RUNBOOK：token-proxy 缓存探测（cache_probe）¶
本手册只覆盖
cache_probe这一个功能；代理整体的启动/路由/计费见docs/BASELINE.md（命令速查 §3）与docs/HANDOFF.md。
1. 它是什么 / 异常时的业务影响¶
会话空闲 ≥1 h 后，代理先发一个「复用该会话前缀的前 50 K token」的极小请求，
读回 cached_tokens 算命中占比：
- 命中 ≥90% → 缓存还在，正常转发（零感知）；
- 命中 <90% → 缓存已失效，返回 500 拒绝本次请求，提示「请先压缩上下文再继续」。
异常时的影响：仅在「空闲 ≥1 h 后的第一次请求」上生效。若本功能整体故障， 表现为探测失败 → 自动放行（业务不受影响），代价是退化为「按时间猜」的旧状态。
2. 日常速查表¶
# 1) 看当前生效参数（启动日志最后一行）
journalctl --user -u token-proxy -n 30 --no-pager | grep '代理启动'
# 2) 看最近的探测判定
journalctl --user -u token-proxy --since '1 hour ago' --no-pager | grep '缓存探测'
# 3) 看最近的拒绝
journalctl --user -u token-proxy --since '1 hour ago' --no-pager | grep '拒绝请求'
# 4) 探测花了多少钱（单独一行、conv_key=null）
grep '"probe": true' /home/rain/Documents/services/token_proxy/logs/usage.jsonl | tail -20
# 5) 一键关闭（改 enabled: false 后重启，最常用）
cd /home/rain/Documents/services/token_proxy
sed -i 's/^ enabled: true/ enabled: false/' config.yaml && systemctl --user restart token-proxy
# 6) 恢复开启
sed -i 's/^ enabled: false/ enabled: true/' config.yaml && systemctl --user restart token-proxy
注：第 5/6 条的
sed只改cache_probe段内的enabled行；改完务必grep -n -A3 '^cache_probe:' config.yaml复核。
3. 配置项¶
| 项 | 默认 | 含义 | 调整建议 |
|---|---|---|---|
enabled |
true |
总开关 | 误拦过多时先置 false 观察 |
idle_seconds |
3600 |
距上次请求超过该秒数才探测 | 想更早介入可降到 1800；0 = 每次请求都探测，仅调试 |
probe_tokens |
50000 |
探测前缀长度（token） | 失效时残留命中实测 ≤25.2 K，50 K 留了一倍余量；调小会增加误判风险 |
hit_ratio |
0.90 |
命中占比低于该值判失效 | 阈值区间 (0,1]；调低=更宽松（更少拦截），调高=更严格 |
timeout |
15 |
探测请求超时（秒） | 超时即放行，宁可漏拦不可阻塞 |
max_convs |
64 |
会话快照 LRU 上限 | 并发会话多时上调 |
改完必须重启：systemctl --user restart token-proxy（会打断在途回答）。
4. 观测¶
| 看什么 | 命令 | 正常表现 |
|---|---|---|
| 启动参数 | 速查表 1 | 末段含 缓存探测=开启(空闲>=3600s, 探前 50000 tok, 命中<90% 拦截, 超时 15s) |
| 探测判定 | 速查表 2 | 缓存探测 conv=… 空闲=…s 命中=…/… (…%) 阈值=90% |
| 拒绝 | 速查表 3 | 拒绝请求：前缀缓存已失效 空闲=…min 命中=…/… |
| 探测开销 | 速查表 4 | 命中时 cache_hit_tokens≈prompt_tokens；失效时 cache_miss_tokens 占多数 |
5. 故障处置¶
场景 A：被拒绝后不知道怎么办¶
症状：客户端报 500，提示 前缀缓存已失效。
诊断：journalctl --user -u token-proxy --since '5 min ago' | grep '缓存探测'
看命中占比是否真的 <90%。
处置：在 Trae 里点「压缩」，然后回一句「继续」即可续跑。
验证：grep -c '"probe": true' logs/usage.jsonl 计数继续增长，且新的业务请求 miss 明显下降。
场景 B：怀疑误拦（缓存其实还在）¶
症状：空闲时间不长却被拦。
诊断：查日志里的 空闲= 值——若明显小于 idle_seconds，说明是快照时间被误刷新；
若 空闲 正常但 命中 很低，说明缓存确实失效。
处置：先 enabled: false 重启止血；再把 hit_ratio 调低（如 0.7）观察。
若「空闲」确实偏小，属代码缺陷，按 cache-probe-20261008/SOP.md §7 回滚。
验证：改完重启，日志中不再出现该会话的拒绝。
场景 C：探测变慢、拖累首次请求¶
症状：空闲后第一次请求明显变慢。
诊断：journalctl --user -u token-proxy --since '10 min ago' | grep -E '缓存探测|上游请求失败'
处置：把 timeout 降到 5；仍慢则 enabled: false。
验证：首次请求耗时回到正常区间。
场景 D：想彻底关掉¶
处置：sed -i 's/^ enabled: true/ enabled: false/' config.yaml && systemctl --user restart token-proxy
验证：启动日志显示 缓存探测=关闭；logs/usage.jsonl 不再新增 "probe": true。
6. 回滚¶
- 只关开关（推荐，秒级）：见场景 D。
- 回滚代码：
cache-probe-20261008/SOP.md§7（含备份路径与命令）。 - 备份台账：
cache-probe-20261008/backup/README.md。
来源：
/home/rain/Documents/services/token_proxy/cache-probe-20261008/RUNBOOK.md｜ 最后更新：2026-10-08 00:55（由build/sync.py同步，请勿在站点侧修改）