SOP：Agent 执行效率约束落地 + 提问对照卡（2026-09-23）¶
本次变更的实现体为
output-cost-20260923/apply_changes.py（默认预演、幂等、带备份与回滚）。 本文第 5 章的操作序列以实现体为准，仅供阅读、复核与手工复现。
1. 背景¶
实测（2026-09-23）：输出 token 单价 ¥4/百万，是缓存命中输入（¥0.02/百万）的 200 倍； 每一次工具步进 = 一次完整的重新推理（含思考）。当日 697 条请求只对应 40 个用户轮次 （平均 17.4 步/轮），输出成本中 65% 是思考 token，42% 花在 7 轮重复的开放式检查上。
浪费的来源不是任务本身，而是提问方式与 Agent 执行方式：开放式提问（「再检查一下是否合理」） 让模型先自行定义「什么叫合理」，把不可穷尽的判断变成一轮又一轮的探索性读取。据此确定两项措施：
| 措施 | 作用面 | 落地形式 |
|---|---|---|
| M1 新增全局规则约束 Agent 执行方式 | Agent 侧（每次请求都注入） | ~/.trae-cn/user_rules/rule-agent-efficiency.md |
| M2 落盘「提问对照卡」 | 用户侧（提问前自查） | output-cost-20260923/提问对照卡.md |
2. 目标¶
变更完成后，以下状态可验证：
~/.trae-cn/user_rules/rule-agent-efficiency.md存在，且与output-cost-20260923/rule-agent-efficiency.md逐字节一致。- 规则文件含四个小节：为什么 / 执行方式（必须）/ 边界 / 停止判据。
docs/HANDOFF.md的变更前版本已备份到output-cost-20260923/backup/并在台账登记 （本次由主 agent 随后修订 HANDOFF 正文，实现体只负责备份）。- 实现体复跑零变更、全跳过；核验脚本全通过（退出码 0）。
proxy.py、config.yaml、~/.trae-cn/hooks.json与变更前指纹一致（未被触碰）。
3. 前置条件¶
| 项 | 要求 |
|---|---|
| 运行环境 | 本机系统 python3（≥3.9），无需第三方依赖、无需 venv |
| 目录 | ~/.trae-cn/user_rules/ 已存在（本机已存在，含 4 个既有规则文件） |
| 输入文件 | output-cost-20260923/rule-agent-efficiency.md、docs/HANDOFF.md 均存在 |
| 目标状态 | ~/.trae-cn/user_rules/rule-agent-efficiency.md 当前不存在（本次为纯新增）；若已存在且内容不同，实现体拒绝覆盖 |
| 权限 | 当前用户 rain 对 ~/.trae-cn/user_rules/ 有写权限，无需 sudo |
| 执行前检查 | 确认没有其它会话正在改 docs/HANDOFF.md；确认 token-proxy 服务状态与本次无关 |
4. 影响范围¶
| 项 | 值 |
|---|---|
| 主机 | 单机 192.168.31.250（用户 rain），无其它节点 |
| 组件 | ① 全局用户规则目录 ~/.trae-cn/user_rules/（新增 1 个文件）② docs/HANDOFF.md 的备份（只读复制） |
| 是否停服 | 不需要。不改动代理服务：proxy.py / config.yaml 不触碰，systemd 用户服务 token-proxy 不重启、不重载 |
| 窗口期 | 无要求。规则文件由 Trae 在下一次请求时读取，无在跑作业、无并发写入 |
| 影响面 | 仅影响本机 Trae 的规则注入内容；Hooks、Skills、其它 4 个规则文件均不改 |
4.1 前缀缓存影响（重要）¶
新增规则文件会使注入请求前缀的 system 消息内容变化。按 docs/SOP.md 18.4.1 的实测归因，
system 或 tools 定义一变，前缀几乎必然整段失效（2096 组正常请求中该变化率为 0.0%，
而失效请求中 system+tools 变化占 31.7%），从变化位置起的所有前缀（system + tools + 全部历史）
在上游缓存里整段作废。
由此有两种代价，差别约一个数量级：
| 做法 | 代价 | 依据 |
|---|---|---|
| 改完立即开新会话（正确做法） | 首条全 miss ≈ ¥0.03 | docs/SOP.md 第 1171 行：「单次成本量级：改文件 + 一次新会话首条全 miss ≈ 0.03 元（依据见 18.4.1），可忽略」 |
| 在旧会话内继续对话 | 可能 0.1 ~ 0.35 元/次（且会周期性重复） | docs/SOP.md 18.4.1 口径订正：09-21 0.118 元 → 09-22 0.588 元 → 09-23 0.536 元；只要持续改规则，前缀失效就是周期性的，不会自然收敛 |
结论：本次落地后必须开新会话，不要在当前会话里继续对话。
5. 分步操作¶
对应实现体：output-cost-20260923/apply_changes.py。以实现体为准，以下为等价序列。
cd /home/rain/Documents/services/token_proxy
# 1) 预演：只列出将执行的两项动作，不写任何文件（默认行为，无需参数）
python3 output-cost-20260923/apply_changes.py
# 预期：待变更 2 项（A1 备份 HANDOFF、A2 写规则文件），已达标 0 项
# 2) 语法预检实现体与核验脚本，避免跑坏文件
python3 -m py_compile output-cost-20260923/apply_changes.py \
output-cost-20260923/verify_changes.py
# 3) 执行：备份 HANDOFF → 新增规则文件 → 登记台账
python3 output-cost-20260923/apply_changes.py --apply
# 4) 验证（见第 6 章）
python3 output-cost-20260923/verify_changes.py
失败时的判断依据：
| 现象 | 判断 |
|---|---|
| 预演输出「待变更 0 项，已达标 2 项」 | 已应用过，无需重复执行（幂等） |
| 报「已存在且内容与源文件不同」 | 目标被第三方占用或有历史版本，停止并人工核对，勿强制覆盖 |
| 报「写入校验失败」 | 立即 --revert 删除该规则文件，再定位 |
| 报「预检失败：待备份文件不存在」 | docs/HANDOFF.md 缺失，检查工作目录 |
6. 验证¶
cd /home/rain/Documents/services/token_proxy
# 核验 11 项：交付物、结构、落地路径、逐字节一致、备份、台账、幂等、未触碰项
python3 output-cost-20260923/verify_changes.py
# 预期：结果：11/11 通过（退出码 0）
# 幂等复跑：第二次执行为零变更
python3 output-cost-20260923/apply_changes.py
# 预期：预演结束：待变更 0 项，已达标 2 项（预演不写文件）
# 逐字节比对（人工旁证）
sha256sum output-cost-20260923/rule-agent-efficiency.md \
~/.trae-cn/user_rules/rule-agent-efficiency.md
# 预期：两行 SHA256 相同
# 备份与台账
ls -l output-cost-20260923/backup/home/rain/Documents/services/token_proxy/docs/
cat output-cost-20260923/backup/README.md
真机行为验收（需你新开一次会话）：新会话中执行一个多文件读取任务，观察 Agent 是否在同一条消息内 并行调用读取工具，而非「读一个、看一眼、再读下一个」。
7. 回滚¶
备份位置：output-cost-20260923/backup/，按「去掉开头斜杠的原绝对路径」保留层次，命名
<原名>.bak.<YYYYmmdd-HHmmss>；逐条台账见 output-cost-20260923/backup/README.md
（含备份文件、原路径、备份时间、因何产生、回滚什么、何时可删）。
cd /home/rain/Documents/services/token_proxy
# 一键回滚：只删除本次新增的规则文件（路径白名单校验，内容非本次版本则拒绝删除）
python3 output-cost-20260923/apply_changes.py --revert
# 预期：已删除 ~/.trae-cn/user_rules/rule-agent-efficiency.md（备份未动）
# 回滚后复验：规则目标应不再存在，HANDOFF 备份与台账仍在
ls ~/.trae-cn/user_rules/rule-agent-efficiency.md # 预期：No such file
python3 output-cost-20260923/verify_changes.py # 预期：规则落地相关项转 FAIL，属回滚后的正常状态
# HANDOFF 正文如需一并恢复（本次不由实现体自动恢复，人工按需）
cp output-cost-20260923/backup/home/rain/Documents/services/token_proxy/docs/HANDOFF.md.bak.<时间戳> \
docs/HANDOFF.md
说明：--revert 只删规则文件、不动备份（备份是「失败能回原点」的保障，由你对照台账自行清理）。
HANDOFF 的备份不作为自动回滚目标——它的正文由主 agent 修订，是否恢复由人决定。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 新增全局规则注入后，规则内容被误读、影响面超出预期 | 规则文件只约束执行方式，并在「边界」一节明确不以「省输出」为由违反串行依赖、必要验证与取证严谨性；回滚只需 --revert 一步 |
| 覆盖已存在的同名规则文件，丢失既有内容 | 实现体在目标存在且内容不同时直接报错退出，不覆盖、不猜测；本机该路径当前不存在（纯新增） |
--revert 误删他人文件 |
删除前做双重校验：目标目录必须命中 ~/.trae-cn/user_rules/ 白名单、文件名必须为 rule-agent-efficiency.md，且内容仍等于源文件；非普通文件（符号链接）一律拒绝 |
| 本次落地触发前缀整段失效，旧会话内继续对话按次付费 | 见 4.1：改完立即开新会话，代价压到约 ¥0.03；不要在旧会话继续 |
| 文档与实现体漂移 | 第 5 章声明「以实现体为准」；核验脚本第 7 项以复跑实现体验证幂等，第 4 项校验内容一致性 |
| 台账与实际备份目录不一致 | 台账由实现体在备份成功后自动追加；核验脚本第 6 项逐条核对备份文件名是否已入账 |
| A1 幂等判据曾误判（按「内容相同」比对） | 验证阶段已修正为「backup 下已有本文件任一份 .bak 即跳过」。原因：HANDOFF 正文随后由主 agent 修订，内容必然变化，按内容比对会使修订后复跑重复备份、破坏「复跑零变更」判据（修正前核验 10/11，修正后 11/11） |
附录 A：交付物清单¶
| 路径（相对项目根） | 说明 |
|---|---|
output-cost-20260923/SOP.md |
本文 |
output-cost-20260923/rule-agent-efficiency.md |
规则源文件（写入源，逐字节复制到目标路径） |
output-cost-20260923/提问对照卡.md |
用户侧提问对照卡（M2） |
output-cost-20260923/apply_changes.py |
实现体（默认预演 / --apply / --revert） |
output-cost-20260923/verify_changes.py |
核验脚本（只读，11 项，退出码 0/非 0） |
output-cost-20260923/backup/ |
HANDOFF 变更前备份 + README.md 台账 |
output-cost-20260923/logs/apply.log |
实现体执行日志 |
落地目标（工程外）：~/.trae-cn/user_rules/rule-agent-efficiency.md
附录 B：决策经过¶
- 规则 vs 提问卡的分工：规则约束 Agent 侧（必然注入、无需用户配合），提问卡约束用户侧 （提问前自查）。两者都落盘，是因为实测显示浪费既来自执行方式也来自提问方式，缺一不可。
- 实现体只备份 HANDOFF、不改其正文：HANDOFF 是交接快照，其修订需整体重写判断（由主 agent
按
writing-handoff决定增量或重写），不属本实现体职责；实现体只保证「改前有档可回」。 - 目标已存在且内容不同时拒绝覆盖：沿用
hooks-fix-20260923的「不猜、不覆盖」原则；全局规则 目录属长期资产，静默覆盖的代价远高于一次人工核对。 - 不写
.sh交付：本次无需移交第三方手工执行，操作序列写进第 5 章即可。
2026-09-30 补充：任务提示词模板与澄清门槛¶
变更内容¶
提问对照卡.md：在原有“目标 + 范围 + 停止条件”基础上，加入目标、范围、动作、约束、验收、停止、输出七项最小模板；说明哪些任务无需套完整模板，以及范围不明时的澄清写法。- 规则源与全局规则
~/.trae-cn/user_rules/rule-agent-efficiency.md：增加“范围或验收不清时，只问一个最小澄清问题，不自行猜范围或开始探索”以及“用户明确只读时不修改、不创建交付物”两项约束。 - 不新增自动提示词评分、不改日志采集；现有台账用于后续同类任务对照，当前结论标记为【经验】，尚未完成至少 3 个同类样本验证。
备份与回滚¶
修改前版本位于 output-cost-20260923/backup/，逐项见 output-cost-20260923/backup/README.md。如需回滚，分别将台账中的规则源及全局规则备份复制回各自原路径；提问卡可用版本管理或人工按需恢复。本次未修改代理配置或服务，无需重启代理。全局规则生效需在新会话中验证。
验证¶
核对规则源与全局规则逐字节一致；检查提问卡包含七项模板和澄清门槛；检查备份与台账文件均存在。成本效果待后续至少 3 个同类任务或可比样本评估，不据单日差异宣称有效。
来源：
/home/rain/Documents/services/token_proxy/output-cost-20260923/SOP.md｜ 最后更新：2026-09-30 16:32（由build/sync.py同步，请勿在站点侧修改）