跳转至

SOP：可并组识别口径扩为全覆盖（merge-coverage-20261006）

主题：把「能合并的步骤」的识别从「碎步组」扩为全覆盖口径 对象：cost_audit/step_profile.py（主）、~/.trae-cn/user_rules/rule-agent-efficiency.md（口径同步） 执行时间：2026-10-06

1. 背景

现行「疑似可并组」口径写死在 cost_audit/step_profile.py：连续 ≥3 步、且每步末尾 tool 消息 < 2000 字节。

2026-10-06 复核（窗口 2026-10-02 起，101 会话 / 5378 步）实测该口径的三处缺口：

缺口 实测
只认「连续 ≥3 步」 漏掉 2 步组 179 组 / 358 步
只认「末尾 < 2000 字节」 把「末尾结果大」的步骤整段排除——而那恰恰是最该合并的一类
合计覆盖 旧口径覆盖 1985 步，而「连续工具步」共 3953 步 —— 仅约一半

用户要求：覆盖度越高越好。

2. 目标

  • 识别口径不设大小门槛、不设高步数门槛，把可合并的步骤全部纳入统计；
  • 能直接回答「还有多少步本可合并」与「已经合并了多少」；
  • 旧口径保留，跨轮样本可比性不破。

可验证判据：全窗口「未合并块」组数 / 步数 ≥ 旧口径；已合并率可直接读出；旧「碎步组」数字与改造前一致（355 组 / 1985 步）。

3. 前置条件

  • python3（脚本仅用标准库）；
  • logs/req_shape.jsonl 可读、未损坏（不可再生，绝不可删）；
  • tool_names 覆盖窗口为 2026-10-02 起（此前记录无该字段，类别落「其他」属正常）。

4. 影响范围

  • 主机：本机（192.168.31.250），无远端；
  • 组件：只读分析脚本 cost_audit/step_profile.py、全局规则文本；
  • 是否停服：否；代理 8788 与 Hook 链路均不受影响；
  • 窗口期：无；无在跑作业约束；
  • 副作用：全局规则进每轮前缀，改动后须开新会话生效（否则旧会话继续每轮多付约 0.35 元）。

5. 分步操作

步骤 1：备份

TS=$(date +%Y%m%d-%H%M%S)
mkdir -p merge-coverage-20261006/backup/cost_audit ~/.trae-cn/user_rules/backup
cp cost_audit/step_profile.py "merge-coverage-20261006/backup/cost_audit/step_profile.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 merge-coverage-20261006/backup/cost_audit/*.bak.* ~/.trae-cn/user_rules/backup/*.bak.$TS

预期：生成两个权限 600 的 .bak.<时间戳>。失败判断：源文件不存在 → 停下核对路径，不得跳过备份继续。

步骤 2：改 step_profile.py（新增主口径）

六处改动，全部为增量、旧函数与旧字段保留：

  1. 常量区新增 UNMERGED_MIN = 2；
  2. 新增函数 unmerged_blocks(detail, min_len=None)：识别连续单工具步（len(tool_names)==1 且末尾为 tool 结果）≥2 的块，按 KINDS 分列，并统计「已合并步数 / 有工具名步数」；
  3. analyze() 增返回 ublocks / ublock_steps / ublock_kind / merged_steps / tn_steps；
  4. print_rank() 表加「未合并块(主)」「已合并%」两列，合计行与分列行同时给两种口径；
  5. print_conv() 明细加主口径块与已合并率；
  6. main() 增 --umin（默认 2），并同步 global 声明。

坑：unmerged_blocks 若写成 def f(min_len=UNMERGED_MIN)，默认值在定义时绑定，--umin 覆盖全局后不生效；故签名用 min_len=None，函数内再读全局。

实现体：cost_audit/step_profile.py（本次以增量编辑完成，未整篇重写）。

步骤 3：改全局规则（口径同步）

~/.trae-cn/user_rules/rule-agent-efficiency.md 四处：

  1. 「执行方式」表新增「跨轮 / 等待期 / 单命令内批处理」行；
  2. D 组「工具调用」行：主口径改为「未合并块 + 已合并率」，旧碎步组降为跨轮可比项；
  3. 「无异常判据」D 行、D 组「指标回填」行同步；
  4. 文末追加「九修」说明。

步骤 4：验证

python3 cost_audit/step_profile.py --date 2026-10-06 --top 5
python3 cost_audit/step_profile.py --umin 3 --date 2026-10-06 --top 3

预期：表含「未合并块(主)」「已合并%」两列；合计行给出旧口径与新口径两组数字与分列。 失败判断：报 KeyError / 表头缺失 → 按第 7 章回滚后重做。

6. 验证

  • 数字对账：全窗口（2026-10-02 起）「未合并块」= 436 组 / 2321 步、已合并率 33.7%（1469 / 4364），与改造前一次性统计（435 组 / 2319 步 / 33.6%）一致（±数步系统计期间本会话持续写入新记录）；
  • 旧口径不变：碎步组仍为 355 组 / 1985 步量级；
  • 边界可调：--umin 3 时组数下降（只算 ≥3 步块）；
  • 无 lint 错误：编辑器诊断为空。

7. 回滚

  • 备份位置：merge-coverage-20261006/backup/（项目脚本）与 ~/.trae-cn/user_rules/backup/（全局规则），台账见 merge-coverage-20261006/backup/README.md；
cp merge-coverage-20261006/backup/cost_audit/step_profile.py.bak.20261006-225624 cost_audit/step_profile.py
cp ~/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.20261006-225624 ~/.trae-cn/user_rules/rule-agent-efficiency.md

回滚后验证：python3 cost_audit/step_profile.py --top 3 表头应恢复为旧的单一口径（无「未合并块(主)」列）；全局规则回滚后同样须开新会话生效。

8. 风险说明

风险 缓解
全局规则改动使每轮前缀失效（≈0.35 元/次） 已知代价；收尾即提醒开新会话
新口径数字与旧口径不可比，跨轮样本断裂 旧「碎步组」口径保留并同表输出
「未合并块」被误读为「必须合并」 脚本提示与规则均写明：只归类、不判依赖，有依赖的必须串行
tool_names 覆盖不足的旧窗口类别落「其他」 脚本既有说明，本次不变

附录：交付物清单

文件 说明
cost_audit/step_profile.py 改造后的脚本（主口径：未合并块 + 已合并率）
~/.trae-cn/user_rules/rule-agent-efficiency.md 口径同步（九修）
merge-coverage-20261006/SOP.md 本文件
merge-coverage-20261006/backup/README.md 备份台账

RUNBOOK 判定：本次是既有脚本的口径增强，使用方式（一条命令）与参数均向后兼容，未产生需照做的新运维流程 → 不出独立 RUNBOOK。

来源：/home/rain/Documents/services/token_proxy/merge-coverage-20261006/SOP.md ｜ 最后更新：2026-10-06 22:59（由 build/sync.py 同步，请勿在站点侧修改）