跳转至

rule-agent-efficiency 增补「工具选择与退化」— 变更 SOP

变更日期：2026-09-30　|　类型：C 类（全局规则变更）　|　实测时间戳：20260930-122421

一、背景

本环境的 LS 工具（Trae 目录列举工具，非 shell 命令）对部分路径长期稳定返回空：2026-09-30 实测 /home/rain/Documents/k8s_ins/agent-efficiency-skill-20260930，LS 连续调用两次均只回显父目录， 而同路径 shell ls -ld 正常（drwxrwxr-x rain rain，一级 4 条、全树 15 条），同项目对照目录 env-monitor-deploy（17 条）亦正常。改用 Glob 立即取到该目录全部 7 个文件。

由此暴露两个问题：

  1. 无效往返：LS 返回空后需补一次 Glob，多一次工具步进（= 一次完整重新推理）；
  2. 正确性风险（更严重）：把工具异常当作事实，得出「目录为空」的错误结论 —— 与技能红线「查不到 ≠ 没有」同类，属于取证失真。

用户据此要求：将该约定写入全局规则、全局生效（不限某项目），并授权由 agent 判断落点。

触发条件：用户明确指令「写入规则吧，要全局生效」。

二、目标

  • 在 rule-agent-efficiency.md 新增「工具选择与退化」一节，含 3 条约定： ① 列目录 / 文件清单优先 Glob；② LS 返回空不等于目录为空；③ 任一工具连续失败 2 次即换手段；
  • 不新建规则文件——新建 alwaysApply 文件会增加每轮固定注入成本，与本节要省的东西相悖；
  • 原有 5 节（为什么 / 执行方式 / 边界 / 停止判据）内容零改动；
  • 结构校验、内容断言、备份校验和、与备份的 diff 全部通过。

三、前置条件

# 条件 校验命令
1 规则目录存在且含 5 份规则文件 ls -1 /home/rain/.trae-cn/user_rules
2 目标文件可写、备份目录可写 test -w /home/rain/.trae-cn/user_rules/rule-agent-efficiency.md && echo ok
3 备份时间戳唯一（不覆盖既有备份） ls /home/rain/Documents/k8s_ins/tool-usage-rule-20260930/backup/home/rain/.trae-cn/user_rules/
4 变更前基线校验和已记录 sha256sum /home/rain/.trae-cn/user_rules/rule-agent-efficiency.md

变更前基线：a4e52700a9f6a2767a0ca36acc0e2645f7cd2dd30f25e4d0ef7995dab73d1ac3（25 行 / 1309 字节）。

四、影响范围

  • 涉及对象：/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md（全局规则，所有项目生效）；
  • 不涉及：任何主机、服务、K8s 资源；另外 4 份规则文件（rule-ops-*、rule-python-script-safety.md、rule-skill-index.md）本次未改；
  • 是否需停服：否。规则为纯文本，仅在会话启动时读入；
  • 窗口期：不限；在跑作业：无；
  • 副作用：规则位于会话前缀，改完当轮即失效上游前缀缓存。 【实测】PostToolUse hook 提示 约 0.35 元/次，高于改技能时的 0.13 元/次（规则在前缀更靠前，重建面更大）； 改完必须开新会话续接。

RUNBOOK 判定：本轮不产出。变更产物是纯文本规则，无运行时、无服务状态、无值班操作， 填不出 RUNBOOK 任一章节；与 agent-efficiency-skill-20260930 的判定一致。

五、分步操作

步骤 1：备份目标文件

叙述：改写前先按 backup/<相对该主题目录的原路径>/ 落盘，命名 <原名>.bak.<YYYYmmdd-HHmmss>。 高危：覆盖原文件前必须完成本步。

坑：必须用新时间戳，不得复用其它主题的备份时间戳——回滚语义不同。

TS=$(date +%Y%m%d-%H%M%S)
DEST=/home/rain/Documents/k8s_ins/tool-usage-rule-20260930
SRC=/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md
B="$DEST/backup/home/rain/.trae-cn/user_rules"
mkdir -p "$B"
cp -p "$SRC" "$B/rule-agent-efficiency.md.bak.$TS"
sha256sum "$SRC" "$B/rule-agent-efficiency.md.bak.$TS"   # 两者应一致

预期：出现 rule-agent-efficiency.md.bak.<TS> 且两个校验和相同。本次实测 TS=20260930-122421。 失败判断：cp 非 0 或校验和不一致 → 停止，不得进入步骤 2。

步骤 2：插入「工具选择与退化」一节

叙述：由 agent 以文件写入方式在「执行方式（必须）」表之后、「边界」之前插入 6 行 （1 行标题 + 1 行空行 + 3 条 + 1 行空行），不重写全文。

坑：本节措辞不得过宽——不是禁用 LS（多数目录 LS 正常），而是「列清单优先 Glob； LS 异常时立即换 Glob」。写宽了会导致正常结构浏览也弃用 LS。

# 等价的定位核对（写入本身由 agent 的 Edit 工具完成，校验见第六章）
grep -n "同类操作出现第 3 次\|^## 边界\|^## 工具选择与退化" \
  /home/rain/.trae-cn/user_rules/rule-agent-efficiency.md

预期：插入前仅命中前两项；插入后三项命中，且「工具选择与退化」位于两者之间（本章第 17 行）。 失败判断：位置错误或原有内容被改动 → 停止，按第七章回滚。

步骤 3：登记台账与交接

叙述：backup/README.md 记录本次台账（校验和、回滚命令）；本 SOP.md 记录实测值； 更新 docs/HANDOFF.md 交接快照（C 类变更收尾强制项）。

预期：三处文档非空且与实测一致（校验和、行数、时间戳照抄实测值）。

六、验证

set -e
SRC=/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md
B=/home/rain/Documents/k8s_ins/tool-usage-rule-20260930/backup/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md.bak.20260930-122421
test "$(grep -c '列目录 / 文件清单优先 Glob' "$SRC")" = 1
test "$(grep -c 'LS 返回空不等于目录为空' "$SRC")" = 1
test "$(grep -c '连续失败 2 次即换手段' "$SRC")" = 1
test "$(grep -c '17.4 步/轮' "$SRC")" = 1        # 原有内容留存
test "$(grep -c '停止判据' "$SRC")" = 1          # 原有内容留存
test "$(wc -l < "$SRC")" = 31
test "$(sha256sum "$B" | cut -d' ' -f1)" = a4e52700a9f6a2767a0ca36acc0e2645f7cd2dd30f25e4d0ef7995dab73d1ac3
echo PASS

本次实测结果：

检查 结果
行数 / 字节 25 → 31 行 / 1309 → 1759 字节
章节顺序 为什么 / 执行方式 / 工具选择与退化 / 边界 / 停止判据 —— PASS
新增三条断言（各 1 处） PASS
原有内容留存断言（各 1 处） PASS
与备份 diff 纯新增 16a17,22（6 行），无删除无改写 —— PASS
备份校验和与台账一致（回滚可用） PASS
变更后校验和 4734093905f483088747de6139f57a04094ca3cc085bf6390da1fc0441efbfd7

后续手工步骤：开新会话使新规则生效（本会话的规则是启动快照，不随文件实时刷新）。

七、回滚

备份位置：tool-usage-rule-20260930/backup/，台账见其 README.md。

SRC=/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md
B=/home/rain/Documents/k8s_ins/tool-usage-rule-20260930/backup/home/rain/.trae-cn/user_rules
TS=20260930-122421
cp -p "$B/rule-agent-efficiency.md.bak.$TS" "$SRC"
sha256sum "$SRC"     # 应为 a4e52700a9f6a2767a0ca36acc0e2645f7cd2dd30f25e4d0ef7995dab73d1ac3

回滚后校验和应与台账记录一致，随后开新会话确认规则恢复为旧版。

回滚触发条件（动手前量化，任一达标即回滚）：

  • 第六章校验断言任一失败，且修正 2 次仍不过；
  • 开新会话后规则内容与磁盘文件不一致（写入被截断）；
  • 新措辞导致正常目录结构浏览也被弃用（LS 被误禁）——属语义缺陷，回滚后重写。

八、风险说明

风险 等级 缓解
改完在旧会话继续 → 前缀全量重建 中 第四章已量化（约 0.35 元/次）；收尾即提醒开新会话
措辞过宽误禁 LS 中 条文限定「列清单优先 Glob」「异常时换 Glob」，未禁用 LS 结构浏览；列回滚判据
规则文件被其它会话覆盖（多端并发） 低 变更前后校验和比对；不一致即停止
每轮固定注入成本上升 低 未新建文件，仅增 6 行（约 450 字节），小于新建一份 alwaysApply 文件的开销

附录：交付物清单

文件 说明
SOP.md 本文件
backup/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md.bak.20260930-122421 变更前备份（回滚依据）
backup/README.md 备份台账

被变更文件（不在本目录）：/home/rain/.trae-cn/user_rules/rule-agent-efficiency.md

同批变更的交接文件：docs/HANDOFF.md（整体重写，压缩 10171 → 9230 字节）——其备份按根级档案台账制放于 docs/backup/HANDOFF.md.bak.20260930-122540，登记见 docs/backup/README.md。

来源：/home/rain/Documents/k8s_ins/tool-usage-rule-20260930/SOP.md ｜ 最后更新：2026-09-30 12:27（由 build/sync.py 同步，请勿在站点侧修改）