Skip to content

martin1847/evolab / skills/agent-backend-standard

agent-backend-standard

Verified

后端架构与工程规范。适用于构建或评审 agent/LLM 后端、任何涉及数据库(DB)的后端,以及建立或评审后端仓库工程门禁。

references/caching-discipline.md

View on GitHub
# 附录 D — 缓存纪律(准入 · 永不缓存 · 失效治理)<!-- trunk:caching-discipline.md -->

> hub `agent-backend-standard` 的一章。来源:某伞仓缓存立法(双路调研合成:经典方法论 + agent 时代
> 架构)+ 公开事故复盘。**范围**:通用持久层后端——何时允许缓存、什么永不缓存、失效如何治理;
> agent 时代增量是 §3 失效治理三件套(LLM 高频产写路径,失效逻辑最容易没人接)。

## 0. 本质

**缓存只是加速层:写路径同变更声明失效,失效键一律登记在册,禁自由发明缓存。**
任何缓存必有 TTL 兜底——失效逻辑漏接时系统自愈,而不是永久陈旧。

## 1. 四轴准入(任一不过即不缓存)

1. **读写比 > 10:1**?低于此,失效开销 > 收益。
2. **陈旧可容忍**?红线:**陈旧值会让用户做出有真实后果的错误动作 → 不缓存**。
3. **所有权是共享**?per-user 数据(关注/收藏/钱包)默认不进共享缓存。
4. **DB 实测不够快**?先索引/连接池调优(调优后主键/索引读常 <5ms),再谈缓存。

## 2. 永不缓存区(fail-closed)

- **金钱**:余额 / 支付态 / 退款态 / 金额——直穿 DB。
- **占位型"库存"**:可约时段 / 席位 / 配额——陈旧即超卖。
- **鉴权响应**:不进任何共享/边缘缓存,HTTP 响应显式 `Cache-Control: private`。
- **per-user 数据**确要缓存时,键强制 userId 命名空间(公开事故为据:共享缓存串号把
  A 用户数据回给 B,如 Klarna 2022)。

## 3. 失效治理三件套(agent 时代头号事故模式)

业界多源一致的头号缓存事故:**"新写路径没人接失效逻辑"**——LLM 车次高频新增写路径,
恰是高发区。对策全部结构化、不靠记忆:

1. **缓存决策表 = SoT**:每行 `key 模式 | 层 | TTL | 失效方式 | 关联写路径`;
   未登记的缓存 = 违规。
2. **失效点唯一可枚举**:声明式注解(@CacheEvict 类)+ 缓存名收敛进专用 enum,
   禁散落裸字符串 / 裸 `cache.del`(可 grep 可枚举是机检前提)。
3. **机检门**:架构测试规则(按语言:ArchUnit / NetArchTest / import-linter /
   dependency-cruiser)——写方法命中决策表已登记的域,必须存在配对失效声明;进
   repo-owned `check` 门(接口见附录 C)。静态门管不到的跨时序 race / orphan
   invalidation,上分布式层时用运行期对账指标兜。

项目 AGENTS.md guardrail 三句模板:新增缓存必须登记决策表;失效走注册 enum 单一入口;
新写路径必须声明关联失效键,不确定即 stop-and-report。

## 4. 引入路线(由外向内,实测热点倒逼)

`DB 调优 →(单副本期)进程内缓存 →(多副本漂移实测成问题)分布式缓存 →(公网读峰)CDN/边缘`。
**升级触发即立 ADR,不静默升级**;触发条件第一天写死在决策表头(本地缓存跨副本漂移实测
成问题 / 出现跨实例共享需求如分布式限流)。**三防(负缓存 + TTL jitter + singleflight)
随第一个缓存点同车进,不事后补。** 铺垫三件让升级是"换实现"而非"改架构":
- 缓存访问走自有薄封装,业务代码不直接 import 缓存库;
- 决策表自带"层"字段;
- 命中率 / 加载时长埋点随第一个缓存点进(升级决策靠数据不靠感觉)。

## 5. 模式两则

- **stale-while-revalidate**:`refreshAfterWrite(N)` + `expireAfterWrite(N+Δ)`——到期先回
  旧值异步刷新,强制过期兜底。
- **公钥 / JWKS 类**:无限期缓存 + **触发式换代**(遇未知 key id → 重新加载、成功后整体
  替换)+ 最小刷新间隔(如 60s)防恶意 key id 打穿回源。

## 语言注

- **Java / GraalVM native**:Caffeine 内部代码生成实现类须显式反射注册,且**类名随
  builder 特性组合变化**——JVM 全绿、native 运行期才 ClassNotFound;native 冒烟必须
  真调一次缓存路径,负探针按最终 builder 配置核对内部类名。
- Python / Go / Rust:TBD(等真实素材,零投机)。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall