跳转至

SOP — 给收尾自查补「执行阶段详情」（selfcheck-detail-20261002）

触发：用户反馈收尾自查三处退化——① 时间分布（墙钟 / 步间隔）不见了； ② 未命中只报百分比、无解释；③ 输出只有百分比、看不出思考占多少。且上一轮任务里 部分复盘内容要额外追问一轮才补出。用户明确「宁愿多付成本，也要知道执行阶段详情」。

1. 背景

用户在查看上一轮任务的收尾自查时发现呈现退化，并追问后才发现完整复盘。核查后确认三条根因：

  1. 时间分布：cost_audit/selfcheck.py 自 2026-10-01 起已在输出「墙钟 / 平均步间隔 / 最大步间隔」， 但全局规则 rule-agent-efficiency.md B 组没要求写，导致数据有、答复里丢了。
  2. 未命中 / 输出：规则 B 组只写「四段占比」与「输出 TOP3」，未命中与输出都只有一个百分比； selfcheck.py 未读 reasoning_tokens，也没有「未命中失效步」输出（daily_review.py 早有该口径）。
  3. 追问才补齐的复盘：图片2 那张「功能哪些真用上 / 哪些没用好」的表属行为自评， 四组覆盖不到——D 组只报机器指标数字，不报「该用没用 / 用得不到位」，故只能靠追问。

2. 目标

变更完成后应达到的可验证状态：

  • selfcheck.py 在原有输出之外，增两行： 「输出构成：输出 N tok ｜ 其中思考 M tok（占输出 P%）｜ 正文 K tok」与「未命中 TOP3：…（标出轮首条）」。
  • 全局规则 B 组由 4 项扩为 6 项：并入「时间分布」「未命中归因」「输出构成」。
  • 全局规则新增 E 组「效率手段对照」：固定 8 条清单逐条判定，含漏用说明 / 机器对账 / 指标回填； 硬门禁由「四组」升为「五组」，E 组缺失即任务未完成。
  • skill ops-execution-efficiency 同步（§6.2 输出项 + 收尾清单两项 + 「五组」措辞）。

3. 前置条件

  • 主机 192.168.31.250，工程根 ~/Documents/services/token_proxy，python3 可用（仅标准库）。
  • 数据源 logs/usage.jsonl 可读（不可再生数据，全程只读）。
  • 无需 sudo、无需停服、无需重启代理。
  • 已知：logs/usage.jsonl 写入有滞后，取数样本须标注窗口起止时刻（同族挂账 #18）。

4. 影响范围

项 内容
涉及主机 单机（192.168.31.250）
涉及组件 cost_audit/selfcheck.py（只读分析工具）；全局规则 ~/.trae-cn/user_rules/rule-agent-efficiency.md；skill ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md
是否停服 否。不触碰 proxy.py / config.yaml / systemd 服务
窗口期 无窗口要求，随时可执行
在跑业务 代理三条路由 ds / glm / mi 不受影响
影响面 仅影响"收尾自查的取数与呈现"；不改变任何采集、记账与代理行为

代价提示（重要）：改全局规则会让每轮 system prompt 前缀分叉，同会话继续会在下一次请求触发前缀重建（约 0.35 元/次）。改完应开新会话继续。

5. 分步操作

步骤 1：备份改动前的脚本

改动前留底，满足"失败能回原点"。备份放本主题 backup/（台账见 backup/README.md）。

cd ~/Documents/services/token_proxy
TS=$(date +%Y%m%d-%H%M%S)
mkdir -p selfcheck-detail-20261002/backup/cost_audit
cp cost_audit/selfcheck.py "selfcheck-detail-20261002/backup/cost_audit/selfcheck.py.bak.$TS"
cp ~/.trae-cn/user_rules/rule-agent-efficiency.md "$HOME/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.$TS"
chmod 600 "$HOME/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.$TS"
ls -l selfcheck-detail-20261002/backup/cost_audit/ ~/.trae-cn/user_rules/backup/

预期：selfcheck.py.bak.20261002-212225（6091 字节）与 rule-agent-efficiency.md.bak.20261002-212225（10068 字节）存在。 失败判断：路径或权限错误 → 停止，不进行后续编辑。

步骤 2：selfcheck.py 增「输出构成」与「未命中 TOP3」

坑：usage.jsonl 顶层没有 reasoning 字段，思考 token 在 usage.completion_tokens_details.reasoning_tokens， 取值须走嵌套结构并容错（(r.get("usage") or {}).get("completion_tokens_details") or {}）， 否则对旧记录或异常结构会抛 AttributeError——扫描 11k+ 条记录时不容错必崩。

在 _report() 里、print(" 输出 TOP3 …") 之后插入两处（用 SearchReplace 增量编辑，不整篇重写）：

  • 计算 reason（累加 reasoning_tokens）与 miss_top（按 cache_miss_tokens 取前三）、first_ts；
  • 打印「输出构成：…（思考 M tok，占输出 P%）」与「未命中 TOP3：…（轮首条标注）」。

判读口径（写进答复时用）：轮首条 miss 属正常（新输入本就不命中）， 中段大 miss 才是"前缀被改写"的信号（大文件整篇重写 / 规则改动 / 整页抓取后重放）。

核对：

cd ~/Documents/services/token_proxy
python3 -c "import ast;ast.parse(open('cost_audit/selfcheck.py').read());print('syntax OK')"
python3 cost_audit/selfcheck.py --last 1

预期：语法通过；输出含「输出构成」与「未命中 TOP3」两行。

步骤 3：全局规则 B 组扩为六项

文件 ~/.trae-cn/user_rules/rule-agent-efficiency.md（项目外，进每轮前缀）。三处定点编辑：

  1. B 组表格：「四段占比」行改为「四段占比 + 未命中归因」，新增「时间分布」与「输出构成」两行；
  2. 开头「按下面四组」改为「按下面五组」；结尾硬门禁「（D 组可按…）」改为「（D / E 组可按…）」；
  3. 修订说明追加「2026-10-02 六修」。

坑：该文件是全局规则，改动进每轮 system prompt——只做定点替换，不得整篇重写（重写会污染前缀且难以核对）。

步骤 4：全局规则新增 E 组「效率手段对照」

在 D 组「无相关动作时写一行『无』」之后、取数命令之前插入 E 组（固定 8 条清单 + 漏用说明 + 机器对账 + 指标回填）， 并把取数说明补为"2026-10-02 起增输出构成与未命中 TOP3，B 组与 E 组共用这一条"。

核对：

grep -n "^**E. 效率手段对照\|^**D. 工具与子智能体\|按下面五组\|D / E 组" \
  ~/.trae-cn/user_rules/rule-agent-efficiency.md

预期：五组措辞与 D / E 组标题各命中一处。

步骤 5：skill ops-execution-efficiency 同步

文件 ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md（skill 正文，不进每轮前缀，改后无需开新会话）。三处：

  1. §6.2 末「该脚本 2026-10-01 起同时输出…」补为含输出构成 / 未命中 TOP3；
  2. 收尾清单「成本已量化」项补时间分布 / 输出构成 / 未命中 TOP3；新增「效率手段对照（E 组）」一项；
  3. 「效率 / 成本 / 积累 / 工具与子智能体四组」改为「…/ 效率手段对照五组」，「已回填」项补 E 组回填。

步骤 6：更新 docs/HANDOFF.md

按 writing-handoff 的增量判据执行：本轮为状态推进 + 新产物，定点修订相关节，不整体重写。

6. 验证

自检脚本语法并实跑（数据源为真实 logs/usage.jsonl，只读）：

cd ~/Documents/services/token_proxy
python3 -c "import ast;ast.parse(open('cost_audit/selfcheck.py').read());print('syntax OK')"
echo "== [1] 最近一轮 =="
python3 cost_audit/selfcheck.py --last 1
echo "== [2] 指定整任务窗口（上一轮 C 类变更） =="
python3 cost_audit/selfcheck.py --since "2026-10-02 20:40:00" --until "2026-10-02 21:05:00"
grep -c "^**E. 效率手段对照" ~/.trae-cn/user_rules/rule-agent-efficiency.md

实测结果：

# 项 结果 判定
1 语法检查 syntax OK ✅
2 最近一轮 新增「输出构成：输出 14636 tok｜思考 10705（占输出 73%）｜正文 3931」与「未命中 TOP3」（含轮首条标注） ✅ 两行均有数据
3 指定窗口 62 步 / ≈0.7075 元 / 思考占输出 62% / 未命中 TOP3 首位 46043 tok（中段） ✅ 口径可用
4 规则结构 ^**E. 效率手段对照 命中 1 处 ✅

附注：窗口 20:40→21:05 的 62 步 / 0.7075 元，比上一轮那次收尾自查所报的 49 步 / 0.5437 元更多—— 印证挂账 #29「收尾取数须在最后一次工具调用之后」。本 SOP 的样本口径以整任务窗口为准。

7. 回滚

  • 备份位置：selfcheck-detail-20261002/backup/cost_audit/selfcheck.py.bak.20261002-212225； 规则备份 ~/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.20261002-212225（详见各自 README.md）。
  • 回滚触发条件（任一即回滚，不临场判断）：
  • 第 6 章验证任一项不符预期（脚本报错 / 新增行无数据 / 规则结构缺失）；
  • 新输出导致 --last 1 等既有调用报异常或输出乱码。
  • 回滚步骤：
cd ~/Documents/services/token_proxy
cp selfcheck-detail-20261002/backup/cost_audit/selfcheck.py.bak.20261002-212225 cost_audit/selfcheck.py
cp ~/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.20261002-212225 \
   ~/.trae-cn/user_rules/rule-agent-efficiency.md
python3 cost_audit/selfcheck.py --last 1   # 预期回到仅「墙钟 / 步间隔 / 输出 TOP3」
  • skill 回滚：按本 SOP 第 5 章三处反向定点恢复（skill 正文无 .bak）。

8. 风险说明

风险 等级 缓解
改全局规则触发前缀重建（约 0.35 元/次） 中 收尾后开新会话继续；不在旧会话反复累积
E 组使每轮收尾输出变长 低 用户明确接受（"宁愿多付出成本"）；固定 8 条，只多一小节
reasoning_tokens 取值对旧记录不存在 低 嵌套取值 + or {} 容错；缺字段按 0 计
规则文本过长拖慢每轮加载 低 E 组用表 + 一段说明；总计新增约 20 行
机器对账与自评不符 中 规则明写"自评不得与机器数字矛盾"，矛盾即改口径
文档与代码漂移 低 本 SOP 第 5 章与实现体同源；skill 同步更新

附录：交付物清单

交付物 路径
本 SOP selfcheck-detail-20261002/SOP.md
备份台账 selfcheck-detail-20261002/backup/README.md
脚本备份 selfcheck-detail-20261002/backup/cost_audit/selfcheck.py.bak.20261002-212225
规则备份 ~/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.20261002-212225
变更的实现体 cost_audit/selfcheck.py
变更的全局规则 ~/.trae-cn/user_rules/rule-agent-efficiency.md（B 组六项 + E 组 + 五组）
变更的 skill ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md
过账 ~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md
样本回填 ~/.trae-cn/skills/ops-execution-efficiency/references/measured-baselines.md
交接 docs/HANDOFF.md

来源：/home/rain/Documents/services/token_proxy/selfcheck-detail-20261002/SOP.md ｜ 最后更新：2026-10-02 21:24（由 build/sync.py 同步，请勿在站点侧修改）