Trae Token 计量代理 + 成本报表 部署 SOP

主机：Ubuntu 192.168.31.250（eno2，静态）| 工程目录：/home/rain/Documents/services/token_proxy 性质：C 类实操变更（新增本地服务，不改动系统级配置）| 最后更新：2026-09-17

2026-09-17 工程迁移：工程由 /home/rain/Documents/eda_tools_install/token_proxy 迁至 /home/rain/Documents/services/token_proxy。systemd 用户单元（4 处）、用户 crontab（3 处）与 config.yaml 的 cost.output_dir 这三处工程外写死路径已同步改写，服务中断约 0.76s；工程内部 （proxy.py / cost_report.py / run.sh）路径自推导，无需改动。执行与回滚记录见工程内 relocate_20260917/docs/SOP.md。第十六、十七节的历史执行记录仍保留旧路径。

2026-09-14 环境重建：本机网段由 192.168.0.0/24 变为 192.168.31.0/24，系统用户由 rian 变为 rain，Python 由 3.10 变为 3.12，报表输出目录改至工程内 reports/， 且新环境不再使用 samba。本次改动与验证记录见第十七节。下文中凡涉及旧地址/旧路径的 历史执行记录（第十五节、第十六节）保持原样，仅作留档。

⚠ 有未完成的待办，请先看第十八节

十八、待办与交接（2026-09-16 起） —— 截至 2026-09-22，代理已恢复上游默认思考行为（不干预），待办只剩一件： 排查 2026-09-15 的 24 条缺 usage 记录（见 18.5）。那节自包含，读完即可开工。

第十六节的 24 小时对账已结项（结论见 16.6），无需再做； 思考开关的实测结论与最终决策见 18.3（结论：不关思考）； 「前缀整段失效」已于 2026-09-22 定位结项，触发点为 tools / system 定义变更 （改 skill、改规则文件），处置约定见 18.4。

---

一、背景与最终态架构

问题：Trae 自定义模型（deepseek-flash、deepseek-v4-flash、GLM-5.3-Flash、GLM-4.6V）直连厂商，客户端不展示 token 明细，成本无法观测。

前置结论（只读验证）： - LLM 请求不由 Ubuntu 发出，出口在 Windows 客户端侧； - Ubuntu 能直连两上游（DeepSeek / 智谱）。

方案：在 Ubuntu 起一个透明代理，Windows 侧把自定义模型的 base_url 指过来，代理原样转发并记录 usage，再由报表脚本算出成本。

Windows (Trae CN / TraeWork)
   │  自定义模型 base_url
   ├── /ds  ──►  http://192.168.31.250:8788/ds  ──►  https://api.deepseek.com
   └── /glm ──►  http://192.168.31.250:8788/glm ──►  https://open.bigmodel.cn/api/paas/v4
                          │
                          └──► logs/usage.jsonl ──► cost_report.py ──► reports/ 下的 xlsx

最终态的关键设计——双模型手动切换：

代理是 Ubuntu 上的单点服务，Ubuntu 关机即不可用。为避免"Ubuntu 一关 AI 就不能用"，做法是同一模型在 Trae 里建两条：

用途	base_url	何时选
计量	http://192.168.31.250:8788/ds（或 /glm）	Ubuntu 在线时，用量会被记录
直连兜底	厂商官方地址	Ubuntu 关机/代理停止时，可用但不计量

不采用任何 Windows 侧改 state.vscdb 的自动切换脚本——该方案已废弃并清理，切换由使用者按 Ubuntu 开关机状态手动选择模型。因此本工程的全部改动都局限在 Ubuntu 侧，不碰客户端配置。

---

二、目标与约束

项	值
监听	0.0.0.0:8788
路由	/ds/* → https://api.deepseek.com；/glm/* → https://open.bigmodel.cn/api/paas/v4
访问控制	来源 IP 白名单 192.168.31.0/24 + 127.0.0.1/32，越界返回 403
用量记录	logs/usage.jsonl，每行一条 JSON
请求语义	不改 messages；按 thinking 规则表写入 thinking 字段（默认 {"type":"disabled"}，即关闭显式思考；GLM-5.3 系列不支持关闭，已列入跳过）；仅当 stream=true 时注入 stream_options.include_usage=true
密钥处理	代理不存储 key，客户端 Authorization 头原样透传
报表输出	/home/rain/Documents/services/token_proxy/reports（新环境未启用 samba，Windows 需自行取回文件）

2026-09-16 变更（显式思考注入）：config.yaml 新增 thinking 段，代理对经代理的请求 （/ds、/glm 全路由）按模型规则写入 thinking 字段，默认 {"type": "disabled"}，即关闭显式思考， 用于压缩输出 token、降低成本。规则与开关都在配置里，改完执行 systemctl --user restart token-proxy 生效： - thinking.inject: false —— 完全不碰请求体，恢复透明转发； - thinking.default.type: enabled —— 反向强制开启思考； - thinking.skip_models —— 命中即原样放行的模型（大小写不敏感，支持 * 通配）。 glm-5.3* 必须保留：智谱官方明确 GLM-5.3 / GLM-5.3-Flash 强制思考、传 disabled 会报错； - thinking.overrides —— 按模型单独指定注入值，值写 null 表示该模型不注入； - thinking.fallback_on_reject —— 上游 4xx 且报错内容与 thinking/reasoning 相关时， 自动改用客户端原始请求体重发一次（只一次），避免本功能把请求打死。

实现位于 proxy.py：注入在 _prepare_body（与既有 stream_options 注入相邻，已等于目标值时不再改写，幂等）， 规则解析见 parse_thinking_config / resolve_thinking_value，拒绝兜底见 _forward / _should_probe_reject。 全程不改 messages（不影响上游 prompt 缓存键）。改动只涉及 proxy.py 与 config.yaml。

同日新增：请求体结构指纹（诊断用）。logging.shape_file（默认 logs/req_shape.jsonl）记录每条请求的 messages 条数、tools 指纹与首尾若干条消息的哈希与长度，只记哈希、不落任何内容，并附带当次的 hit/miss/out 便于对照；用于排查上游前缀缓存为何整段失效（表现为单次 prompt_cache_miss_tokens 异常大）。 留空则完全关闭该记录。实现见 build_shape_fingerprint / _record。

---

三、前置条件

#	条件	校验命令	适用
1	Python ≥ 3.9 且含 PyYAML	python3 -c "import yaml; print(yaml.__version__)"	报表
2	端口 8788 未被占用	ss -ltn \| grep 8788	代理
3	本机能直连两上游	python3 -c "import socket;s=socket.create_connection(('api.deepseek.com',443),timeout=8);print('连通',s.getpeername());s.close()"（别用根路径判状态码：无 key 时返回 401 属正常，不是故障）	代理
4	Windows 可达本机 8788	Windows 上 curl http://192.168.31.250:8788/healthz	代理
5	venv 含 openpyxl、pyyaml	venv/bin/pip list \| grep -E 'openpyxl\|PyYAML'	报表
6	报表目录可写	touch reports/.w && rm -f reports/.w	报表

新环境注意（2026-09-14）： 1. 系统未预装 curl，本机自检/查余额改用 python3 的 urllib； 2. python3.12 缺 ensurepip 模块且 sudo 需要密码，python3 -m venv venv 无法直接建环境， 建 venv 走第五节步骤 1 的 --without-pip + get-pip.py 免 sudo 流程； 3. samba 未安装、未启用，报表只在 reports/ 本地落盘。

---

四、文件清单

token_proxy/
├── proxy.py        # 代理主程序（标准库实现，无第三方依赖）
├── cost_report.py  # 成本报表生成（xlsx，含余额对账）
├── config.yaml     # 监听/白名单/路由/日志/价目表配置
├── secret.yaml     # 余额查询 API Key（权限 600，不备份不打印）
├── run.sh          # 代理启停脚本（幂等，PID 文件锁）
├── venv/           # cost_report.py 依赖环境（Python 3.12，openpyxl 3.1.5 / PyYAML 6.0.3）
├── reports/        # 报表输出目录（2026-09-14 起启用，替代旧 samba 目录）
├── logs/
│   ├── proxy.log            # 代理运行日志
│   ├── proxy.stdout.log     # run.sh 的 nohup 输出
│   ├── proxy.pid            # 运行中 PID
│   ├── usage.jsonl          # 用量记录（每行一条）★核心数据
│   ├── req_shape.jsonl      # 请求体结构指纹（诊断缓存失效用，只记哈希不记内容，可删）
│   ├── balance_history.jsonl# 余额快照（对账基准）★核心数据
│   ├── cost_report.log      # 报表运行日志
│   └── cost_cron.log        # 定时任务输出（首次 00:00 触发后生成，非缺失）
└── docs/SOP.md     # 本文档

logs/usage.jsonl 与 logs/balance_history.jsonl 是唯一不可再生的数据，任何清理动作都要保留。

---

五、首次部署（全新环境可照做）

幂等：每步先检查，已达标则跳过。

步骤 1：准备依赖

cd /home/rain/Documents/services/token_proxy

# 1) 建 venv。新环境 python3.12 缺 ensurepip（且 sudo 需密码，装不了 python3-venv），
#    故只能用 --without-pip 建，再引导 pip。已存在则跳过。
[[ -d venv ]] || python3 -m venv --without-pip venv

# 2) 若 venv 内没有可用的 pip（首次或旧环境残留），用 get-pip.py 引导
if ! venv/bin/pip --version >/dev/null 2>&1; then
  python3 -c "import urllib.request;urllib.request.urlretrieve('https://bootstrap.pypa.io/get-pip.py','/tmp/get-pip.py')"
  venv/bin/python /tmp/get-pip.py -i https://pypi.tuna.tsinghua.edu.cn/simple
  rm -f /tmp/get-pip.py
fi

# 3) 装依赖（已装则不重复下载）
venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openpyxl pyyaml

# 4) 校验
venv/bin/python -c "import yaml, openpyxl; print('pyyaml', yaml.__version__, '| openpyxl', openpyxl.__version__)"

为什么不能用 python3 -m venv venv：本机只有 Python 3.12，且未安装 python3-venv/python3-pip （import ensurepip 报 ModuleNotFoundError），sudo 又需要密码。--without-pip 绕过 ensurepip， pip 由官方 get-pip.py 引导，全程不需要提权。国内镜像用清华源，避免拉包超时。

旧 venv 失效的典型症状：ModuleNotFoundError: No module named 'yaml'。原因是 venv 是重建前 Python 3.10 建的，包装在 venv/lib/python3.10/site-packages，3.12 只认 lib/python3.12/site-packages。 处理：把旧 venv 改名归档到 .bak/venv.<时间戳>，再按上面流程重建。

步骤 2：写入余额查询密钥

仅当 secret.yaml 不存在时才写入。已存在时不要覆盖，否则会清掉现成的密钥：

[[ -f secret.yaml ]] && echo "secret.yaml 已存在，跳过" || cat > secret.yaml <<'EOF'
deepseek:
  api_key: "<你的 DeepSeek API Key>"
EOF
chmod 600 secret.yaml        # 幂等：权限已是 600 时无变化
ls -l secret.yaml

2026-09-14 环境重建时该文件已随工程保留，权限已是 600，无需重建。 Key 获取：https://platform.deepseek.com/api_keys。仅用于查余额，与 Trae 里配置的 key 相互独立。

步骤 3：核对 config.yaml

键	说明
listen.port	默认 8788，改动需同步改 Windows 侧 base_url
allow_cidr	客户端网段，不在白名单会被 403。2026-09-14 起为 192.168.31.0/24（旧值 192.168.0.0/24，环境重建后必须改，否则客户端全部 403）
routes	上游地址，一般不动
cost.output_dir	报表落盘目录，2026-09-14 起为工程内 reports/（旧值 /home/rian/Documents/rain/trae_cost）
pricing	价目表，见第十节

步骤 4：启动代理并自检

./run.sh start
./run.sh status
python3 -c "import urllib.request;print(urllib.request.urlopen('http://127.0.0.1:8788/healthz',timeout=5).read().decode())"

预期：[已启动] PID=xxxx / [运行中] PID=xxxx / {"status": "ok", "routes": ["ds", "glm"]}

步骤 5：注册定时报表（每天 00:00 全量刷新）

先查重，避免重复写入：

crontab -l 2>/dev/null | grep -q 'cost_report.py' && echo "已存在，跳过" || (
  crontab -l 2>/dev/null; echo '0 0 * * * cd /home/rain/Documents/services/token_proxy && /home/rain/Documents/services/token_proxy/venv/bin/python cost_report.py >> /home/rain/Documents/services/token_proxy/logs/cost_cron.log 2>&1'
) | crontab -

---

六、Windows 侧 Trae 配置

对每个要计量的模型，建两条（一条走代理、一条直连），命名建议用后缀区分：

显示名	服务商	base_url
deepseek-flash-proxy	自定义	http://192.168.31.250:8788/ds
deepseek-flash	DeepSeek	官方地址（直连）
DeepSeek-V4-Flash-proxy	自定义	http://192.168.31.250:8788/ds
DeepSeek-V4-Flash	DeepSeek	官方地址（直连）
GLM-5.3-Flash-proxy	自定义	http://192.168.31.250:8788/glm
GLM-5.3-Flash	Bigmodel	https://open.bigmodel.cn/api/paas/v4
GLM-4.6V-proxy	自定义	http://192.168.31.250:8788/glm
GLM-4.6V	Bigmodel	https://open.bigmodel.cn/api/paas/v4

要点： 1. 走代理那条的地址必须自定义填写（服务商选"自定义"，不要选预置厂商，否则地址栏不可编辑）； 2. 添加时 Trae 会发一条测试请求，成功才允许保存——此时 logs/usage.jsonl 会立刻多一条，可用来确认链路通； 3. API Key 不用改，代理原样透传； 4. 新增其他模型同理：DeepSeek 系走 /ds，智谱系走 /glm，同时在 config.yaml 的 pricing 里补价目，否则成本记为 0 并告警。

若某模型不需要计量，只建直连那条即可，代理侧无需任何配置。

---

七、验证

代理链路

tail -n 3 /home/rain/Documents/services/token_proxy/logs/usage.jsonl
grep -iE "error|fail|traceback" /home/rain/Documents/services/token_proxy/logs/proxy.log | tail -n 10

预期：发一句话后新增一条记录，model、total_tokens 有值。 - route=ds：带 cache_hit_tokens / cache_miss_tokens 分项； - route=glm：只有 cached_tokens，无 hit/miss 对（报表侧自动反推，见第十节）。

报表

venv/bin/python cost_report.py --dry-run     # 只打印不落盘，安全的回归方式
ls -l reports/

预期 dry-run 输出的「已定价请求 N 条」等于总请求数；若出现缺价告警，说明有新模型未配价目。

幂等复跑

./run.sh start 在已运行时输出 [跳过] 代理已在运行；crontab 重复写入前被查重拦截；cost_report.py --dry-run 不改任何状态。

---

八、日常运维

服务由 systemd 用户服务 token-proxy 托管（安装方案见 autostart/SOP.md，linger 已开启）：

操作	命令
启动	systemctl --user start token-proxy
停止	systemctl --user stop token-proxy
重启（改完 config.yaml / proxy.py 后）	systemctl --user restart token-proxy
查看状态	systemctl --user status token-proxy --no-pager
实时看用量	tail -f logs/usage.jsonl
看代理日志	tail -n 50 logs/proxy.log

run.sh（./run.sh {start|stop|restart|status}）是迁移前的手工管理方式，走 nohup + logs/proxy.pid， 与 systemd 互斥：两套混用会抢占 8788 端口，并造成「进程活着但链路不可用」的状态误判。 systemd 正常时不要执行 ./run.sh start，仅在其不可用时才用它应急接管。

⚠ Ubuntu 重启后

代理已注册为 systemd 用户服务 token-proxy 并开启 linger（Linger=yes），开机自动启动，无需人工干预。 重启后确认：

systemctl --user is-active token-proxy      # 期望 active
ss -ltn | grep 8788                         # 期望 LISTEN 0.0.0.0:8788

不要再执行 ./run.sh start：手工 nohup 方式会与 systemd 服务抢 8788 端口（见本章开头说明）。

在重启完成前，Windows 侧请选用直连模型（不带 -proxy 后缀的那条），否则请求会因连接失败而报错。

定时报表由 cron 托管，不受影响。

日志轮转（可选）

logs/proxy.log 与 logs/usage.jsonl 会持续增长。usage.jsonl 是数据、不可删；proxy.log 可直接截断：

: > logs/proxy.log

---

九、成本报表使用

读取 logs/usage.jsonl，按官方价目计算每轮对话成本，调用 /user/balance 记录余额快照，用「相邻两次余额差额」对账「区间自算成本」，输出 xlsx。

项	值
输出目录	/home/rain/Documents/services/token_proxy/reports
全量报表	trae_cost_overview.xlsx（无参数时）
单日报表	trae_cost_<日期>.xlsx（带 --date 时）
区间报表	trae_cost_<起>_<止>.xlsx（带 --since/--until 时）
工作表	按轮汇总（首表） / 请求明细 / 按日汇总 / 按模型汇总 / 余额对账 / 价目表

「按轮汇总」——一轮对话一行

对齐 Trae 客户端会话列表的读法，解决「一屏全是 deepseek-flash，看不出是哪次提问」：

列	含义
时间	该轮首个请求的时刻
使用记录	该轮末条用户提问的前 60 字（prompt）
模型	该轮使用的模型
产品端	TraeCode / TraeWork；识别不到为 -
路由	ds / glm
请求数	该轮内的 HTTP 请求条数（Agent 一次提问会多次步进）
输入(命中/未命中)	该轮内所有请求的输入缓存命中与未命中 token 合计
缓存命中率	该轮 命中输入 ÷ 输入合计，格式 0.00%；输入为 0 时显示 -
输出 / 总 tokens / 成本	该轮内所有请求的合计

缓存命中率怎么用：DeepSeek 的命中价（闲时 0.02 元/百万）只有未命中价（1 元/百万）的 2%，正常 Agent 轮次的命中率应在 95% 以上。若某轮突然大幅下降，说明该轮 prompt 前缀被打断、缓存整体失效——通常是发生了上下文压缩（历史被替换成摘要）， 或上游缓存过期。这一列的用途就是让这种「隐形开销」一眼可见。

切轮规则：代理旁路读取请求体 messages，取末条 <user_input> 标签内容作为该轮标识 （turn_key = sha1(末条提问)[:12]）。同一轮内 Agent 多次步进该值稳定，用户发出新提问才改变； 末条提问同时作为标题，首条提问作为会话标识（conv_key）。同一 turn_key 的请求按时间归并， 相邻间隔超过 30 分钟（TURN_GAP_MINUTES）则另起一轮，避免不同会话提了相同问题时被误合并。

产品端识别：Trae 把产品名写在 system 消息首行（如 You are an interactive agent in TraeCode that helps the USER ...），据此识别； User-Agent 固定为 HTTP 客户端库名 hertz，无辨识价值。

无提问摘要的行：标题显示 （无提问摘要：Trae 内部调用或代理升级前历史）， 说明该请求不含 <user_input>——Trae 生成对话摘要/标题等内部调用，或代理升级前落盘的历史记录。 这类请求无法归属到某一轮，合并为一行置于表尾，以保证成本合计与「请求明细」一致。

已知陷阱（务必保留现有实现）：Trae 会把会话摘要注入 user 消息，而摘要正文里会 以字面形式提到 <user_input> 标签（例如「<user_input> 命中 1 次」）。 因此不能用非贪婪正则配对，会被散文里的标签带偏、把摘要正文当成提问。 代理改用栈式配对（_iter_user_inputs），并丢弃「块内仍含注入标记」或 「开标签前一字符是反引号/引号」的配对。

手动生成

cd /home/rain/Documents/services/token_proxy
venv/bin/python cost_report.py                        # 全量（所有历史）
venv/bin/python cost_report.py --dry-run              # 预演：只打印，不写文件不写快照
venv/bin/python cost_report.py --date 2026-09-12      # 指定某天
venv/bin/python cost_report.py --since 2026-09-10 --until 2026-09-12   # 指定区间
venv/bin/python cost_report.py --daily                # 只统计昨天
venv/bin/python cost_report.py --no-balance           # 跳过余额查询（离线）
venv/bin/python cost_report.py --log-level DEBUG      # 排查用

定时任务

每天 00:00 自动刷新全量总表，条目见第五节步骤 5。

crontab -l | grep cost_report        # 查看

若 00:00 时 trae_cost_overview.xlsx 正被 Windows 的 Excel 打开，写入会失败（CIFS 排他锁），详见第十三节。

---

十、价目表维护

价目表在 config.yaml 的 pricing，版本化：同一模型可配多条，脚本按请求时刻取 effective_from 最新的生效价。新增降价条目放最前，不要删旧条目（历史成本需要按当时价格重算）。

pricing:
  aliases:                       # 上游返回的模型名 -> 价目表规范名
    GLM-5.3-Flash: glm-5.3-flash
  models:
    deepseek-flash:
      - effective_from: "2026-09-10 12:00"
        peak: {cache_hit: 0.04, cache_miss: 2.0, output: 8.0}
        off_peak: {cache_hit: 0.02, cache_miss: 1.0, output: 4.0}

DeepSeek：分峰谷。高峰 = 北京时间周一至周五 09:00-12:00、14:00-18:00，其余空闲且空闲价为高峰价一半。 来源：https://api-docs.deepseek.com/zh-cn/quick_start/pricing/

智谱 GLM：不分峰谷，故 peak 与 off_peak 填同一组价。GLM-5.3-Flash 标准价为命中 0.23 / 未命中 0.8 / 输出 2.8（元/百万 tokens）。 来源：https://open.bigmodel.cn/pricing

    glm-5.3-flash:
      - effective_from: "2026-08-01 00:00"
        peak: {cache_hit: 0.23, cache_miss: 0.8, output: 2.8}
        off_peak: {cache_hit: 0.23, cache_miss: 0.8, output: 2.8}

智谱常有「限时五折」，若要按折扣价核算，改成 0.115 / 0.4 / 1.4。

两家的字段差异（脚本已兼容，无需手工干预）

项	DeepSeek	智谱 GLM
用量明细	prompt_cache_hit_tokens / prompt_cache_miss_tokens 成对给出	只有 prompt_tokens_details.cached_tokens；未命中数由 prompt_tokens − cached_tokens 反推
峰谷	有	无
余额对账	/user/balance 可查	接口不支持 API Key 认证，无法对账（对账表已按 ds 路由隔离）

两个坑，已固化： 1. 空闲价键名必须写 off_peak。YAML 会把裸键 off/on/yes/no 解析成布尔值，导致取不到空闲价、成本算成 0； 2. GLM 的模型名带大写与点号，必须经 pricing.aliases 映射，否则取不到价。

选型提示（实测结论）

截至 2026-09-12 实测，GLM 的 cached_tokens 恒为 0（含 37,123 输入的那轮），即智谱的隐式缓存在 Trae 这类 Agent/RAG 场景下几乎不命中；而本场景输入中约 98% 是命中缓存。

计费项	DS 空闲	DS 高峰	GLM 标准价
缓存命中输入	0.02	0.04	0.23
未命中输入	1	2	0.8
输出	4	8	2.8

也就是说 DeepSeek 的命中价只有未命中的 2%，而 GLM 是 29%。命中率高的场景下 DeepSeek 明显更省；GLM 只在需要其特定能力时使用，并注意控制上下文长度。

---

十一、余额对账说明

• 「距上次差额」= 上一次快照余额 − 本次快照余额，即该区间真实扣费；
• 「期间自算成本」= 该区间内 usage 按价目算出的成本，只统计 ds 路由（智谱无余额接口，纳入会污染差额）；
• 「偏差」= 真实扣费 − 自算成本。偏差来源：余额接口更新有延迟、快照区间与请求时刻存在边界错位、首条快照无基准；
• 相邻快照间隔小于 60 秒且余额未变时不重复记录（append_balance_snapshot 的 min_interval）。

用途：把「自算成本」当趋势看，用「真实扣费」做校准。若某段时间偏差持续偏大，优先怀疑价目表没跟上官方调价。

---

十二、风险与限制

风险	等级	说明与规避
内网端口暴露	中	监听 0.0.0.0，已用 allow_cidr 限为 192.168.31.0/24 + 127.0.0.1/32，越界 403
Ubuntu 单点	中	关机即无计量；用第六节的双模型兜底，手动切直连模型
无开机自启	—	已解决：注册为 systemd 用户服务 token-proxy 并开启 linger，开机自动启动，见第八节
API Key 经内网明文传输	低	请求头含 key，仅在内网段传输；代理不落盘 key
请求体被改动	低	仅注入 stream_options.include_usage，不改 messages，不影响上游 prompt 缓存
大响应内存占用	低	解析 usage 时只保留响应尾部 2MB（max_capture_bytes）；usage 在 SSE 流末尾，故大流式响应也能正常记账
上游压缩响应	低	请求头统一 Accept-Encoding: identity，响应为明文，规避解压依赖
报表写入失败	低	reports/ 目录权限不足，见第十三节（旧环境的 CIFS 排他锁问题在新环境已不适用）
GLM 无法对账	低	仅 DeepSeek 可查余额；GLM 成本只能自算

---

十三、故障排查

代理侧

现象	原因	处理
403 forbidden	来源 IP 不在白名单	确认客户端 IP 属 192.168.31.0/24，或把网段加入 allow_cidr。环境重建后最常见的故障，见第十七节
404 未知路由	base_url 前缀写错	必须以 /ds 或 /glm 开头
上游 401	key 缺失/错误	检查 Trae 模型配置里的 API 密钥
上游 405 / 404	上游 base 自带路径前缀丢失	已修复：代理会拼接 base 自带路径（如 /api/paas/v4）
usage 为 null	① 上游返回错误响应；② 非流式响应体超过 max_capture_bytes，截断后无法解析 JSON	① 属预期；② 调大 max_capture_bytes（流式响应已改为保留尾部，不受影响）
端口占用	已有进程监听 8788	ss -ltnp \| grep 8788 定位后处理
Windows 报连接失败	Ubuntu 关机或代理未启动	systemctl --user status token-proxy；重启后本应自动拉起，未起时 systemctl --user start token-proxy，或临时改选直连模型
流式回答无 usage	客户端未开 stream，或上游忽略 include_usage	检查 logs/proxy.log 中该条的 usage 字段

报表侧

现象	原因	处理
成本为 0 且日志提示「缺少价目」	模型名未在 pricing.models 中	补该模型条目或配 pricing.aliases 映射
空闲价读不到（成本偏低）	键名写成了 off 被 YAML 当布尔	改为 off_peak
「按轮汇总」某行标题为空/显示「无提问摘要」	该请求不含 <user_input>（Trae 内部调用或升级前历史）	属预期，见第九节「按轮汇总」
「按轮汇总」标题是摘要正文而非提问	<user_input> 提取实现被改回了非贪婪正则	恢复为栈式配对 _iter_user_inputs，见第九节陷阱说明
配置中缺少 pricing.models 价目表	config.yaml 无 pricing 段	按第十节补齐
ModuleNotFoundError: No module named 'yaml'	venv 是环境重建前 Python 3.10 建的，包装在 lib/python3.10/site-packages，3.12 读不到	按第五节步骤 1 重建 venv（--without-pip + get-pip.py），见第十七节
venv/bin/pip 报路径不存在	旧 venv 的 pip shebang 写死了旧用户路径 /home/rian/...	同上，重建 venv
余额查询失败	网络或密钥失效	检查 secret.yaml（权限 600）与 python3 -c "import json,urllib.request;req=urllib.request.Request('https://api.deepseek.com/user/balance',headers={'Authorization':'Bearer <KEY>'});print(urllib.request.urlopen(req,timeout=10).read().decode())"
xlsx 写入失败 Permission denied	reports/ 目录权限不足（旧环境还有「被 Windows 打开」的 CIFS 排他锁，新环境无 samba 不再涉及）	检查 reports/ 属主与权限后重跑
定时未执行	cron 服务停止	systemctl status cron；另看 logs/cost_cron.log

---

十四、回滚与下线

按「不留备份」约定维护：本工程不再保留 backup/ 快照，回滚依赖下列操作。

场景	操作
暂停计量（保留数据）	systemctl --user stop token-proxy；Windows 侧改选直连模型
恢复计量	systemctl --user start token-proxy；Windows 侧改选 -proxy 模型
撤销定时报表	crontab -l \| grep -v cost_report.py \| crontab -
临时停报表	用 --dry-run 手动跑，或先撤销定时任务
只删报表功能	删 cost_report.py 与 venv/；logs/ 与 reports/ 是纯数据，按需保留
整体下线	① ./run.sh stop；② 撤销定时任务；③ Windows 侧全部改回直连模型；④ 需要留档先取走 logs/usage.jsonl、logs/balance_history.jsonl 与 reports/ 下的报表；⑤ 删除 token_proxy/ 目录

全流程无系统级改动（无 systemd 单元、无 /etc 修改、无全局环境变量），删除目录即彻底还原。

---

十五、执行记录（2026-09-12 实测）

本节为旧环境（用户 rian、主机 192.168.0.11、Python 3.10、samba 共享）的实测留档， 其中的地址与路径不代表当前环境。当前环境的部署与验证记录见第十七节。

代理

验证项	结果
mock 上游：非流式转发	通过，响应完整回传
mock 上游：SSE 流式转发	通过，逐帧转发含 [DONE]
未知路由	通过，返回 404 JSON
usage 落盘	通过，含 prompt/completion/total 与缓存命中、未命中分项
真实 DeepSeek 链路	通过（无 key 时 401，链路正常）
真实智谱链路	通过（修复 base 路径前缀拼接后），智谱接受注入的 stream_options
白名单	通过，实测来源 192.168.0.11 命中白名单
大响应 usage 捕获	通过（离线构造 2.6MB SSE）：旧策略保留头部解析为 None，改为保留尾部后正确解出 usage；小响应行为不变

与 DeepSeek 官方控制台对账（2026-09-12 21:00 窗口）

项	官方面板	按我们的价目反算	结论
命中输入	7,622,784	—	—
未命中输入	401,457	—	—
输出	128,026	—	—
消费金额	￥1.06	1.06602 元	误差 0.6%，价目表与计费口径验证通过

2026-09-12 为周六，DeepSeek 周末全天按空闲价计（cache_hit 0.02 / cache_miss 1.0 / output 4.0）。

同期代理落盘：命中 9,688,960 / 未命中 317,830 / 输出 126,326，自算 1.017 元，比官方低 4.6%。

• 输出量差 1.3%（窗口对齐）；前后平移 ±10 分钟反而更差，故非整点边界错位；
• 未命中缺口 8.4 万已定位为 3 条响应超 2MB 导致 usage 丢失，已通过「保留响应尾部」修复（见风险表与排查表）；
• 命中量 +27% 属口径差异，根因未定；需等全天数据都经代理后，用官方 24h 总量复核。

报表

验证项	结果
全量 dry-run	通过，114 条请求全部定价，无缺价告警，EXIT=0
GLM 成本核算	通过，实测 58190×0.8 + 4430×2.8 = 0.058956 元，与脚本输出逐位吻合
余额对账	通过，快照正常追加；窗口已按 ds 路由隔离
价目表版本化	通过，按 effective_from 正确匹配降价前后价
crontab 幂等	通过，重复执行提示「已存在，跳过」
cron 精简环境	通过，env -i HOME=... PATH=/usr/bin:/bin 下运行正常
xlsx 输出	通过，6 张工作表内容正常，落盘 samba 可被 Windows 直接打开
按轮汇总切轮	通过，按末条 <user_input> 哈希归并；同一轮内多次 Agent 步进正确合并为一行
按轮汇总成本合计	通过，各轮成本之和与「请求明细」一致
<user_input> 提取	通过，栈式配对排除了摘要正文里对标签的字面引用（实测 3 处命中，仅 1 处为真实提问）
产品端识别	通过，从 system 消息首行识别出 TraeCode
按轮缓存命中率	通过，命中 ÷ 输入合计，与「按日汇总」同算法；实测正常轮次 95.5%~99.5%，输入为 0 时显示 -

历史脏数据清洗（2026-09-12 20:54，一次性）

代理首个版本用非贪婪正则提取 <user_input>，被会话摘要正文里的标签字面引用带偏， 在 2026-09-12 20:15 ~ 20:50 落盘了 73 条脏标题。清洗方式：

• 判据（限定 ts < 2026-09-12 20:52 的历史窗口，白名单，不误伤真实提问）： ① prompt 含 <system-reminder 或 <user_input；② prompt 以 Your task is to create a detailed summary 开头（Trae 内部摘要调用）；③ usage 为 null。
• 动作：仅把命中记录的 prompt / turn_key / conv_key 置为 null， token 与成本字段一律不动；这些记录归入表尾「无提问摘要」行，成本合计不变。
• 备份：.bak/usage.jsonl.20260912-205414（清洗前 282 条）、 .bak/usage.jsonl.20260912-205454（补清洗前 287 条）。
• 幂等：重复执行命中 0 条（已验证）。
• 结果：「按轮汇总」由 9 行收敛为 3 行，请求数合计 = 「请求明细」行数，成本合计与日志一致。

---

十六、待办：24 小时全量对账（交接给下一轮对话）

本节是给下一个对话窗口的交接说明。读完本节即可知道要做什么，无需回溯历史对话。 状态：未完成，等待一个「全天数据都经代理」的完整自然日。

16.1 为什么要做

2026-09-12 晚做过一次单小时抽样对账，结果如下：

20:00~21:00	DeepSeek 官方控制台	代理落盘	差
输入(缓存命中)	7,622,784	9,688,960	+27%
输入(缓存未命中)	401,457	317,830	-21%
输出	128,026	126,326	-1.3%
消费金额	￥1.06	1.017 元	-4.6%

已结清的两项：

• ✅ 价目表与计费口径验证通过：官方 ￥1.06，用 config.yaml 闲时价反算 = 1.06602 元，误差 0.6%。
• ✅ 未命中缺口 8.4 万已定位：响应体超 2MB 导致 usage 丢失（捕获缓冲原先保留响应头部， 而 usage 在 SSE 流末尾）。2026-09-12 21:10 已修复为保留尾部。
• 离线验证通过：构造 2.6MB SSE，旧策略解析为 None，新策略正确解出 usage；
• 线上验证未完成：修复后截至 2026-09-12 21:20 尚无新的 >2MB 响应出现， 需在步骤 1 中确认「修复后出现了大响应且 usage 正常」才算闭环。

已知数据缺口（修复前的历史，不可修复）：2026-09-12 全天共 9 条 usage 缺失 （19:27:55 ~ 21:08:32），全部是响应超 2MB 造成，合计约 8.4 万未命中 token 未计入。

仍未结清（本节要做的三件事）：

1. 「命中输入」比官方多 27% —— 根因未定，需全天数据复核；
2. 成本低估 4.6% 是否已随 21:10 的修复消失；
3. 请求条数是否与官方完全一致（不一致即说明该日有请求没走代理）。

单小时窗口不足以定论：代理 2026-09-12 17:56 才上线，当天白天数据缺失，且官方控制台有聚合延迟。

✅ 上述三项已于 2026-09-16 全部结清，对账明细与 2MB 修复的线上验证见 16.6。

16.2 前置条件（缺一不可）

#	条件	校验方法
1	选一个完整自然日，且该日 00:00 起代理已在运行	代理上线于 2026-09-12 17:56，故最早只能取 2026-09-13（含）之后
2	该日全天 Trae 只用带 -proxy 后缀的模型，未切直连	见第六节「双模型」设计。切了直连 → 官方有、我们没有，必然对不上
3	该日无其他程序使用同一个 DeepSeek API Key	官方统计按 Key 聚合
4	代理已包含 21:10 的修复	grep -n "overflow" proxy.py 应有输出
5	usage.jsonl 在该日连续无缺口	步骤 1 的统计命令

⚠ 2026-09-12 不可用作对账日：该日 usage.jsonl 有 9 条 usage 缺失（见 16.1）， 属修复前历史，成本必然低估。请从 2026-09-13（含）之后选完整自然日。

⚠ 峰谷价：若目标日是工作日，价格分峰谷（09:00-12:00、14:00-18:00 为高峰，价×2）； 若是周末则全天闲时。对账前确认 config.yaml 的 pricing 与当日匹配，规则见第十节。 （2026-09-13 是周日，全天闲时；2026-09-14 起为工作日。）

⚠ 2026-09-14 环境重建的影响：重建发生在 2026-09-14 凌晨（网段由 192.168.0.0/24 变为 192.168.31.0/24，见第十七节），重建后代理一度因白名单不匹配拒收请求（09-14 00:37 起）， 直到 09-14 00:56 修复重启。因此 2026-09-14 当天数据有缺口，不可用作对账日； 2026-09-13 全天代理在线且白名单匹配，仍是有效的对账日候选。

16.3 步骤

步骤 1：确认代理健康与当日数据完整性

cd /home/rain/Documents/eda_tools_install/token_proxy
./run.sh status
./venv/bin/python -c "
import json
rows=[json.loads(l) for l in open('logs/usage.jsonl',encoding='utf-8') if l.strip()]
day='<目标日期 YYYY-MM-DD>'
sel=[r for r in rows if r['ts'].startswith(day)]
big=[r for r in sel if (r.get('bytes') or 0)>2097152]
print('当日记录数:',len(sel))
print('当日 usage 缺失条数:',sum(1 for r in sel if r.get('usage') is None))
print('当日响应>2MB:',len(big),'其中 usage 正常:',sum(1 for r in big if r.get('usage')))
print('路由分布:',{k:sum(1 for r in sel if r.get('route')==k) for k in ('ds','glm')})
"

判读：

• usage 缺失条数 应为 0（上游错误响应除外）。若非 0，说明仍有响应丢 usage，先排查再对账。
• 响应>2MB 条数 > 0 且「usage 正常」等于它 → 2026-09-12 21:10 的「保留响应尾部」修复 在线上确认生效，16.1 第 2 项可结案。
• 若 响应>2MB 为 0 → 当天没触发过大响应，修复仍待验证（不影响对账，但不能据此结案）。

步骤 2：生成该日报表，得到我们的数字

./venv/bin/python cost_report.py --date <目标日期>
# 输出：<cost.output_dir>/trae_cost_<目标日期>.xlsx（目录见 config.yaml）

从该 xlsx 中取：

来源工作表	取哪些列
按日汇总	请求数 / 输入(缓存命中) / 输入(缓存未命中) / 输出 / 总tokens / 成本(元) / 缓存命中率
按模型汇总	确认全部为 deepseek-flash，且请求数与「按日汇总」一致
余额对账	「距上次差额」= 该区间真实扣费（唯一真值）

余额对账看的是相邻两次余额快照的差额，需确保有覆盖目标日两端的快照。 若没有，先跑一次全量报表补一个快照：./venv/bin/python cost_report.py。

步骤 3：取官方数字（必须由用户提供，AI 无法访问）

请用户打开 https://platform.deepseek.com/usage 并提供目标日的：

1. API 请求次数
2. Tokens 总量
3. 消费金额
4. 分项：「输入（命中缓存）」「输入（未命中缓存）」「输出」三项各自的值

控制台时间粒度为北京时间，与 usage.jsonl 的 ts 一致，无需时区换算。 若只有「按小时」视图，请依次悬停 24 根柱子取数；或切到「按天」视图直接读总量。

步骤 4：比对与判据

核对项	判据	不符时的含义
API 请求次数	应完全一致	我们少 → 该日有请求走了直连，或用了别的 Key
消费金额	误差 ≤ 2% 通过	我们低 → 仍有 usage 缺失；我们高 → 价目偏贵
缓存命中率	与官方差值 < 1pp	仍差 1~2pp → 见 16.4
输出 tokens	误差 ≤ 2%	偏差大 → 有非 Trae 客户端调用

步骤 5：有偏差时的排查顺序

1. usage 缺失条数（步骤 1）—— 最常见的漏记来源；
2. 是否有请求走了直连：按模型汇总 的请求数 vs 官方请求次数；
3. 价目表是否与该日峰谷匹配（第十节）；
4. 余额对账的「偏差」列若持续同向偏大，优先怀疑价目没跟上官方调价。

16.4 预期结果与口径差异的处理

• 若「命中输入 +27%」在全天窗口下收敛到 1pp 以内 → 单小时抽样噪声，结案。
• 若仍稳定偏大 → 记录为已知口径差异（官方面板与 usage 字段的 cache 统计口径不同）， 并在使用报表时给「余额对账」的「真实扣费」更高权重——余额差值是唯一真值。
• 余额接口有更新延迟，短窗口（< 1 小时）对账不可信，24 小时窗口才有效。

16.5 完成后要做的事

1. 把结论写回本节，把 16.1 的「仍未结清」三项标记为已结清或转为已知限制；
2. 若调整了 config.yaml 的价目，按第十节「版本化」新增条目，不要删旧条目（历史成本要按当时价重算）；
3. 若有代码改动，按第十节/第十二节同步更新风险表与排查表。

16.6 对账结果补录（2026-09-16）

对账窗口：2026-09-16 00:00–04:00（北京时间，闲时）。官方数字取自用户提供的控制台视图， 本机数字取自 logs/usage.jsonl，按 config.yaml 现行价与峰谷规则计算。

核对项	判据（16.3 步骤 4）	官方	本机	结论
API 请求次数	完全一致	250	250	✅
Tokens 总量	—	56,818,460	56,818,460	✅ 逐项一致
输入（命中缓存）	—	23,623,552（03:00–04:00）	23,623,552	✅
输入（未命中缓存）	—	401,003（03:00–04:00）	401,003	✅
输出	误差 ≤2%	159,888（03:00–04:00）	159,888	✅
缓存命中率	与官方差值 <1pp	—	98.31%	✅
消费金额	误差 ≤2%	￥3.92	3.9252 元	✅ 误差 0.13%

16.1「仍未结清」三项的结项结论：

1. 「命中输入比官方多 27%」→ 结案（单小时抽样噪声）：全窗口分项 token 与官方逐项一致；
2. 「成本低估 4.6%」→ 已随 2026-09-12 21:10 的「保留响应尾部」修复消失：本次误差 0.13%；
3. 「请求条数是否与官方完全一致」→ 一致（250 = 250），该窗口无直连请求。

2MB 修复的线上验证（16.1 遗留项）→ 已闭环： 2026-09-15 21:03 与 2026-09-16 02:22–02:28 共 7 次响应体 5.1–5.3 MB， usage 全部正常解析入库（修复前这类响应必然丢 usage）。

同日新发现（待排查）：2026-09-15 有 24 条记录缺 usage，特征为 status=200、 响应体固定 1190 字节、集中于 03:00–04:21，与「响应过大」无关。详见 cost_audit/20260916-token成本-巡检报告.md 异常 A5。

复现命令：

cd /home/rain/Documents/eda_tools_install/token_proxy
./venv/bin/python cost_audit/analyze_usage.py

---

十七、环境重建记录（2026-09-14）

本节记录一次「整机重建后重新部署」的过程与验证，供下次重建直接照做。

	旧环境	新环境（2026-09-14 起）
用户 / 家目录	rian / /home/rian	rain / /home/rain
主机地址	192.168.0.11	192.168.31.250（eno2，客户端统一用这个；另有 eno1 192.168.31.249、eno3 192.168.31.251）
网段	192.168.0.0/24	192.168.31.0/24
Python	3.10	3.12.3（无 ensurepip，sudo 需密码）
报表输出	/home/rian/Documents/rain/trae_cost（samba）	工程内 reports/（未启用 samba）

⚠ 本机三个网卡已于 2026-09-14 固化为静态 IP（netplan，见 net_static_ip/SOP_静态IP.md）： eno1=192.168.31.249、eno2=192.168.31.250、eno3=192.168.31.251，不再随 DHCP 漂移。 代理监听 0.0.0.0，三个地址都能通；客户端统一填 192.168.31.250。

17.1 重建后暴露的两个问题

#	现象	根因	处理
1	代理在跑，但客户端请求全部失败；logs/proxy.log 反复出现 拒绝非白名单来源: 192.168.31.40	config.yaml 的 allow_cidr 仍是旧网段 192.168.0.0/24	改为 192.168.31.0/24 后 ./run.sh restart
2	venv/bin/python cost_report.py 报 ModuleNotFoundError: No module named 'yaml'；venv/bin/pip 报旧路径 /home/rian/... 不存在	venv 是重建前 Python 3.10 建的，包装在 lib/python3.10/site-packages，新系统 3.12 不认；pip 的 shebang 亦写死旧路径	旧 venv 归档到 .bak/venv.<时间戳>，按第五节步骤 1 免 sudo 重建

问题 1 的定位要点：代理进程活着 ≠ 链路可用。./run.sh status 只证明进程在， 真正的证据是 logs/proxy.log 里的 拒绝非白名单来源 与 logs/usage.jsonl 是否停止增长。

17.2 本次改动清单

文件	变更点	风险	回滚
config.yaml	allow_cidr：192.168.0.0/24 → 192.168.31.0/24	客户端不在新网段仍会 403	改回旧网段
config.yaml	cost.output_dir → /home/rain/Documents/eda_tools_install/token_proxy/reports	无（目录自动创建）	改回旧路径
venv/	旧 3.10 环境归档，重建为 3.12 + openpyxl 3.1.5 / PyYAML 6.0.3	无	从 .bak/venv.<时间戳> 恢复
docs/SOP.md	地址/路径/命令更新为新环境，新增本节	无	.bak/SOP.md.<时间戳>
proxy.py	仅 docstring 里的旧 IP 注释	无	.bak/proxy.py.<时间戳>
crontab	按新路径注册每日 00:00 全量报表（脚本自带查重）	无	crontab -l \| grep -v cost_report.py \| crontab -

改动前的 config.yaml、SOP.md、proxy.py、usage.jsonl 均已在 .bak/ 下按时间戳留存。

17.3 验证结果

验证项	命令/方法	结果
代理进程	./run.sh status	[运行中] PID=23319
健康检查	urllib 请求 /healthz	200 {"status": "ok", "routes": ["ds", "glm"]}
新网段放行	绑定源 192.168.31.39 请求 192.168.31.40:8788/healthz	200 OK（改动前为 403）
启动日志白名单	tail logs/proxy.stdout.log	白名单=['192.168.31.0/24', '127.0.0.1/32']
上游链路	无 key 请求 /ds/chat/completions	上游返回 401，证明已正常转发
usage 落盘	tail logs/usage.jsonl	新增记录，字段完整
报表依赖	venv/bin/python -c "import yaml, openpyxl"	pyyaml 6.0.3 \| openpyxl 3.1.5
报表 dry-run	venv/bin/python cost_report.py --dry-run	893 条请求全部定价，无缺价告警
cron 精简环境	env -i HOME=/home/rain PATH=/usr/bin:/bin .../venv/bin/python cost_report.py	报表成功生成到 reports/trae_cost_overview.xlsx
crontab 幂等	连续注册两次	第二次输出 [跳过] 定时条目已存在

自测产生的 1 条 401 记录（model=deepseek-chat、usage=null）已从 logs/usage.jsonl 移除， 移除前备份为 .bak/usage.jsonl.20260914-005812，保证用量数据不含测试噪声。

17.4 下次重建的检查清单

1. 改 config.yaml 的 allow_cidr（本次为 192.168.31.0/24）与 cost.output_dir；
2. 按第五节步骤 1 重建 venv——新系统无 python3-venv 且 sudo 需密码时，用 --without-pip + get-pip.py；
3. systemctl --user start token-proxy（或依赖开机自启），并用非本机来源 IP 验证一次不再 403；
4. 按第五节步骤 5 注册 cron（脚本自带查重，可反复执行）；
5. 确认 secret.yaml 仍在且权限 600（本次随工程保留，未重建）。

新环境未启用 samba，报表只在 reports/ 本地落盘；若后续要恢复「Windows 直接看」， 需重新安装并配置 samba，属系统级变更，另行评估。

---

十八、待办与交接（2026-09-16 起）

本节自包含：新开一个对话窗口时，读完本节即可接手，无需回溯前文。 完整分析与建议见 cost_audit/20260916-token成本-巡检报告.md。

18.1 当前状态（截至 2026-09-16 15:57 重启）

项	状态
代理	systemctl --user 服务 token-proxy，2026-09-16 15:57:37 重启（PID 709938），active
思考注入	已关闭（不干预）：thinking.inject: false，代理不改写 thinking，走上游默认（DeepSeek 默认 high）。这是 2026-09-16 的最终决策，依据见 18.3
跳过名单	glm-5.3*（保留，仅当重新启用注入时生效）
4xx 兜底	fallback_on_reject: true（保留，仅当重新启用注入时生效）
结构指纹	已启用：logs/req_shape.jsonl，每条请求记录 messages 条数 / tools 指纹 / 首尾消息哈希（只有哈希，无内容）
数据源	logs/usage.jsonl（计量）、logs/req_shape.jsonl（诊断）、logs/proxy.log（运行日志）
已结项	第十六节 24 小时对账（见 16.6）；2MB 大响应丢 usage 的线上验证；思考开关的实测与决策（见 18.3）；「前缀整段失效」归因（见 18.4，2026-09-22）

变更前备份（按时间由近及远）：.bak/config.yaml.20260916-155454（本次恢复思考前）、 .bak/proxy.py.20260916-150314 与 .bak/config.yaml.20260916-150314（加结构指纹前）、 .bak/*.20260916-141406（最初实装 thinking 注入前）。 完整回滚：覆盖回对应文件 + systemctl --user restart token-proxy。

18.2 待办清单

#	待办	类型	入口
T3	排查 2026-09-15 的 24 条缺 usage 记录	需新增采集	见 18.5

已决策 / 不再作为待办：

• T2 定位「前缀整段失效」的触发点 → 2026-09-22 已定位结项，触发点为 tools / system 定义变更（改 skill、改规则文件），实测数据与处置约定见 18.4；
• T1 关闭思考是否变笨、T4 观察成本下降 → 2026-09-16 决策不关闭思考，两项一并结项，依据见 18.3；
• 缩短会话（P2）→ 属使用者习惯，代理无法强制，已由使用者主动控制；
• 高峰挪闲时（P5）→ 收益仅约 4.9%，且受工作时段约束，暂不做；
• 输出上限调大（P4）→ 使用者已在 Trae 客户端改为 384K（deepseek-flash 官方上限），截断已归零。

18.3 思考开关：实测结论与最终决策（2026-09-16）

最终决策：thinking.inject: false，代理不干预思考，保持上游默认（DeepSeek 默认 high）。 config.yaml 中保留完整能力（default / reasoning_effort / skip_models / overrides / fallback_on_reject）， 需要时把 inject 改 true 即可一键启用，改动理由已写在配置注释里。

决策依据（全部为本工程实测或官方口径）：

#	结论	证据
1	关闭思考只省输出侧，输入侧一分不省	关思考前后对比：输入 prompt 中位 188,618 → 199,419（无变化，反因会话增长略升）；前缀稳定时每轮新增未命中 505 → 442；输出中位 1,003 → 501（腰斩）
2	DeepSeek 的 disabled 是真关推理，不存在"隐藏思考"	上游 usage.completion_tokens_details.reasoning_tokens 字段整体消失（不是置 0），且 completion_tokens 同步腰斩——说明真的少生成了约一半 token。（对照：Claude 的 display: omitted 才是"思考照发生照计费、只是不返回"）
3	Trae 本就不把思考回传进上下文	前缀稳定配对 1840 组：假设"上一轮输出含思考全部回传"→ 残差中位 −330（逻辑上不成立）；假设"思考不回传"→ 残差中位 +154、71% 为正。故"不显示思考"从未省过上下文
4	官方口径：Agent 场景推荐 high，不是 low	官方指南：low 用于分类 / 提取 / 改写等边界明确任务；high（默认）用于代码审查、调试、工具选择、需规划的工作流；max 用于失败代价高的任务。本代理承载的正是 Agent 类任务
5	降档 low 的收益本身不确定	多来源对 low 的映射口径不一致（有称 low/medium 会映射回 high），且 Agent 类请求可能被上游自动升档

综合判断：思考占输出 62%、约占总成本 29%，属"买到质量"的钱；真正的浪费在 18.4 的 「前缀整段失效」（约 15%）。能省则省，但这一项不该省。

如需临时启用（例如批量跑简单任务）：

1. 改 config.yaml 的 thinking.inject: true；
2. 按需设 default.type（disabled = 关思考 / enabled = 保思考）与 reasoning_effort（low/high/max）；
3. systemctl --user restart token-proxy。

校验手段（唯一硬指标：看 completion_tokens_details.reasoning_tokens 字段是否存在）：

cd /home/rain/Documents/services/token_proxy
./venv/bin/python cost_audit/verify_thinking.py

脚本自动从 logs/proxy.log 取最后一次「代理启动」时刻，输出重启前后的 输出量 / 含 reasoning_tokens 的请求占比 / 思考 token 占比 / 单位成本对比。

18.4 T2：定位「前缀整段失效」（2026-09-22 已定位）

现象：单个请求 prompt_cache_miss_tokens 异常大（1 万~37 万），而 prompt_cache_hit_tokens 极小。 定价：命中 0.02 元/百万 vs 未命中 1 元/百万，差 50 倍；实测 60 次此类请求占总未命中 64%、成本 4.12 元（15%）。

排查方法：在 logs/req_shape.jsonl 中取该请求及其前一条，对比四项：

对比项	若变化 → 结论
shape.head[0]（system 消息指纹）	系统提示被改写（改规则 / 改技能 / 项目文件变动）
shape.tools_hash	工具定义被改写
shape.msgs	消息条数突变（上下文被压缩或重排）
shape.head[1..7]	历史中段被改写

# 列出所有大额未命中的请求及其结构指纹
./venv/bin/python -c "
import json,pathlib
p=pathlib.Path('logs/req_shape.jsonl')
rows=[json.loads(l) for l in p.open(encoding='utf-8') if l.strip()]
for i,r in enumerate(rows):
    if (r.get('miss') or 0)>10000:
        prev=rows[i-1] if i else None
        print(r['ts'],'miss=',r['miss'],'msgs=',r['shape']['msgs'],'tools_hash=',r['shape']['tools_hash'])
        print('   head0=',r['shape']['head'][0][:40])
        if prev: print('   上一条 head0=',prev['shape']['head'][0][:40],'tools_hash=',prev['shape']['tools_hash'])
"

18.4.1 定位结论（2026-09-22）

触发点：tools 定义或 system 消息被改写——也就是改 skill、改规则文件、改项目上下文文件。

对照实验（logs/req_shape.jsonl 覆盖窗 2026-09-16 15:12 ~ 2026-09-22 20:38，以同一会话内 相邻两次请求为单位配对）：

结构维度	失效请求（41 对）	正常请求（2096 对）
system 消息变	14.6%	0.0%
tools 定义变	31.7%	0.0%
历史中段变	19.5%	2.1%
msgs 减少	7.3%	0.0%

2096 组正常请求里 system / tools 的变化率是 0.0%（一次都没发生），而失效请求里 tools 变占 31.7%。工具或技能定义一变，前缀几乎必然整段失效。

机理：Trae 把技能 / 工具定义注入请求前缀。会话中途改动 skill 文件后注入内容变化， 从该位置起的所有前缀（system + tools + 全部历史）在上游缓存里整段作废，下一个请求要把 十几万甚至几十万 token 按未命中价重算。

实测归因（覆盖窗内 58 条 miss>10k，成本 6.077 元；其中 41 条为有前序的中途失效）：

主因	条数	miss 合计	成本（元）
仅 tools 变（改工具 / 技能定义）	7	1,488,995	1.526
system + tools 同变	6	1,341,515	1.370
仅历史中段变（上下文压缩）	6	710,144	0.733
无结构变化（上游缓存过期等）	22	351,345	0.604

失效请求的提问原文集中在 skill 调优对话（如「你建议下是新建 skills 还是怎么做」 「请再次读取我更新后的写 SOP 的 skill，重新写」），与本节的怀疑项一致。

按天分布把问题锁定在 2026-09-19：当天 16 条失效 / 2.850 元，其中 10 条 / 2.450 元由 tools / system 变化触发——正是密集编写与讨论 skill 的那一天。

口径订正（2026-09-23）：原文此处写「09-20 之后回落到 0.12 ~ 0.27 元/天，已自然收敛」， 该判断已被推翻。后续实测：09-21 0.118 元 → 09-22 0.588 元 → 09-23 0.536 元 （仅统计到 01:52）。只要本项目持续改 skill / 规则 / 档案，前缀失效就是周期性的， 不会自然收敛。

复盘口径提醒：本节开头「实测 60 次此类请求……成本 4.12 元（15%）」是 2026-09-16 的 全时段数字；18.4.1 的 58 条 / 6.077 元是 req_shape 覆盖窗内的数字，两者时间窗不同， 不要混用。

两个附带结论：

1. 上下文压缩本身也会触发一次前缀失效（「仅历史中段变」6 条 / 0.733 元）：压缩把历史换成 摘要，中段哈希全变。所以压缩不是零成本——它把「持续付费读长历史」换成「一次性全量重算」， 对长会话仍划算；但前提是压缩之后不要再改 skill，否则连压缩后的前缀也一起作废。
2. 会话首条是必要开销：新会话第一问必然全 miss（覆盖窗内 15 条 / 1.093 元，约 0.073 元/会话）。

处置约定（零质量代价，不改任何代码与配置）：

改动 skill / 规则文件之后，立即开新会话；不要在长会话中途改。

依据是量级对比：

做法	单次代价
长会话中途改 skill（msgs=533 时）	约 36.6 万 token ≈ 0.37 元
改完 skill 直接开新会话	首条约 3.1 万 token ≈ 0.031 元

差约 10 倍。这条路省下的是「重算全部历史」的未命中费用，不影响输出质量。

复跑命令（与 analyze_usage.py 同目录，只读、路径自推导）：

cd /home/rain/Documents/services/token_proxy
./venv/bin/python cost_audit/analyze_prefix_fail.py

脚本输出对照实验、主因归类、样本原文与失效按天分布；skill 调优结束后跑一次， 即可确认有无新增长。

18.5 T3：24 条缺 usage 的记录

• 现象：2026-09-15 有 24 条 status=200、响应体固定 1190 字节、缺 usage，集中于 03:00–04:21；
• 已排除：与「响应超 2MB 丢 usage」无关（该问题已于 09-12 修复，本次 7 次 5MB 响应全部正常计费）；
• 待做：需临时增采「无 usage 响应的体摘要」（响应体不含敏感信息时），属 C 类改动，实施前需确认。

18.6 交接提示

• 改动代理前：改 proxy.py 或 config.yaml → 备份到 .bak/<名>.<时间戳> → 离线验证（/tmp 下临时端口 + 假上游）→ systemctl --user restart token-proxy；
• 注意重启会打断客户端正在进行的流式回答；
• 不要删 logs/usage.jsonl 与 logs/balance_history.jsonl（唯一不可再生数据）；logs/req_shape.jsonl 可随时删（诊断用，只含哈希）；
• 本工程所有分析脚本在 cost_audit/，均只读、路径自推导，可直接复跑。

---

十九、执行记录（2026-09-22）：AI skill 命中率优化（层 1）

变更对象不在本工程内：本次改的是 Trae 的技能文件（~/.trae-cn/skills/*/SKILL.md）与全局规则文件 ~/.trae-cn/user_rules/rule-skill-index.md。沿用本 SOP 留档，因为 18.4.1 已证实改动 skill 会直接 导致本代理的前缀整段失效，两者在成本上强耦合——skill 改动本身就是本代理的成本事件。

19.1 变更背景

Trae 的 skill 由模型按 description 语义匹配触发，天生是概率性的。本次改动前有两个实测失败样本：

场合	应有行为	实际
读 docs/SOP.md 了解工程背景	加载 reading-docs-for-context（其规定：待读量超 800 行须派子 agent）	未加载，主上下文通读 963 行 / 19,973 token
修改 docs/SOP.md 第 18 节	加载 writing-ops-change-sop	未加载，凭个人理解改写

三条根因：① description 只写语义场景、缺具体触发物（文件名 / 路径 / 类名）；② 未覆盖「更新既有文档」这类边界；③ 模型在任务流中不做「我该用哪个 skill」的元认知。

机制可靠性分档（已确认）：Hook ✅ 必然执行 > Rules 🟡 每轮注入靠遵守 > Skill 🔴 概率触发。故「必须发生的事」不应托付给 skill。

19.2 变更目标

• 同类任务中，reading-docs-for-context 与 writing-ops-change-sop 的主动加载可复现；
• 判据：三个触发样本里至少两个命中即算层 1 有效；
• 无反向副作用：无关任务不被反复加载导致每轮上下文膨胀；frontmatter 结构完好。

19.3 前置条件

• 改动前四个 SKILL.md 已备份（台账见 skill-hit-rate/backup/README.md）；
• 改动后必须开新会话才生效——skill 列表在会话开始时注入（依据 18.4 处置约定）；
• 验证须在新会话中进行，长会话中途改 skill 无效。

19.4 影响范围

项	内容
主机	仅本机 Ubuntu 192.168.31.250（~/.trae-cn/ 为用户配置目录）
是否停服	不停服。不触碰 token-proxy 服务、config.yaml、proxy.py
窗口期	无窗口要求。但改动瞬间产生一次前缀失效（后续首个请求全量未命中）
在跑业务	不影响代理转发与报表；若有客户端正在流式对话，仅其缓存命中率受影响，功能不受损
回滚影响	恢复文件后需再开新会话才恢复原匹配行为

19.5 分步操作

本次无独立实现体（由 AI 直接编辑文件），实现即为下列编辑动作本身；代码块用于复核与复现，不承担幂等。

D=/home/rain/.trae-cn
B=/home/rain/Documents/services/token_proxy/skill-hit-rate/backup   # 备份落主题目录，台账见其 README.md

# 1) 备份 4 个待改 skill（高危：覆盖原文件前必须完成）
mkdir -p "$B/home/rain/.trae-cn/skills"
for s in reading-docs-for-context writing-ops-change-sop developing-python-deploy-scripts writing-ops-diagnostic-report; do
  cp -p "$D/skills/$s/SKILL.md" "$B/home/rain/.trae-cn/skills/$s/SKILL.md.bak.20260922-222624"
done

# 2) 改 description：把文件名 / 路径 / 类名等具体触发物写进触发句（逐文件编辑，不做批量替换）
#    reading-docs-for-context         → 补 docs/SOP.md、docs/HANDOFF.md、RUNBOOK.md、INCIDENT-*.md
#    writing-ops-change-sop           → 补「这些文档的新增或修改（含在既有 SOP.md 上追加记录、修订章节、更新头部待办）」，「使用」改「必须使用」
#    developing-python-deploy-scripts → 补 BaseModule 基类、多模块编排、模块级状态检查与跳过逻辑
#    writing-ops-diagnostic-report    → 补报告文件名形态 + 反向边界「只要口头结论、不需成文报告」

# 3) 新增技能加载索引（把「必须加载」固化成显式清单，随规则每轮注入）
#    文件：$D/user_rules/rule-skill-index.md

# 4) 校验 frontmatter 结构（`---` 成对、description 双引号闭合），任一不通过即回滚
grep -c '^---$' "$D"/skills/*/SKILL.md        # 预期各文件均为 2

# 5) 开新会话，按 19.6 跑验证样本

19.6 验证

方式：在新会话中执行下列两个样本，观察是否主动加载对应技能。

#	样本	期望加载
1	让 AI 读 docs/SOP.md 并汇报项目背景与约束	reading-docs-for-context
2	让 AI 在 docs/SOP.md 追加一节执行记录	writing-ops-change-sop

补充观测项：① 样本 1 中，待读量超 800 行时是否派子 agent 而非主上下文通读；② 无关任务是否被反复加载（反向膨胀）；③ skill 列表在会话开始时是否完整。

19.6.1 实测结果（2026-09-22 22:30 起的新会话）

#	是否加载	过程说明
1	命中	reading-docs-for-context 在本会话早前轮次加载；其流程被执行——Glob docs/*.md 限定目录 → 量出 SOP.md 1038 行 → 因超 800 行派子 agent 读取并只回摘要，子 agent 声明未跟进任何引用文件
2	命中	追加本节前加载 writing-ops-change-sop，并按该技能规范（八要素、第 5 章 shell 代码块、备份台账、回滚判据量化）组织本节

偏差说明：本次确为新会话，但 AI 在跑样本前已从 SessionStart 注入的 docs/HANDOFF.md 得知「本次是层 1 验证会话」。因此样本 2 的命中含知情偏差，无法完全区分是 description 命中还是 rule-skill-index.md 映射表驱动。若要取得干净样本，需在不知情的新会话中复测。

19.6.2 复测方案：知情条件下的对称 A/B 对照【待执行】

先纠正一个方向错误（本节初版目标已废弃，留痕备查）：

初版要求"在不知情的新会话中复测"。该目标物理上不可达——docs/HANDOFF.md 每次会话都被 Hook 注入，而它必须回答"下一步做什么"，于是"存在复测待办"这件事本身藏不住。2026-09-22 晚已实测到这一点：新会话在用户只说"你好"时，就主动把「无偏复测与归因」列为第一个待办选项；用户只要顺着走，知情偏差立即重现。

修正后的目标：不追求 AI 不知情，只追求 A/B 两组处于同样的知情条件。

要解决的两个问题：

问题	表现	与修正后方案的关系
知情偏差	AI 在跑样本前已知「这是验证」	接受为常量（不可消除）；两组一致即不破坏对照
归因不清	规则表与 description 措辞已对齐、覆盖同一批任务	靠 A/B 对照解耦：命中究竟由 Rules（🟡）还是 description（🔴）贡献

A/B 如何给结论（判据是行为——UI 上该技能是否被加载，不是 AI 的自述）：

组	条件	观测	结论
A	规则表保留	加载	基准。第四轮已跑，两个样本均命中
B	目标行注释掉	仍加载	description 足以单独驱动该项 → 规则表对应行可删（省每轮注入体积）。但不能排除"知情推了一把"
B	同上	未加载	此前命中由规则表贡献，description 独立贡献为零；Rules 仍有效，层 1 整体不算失败

为什么知情不致命：知情会让 AI 倾向"表现好"，但该倾向在两组里同向、同量，做差即被消掉。真正会毁掉对照的是"AI 知道自己在哪一组"——所以绝不能在指令里暗示"本节规则已被注释"。

实施步骤：

1. 规则文件备份已预置（见 skill-hit-rate/backup/README.md 中 rule-skill-index.md.bak.20260922-223420 一行）；
2. 把目标技能对应的那一行注释掉，保留文件其余部分（不要整文件停用，避免次生现象混淆结果）；
3. 开新会话，让 AI 做该技能对应的任务。无需伪装（不必回避"验证"字样），但同样不得提示"某行已被注释"或"应加载某技能"；
4. 记录观测结果：该技能是否被加载（UI 上直接可见）；
5. 恢复规则文件，再开新会话；
6. 一个会话只测一个技能——同一会话内先测的技能会污染后测的（第四轮样本 1 就吃了这个亏：技能在会话早前已被加载，测不到"首次触发"）。

假阴性风险：判"未加载"前，须先确认该任务在 A 组条件下确实能命中（A 组无记录时先补跑 A 组），否则无法区分"description 不够强"与"任务本身不匹配该技能"。

单次成本量级：改文件 + 一次新会话首条全 miss ≈ 0.03 元（依据见 18.4.1），可忽略。

建议次序（从信息量最大者开始）：

次序	目标技能	任务	A 组数据
1	writing-ops-change-sop	改 docs/SOP.md 追加一节	已有（第四轮样本 2，命中）
2	reading-docs-for-context	读 docs/SOP.md 汇报背景	不干净（第四轮样本 1 早前已加载），需补跑
3	developing-python-deploy-scripts	编一个多主机部署脚本	无，需先跑 A 组

附加收益：任一项在 B 组仍命中，即说明它可只依赖 description——规则表对应行可删除，直接降低规则每轮注入的体积（Rules 每次请求都要重新计费）。

19.6.3 观测记录

次序	技能	A 组（规则表保留）	B 组（对应行删除）	结论
1	writing-ops-change-sop	加载（第四轮样本 2）	仍加载（2026-09-22 晚，新会话执行"在 docs/SOP.md 追加一节"）	description 独立有效，该技能不依赖规则表

本次 B 组的两个局限（不可忽略）：

1. 混淆变量：该任务同时需要读 docs/SOP.md，而 reading-docs-for-context 的规则行仍在表中（且确实被加载）。不排除"已进入加载技能的模式"带来的顺带效应；更纯的 B 组应选一个不涉及读档案的任务。
2. 单次命中 ≠ 稳定命中：skill 触发本身是概率性的（这正是当初增设规则表的理由）。因此不建议据此删除规则表中对应的两行 —— 用一次 🔴 级命中替换 🟡 级兜底不划算，除非能多次复现。

规则文件已于观测后立即恢复（sha256 7a8a5bcb…、22 行）；台账与恢复方式见 skill-hit-rate/backup/README.md。

第 2、3 项不再执行（2026-09-22 用户决定）：不逐一验完四项，改为日常使用中观察，发现漏触发再回来处理。因此 reading-docs-for-context 与 developing-python-deploy-scripts 的触发可靠性仍属未知（前者 A 组数据不干净、后者 A/B 均未跑）。

19.6.4 规则表措辞精简（2026-09-22）

在"是否直接删除规则表"上，结论是精简而非删除（依据见 19.6.3 的两条局限：单次命中不足以替换 🟡 级兜底）。执行内容：

• 删除文件首段的纯背景说明（2 行），压缩表格内的冗余修饰与「边界」条目措辞；5 条映射与强制语气全部保留 —— 触发物关键词是层 1 的核心成果，不动；
• 结果：1386 → 1116 字节（-270，-19.5%），折算约 −90 token/请求；
• 恢复点：skill-hit-rate/backup/home/rain/.trae-cn/user_rules/rule-skill-index.md.bak.20260922-223420（该备份即精简前的完整版本）；
• 收益说明：经济收益很小（按单位成本基线估，月省约 0.6 元）。本项的目的是在不削弱兜底的前提下去掉冗余文字；若目标是显著降本，应走"逐项多次复现 → 有稳定结论再逐行删"的路子。

19.7 回滚

备份位置：skill-hit-rate/backup/docs/SOP.md.bak.20260922-223219（本节记录本身）与 skill-hit-rate/backup/home/rain/.trae-cn/skills/<skill>/SKILL.md.bak.20260922-222624（层 1 的 4 个 skill）；台账见 skill-hit-rate/backup/README.md。

# ① 回滚层 1（restore 4 个 skill 的 description）
D=/home/rain/.trae-cn/skills
B=/home/rain/Documents/services/token_proxy/skill-hit-rate/backup/home/rain/.trae-cn/skills
for s in reading-docs-for-context writing-ops-change-sop developing-python-deploy-scripts writing-ops-diagnostic-report; do
  cp -p "$B/$s/SKILL.md.bak.20260922-222624" "$D/$s/SKILL.md"    # 高危：覆盖当前 description
done
rm -f /home/rain/.trae-cn/user_rules/rule-skill-index.md         # 高危：删除新增规则文件（新文件，无备份）

# ② 回滚本节记录（可选）
cp -p skill-hit-rate/backup/docs/SOP.md.bak.20260922-223219 docs/SOP.md   # 高危：覆盖整个 SOP.md

回滚后必须开新会话才恢复原行为。

回滚触发判据（任一达标即回滚）：同类新会话仍未加载对应技能 / 出现反向膨胀 / frontmatter 解析失败致技能从列表消失。

19.8 风险说明

风险	缓解措施
命中率未改善	判据量化（19.6），达标即回滚；备份与回滚脚本已就位
反向膨胀	索引表只收「必须发生」的情形，并保留反向边界（如「只要口头结论、不需成文报告」）
改 skill 触发前缀失效	不可避免（机理见 18.4.1）；按处置约定改完立即开新会话，可把代价压到约 1/10
规则表与 skill 双重触发导致重复加载	索引表表述与 description 对齐，两者指向同一动作

---

二十、执行记录（2026-09-22）：HANDOFF 生成机制定稿

变更对象不在本工程内：本次改的是 Trae 全局规则文件（~/.trae-cn/user_rules/*.md）与新增技能 ~/.trae-cn/skills/writing-handoff/SKILL.md；同时压缩本工程的 docs/HANDOFF.md 并追加本节。 沿用本 SOP 留档，理由同第十九节：改动 skill / 规则会触发本代理的前缀整段失效，两者在成本上强耦合。

20.1 变更背景

原规则只有一句「变更结束时，若项目存在 docs/HANDOFF.md，必须整体重写更新它」，且挂在 C 类「收尾」段内，由此暴露三个缺口：

#	缺口	表现
1	触发面窄	A 类讨论、B/D 类报告收尾均不触发 → 讨论形成的结论、决策与待办落不到 HANDOFF
2	无「怎么写」	writing-ops-change-sop 只覆盖 SOP / RUNBOOK / INCIDENT 三份，HANDOFF 的章节与压缩标准无归属（原 HANDOFF 5.3 记为待决策）
3	无长度预算	本文件经 SessionStart Hook 全文注入且尾部静默截断（上限未定位），且永久计入每轮固定成本

20.2 变更目标

• 触发面：覆盖三档时点——① C 类变更结束 ② A 类讨论形成结论或决策 ③ B/D 类报告交付收尾；
• 内容边界：讨论内容只进结论、决策与待办，不进过程（过程写 SOP）；
• 写法归属：新增技能 writing-handoff，承载必备五节骨架、内容取舍判据与 12 KB 硬上限；
• 可验证：wc -c docs/HANDOFF.md ≤ 12288。

20.3 前置条件

• 4 个待改文件改前已备份（台账见 handoff-spec/backup/README.md）；
• 规则文件改动每轮即时生效；新增 / 改动的 skill 需开新会话才进技能列表（依据 18.4.1 处置约定）。

20.4 影响范围

项	内容
主机	仅本机 Ubuntu 192.168.31.250（~/.trae-cn/ 为用户配置目录，docs/ 在工程内）
是否停服	不停服。不触碰 token-proxy 服务、config.yaml、proxy.py
窗口期	无窗口要求。改动瞬间产生一次前缀失效（此后首个请求全量未命中）
在跑业务	不影响代理转发与报表；若客户端正在流式对话，仅其缓存命中率受影响，功能不受损

20.5 分步操作

以 shell 代码块表达，供人阅读与手工复现；以实现体为准。本变更的实现体即文件编辑本身，未产出脚本（理由：单机、动作类别 ≤3、无编排）。

# 1) 备份 4 个待改文件（高危：后续将覆盖这些文件，必须先完成备份）
TS=$(date +%Y%m%d-%H%M%S)
D=/home/rain/Documents/services/token_proxy/handoff-spec/backup
mkdir -p "$D/home/rain/.trae-cn/user_rules" "$D/docs"
cp -p /home/rain/.trae-cn/user_rules/rule-ops-scenario-routing.md "$D/home/rain/.trae-cn/user_rules/rule-ops-scenario-routing.md.bak.$TS"
cp -p /home/rain/.trae-cn/user_rules/rule-skill-index.md       "$D/home/rain/.trae-cn/user_rules/rule-skill-index.md.bak.$TS"
cp -p docs/SOP.md     "$D/docs/SOP.md.bak.$TS"
cp -p docs/HANDOFF.md "$D/docs/HANDOFF.md.bak.$TS"

# 2) 新增技能：承载 HANDOFF 的「怎么写」（五节骨架 + 取舍判据 + 12KB 上限）
mkdir -p /home/rain/.trae-cn/skills/writing-handoff
# 写入 SKILL.md：frontmatter 的 description 内嵌具体触发物 docs/HANDOFF.md 与三档时点

# 3) 改规则一：把 HANDOFF 条从 C 类「收尾」段移出，提升为跨类通用的「交接文件」节
#    新文本 = 三档时点 + 「加载 writing-handoff」+ 「讨论只记结论、决策与待办，不记过程」

# 4) 改规则二：技能索引表 5 → 6 条，加一行「重写或更新 docs/HANDOFF.md 交接快照」→ writing-handoff

# 5) 压缩重写 docs/HANDOFF.md（先移入 SOP 再删，不做纯删除）
wc -c docs/HANDOFF.md            # 预期 ≤ 12288

# 6) 追加本节（SOP 第二十节），并把原 HANDOFF 第 2 节的外部件评估结论移交至 20.9

20.6 验证

#	验证项	命令 / 方式	预期
1	规则新节就位	grep -n "交接文件" ~/.trae-cn/user_rules/rule-ops-scenario-routing.md	命中「交接文件」节，三档时点齐全
2	旧挂载已解除	grep -c '必须整体重写更新它' ~/.trae-cn/user_rules/rule-ops-scenario-routing.md	0
3	索引表含新映射	grep -c 'writing-handoff' ~/.trae-cn/user_rules/rule-skill-index.md	1
4	skill 结构完整	grep -c '^---$' ~/.trae-cn/skills/writing-handoff/SKILL.md	2
5	HANDOFF 长度	wc -c docs/HANDOFF.md	≤ 12288
6	触发有效性	新会话中执行「讨论形成结论后更新 HANDOFF」	加载 writing-handoff（概率性，见 20.8）

20.7 回滚

备份位置：handoff-spec/backup/；台账见 handoff-spec/backup/README.md。

B=/home/rain/Documents/services/token_proxy/handoff-spec/backup
TS=20260922-231506

# ① 回滚两处规则（高危：覆盖当前规则文件）
cp -p "$B/home/rain/.trae-cn/user_rules/rule-ops-scenario-routing.md.bak.$TS" /home/rain/.trae-cn/user_rules/rule-ops-scenario-routing.md
cp -p "$B/home/rain/.trae-cn/user_rules/rule-skill-index.md.bak.$TS"         /home/rain/.trae-cn/user_rules/rule-skill-index.md

# ② 回滚 HANDOFF 与本节记录（高危：覆盖整个文件）
cp -p "$B/docs/HANDOFF.md.bak.$TS" docs/HANDOFF.md
cp -p "$B/docs/SOP.md.bak.$TS"     docs/SOP.md

# ③ 撤销新增技能（高危：删除技能目录；路径已核对、无通配）
rm -r /home/rain/.trae-cn/skills/writing-handoff

回滚后必须开新会话才恢复原行为。

回滚触发判据（任一达标即回滚）：

• 新会话中「更新 HANDOFF」类任务仍未加载 writing-handoff，且日常多次复现；
• docs/HANDOFF.md 超过 12288 字节；
• Trae 提示规则文件解析失败，或技能列表中缺失 writing-handoff；
• 出现反向膨胀：无关任务被反复加载该技能。

20.8 风险说明

风险	缓解措施
规则文本写错导致每轮注入异常（影响面最大）	新文本极短、语义单一；改前已备份，回滚即恢复
新技能不被触发（skill 本身是概率性的）	description 内嵌具体触发物（docs/HANDOFF.md + 三档时点），并在规则表加映射作兜底
压缩 HANDOFF 丢信息	只做移交不做删除；5 个外部 skill 的评估结论已移交至 20.9
截断上限仍未定位	本次只做规避（12 KB 预算 + 关键信息前置），定位仍列为待办
改 skill 触发前缀失效	不可避免（机理见 18.4.1）；改完即开新会话，可把代价压到约 1/10

20.9 附录：外部 5 个 skill 的评估结论（自 HANDOFF 移交，2026-09-22 校准）

原记于 docs/HANDOFF.md 第 2 节，因该文件设 12 KB 上限而移交至此留档。

2026-09-22 校准说明：本节经核对原始讨论截图后修订，纠正三处失真—— ① 判定标签的区分度在压缩时被抹平为统一的「借思路」，5 条的落地形态差异消失； ② save-token 的所属生态被记错（详见下表第 2 行）； ③ MemOS 行曾被追加「但更优做法是用 SessionStart Hook 做检索-注入的桥」一句，该表述在 原始讨论与全部档案中均无出处，判定为压缩产物，已删除。 校准依据与过程见第二十一节；原始判定以讨论截图为权威。

#	skill	机制挂在哪一层	判定（原始讨论用语）
1	上下文医生（dsh-context-doctor）	DSH 请求管线 + UI	无需引入——Trae 已内置上下文使用率面板与自动/手动压缩，核心诉求被平台覆盖
2	save-token	DSH 请求管线（请求入口瘦身）	机制可复刻——Hook 加 Skill 约定可复刻压缩策略，但无法改写模型请求体，只能作用于工具输出
3	dsh-context	DSH Web 扩展点	部分可借鉴——面板依赖 DSH Web 扩展点，装不进 Trae；组成归因思路可用 Skill 加脚本自建
4	MemOS	独立 MCP Server	可直接接入——自带 MCP Server，可直接加进 Trae 的 MCP 市场或项目级 MCP，做跨会话记忆
5	Distilly	MCP + 纯 SKILL.md 产物	产物可复用——产物即带版本管理的 SKILL.md，与 Trae 技能目录同构，可手工搬入

关键洞察一（机制分层判据）：5 个里 3 个根本装不进 Trae，1 个能直接接，1 个是「产物能搬、工具不能搬」。 判据不是「好不好用」，而是它的机制挂在哪一层：

• 挂在宿主的请求管线 / UI 扩展点上 → 装不进来；
• 只提供 MCP Server / CLI / 纯 SKILL.md → 能进来。

关键洞察二：那 3 个 dsh 插件装不进来（依赖 dsh 内部扩展点），但不装它们也能复刻它们做的事——用 Trae 原生 Hook。Hook 是「接入层」，这 5 个是「内容 / 能力层」。

20.10 移交：固定注入成本复算脚本（自 HANDOFF 4.5 移交）

原记于 docs/HANDOFF.md 第 4.5 节，随本次压缩移交至此留档。作用：按 conv_key 复算任一会话的轮数与输入 / 未命中量。只读，脚本内部读文件、不输出正文；对应读数见 docs/HANDOFF.md 2.4。

./venv/bin/python - <<'PY'
import json
ck = "2923ea41bf90"                      # 换成目标会话的 conv_key
rows = [r for r in (json.loads(l) for l in open('logs/usage.jsonl'))
        if r.get('conv_key') == ck]
print("轮数", len(rows), "| 首轮", rows[0]['prompt_tokens'], "| 末轮", rows[-1]['prompt_tokens'])
print("累计输入", sum(r['prompt_tokens'] for r in rows),
      "| 未命中", sum(r.get('cache_miss_tokens') or 0 for r in rows))
PY

---

## 二十一、执行记录（2026-09-22）：外部 5 个 skill 判定校准与借鉴杠杆评估

> **变更对象**：本工程 `docs/SOP.md`（20.9 节修订 + 本节追加）与 `docs/HANDOFF.md`（按结论重写）。
> **不触碰** `proxy.py`、`config.yaml` 与 `token-proxy` 服务。

### 21.1 变更背景

起因是追查「5 个外部 skill 的『借思路』事项为何一条都没落地」。追查中暴露两个问题：

| # | 问题 | 表现 |
|---|---|---|
| 1 | 20.9 节与原始讨论失真 | 判定标签被抹平；`save-token` 所属生态记错；`MemOS` 行多出一句无出处的但书 |
| 2 | 「借思路」缺落地判据 | 只知「可以借」，不知「借了值多少」，无法排序，故搁置 |

### 21.2 变更目标

- 20.9 节恢复原始判定的完整信息（判定标签 + 机制分层判据），删除无出处表述；
- 补齐 `save-token` 落地的前置判据：工具结果在 token 流中的量级；
- 给出按**成本杠杆**排序的落地优先级，替代原先按判定标签的排序；
- 可验证：20.9 节含机制分层判据；`MemOS` 行的判定为「可直接接入」且不再附任何但书。

### 21.3 前置条件

- 原始讨论截图（用户提供），作为判定校准的权威依据；
- `logs/usage.jsonl` 可读（4109 条有效记录，2026-09-12 ~ 2026-09-22）；
- 变更前已备份，台账见 `external-skills/backup/README.md`。

### 21.4 影响范围

| 项 | 内容 |
|---|---|
| 主机 | 仅本机 Ubuntu `192.168.31.250` |
| 是否停服 | **不停服**。不触碰服务、`config.yaml`、`proxy.py` |
| 窗口期 | 无窗口要求 |
| 在跑业务 | 不影响代理转发与报表 |
| 附带影响 | `docs/HANDOFF.md` 由 `SessionStart` Hook 每轮注入，其内容变化会使该会话前缀缓存失效一次（机理见 18.4.1） |

### 21.5 分步操作

以实现体为准；本变更的实现体即文件编辑本身，未产出脚本（单机、动作 ≤3、无编排）。

```bash
# 1) 备份（高危：后续将覆盖这些文件，必须先完成）
TS=$(date +%Y%m%d-%H%M%S)
D=external-skills/backup/docs
mkdir -p "$D"
cp -p docs/SOP.md     "$D/SOP.md.bak.$TS"
cp -p docs/HANDOFF.md "$D/HANDOFF.md.bak.$TS"

# 2) 修订 20.9 节：补判定标签与机制分层判据、修正 save-token 生态、删除无出处的 MemOS 但书

# 3) 追加本节（第二十一节），记录校准依据与测量结论

# 4) 重写 docs/HANDOFF.md（加载 writing-handoff）：更新 3.4 / 3.5 待办的优先级
wc -c docs/HANDOFF.md              # 预期 ≤ 12288

21.6 验证

#	验证项	命令	预期
1	MemOS 判定行不再带但书	grep -c '^| 4 | .MemOS.*检索-注入' docs/SOP.md	0（行首锚点避开本节自指）
2	机制分层判据就位	grep -c '机制挂在哪一层' docs/SOP.md	≥1
3	判定标签就位	grep -c '机制可复刻' docs/SOP.md	≥1
4	本节章节齐全	grep -c '^### 21\.' docs/SOP.md	11（八章 + 3 个附录）
5	HANDOFF 长度	wc -c docs/HANDOFF.md	≤ 12288

21.7 回滚

备份位置：external-skills/backup/docs/；台账见 external-skills/backup/README.md。

B=/home/rain/Documents/services/token_proxy/external-skills/backup/docs
TS=20260922-235437

# 高危：覆盖当前文件，将同时撤销 20.9 修订与第二十一节
cp -p "$B/SOP.md.bak.$TS"     docs/SOP.md
cp -p "$B/HANDOFF.md.bak.$TS" docs/HANDOFF.md

回滚触发判据（任一达标即回滚）：

• 20.9 校准结论与原始讨论截图不符；
• 本节测量结论被后续更硬的证据推翻（如请求体采样给出不同量级）。

21.8 风险说明

风险	缓解措施
以截图为准，但截图本身可能不是完整原判	截图为用户提供的原始记录，已注明其权威性；如有更早记录可再校准
测量结论基于间接估算，量级可能偏	在 21.9 明确标注可信度与已废弃口径，并列为待定论项
改 HANDOFF 触发一次前缀失效	不可避免（18.4.1）；本会话内改完，代价限于一次

21.9 附录：save-token 前置测量（结论：现有数据不足以定论）

数据侧事实：logs/usage.jsonl 仅记录计费字段（prompt_tokens / cache_miss_tokens 等）与提问摘要， 不含请求体，无「工具输出」维度，无法直接测量。

尝试一（已废弃）：相邻轮 prompt_tokens 增量口径

残差 = 本轮 prompt_tokens 增量 − 上轮模型可见输出（completion_tokens − reasoning_tokens）。

口径	残差占增量	负增量占比
含思考（completion_tokens 全算）	42.6%	0.7%
扣思考（减去 reasoning_tokens）	76.4%	0.5%

废弃理由：两口径相差 34 个百分点，对「思考是否回传」高度敏感；且实测增量中位 1,725 大于未命中中位 573——新增量不可能多于未命中量，说明增量口径混入了非新增的跳变 （重复内容重新插入位置、上下文重组等）。该口径作废。

采用口径：cache_miss_tokens（上游真实报告）

复用 cost_audit/analyze_usage.py 的输出（前缀稳定配对 4039 组）：

本轮 miss 中位 534，上轮可见输出中位 451 → 残差中位 159，约占新增的 30%

结论：工具结果类内容约占新增上下文的 30%（中等可信度）。 要定论需采样请求体（改 proxy.py，属 C 类变更，本轮未执行）。

21.10 附录：全量成本结构与杠杆重排

全量窗口 2026-09-12 17:56 ~ 2026-09-22 23:45，4372 请求 / 48 会话 / 278 用户轮次， 合计 64.445 元（数据源：cost_audit/analyze_usage.py）。

项	金额	占比
输入·缓存命中	21.867 元	33.9%
输入·未命中	14.674 元	22.8%
输出	27.904 元	43.3%
└ 其中思考	16.237 元	25.2%（占输出 58.1%）

辅证：未命中侧极度集中——miss>10k 仅 141 条（占请求 3.2%），却占未命中的 66.5%、成本 10.807 元。

按「是否已被处理」重排「借思路」事项（2026-09-22 复核后修正，复核依据见 21.11）：

项	占总成本	实际状态
思考 token	25.2%	有意花费——18.3 已决策不省（买质量），不是待办
前缀整段失效	16.8%（当前水位 2~4%）	已解决——18.4.1 已定位 + 处置约定「改 skill / 规则后立即开新会话」，09-20 后已自然收敛
工具结果压缩（save-token 条）	约 10~17%	唯一从未处理过的空项 → 第一优先

判定变更（修正本节初稿的两处排序错误）：

初稿写法	错在哪	修正
「思考 token」列为优先级 1、标待决策	它是 18.3 已决策「不省」的有意花费，把已否决议题重新提上桌	移出待办，标注为「有意花费」
「save-token 条」列为优先级 3	另两项均已封口，它才是唯一空项	提为第一优先

修正后结论：save-token 条为第一优先，但收益上限仅 10~17%，且 Trae 侧只能「提示过滤」、 无法机械改写请求体——三项里干预手段最弱。

21.11 附录：两项既有结论的复核（2026-09-22）

复核缘由：21.10 初稿把「思考 token」排为第一优先，需确认该排法是否成立。复核对象为 18.3 与 18.4。

一、18.3 思考开关决策：不翻案

18.3 的最终决策为 thinking.inject: false（不干预，保持上游默认 high）。三条核心依据：

#	依据	证据
1	关思考只省输出侧，输入侧一分不省	关前关后输入 prompt 中位 188,618 → 199,419（无变化）；输出中位 1,003 → 501（腰斩）
2	DeepSeek 的 disabled 是真关推理	reasoning_tokens 字段整体消失（非置 0），completion_tokens 同步腰斩
3	Trae 本就不把思考回传进上下文	前缀稳定配对 1840 组：假设全回传 → 残差中位 −330（逻辑不成立）；假设不回传 → +154、71% 为正

叠加官方口径（Agent 场景推荐 high，low 用于分类 / 提取类任务）与降档收益不确定， 18.3 的结论是：思考属「买到质量」的钱，能省则省，但这一项不该省。

本轮全量数据独立验证了 18.3 的两个关键数字：

18.3 当时口径	本轮全量实测（见 21.10）	吻合
思考占输出 62%	58.1%	✅
思考占总成本 29%	25.2%	✅

复核结论：依据成立、决策基础未变，不翻案。其成本量级确实居首，但性质是「有意花费」而非浪费， 因此不应列为待办。

二、18.4 前缀失效：已解决，非未做

21.10 初稿把「输入未命中」列为待办不准确。18.4 的完整结论表明它已封口：

• 已定位：触发点为 tools / system 定义被改写（改 skill、改规则、改项目上下文文件）。 对照实验中 2096 组正常请求的 system / tools 变化率为 0.0%，而失效请求中 tools 变占 31.7%；
• 已有处置约定（零质量代价，不改代码与配置）：改动 skill / 规则文件之后立即开新会话， 不要在长会话中途改。量级依据：中途改约 0.37 元/次 vs 改完开新会话约 0.031 元/次，差约 10 倍；
• 已自然收敛：问题集中在 2026-09-19（16 条 / 2.850 元，正是密集编写与讨论 skill 那一天）， 09-20 之后回落至 0.12 ~ 0.27 元/天。

因此 21.10 中的「输入未命中 22.8%」「miss>10k 占 66.5%」是全窗口历史平均， 被 09-19 峰值拉高；当前水位约 2~4%。

三、复核后的净结论

三项里两项已封口（一为有意花费、一为已解决），唯一从未处理过的只剩工具结果压缩。 21.10 的排序据此修正：save-token 条为第一优先，但收益上限仅 10~17%，且干预手段最弱。

复核的可复现性：复核仅读 docs/SOP.md 18.3 / 18.4 与 config.yaml 的 thinking 段， 未执行任何变更命令；引用的数字均可在 21.10 与 18.4.1 中原位查到。

后续（2026-09-22/23）：本节的「唯一空项」已于同日以规则形态落地——见 22.9。 21.10 与本节所称「从未处理过」是落地前的判定，勿再按未处理引用；其收益仍未量化 （量化需采样请求体，属 C 类变更）。

---

二十二、执行记录（2026-09-22/23）：规则层落地「上下文成本约束」

变更对象：Trae 全局规则 ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md（不在本工程内）。 沿用本 SOP 留档，理由同第十九 / 二十节：改动规则会触发本代理的前缀整段失效，两者在成本上强耦合。

22.1 变更背景

21.10 / 21.11 复核后确认，三项「借思路」里两项已封口（思考＝有意花费、前缀失效＝已解决）， 唯一空项是工具结果压缩（save-token 条）。因 Trae 侧 Hook 无法改写模型请求体， PostToolUse 提示型方案存在「提示自身也计费、可能倒亏」的风险，故选择路径 B：规则 / 约定层。

摸底时发现一个关键事实：现行取证约束明确豁免源码——

以下限制只作用于日志与运行输出；项目源码、配置、模板不受限，须完整读取。

而读源码 / 文档正是工具输出的主体。故本次不做新增，而是收紧该句。

22.2 变更目标

• 把「先定位再过滤」的适用范围从「仅日志」扩展至全部读取；
• 用阈值 + 例外条款兜底，避免为省成本而漏读关键上下文；
• 明确标注本条为经验清单、效果未实测，防止被当作已验证结论引用。

22.3 前置条件

• 变更前已备份，台账见 external-skills/backup/README.md；
• 规则文件每轮即时生效，无需新会话（与 skill 不同）。

22.4 影响范围

项	内容
主机	仅本机（~/.trae-cn/user_rules/）
是否停服	不停服。不触碰服务、config.yaml、proxy.py
窗口期	无
前缀影响	规则每轮注入、属 system 侧；改动后下一个请求全量未命中一次（机理见 18.4.1）
成本增量	规则文件 3,348 → 4,433 字节（+1,085）/ 轮固定注入；规则总量 9,866 → 10,951 字节

22.5 分步操作

以实现体为准；实现体即文件编辑本身，未产出脚本（单机、动作 ≤3、无编排）。

# 1) 归置历史散落备份（高危：移动文件。为「移入台账」而非删除，目标目录已先建）
D=external-skills/backup/home/rain/.trae-cn/user_rules
mkdir -p "$D"
mv /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md.bak.20260919-161121 "$D/"
mv /home/rain/.trae-cn/user_rules/rule-ops-scenario-routing.md.bak.20260914-235424 "$D/"

# 2) 备份待改文件（高危：后续将覆盖）
cp -p /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md "$D/rule-ops-evidence-constraints.md.bak.<TS>"

# 3) 改规则文件（4 处，集中在同一轮编辑，使前缀只失效一次）
#    a. description：去掉「Linux 生产运维的」限定，补「含大文件读取与上下文成本」
#    b. 一级标题：`# Linux 生产运维 — 全局约束` → `# 全局约束`
#    c. 取证约束适用范围句：删除「源码不受限，须完整读取」豁免
#    d. 新增一节「上下文成本约束」（大文件阈值 800 行 + 4 条清单 + 3 条通读例外）

# 4) 追加本节记录；重写 docs/HANDOFF.md 至终态（供下一会话）

22.6 验证

#	验证项	命令	预期
1	豁免句已删除	grep -c '源码、配置、模板不受限' ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md	0
2	新节就位	grep -c '^## 上下文成本约束' ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md	1
3	通读例外就位	grep -c '应当通读的例外' ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md	1
4	frontmatter 完整	grep -c '^---$' ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md	2
5	历史备份已归置	ls ~/.trae-cn/user_rules/*.bak* 2>/dev/null \| wc -l	0
6	HANDOFF 长度	wc -c docs/HANDOFF.md	≤ 12288

22.7 回滚

备份位置：external-skills/backup/home/rain/.trae-cn/user_rules/；台账见 external-skills/backup/README.md。

B=/home/rain/Documents/services/token_proxy/external-skills/backup/home/rain/.trae-cn/user_rules

# 高危：覆盖当前规则文件，撤销本次全部 4 处改动
cp -p "$B/rule-ops-evidence-constraints.md.bak.20260923-000708" \
      /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md

回滚触发判据（任一达标即回滚）：

• 规则文件解析失败，或每轮注入出现异常；
• 因「大文件先定位」导致漏读关键上下文、产出错误结论（这是本条的主要风险）；
• 实测显示规则未带来可观测的成本下降。

注（2026-09-23 修订）：上述第三条判据在现有数据下不可判定（21.9 已认定数据不含请求体），实际后果是「永远不会回滚」。已按方案甲替换为人工抽查型代理指标，见 24.9。

22.8 风险说明

风险	缓解措施
为省成本牺牲正确性（主要风险）	阈值只约束「> 800 行」的文件；设 3 条通读例外（全文审阅 / 档案类文档 / 用户明确要求）；未通读时须说明范围与理由
与原豁免条款并存矛盾	原句已同步修订，新节声明「适用于全部读取」，无并存冲突
效果未经实测	新节内已标注「经验清单、效果尚未实测验证」，并指向 21.9 的测量受阻说明
前缀失效一次	不可避免（18.4.1）；4 处改动集中在一轮内完成，使失效只发生一次；按处置约定，本轮结束后开新会话

22.9 附录：本次变更与主线的衔接

本次是「外部 skill 借鉴」主线的收尾动作：save-token 条的落地形态由 Hook 改为规则，理由是 Hook 侧只能追加提示、无法改写请求体，提示自身仍计费（见 21.10 与 HANDOFF 3.4 的两条边界）。 规则层虽同样依赖 AI 遵守，但成本形态是「一次性注入 + 每轮微小固定成本」，优于「每次触发都追加」。

同轮附带完成：把 ~/.trae-cn/user_rules/ 下 2 个散落的历史 .bak（09-14、09-19）移入本次台账目录， 使其符合「备份不散落在被改文件旁」的既有约定。

---

二十三、执行记录（2026-09-23）：核验第二十二节并修正措辞冲突

变更对象：Trae 全局规则 ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md（不在本工程内）。 缘起：用户要求核验上一轮落地的「上下文成本约束」整体是否合理。核验为只读（A 类），完整结论见 23.9。

23.1 变更背景

对 22 节落地结果做整体核验：逐项复现 22.6 的 6 条验证（全部通过），并复核规则文本的内部一致性。 核验共发现 6 项问题（P1~P6），用户决定只修 P1。

P1 内容：第 16 行的「禁止全量读取」是无条件祈使句，与第 14 行「小文件可整体读」、 第 51 行「应当通读的例外」直接冲突。该句在原文只作用于日志时自洽，22 节把适用范围扩到 「全部读取」后未同步限定，两条祈使句相隔 35 行，「禁止」语气更绝对，执行时易取严。

23.2 变更目标

把「禁止全量读取」的适用范围收窄回大文件，并在同一句内显式豁免小文件与通读例外，消除冲突。

23.3 前置条件

• 已备份，台账见 external-skills/backup/README.md；
• 规则文件每轮即时生效、无需新会话；改动会使下一个请求全量未命中一次（机理见 18.4.1）。

23.4 影响范围

项	内容
主机	仅本机（~/.trae-cn/user_rules/）
是否停服	不停服。不触碰服务、config.yaml、proxy.py
窗口期	无
前缀影响	同 22.4：改动后下一个请求全量未命中一次，量级约 0.03 元
成本增量	4,433 → 4,523 字节（+90）/ 轮固定注入；规则总量 10,951 → 11,041 字节

23.5 分步操作

以实现体为准；实现体即文件编辑本身，未产出脚本（单机、动作 ≤3、无编排）。

# 1) 备份待改文件（高危：后续将覆盖）
D=external-skills/backup/home/rain/.trae-cn/user_rules
TS=$(date +%Y%m%d-%H%M%S)
cp -p /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md "$D/rule-ops-evidence-constraints.md.bak.$TS"

# 2) 改规则文件（仅 1 处，第 16 行）
#    旧：先定位再过滤，禁止全量读取：
#    新：先定位再过滤；禁止全量读取大文件（> 800 行，见下节）。小文件与「应当通读的例外」不受此限：

# 3) 台账登记本次备份；追加本节记录；重写 docs/HANDOFF.md 至终态

23.6 验证

#	验证项	预期	实测
1	旧句已消除（grep -c '禁止全量读取：'）	0	0 ✅
2	新句就位（grep -c '禁止全量读取大文件'）	1	1 ✅
3	改动范围 = 1 处（diff <本次备份> <当前>）	仅第 16 行	仅第 16 行 ✅
4	结构未损（^---$ 计数 / ^## 计数）	2 / 6	2 / 6 ✅
5	第 14 / 16 / 51 行并读语义一致	无冲突	一致 ✅

23.7 回滚

备份位置：external-skills/backup/home/rain/.trae-cn/user_rules/；台账见 external-skills/backup/README.md。

B=/home/rain/Documents/services/token_proxy/external-skills/backup/home/rain/.trae-cn/user_rules

# 高危：覆盖当前规则文件，撤销本次措辞修正
cp -p "$B/rule-ops-evidence-constraints.md.bak.20260923-001337" \
      /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md

回滚触发判据：修正后若出现「本应通读的档案被跳读、产出错误结论」，即回滚（同 22.7 第二条）。

23.8 风险说明

风险	缓解措施
措辞收窄后小文件不再受「先定位」约束，单次读取量可能上升	有意为之：正确性优先。大文件阈值（> 800 行）与「不重复读」「列举要设限」「聚合在命令内」三条仍在
前缀失效一次	不可避免（18.4.1）；改完开新会话
同轮顺带删除 22.9 末尾一个未闭合的代码块围栏	该围栏系笔误，会导致其后内容整体落入代码块；删除后本次新增节渲染正常

23.9 附录：核验结论与未修问题（P2~P6）

核验总结：22 节的事实与数字全部可复现（4 处改动、字节数、6 条验证），落点正确； 以下 5 项本次未修，留作待办（同步记入 HANDOFF 3.4）：

编号	问题	性质
P2	22.7 第三条回滚判据「实测显示规则未带来可观测的成本下降」当前不可判定——21.9 已认定数据不含请求体、无法测工具输出维度，测量须改 proxy.py（C 类）	判据缺一条
P3	22 节（规则层落地）与 21 节（skill 判定校准）共用同一 backup/，与「一个主题一个 backup」不完全相符	留档
P4	external-skills/backup/README.md 的「回滚方法」节只覆盖 21.7 两组，未给 22 / 23 节规则备份的回滚命令，且仍写「见 21.7 节」	留档
P5	规则用「文件 > 800 行」，skill reading-docs-for-context 用「待读量 > 800 行」，同数不同义	口径漂移
P6	新节 4 条清单并列，未体现杠杆差异（「不重复读」「聚合在命令内」影响每轮重放，是主要杠杆）	优先级

成本量级复核（粗估，供 22 节参考）：+1,085 字节约合 300~400 token/轮，按缓存命中价折算， 60 轮会话在 1 分钱以内；22.4 的「成本增量」栏只算了固定注入，未计入改规则引发的一次性前缀失效， 本次已在 23.4 补上该口径。

---

二十四、执行记录（2026-09-23）：核验后修订 D1 / P4 / P6 与 P2 判据替换

变更对象：① Trae 全局规则 ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md（不在本工程内）； ② 本工程 docs/SOP.md、docs/HANDOFF.md、external-skills/backup/README.md。 缘起：第二十三节的核验留 5 项未修（P2~P6）。本轮复核时另发现 3 项上轮遗漏（D1~D3）， 用户裁定：执行 D1 + P4 + P6，P2 取方案甲，D2 / D3 只记入待办。

24.1 变更背景

23.9 的 5 项未修 + 本轮新发现的 3 项：

编号	问题	判定
D1（新）	规则第 44 行把「效果未实测」的出处指向 token_proxy 工程 SOP 21.9	全局规则引用具体工程内文档，对其他工程是噪声，且与同句自述重复
D2（新）	HANDOFF 12,089 / 12,288，余量仅 199 B	已顶格，叠加「Hook 注入尾部静默截断」缺陷
D3（新）	「通读例外②」把档案类文档交给概率触发的 skill 承接	成本约束在最重的场景上最弱

用户裁定：D1 / P4 / P6 本轮执行；P2 取方案甲；D2 / D3 只记入待办。

24.2 变更目标

• D1：删除全局规则中的工程内路径引用，压缩为中性表述；
• P6：把「上下文成本约束」4 条清单按杠杆重排（减少每轮重放量的两条前置），并加一行杠杆判据说明；
• P4：台账「回滚方法」节补齐第二十二 ~ 二十四节规则文件的回滚命令；
• P2（方案甲）：把 22.7 第三条不可判定的回滚判据替换为人工抽查型代理指标；
• 目标状态：规则文件自洽、台账可独立完成回滚、每项修订都有可复现的验证命令。

24.3 前置条件

• 变更前已备份 4 个文件，台账见 external-skills/backup/README.md（TS=20260923-002245）；
• 规则文件每轮即时生效、无需新会话（与 skill 不同）；
• 未触碰服务、config.yaml、proxy.py。

24.4 影响范围

项	内容
主机	仅本机（~/.trae-cn/user_rules/ + 本工程）
是否停服	不停服
窗口期	无
前缀影响	改规则会触发一次全量未命中（机理见 18.4.1），量级约 0.03 元
成本增量（实测）	规则 4,523 → 4,580 字节（+57）/ 轮；规则总量 11,041 → 11,098 字节

偏差记录：事前预估 +17 B（删 D1 约 −45、P6 约 +62），实测 +57 B—— P6 新增的杠杆说明句与其前后空行约 +102 B，超出预估。总额仍在预算内（约 20 token/轮）。

24.5 分步操作

以实现体为准；实现体即文件编辑本身，未产出脚本（单机、动作 ≤3、无编排）。

# 1) 备份待改文件（高危：后续将覆盖）
TS=$(date +%Y%m%d-%H%M%S)
B=external-skills/backup
mkdir -p "$B/home/rain/.trae-cn/user_rules" "$B/docs"
cp -p /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md "$B/home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md.bak.$TS"
cp -p docs/SOP.md     "$B/docs/SOP.md.bak.$TS"
cp -p docs/HANDOFF.md "$B/docs/HANDOFF.md.bak.$TS"
cp -p "$B/README.md"  "$B/README.md.bak.$TS"

# 2) 改规则文件（2 处，同轮完成使前缀只失效一次）
#    a. 第 44 行：删「（测量受阻的说明见 `token_proxy` 工程 SOP 21.9）」
#    b. 第 46~49 行：4 条清单重排为 不重复读 → 聚合在命令内 → 大文件先定位 → 列举要设限，并加一行杠杆说明

# 3) 改台账（P3 / P4）：标题与范围声明扩至第二十一 ~ 二十四节；
#    「回滚方法」节拆为「规则文件」「工程文档」两组，共 5 个回滚点

# 4) 追加本节记录（SOP 第二十四节），并在 22.7 原位加一行修订注记（指向 24.9）

# 5) 重写 docs/HANDOFF.md 至终态（加载 writing-handoff）：压缩 2.1 概览表腾出空间，D2 / D3 记入第 3 节

24.6 验证

#	验证项	命令	预期	实测
1	D1 工程内引用已消除	grep -c 'token_proxy' ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md	0	0 ✅
2	P6 清单顺序	grep -n '^- \*\*' <规则文件>（第 48~51 行）	不重复读 → 聚合在命令内 → 大文件先定位 → 列举要设限	一致 ✅
3	杠杆说明就位	grep -c '按杠杆排序' <规则文件>	1	1 ✅
4	台账回滚点齐全	grep -c '回滚点 R2' external-skills/backup/README.md	3（R22 / R23 / R24）	3 ✅
5	规则文件结构未损	grep -c '^---$' / grep -c '^## '	2 / 6	2 / 6 ✅
6	22.7 注记 / 第二十四节就位	grep -c '上述第三条判据在现有数据下不可判定' docs/SOP.md / grep -c '^## 二十四、' docs/SOP.md	1 / 1	1 / 1 ✅
7	HANDOFF 长度	wc -c docs/HANDOFF.md	≤ 12288	11,324 ✅（余量 964 B）
8	规则总量	wc -c ~/.trae-cn/user_rules/*.md \| tail -1	记录实测值	11,098 ✅
9	台账引用的 6 组备份均存在	逐个 ls 校验 TS	全部命中	6/6 ✅

注：验证命令本身含待查字符串时会产生自指污染——初稿用 grep -c '见 24.9' 实测得 3 处 （22.7 注记 1 处 + 本节 24.5 / 24.6 正文 2 处），并非 1 处。故第 6 行改用不含自指的 pattern。 本项目的验证大量依赖 grep 计数，后续写验证项时须避开这一坑。

24.7 回滚

备份位置：external-skills/backup/；台账与 5 个回滚点见 external-skills/backup/README.md。

B=/home/rain/Documents/services/token_proxy/external-skills/backup

# 高危：覆盖当前文件，撤销本次全部修订
TS=20260923-002245
cp -p "$B/home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md.bak.$TS" \
      /home/rain/.trae-cn/user_rules/rule-ops-evidence-constraints.md
cp -p "$B/docs/SOP.md.bak.$TS"     docs/SOP.md
cp -p "$B/docs/HANDOFF.md.bak.$TS" docs/HANDOFF.md
cp -p "$B/README.md.bak.$TS"       "$B/README.md"

回滚后的验证：wc -c 规则文件应回到 4,580 B 之前的值（4,523 B），grep -c 'token_proxy' 应回到 1。

回滚触发判据（任一达标即回滚）：

• 规则文件解析失败，或每轮注入出现异常；
• P6 重排后出现「本应精简的读取反而变多」或「关键上下文被漏读」；
• 台账回滚命令与磁盘实际备份文件不匹配（用 ls 校验缺失即触发）。

24.8 风险说明

风险	缓解措施
规则为全局注入，改动作用于所有工程的每轮输入	改前备份 + 改后校验 frontmatter（^---$ = 2）与节数（^## = 6），两项均已实测通过
重排后可能只被记住前两条、忽略后两条	说明句明确二者作用层不同（每轮重放 vs 单次输出），非替代关系
台账同时被改又登记自身备份	README.md.bak 与 README 同目录，台账内已登记其用途与位置
前缀失效一次	不可避免（18.4.1）；两处规则改动同轮完成，本轮结束后开新会话

24.9 附录：P2 判据替换与 P3 / P5 / D2 / D3 的处置

P2 —— 22.7 第三条判据替换（方案甲）

原判据「实测显示规则未带来可观测的成本下降」在现有数据下不可判定（21.9 已认定数据不含请求体）， 实际后果是「永远不会回滚」。替换为人工抽查型代理指标：

抽查 5 个会话，若出现①同一文件被整段重复读取，或②单次读取 > 800 行且不属三条例外，即判规则未生效，回滚。

该指标零成本、不依赖改 proxy.py，且直接对应规则要约束的行为。22.7 原位已加注记指向本小节。

P3 —— 不拆目录，改范围声明：21 / 22 / 23 / 24 节是同一主线的连续动作，规则文件版本链强耦合， 拆目录会导致回滚时找不到对应备份。故保留本目录，改标题与范围声明明确其覆盖范围（见 24.5 步骤 3）。

P5 —— 本轮未改：规则「文件 > 800 行」触发「先定位」，skill reading-docs-for-context 的 「待读量 > 800 行」触发「先出标题树问用户」——二者职能不同、并非同一判据，但同值不同义易混。 留待下次触碰该 skill 时加限定语，本轮不动。

D2 / D3 —— 只记待办，本轮不动：

• D2：HANDOFF 已在本轮重写中压缩（2.1 概览表由 9 行压为 3 行），腾出余量；上限截断问题仍待定位；
• D3：档案类文档的成本约束依赖 reading-docs-for-context 触发，欠确定性，与 HANDOFF 3.5 的层 2 方案同源，合并跟踪。

两项均已记入 docs/HANDOFF.md 第 3 节。

后续：D3 已于同日落地，见第二十五节。

二十五、执行记录（2026-09-23）：PreToolUse Hook 落地「层 2」——读档案前注入成本约束

25.1 变更背景

第二十二节把「上下文成本约束」落到规则层（每轮注入、靠模型自觉 = 🟡），但其中「读档案类文档前先加载 reading-docs-for-context」这一条，仍依赖概率触发的 skill（🔴）。24.9 的 D3 已把它列为遗留， 判据是第一性原理：「必然发生的事」不能托付给 LLM 自觉，须迁到 Hook（✅）。

HANDOFF 3.4 把「层 2」写成待决策方案：PreToolUse Hook，在读取 docs/*.md 前强制注入提示。

本轮开工时发现层 2 已部分动手：hooks.json 里已有 PreToolUse 探针（matcher="*" → probe-log.sh）， 其使命是确认本机 Trae 实际传出的字段名，不含业务逻辑。本轮把探针换成正式实现。

25.2 变更目标

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

1. 发生 Read 且路径命中 docs/*.md 时，必定向模型上下文注入一段成本约束提示；
2. 绝不阻断工具调用——任何异常路径都以退出码 0 结束；
3. 同一 (session_id, agent_id) 只注入一次，避免重复占用上下文；
4. 提示文本 ≤ 120 字（它进入上下文后每轮重放，写长了与「省 token」自相矛盾）；
5. 脚本缺失或不可执行时，对任何工作区零影响。

25.3 前置条件

项	状态
~/.trae-cn/hooks.json 可写	✅
python3 可用	✅ 3.12.3。venv/bin/python3 实为 /usr/bin/python3 软链，零依赖脚本无需绑 venv
字段名有实测依据	✅ 探针 12 条事件，见 25.9-A
官方文档确认 stdout 可注上下文	✅ hookSpecificOutput.additionalContext
全局 Hook 三道闸门	✅ 已开（HANDOFF 2.3）

25.4 影响范围

项	内容
主机	本机 192.168.31.250（用户 rain）
组件	Trae 全局 Hook（对本机所有工作区的 Read 生效）；脚本置于 token_proxy 工程内
是否停服	否。不触碰 token-proxy 服务，不占 8788 端口
窗口期	无。Hook 改动不产生中断，重启 Trae 后生效
在跑作业	无关联，不涉及任何调度节点

唯一持续成本：注入文本计入模型上下文并每轮重放。会话内去重与 120 字上限即为压制它而设。

25.5 分步操作

实现体：docs-read-hook/docs-read-guard.py（以实现体为准，下列序列供阅读与手工复现）

D=/home/rain/Documents/services/token_proxy/docs-read-hook
B=$D/backup/home/rain/.trae-cn

# 1) 备份全局 Hook 配置（高危：下一步将覆盖它，必须先完成）
cp -p /home/rain/.trae-cn/hooks.json "$B/hooks.json.bak.$(date +%Y%m%d-%H%M%S)"

# 2) 写入正式脚本（幂等：内容一致即零变更）
#    命中 docs/*.md 的 Read → 输出 allow + additionalContext；其余静默 exit 0
#    见实现体 docs-read-guard.py

# 3) 改写 hooks.json：matcher 由 "*" 收窄为 "Read"，command 指向新脚本
#    命令自带 [ -f ] 悬空守卫与 `|| true; exit 0` 兜底，脚本缺失也不阻断
#    （高危：覆盖全局配置，务必先完成步骤 1）

# 4) 重启 Trae 使配置生效（实测运行期不重载，见 25.9-C）

# 5) 追加本节记录，重写 docs/HANDOFF.md（加载 writing-handoff）

25.6 验证

#	验证项	方法	预期	实测
1	命中注入且 JSON 合法	喂 Read+docs/SOP.md 事件	输出 allow + additionalContext	✅ 119 字
2	同会话去重	同 session 再喂 docs/HANDOFF.md	无输出	✅
3	非目标路径不注入	喂 Read+src/main.py	无输出	✅
4	非 Read 工具不注入	喂 Bash 事件	无输出	✅
5	坏 JSON 不阻断	喂 not-json{{	无输出、exit 0	✅
6	缺字段不阻断	喂 tool_input={}	无输出、exit 0	✅
7	跨 agent 各注入一次	同 session 换 agent_id	有输出	✅
8	配置合法性	json.load + 断言 matcher=="Read"	通过	✅
9	端到端（原样 command）	bash -c "$CMD" 喂事件	合法 JSON、exit 0	✅
10	悬空守卫	命令中脚本路径指向不存在文件	exit 0	✅
11	幂等复跑	重新生成 hooks.json 逐字节比对；同事件两次取哈希	零变更	✅ 0ce2b67a… / 脚本产出 dfd2526e… 两次一致
12	真机注入	重启 Trae 后读 docs/*.md	模型收到提示，且 state/ 落状态文件	✅ 已注入，去重亦通过

第 12 项已于同日闭环，全部 12 项通过。证据链：① 重启后另一会话的子 agent 读 docs/*.md， 生成 state/6ab2b170…__search，证明 Hook 被执行；② 本会话读 docs/HANDOFF.md 时，模型上下文中 实际出现 <hooks_context event_phase="pre_tool_use"> 包裹的 <additional_context>，注入可见； ③ 紧接着再读 docs/SOP.md，该块不再出现，去重生效；④ state/ 相应出现 6ab2ad4e…__solo_agent。

25.7 回滚

备份与台账：docs-read-hook/backup/README.md（2 个回滚点）

B=/home/rain/Documents/services/token_proxy/docs-read-hook/backup/home/rain/.trae-cn

# 高危：覆盖当前全局 Hook 配置
cp -p "$B/hooks.json.bak.20260923-002751" /home/rain/.trae-cn/hooks.json   # 回滚点 A：回到「无 PreToolUse」
cp -p "$B/hooks.json.bak.20260923-003753" /home/rain/.trae-cn/hooks.json   # 回滚点 B：回到「探针版」

回滚后同样需重启 Trae 才生效。

回滚触发判据（任一达标即回滚，不靠临场判断）：

1. 出现任何一次工具调用被阻断（Read 报错，或其它工具被 deny）；
2. 注入后「档案反复整段重读」反而恶化，或提示被判定为噪音；
3. 单会话固定注入成本显著上升（基线：首轮约 30k，见 HANDOFF 2.4）。

25.8 风险说明

风险	缓解措施
Hook 误判阻断工具调用（最严重）	所有异常路径 exit 0；命令串带 || true; exit 0；25.6 第 5/6/9/10 项已实测
全局生效，波及其它工程	仅命中 docs/*.md 的 Read，其余静默；脚本缺失时守卫跳过
注入文本每轮重放，反成新成本	文本压到 119 字 + 会话内去重，双重压制
工程被删导致全局 Hook 悬空	[ -f "$s" ] 守卫，实测不可达时 exit 0
主 / 子 agent 重复注入	去重键取 session_id+agent_id，二者各一次
前缀失效一次	不可避免（18.4.1）；本变更后开新会话

25.9 附录：机制事实、字段证据与未验证项

A. 字段证据（探针 12 条真实事件）

{"session_id":"...","cwd":"...","hook_event_name":"PreToolUse","workspace_roots":["..."],
 "agent_id":"solo_agent","agent_type":"solo_agent","tool_use_id":"call_...",
 "tool_name":"Read","llm_tool_name":"Read",
 "tool_input":{"file_path":".../docs/SOP.md","limit":500,"offset":1}}

关键结论：路径字段是 tool_input.file_path；matcher 只能匹配工具名，不能匹配路径， 故「是否命中 docs/*.md」的判断必须在脚本内完成——这是探针最直接的产出。

B. PreToolUse 的 stdout 语义（官方文档）

{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow",
 "permissionDecisionReason":"...","updatedInput":{},"additionalContext":"附加给模型的上下文"}}

本变更只用 permissionDecision=allow + additionalContext，不用 deny——deny 会阻断读取， 与「读到文档并附带提示」的目标相悖。另注：退出码 2 等价于 deny，故脚本严禁以 2 退出。

C. 实测发现：Trae 运行期不重载 hooks.json

• 00:37:53 改写配置（matcher 由 * 收窄为 Read，command 指向新脚本）；
• 00:38:08 探针仍记录到一条 RunCommand 事件——若新配置已加载，RunCommand 不匹配 matcher="Read"，且探针已不再被引用，不该再产生新条目；
• 故旧配置仍在生效，须重启 Trae。

补充观测：重启后探针在 00:40:21 之后不再产生任何新条目（RunCommand 已不触发 Hook）， 新配置接管，反向佐证了上述判断。

这条为 HANDOFF 2.3 坑③（原文只说「IDE 运行期改配置需重启」）补上了可复现证据。

D. 已验证与未验证项

1. ✅ 已验证：additionalContext 确实注入模型上下文。实测在工具结果前出现 <hooks_context event_phase="pre_tool_use"><additional_context>…</additional_context></hooks_context>； 同一 (session_id, agent_id) 再次读取 docs/*.md 时该块不再出现，去重生效；
2. ✅ 已验证（2026-09-23，见第二十九节）：子 agent 的 additionalContext 确实注入其独立上下文； 此前仅观测到子 agent 触发脚本（state/…__search），未直接读取其上下文；
3. ⏳ 未量化：收益——与第二十二节同理，量化需采样请求体（C 类）；本次提升的是投递必然性， 上限受限于「模型是否遵守」。

E. 层 2 的定位（避免过度宣称）

本 Hook 把规范投递从 🔴 概率提到 ✅ 必然，但「模型是否遵守」仍是 🟡。它强于留在 skill 里， 但不等于强制生效——25.7 的触发判据 2 就是为此保留的观察口。

---

二十六、执行记录（2026-09-23）：T3 结项与积压待办清理

本次不改变系统状态，只改文档：docs/SOP.md、docs/HANDOFF.md、skill writing-handoff。 沿用 C 类留档，因为交付物发生了变更。

26.1 变更背景

T3（09-15 的 24 条缺 usage）自 09-15 挂起，18.5 记的下一步是「临时增采响应体摘要（C 类）」， 因需改 proxy.py 而长期未动。2026-09-23 用户提出三个问题并要求裁定：① HANDOFF 注入截断能否定位 （不能则删除该待办）；② T3 过这么多天可否查；③ 改 proxy.py 的影响评估（因其本人正在使用该代理）。

26.2 变更目标

• T3 结项：用现有数据给出可复现的定性结论，从待办清单移除；
• 截断待办删除：「12KB 上限用于规避注入截断」的理由移交 skill writing-handoff，避免上限失去出处；
• 改 proxy.py 的影响评估归档，作为独立待办保留（用户裁定「最后做」）。

26.3 前置条件

• 三个待改文件已备份，台账见 backlog-cleanup/backup/README.md；
• 取证均为只读。数据源：logs/usage.jsonl（4594 条，覆盖 09-12 17:56 ~ 09-23 00:58）、 logs/proxy.log（4621 行，覆盖 09-12 ~ 09-23）；
• logs/req_shape.jsonl 起始于 09-16 15:12，不覆盖 09-15，故响应结构指纹对 T3 不可用—— 这是本次只能「定性」而不能「确证响应体内容」的直接原因。

26.4 影响范围

• 主机：192.168.31.250 单机；不停服、无窗口期——不改 proxy.py / config.yaml，不重启代理；
• 影响面仅限文档：SOP 追加一节、HANDOFF 整体重写、全局 skill 改 1 处；
• 改 skill 会使下一个请求前缀全量未命中一次（机理见 18.4.1）；改完开新会话可把代价压到约 1/10。

26.5 分步操作

D=backlog-cleanup                       # 本次交付物目录
# 1) 建目录并按「原路径层次」备份三个待改文件（高危：后续将覆盖，必须先备份）
mkdir -p "$D/backup/home/rain/Documents/services/token_proxy/docs"
mkdir -p "$D/backup/home/rain/.trae-cn/skills/writing-handoff"
cp -p docs/SOP.md     "$D/backup/home/rain/Documents/services/token_proxy/docs/SOP.md.bak.<时间戳>"
cp -p docs/HANDOFF.md "$D/backup/home/rain/Documents/services/token_proxy/docs/HANDOFF.md.bak.<时间戳>"
cp -p /home/rain/.trae-cn/skills/writing-handoff/SKILL.md \
      "$D/backup/home/rain/.trae-cn/skills/writing-handoff/SKILL.md.bak.<时间戳>"
# 2) 追加本节（SOP 第二十六节）
# 3) 改 skill `writing-handoff` 的「为什么有预算」段：去掉「上限尚未定位」的未决语气，
#    改为「历史偶发一次、已判定不值得定位并结项」，保留 12KB 上限的出处
# 4) 重写 docs/HANDOFF.md（加载 skill `writing-handoff`）：
#    删 3.3 截断待办、T3 自 3.5 移除并计入已结案、新增「改 proxy.py」待办
# 5) 登记 backup/README.md；校验 wc -c docs/HANDOFF.md ≤ 12288

以本文叙述为准；命令供阅读与手工复现，未交付独立脚本。

26.6 验证

wc -c docs/HANDOFF.md            # 预期 ≤ 12288
grep -c "截断上限仍未定位" docs/HANDOFF.md    # 预期 0（待办已删）
grep -n "T3" docs/HANDOFF.md                  # 预期只出现在「已结案」处
grep -n "为什么有预算" /home/rain/.trae-cn/skills/writing-handoff/SKILL.md
                                              # 预期命中，且不含「上限尚未定位」

执行结果（2026-09-23 01:04）：四项全部通过，且复跑零变更——

检查项	实测	判据
wc -c docs/HANDOFF.md	10,532 B	≤ 12288 ✅（余量 1,756 B）
「截断上限仍未定位」残留	0	待办已删 ✅
T3 出现位置	仅「已结案」与文档地图指引处	✅
skill 第 69 行「为什么有预算」	已不含「上限尚未定位」，并写明 12KB 上限的由来	✅

文件指纹：HANDOFF.md = 0c5bd7d0…、writing-handoff/SKILL.md = fe90ceff… （SOP 自身指纹不登记——本节写入后即变化，属自指）。 复跑校验命令，HANDOFF.md 仍为 10,532 B，零变更；SOP 增补后共 2,297 行。

26.7 回滚

备份与台账：backlog-cleanup/backup/README.md

B=/home/rain/Documents/services/token_proxy/backlog-cleanup/backup
T=<时间戳，见台账>

# 高危：覆盖当前文件
cp -p "$B/home/rain/Documents/services/token_proxy/docs/SOP.md.bak.$T"     docs/SOP.md
cp -p "$B/home/rain/Documents/services/token_proxy/docs/HANDOFF.md.bak.$T" docs/HANDOFF.md
cp -p "$B/home/rain/.trae-cn/skills/writing-handoff/SKILL.md.bak.$T" \
      /home/rain/.trae-cn/skills/writing-handoff/SKILL.md

回滚后 HANDOFF 于下一会话生效；skill 需新会话生效。

回滚触发判据（任一达标即回滚）：

1. wc -c docs/HANDOFF.md > 12288；
2. HANDOFF 五节骨架缺失或事实档位标注错误；
3. 删除截断待办后，12KB 上限的由来在 HANDOFF 与 skill 中同时消失。

26.8 风险说明

风险	缓解措施
覆盖 HANDOFF 丢失现行信息	先备份；重写遵循「只做移交不做删除」，已结案项在 3.1 保留一行指引
改 skill 触发前缀失效	不可避免（18.4.1）；改完开新会话
结项过早，日后同类事件无据可查	判据与证据留在 26.9；再遇「usage=null 且 bytes 固定」按 A.5 即可快速识别
删待办后 12KB 上限失去依据	由来写入 skill writing-handoff（见 26.5 步骤 3）

26.9 附录 A：T3 结项的证据与结论

A.1 决定性证据（同一 conv_key = 77c5170131d1，同一句 prompt）

时间	响应体	usage	备注
09-15 02:30:04	576,261 B	正常	42 秒内连发 5 次
09-15 02:30:17	270,080 B	正常
09-15 02:30:27	373,430 B	正常
09-15 02:30:38	445,887 B	正常
09-15 02:30:46	424,991 B	正常
09-15 02:46:40	1,190 B	null	16 分钟后，同样的话

A.2 四条硬事实

1. bytes==1190 在 09-15 全天正好 24 条，且全部缺 usage——1190 B 是异常响应的专属指纹， 无一条正常响应为该长度；
2. 同一句话在 02:30 尚能返回 576 KB 正常响应 → 与请求内容无关，属上游侧状态；
3. 24 条仅落在 4 个 conv_key，prompt 在「你好 / 刚卡住 了 / 还能继续对话不 / 还没恢复吗」之间 近乎逐字重复，三组间隔约 15 分钟 → 客户端自动重试（用户 prompt 原文自证「我在你的另一个窗口卡住 了」）；
4. 09-16 至今零复现（全库 33 条缺 usage = 09-12 的 9 条已知问题 + 09-15 这 24 条）。

A.3 结论

09-15 02:46–04:21，上游在短暂故障窗口内对流式请求返回了 HTTP 200 + 固定错误响应体（1190 B，不含 usage）。 代理记账行为正确——上游未给 usage 即记 null，属忠实记录而非缺陷；客户端无法识别此类错误流， 表现为「卡住」，触发自动重试共 24 次。金额影响可忽略（24 × 1190 B ≈ 28 KB，不足 0.01 元）。

A.4 为何不再追根因

确证响应体内容须落盘响应体摘要，而这需要改 proxy.py——正撞上 26.10 的自举困境与脱敏约束， 且事件已不复现、金额可忽略。投入与收益不成比例，故结项。

A.5 保留的观测口

若再出现 usage=null，先看 bytes 是否为固定值：固定值 = 同类上游错误响应； 长度各异 = 回到 18.5 的原始假设，届时再议。

26.10 附录 B：改 proxy.py 的影响评估

使用者本人的模型流量全部经由该代理（本次会话在 usage.jsonl 中的最后一条记录即为用户提问本身）， 故改动具有自伤性。三重代价：

#	代价	说明
1	重启即断流	改后必须 systemctl --user restart token-proxy，会打断所有在途流式回答，含使用者正在进行的会话。是必然结果，非概率风险
2	自举困境	验证的常规手段是「发请求试试」，而请求路径正是被改对象——改坏了连自测都做不到。故验证必须离线（/tmp 假上游 + 临时端口，见 17.2），不得在 8788 上试改动的代码
3	脱敏约束	响应体摘要的正文即对话内容，与既有原则「只记哈希、不落内容」（req_shape.jsonl 的做法）冲突。若确要采，只能记长度 + 哈希 + 特征前缀

改动面（以 T3 所需的「响应体摘要」为例）：位置在 proxy.py 的 _forward 尾部（usage is None 处）， 属新增分支，主转发路径不动；须以 try/except 包裹，异常不得影响转发与记账。

结论：改动本身难度低，但触发条件苛刻，优先级定为最后；结合 A.4，很可能永远不需要实施。

---

二十七、执行记录（2026-09-23）：缺 usage 时的响应摘要（改 proxy.py）

27.1 变更背景

26.10 对「改 proxy.py」做过影响评估（难度低、代价三重、优先级最后）。本次由使用者裁定直接实施， 目的是补上 T3 暴露的最后一处盲区：上游未返回 usage 时，事后无法判断当时上游回了什么—— 只能看到 usage: null 与字节数。26.9 的 T3 结项依赖了「固定 1190 B」这一巧合，同类事件再发生则无从下手。

27.2 变更目标

1. 上游未返回 usage 时，额外落一条响应摘要：长度（bytes）+ 捕获缓冲 sha256（16 位短哈希）+ Content-Type；
2. 仅当响应为非流式且非 2xx（典型是错误响应）时，额外记 120 字节可打印 ASCII 前缀，用于辨认错误类型；
3. 流式响应与 2xx 响应的正文绝不落盘（正文即对话内容）；
4. usage.jsonl 结构不变；摘要记录失败不得影响转发与主记账。

27.3 前置条件

• 工程内 venv：./venv/bin/python（3.12，含 PyYAML），不使用系统 Python
• 离线验证能力：/tmp 假上游 + 临时端口；禁止在 8788 上试改动的代码（自举困境见 26.10）
• 改前备份：resp-digest/backup/（台账见 resp-digest/backup/README.md）
• 执行前检查：systemctl --user is-active token-proxy；确认无关键在途请求（重启必断流）

27.4 影响范围

项	值
主机	192.168.31.250（单机，无冗余）
服务	systemd 用户服务 token-proxy，监听 0.0.0.0:8788
是否需停服	需重启：必然打断所有在途流式回答（含使用者当前会话），实测恢复 ≈ 3 s
窗口期	夜间（本次 01:09）执行，无批量作业在跑
改动文件	proxy.py（新增常量 / 类属性 / _relay 分支 / 新方法）、config.yaml（新增 logging.resp_file）
新增数据	logs/resp_digest.jsonl（append-only 诊断数据，可随时删除重建，不参与报表）

27.5 分步操作

实现体为 proxy.py 本体改动 + resp-digest/offline-verify/verify_resp_digest.py（离线验证脚本）。 下方代码块供人阅读与手工复现，以实现体为准。

cd /home/rain/Documents/services/token_proxy

# 1) 备份（改前必做，失败可回原点）
mkdir -p resp-digest/backup/docs
cp -p proxy.py "resp-digest/backup/proxy.py.bak.$(date +%Y%m%d-%H%M%S)"
cp -p config.yaml "resp-digest/backup/config.yaml.bak.$(date +%Y%m%d-%H%M%S)"
cp -p docs/HANDOFF.md "resp-digest/backup/docs/HANDOFF.md.bak.$(date +%Y%m%d-%H%M%S)"

# 2) 改 proxy.py（实现体，本次四处改动）：
#    RESP_HEAD_BYTES 常量 / resp_recorder 类属性 / _relay 尾部「usage is None」分支
#    / 新方法 _record_missing_usage / main() 建 recorder 并写入启动日志

# 3) 改 config.yaml：logging 段新增 resp_file: logs/resp_digest.jsonl（留空即关闭）   # 高危：覆盖配置

# 4) 语法检查 + 离线验证（假上游 + 临时端口，绝不碰 8788）
./venv/bin/python -m py_compile proxy.py
./venv/bin/python resp-digest/offline-verify/verify_resp_digest.py   # 预期：16 项全通过，退出码 0

# 5) 重启生效（高危：打断在途流式回答）
systemctl --user restart token-proxy
sleep 3 && systemctl --user is-active token-proxy                    # 预期：active

# 6) 线上验证（无 KEY 请求必然 401，正属「缺 usage」场景）
curl -sS -o /dev/null -w 'status=%{http_code}\n' -X POST http://127.0.0.1:8788/ds/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'
tail -n 1 logs/resp_digest.jsonl                                     # 预期：新增 status=401 + head 前缀

27.6 验证

验证项	命令/方法	结果
离线·转发不变	三类响应（带 usage 的 SSE / 无 usage 的 SSE / 400 JSON）与假上游逐字节比对	3/3 原样转发
离线·摘要写入	断言摘要文件恰好 2 条（带 usage 不写、缺 usage 写）	通过
离线·脱敏	断言流式 head 为空、错误响应 head 为可打印前缀	通过
离线·主记账未变形	断言 3 条记账、缺 usage 者仍为 usage: null	通过
离线·整体	verify_resp_digest.py 连跑两轮	16/16 通过，两轮一致
线上·服务	systemctl --user is-active + GET /healthz	active / 200
线上·启动日志	tail -n 1 logs/proxy.log	含 响应摘要=/home/.../logs/resp_digest.jsonl
线上·空 usage 分支	无 KEY 请求 → 401	摘要记 status=401 / bytes=31 / sha256=271d3544c88440f7 / head="Authentication Fails (governor)"
幂等复跑	再次 restart 并比对摘要文件行数	重启前后均 1 行、启动日志一致、无额外写入

27.7 回滚

cd /home/rain/Documents/services/token_proxy
# 高危：覆盖当前文件；执行前先确认备份文件存在
cp -p resp-digest/backup/proxy.py.bak.<TS> proxy.py
cp -p resp-digest/backup/config.yaml.bak.<TS> config.yaml
systemctl --user restart token-proxy        # 高危：打断在途流式回答
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8788/healthz    # 预期 200

备份清单与台账：resp-digest/backup/README.md。 logs/resp_digest.jsonl 为新增诊断数据，回滚后可直接删除（不影响记账与报表）。

27.8 风险说明

风险	缓解
重启打断在途流式回答	必然发生、无法规避；选无批量任务时段执行；实测恢复 ≈ 3 s
自举困境（改坏无法自测）	上生产前先离线验证（假上游 + 临时端口），通过才动手
摘要误落对话正文	代码级约束：流式一律 head=""，仅「非流式且非 2xx」取 120 字节前缀；离线用例逐条断言
摘要写入异常影响记账	_record_missing_usage 整体 try/except（失败仅告警）；主记账 _record 先于摘要执行
磁盘增长	仅在缺 usage 时写一行；如需关闭，把 config.yaml 的 resp_file 留空并重启

27.9 附录：交付物与自测噪声

• 交付物目录 resp-digest/：backup/（3 个回滚点 + 台账）、offline-verify/verify_resp_digest.py
• 临时取证目录：/tmp/resp-digest-verify-*（两轮验证各一个，保留供查，可随时删）
• 自测噪声：线上验证产生 1 条 401 记录（usage.jsonl 01:09:26，usage: null、0 token、金额 0）， 与 resp_digest.jsonl 同时刻那条对应。前者是真实发生的请求，予以保留（数据不可再生，不做删除）。 副作用：该记录的 model=deepseek-chat 不在价目表内，cost_report.py --dry-run 会多一条 以下模型缺少价目，未计入成本: deepseek-chat 告警（0 token，不影响金额与对账）。
• 与 26.10 的关系：26.10 判定「很可能永远不需要实施」，本次为使用者裁定执行；T3 已结项（26.9）， 本次价值在于——同类事件若再发生，不必再依赖字节数巧合。

27.10 追加变更（同日 01:11）：价目表别名增补

• 背景：27.9 的自测记录 model=deepseek-chat 触发报表缺价告警，每次运行都会输出，使用者裁定消除。
• 改动：config.yaml 的 pricing.aliases 新增 deepseek-chat: deepseek-v4-flash （DeepSeek 官方旧模型名，与 deepseek-v4-flash 同价档）。
• 影响面：pricing 段仅被 cost_report.py 读取，代理不受影响、无需重启（不产生断流）。
• 验证：./venv/bin/python cost_report.py --dry-run → 缺价告警消失、退出码 0； 对账数字与改动前一致（真实扣费 8.42 vs 自算 8.469961，偏差 -0.04996 未变）； 该记录仍计入「空响应」，不计费、不计次。
• 回滚：cp -p resp-digest/backup/config.yaml.bak.20260923-011147 config.yaml（无需重启）。
• 备份：resp-digest/backup/config.yaml.bak.20260923-011147，台账见 resp-digest/backup/README.md。
• 未采用：删除该条测试记录——与「usage.jsonl 不可再生、绝不可删」原则冲突。

---

二十八、执行记录（2026-09-23）：HANDOFF 瘦身与 skill 上限收紧（12KB→8KB）

28.1 变更背景

使用者提出两项成本关切，均为本轮实测得出：

1. 整体重写 HANDOFF 是纯输出（4.0 元/百万，是命中输入价的 200 倍），12 KB 一次约 4k token ≈ 0.016 元；
2. 新会话首次注入 HANDOFF 走未命中输入价（1.0 元/百万，是命中价的 50 倍），其后再逐轮按命中价重放。

核对时又发现：文件 12,028 B 中约 4.5 KB 属 skill writing-handoff 自己规定的禁入内容 （轮次概览 617 B、已结案正文 1,355 B、机制分档 437 B、Hook 实现细节 1,380 B、文档地图冗余 600 B 等） ——即文件违反了自己的规矩，这是比成本更值得修的理由。

28.2 变更目标

1. skill writing-handoff：硬上限 12 KB → 8 KB（目标 7 KB）；
2. 新增「按状态增量分档」判据（整体重写 / 定点修订 / 强制整体重写）与禁入清单，骨架第 2 项明确「不写轮次历史」；
3. docs/HANDOFF.md 按新标准重写至 ≤ 8 KB，且不丢信息（砍掉的内容逐条核对已在 SOP 归档）。

28.3 前置条件

• 备份 skill 与 HANDOFF 到 handoff-slim/backup/（台账见该目录 README.md）
• 压缩前先核对归档：待移出内容必须在 SOP 有对应节（用 grep 验；本次核到机制分档在 SOP 机制节、Hook 实测细节在层 2 两节）
• 改 skill 后须开新会话才对新会话生效（本会话内不生效）

28.4 影响范围

项	说明
系统状态	不变：不碰代理、不重启、无断流、不涉及数据文件
影响对象	① ~/.trae-cn/skills/writing-handoff/SKILL.md（全局，影响此后所有会话的 HANDOFF 写法）② docs/HANDOFF.md（每轮注入内容变小）
生效时机	skill 改动下个新会话生效；HANDOFF 改动下次驱动即注入
风险面	压缩若丢关键信息 → 已逐条核对；上限过低 → 触发更频繁的「强制整体重写」

28.5 分步操作

本次无脚本实现体，改动即 skill 与文档的直接编辑；下方供复现与人工核对。

cd /home/rain/Documents/services/token_proxy

# 1) 备份（skill 在 ~/.trae-cn/skills/ 下，不在工程内）
mkdir -p handoff-slim/backup/docs handoff-slim/backup/skill-writing-handoff
cp -p docs/HANDOFF.md "handoff-slim/backup/docs/HANDOFF.md.bak.$(date +%Y%m%d-%H%M%S)"
cp -p ~/.trae-cn/skills/writing-handoff/SKILL.md \
      "handoff-slim/backup/skill-writing-handoff/SKILL.md.bak.$(date +%Y%m%d-%H%M%S)"

# 2) 核对归档：被移出的内容必须在 SOP 里（只读）                        # 危险：无
grep -n "托付给 skill\|三道闸门\|additionalContext" docs/SOP.md

# 3) 改 skill：上限 8 KB + 分档判据表 + 禁入清单 + 骨架第 2 项           # 高危：覆盖全局 skill 文件
# 4) 按新标准重写 docs/HANDOFF.md（Write 全量覆盖）

# 5) 验证
wc -c docs/HANDOFF.md            # 预期 ≤ 8192
grep -c "^## " docs/HANDOFF.md   # 预期 5（五节骨架）

28.6 验证

验证项	结果
HANDOFF 体积	6,620 B（原 12,028 B，降 45%），≤ 8192 ✓
五节骨架	grep -c "^## " = 5 ✓
禁入内容	无轮次概览、无已结案正文、无实现细节、无证据片段 ✓
归档完整	机制分档、Hook 实测、各已结案项在 SOP 均有对应节，HANDOFF 只留指引 ✓
skill 一致性	全文无残留「12 KB / 12288」（仅本节与 skill 内的沿革说明提及）；上限、判据表、禁入清单、收尾清单均已更新 ✓
过时表述	通读一遍，无与当前状态冲突的表述 ✓

28.7 回滚

cd /home/rain/Documents/services/token_proxy
# 高危：覆盖当前文件；执行前先确认备份存在
cp -p handoff-slim/backup/skill-writing-handoff/SKILL.md.bak.<TS> ~/.trae-cn/skills/writing-handoff/SKILL.md
cp -p handoff-slim/backup/docs/HANDOFF.md.bak.<TS> docs/HANDOFF.md

回滚 skill 后需开新会话生效；回滚 HANDOFF 后下次驱动即注入旧版。

28.8 风险说明

风险	缓解
压缩丢关键信息	逐条核对 SOP 归档；红线、环境事实、命令速查、成本基线一律保留
8 KB 过紧，导致频繁「强制整体重写」	本次落在 6.6 KB，留 20% 余量；若连续两轮触发强制重写，再议回调至 10 KB
skill 改动面大（全局生效）	改动限于长度预算、判据、清单、骨架第 2 项四处；已备份且回滚路径明确
生效时机被误判	skill 改动须新会话生效——本轮改动对本会话无效，验证须在新会话复核

28.9 附录：本轮讨论固化的成本认知

档位	单价（元/百万）	含义
命中输入	0.02	历史重放的主体
未命中输入	1.0	每轮新加入的内容（读文件、工具结果、上轮回显）
输出	4.0	回答与写文件

实测一个 39 轮会话：输入 2.70M（未命中 47.8k）、输出 49.2k、≈ 0.30 元，输出占 66%。 → 优化优先级：少输出 > 少未命中 > 少历史。此文已固化进 HANDOFF 第 2 节。

同时记下量级判断：本文件体系的花费都很小（HANDOFF 一次生命周期 ≈ 0.023 元；即便每轮 C 类变更都整体重写， 也只占日均支出的 < 1%）——瘦身的主要收益是「更好用、更不易被注入截断」，不是省钱。

交付物：handoff-slim/（backup/ 台账 + 2 个回滚点）。

---

二十九、执行记录（2026-09-23）：档案一致性修补与子 agent 验证落档

变更对象：① 本工程 docs/SOP.md、docs/HANDOFF.md；② Trae 全局 skill ~/.trae-cn/skills/reading-docs-for-context/SKILL.md（不在本工程内，沿用本 SOP 留档，理由同第十九节： 改 skill 会使本代理前缀整段失效一次，两者在成本上强耦合）。 不触碰 proxy.py、config.yaml 与 token-proxy 服务。

29.1 变更背景

缘起：用户要求汇总「针对其使用 Trae 的行为与习惯」。汇总过程中暴露四件事，全部属档案层面问题，本次一并处理：

#	问题	表现
1	表述断层	21.10 / 21.11 写「工具结果压缩是唯一从未处理过的空项」，但同一天的 22 节已把它以规则形态落地；22.9 仅一句轻描。读者反复查阅仍不知到底处理过没有
2	口径漂移（P5）	取证约束规则判「文件 > 800 行」、skill reading-docs-for-context 判「待读量 > 800 行」，同值不同义。24.9 裁定「留待下次触碰该 skill 时加限定语」，本次即为该时机
3	验证结论未落档	25.9 D.2 记「子 agent 的 additionalContext 是否注入其独立上下文」为【未直接验证】，留待日常观察；本轮已实测确认
4	待办散落	「前缀失效告警」只存在于 HANDOFF 3.2 的一句话，本 SOP 无归档，易被遗忘

29.2 变更目标

• 21 节不再被按「未处理」引用，读者可一跳到达落地点（22.9）；
• skill 与规则的两条 800 判据不再混淆；
• 25.9 D.2 由【未验证】升为【已验证】，并附可复现证据；
• 「前缀失效告警」在本 SOP 内成为有判据、有实现路线的正式待办（见 29.10）。

29.3 前置条件

• 三个被改文件已备份，台账见 archive-fixups/backup/README.md；
• 改 skill 须开新会话才对技能列表生效（机理见 18.4.1）；本工程文档与规则改动即时生效；
• 无服务依赖，代理不参与本次变更。

29.4 影响范围

项	内容
主机	仅本机 Ubuntu 192.168.31.250（用户 rain）
涉及文件	docs/SOP.md、docs/HANDOFF.md、~/.trae-cn/skills/reading-docs-for-context/SKILL.md
是否停服	不停服。不触碰 token-proxy 服务、config.yaml、proxy.py
窗口期	无
在跑业务	不影响代理转发与报表；仅在途会话可能多一次前缀失效
前缀影响	改 skill 使下一会话首个请求全量未命中一次（18.4.1）；本工程文档与规则改动同理产生一次
成本增量	skill 正文 +1 行（约 60 字）；SOP 新增本节。均属文档开销，量级 < 日均支出 1%（依据 28.9）

29.5 分步操作

实现体即文件编辑本身（单机、动作 ≤3 类、无编排），未产出脚本；代码块用于复核与复现， 不承担幂等与错误处理。

# 备份落主题目录，台账见其 README.md
D=/home/rain/Documents/services/token_proxy/archive-fixups
B="$D/backup"
TS=20260923-014909

# 1) 备份三个待改文件（高危：覆盖原文件前必须完成）
mkdir -p "$B/docs" "$B/home/rain/.trae-cn/skills/reading-docs-for-context"
cp -p /home/rain/Documents/services/token_proxy/docs/SOP.md     "$B/docs/SOP.md.bak.$TS"
cp -p /home/rain/Documents/services/token_proxy/docs/HANDOFF.md "$B/docs/HANDOFF.md.bak.$TS"
cp -p /home/rain/.trae-cn/skills/reading-docs-for-context/SKILL.md \
      "$B/home/rain/.trae-cn/skills/reading-docs-for-context/SKILL.md.bak.$TS"

# 2) 修表述断层：在 SOP 21.11 末尾加注记，指向 22.9 的落地点
# 3) 修口径漂移（P5）：SKILL.md 第 4 步「待读量 > 800 行」处补限定语，点明此 800 非文件总行数
# 4) 落档验证：SOP 25.9 D.2 由 ⏳ 改为 ✅，并指向本节
# 5) 追加本节（八章 + 两附录）

# 生效：改 skill 须开新会话；本工程文档下次读取即生效

29.6 验证

#	验证项	命令	实测结果
1	表述断层注记已加	grep -n "勿再按未处理引用" docs/SOP.md	✅ 命中 1597 行（21.11 末尾注记）
2	25.9 D.2 已升级	grep -n "见第二十九节" docs/SOP.md	✅ 命中 2129 行，该项已为 ✅ 已验证
3	P5 限定语已加	grep -n "非文件总行数" ~/.trae-cn/skills/reading-docs-for-context/SKILL.md	✅ 命中
4	skill frontmatter 完好	head -n 4 ~/.trae-cn/skills/reading-docs-for-context/SKILL.md	✅ --- / name / description / --- 结构未损
5	HANDOFF 未超限	wc -c docs/HANDOFF.md	✅ 6724 字节（上限 8192）
6	无过时表述残留	通读 HANDOFF	✅ 无「未处理」「未验证」等已失效说法

29.7 回滚

# 覆盖回备份；skill 需开新会话才恢复原行为
B=/home/rain/Documents/services/token_proxy/archive-fixups/backup
TS=20260923-014909
cp -p "$B/docs/SOP.md.bak.$TS"     /home/rain/Documents/services/token_proxy/docs/SOP.md
cp -p "$B/docs/HANDOFF.md.bak.$TS" /home/rain/Documents/services/token_proxy/docs/HANDOFF.md
cp -p "$B/home/rain/.trae-cn/skills/reading-docs-for-context/SKILL.md.bak.$TS" \
      /home/rain/.trae-cn/skills/reading-docs-for-context/SKILL.md

回滚后 SOP/HANDOFF 下次读取即恢复；skill 须开新会话才恢复原匹配行为。

29.8 风险说明

风险	缓解措施
编辑误伤原文	逐处 diff 复核；本次实测确已发生一处误删（21.11 的「中」字），已当场修正
改 skill 全局生效，波及所有会话	改动限于一句限定语；frontmatter 未动；已备份、回滚路径明确
改 skill 触发前缀失效一次	不可避免（18.4.1）；本轮改完即开新会话
新增 SOP 节使档案更长	本节为必需的变更档案；HANDOFF 另有 8 KB 上限约束，不受影响

29.9 附录 A：子 agent 验证的证据（本轮实测）

实验设计：派一个 search 子 agent，令其直接用 Read 读 docs/HANDOFF.md（不先做 Glob/LS， 避免绕开 Hook），并要求它如实报告自己上下文的结构；同时以 docs-read-hook/state/ 的文件增量作第二条独立证据。

证据	内容
1. 子 agent 自报	回报收到了 <hooks_context event_phase="pre_tool_use"><hook event_name="PreToolUse"><additional_context>…</additional_context></hook></hooks_context> 块，其文案与 docs-read-guard.py 的 PROMPT 常量逐字一致；该文案不在 HANDOFF.md 正文内，子 agent 无从别处抄得
2. state 增量	新增 6ab2bbb5a5e95acebe11ad11__search（01:45:27），与主 agent 的 6ab2bbb5a5e95acebe11ad11__solo_agent（01:34:31）同 session_id、不同 agent_id，符合脚本去重键 session_id__agent_id 的设计

结论：25.9 D.2 由【未直接验证】升为【已验证】；HANDOFF 3.1 的对应待观察项一并结项。

附带发现（对应 25.9 E）：该子 agent 主动声明未加载 reading-docs-for-context，理由是本次任务 「对象是验证工具返回结构，不是获取项目背景，故不适用」。这是一个「投递必然、遵守仍是概率」的活样本—— 机制把投递从 🔴 提到 ✅，但遵守仍受模型判断支配，本次判断合理、不属误用。

复现方式：ls -la docs-read-hook/state/ 看是否出现新的 …__search 条目；或再派子 agent 直读 docs/*.md 并要求其逐字回报上下文中的 hooks_context 块。

29.10 附录 B：正式待办——前缀失效告警

源出 HANDOFF 3.2【待决策】，原先仅一句、本 SOP 无归档，本节将其固化为正式待办。

是什么：把 18.4.1 已定位的「前缀整段失效」做成实时提示——当某条请求 miss 突增、且 shape.tools_hash（或 system 指纹）与前一条不同时，记一条提示，让使用者当场知道「刚这一下贵了」。

定性：便利性提示，不是省钱手段。省钱靠的是既有处置约定「改 skill / 规则后立即开新会话」（18.4.1）， 告警只是提醒别忘。

数据基础：logs/req_shape.jsonl 已落 miss 与 shape.tools_hash，判定所需字段齐备。

两条实现路线：

路线	形态	代价
甲	改 proxy.py 实时判定并记一条	C 类；须重启，必然打断在途流式回答（26.10 已评估）
乙	只读定时巡检（B 类），复用 cost_audit/analyze_prefix_fail.py 的判定逻辑	零风险、不动服务；但有延迟，非实时

失效判据：若实施后长期（如连续多日）无新增 miss>10k 且无 tools_hash 变化，说明前缀失效已收敛， 该告警可下线。

当前状态：【已决策】不实施（2026-09-23 评估，记录见第三十节 30.10）。否决理由： ① 失效瞬时发生、上游已重算，告警只能事后记账，拦不住本次；② 代理是独立进程， 推不到正在进行的 Trae 会话，甲路线的「实时」送不达决策点，却要付改 proxy.py + 重启 + 打断在途流式回答的代价；③ 真杠杆是既有约定「改完 skill 立即开新会话」。实测可挽回上限 约 0.87 元 / 7 天——14 个受影响会话中 12 个只失效 1 次，那一次是改 skill 的固有成本。

---

三十、执行记录（2026-09-23）：hooks / skills / rules 合理性整改

30.1 变更背景

2026-09-23 对配置层（~/.trae-cn/ 下的 hooks、skills、user_rules）做了一次只读合理性评估， 发现 6 处问题（记为 P1~P6）。其中 P1 是评估过程中实际撞上的规则冲突——执行时被迫停下向用户请示。

编号	问题	类型
P1	A 类「不生成任何文档」与「A 类决策必须重写 HANDOFF」自相矛盾	规则内部冲突
P2	~/.trae-cn/skills/ 下 5 个 .bak 散落在被改文件旁，违反自家备份规则且无台账	规则被自身违反
P3	docs-read-guard.py 头部仍写「子 agent 注入未实测」，与 29.9 的已验证结论矛盾	档案过时
P4	4 个 rule 文件中 3 个有 frontmatter、rule-skill-index.md 缺失	写法不一致
P5	全局 hooks.json 硬编码项目内脚本绝对路径，项目迁移时会静默失效，且迁移记录未列此项	脆弱点
P6	rules 与 skills 存在系统性内容重叠，且已出现不同步（skill 侧多一条「联动」）	分工不清

30.2 变更目标

• P1~P4、P6 消除矛盾与不同步；
• P5 不改动 hooks.json（相对路径是有意设计，guard 绝对路径当前正确），改为固化 「工程外写死路径完整清单」供今后迁移核对（见 30.9）；
• P6 采用去重方向：rules 补齐、skill 侧重复内容改为指针。不反向——rules 每轮必然注入、 skill 概率触发，把必须遵守的内容下沉到 skill 等于从「必然可见」降级为「概率可见」， 违反 2.2 的三层机制结论「必须发生的事不能托付给 skill」。

30.3 前置条件

• 7 个待改文件逐个备份到 config-review/backup/ 并登记台账；
• 全部改动集中在一次完成，只触发一次前缀失效；
• 无需停服、无需重启代理。

30.4 影响范围

项	内容
主机	Ubuntu 192.168.31.250（用户 rain），单机
受影响文件	全局 4 个（3 个 rule + 1 个 skill）、项目内 3 个（docs/SOP.md、docs/HANDOFF.md、docs-read-hook/docs-read-guard.py）
是否停服	否。不改 proxy.py / config.yaml，代理 token-proxy 不受影响
窗口期	无要求。唯一即时影响：rules / skill 改动立即对所有项目、所有会话生效；改完当前会话触发一次前缀失效（预期内，见 30.8）
在跑业务	无
生效方式	rules 与 skill 改动下一次新会话完全生效；docs-read-guard.py 由 hook 每次调用即时生效

30.5 分步操作

本次为文件编辑，无脚本实现体；以下为等价操作序列，供人阅读与复核，不承担幂等与错误处理。

# 工作目录：/home/rain/Documents/services/token_proxy

# 1) 备份 7 个待改文件（时间戳 20260923-020633）
mkdir -p config-review/backup/trae-cn/user_rules config-review/backup/trae-cn/skills/writing-ops-change-sop \
         config-review/backup/token_proxy/docs config-review/backup/token_proxy/docs-read-hook
cp -p ~/.trae-cn/user_rules/rule-ops-scenario-routing.md    config-review/backup/trae-cn/user_rules/rule-ops-scenario-routing.md.bak.20260923-020633
cp -p ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md config-review/backup/trae-cn/user_rules/rule-ops-evidence-constraints.md.bak.20260923-020633
cp -p ~/.trae-cn/user_rules/rule-skill-index.md             config-review/backup/trae-cn/user_rules/rule-skill-index.md.bak.20260923-020633
cp -p ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md     config-review/backup/trae-cn/skills/writing-ops-change-sop/SKILL.md.bak.20260923-020633
cp -p docs-read-hook/docs-read-guard.py                     config-review/backup/token_proxy/docs-read-hook/docs-read-guard.py.bak.20260923-020633
cp -p docs/SOP.md                                           config-review/backup/token_proxy/docs/SOP.md.bak.20260923-020633
cp -p docs/HANDOFF.md                                       config-review/backup/token_proxy/docs/HANDOFF.md.bak.20260923-020633

# 2) P2：把散落在 skill 目录旁的 5 个历史备份移入台账（移动，非删除；原名不改）
mkdir -p config-review/backup/trae-cn/skills/developing-python-deploy-scripts config-review/backup/trae-cn/skills/reading-docs-for-context
mv ~/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md.bak.20260914-235424 config-review/backup/trae-cn/skills/developing-python-deploy-scripts/
mv ~/.trae-cn/skills/reading-docs-for-context/SKILL.md.bak.20260916-133821     config-review/backup/trae-cn/skills/reading-docs-for-context/
mv ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md.bak.20260914-235424       config-review/backup/trae-cn/skills/writing-ops-change-sop/
mv ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md.bak.20260919-154734       config-review/backup/trae-cn/skills/writing-ops-change-sop/
mv ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md.bak.20260919-155819       config-review/backup/trae-cn/skills/writing-ops-change-sop/

# 3) P1：A 类那句加 HANDOFF 例外
#    ~/.trae-cn/user_rules/rule-ops-scenario-routing.md「A 类」节
#    「不生成任何文档、SOP、脚本…」→「不生成任何交付文档、SOP、脚本…**例外**：写入 docs/HANDOFF.md 交接快照不受此限」

# 4) P6-a：备份与留档补「联动」条
#    ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md，在「台账」与「清理」之间插入：
#    SOP 第 7 章与附录须写明备份存放位置并指向 backup/README.md

# 5) P4：补 frontmatter
#    ~/.trae-cn/user_rules/rule-skill-index.md，文件头加 alwaysApply: true + description

# 6) P6-b：skill 侧去重
#    ~/.trae-cn/skills/writing-ops-change-sop/SKILL.md
#    SOP 第 7 章补「指向 backup/README.md」；「备份与留档」节 5 条 → 一行指针

# 7) P3：修 guard 脚本过时注释
#    docs-read-hook/docs-read-guard.py，头部「未验证项」→「已验证（2026-09-23）」

# 8) 幂等复跑：重跑 3)~7) 的编辑动作，因目标文本已不存在而零改动、无报错

30.6 验证

#	命令	预期	实测
V1	python3 -c "import ast; ast.parse(open('docs-read-hook/docs-read-guard.py',encoding='utf-8').read())"	无异常（用 ast.parse 而非 py_compile，避免落 __pycache__）	通过
V2	逐文件 grep -c 五处改动标记	各 = 1	各 = 1
V3	逐文件 grep -c 三处旧文本残留	全 = 0	全 = 0
V4	find ~/.trae-cn/skills -type f	只剩 5 个 SKILL.md，无散落 .bak	干净
V5	开新会话后确认 rules 仍完整注入（含「技能加载索引」）、A 类新表述可见；读 docs/*.md 时 PreToolUse 提示仍出现	三项齐备	待新会话

V3 的三处残留判据：不生成任何文档、SOP、脚本、本机尚未实测、本次交付物目录下的（skill 侧旧 5 条）。

幂等复跑：重跑 30.5 的 3)~7) 编辑动作，目标文本均已不存在，故零改动、无报错——即「第二次零变更、全跳过」。

30.7 回滚

备份全部位于 config-review/backup/，台账见 config-review/backup/README.md（逐条含原路径、 产生时间、因何产生、回滚什么、何时可删）。回滚 = 按台账逐条 cp -p 覆盖回原路径，随后开新会话。

回滚触发判据（任一命中即回滚全部 7 处，不逐项保留）：

1. V1 语法检查抛异常；
2. 新会话中 rules 缺失任一原有章节（尤其「技能加载索引」）；
3. 新会话读 docs/*.md 时 PreToolUse 注入提示消失。

第 2、3 条把「不可自动检测的行为变化」转成了可观察判据；第 2 条正是 P4 的主要风险出口。

30.8 风险说明

风险	说明与缓解
规则即时生效、无缓冲	改前逐个备份；出错即 cp -p 回滚（10 秒内完成）
触发一次前缀失效（约 0.35 元）	不可避免（机理见 18.4.1）；7 处改动集中一次做完只失效一次；改完立即开新会话
P4 补 frontmatter 后注入行为可能变化	依赖 Trae 对 alwaysApply 的处理方式，本机无法预先验证；已列为回滚判据 2
误把细则下沉到 skill	本次为反向操作（rules 补齐、skill 去重），理由见 30.2；不采用反向方向
历史 .bak 原始用途不可追溯	只移动不删除，可原样移回；台账如实标注「无法追溯」，不做推测

30.9 附录 A：工程外写死路径完整清单（P5 产出）

项目迁移 / 改名时，以下项目外位置写死了本项目路径，必须逐一核对。 清单外的遗漏会导致静默失效——这些位置的守卫多为 [ -f ]，找不到即跳过，不报错。

#	位置	内容	失效表现
1	systemd 用户单元（4 处）	工程路径与启动命令	服务无法启动
2	用户 crontab（3 处）	报表定时任务路径	报表不再刷新，无报错
3	config.yaml 的 cost.output_dir	报表输出目录	报表落到错误位置
4	~/.trae-cn/hooks.json 的 PreToolUse	$HOME/Documents/services/token_proxy/docs-read-hook/docs-read-guard.py	档案读取提示静默消失（第三十节 P5 新发现，此前迁移记录未列此项）
5	~/.trae-cn/hooks.json 的 PostToolUse	$HOME/Documents/services/token_proxy/posttooluse-guard/skill-edit-guard.py	规则变更提醒静默消失（第三十二节新增）
6	~/.trae-cn/hooks.json 的 SessionStart	$HOME/Documents/services/token_proxy/sessionstart-hook/session-start-inject.py；该脚本内另写死兜底 HANDOFF 路径与留痕路径	会话启动注入静默消失——中文指令与 HANDOFF 都不再注入（第三十七节新增）

2026-09-17 的工程迁移实际改对了第 4 项，但迁移记录（本 SOP 头部）只列了前三类—— 记录不全但结果正确，属侥幸。今后迁移一律按本表核对。

30.10 附录 B：关联订正

本轮顺带修正了「前缀失效告警」评估（HANDOFF 3.2 原待决策项）遗留的两处口径过时：

1. 18.4.1：「09-20 之后已自然收敛」→ 该判断被后续实测推翻，已在 18.4.1 内加「口径订正」注；
2. 29.10：「当前状态：【待决策】」→ 改为「【已决策】不实施」，附三条否决理由。

前缀失效告警的决策依据（实测 7 天数据、14 个会话中 12 个只失效 1 次、可挽回上限约 0.87 元/7 天） 记录在 HANDOFF 2.1；否决理由的核心是「告警只能事后记账，且代理无法向 Trae 会话推送提示」。

---

三十一、执行记录（2026-09-23）：清理历史备份与失效探针（HANDOFF 3.2 待决策项结项）

性质：交付物清理（C 类收尾）。不触碰服务、配置、代码与数据；无停服、无窗口期、无业务影响。

31.1 背景

第三十节配置层整改结项后，工程根累积了大量历史残留：13 个主题 backup/ 目录、一个无台账登记 的根 .bak/（26 MB，含 2026-09-14 环境重建前的完整 venv 副本）、以及层 2 上线时的抓包探针。

HANDOFF 3.2 自第二十五节起挂着一条待决策：「docs-read-hook/probe-log.sh、probe/、各 */backup/ 已无用，按各自台账由用户自行删（Agent 不主动删除）」。本轮由用户明确指令执行，删前逐项确认范围。

31.2 目标

• 工程根不再出现无台账登记的备份目录与已失效的探针脚本；
• 仍有回滚价值的近期变更回滚底牌原样保留。

31.3 前置条件与引用核验（执行前）

检查项	方法	结果
Hook 是否仍指向探针	cat ~/.trae-cn/hooks.json	PreToolUse 已指向 docs-read-guard.py，不引用 probe-log.sh
配置/代码是否引用备份路径	grep -rn -E 'probe-log\|/\.bak\|backup/' hooks.json config.yaml run.sh proxy.py	零匹配
crontab 是否涉及	crontab -l	仅报表与 k8s 隧道两条，无涉及
台账是否允许删除	各 backup/README.md	统一写「由用户对照本表自行删除单个文件或整个目录；Agent 不主动删除」

31.4 影响范围

项	值
主机	仅 192.168.31.250 本机、工程目录内
组件	计量代理与成本报表均不涉及；systemd 服务、crontab、proxy.py / config.yaml 未改动
是否停服	否
窗口期	无（纯文件删除，瞬时完成）
在跑作业	无影响；代理服务全程 active

31.5 分步操作

本次为一次性人工操作，未产出脚本。删除目标以显式路径数组给出，删除前逐条做 「路径前缀必须在工程根之下」的白名单校验；全程未使用任何通配符。

cd /home/rain/Documents/services/token_proxy
ROOT=$(pwd)
targets=(
  archive-fixups/backup autostart/backup backlog-cleanup/backup cost_audit/backup
  external-skills/backup handoff-slim/backup handoff-spec/backup
  prefix-alert-review/backup relocate_20260917/backup skill-hit-rate/backup
  .bak docs-read-hook/probe docs-read-hook/probe-log.sh
)
for t in "${targets[@]}"; do                     # 逐个校验后删除，无通配
  p="$ROOT/$t"
  case "$p" in "$ROOT"/*) ;; *) echo "拒绝(越界): $p"; exit 1;; esac
  [ -e "$p" ] || continue
  rm -rf -- "$p"                                 # 高危：删除不可恢复，范围已由用户确认
done

随后清理 7 个因此变空的主题目录（rmdir 仅对空目录生效，非空即失败跳过）：

for d in prefix-alert-review backlog-cleanup external-skills archive-fixups \
         handoff-spec handoff-slim skill-hit-rate; do
  [ -d "$d" ] && [ -z "$(ls -A "$d")" ] && rmdir "$d"
done

31.6 验证

find . -path ./venv -prune -o -type d -name backup -print    # 预期仅剩 3 个
ls -d .bak docs-read-hook/probe docs-read-hook/probe-log.sh  # 预期全部 No such file
systemctl --user is-active token-proxy                       # 预期 active

判据	预期结果	实测
剩余 backup/	3 个（resp-digest / config-review / docs-read-hook）	✅
根 .bak/	不存在	✅
探针	probe/、probe-log.sh 均不存在	✅
空主题目录	7 个已删除	✅
服务	token-proxy = active	✅

31.7 回滚

本次操作不可回滚，且不需要回滚。

删除对象本身就是历史备份与失效探针；其守护的变更均已结案并验证通过。若日后仍需旧版本文档， 取保留台账 config-review/backup/README.md 中登记的副本（含第三十节整改前的 HANDOFF / SOP / 各 skill 与 rules 原件）。

31.8 风险说明

风险	缓解
误删仍具回滚价值的底牌	删除前逐项与用户确认范围；主动保留 config-review / resp-digest / docs-read-hook 三处近期回滚点
误删被引用的文件	删除前核验 hooks.json / config.yaml / run.sh / proxy.py / crontab，零引用
越界或通配误伤	显式路径数组 + 工程根前缀白名单校验；空目录用 rmdir（非空即失败），无 rm -rf 通配
丢失「不可再生数据」	logs/usage.jsonl 与 logs/balance_history.jsonl 从未进入删除清单；被删的 .bak/usage.jsonl.* 系 9/12 与 9/14 的历史快照

31.9 附录：删除与保留清单

已删除（分项合计约 27 MB）

类别	对象
主题备份（10 个）	archive-fixups / autostart / backlog-cleanup / cost_audit / external-skills / handoff-slim / handoff-spec / prefix-alert-review / relocate_20260917 / skill-hit-rate 的 backup/
无台账历史残留	工程根 .bak/（config.yaml ×6、proxy.py ×7、cost_report.py ×3、usage.jsonl ×3、SOP.md ×2、net_static_ip ×1，以及旧 venv 副本 25 MB）
失效探针	docs-read-hook/probe/、docs-read-hook/probe-log.sh
空主题目录（7 个）	上表前七项的主题目录本体

保留

对象	理由
config-review/backup/	第三十节整改的回滚底牌（含收编的 5 个历史散落 .bak）
resp-digest/backup/	proxy.py 与 config.yaml 目前唯一的回滚副本
docs-read-hook/backup/	层 2 hooks.json 的唯一回滚点
docs-read-hook/state/	Hook 活跃运行数据，非备份
logs/usage.jsonl、logs/balance_history.jsonl	不可再生数据，绝不可删

后续清理由用户对照各 backup/README.md 自行执行，Agent 不主动删除。

---

三十二、执行记录（2026-09-23）：PostToolUse 实测与「规则变更提醒」落地

性质：C 类变更（改 ~/.trae-cn/hooks.json）+ 交付物新增（posttooluse-guard/）。 计量代理与报表未改动，无停服；需两次重启 Trae（Hook 配置运行期不重载）。

32.1 背景

HANDOFF 3.2 长期挂着一条「可选增量」：若 Trae 支持 PostToolUse，可在写操作命中 ~/.trae-cn/skills/** 或 user_rules/** 后注入一行「记得开新会话」。动机是改这两处会使 上游前缀缓存失效（实测约 0.35 元/次，见 18.4.1），在旧会话里继续对话等于反复踩这条成本。

该增量此前无法决策，症结是「Trae 是否支持 PostToolUse」未经证实。本轮回应用户提问， 一并做了实测与落地。

32.2 目标

1. 以实机证据确认本机 Trae 触发 PostToolUse，且 additionalContext 能回注给模型；
2. 支持则落地「规则变更提醒」，只在命中目标路径时注入，不进每轮固定重放。

32.3 前置条件与依据

项	内容
官方契约	docs.trae.cn 列出 6 类事件（含 PostToolUse）；stdin 含 tool_input / tool_response，stdout 支持 hookSpecificOutput.additionalContext
关键差异	纯文本回注仅适用于 SessionStart 与 UserPromptSubmit；PostToolUse 必须走 JSON 的 additionalContext
已知约束	Trae 运行期不重载 hooks.json（本次再次确认）；改配置必须重启
权限	~/.trae-cn/hooks.json 可写；Hook 可写工程内与 /tmp

32.4 影响范围

项	值
主机	仅 192.168.31.250 本机
组件	计量代理、报表、proxy.py、config.yaml 均未改动
是否停服	否
阻塞开销	matcher 为 *，每次工具调用后执行一次判断脚本（毫秒级，未命中即退出）
窗口期	需重启 Trae 两次（接入探针一次、转正配置一次）；重启会打断在途流式回答

32.5 分步操作

实现体：posttooluse-guard/skill-edit-guard.py（正式）与 posttooluse-guard/posttooluse-probe.py（验证探针）。 下列代码块供阅读与复核，以实现体为准。

# ① 备份（高危：后续将覆盖 hooks.json）
cp -p ~/.trae-cn/hooks.json \
  posttooluse-guard/backup/home/rain/.trae-cn/hooks.json.bak.$(date +%Y%m%d-%H%M%S)  # sha256 0ce2b67a…

# ② 阶段 1：加 PostToolUse 探针（matcher="Read"），只记录不输出 → 重启 Trae
# ③ 阶段 2：探针改输出 additionalContext → 仅改脚本内容，即时生效、无需重启
# ④ 转正：matcher 改 "*"，command 指向 skill-edit-guard.py → 再次重启 Trae

32.6 验证

阶段	判据	结果
1. 事件触发	probe.jsonl 出现记录	✅ 2 条，tool_name=Read，stdin 11 键与官方契约一致
2. 回注通路	会话出现 <hooks_context event_phase="post_tool_use">	✅ 读到带实时时间戳的探针文本
3. 静默可控	关闭输出后不再注入	✅
4. 端到端	影子目录 /tmp/skill-guard-test/ 写入后出现 [规则变更提醒]	✅
5. 未命中不打扰	写工程内文件时无注入	✅
6. 退出码	全部用例恒为 0、无 stderr	✅

端到端验证刻意使用 /tmp 影子目录，未向真实的 skills/ 与 user_rules/ 写入任何文件 （已用 find -mmin -10 复核）。

32.7 回滚

# 高危：覆盖当前 hooks.json。回滚后须重启 Trae 才生效。
cp -p posttooluse-guard/backup/home/rain/.trae-cn/hooks.json.bak.20260923-021747 ~/.trae-cn/hooks.json

备份位置与台账见 posttooluse-guard/backup/README.md。回滚后 PostToolUse 组消失， 即回到「仅 SessionStart + PreToolUse」的原状。

32.8 风险说明

风险	缓解
matcher 写错导致功能静默失效	用 * 覆盖全部工具、不依赖工具名；脚本首步即判断路径
脚本以非 0/2 退出码结束	命令尾部统一 || true; exit 0
提醒文本进入上下文变成固定成本	仅命中目标路径时注入；单次一行，触发频率极低
误向真实 skill / 规则目录写入	端到端验证改用 /tmp 影子目录，未触碰真实目录
工程迁移后 hook 静默失效	已登记进 30.9 写死路径清单（新增第 5 项）

32.9 附录：交付物

路径	说明
posttooluse-guard/skill-edit-guard.py	正式实现
posttooluse-guard/posttooluse-probe.py	验证探针（置 INJECT_PROBE=True 可复测回注）
posttooluse-guard/probe.jsonl	验证阶段抓到的真实事件记录
posttooluse-guard/backup/	hooks.json 备份与台账

---

三十三、执行记录（2026-09-23）：PostToolUse 守卫误报修复 + 全局规则口径对齐

性质：C 类变更（改 ~/.trae-cn/skills/** 与 user_rules/**）。 hooks.json 未改动，无需重启 Trae；计量代理与报表未改动，无停服。 完整 SOP（八章）见 rules-consistency-fix/SOP.md，本节为档案条目。

33.1 背景

起因是一次只读审查（检查 hooks / rules / skills 是否有不合理处），审查过程中当场复现 第三十二节上线守卫的误报：一轮会话内 9 次纯 Read 操作全部触发「本次写操作改动了 …」。

根因：skill-edit-guard.py 的 main() 只从 tool_input 提取路径，从不检查 tool_name； 而 hooks.json 的 matcher 为 "*"，Read 同样携带 file_path，命中监视目录即被判为写操作。

佐证：probe.jsonl 的 3 条样本 tool_name 全为 Read，可见该路径早已存在； 而 32.6 的用例集只覆盖「写操作命中」与「写操作未命中」，未覆盖「只读工具命中监视路径」， 误报因此在验证阶段被漏检。

同时，只读审查发现全局规则体系内三处口径不一致。

33.2 目标

1. 只读工具一律静默，写类工具仍如期提醒；
2. 三处口径不一致消除，各自指向单一源，不再各维护一份写法。

33.3 前置条件与依据

项	内容
权限	rain 用户，可写 ~/.trae-cn/user_rules、~/.trae-cn/skills 与工程目录
字段依据	probe.jsonl 证明事件 stdin 含 tool_name（11 键），字段本就可用，只是未被使用
关键决策	采用白名单而非黑名单。漏报只损失一次提醒（约 0.35 元）；误报则每轮重放并误导模型，代价不对等

33.4 影响范围

项	值
主机	仅 192.168.31.250 本机
组件	全局 PostToolUse 守卫；2 个规则文件；1 个 skill 文件。hooks.json 与代理均未改动
是否停服	否
是否重启 Trae	否（守卫脚本每次新起进程，改动即时生效）
窗口期	无；但改 rules / skill 会触发前缀缓存失效（约 0.35 元/次），故 3 个文件一次改完，随后开新会话

33.5 分步操作

实现体：4 个文件的定点文本替换，由 Agent 编辑能力直接完成，未引入脚本。 完整操作序列与改前改后对照见 rules-consistency-fix/SOP.md 第 5 章。

# ① 备份 4 个待改文件（高危：回滚唯一依据）→ rules-consistency-fix/backup/
# ② skill-edit-guard.py：插入 WRITE_TOOLS 白名单 + main() 中工具类型判断
# ③ rule-ops-scenario-routing.md:49：备份命名改为指向单一源（原为 date +%Y%m%d，缺时分秒）
# ④ developing-python-deploy-scripts/SKILL.md:18：「四条安全红线」→「安全红线（当前 5 条，以规则正文为准）」
# ⑤ rule-skill-index.md:19：索引表补「单主机多步骤」分档，与技能自身边界表对齐
# ⑥ 验证：7 个离线用例 + 两轮幂等复跑

33.6 验证

项	判据	结果
离线用例	Read / Grep 命中监视路径应静默；Write / Edit / DeleteFile 命中则应提醒；非监视路径静默；tool_name 缺失静默	✅ 7/7
幂等	同组用例连跑 2 次，结果完全一致	✅
真实写操作	本轮改 3 个规则 / skill 文件后，如期回注 3 条提醒	✅
无回归误报	全程 Read 未再触发	✅
文本核对	grep 三处均为目标态，无残留旧写法	✅

该条同时关闭 HANDOFF 3.1 的【未验证】项「真实改动 skill / 规则时是否如期提示」—— 判据 [规则变更提醒] 已满足，且方向正确（真写触发、假写不触发）。

33.7 回滚

备份位置 rules-consistency-fix/backup/，台账见其 README.md；命令见 rules-consistency-fix/SOP.md 第 7 章。

33.8 风险说明

风险	缓解
WRITE_TOOLS 用白名单，未来新增写类工具会漏报	取「漏报优于误报」；常量内注释已声明需同步
MCP 类工具的写操作不在白名单内	已知局限，未覆盖
守卫无去重，一次会话改多个文件会注入多条同类提醒	本轮实测 3 条，成本可接受；误报消除后不再无节制增长

33.9 附录：交付物

路径	说明
rules-consistency-fix/SOP.md	本次变更完整 SOP（八章）
rules-consistency-fix/backup/	4 个被改文件的备份与台账 README.md

本轮经用户确认未处理（留作后续）：① SessionStart 用相对路径，在工程子目录启动会话时不注入； ② ~/.trae-cn/commands/** 未纳入 PostToolUse 监视面；③ docs-read-hook/state/ 无回收机制； ④ docs-read-guard.py 的 TARGET_RE 只匹配 docs/<单层>.md； ⑤ 「第 5 章以 shell 代码块呈现、不单独交付 .sh」的约定在 3 处重复，有漂移风险。

---

三十四、执行记录（2026-09-23）：Hooks / Rules / Skills 二次审查与口径修复

性质：C 类变更（改 ~/.trae-cn/hooks.json、3 个规则文件、1 个 skill、1 个命令、2 个 hook 脚本）。 hooks.json 有改动，须重启 Trae 才生效；计量代理与报表未改动，无停服。 完整 SOP（八章）见 agent-config-fix-20260923/SOP.md，本节为档案条目。

34.1 背景

第三十三节之后按同样口径再做一次只读审查（检查 hooks / rules / skills 是否有不合理处）。 本轮除复核 33.9 遗留项外，另发现 6 处口径问题（P1~P6）与 5 项未验证风险；经用户确认「已知的全部改完」。

34.2 目标

1. 33.9 的 ①②④ 关闭（③ 与 venv 重复项留档）；
2. P1~P6 六处口径问题消除；
3. 两个守卫脚本的离线用例从 7 项扩到 18 项，并首次为 docs-read-guard.py 补上回归用例。

34.3 前置条件

项	内容
权限	rain，可写 ~/.trae-cn/** 与工程目录
备份	10 个被改文件全部 cp -p 到 agent-config-fix-20260923/backup/，台账见其 README.md
实现体判断	动作同质（文本口径替换）、单机、无编排、无服务启停 → 不引入部署工程，改交付只读校验器（理由见 34.8）

34.4 影响范围

项	值
主机	仅 192.168.31.250
组件	2 个 Hook 实现体 + hooks.json + 3 个规则 + 1 个 skill + 1 个命令 + 2 份档案
是否停服	否（代理未动）
是否重启 Trae	是（hooks.json 改了）
窗口期	无；改 rules / skill 触发前缀失效（约 0.35 元/次），故 10 个文件一次改完、随后开新会话

34.5 分步操作

实现体：定点文本替换 + 一个只读校验器，由 Agent 编辑能力直接完成。 命令序列与改前改后对照见 agent-config-fix-20260923/SOP.md 第 5 章，以实现体为准。

# ① 备份 10 个待改文件（高危：回滚唯一依据）→ agent-config-fix-20260923/backup/
# ② hooks.json：SessionStart 注入路径由相对改绝对（须重启 Trae）
# ③ skill-edit-guard.py：WATCHED 拆为 DIRS + FILES，纳入 commands/ 与 hooks.json
# ④ docs-read-guard.py：TARGET_RE 支持子目录，新增 EXCLUDE_RE 排除依赖 / 缓存目录
# ⑤ rule-skill-index.md：补「改技能自身 → skill-creator」一行
# ⑥ rule-ops-scenario-routing.md：规则指代统一为文件名；第 5 章口径指向技能单一源
# ⑦ rule-python-script-safety.md：适用范围由「Python」扩为「所有脚本」
# ⑧ developing-python-deploy-scripts/SKILL.md：description 补「单主机多步骤」档
# ⑨ commands/deploy-py.md：去掉「加载规则」措辞
# ⑩ 验证：18 项离线用例 + 只读校验器两轮复跑

34.6 验证

项	判据	结果
守卫离线用例	PostToolUse 12 项 + PreToolUse 6 项（含误报回归、漏报修复、前缀相似路径拒绝）	✅ 18/18
只读校验器	verify_changes.py 10 项文本断言 + JSON 合法性 + 脚本可编译	✅ 12/12
幂等	校验器连跑两次，结果一致、需变更 0 项	✅
SessionStart 命令	在 /tmp（非工程 cwd）执行亦能命中 HANDOFF	✅
真实写操作提醒	本轮改规则 / skill 时如期回注提醒	✅ 6 条
无回归误报	全程 Read 未触发写操作提醒	✅

上表同时关闭 HANDOFF 3.1 的【未验证】项「守卫白名单是否覆盖真实工具名」—— 本轮改 user_rules 时 SearchReplace 路径如期触发，证明真实事件的 tool_name 与白名单一致。

34.7 回滚

备份位置 agent-config-fix-20260923/backup/，台账见其 README.md，命令见同目录 SOP.md 第 7 章。 回滚 hooks.json 后须重启 Trae。

34.8 风险说明

风险	缓解
hooks.json 写坏 → Hook 全线失效	改后立即 json.load 校验；备份可整体还原
守卫脚本写坏 → 每次工具调用受影响	任何异常路径均 exit 0；18 项离线用例回归
实现体未用 Python 工程（规则从严侧的边缘）	动作同质、单机、无编排、无服务启停，落在「极简」一侧；以只读校验器补足审计与幂等证明
commands/** 纳入提醒后，改命令也提示「开新会话」	命令正文只在被调用时展开，影响面小于 skill / 规则；提示偏保守，可接受

34.9 附录：交付物

路径	说明
agent-config-fix-20260923/SOP.md	本次变更完整 SOP（八章）
agent-config-fix-20260923/verify_changes.py	只读验收器（10 项期望状态断言 + 2 项结构校验，可反复执行）
agent-config-fix-20260923/tests_guard_cases.py	两个守卫的 18 项离线用例
agent-config-fix-20260923/backup/	10 个被改文件的备份与台账 README.md

本轮经用户确认仍未处理（留作后续）：① docs-read-hook/state/ 无回收机制，现 10 个空文件、 随会话单调增长；② venv 规范在 rule-ops-scenario-routing.md 与 developing-python-deploy-scripts 技能内各有一份，尚未收敛到单一源；③ docs-read-guard.py 的去重键在 session_id 缺失时退化为 「全机器注入一次」（当前事件样本均有值，影响低）。

三十五、Hooks / Rules / Skills 第三轮审查与修复（2026-09-23）

背景与触发

第三十四节（第二轮）修复后做第三轮通读，又发现五类问题。触发条件：用户要求「再次检查 Hooks、rules、 skills 是否有不合理的地方，全部修掉」。

发现（按严重度）

1. commands/ 命中被错误归因——skill-edit-guard.py 对 skills / user_rules / commands 三类输出同一句 「…会使上游前缀缓存失效（约 0.35 元/次）…请开新会话」。但 slash 命令只在调用时展开、不进系统提示， 改它不必开新会话；该文案会诱导一次无谓的新会话（重注入 HANDOFF + 重建上下文同样要花钱）。
2. Hook 注入与技能 description 冲突——Hook 强制「读 docs/ 档案前加载 reading-docs-for-context」， 而该技能 description 写「不适用于需要改动系统状态的变更场景」；C 类变更前查阅既有 SOP 正是高频场景。
3. 5 个自建技能 frontmatter 不合规——违反内置 skill-creator 规范：name / description 带引号、 description 含尖括号、长度超 200 字符。这是此前两轮都未检查的维度。
4. 版本管理表述与事实不符——git check-ignore 报「不是 git 仓库（或者任何父目录）」：token_proxy 根目录既无 .git 也无 .gitignore；而两个技能与一条规则共四处要求「纳入版本管理」「.gitignore 必须包含 .venv/」。
5. 既存瑕疵——docs-read-guard.py 的 docstring 含未转义反斜杠，每次执行向 stderr 抛 SyntaxWarning: invalid escape sequence '\.'；docs-read-hook/state/ 无回收，已积 10 个 0 字节文件。

另有三处「同一事实写两处」：venv 环境（规则 vs 技能）、SOP 第 5 章写法（规则已收敛、技能仍复述）、 技能内共享库清单（同文件内两节重复）。

经判断不改（留档）

• PostToolUse 的 matcher 仍为 *，每次工具调用都起一个 python3。收窄需改 hooks.json 并重启 Trae， 且 Trae 的 matcher 是否支持多工具正则未经验证，失败模式是提醒静默失效，而收益仅毫秒级 → 不动。
• PreToolUse 返回 permissionDecision: "allow"、WRITE_TOOLS 不含 RunCommand：前者只挂 Read， 无实质风险；后者属漏报可接受的取舍 → 不动。
• developing-python-deploy-scripts 的目录结构节与共享库节重复列 4 个模块文件：属示例性重复， 保留便于单节阅读 → 不动。

变更与证据

实现体 agent-config-fix2-20260923/apply_changes.py（幂等：预检锚点唯一性 → 备份 → 写入 → 台账）。 被改 11 个文件：5 个技能 SKILL.md、2 个全局规则、2 个守卫脚本，以及上轮交付物内的 tests_guard_cases.py 与 verify_changes.py（上轮断言随本轮演进更新）。

证据（2026-09-23 实测）：

• 本轮 verify_changes.py：26/26 项达标
• tests_guard_cases.py：20/20 通过（由 18 项扩至 20 项，新增「commands 不得提开新会话」与 「skills 须提开新会话」两条分档文案用例）
• apply_changes.py 复跑：零变更、全跳过（幂等判据成立）
• 上轮 agent-config-fix-20260923/verify_changes.py：12/12 项仍达标

过程记录（供复盘）

改 tests_guard_cases.py 的两处断言时连续出现两次锚点边界错误：第一次 old 取了已被替换掉的原文 （0 命中），第二次 new 越界、把 return True 行重复写入而产生 SyntaxError。改为「从备份恢复 + 单行锚点替换」后一次通过。教训：多行块锚点在「同一文件被多轮修改」的场景下容易失真，单行锚点更稳； 实现体必须支持预检、失败时整体不落盘。

交付物：见 agent-config-fix2-20260923/（八章 SOP.md、apply_changes.py、verify_changes.py、 backup/）。

三十六、Hooks / Rules / Skills 第四次审查与修复（2026-09-23）

性质：C 类变更（改 2 个守卫脚本、2 条全局规则、1 个用例文件，并重写 2 份档案）。 hooks.json 未改动，无需重启 Trae；计量代理与报表未动，无停服。 完整 SOP（八章）见 agent-config-fix3-20260923/SOP.md，本节为档案条目。

36.1 背景

第三十五节（第三轮）之后按同一口径做第四次通读。触发条件：用户要求「再次检查 Hooks、rules、skills 是否有不合理的地方」。审查以内置 skill-creator 规范与三十四、三十五节为判据，用户确认「全改」。

36.2 发现（按严重度）

1. P1 守卫脚本会崩溃——skill-edit-guard.py 只捕 JSON 解析失败（ValueError），当 stdin 是 合法但非对象的 JSON（[] / "x" / 123 / null）时，event.get 抛 AttributeError， 脚本以退出码 1 结束并向 stderr 写约 415 字节 traceback（4 种输入实测全部复现）。这既违背 脚本自身「始终以退出码 0 结束」的承诺，也与 docs-read-guard.py 的外层兜底不对称。
2. P2 口径冲突——rule-ops-scenario-routing.md 要求「必须整体重写」HANDOFF，而 writing-handoff 技能要求「按状态增量分档，1~2 处用定点修订」。规则优先级高于技能，实际会强制走技能自己论证过 更贵的那条路。
3. HANDOFF 逼近硬上限——实测 7940 字节，既超 7 KB 目标，也越过技能自定的「> 上限 − 0.5 KB 即 强制整体重写」阈值（7680 字节）。
4. 低优先——docs-read-guard.py 的 emit(event) 形参未被使用；_prune_state 删除文件静默无留痕 （与脚本安全红线「删除文件属于高危操作，必须在日志中醒目标记」相悖）；技能索引表未覆盖 commands/，也未说明一次变更可同时加载多个技能。

36.3 经判断不改（留档）

• PreToolUse 注入文案与 alwaysApply 规则内容重叠（净增信息 ≈ 0）：这是「必然 > 概率」的 有意冗余（第二十五节论证），保留。
• commands/deploy-py.md 的 frontmatter 仍带引号：命令文件的 frontmatter 规范未知，去引号有影响 Trae 命令解析的风险，收益仅风格统一 → 不动。
• skill-config.json（技能启用 / 禁用配置）未纳入守卫监视：其是否影响上游前缀未验证，纳入需 新增文案分类分支 → 不动。
• posttooluse-probe.py 保留：README 已注明为「验证探针（备用）」，可复测回注通路。
• 第 34.9 节遗留的「去重键在 session_id 缺失时退化为全机器注入一次」仍未处理，影响低。

36.4 变更与证据

实现体 agent-config-fix3-20260923/apply_changes.py（幂等：预检锚点唯一性 → 备份 → 写入 → 台账）， 12 项改动、5 个被改文件：2 个守卫脚本、2 条全局规则、1 个用例文件。

证据（2026-09-23 实测）：

• P1 修复前后对照：[] / "x" / 123 / null —— 修复前退出码 1、stderr 约 415 B；修复后 退出码 0、stderr 0 B
• 守卫离线用例：20 项 → 24/24 通过（新增 4 条非对象 JSON 健壮性用例）
• 本轮验收器：24/24；上轮验收器：26/26 无回归
• 幂等复跑：零变更、全跳过，未新增备份、未追加台账
• HANDOFF：7940 → 7098 字节（≤ 7168 目标，硬上限 8192）

36.5 过程记录

本轮实现体改用单片段锚点（不再用大段多行块），12 项一次预检全过，未复现第三十五节那种多行块 锚点失真。

另：本轮改规则是经 RunCommand 调实现体完成的，而 WRITE_TOOLS 白名单不含 RunCommand，故 PostToolUse 守卫全程未提醒——「改完开新会话」需人工记住（该漏报属已决策的可接受取舍）。

交付物：见 agent-config-fix3-20260923/（八章 SOP.md、apply_changes.py、verify_changes.py、 backup/）。

三十七、HANDOFF 上限 10K + 中文指令固定注入 + 多项目铺开 + 部署技能口径收紧（2026-09-23）

诉求（用户一次提出四项 + 一项评估）：① HANDOFF 上限 8 KB → 10 KB；② 把「请全程用中文思考和回答」 做成每会话自动注入；③ HANDOFF 仅对 token_proxy 生效，其它运维项目（部署脚本 / 多主机排障 / 巡检 / 咨询）拿不到交接快照；④ developing-python-deploy-scripts 触发面过宽，简单问题被拖重；⑤ 评估 ④ 的联动。

裁定： - 第 3 项规则层已覆盖——A/B/C/D 四类时机与运维场景一一对应，瓶颈在 hooks.json 的注入路径写死。 - 第 4 项不收窄为「仅部署脚本」：那会漏掉「改造既有部署工程」与「多主机可复用采集工具」两类； 判据改为是否维护需长期复用的脚本工程。 - 「中文指令」落点选 hooks.json 的 SessionStart（全项目自动）+ 全局规则「输出语言」节（双保险）， 不放 HANDOFF 首句（只覆盖单项目、且整体重写易丢）。手动输入仍是效果最好的方式，其权威性注入无法 完全复刻——标【未验证】。

落地： - writing-handoff：上限 10 KB / 目标 8.5 KB，强制重写阈值改按目标值判。 - rule-ops-evidence-constraints「输出语言」：由「思考过程必须用中文」扩到「思考过程与回答正文一律用中文」。 - developing-python-deploy-scripts：description 与适用边界表收紧；rule-skill-index 条目、 writing-ops-change-sop 实现体措辞同步（组 4c，见下）。 - 新增 sessionstart-hook/session-start-inject.py（层 0）：注入中文指令 + 按工作区向上 4 层查找 docs/HANDOFF.md，找不到回退本项目固定路径（零回归），并向 state/session-start.log 留痕一行； hooks.json 的 SessionStart 改指向它。

过程（两处自我修正）： 1. 首轮执行暴露备份缺陷——同一文件的多处改动共用同一时间戳备份名，后者覆盖前者，备份落成 中间态而非原点。改法：补 --revert（Edit 反向替换、新文件内容一致则删除）+ unique_backup_path() （按文件去重、任何修改之前一次完成、绝不覆盖）；回退 → 清理错误备份与台账 → 重新应用。 2. 整体复验发现 writing-ops-change-sop 要求「实现体由 developing-python-deploy-scripts 规范的工程承载」， 与新口径冲突（本轮 apply_changes.py 恰是这类一次性脚本）。改措辞消除冲突。

验证：核验 32/32、幂等复跑零变更（备份稳定在 6 + 2）、守卫用例 24/24、docs/HANDOFF.md 重写后 须 ≤ 10240 字节。

交付物：handoff-10k-20260923/（八章 SOP.md、apply_changes.py（含 --revert）、verify_changes.py、 backup/）；长期资产 sessionstart-hook/session-start-inject.py。

三十八、Hooks 第五轮复查与 4 处修补 + 上游缓存命中机制实测归因（2026-09-23）

诉求（两件）：① 复查 Hooks / Rules / Skills 是否仍有不合理处；② 解释「重复问同一个问题，在新会话里 到底是缓存命中还是未命中，开新对话是否等于全新输入」。

诉求 ② 的实测结论（本轮最有价值的产出，改变了后续成本决策的依据）：

• 缓存按请求前缀匹配，不按「问题」匹配——重复的提问文本本身不带来任何命中。
• logs/usage.jsonl 5029 条 / 53 个会话：新会话首轮 prompt 中位 24498、命中中位 10752（≈25%）、 未命中中位 16848；同会话后续轮 prompt 中位 200192、命中中位 198464（≈100%）、未命中中位 591。
• 用户连续四次问同一句「再次检查我的 Hooks/rules/skills」：prompt 稳定在 28.1~28.4k，命中 6784~6912 （23~24%，仅 02:34 那次因前序会话前缀延续达 79%），每次约 2.1 万 token 按未命中价重付。
• 归因（logs/req_shape.jsonl 结构指纹）：各会话第一条 system 消息只有 6 种取值（system:20295:* 复用 12 次），20295 字符 ≈ 6.8k token，与命中 6784 吻合；第二条注入消息每会话都不同 （长度 5875~6049，指纹无一重复）——差异点自此开始，其后整段失效。
• 推论：新会话省掉的是「不带历史」（那部分根本不计费），不是「输入全新」；命中上限卡在 system 消息长度。 也顺带解释「改 rules/skills 约 0.35 元/次」——rules 在 system 里，一改指纹即变，前缀从第 0 块起失效。

诉求 ① 的裁定：结构无问题，4 处实现缺口要改；原报的「前缀匹配过宽」经复查撤回（常量已带尾斜杠， skills-evil 用例早已覆盖）。

落地（4 项，全部只改脚本，未动 hooks.json，无需重启 Trae）：

编号	文件	改动
C1	posttooluse-guard/skill-edit-guard.py	加会话去重：同 (session_id, agent_id) 只提醒一次；缺 session_id 则不去重（去重键退化会让提醒永久静默，比重复注入更坏）
C2	sessionstart-hook/session-start-inject.py	删除跨项目兜底：找不到 docs/HANDOFF.md 即不注入。实测证据 /tmp/tmp_laojof2 → token_proxy/docs/HANDOFF.md；逐级向上 4 层已覆盖子目录场景，兜底只会把无关项目状态注入进来
C3	同上	加长度护栏 MAX_INJECT_BYTES = 12288（10 KB 硬上限的 1.2 倍），超限截断并附提示
C4	同上	留痕字段如实：event_cwd / proc_cwd / handoff / bytes / truncated（原 cwd= 取自 Path.cwd()，无法据此判断动态查找是否用上事件工作区）

验证：核验 14/14、离线用例 31/31（新增会话去重组 1 项、SessionStart 组 6 项）、幂等复跑零变更 （第二次「待变更 0 项，已达标 3 项」）、hooks.json SHA 未变。

交付物：hooks-fix-20260923/（八章 SOP.md、apply_changes.py（默认预演 / --apply / --revert）、 verify_changes.py、new/、backup/ + 台账、logs/apply.log）；长期资产为三个被改脚本与扩至 31 项的 agent-config-fix-20260923/tests_guard_cases.py（该文件作为守卫用例的唯一回归入口）。

三十九、输出成本优化：新增执行效率规则（2026-09-23）

背景：用户追问「少输出有什么方案」。当日账单（00:01–03:45）实测：689 条请求 / 9 会话 / ¥7.90， 其中输出 ¥4.71 占 59.8%。输出拆解：1,194,695 token = 思考 774,448（65%）+ 可见回答 420,247（35%）。 按 turn_key 聚合后暴露真正的放大器：697 条请求只对应 40 个用户轮次 = 17.4 步/轮 （p50 11、max 65），每一次工具步进都是一次完整的重新推理。当日输出成本中 42% 花在 7 轮重复的 开放式检查上（「请再次检查一下我的 Hooks，rules，skills 是否有不合理的地方」同类问法 7 遍， 合计 260 步 / ¥2.02）。

方案取舍（与用户共同裁定）：

杠杆	裁定	依据
① 减少轮次（并行调用、脚本聚合、点名范围）	采纳，固化为规则	零副作用，收益最大
② 思考降档 / 关闭	否决（用户要求）	thinking.inject 保持 false，不关不降
③ 约束可见回答长度	采纳，并入同一条规则	只影响 35%，几乎零成本
④ 注入 max_tokens	否决	收益仅 6%（输出 >8k 仅 7 条），截断长回答=任务失败
⑤ 换 GLM-5.3-Flash	否决	输出价低 30%，但缓存命中价 ¥0.23 vs ¥0.02（贵 11 倍），命中率 97.6% 时净亏
⑥ 换 deepseek-v4-pro	否决	输出价 ¥13.5/百万，是 Flash 的 3.4 倍

口径订正（修正第三十八节末尾那句）：「改 rules/skills 约 0.35 元/次」不准确。0.35 元是 「改完仍在旧会话内继续对话」的代价——system + tools + 十几万 token 历史整段按未命中价重算 （18.4.1 实测：58 条失效请求 6.077 元；09-19 单日 16 条 / 2.850 元）。按正确做法改完立即开新会话， 只付新会话首条 ≈ ¥0.03（本日 9 个新会话首轮实测均值 ¥0.0307，与第 1171 行同口径）。 旁证：本日 02:39 / 03:02 / 03:23 三次规则文件改动后，正在运行的会话 miss 无凸起（数百至数千）， 证实改动只对新会话生效。

落地：新增全局规则 ~/.trae-cn/user_rules/rule-agent-efficiency.md（5 条执行方式 + 4 条边界 + 停止判据「探索性读取超 5 次仍无结论即停」），并落盘 output-cost-20260923/提问对照卡.md （用户侧 6 组实测对照 + 通用提问模板）。规则文件为纯新增，proxy.py / config.yaml / hooks.json 均未改动，代理未重启。

验证：verify_changes.py 11/11 通过（含目标与源逐字节一致、三项文件指纹未变、幂等复跑零变更）。 交付物：output-cost-20260923/（八章 SOP.md、apply_changes.py（默认预演 / --apply / --revert）、 verify_changes.py、规则源文件、提问对照卡、backup/ + 台账）。

四十、Hooks 守卫去重红线修复与用例补强（2026-09-23）

背景：先跑 agent-config-fix-20260923/tests_guard_cases.py 列失败项，结果 31/31 通过、无失败项。 按「全绿不等于无缺陷」继续做了一轮只读取证（三个守卫脚本复制到 /tmp 下运行，避免污染真实 state/）， 实证出两处不合理，均属「全绿掩盖缺陷」：

项	问题	证据
P1	docs-read-guard.py 去重键写作 session_id or "nosession"，缺 session_id 时退化为固定值 nosession__noagent；该标记已实际落盘（mtime 02:59:03），此后所有缺 session_id 的 Read docs/*.md 永久静默 = 漏注入。skill-edit-guard.py 早有「缺 session_id 就不去重」处理，两脚本不对称	探针：缺 session_id 连续两次 → 第一次注入、第二次静默；docs-read-hook/state/nosession__noagent 实存
P2	用例只判退出码、不判 stderr，「退码 0 但 stderr 有输出」这条污染路径无人守	5 个判定点均只查 returncode

原 31 项抓不到 P1 的原因：run_docs_case 强制注入一次性 session_id；缺 session_id 的用例只跑一次， 而「第一次必定命中」，故固定键退化永远不红。

落地（13 项，2 个文件，实现体 agent-config-fix4-20260923/apply_changes.py）：docs-read-guard.py 3 项——docstring 补第四次修复记录、设计约束 3 补例外、main() 去重块前加短路（缺 session_id 直接 emit() 返回、不写标记）；tests_guard_cases.py 10 项——新增 check_process()（退出码 + stderr 双红线） 并接入全部 5 个判定点、新增 run_no_session_case()（缺 session_id 连续两次都必须命中）与 run_docs_dedup_case()（带 session_id 时第二次必须静默）、main() 注册 3 条新用例。用例数 31 → 34。

验证：34/34 通过；幂等复跑零变更、全跳过；反向验证——用备份的旧脚本跑同一套用例恰好 1 条 FAIL， 信息为「缺 session_id 时第二次调用静默（去重键退化，提醒/注入永久失效）」，33/34。脚本即时生效， 未改 hooks.json、无需重启 Trae。

本轮审查发现但未修的其余缺口（后续待办依据，均为只读取证所得）：

1. 31 项全部绕过 hooks.json：路径写错 / matcher 与脚本判定的 tool_name 不一致 / timeout 缺失时， 用例仍全绿而 Hook 静默失效 —— 恰是 HANDOFF 点名的失败模式。建议补静态校验用例。
2. TARGET_RE 要求 docs 前有分隔符 → 相对路径 docs/SOP.md 不注入（实测）。
3. EXCLUDE_RE 只列 8 个目录名，缺 .tox / build / dist / vendor / target / .pytest_cache。
4. 用例注释称「不触碰真实」，实际会写真实 state/ 去重标记；run_sessionstart_log_case 还会往真实 session-start.log 追加行，且把日志路径硬编码为 token_proxy，与 --project 参数矛盾。
5. _handoff_marker() 直接读 docs/HANDOFF.md，文件缺失即整集崩溃（连 PASS 汇总都没有）。
6. 写类工具白名单 6 个只测 3 个（Write / SearchReplace / DeleteFile）；Trae 若改名（如 SearchReplace → StrReplace）会静默失配，用例也不会红。
7. prune.log 受同一保留期规则管理，7 天无写入会被自身删除，与「高危动作可追溯」冲突。
8. 监视面匹配语义不一致：三个目录用前缀匹配（skills/** 下的 .bak 备份文件也提醒），hooks.json 用精确相等（hooks.json.bak 不提醒）。

交付物：agent-config-fix4-20260923/（八章 SOP.md、apply_changes.py、backup/ + README.md 台账）。

四十一、hooks.json 接线静态校验（缺口 1 结项）（2026-09-23）

背景：第四十节登记 8 项未修缺口，第 1 项危害最大——全部 34 项用例都直接 python3 <脚本> 调用， 绕过 hooks.json 这条真实链路。后果：脚本路径写错、脚本被移动改名、matcher 与脚本实际判定的 tool_name 不一致、timeout 缺失或过大时，用例仍全绿而 Hook 静默失效。即此前只能证明「脚本自洽」， 不能证明「Hook 自洽」。用户批准后本轮补上。

落地（只改 agent-config-fix-20260923/tests_guard_cases.py，用例 34 → 44）：新增常量表 EXPECTED_MATCHERS（SessionStart=None / PreToolUse=Read / PostToolUse=*）与 EXPECTED_SCRIPTS （三个事件各自应挂的守卫脚本名），以及 script_path_from_command()（从 command 中抽 $HOME / ~ / 绝对路径）与 run_hooks_json_cases()（10 条断言：文件存在且合法、三事件齐全、每事件 matcher 与脚本 判定一致、脚本挂对且存在非空、timeout 1–60s、command 以 exit 0 收尾），并在 main() 注册该组。

验证：真实配置 44/44 通过；反向验证——用 --root /tmp/fakehome5 造坏配置（PreToolUse 改挂 skill-edit-guard.py、matcher 改 *、timeout 改 300、去掉 exit 0、删掉 SessionStart），逐条报出 6 条 FAIL，定位准确（缺失事件 / matcher 不一致 / 实挂脚本错 / timeout 超限）。真实 hooks.json 全程 未改，假 home 只写 /tmp。

残余风险：校验只覆盖 hooks.json 的内容接线，不覆盖「Trae 是否真的读取并执行该事件」——后者无法 离线验证，真机表现为 Hook 不触发，可用 state/ 目录是否出现新标记判断。

交付物：agent-config-fix5-20260923/（八章 SOP.md、backup/README.md 台账 2 条）；被改文件 agent-config-fix-20260923/tests_guard_cases.py。

四十二、回归用例隔离改造与日志路径相对化（缺口 4 结项）（2026-09-23）

背景：第四十节缺口 4——用例注释称「不触碰真实」，实际每跑一次回归就往真实 sessionstart-hook/state/session-start.log 追加一行（95 行里约有一半来自跑用例），并在 docs-read-hook/state/ 留下去重标记；run_sessionstart_log_case 还把日志路径硬编码为 token_proxy， 与 --project 参数矛盾。根因是状态落点写死：session-start-inject.py 的 STATE_LOG 用 Path.home() 拼绝对路径，用例又直接用真实工程的脚本与 state/。

落地（2 个文件）：① session-start-inject.py 的 STATE_LOG 改为 Path(__file__).resolve().parent / "state" / "session-start.log"（与两个守卫脚本的 STATE_DIR 同口径， 现有日志位置不变——脚本本就位于该目录），docstring 补第五次修复记录；② tests_guard_cases.py 新增 build_sandbox()（shutil.copy2 复制三个守卫脚本 + 造最小 docs/HANDOFF.md），main() 先建镜像、 project 指向镜像、结尾 rmtree 清理；run_sessionstart_log_case 的日志路径改为脚本同级 state/。 顺带消除缺口 5：_handoff_marker() 不再读真实 docs/HANDOFF.md，改用镜像内自造内容， 「真实 HANDOFF 缺失导致整集崩溃」的路径不复存在。

验证：44/44 通过；真实 state/ 与日志零写入——跑前跑后 docs-read-hook/state 17 个、 posttooluse-guard/state 0 个、sessionstart-hook/state 1 个、日志 95 行、三处内容指纹 27d39e106ea7d51ede5b183a53c6e406 完全一致（改造前每跑一次日志 +1 行）；/tmp/guardcases-* 残留 0； 反向验证——旧 docs-read-guard.py 在镜像里跑仍报同一条 FAIL（43/44），隔离未削弱抓漏能力。

剩余缺口：原 8 项已结 3 项（第 1、4、5 项），余 5 项见四十节清单。

交付物：agent-config-fix6-20260923/（八章 SOP.md、backup/README.md 台账 4 条）。

四十三、写类工具白名单覆盖补全 + 常量一致性断言（缺口 6 结项）（2026-09-23）

背景：第四十节缺口 6——写类工具白名单 6 个只测 3 个（Write / SearchReplace / DeleteFile）， Trae 若改名会静默失配且用例不红。取证（只读）：

证据源	结论
logs/usage.jsonl（3.49 MB / 5265 行；顶层键 ts / route / model / status / bytes / usage / *_tokens）	不含工具名，对 10 个模式全量扫描命中 0，无法从用量日志取真实分布
posttooluse-guard/probe.jsonl（真实事件 3 条）	事件 stdin 11 个键，同时含 tool_name 与 llm_tool_name；脚本只读前者
本机 Trae 工具清单 + 历史实测（三十三/三十四节：SearchReplace 改规则稳定触发）	本机真实写类工具名为 Write / SearchReplace / DeleteFile，均在白名单；白名单里的 Edit / MultiEdit / NotebookEdit 属其它客户端命名，保留为零成本兼容

即白名单无需改，风险在「白名单与用例不同步」。落地（只改 tests_guard_cases.py，44 → 49）： 补 3 条用例（Edit 用 path 键、MultiEdit 用 target_file 键、NotebookEdit 用 notebook_path 键）， 使 6 个白名单工具与 5 个 PATH_KEYS 全部有覆盖；新增 load_guard_module()（按模块加载守卫脚本读常量） 与 run_guard_constants_cases()——把 WRITE_TOOLS / PATH_KEYS 与由用例事件动态提取的覆盖集合 核对，白名单增删而用例没跟上即红。

验证：49/49 通过（写类工具白名单全部有用例（6 个）-> 全覆盖、路径键全部有用例（5 个）-> 全覆盖）； 真实 state/ 与日志内容指纹跑前跑后一致（7e2b12054b0480d070cf87bed3f69d05）；反向验证——副本白名单 加入 "FakeNewTool" 后报 [FAIL] 写类工具白名单全部有用例（7 个） -> 未覆盖：FakeNewTool（48/49）。

残余边界：一致性断言保证「白名单 ↔ 用例」同步，保证不了 Trae 单方面改名——需一次真机写操作 触发提醒来确认（步骤见 posttooluse-guard/README.md）。另，事件里的 llm_tool_name 当前未被脚本读取， 已记为观察项（无证据表明会缺 tool_name，故不做防御性改动）。

交付物：agent-config-fix7-20260923/（八章 SOP.md、backup/README.md 台账 3 条）。

四十四、守卫边界收口（缺口 2 / 3 / 7 / 8 结项）（2026-09-23）

背景：第四十节 8 项缺口的最后 4 项，全是边界口径问题——TARGET_RE 要求 docs 前有分隔符 （相对路径漏注入）、EXCLUDE_RE 只列 8 个目录（构建产物内 docs/*.md 误注入）、prune.log 受同一 保留期管理（7 天无写入被自身回收，高危记录丢失）、目录用前缀匹配而 hooks.json 用精确相等 （写 skills/x/SKILL.md.bak.<ts> 这类备份也提醒，属误导）。

落地（3 个文件，用例 49 → 54）：① TARGET_RE 改为 (?:^|[/\\])docs[/\\].+\.md$； ② EXCLUDE_RE 补 .tox / build / dist / vendor / target / .pytest_cache / .mypy_cache / .ruff_cache / .next / .nuxt；③ 两个脚本的 _prune_state 对 prune.log 直接跳过； ④ skill-edit-guard.py 新增 BACKUP_RE = r"\.bak(\.|$)"，命中判定前跳过备份文件；⑤ 回归集补 5 条用例 （相对路径应注入、build/target 内应静默、监视目录内 *.bak 应静默、hooks.json.bak 应静默）。

验证：54/54 通过；真实 state/ 与日志指纹跑前跑后一致（7e2b12054b0480d070cf87bed3f69d05）； 反向验证——用改动前的两个守卫脚本跑，恰好 4 条 FAIL（备份文件误报、相对路径漏注入、build/target 误报各一），50/54（hooks.json.bak 用例不红属预期，那是防回归条目）。

至此第四十节登记的 8 项缺口全部结项（1/4/5/6 见四十一～四十三节）。

交付物：agent-config-fix8-20260923/（八章 SOP.md、backup/README.md 台账 5 条）。

四十五、轮次口径修复：新增 turn_seq（步/轮 可算准）（2026-09-23）

背景：用户要求「先算一下步数和成本」。算的过程中发现分母不可靠：turn_key = 末条用户输入的 哈希，用户重复发同一句话（如连说多次「好的，执行吧」）会被合并成一轮。本会话实测：实际 10 次用户 输入被算成 6 轮 → 「步/轮」20.7 实为 12.3（偏差约 7 成）。用「相邻请求时间间隔」切分校正失败 （120s 阈值把 10 轮压成 3 轮、300s 压成 1 轮——长任务里 Agent 连续工作，间隔分不开）。故只能改数据源。

落地（2 个文件 + 1 个验证脚本）：① proxy.py 的 _extract_turn_meta 新增 turn_seq = len(texts)（会话内 <user_input> 条数：同轮内多次步进不变、用户新发一次 +1）， empty 与 meta 模板补键，_record 落盘该字段；② cost_audit/analyze_usage.py 新增 turn_id_of()， 轮次标识优先 conv_key#turn_seq、旧记录回退 turn_key；③ 新增 turn-seq-fix-20260923/verify_turn_seq.py（假上游 + 临时端口，不碰生产 8788 与 logs/）。

验证：离线 9/9 通过——turn_seq 依次为 1,2,3,4,4、旧口径事实（重复同一句话的两次提问 turn_key 相同，会被合并）、新口径结果（两条记录的轮次标识不同、同轮重复步进标识相同）、 内部调用为 None、日志无异常栈；改后分析脚本跑旧数据（无 turn_seq）正常，轮次计数不变（回退生效）。

生效与实测：proxy.py 是 systemd 服务，需重启才生效——已于 04:50:56 重启 （systemctl --user restart token-proxy，随后 healthz 200、服务 active）。生效证据：04:51:05 的记录 turn_seq=11，与本会话真实用户输入条数（11 次）一致，而旧口径只算得 6 轮；同一会话内 turn_key 仍是 同一个哈希（5 次「好的，执行吧」文本相同）——这正是旧口径把多轮合并成一轮的直接证据。 04:51 之前的历史记录没有该字段，「步/轮」在重启前后不可比，基线需从此后重新积累； 触发失败判据与回滚命令见 turn-seq-fix-20260923/SOP.md 第 6~8 章。

交付物：turn-seq-fix-20260923/（八章 SOP.md、verify_turn_seq.py、backup/README.md 台账 4 条）。

四十六、Hook 守卫脚本误删恢复（2026-09-23）

背景：13:18~13:32 用户清理工程目录，误删 sessionstart-hook/ 整个目录与 docs-read-hook/docs-read-guard.py——当时的理解是「Hooks 只是 hooks.json 在生效」，脚本被当临时产物清掉。hooks.json 三条命令均为 [ -f "$s" ] && python3 "$s" || true; exit 0，脚本缺失即静默跳过，故故障表现是「无报错、也无注入」：SessionStart 的中文指令 + HANDOFF 注入、PreToolUse 的档案读取提示双双静默消失。posttooluse-guard/skill-edit-guard.py 未丢（现存版本已含第六次修复）。

数据源：Trae 回归「用例隔离」一轮在 /tmp/regress-check2|3|4/ 留下的项目镜像。

落地（2 个文件新建 + 1 个实现体）： ① sessionstart-hook/session-start-inject.py ← 镜像直接回填：三份镜像字节一致，且含「（五）：日志路径相对化」，即最终版； ② docs-read-hook/docs-read-guard.py ← 镜像为第四版、生产 pyc 为第五版；两者 co_code 完全一致，仅 4 处常量不同（模块 docstring 追加段、TARGET_RE、EXCLUDE_RE、_prune_state 的 prune.log 豁免），故由 hook-restore-20260923/restore_hooks.py 按 pyc 常量还原这 4 处，不直接使用镜像源码； ③ 恢复动作只新建文件、不覆盖任何现存文件；目标已存在且内容不同即报错退出。hooks.json 未改动。

验证：还原结果与生产 pyc 逐 code object 全等（co_code/co_consts/co_names 递归一致）；离线用例 4 项通过（正例注入 364 字节、非目标文件静默、依赖目录静默、SessionStart 注入 9233 字节且两项特征串各命中 1 次），四项均退出码 0、stderr 为空；留痕日志 5 字段齐全；hooks.json 三条路径齐全；实现体复跑幂等（第二次两行 [跳过]）。

未恢复项：agent-config-fix-20260923/tests_guard_cases.py（54 项统一回归入口）在全盘、/tmp、Trae 快照区与会话库均无副本（会话库 database.db 为加密格式，非 SQLite）。经用户决定不重建、不计入待办；此后守卫脚本的离线回归口径改以 hook-restore-20260923/SOP.md 第 6 章的用例表为准。

交付物：hook-restore-20260923/（八章 SOP.md、restore_hooks.py、backup/README.md 台账 2 条 + 验证痕迹登记）。

真机验收（2026-09-23 14:00 补记）：离线用例通过后，在新会话实测三层 Hook——

① SessionStart【通过】：首轮注入「请全程用中文思考和回答」+ HANDOFF 正文；state/session-start.log 末行 5 字段齐全（event_cwd / proc_cwd / handoff / bytes=9037 / truncated=no），与 HANDOFF 当时大小一致、未截断。

② PreToolUse【通过】：用 Read 读 docs/HANDOFF.md 时，工具结果前注入「【上下文成本约束】」additionalContext；docs-read-hook/state/6ab36a9aa5e95acebe11bce1__solo_agent（13:59:38）即该次命中的会话级去重标记，6ab36a9aa5e95acebe11bce1 为本会话 id。

③ PostToolUse【通过（当日早前实测）】：当日改 user_rules 时已实测稳定触发提醒（见 skill-edit-guard.py docstring）。本轮写的是 docs/HANDOFF.md，不在 WATCHED_DIRS / WATCHED_FILES 内，按设计静默且不写去重标记——state/ 无本会话标记属预期行为，非失效。

结论：Hook 链路完好，误删恢复验收闭合。

四十七、HANDOFF 机制空档补齐：未命中提示 + lustre_ins 首份快照（2026-09-23）

背景：用户在 /home/rain/Documents/lustre_ins 下连续数轮没有 HANDOFF 注入，判断「是不是失效了」。排查结论是机制没坏，卡在死循环起点——state/session-start.log 中该工作区四次记录全部 handoff=- bytes=0（14:06:58 / 22:15:03 / 23:26:23 / 23:28:00），同期 token_proxy 自身每次均正常注入（≈9.1 KB）。直接原因：该项目 docs/ 下从来没有 HANDOFF.md，脚本按设计「找不到即不注入」（第四十六节同款静默模式）；机制原因：writing-handoff 只规定怎么写，没有「新项目何时建第一个」的触发点，未命中时完全静默使失效不可见。判断：不恢复跨项目兜底——它注入的是 token_proxy 的错误快照，只产生错误记忆。

落地（2 个文件改动 + 1 个新建 + 1 个实现体）： ① sessionstart-hook/session-start-inject.py 新增 MISSING_HANDOFF_NOTICE 常量，main() 在「未命中」或「命中但内容为空」时注入该提示，命中路径的注入内容与行为完全不变，docstring 补修复记录（六）； ② ~/.trae-cn/user_rules/rule-skill-index.md：Hook 脚本的回归口径由 tests_guard_cases.py（第四十六节已记，误删且经用户决定不重建）改指 hook-restore-20260923/SOP.md 第 6 章用例表，消除规则与事实的漂移； ③ 新建 lustre_ins/docs/HANDOFF.md——该项目首份交接快照，按 writing-handoff 五节骨架，素材取自其 SOP.md / RUNBOOK.md / troubleshoot.md； ④ 实现体 handoff-bootstrap-20260923/apply_changes.py：把锚点唯一性校验前置到预检，使 dry-run 即暴露锚点漂移，不再产生「先备份、后失败」的中间态。

验证：离线 11/11 通过——未命中给出提示（rc=0、stderr 空、97 字节）；命中 token_proxy 注入 5412 字节且不含提示；命中 lustre_ins 注入 3625 字节且含 edafs；规则两处口径断言通过；新快照 6011 字节（上限 10240）；两目标备份与台账齐备；hooks.json 三处脚本接线齐全。实现体复跑幂等（「变更 0 项，跳过 2 项」）。调试期两次中止（锚点前缀取错、插入型替换的校验误判）均止于写盘之前，被改文件未受影响，等价副本已在台账登记。

不改 hooks.json，故无需重启 Trae；脚本改动即时生效。

交付物：handoff-bootstrap-20260923/（八章 SOP.md、apply_changes.py、verify_changes.py、backup/README.md 台账 4 条）。

四十八、新增小米 MiMo 模型路由（2026-09-24）

背景：用户已对接小米模型（https://api.xiaomimimo.com/v1，mimo-v2.6-flash），要求代理新增该上游以记账计价。

改前实测（A 类只读，测试 key 用后即删未留档）：非流式与流式均返回 OpenAI 式 usage（prompt_tokens_details.cached_tokens，completion_tokens_details.reasoning_tokens 存在），与 GLM 同构——现有 proxy.py 提取与 cost_report.py 的 GLM 回退逻辑直接兼容，零代码改动；上游回显模型名与价目表规范名一致，无需 aliases。

变更（仅 config.yaml 3 处纯新增）：头注释加 /mi 行；routes 加 mi: https://api.xiaomimimo.com/v1；pricing.models 加 mimo-v2.6-flash（实时推理价 0.02/1.0/2.0 元/百万，不分峰谷 peak=off_peak，来源官方「模型国内定价」页，价目表截图由用户提供）。thinking 段不动（inject: false 全局不干预）。

执行插曲：一次编辑误将 deepseek-v4-flash 的 off_peak.output 4.0 改成 4.5 且漏加小米条目，当场发现，第二次编辑恢复 4.0 并补齐；最终 diff 对备份确认恰好 3 处纯新增、无残留。

验证：restart 后服务 active、/healthz 返回 ['ds','glm','mi']；YAML 解析断言全过（含 v4-flash 价未被误改）；幂等复跑零变化。

交付物：mi-model-20260924/（八章 SOP.md、backup/config.yaml.bak.20260924-123412 + README.md 台账）。遗留：原「Trae 侧配置与首条 route=mi 记账核对」已于 2026-09-24 12:40 真机闭环——usage.jsonl 首条 route=mi 记录 status 200、cached_tokens 走 GLM 回退计价正常（prompt 22 / completion 78 / total 100），全链路结项。

四十九、PostToolUse 守卫 skills 命中面收窄 + HANDOFF 拆稳定层（2026-10-02）

背景：用户要求复测「改 skill 正文 / references/（不改 description）是否触发上游前缀重建」，并据此调整 PostToolUse 守卫（skill-edit-guard.py）的注入文案。

复测（本会话 23 步，取数走 logs/usage.jsonl）：cache_hit_tokens 从 6,784 单调递增至 127,104、无回落；写报告那步 miss=11,410、读 references/（约 33 K）那步 miss=32,904、改动 references/ 那步 miss=1,584、跨用户轮次后首请求 miss=2,339 —— 均为「新内容一次性未命中」，不是前缀重建（对照：改 user_rules 实测全量重建 miss=364,998）。结论成立：只有 SKILL.md 的 frontmatter description 进每轮前缀，skill 正文与 references/ 按需加载。

变更：posttooluse-guard/skill-edit-guard.py 收窄 skills 命中面——删 WATCHED_DIRS，新增 SKILL_FILE / DESCRIPTION_RE / CONTENT_KEYS 与 _touches_description()；skills 下仅「文件名为 SKILL.md 且改动文本含 description:」才计入提醒，references/ 与 skill 正文静默；文案改为「全局规则或 skill 的 frontmatter」。不改 hooks.json，脚本即时生效、无需重启 Trae。

验证：hook-skill-desc-20261002/verify_guard_cases.py 14 项全 PASS（含新增的 references/正文静默、description 提醒、同会话去重、非对象 JSON 边界），两条红线（退出码 0、stderr 空）全过。真机正向对照（改 description → 全量重建）沿用 2026-10-01 旧实测，已登记待补。

连带纠正：HANDOFF 与 docs/BASELINE.md 中「改 skill 就须开新会话」的表述，同步改为「改 user_rules 或 skill 的 description」。

HANDOFF 结构性调整（超硬限修复）：修订后 HANDOFF 一度达 10,829 B，超 10 KB 硬上限（失败判据），遂按 writing-handoff 整体重写并首次拆出稳定层 docs/BASELINE.md（环境事实 / 机制与陷阱 / 命令速查 / 文档地图），HANDOFF 降至 5,823 B（目标 6 KB 内）。docs/PROJECT-MAP.md 按该技能应建（根下 ≥3 个主题目录）但本轮未做，已挂账 HANDOFF 3.1。

交付物：hook-skill-desc-20261002/（八章 SOP.md、verify_guard_cases.py、backup/README.md 台账 2 条：守卫脚本 + HANDOFF）；另新增 docs/BASELINE.md。

五十、给 req_shape.jsonl 补工具名（2026-10-02）

背景：step_profile.py 要回答「哪几步可合并」，但 req_shape.jsonl 每步只记 角色:字节数:哈希，无工具维度；上个主题实测其「疑似可合并组」判据对字节阈值跨 26 倍敏感（2.2%~57.6%），不可用。根因收敛到「缺工具名」，挂账为全局总账 #21（需改 proxy.py，红线级）。

变更（C 类，单机）：① 采集端 proxy.py——build_shape_fingerprint 新增 shape.tool_names（本步末尾最近一次 assistant 工具调用的名字列表，只记名字、不记参数与路径），新增 _tool_names()；head/tail 格式未改，analyze_prefix_fail.py 不受影响。② 消费端 cost_audit/step_profile.py——新增 tools_of() / merge_groups()，明细加「工具」列，并把「可合并组」分档为「只读组」（组内工具全为 Read/Glob/Grep 等，更可信）；旧记录无该字段时退化为原弱信号。

验证：离线脚本 shape-toolname-20261002/verify_shape_tools.py 两段共 15 项全过（A 纯函数 7 项含脱敏断言、B 假上游端到端 8 项含转发链路未断）；重启 token-proxy 后即刻落盘 tool_names（首条为 ["RunCommand"]），旧记录向后兼容。

交付物：shape-toolname-20261002/（八章 SOP.md、verify_shape_tools.py、backup/ 台账 3 条）。回滚：cp 回 backup/proxy.py.bak.20261002-162823 与 backup/step_profile.py.bak.20261002-163616 后 systemctl --user restart token-proxy。

五十一、代理层注入固定「推理约束」提示（2026-10-02）

背景：实测输出成本大头是模型思考（13,984 步 reasoning_tokens 中位 517 tok、占输出约 60%）。社区针对推理模型的实践是在系统提示加推理约束，但 Trae 不提供编辑 Agent 系统提示的入口，故落到自建代理层。

变更（C 类，单机）：config.yaml 的 thinking 段增 prompt_hint（固定文本，置空即关）；proxy.py 新增 apply_prompt_hint()（追加到首条 system 末尾，幂等、支持多模态 text 块、无 system 不动），parse_thinking_config() 解析并在 json.dumps 前调用，启动摘要增「推理约束=开」。第 1 条由"唯一目的是调工具"放宽为"决定下一步动作（调用工具或给出结论）"，以免损伤分析/写作类任务。

验证：离线 prompt-hint-20261002/verify_prompt_hint.py 18 项全过（A 纯函数 8 + B 假上游 10，含"上游确实收到 hint、只出现 1 次、thinking/effort 仍在"）；真机重启后启动日志出现「推理约束=开」。已知局限：req_shape 的 system 指纹在注入之前计算，故不反映 hint。

效果：待观察（与生效前对比 reasoning_tokens 中位与思考占比，同时盯返工）。回滚：恢复 prompt-hint-20261002/backup/ 两份备份并重启；或置空 thinking.prompt_hint 一键关闭。交付物：prompt-hint-20261002/（八章 SOP.md、verify_prompt_hint.py、backup/ 台账 2 条）。

五十二、用户级 Subagent ctx-scout 上线 + 积分门控切换（2026-10-02）

背景：实测成本 93% 集中在 ≥150k prompt 的请求，Subagent 的独立上下文可直接缓解。用户有 1666 Trae 积分，期望「积分足用内置模型、积分 < 200 改走代理只做上下文隔离」。硬约束（据 Trae 官方《子智能体(Subagent)》）：Subagent 的 model 只能填内置模型名，不支持自定义模型，且无法按次切换；不填 model 则跟随主模型。Trae 积分为账号侧数据、本机无可编程读取入口 → 门控只能人工触发。

变更（C 类，单机，全部新增）：① ~/.trae-cn/agents/ctx-scout.md——用户级只读 Subagent（tools: Read,Glob,Grep,Bash,WebSearch,WebFetch,Skill，无 Write/Edit），默认 model: DeepSeek-V4-Flash；② subagent-20261002/switch_subagent_model.py——一键切档（trae 写内置模型行 / proxy 删该行 / status 只看），幂等 + 原子写；③ ~/.trae-cn/commands/subagent-mode.md——Trae 内 /subagent-mode 入口，仅做「意图→参数」映射。

验证：离线 10 项实机全过（初始档位、重复切档零变更、proxy 删行且保留首行 ---、trae 还原、未知对象 [错误]+exit 2、正文完整）。踩坑：首版重组 frontmatter 时丢了首行定界符 ---，致 status 报 ValueError；已修并回归（SOP 第 5 章已留痕）。真机端到端待验：需 Beta「启用 Subagents 目录」为开 + 新会话，确认能被调用。

局限：内置档位名 DeepSeek-V4-Flash 取自官方「可用模型」表，真机是否被认待验；积分阈值（200）由人判断。回滚：删除三个新增文件即回到原点（rm -f ~/.trae-cn/agents/ctx-scout.md ~/.trae-cn/commands/subagent-mode.md; rm -rf subagent-20261002）；另 docs/HANDOFF.md、docs/PROJECT-MAP.md、docs/SOP.md、~/.trae-cn/user_rules/rule-skill-index.md 有同目录 .bak 备份。交付物：subagent-20261002/（八章 SOP.md、RUNBOOK.md、switch_subagent_model.py、backup/ 台账 4 条）。

五十三、给优化总账的过账加触发点（2026-10-02）

背景：优化总账（~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md）的过账此前只有正文里「每周过一遍」的人工约定，无触发点、无验收方——挂账项写下即沉底；与 2026-10-01 收尾清单两次漏执行同源。

变更（C 类，单机，全局）：① sessionstart-hook/session-start-inject.py 新增「过账提醒」注入段——会话启动时读总账，按「距上次过账 ≥7 天 或 挂账 ≥20 项」注入一行 [过账提醒]；判据（第一节挂账行数、第四节末行日期）全部由总账表格算出、不写状态文件（天然幂等、无过期清理）；解析失败一律静默、退出码恒 0。② 全局规则 rule-agent-efficiency.md 在收尾自查后新增「过账响应」硬门禁：注入提醒即须在答复中给出过账结论或不做理由。不改 hooks.json，故未重启 Trae；脚本下次开新会话生效，规则需开新会话。

验证：离线 backlog-review-20261002/verify_backlog_review.py 8 项全过（文件缺失静默、未达阈值静默、天数/挂账各自越阈值提醒、空表不崩且计数只认第一节、日期畸形静默、stdin 畸形退出码 0、与 HANDOFF 共存顺序稳定）；真实总账演练命中（挂账 20 项）；python3 -m py_compile 通过。

上限声明：这是「到点必提醒 + 必回应」，不是自动过账——决策与执行仍由人/AI 做，Hook 只解决触发、规则只解决回应。

交付物：backlog-review-20261002/（八章 SOP.md、RUNBOOK.md、verify_backlog_review.py、backup/ 台账 2 条：Hook 脚本 + 全局规则；全局规则备份存 ~/.trae-cn/user_rules/backup/）。回滚：恢复两处 .bak 即回原点。

五十四、重启代价与「攒批重启」口径（2026-10-08）

背景：代理重启此前被当成"无害操作"，实测不是。全量复盘 logs/proxy.log（38 条 代理启动）与 logs/usage.jsonl（19 946 个普通步）后得到一个比最初判断弱得多的结论——本文按如实口径记录，不要把弱证据当硬事实引用。

实测

对照（同会话空闲时长 × 是否刚重启过；19 946 个普通步）

分组	步数	miss 中位	大 miss（≥20 k）	占比中位
空闲 ≥1 h & 重启后	11	4707	5（45.5%）	15.9%
空闲 ≥1 h & 非重启后	47	1042	19（40.4%）	1.4%
空闲 <1 h & 重启后	21	596	4（19.0%）	0.5%
空闲 <1 h & 非重启后	19 928	643	227（1.1%）	0.4%

结论分两半——不要合成一句「重启代价 ¥X」

• 长空闲（≥1 h）组：重启与否几乎无差别（45.5% vs 40.4%）→ 这批大 miss 属上游缓存 TTL， 与重启无关，重启只是时间上撞在一起（这也解释了"我在别的窗口空闲很久"那类情形）。
• 短空闲（<1 h）组：19.0% vs 1.1%（17 倍） → 9 s ~ 89 s 的间隔不可能触发 TTL，这一组与重启相关； 但 n=4，且其中 1 例 hit=0（全冷）——hit=0 不是"前缀从中段断裂"，故「打断 → 重发 → 前缀断裂」 这条机制假说解释不了全部案例，机制未证实。

仍明确成立的两条（「攒批重启」的理由只用这两条）

1. 重启会打断在飞的流式请求，客户端须重发——可观测事实；
2. 重启会清掉内存态（thinking_stages / 缓存探测快照）→ 该会话的空闲保护缺席一次 （证据：2026-10-08 01:34:22，间隔 3.1 h、无探测日志、hit=0、全额重建 104 310 tok）。 第 2 条已由本次变更修掉（状态落盘）。

旧结论更正：既曾把「思考强度翻转」当主因（见下），也曾把 9 次大 miss ≈¥1.85 整体记作「重启代价」—— 同样是过度归因；正确账目就是上面那两半。

口径（攒批重启）：同一批要改的代理代码 / 配置改完再重启一次，不要「改一处 → 重启 → 再改 → 再重启」。 反驳过的一条替代解释：以前把大 miss 归给「思考强度翻转」，实测不成立——245 次阶段翻转里降级仅 7 次、 且 7/7 全发生在重启后，而最大的三次（42.4 万 / 35.1 万 / 24.9 万）强度根本没变（coding:high → unknown:high）； 翻转只是"刚重启过"的伴随标志。

顺带修掉的两处内存态：thinking_stages 与 cache_probe 快照原本只在内存、重启即丢 —— 2026-10-08 01:34:22 即为例（间隔 3.1 h、无探测日志、hit=0、全额重建 104 310 tok）。 两处改为启动时恢复、SIGTERM（systemctl restart 走的正是这条路径）时落盘，详见 state-persist-20261008/。

验证

cd /home/rain/Documents/services/token_proxy
grep -c '代理启动' logs/proxy.log                                     # 同批重启次数（>1 违反攒批口径）
tail -n 1 logs/proxy.log | grep -o '状态恢复=阶段[0-9]*/快照[0-9]*'   # 启动时恢复了多少内存态
ls -l logs/state/                                                     # 落盘文件确实生成

交付物：state-persist-20261008/（八章 SOP.md、RUNBOOK.md、backup/ 台账）。 回滚：恢复 state-persist-20261008/backup/proxy.py.bak.* 并重启；删除 logs/state/ 即回到无持久化行为。

---

五十五、HANDOFF 写入口径 v4（余量门槛）+ 本轮整体重写移出内容（2026-10-08）

背景：2026-10-08 下午一次 HANDOFF 写入把 10 507 B → 11 918 B，越过 11.5 KB 触发线。 skill《写入前置流程》⑤ 明写「≥ 11776 → 触发整体重写（不是回来压缩）」，当次却做了压缩（→ 11 433 B）= 违反。 根因是 v3 那句「不判本轮会不会超」走到了另一个极端：余量只剩 1781 B 仍直接写 → 越线 → 白写一遍。 v4 改为「实测余量 vs 1.5 KB 门槛」（只用读数、不估本轮内容）：余量 < 1.5 KB → 先整体重写（目标 ≤ 7 KB）再写本轮。

本轮整体重写（2026-10-08）：按 v3 定义只重写 §2 / §3，§1 / §4 / §5 逐字保留；终值 7 KB 以内。

移出 / 关闭的内容（自 HANDOFF §2·§3 移来，原件据此压缩；先移入再删）：

原位置	内容	去向
§2「上一轮 / 上前一轮 / 近几轮变更」三行	各轮变更明细（条款验收方补强 / 写入前置 v1 / wrapup.py 费用口径…）	各主题档案 */SOP.md；HANDOFF 只留一行指针
§3.1「待裁定③」	已关闭：上限上调 12 KB、触发线 11.5 KB（余量 89 B → 2 KB）	结论已落本文件与 skill《长度预算》v3
§3.2「tools 顺序抖动」	已结案：生效后顺序抖动 0 步；「生效前 21 步 / 4.34 元」系原口径、不可复现，勿引用该金额	tools-norm-verify-20261007/

五十六、HANDOFF §2「轮次概览」迁出 + 容量口径 v6（2026-10-08）

背景（落点违规的实例）：docs/HANDOFF.md §2 曾按「本轮 / 第二轮 / 第三批」累积当日变更明细， 2026-10-08 实测该块达 2 211 B（占全文 25%、全文最大单块）。而 skill writing-handoff 的 「严禁留在 HANDOFF」清单第一条就是 「轮次概览 / 历次变更清单——『过去』，SOP 本就是按轮累积的」； §2 的正确形态是「一句话现状 + 本轮变更要点（1~3 行）」。 → 这是 HANDOFF 涨到 8.8 KB 真正的原因（不是"现在的量太大"）：该落的没落。

迁出内容（当日 12 项变更的一行索引；明细在各自主题档案）

序	变更	档案 / 落点
④	遮蔽自检 B 级 → A 级（新增 PostToolUse shadow-check-guard.py，挂载 12 → 13）	rule-acceptance-20261008/SOP.md §9
⑤	Trae 权限全开（permission/global.json：写白名单加 /home/rain、命令白名单 19 → 56）	permission-grant-20261008/backup/README.md
⑥	HANDOFF 写入口径 v2 → v4（先整体重写 + 实测判余量）	handoff-frontload-20261008/
⑦	路线定案「不切会话 + 手动压缩」：CTX_THRESHOLDS → (300_000,)，文案改「就地压缩」	compress-point-20261007/backup/README.md
⑧	BASELINE §2.1 第 4 条改写升档（闲置会让前缀失效、时点不定【已确认】）	本文件 + cache-ttl-20261007/
⑨	状态持久化判据闭环：重启后 状态恢复=阶段4/快照4	state-persist-20261008/SOP.md §6.2
⑩	待裁定④：HANDOFF §5 长行 → PROJECT-MAP.md §3「留档」（并补录 26 → 70 条）	rule-acceptance-20261008/backup/README.md
⑪	关闭总账 #32：共享库 run_on_host 重复命令回显 2 遍 → 1 遍	shared-lib-log-20261008/backup/README.md
⑫	HANDOFF 容量口径 v5（三处口径统一；7 KB 降为「重写收敛软目标」）	本节 + skill writing-handoff
⑬	规则「2026-10-07 修订」历史块迁出常驻正文	rule-slim-20261008/RULE-CHANGELOG.md
—	规则减重两批（42 340 → 29 782 → 28 229 B）	rule-slim-20261008/
—	proxy 内存态落盘（thinking_stages + 探测快照）	state-persist-20261008/

同日容量口径再调（v5 → v6，用户裁定）

项	v5	v6
硬上限	12 KB	16 KB
动作线	10.5 KB	14.5 KB（= 上限 − 单轮最大净增 1.5 KB）
重写收敛目标	≈7~8 KB（软）	不变
正常运行区	7~10.5 KB	7~14.5 KB（不压、不重写、不报）
注入护栏 MAX_INJECT_BYTES	16 KB	20 KB —— 原与上限同为 16384，文件一到上限就被截断（尾部 §5 丢失）；两者必须保持 ≥4 KB 间距

§3 实测构成（回答「待办量是否合理」）：§3.1 需你动作 898 B / 2 项 ｜ §3.2 待观察 1 432 B / 11 项 ｜ §3.3 已决策 681 B / 4 项。 固定内容（§1 用法 667 + §4 红线 1 616 + §5 指针 655）= 2 938 B = 33%，属合理：§4 红线是 HANDOFF 最不可替代的部分（不可逆禁忌）。

---

五十七、HANDOFF「落点核验前置」流程 v7 + PreToolUse 写前守卫（2026-10-08）

背景（第五十六节问题的机制根因）：第五十六节已确认「该落的没落」是 HANDOFF 暴涨的真因， 但为什么会没落当时未解。本轮定位到两条机制缺陷：

1. 触发点被规则盖掉：skill writing-handoff《落点自检》写的是「或本轮动过 HANDOFF 时收尾执行」， 而常驻规则《HANDOFF 容量与落点》末尾写的是「未触发时不提（HANDOFF < 11.5 KB 且未满 5 轮 → 完全不出现）」。 规则每步重放、skill 按需加载 → 冲突时按规则走，"落点核验"被降级为"越线才做"。
2. 顺序错了：旧《写入前置流程》是 ①判容量 →（仅越线）②搬移 → ③写。7 KB 常态下容量判为"可直接写"， "落"这一步压根不执行。

用户裁定的目标形态（原话）：「先核验一遍该落未落的点，有未落的执行完落动作，再开始本轮的 handoff 任务」； 「理论上 handoff 应该一直在 7k 左右，设置 16K 是为了真有未完成项比较多的真实需求时有余量」。

改法（A′ + B′ + C 三件，明细见 handoff-landing-20261008/SOP.md）

件	落点	改动
A′ 阈值语义翻档	规则 + skill《长度预算》+ cost_audit/handoff_precheck.py	三档：≈7 KB 常态健康水位｜≥9 KB 偏高 → 先查「该落未落」，不是压缩｜≥14.5 KB 先整体重写｜16 KB 硬余量。删「7~14.5 属正常运行区、不报」
C 流程顺序写死	规则《HANDOFF 容量与落点》+ skill《写入前置流程》v6 → v7	①落点核验 + 落（无条件）→ ②量 + 判 → ③写 → ④复核；删「未触发时不提」
B′ 写前硬触发	新建 handoff-landing-guard/ + hooks.json	PreToolUse 认「写类工具 + docs/HANDOFF.md」→ 写前注入落点提醒（每会话一次，只 allow 不 deny）；挂载 13 → 14

B′ 的能力边界（如实）：正常路径是先跑 handoff_precheck.py（其输出自身已带「第一步（先做）」提示）， Hook 是兜底——跳过前置直接写时才由它提醒。它做到的是「必然触发」而非「必然执行」： Trae 只有 SessionStart / PreToolUse / PostToolUse 三类事件、无「工具执行后是否照做」的机检事件， 「是否真在写前落了」仍由模型执行、用户目视验收。不要把它当强制拦截。

验证（双跑）：offline_verify_handoff_precheck.py 与 offline_verify_handoff_landing_guard.py 各跑两遍全通过； hooks.json 合法且 PreToolUse: 9 / total 14；新 Hook 真机单跑注入正常。

顺带修的同类问题（口径漂移）：skill 内 3 处 11.5 KB 旧口径（PROJECT-MAP 对比表 /《为什么用滞回》/《≥5 轮》段）； HANDOFF §4 红线的「9 条脚本 / 12 条挂载」自遮蔽自检升 A 级后即未同步（实为 13），本轮统一为 10 脚本 / 14 挂载。

---

五十八、req_shape 命令特征埋点（C2）+「重启不中断输出流」定死（2026-10-08）

三件事同轮（明细见 task-side-metric-20261008/SOP.md）：

件	落点	结果
C2 任务侧效率升机检	proxy.py	shape 新增 cmd：{n, len, remote, deployer, heads}，不落命令全文；执行步有值、非执行步 null。真机验证：同是 RunCommand，重启前 null → 重启后 {n:1,len:316,remote:0,deployer:0,heads:[echo,systemctl,sleep]}
结论定死 重启不中断输出流	HANDOFF §4 红线 + 全局规则《攒批重启》+ BASELINE §2.1	旧结论「重启会打断在途流式回答」系推测、从未实测，2026-10-08 用户实测推翻；攒批重启的理由只剩一条（清内存态 → 空闲保护缺席一次）。已证伪表追加 #14 留痕
D HANDOFF 过时表述	HANDOFF.md §3.1 / §3.2	§3.2 删「写入前置 v4」残留行；§3.1 过账行改为「1.1 待办型已清空」（#32 早已关闭）

为什么 C2 要做：规则早已注明「现有日志均不含命令文本 → 任务侧效率口径有机检之名、无验收之实」。补上 cmd 后，"本轮是否跑了部署器 / 远程批量"第一次有了客观判据（消费端只读命令见主题 SOP §6 V5）。

隐私边界：只落条数 / 总长度 / 两个布尔 / 前 3 个首词，不落命令全文——离线用例 U9 断言特征 JSON 中不含命令行原文子串。

验证（双跑）：offline_verify_cmd_features.py 15 项全通过 ×2；py_compile rc=0；真机 healthz=200、shape keys 含 cmd。

副作用（有益）：本轮重启代理后本会话未中断，命令正常返回、对话继续——即「不中断输出流」的第二次实证。

---

五十九、cmd 指标接入 wrapup.py（任务侧效率升机检｜2026-10-08）

承第五十八节：C2 只做了埋点（proxy.py 落 shape.cmd），消费端仍缺 → 收尾自查的「任务侧效率」行依然靠自判。本节把消费端接上。

项	内容
新增	wrapup.py 的 task_side_stats(shape_rows)（汇总 cmd）+ should_report_task_side(stats)（机检触发）
输出	仅当本轮有远端或部署器命令时追加一块：命令步 / 命令调用 / 远端步 / 部署器步 / 重复 heads；纯本地命令轮不输出（保住"不输出"纪律）
规则同步	《任务侧效率》节：表头由「墙钟 / 远端命令 / 可省重复 / 建连」改为机检可得的五个字段；旧「条件触发（自判）」废除；「上限须知」同步为"已升机检、但建连与精确重复仍不可机检"

触发从自判变机检是本节的实质：旧口径「自己判断本轮算不算部署 / 巡检 / 远程批量」没有任何验收方；现在触发与数值都取自 shape.cmd。

仍不可机检（如实）：SSH 建连数（无连接数埋点）、精确「可省重复」（cmd 只存首词）——表内「重复 heads」只是线索，不等于真重复。

验证（双跑 + 正反例端到端）： - offline_verify_task_side.py 13 项全通过 ×2（含坏样本：全本地命令必须不输出、命令步再多也不以步数代触发）； - 反例端到端：本轮（纯本地命令）跑 wrapup.py → 无该块； - 正例端到端：造 3 行 remote=1 的 shape 日志 → 输出块且数值正确（命令步 3 / 远端步 3 / 重复 heads 2）。

首次真机使用即暴露一个判据缺陷（已修）：接入后第一次跑收尾自查，本轮只有本地命令却报「部署器步 = 1」。根因是 DEPLOYER_HINTS 用朴素子串匹配，命中了一条构造测试数据的命令里的字面量 "deployer": 0——命令里"提到"关键词 ≠ "跑了"该类命令。修法：新增 _hint_hit() 改按 token / 路径段边界匹配，REMOTE_HINTS 同步去尾空格。真机对照：同形态命令在旧代码下 deployer=1（15:39:47）、新代码下 deployer=0, remote=0（15:42:36）。用例补 U12/U13 反例 + U14/U15/U15b 正例。

上线两次重启代理（先落 cmd、再落 _hint_hit），两次均未中断本会话——再次佐证「重启不中断输出流」。

---

六十、收尾自查「费用」口径改为当轮（2026-10-08 用户要求）

诉求（原话）：「我不想要总计的命中、未命中输出、输出思考占比，我想要的就当轮任务的」。

改动：wrapup.py 费用格中四个百分数（命中 / 未命中 / 输出 / 思考占输出比）由「本会话累计」改为「本轮」； 金额仍保留「本轮 / 本会话」两个数（对照有价值）。规则《收尾自查》表与说明行同步（新增"四个百分数均取本轮任务"）。

坑：这四个百分数是金额占比（非 token 占比），故本轮需按峰谷逐条取价算三段金额——首版改动误把 token 数传入，量纲错，已修正。

验证（异源对照 + 手验 + 幂等）：wrapup.py 输出 0.279/2.748 ｜ 52%/10%/38%/70%，129； 独立自写脚本复算本轮 步=11 hit=3,605,632 miss=14,048 out=13,333 reason=9,371 思考占输出=70%； 手验金额占比 0.1442 / 0.0281 / 0.1067 = 0.279 → 52% / 10% / 38% ✓；两遍输出一致。

同轮答复的成本定性（用户提问）：这两轮各 0.5~0.7 元，不是 miss 异常——未命中仅 0.4%（2.5~3.5 万 tok）、 中段 miss 全在 20000 阈值下（最大 9,394）；成本主体是命中重放 ≈45%（每步重放 ≈22 万上下文 × 28~30 步） 与输出 ≈47%，叠加高峰 2 倍价。结构性因素是长会话的每步重放，非异常。

---

六十一、收尾自查「命中 / 未命中」改为输入侧独立 100%（2026-10-08 用户要求）

诉求（原话）：「我要的是命中/未命中 这个合起来是 100%，这个是输入侧的，不需要你完全统计…… 你现在的统计是将输出侧的也加进来算了」。

根因：第六十节把四个百分数改成取本轮时，分母仍是总成本（命中 + 未命中 + 输出）， 于是三项凑 100%、输出被折进了「输入侧」的 100% 里。用户看到的 53%/9%/38%/63% 中， 第 3 个 38% 是输出占总成本的比例，与前两项不同分母，读起来像「命中+未命中≠100%」。

改动（cost_audit/wrapup.py 费用格）： - 命中% / 未命中% 改为只按输入侧金额归一（分母 = cur_cost_hit + cur_cost_miss），两项合计 100%； - 去掉原「输出%」（不再把输出折进同一分母）； - 保留「思考占输出比」（输出侧，reasoning_tokens / completion_tokens，与输入侧不同分母）。 - 规则《收尾自查》四处同步：费用行、形态示例行、形态说明行、B 组异常判据与「输入侧占比 + 未命中归因」行。

验证（异源复算 + 幂等）：同刻同数据 —— wrapup.py 输出 0.194/0.352 ｜ 42%/58%/69%，15； 独立脚本按同一 active_tail 复算 命中42% 未命中58% 合计100% 思考占输出69%，逐项一致； 连续两遍输出完全一致（幂等）。42 + 58 = 100 ✓。

备份：task-side-metric-20261008/backup/（wrapup.py / 规则 / 本 SOP / 主题 SOP，TS 20261008-155628）。

---

六十二、收尾自查「常驻瘦身」：常驻只留五项表，其余按需（2026-10-08 用户裁定）

诉求（原话）：「我要的收尾只有常驻 5 项，其它的是有异常再运行……我纠结的不主要是规则的文本， 而是文本对应要做的动作，每轮重放对于我来说正常也重放没必要呀，我们现在整体的措施， 在做完触发点与验收方后很多东西已经过时了呀」。

判定（哪些已「过时」= 已有别的触发者）：

原常驻块	体积	现在的触发者（故规则正文不再需要常驻）
任务侧效率、miss 检测	2,155 B	cost_audit/wrapup.py（机检判定 + 自动输出）
遮蔽自检	930 B	Hook shadow-check-guard（PostToolUse）
HANDOFF 容量与落点	2,018 B	Hook handoff-landing-guard（PreToolUse）+ handoff_precheck.py
过账	236 B	Hook session-start-inject.py（SessionStart）
A/B/C/D 展开口径、工具简称映射、形态约束与上限须知	8,512 B	仅异常时才用

改动： 1. 规则 rule-agent-efficiency.md：收尾自查节 16,079 B → 1,965 B；整份规则 29,694 → 15,775 B（−13,919 B，−46.9%）。 2. 新建按需文件 ~/.trae-cn/skills/ops-execution-efficiency/references/wrapup-expand.md（15,838 B）， 逐段无损承接全部移出内容（8 段按标记切片拼接，非重打）。 3. ops-execution-efficiency/SKILL.md（Update 路径）同步：单一源指针改指按需文件； 修掉已过时表述「默认一句话」「A–E 五组」「E 组 8 条」「墙钟 / 远端命令数 / 可省重复数 / 建连数」。

验证（无损 + 寻址）：8 段切片在参考文件中逐段命中 ✓；规则内 8 个被移出块的关键词全部消失； 规则内指针 wrapup-expand.md 存在且路径可寻址。

成本影响：常驻文本 ≈4,946 tok → ≈610 tok；每步 ¥0.00020 → ¥0.00004（高峰命中价），100 步 ¥0.0198 → ¥0.0038。 每轮真正的固定成本仍是那一次取数步（¥0.014~0.024），与规则文本无关。

备份：~/.trae-cn/user_rules/backup/rule-agent-efficiency.md.bak.20261008-161712 + ops-execution-efficiency-SKILL.md.bak.20261008-161712 + task-side-metric-20261008/backup/（SOP.md / HANDOFF.md，TS 20261008-161847）。

---

六十三、台账「自动回填」：有变更就追，纯问答不追（2026-10-08 用户裁定）

背景（先质疑、后裁定）： - 我报「效率台账今天 0 条、自我迭代断了」；用户反问「台账有异常才进，今天无异常不进不是很正确的事么？」 —— 部分成立：纯问答轮不追是对的； - 但变更轮同样 0 条才是真缺口。根因：回填口径挂在「有异常才展开」下，把「有变更」与「有异常」混成一件事。 - 用户裁定：推（有变更就追 + 上限轮换）。

改动： 1. cost_audit/wrapup.py：新增 round_has_writes() / count_write_calls() / autofill_baseline()； main() 在本轮有写入类工具时自动往台账追一行（--note 可带一句说明）。 幂等靠 .autofill_state.json 记 last_turn（同一轮跑两遍只追一行）；块内只留最近 200 行（超限裁最老）。 2. 台账：新增 ## 三十三、自动回填 · 每轮变更样本（机检） 节，由脚本维护，不动既有章节。 3. 规则《收尾自查》「脚本自己做的」补「台账回填」与口径。

验证：离线 task-side-metric-20261008/offline_verify_autofill.py 17 项 ×2 遍全过（含反例「纯只读 → 不得追」、 幂等、上限轮换、后续章节不被破坏）；真机改前 0 行 → 连跑两遍 wrapup.py 后 1 行（第二遍 skip(本轮已追过)）。

未覆盖（如实）：今天之前的十几项变更未回补（缺安全的轮身份归并），从本轮起连续记录。

补记（同日 16:54）：按用户指示回补当日 00:04~16:48 的 51 轮变更样本（脚本按 turn_key 分组重算，自动节 1 → 52 行，按时间排序）。

追加（同日 16:56，用户第二次裁定）：触发补第二条 —— 收尾命令带 --note 也算变更， 用于覆盖「用脚本改文件」（不经写作类工具）的轮次；不做「猜命令里有没有写文件」的启发式（会误拉纯取数轮）。 配套 wrapup.py 新增 should_autofill()；离线用例扩到 20 项 ×2 遍全过（新增 U4b 正例 / U4c 反例 / U4d）。

备份：TS 20261008-164952（wrapup.py / 规则 / measured-baselines.md）；165410（台账补记前）；165643（--note 触发）。

---

六十四、效率侧首个机检数据源：shape.last_tool（返工 / 试错）（2026-10-08 用户裁定）

动因（用户原话）：「度量只计成本的么？应该有你执行任务时的返工、错误执行的步骤……这个是效率呀」 「难怪你老只提成本，执行效率侧的从来不提」。此前效率侧只有「碎步」（未合并块 / 已合并率 / DUP）， 返工 / 试错完全没有数据源：tool_timing 只记耗时、step_profile 的 err 只是上游 API 非 200。

改动： 1. proxy.py：新增 shape.last_tool = {name, ok, code, len} —— 上游一步工具结果的特征 （_iter_tool_results() 兼容 OpenAI role=tool 与 Anthropic tool_result；只落特征、不落正文）。 ok 判定：显式 is_error → 文本里的 Exit code: N → 高精度错误标记（全文扫）。 2. wrapup.py：新增 tool_error_stats()；台账回填行加两列「报错步 / 重试步」（表头 12 → 14 列）。 定义：报错步 = 上一步 last_tool.ok is False；重试步 = 上一步失败且本步又调同一工具。

验证： - 离线 offline_verify_autofill.py 25 项 ×2 遍全过（新增 U18~U22 含反例：全成功轮必须 0、ok=None 不计、换工具不算重试）。 - 真机（重启后）：失败命令（ls /definitely-not-here）→ 下一步 last_tool.ok=false ✓； 正常步 → ok=true ✓；本轮台账行实得「报错步 1 / 重试步 1」✓。

③ 标定总账 #25（已修复口径、已出结论）： - 卡点原因：首版按日聚合误用了 merge_steps（那是 merge_groups 的组步数和），正确字段是 merged_steps（一步多工具的步数）→ 算出 2026-10-02 = 105.1% 的荒谬值。 - 修复后（按日重算，全部 ≤100%）：已合并率 32.5%（1 178/3 625，≤10-05）→ 38.7%（1 324/3 424，≥10-06）； 改-验循环占未合并块 42.3% → 39.8%（当天反而 51.6%）；元/步 0.0143~0.0170 → 0.0188~0.0205（受会话长度影响，不可归因）。 - 结论：未见改善。同期另有 5 项变更上线，混杂严重，只能记「未观察到效果」，不判有效。 已回填总账 #25，并列为待你定：把「改-验循环」升级为 Hook 强制，还是撤掉该判据。

备份：TS 20261008-170510（proxy.py / wrapup.py / 规则）。

追加（同日 17:15，用户裁定「按方案 ① 升级为 Hook 强制」）： - 查证结果：判据 I 早已是强制级（ENFORCE_MARKS 含 I）—— 真正缺的是覆盖面：它原只管文档类扩展名。 - 本次做的是扩面：merge-guard.py 新增 CODE_EXTS / GUARDED_EXTS（文档 + 代码），判定改用 GUARDED_EXTS， 提醒与拦截文案去掉「文档类」。 - 验证：离线 task-side-metric-20261008/offline_verify_guard_i.py 6 项 ×2 遍全过 （正例：代码类 / 文档类各一；反例：只改不验、同一步内并行、非受管扩展名）。 - 生效：Hook 脚本改完同会话下一次请求即生效（无需重启 Trae）。 - 备份：TS 20261008-171416（merge-guard.py）。

---

六十五、HANDOFF 落点核验改为「每轮收尾带出」（2026-10-08 用户纠偏）

用户原话：「handoff 不是你写任务改尾时就要判断是否有该落未落的点么？且也最应该这时候做， 完成了未完成项，就是在这里知道的，怎么现在还是不能做到任务中闭环，还要人工来确认？」

根因：v7 的核验触发挂在「本轮动 HANDOFF」上 —— 一旦「越线 → 干脆不写」，核验就被整个绕过 （本轮就是这样：报「后续未做项：HANDOFF 越线」，却把核验推给下一轮）。

改动：wrapup.py 新增 handoff_path() / handoff_status()，在收尾自查表后每轮直接打印一行 **HANDOFF 落点**：X.X KB ｜ 该落候选 N 行 ｜ <裁定>（裁定取自 handoff_precheck 的 ACTION_LINE / WARN_BYTES）。 规则《HANDOFF 容量与落点》同步：核验不再挂「动 HANDOFF」，当轮看到「偏高」就当轮落。

当轮验证（顺带完成一次真实落点核验）： - 打印实得：9.1 KB ｜ 该落候选 16 行 ｜ **偏高 → 先查「该落未落」（不是压缩）**； - 按入口三问判定：「该落未落」处 = §2「本轮」那条 22 项轮次概览（过程记录，skill 明令本文件不写）→ 压成一行指针； - 结果：9,026 B（8.8 KB）→ 健康水位内，复跑裁定改为「健康水位内」✓。

备份：TS 20261008-171935（wrapup.py / 规则）。

六十六、「未合并块」单列「依赖链」+ 拦截额度按判据分计（2026-10-08 用户裁定）

用户质疑：「改-验循环 1 组，本可批量，不是 hook 强制了么？怎么还是没达到预期？」

根因（两件独立的事，此前被混为一谈）： 1. 判据 I 的门槛是「同一窗口内编辑 ≥3 步 且 只读验证 ≥2 步」，只抓「改→验→改→验」的长交替； 而收尾表里那组是编辑仅 1 步的「查→改→验」（改哪要先查、改完必验）——天然不可合并，够不到门槛。 I 不拦是对的（历史累计 I 仅拦 4 次，最近一次 2026-10-07）。 2. 真正的错在指标口径：step_profile 把这类依赖链并进「改-验循环」、计入可并类合计， 使该合计恒被噪声占满、失去分辨力（也让总账 #25「压降改-验循环占比」变成打不赢的仗）。

改动 A：step_profile.py 新增语义类 dep（「依赖链」） - 判定：未合并块内 classify_group 判为 write+run、且含编辑的步数 ≤ 1 → 改判 dep； 编辑 ≥2 步（改 A、验 A、再改 B、再验 B）才是真该批量，仍归 write+run。 - MERGEABILITY["dep"] = "na" → 不计入 mergeable_totals（可并类合计）； LEGACY_MAP 仍映射回 write+run，旧 5 类聚合的跨轮可比不断裂。 - wrapup.py 的 KIND_SHORT / SHORT_ORDER 增加「依赖链」，收尾表分列可显示（如 改1依赖链1）。

改动 B：merge-guard.py 拦截额度由「每会话共 3 次」改为「每个判据各 3 次」 - 用户原话：「我理解应该是一个动作最多拦 3 次吧，后续该拦的还是要拦呀」——用户理解正确。 - 旧口径 denies 是会话级单一整数：会话内任意 3 次拦截用完后，A/B/D/E/F/I/J 全部退化为提醒， 会话后半段「该拦的也不再拦」。 - 新口径 denies 改为 dict（按判据字母计数），判定 denies.get(mark, 0) < DENY_MAX； 旧格式（整数）在读取处丢弃重算，不崩溃。

验证： - 离线 task-side-metric-20261008/offline_verify_dep_and_deny.py 15 项 × 2 遍全过 （A 组 10 项：查→改→验 / 改→验 归 dep、两轮改-验仍归 write+run、纯改 / 纯跑不受影响、 可并类合计排除 dep；B 组 5 项：同判据前 3 次拦 / 第 4 次不再拦、F 用满后 J 仍能拦、 旧格式 state 兼容、denies 以 dict 持久化）。 - 反例校验（甲口径）：用备份的旧版跑同一序列 → F 用满后 J = allow（旧口径整体放行）， 证明 B3 判据能识别新旧差异（不是「永远通过」的假判据）。 - 真机：会话 9fbe7c5148ed 分列为 依赖链 1 组/2 步、改-验循环 0 组/0 步， 可并类合计 1 组/5 步（71.4%）——不再被依赖链污染。

备份：TS 20261008-172917（step_profile.py / wrapup.py / merge-guard.py）。

六十七、台账「度量 → 措施」：efficiency_alerts() 四条阈值（2026-10-08 用户要求）

用户指令：「现在把台账有度量无对应落地措施推进一下」。

根因（先取证）：台账 §33 自动回填节已积累 61 轮 × 14 列样本，但没有任何一列接动作。 对 61 轮做分位统计，得：

指标	实测分布	判读
DUP（重复读）	61 轮全为 0	问题已被合并策略消灭 → 该列零信息量
已合并率	中位 33%；<20% 且步数 ≥10 的有 8 轮（13%）	高发、无动作
>5000 tok 大输出步	≥2 步的有 3 轮；=1 步的有 21 轮	39% 的轮出现、无动作
报错步 / 重试步	3 / 2 轮非 0（埋点刚上线，样本少）	无动作
输入侧未命中	≥50% 有 9 轮（15%）	此前只有「≥2 万中段」的 miss 检测，不看占比

改动：wrapup.py 新增 efficiency_alerts(cur, cur_shape, ms, miss_share) + 4 个阈值常量 （ALERT_MERGE_RATE=20 / ALERT_MERGE_STEPS=10 / ALERT_BIG_STEPS=2 / ALERT_MISS_SHARE=50）， 在收尾自查表后命中才打印一行：

• 碎步偏多：已合并率 <20% 且步数 ≥10 → 带出未合并块的语义类分列（指向可压对象）；
• 大输出 N 步：>5000 tok 的步 ≥2 → 指向增量编辑；
• 返工信号：报错步 >0 → 报错步 / 重试步（数据源 shape.last_tool）；
• 未命中 X%：输入侧未命中 ≥50% → 指向 miss 检测 TOP3 归因。

设计约束（沿用用户既有裁定）：① 阈值取分位防刷屏（命中率 13% / 5% / 已有列 / 15%）； ② 不进常驻规则，全部在实现层（有就出现、没有就不出现），口径写进 wrapup-expand.md（按需文件）； ③ 每条只需一行，不破坏「收尾要短」。

DUP 列的处置：判定「问题已消除」——61 轮全 0，列保留作回归哨兵（一旦非 0 = 合并纪律回退）， 结论写入台账 §33 节头（不删列，保留可比性）。

验证： - 离线 task-side-metric-20261008/offline_verify_alerts.py 10 项 × 2 遍全过：4 条各配正例 + 反例 （不达阈值不得打印），另加「正常轮零提示」一条； - 真机首条命中：本轮因 heredoc 格式化错误（% 未转义）报 **返工信号**：报错步 1 / 重试步 1 —— 与事实相符，说明该提示不是摆设； - 同轮收尾表：1.8 | 12 | 6（50%）｜增1改3查5跑3 | 1/5（跑1） | 0.276/1.313 ｜ 76%/24%/60%，66 | 0/0/0。

备份：TS 20261008-174325（wrapup.py / measured-baselines.md）。

六十八、度量 → 措施的真实落点：执行选型表（2026-10-08 用户纠正）

用户纠正（上一版做偏了）：「对应落地措施落地是把这结果给我？我的想法给后续的你， 在执行任务时选择最优的执行步骤、最省的成本控制。」

偏差定性：上一版把「措施」做成了 efficiency_alerts() —— 收尾时打印一行给人看。 那是事后报告，不改变任何人下一步怎么做；用户要的是事前选型，让后续 agent 开工就按它选路。

改动：新建 ~/.trae-cn/skills/ops-execution-efficiency/references/execution-playbook.md （执行选型表，10 条），每条 = 开工可见信号 → 走哪条路 → 实测依据：

#	信号	走哪条路	依据
1	读 ≥3 文件且只要结论	派 ctx-scout	§26/§29：漏用连续 4 轮未降
2	同一文件改 ≥3 处	一次读够 → 一次改完 → 验一次	判据 I 真机 6 次触发 / 3 次放行
3	「查→改→验」（编辑仅 1 步）	不合并（依赖链）	§33 61 轮 + dep 语义类
4	≥2 类独立只读动作	合并为一条命令 / 一条 ssh	§33：13% 的轮碎步偏多
5	单步 >5000 tok 且要改文件	增量 SearchReplace，不整篇 Write	§33：大输出步出现在 39% 的轮
6	同一共享服务改多处	攒批只重启一次	重启清内存态 → 空闲保护缺席
7	上下文 >600 K 且已收尾	开新会话（≈0.58 元/次）	§25 第六~九次修正
8	距上次 >1 h 又要接着做	背景重述完整	§31：10.8 h 后未命中 98.1%
9	多条远端命令	一次 ssh 跑完（连接复用）	§3：握手数为主要开销
10	≥5 处同类编辑	先列清单再一次做完	《批量项》硬门禁

并在 SKILL.md 的《执行清单》段首加指针（动手前先扫此表）。

两个载体的分工（本次纠偏的要点）：

载体	时机	作用	成本
execution-playbook.md	事前	按信号选路	按需加载（规则已强制多步任务必载本技能）
efficiency_alerts()	事后	对账：命中 = 本轮没按表走	命中才一行

为何不写进常驻规则：常驻每轮重放；选型表只在多步任务开工时有用， 而规则已要求「任何多步执行类任务必须加载本技能」——触发点已有，不必付常驻成本。

验证：文件已建、SKILL.md 指针已加；表内 10 条的「依据」列全部指向已落盘实测 （§3 / §25 / §26 / §29 / §31 / §33、判据 I 真机记录），无凭空条目。

备份：SKILL.md 见台账 TS 20261008-191355；execution-playbook.md 为新建（无改前版本）。

六十九、HANDOFF 体积门禁：由「只提醒」升为 Hook 强制拦截（2026-10-08 用户裁定）

用户原话：「我要的是现有结论做强制，能强制的强制而不是提示，我宁愿先拦—— 实测 hook 拦你是最有效的动作，其它都是扯蛋……你很多时候规则是拦不住你的。 handoff 你都没按我的逻辑做到位：理论上我每轮都在减少待办、同时加些待办， 但靠规则与 skill，handoff 的容量一直在膨胀。」

根因：handoff-landing-guard 此前是只提醒不拦截（它自己的文档头就写着「不要把它当成强制拦截」）， 落点核验因此只落在「每轮打印一行 + 用户目视」上——模型照旧净增。 实测：2026-10-08 一天内 HANDOFF 从 7.5 KB 涨到 9.2 KB，多轮都在「加待办」而没有等量减少。

改动：handoff-landing-guard 升为 PreToolUse 门禁，写 docs/HANDOFF.md 前判据：

条件	动作
预计写入后 > 16 KB（硬上限）	deny
预计写入后 > 14.5 KB（动作线）	deny（要求先整体重写）
当前 ≥ 9.0 KB（偏高线）且 本次净增 > 0	deny（要求本轮先搬走 / 做掉等量内容）
净减 / 压缩 / 偏低水位下的小幅增补	放行

不死锁三道保险（同 merge-guard）：① 被拦调用指纹入册，原样重发即放行（记 allow_fp）； ② 每会话最多拦 3 次（DENY_MAX），超出只提醒；③ 估不出净增时一律不拦（缺字段 / 定位不到文件）。 事件落 logs/guard_events.jsonl（hook=handoff-landing-guard，mark H）→ 收尾自查 guard 计数自动纳入。

原「落点提醒」的去向：文案并入 deny 理由——提醒只在被拦时出现，不再每会话无条件注入。

验证： - 离线 task-side-metric-20261008/offline_verify_handoff_gate.py 11 项 × 2 遍全过 （正例 4：9.5 KB+净增 / 越 14.5 KB / 越 16 KB / Write 覆盖 20 KB；反例 5：净减 / 未到偏高线 / 缺字段 / 非 HANDOFF 目标 / 只读工具；放行闭环 2：原样重发放行 + DENY_MAX 第 4 次不再拦）； - 真机闭环（本次实做）：① 净增 +263 B → 被拦（guard_events.jsonl 记 H deny，19:23:48）； ② 按提示先搬走三条已结案项（判据 I 射程 / 依赖链口径 / 拦截额度，均已并入第六十六节）→ 净减放行； ③ 再加「执行选型表」一行 → 放行；HANDOFF 9.2 KB → 8.9 KB，回到健康水位。

备份：TS 20261008-192203（handoff-landing-guard.py）/ 20261008-192332（HANDOFF.md）。

七十、守卫全面强制化：能拦的全拦（2026-10-08 用户裁定）

用户原话：「我现在要求能拦的就拦，因为拦只是让你停下，最后还是放行，没有影响—— 你发命令 3 次的时间被拦可忽略不计，所以能强制拦的就拦，哪怕严也没后果，全部给我按严的来。」

盘点（先取证）：扫全部 Hook，只提醒、无拦截能力的有 4 处—— merge-guard 的 C/K/L、sched-guard、script-safety-guard、shadow-check-guard （后两者还挂在 PostToolUse：写入已经发生，提醒等于事后追认）。

改动 Batch 1（脚本内改，立即生效）：

项	原	现
merge-guard 判据 C（同文件多次改）	仅提醒	强制（并补上遗漏的 DENY_PROMPTS["C"]）
merge-guard 判据 K（只读检索扎堆）	仅提醒	强制
merge-guard 判据 L（逐项循环）	仅提醒	强制（判定收窄为 shell 形态，见下）
merge-guard 新增判据 M	—	强制：改已存在文件前本会话未 Read 过 → 拦（state 新增 read_files 台账）
sched-guard	仅提醒	强制 deny + 指纹放行 + DENY_MAX + 落 guard 日志（mark S）

改动 Batch 2（改挂载位置，须重启 Trae）：

项	原	现
script-safety-guard	PostToolUse 提醒	PreToolUse deny（写入前扫 tool_input 的文本）
shadow-check-guard	PostToolUse 提醒	PreToolUse deny

hooks.json：这两条由 PostToolUse 移入 PreToolUse（PreToolUse 9 → 11 条，PostToolUse 4 → 2 条）。

放行闭环（两条路，均不死锁）： ① merge-guard / sched-guard：被拦指纹入册，原样重发即放行（allow_fp），每会话每判据上限 3 次； ② script-safety-guard / shadow-check-guard：沿用「每 (session, 目标) 只拦一次」——第二次即放行。

真机发现（本轮实做，含一次真实缺陷）： - 判据 M 首次生效即拦下我改 script-safety-guard / shadow-check-guard（本会话确实没读）→ 原样重发放行； - 判据 L 升强制后首次真机即误拦：我自己那条 python3 <<EOF 里的 for p in [...] 被判「逐项循环」 → 收窄判定为 shell 形态 for … ; do（不认 Python / JS 的 for x in）； - 判据 C 升强制后静默失效：DENY_PROMPTS 里没有 C（它原本只提醒）→ 命中时 KeyError 被 __main__ 的兜底 except 吞掉，表现为「放行」而非报错。离线用例 C1 抓到并补上文案； 同时新增一致性断言「ENFORCE_MARKS ⊆ DENY_PROMPTS」，防同类漏配。

验证： - 离线 task-side-metric-20261008/offline_verify_strict_guards.py 12 项 × 2 遍全过 （M 正/反例 4、C 1、L 正/反 2、K 1、sched-guard 3、配置一致性 1）； - 真机本轮 guard 计数：被拒 6 / 原样重放 9 / 提醒 0 —— 新判据全部真机触发，放行闭环可用。

备份：TS 20261008-192806（4 个脚本 + hooks.json）。

七十一、优秀实践也要强制 + 结论要沉淀（2026-10-08 用户裁定）

用户原话：「台账里面有的优秀实践也做强制了吗？强制只是拦，不影响最终结果， 优秀实践的度量结论要沉淀。」

盘点（先取证）：此前强制的都是防错（拦坏行为），正向最佳实践只停在提示。逐条扫后处置：

优秀实践	原状	处置
大文件先定位（>800 行先搜索再按段读）	docs-read-guard 只提醒	升强制（>32 KB 且未带 offset/limit → 拦）
先搜再抓（WebFetch 前先 WebSearch）	webfetch-guard 只提醒	升强制（本会话第 2 次 WebFetch 起拦）
连接复用（一条 ssh 跑完）	无	新增判据 N（单条命令 ≥2 次 ssh → 拦）
攒批重启（同服务只重启一次）	无	新增判据 O（300 s 内重复重启同一服务 → 拦）
其余 16 条（合并 / 增量编辑 / 改前必读 / 派 ctx-scout / 批量删除 / 调度确认 / 脚本红线 / 遮蔽 / 不弹窗 / HANDOFF 净减 …）	已强制	汇总见总表

沉淀：把台账结论整理成 references/execution-playbook.md「优秀实践总表」，两栏： - 已强制 20 条 —— 每条注明强制手段（哪个判据 / Hook）与依据（台账哪一节）； - 仅沉淀 6 条 —— 每条写明为什么不能机检（「先测量再优化」缺中间产物形态； 「>600 K 且已收尾才切会话」含判断题；「读档案前先加载技能」技能加载不可观测 …）。

为什么必须两栏：用户强调「强制只是拦、不影响最终结果」——故不能只靠拦。 拦得住的（有稳定机检信号）升为判据；拦不住的必须落纸并注明升级路径： 「仅沉淀」项一旦找到稳定信号，就当轮升为「已强制」（本轮 webfetch / docs-read 即如此升上去）。

验证： - 离线 offline_verify_strict_guards.py 23 项 × 2 遍全过（新增 N / O / webfetch / docs-read 共 9 项 + 3 条配置一致性断言）； - 断言又抓到两个真隐患：① PROMPTS 缺 N/O → KeyError 被兜底 except 吞掉（表现为放行）； ② ENFORCE_MARKS 漏 N/O → 判据静默退化为提醒。两者均已修，且固化为断言 （ENFORCE_MARKS ⊆ DENY_PROMPTS、PROMPTS 与 DENY_PROMPTS 键集一致、N/O 在强制集内）。

备份：TS 20261008-192806（merge-guard / sched-guard / script-safety / shadow-check / hooks.json）； 本轮另改 webfetch-guard.py 与 docs-read-hook/docs-read-guard.py（改前未备份，属疏漏， 台账已如实登记为改后快照）。

七十二、会话规模提醒根本不存在——查证并补上（2026-10-08 用户实测）

用户实测（贴图）：「上下文使用率 32% of 1433K」——为什么没有提醒我该压缩了？

查证：两个独立原因，都不是「阈值没到」这么简单

1. 该提醒根本没有任何实现：hooks.json 全文读过，无任何「会话规模」挂载； 唯一的 SessionStart 脚本（session-start-inject.py）里只有中文指令 / HANDOFF / 过账 / Hook 自检四段， 没有规模判定。台账 §25 #34 曾记「Hook 会话规模提醒改口径 35/50/70 万 → 60/90/120 万」， 但那个挂载现已不在 hooks.json 中——即：当时改的是一个已不存在的挂载。
2. 即使按旧设计，32% 也不到第一档（阈值 42% / 63% / 84% = 60 / 90 / 120 万 tok）。

实测数据（proxy 侧真实值，证明规模可读）：最近一次请求 hit 458,240 + miss 6,533 = 464,773 tok = 31.7%，与图上 32% 一致。

改动：新增判据 P（强制，挂在 merge-guard，即时生效、无需改 hooks.json） - 数据源：logs/req_shape.jsonl 最后一行的 hit + miss（proxy 每次请求落一行）；只读尾部 8 KB； - 三档：600000 / 900000 / 1200000（= 1433 K 窗口的 42% / 63% / 84%，对齐台账 §25 结论）； - 行为：首次进入新档 → deny（要求开新会话，或先把任务收尾）；同档只拦一次（state 记 ctx_level）。

验证：离线 offline_verify_strict_guards.py 28 项 × 2 遍全过，判据 P 占 4 项 （P1 反例 464 k 不拦 / P2 进第一档拦 / P3 同档不重复拦 / P4 进第二档再拦）。 本轮又抓到并固化一个真隐患：强制文案里的裸 %（「42% 以上」）会被当成格式符 → TypeError； 已写为 %%，并加断言「每个 DENY_PROMPTS 文案都能单参格式化」。

备份：TS 20261008-194715（merge-guard.py）。

七十三、会话规模提醒改向：长期留着更好，到 30 万提醒压缩（2026-10-08 用户纠偏）

用户原话：「你在干什么，原来的 Hook 注入是提醒该切会话了，按我们的新的结论是 长期维持在一个对话里面会更好，不仅是成本，也是上下文的记忆，所以这个对应的 hook 提醒 应该改为 300K 提醒我压缩（再开会话）。」

我上一轮的偏差：把 P 做成了三档（60/90/120 万）→ 拦截「开新会话」——方向正好相反： 既分档拦（用户只要一次提醒），又推着切会话（新结论是要留着）。

改正后：

项	上一轮（错）	本轮（改正）
阈值	60 / 90 / 120 万 tok 三档	30 万 tok 单档
动作	deny（拦）	只提醒（allow + 一行文本）
文案	「请开新会话」	「建议压缩一次；长期维持同一对话优于频繁新开」
频次	每档各拦一次	每会话提醒一次

为什么改成「不拦」：切不切会话是选择（成本 vs 记忆的权衡），不是对错—— 与「防错」类判据（A / B / C / M …「该合并却没合并」）性质不同，故不进 ENFORCE_MARKS； 判据 P 只保留在 PROMPTS（提醒文案）中。

新结论的沉淀：本结论进入 references/execution-playbook.md 新增的第二栏「仅提醒」； 总表由两栏扩为三栏（已强制 20 / 仅提醒 1 / 仅沉淀 6）。

与旧结论（台账 §25 第九次「600 K 为实测成本最优切点」）的关系：旧结论只算成本、 未计「上下文记忆」；用户新结论把记忆计入收益 → 默认不切，只在 30 万提醒压缩。 两条并不冲突：600 K 仍是「若必须切、这个点最省」；新结论是「默认不必切」。

验证：离线 offline_verify_strict_guards.py 28 项 × 2 遍全过（判据 P 四项已改： P1 反例 299,999 不提醒 / P2 30 万提醒（allow + 文本、非 deny）/ P3 不重复提醒 / P4 P ∉ ENFORCE_MARKS）。

备份：TS 20261008-195207（merge-guard.py）。

七十四、HANDOFF 落点核验：从「每轮进答复」改挂「写前拦截」（2026-10-08 用户裁定）

用户裁定：「我想的是你自己闭环，不需要我参与，这是写给你看的」——wrapup.py 每轮打进 收尾答复的那行「HANDOFF 落点：X KB ｜ 该落候选 N 行 ｜ 档位」，既占用户版面、又把内部自检推给用户读。

但不能因此留漏洞：该行当初从「本轮动 HANDOFF 才自检」挪到「每轮带出」，正是因为旧触发点会被 「越线 → 干脆不写」绕过（见第六十九节）。故本次不是单纯删除，而是换载体：把落点候选数并进 handoff-landing-guard 的 deny 理由 —— 只在我真写 HANDOFF 且越线被拦时出现，进模型上下文、不占用户版面。

改动：cost_audit/wrapup.py（删每轮输出段 + 随之无引用的 handoff_path() / handoff_status() / HANDOFF_MAX_UP / pathlib import，净减 1 285 B）；handoff-landing-guard/handoff-landing-guard.py （新增 _landing_hint()，取不到时静默返回空串）；skill writing-handoff 验收行两处。

验证：既有离线用例 11 项通过 / 0 失败；探针正例 deny 且带「落点核验：候选 360 行 / 合计 20700 B」、 换 session 复跑逐字一致；坏样本（同目录无 cost_audit）仍 deny 但无该文案（静默降级，不误放行）； grep 残留引用为空、py_compile 通过；python3 cost_audit/wrapup.py 输出已无该行。

上限须知（如实）：_landing_hint 只覆盖「已经在写 HANDOFF」这一时刻；「这轮该写却完全没写」 仍无人管（Trae 无「最终答复」事件，Hook 拦不到）。这是本次换载体的已知边界，与用户「你自己闭环」的要求一致 —— 该情形依赖 writing-handoff 的写入前置流程自觉执行，未加机器兜底。

备份：TS 20261008-222232；台账见 task-side-metric-20261008/backup/README.md。 明细：task-side-metric-20261008/SOP.md §10。

补充（同日 22:34，用户裁定「加第三种」）：放行路径也注入——handoff-landing-guard 在 未越线时输出 allow + additionalContext（「【HANDOFF 写前】距上次更新已 N 轮 ｜ 当前 X KB ｜ 落点核验：候选 K 行」）， 越线时轮次并入 deny 理由。轮次口径：自 HANDOFF mtime 以来 req_shape.jsonl 里的不同 turn 值个数 （倒读尾部 256 KB、遇旧即停）；turn 可能被复用，故只是提示值、不是判据。同一会话内轮次与水位档都没变则不重复注入。 验证：健康水位 → 放行且注入含「距上次更新已 36 轮」；同会话复跑 → 输出为空（去重）； 偏高 9.5 KB + 净增 → deny 且理由含轮次；隔离坏样本（无 logs/）→ 仍放行、文案自动省略轮次与候选、不崩；既有 11 项用例全过。

七十五、拦截额度收口：「重发永不放行」改回「每个操作拦三次就放行」（2026-10-08 用户裁定）

现象（用户实测截图 + 底层日志）：另一会话 6ac59a3fc1804934 在 22:47–22:59 被 merge-guard 连续拦 45 次（判据 K「只读检索扎堆」26 次、R「写文件扎堆」7 次），其中同一操作被拦 4 遍； 该会话最后一次工具调用停在 22:59:27，随后自述「编辑通道被 Hook 节流拦，本轮未继续」→ 任务未完成。

根因：同日上午「上强度」把 DENY_MAX 由 3 改为 999（实质不设上限），且「指纹已入册 → 一律 deny_repeat」这一分支不读 DENY_MAX → 同一操作被无限拦。与脚本自身《设计约束 1》 「误判只应浪费一次往返，不得瘫痪会话」直接冲突；也与规则《批量项：先敲定，再一次做完》的 「一口气做完」矛盾（守卫拦的正是「连续读 / 连续写」）。

改动（merge-guard/merge-guard.py）： 1. DENY_MAX 999 → 3； 2. denied 由 list 改 dict（{指纹: 已拦次数}；旧格式 list 兼容读入为 1 次）； 3. deny_repeat 分支加额度：已拦 < 3 继续拦并计数；≥ 3 → 记 allow_fp 静默放行（该指纹本会话内此后一律放行）。

验证：

项	命令	结果
同一操作连发 6 次（间隔 1.7 s）	内联 harness 直调 guard	deny → deny_repeat → deny_repeat → 放行 → 放行 → 放行，日志同步 deny/deny_repeat×2/allow_fp×3
严格守卫用例	task-side-metric-20261008/offline_verify_strict_guards.py	31 通过 / 0 失败
指纹放行用例	merge-guard-allowfp-20261007/verify_allowfp.py	5 / 0
判据 I 用例	task-side-metric-20261008/offline_verify_guard_i.py	5 / 1 —— 改前改后逐字一致，既有失败、非本次引入

边界（如实）：额度按会话累计，超长会话仍可能出现「多个判据各拦 3 次」（上限 ≈ 判据数 × 3）； 「同一操作」以指纹为准，改一个字符即新指纹，可绕开计数——这是有意的（改了做法本就该重新审视）。

备份：TS 20261008-231109（merge-guard.py）；台账 task-side-metric-20261008/backup/README.md。

七十六、HANDOFF 结构改造：五节 → 四节，删重复项与观察项（2026-10-08 用户裁定）

动因（用户原话）：「我跟你讨论下当前 handoff 的组成内容，我觉得很不合适……我的环境有 skill，一些红线有规则及 hook」—— 且「你要是能做到该落就落，我不会动这个」→ 结构必须从设计上防胖，不能靠模型自觉。

改造前的自评（9166 B）：§4 红线 13 条里 7 条在全局规则 / BASELINE / Hook 已有（免确认 → 规则 C 类； 同会话生效 → BASELINE §2.1 第 13 条；run.sh 互斥 / prompt_hint → BASELINE §1；Hook 目录核对 → 存活自检……）； §2 记着 Hook 脚本数与判据条数（变一次就要改 HANDOFF 一次）；§3.2 的 15 条属「过程」；§2 还写了轮次概览（违反自身规定）。

改造内容： 1. 四节骨架：现在什么状态 / 未完成事项 / 本项目特有红线 / 指针（删「这份文件怎么用」——写法说明归 skill）； 2. 红线 13 → 2 条：改 proxy.py / config.yaml 须备份 + 离线验证；logs/ 五个 jsonl 绝不可删； 3. 观察项 14 条 → 优化总账「五、待标定」#41~#54； 4. web-scout 「非强隔离」先补进 agents/web-scout.md 再从 HANDOFF 删（先移入再删）； 5. 过账三锚点契约已在第五十三节，直接删； 6. §2 不再记 Hook / 判据条数（权威来源 = hooks.json + 启动时存活自检）。

结果：HANDOFF 9166 → 2394 B（−74%），四节 39 行。

配套（skill writing-handoff 同步）：五节 → 四节；《入口三问》→ 四问（补第四问「别处能不能拿到」+ 六来源表）； 《长度预算》明确「体积是指标不是目标，目标只有『新会话能接手』」；《收尾检查清单》同步。

判据改造（重要教训）：原计划的「重复机检」（字符 n-gram 查重）实测无效——对中文改写检出率 0 （旧版手写式重复一条没抓到；照抄 4 行只命中 1 行，含英文/路径的行被 ASCII 过滤跳过）。故改为： 查重降级为辅助线索（只抓逐字照抄）；防线换成白名单结构检查—— handoff_precheck.py 新增「结构合规」块：四节骨架 / 红线 ≤5 条 / 全篇 ≤120 行 / 无轮次概览。

验证（正例 + 反例，两遍一致）：

样本	结果
新 HANDOFF（2394 B）	结构合规 四项全过；疑似重复 0 命中
旧 HANDOFF（9166 B 备份）	三项不通过（5 节 / 红线 12 条 / 行 13 有轮次概览）→ 判据有效

备份：TS 20261008-233603（HANDOFF / skill / precheck / web-scout / 优化总账 共 5 份）。

---

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