跳转至

SOP：会话步序列画像工具（step_profile.py）

  • 日期：2026-10-02
  • 类型：C 类变更（交付物变更：新增只读分析工具）
  • 交付物目录：step-profile-20261002/

1. 背景

「优化点总账」中，多个挂账项的共性缺口是：只有任务级汇总，没有步骤级明细—— 现有 selfcheck.py / daily_review.py 能回答「这个任务贵不贵」，答不了「这几百步里哪几步可以合并」。 上上轮讨论据此提出「缺工具维度」。

核查后发现：数据其实已在。logs/req_shape.jsonl（2026-09-16 起持续累积）逐步记录了 conv / turn / hit / miss / out / status 与 shape{msgs, tools, tools_hash, head, tail}， 其中 tail 给出本步末尾消息的指纹 角色:字节数:哈希。缺的只是一段分析脚本。

2. 目标（可验证）

  1. 一条命令列出步数最多的会话及其浪费画像（重复读 / 大输出 / 长空档 / 疑似可合并组）；
  2. 一条命令输出指定会话的逐步明细（默认只打印标记步，避免刷屏）；
  3. 支撑「可合并项占比」是否值得优化的判断，并给出该判断的证据强度。

3. 前置条件

  • 数据源 logs/req_shape.jsonl 存在且可读（只读，不写）；
  • Python 3.8+，仅用标准库（无第三方依赖）；
  • 工程根由 Path(__file__) 推导，无需配置。

4. 影响范围

  • 仅新增一个只读分析脚本；不改配置、不改代理、不重启任何服务，无停机窗口；
  • 输出仅为 stdout，不落盘任何文件。

5. 分步操作

步骤 1：新增脚本 cost_audit/step_profile.py

与既有 cost_audit/selfcheck.py 并列，复用同一套口径（成本 = 命中×0.02e-6 + 未命中×1.0e-6 + 输出×4.0e-6）。 位置例外说明：全局规则要求新文件进交付物子目录，但工具本体须与 selfcheck.py 同址， 否则「命令 + 路径」的跨会话引用约定会失效；故本体入 cost_audit/，变更档案入 step-profile-20261002/。

坑：argparse 的 default= 在解析前求值，若把 global 声明写在 add_argument 之后会触发 SyntaxError: name is used prior to global declaration——global 必须置于函数首行。

# 幂等：文件已存在则先比对再决定是否覆盖（本步为新增，重复执行应检出「已存在」）
test -f cost_audit/step_profile.py && echo "已存在，跳过" || echo "待新增"

预期：首次输出「待新增」；重跑输出「已存在，跳过」（幂等判据）。 失败判断：文件创建后 python3 -c "import ast,sys; ast.parse(open('cost_audit/step_profile.py').read())" 报语法错 → 回到本节排查。

步骤 2：口令速查（三条命令）

python3 cost_audit/step_profile.py --top 10                       # 会话步数排名
python3 cost_audit/step_profile.py --conv <会话ID前缀>            # 逐步明细（默认只打标记步）
python3 cost_audit/step_profile.py --top 30 --small 500            # 调整碎步阈值做敏感性检查

预期：排名末尾给出「单轮步数分布」；明细末尾给出「疑似可合并组」统计与弱信号提示。 失败判断：报「无数据」→ 检查 logs/req_shape.jsonl 是否存在；报「未找到会话」→ 会话 ID 前缀有误。

6. 验证

项 命令 预期
语法与可运行 python3 cost_audit/step_profile.py --top 3 正常输出表与分布行，退出码 0
单会话明细 python3 cost_audit/step_profile.py --conv bb963879 输出标记步 + 汇总 + 弱信号提示
阈值可调 --small 500 / 1000 / 2000 三档 「疑似可并组/步」随阈值单调变化
只读性 运行前后 md5sum logs/req_shape.jsonl 不变

实测结论（2026-10-02，全库 156 会话 / 11,644 步 / 664 轮）

判据 结果 可信度
重复读（哈希重复） 2 次 / 11,644 步 = 0.02% 确定——不是主要浪费
步数集中度 62 个轮（9.3%）占 5,006 步 = 43% 确定——步数高度集中在长轮
疑似可合并组（top30） 阈值 500B → 2.2%｜1000B → 17.5%｜2000B → 57.6% 不可用——跨 26 倍，说明字节数不是可靠代理

7. 回滚

对象 备份位置 回滚命令
cost_audit/step_profile.py 新增文件，无备份 rm cost_audit/step_profile.py

备份台账见 backup/README.md。本变更为纯新增、只读，回滚即删除，无残留状态。

8. 风险说明

风险 缓解
「疑似可合并组」被误当成结论使用 脚本与文档均标注为弱信号；阈值敏感性已实测（26 倍差），明确禁止据其单独下优化结论
误读「大输出步 = 浪费」 输出含思考 token（实测占 62%），脚本只标记数值，不判定浪费
会话 ID 前缀撞车 命中多个会话时全部打印，不静默择一
数据源缺失导致误判「无浪费」 无数据时显式报错退出 1，不输出空表

附录：交付物清单

  • cost_audit/step_profile.py（本工具，常驻工程目录）
  • step-profile-20261002/SOP.md（本文件）
  • step-profile-20261002/backup/README.md（备份台账）
  • 待办去向上游：~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md（挂账：给 req_shape 补工具名）

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