SOP：核实「proxy 侧规范化 tools 顺序」措施的实际效果

• 主题目录：tools-norm-verify-20261007/｜核实日期：2026-10-08｜执行人：Agent（用户授权）
• 关联档案：tools-order-20261007/SOP.md（原变更）、wrapup-tools-jitter-20261007/SOP.md（判据两次收紧）
• 实现体：cost_audit/wrapup.py（常量与 docstring 修正，见 §5）

1. 背景

tools-order-20261007 措施（proxy 转发前按 function.name 排序 tools 数组）自 2026-10-07 生效。 用户要求核实其当前实际效果。核实中发现三处口径问题：

#	问题	证据
①	TOOLS_NORM_SINCE 起点与真实生效时刻不符	常量写 2026-10-07 05:55:24；而 proxy.py mtime = 07:32、proxy 进程启动 = 07:35:09（早 1.6 h）
②	判据依赖的 tool_defs 字段历史仅约 26 h	req_shape.jsonl 共 18,394 行，其中 tool_defs 有值仅 1,879 行（自 2026-10-06 22:36 起）
③	SOP §1 的「21 步 / 4.34 元」基线不可复现	用当前 wrapup.py 判据跑全库（since=""）得到 0 步

2. 目标

1. 把 TOOLS_NORM_SINCE 改为 proxy 进程实际启动时刻 2026-10-07 07:35:09；
2. 在 tools-order-20261007/SOP.md §1 补注「21 步」的口径来源与不可复现性；
3. 在 wrapup.tools_order_since() docstring 补方法学注记（同会话内才可比）；
4. 给出措施有效性的确切结论（§6）。

3. 前置条件

• 已备份 cost_audit/wrapup.py 与 tools-order-20261007/SOP.md（见 §7）；
• 只改取数脚本常量与文档，不改 proxy.py、不重启 token-proxy.service；
• 可读到 logs/usage.jsonl 与 logs/req_shape.jsonl。

4. 影响范围

项	内容
主机	本机
组件	cost_audit/wrapup.py（常量 + docstring）、tools-order-20261007/SOP.md（§1 补注）
服务	无 —— 不触碰 token-proxy.service（8788），无需重启
是否停服	否
窗口期	无
影响面	仅收尾自查脚本的统计窗口起点与文档表述；不影响代理转发与计费

5. 分步操作

步骤 1：核对真实生效时刻（先取证，再改常量）

不能凭记忆填常量——本次的错就出在这里。取两项证据，进程启动时刻才是生效时刻。

ps -o pid,lstart,etime,cmd -p "$(pgrep -f proxy.py | head -1)"
stat -c '%y  %n' /home/rain/Documents/services/token_proxy/proxy.py

预期：进程启动时刻 不早于 proxy.py 的 mtime。 失败判断：若进程启动早于 mtime，说明改动后未重启，此时生效时刻应取下一次重启的时刻。

步骤 2：修正常量

编辑 cost_audit/wrapup.py，把 TOOLS_NORM_SINCE 改为步骤 1 得到的启动时刻，并保留原值与修正理由的注释。

grep -n 'TOOLS_NORM_SINCE = ' /home/rain/Documents/services/token_proxy/cost_audit/wrapup.py

预期：TOOLS_NORM_SINCE = "2026-10-07 07:35:09"。

步骤 3：在 tools-order-20261007/SOP.md §1 补复核注记

在 §1 的判据行下方加一个引用块，写明：21 步系原口径、当前工具复现不出、 根因是 tool_defs 字段只有约 26 h 历史；并附方法学（tools_hash 只在同会话内可比）。

grep -n '2026-10-08 复核注记' /home/rain/Documents/services/token_proxy/tools-order-20261007/SOP.md

预期：命中 1 行。

步骤 4：补 tools_order_since() 的 docstring 注记

在 docstring 末尾（Args: 之前）追加「2026-10-08 补（方法学，勿改）」段：跨会话比较会把 「会话切换」误算成「变化」（不分组 301 次 vs 分组 4 次）；且有效窗口受限，勿改成全局顺序扫描。

sed -n '97,130p' /home/rain/Documents/services/token_proxy/cost_audit/wrapup.py

预期：可见「2026-10-08 补（方法学，勿改）」段。

6. 验证

6.1 统计链路未破

cd /home/rain/Documents/services/token_proxy && python3 cost_audit/wrapup.py

预期：正常输出表格与「tools 定义内容变动」一行（2 步：20:30:43、2026-10-08 00:01:23）。

6.2 三种起点均为 0 步（抖动）

cd /home/rain/Documents/services/token_proxy && python3 -c '
import sys; sys.path.insert(0,"cost_audit"); import wrapup
for s in ("", "2026-10-07 05:55:24", "2026-10-07 07:35:09"):
    r = wrapup.tools_order_since(s, "logs/usage.jsonl", "logs/req_shape.jsonl")
    print(repr(s), "→ 顺序抖动", r[0], "步；定义内容变", r[2], "步")
'

预期：三种起点顺序抖动均为 0 步，定义内容变 2 步。

6.3 确切结论（本次核实的结论，写入最终答复）

层次	结论	依据
机制	有效	tools_hash 用 json.dumps(..., sort_keys=True)，只排 dict 键、不排 list → 顺序计入 hash（能识别）；build_shape_fingerprint() 在排序之前跑（记原始序）、normalize_tools_order() 在其后（发上游是稳定序）→ 能消除
实证	方向确认	生效后（07:35:09 起）顺序抖动 0 步；去掉 miss≥5 万 门槛复核，仍为 0 步
实证强度	有限	生效后窗口仅 0.71 天（约 17 h），按生效前 0.85 步/天 推算期望约 0.6 步，实测 0 步 → 方向一致，但不足以排除低频复发
收益规模	不可确证	「生效前 21 步 / 4.34 元」用当前工具复现不出（见 §1 问题③）。引用时勿称"省了 4.34 元"
净判	保留	零成本（一次排序）、零风险（幂等 + 语义等价）、机制闭环；即便收益规模未知，也没有移除的理由

生效后仍存在的其它大 miss（与顺序抖动无关，全部另有归因）：本轮取「同会话内 间隔 ≤300 s 且 miss ≥5 万」共 8 步，逐条归因如下——压缩 3 步（08:31:16 / 22:12:46 / 23:38:37）、工具增删 1 步（08:41:40）、 工具定义内容变 2 步（20:30:43 / 00:01:23）、其余 2 步为中段变化。没有一步是顺序抖动。

7. 回滚

• 备份位置：tools-norm-verify-20261007/backup/，逐条登记见 backup/README.md。
• 回滚步骤：
• 还原常量与 docstring：cp -p backup/cost_audit/wrapup.py.bak.20261008-004242 ../../cost_audit/wrapup.py
• 删除 SOP 注记：还原 cp -p backup/tools-order-20261007/SOP.md.bak.20261008-004242 ../../tools-order-20261007/SOP.md
• 重跑 §6.1 确认脚本可正常执行。
• 回滚后验证：python3 cost_audit/wrapup.py 正常输出即可。
• 无需重启服务（本次未触碰 proxy.py）。

8. 风险说明

风险	缓解
改错常量导致统计窗口偏移	常量只影响 >= since 过滤；§6.2 三种起点对照可立即发现偏移
误以为「大 miss 步数下降 = 措施生效」	已写入 §6.3：生效后 11.2 步/天 vs 生效前 2.4 步/天，该对比受任务量与上下文规模影响，不构成措施的反证；判生效只能看分类结果（顺序抖动是否为 0）
后续再为其它改动重启 proxy，忘记更新常量	常量注释已写明「取进程实际启动时刻，勿凭记忆填」

---

来源：/home/rain/Documents/services/token_proxy/tools-norm-verify-20261007/SOP.md ｜ 最后更新：2026-10-08 00:43（由 build/sync.py 同步，请勿在站点侧修改）