martin1847/evolab / skills/agent-backend-standard
agent-backend-standard
Verified后端架构与工程规范。适用于构建或评审 agent/LLM 后端、任何涉及数据库(DB)的后端,以及建立或评审后端仓库工程门禁。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.5 KB |
| references/agent-foundations.md | markdown | 2.3 KB |
| references/caching-discipline.md | markdown | 3.9 KB |
| references/code-dependency-lifecycle.md | markdown | 9.5 KB |
| references/data-write-discipline.md | markdown | 9.9 KB |
| references/engineering-interface.md | markdown | 10.9 KB |
| references/evals.md | markdown | 2.6 KB |
| references/governance.md | markdown | 2.7 KB |
| references/hitl-resume-safety.md | markdown | 2.7 KB |
| references/observability-cost.md | markdown | 1.2 KB |
| references/prompt-context.md | markdown | 1.6 KB |
| references/resilience.md | markdown | 3.9 KB |
| references/safety-bounded-execution.md | markdown | 4.5 KB |
| references/secrets-discipline.md | markdown | 2.5 KB |
| references/selfcheck-gates.md | markdown | 4.4 KB |
| references/state-durability.md | markdown | 2.6 KB |
| references/tool-design.md | markdown | 2.8 KB |
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(等真实素材,零投机)。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |