缓存
缓存重复上下文，而不是冻结用户现实
缓存的目标是减少重复读取，而不是长期锁死用户模型。最安全的起点，是显式记录响应形态并结合 ETag 做条件读取。
Format: AI-first docs
Source: DocsAgentsCachingPage
提示
用缓存减少重复，不要用缓存掩盖重要变化。
好的缓存既保留重复读取效率，也保留对事件性变化的敏感度。
缓存层次
从响应形态、新鲜度和失效证据三个角度思考。
条件读取
基于 ETag 的重验证，是最安全的第一层优化。
- 把 ETag 和 view / expand 参数一起存下来。
- 对相同读取使用 `If-None-Match` 回传。
- 把 `304` 当成健康优化路径。
形态意识
明确知道你缓存的是哪一种响应形态。
- 记录它是 compact、full 还是 expanded。
- 把 shaping 参数放进 cache key。
- 默认优先缓存紧凑 context。
失效机制
当工作流证据表明用户模型已变化时，主动丢弃或重验证缓存。
- 简历上传和测评完成都是自然失效点。
- webhook 事件可以触发重新验证。
- 不要跨无关流程复用同一个缓存 payload。
先用 ETag，不要先发明自定义缓存系统
`/api/v1/context` 已经对适合缓存的响应提供条件请求能力，所以原生重验证通常是最干净的第一步。
- 把最新 ETag 和缓存 payload 一起保存。
- 只对完全相同的请求形态使用它。
- 把 cache miss 和 revalidation 当成正常 runtime 行为。
让缓存决策始终绑定工作流证据
当 runtime 观察到足以影响推理质量的产品事件时，就应该主动失效缓存。
- 对动态或波动较大的读取使用更短的新鲜度窗口。
- 在 profile 编辑、resume 解析、assessment 完成后重新拉取。
- 不要保留 runtime 自己也解释不清的长生命周期缓存。
缓存对比
并不是每一种响应形态都值得同样的缓存策略。
| 形态 | 默认策略 | 原因 |
|---|---|---|
| 紧凑 context | 最适合做条件缓存的默认值。 | 信号密度高，而且相对稳定。 |
| 展开的 dynamic context | 使用更短窗口，或直接拉新。 | 近期事件和相关性变化很快。 |
| health / alert 型读取 | 更积极地重验证或直接 fresh fetch。 | 运行信号很容易过时。 |
决策矩阵
根据工作流形态选择缓存动作。
情况
同一个紧凑读取反复发生
动作
保存 ETag，并进行条件重验证。
原因
它能先降低重复传输，而不必立刻设计复杂策略。
情况
任务高度依赖近期事件
动作
使用更短缓存窗口，或直接拉取新鲜状态。
原因
dynamic context 很容易漂移。
情况
webhook 或产品事件改变了用户模型
动作
失效缓存并重新拉取。
原因
后续推理不该建立在陈旧身份信号上。
条件请求示例
对重复 context 访问来说，基于 ETag 的读取是最安全的第一层优化。
首次读取
1
curl "https://api.profileclaw.com/api/v1/context" -H "Authorization: Bearer $PROFILECLAW_API_KEY"重验证读取
1
curl "https://api.profileclaw.com/api/v1/context" -H "Authorization: Bearer $PROFILECLAW_API_KEY" -H 'If-None-Match: "<etag-from-previous-response>"'下一步
缓存稳定后，还要继续收紧重试和异步续跑行为。