SOP — 效率机制修复（技能触发表横切项 / 路由表首步 / 案例入档）¶
- 主题：
agent-efficiency-rule-fix-20260930 - 类型：C 类变更（改全局规则与自建技能）
- 日期：2026-09-30
- 执行人：agent（经用户确认方案后执行）
1. 背景¶
2026-09-30 执行「Slurm 大盘 EDA 视角扩展」（见 env-monitor-deploy/docs/SOP.md 附录 G.5）时，
开局用了 1 次全项目根 Grep（撞 Permission denied、无有效结果）与 2 次 Glob
（其一为工程根 *，返回 200 条，绝大多数是 .venv / __pycache__ / 历史 precheck-*.md）
去探路；而 docs/PROJECT-MAP.md 第 1 节路由表里就写着该任务进哪个工程、先读哪份文档、入口命令。
用户据此提出质疑：「有项目地图、有相关 skill 与规则，这些都没生效吗？」
复盘（只读取证）确认事实如下：
| 层 | 本次是否生效 | 证据 |
|---|---|---|
| SessionStart Hook | ✅ 生效，但只注入两样——中文指令 + docs/HANDOFF.md |
token_proxy/sessionstart-hook/session-start-inject.py 的 main() |
| 5 份 user_rules（含「禁止全仓库通配」） | ✅ 进了上下文 | 其正文即每轮注入的 <user_rules>；rule-agent-efficiency.md 第 1 行标题与注入内容一致 |
docs/PROJECT-MAP.md |
❌ 未读（不自动注入，靠 HANDOFF 指针按需读取） | 本次未调用任何工具读它 |
ops-execution-efficiency 技能正文 |
❌ 未加载 | 仅以一行 description 出现在可用技能清单 |
根因是机制缺口，不是条款缺失：rule-skill-index.md 的技能触发表全是任务对象型
（写 SOP / 执行部署 / 读档案 / 写 HANDOFF / 出报告 / 建工具工程 / 改技能 / 改命令），
没有一条覆盖「任何多步执行类任务」。而 ops-execution-efficiency 恰是横切关注点技能
（管「我怎么做」，不绑定具体产物），description 给的又是「已出现反复往返、耗时超预期」
这类事后信号 —— 结果它在真实执行中长期不被加载，技能里「先测量再优化」「对照验证」
那套机制永远拿不到真实样本。
2. 目标¶
| # | 可验证目标 | 判据 |
|---|---|---|
| 1 | 「多步执行类任务 → 先加载效率技能」成为必然触发 | rule-skill-index.md 触发表含该行 |
| 2 | 「涉具体工程先读路由表」「检索列举须限定目录」写入执行方式表 | rule-agent-efficiency.md 含两行 |
| 3 | 本次案例与改前基线入档，可支撑后续对照验证 | lessons-and-retractions.md 含案例 10 与待办 |
3. 前置条件¶
- 三份文件可写且改前可读（均为用户级文件，
~/.trae-cn/下） - 改前备份已完成并登记（见第 7 章）
- 无需重启 Trae：
user_rules/与skills/由会话读取；只有改hooks.json才需重启 - 无外部依赖、无目标机、无服务启停
4. 影响范围¶
| 项 | 说明 |
|---|---|
| 影响对象 | 所有项目、所有会话（全局规则与全局技能） |
| 生效时点 | 下一次新会话（旧会话的 system/user 前缀已固定，缓存不会自动跟进） |
| 成本 | 新增 3 行 ≈ 每步百万分之几元（测算见附录 B）；一次性前缀重建约 0.35 元/次 |
| 需否停服 | 否 |
| 窗口期 | 无约束（不触碰任何服务、主机与集群） |
| 回滚 | 覆盖三份备份即可，见第 7 章 |
5. 分步操作¶
本次为规则文件的手工编辑，无部署实现体；下面给出与本次改动等价、幂等的可复现命令 （重复执行第二次为「已存在，跳过」）。所有路径均为用户级绝对路径，不含凭据。
步骤 1：改前备份¶
三份文件各存一份带时间戳备份到本主题 backup/，目录层次保留原相对路径以便回滚时一眼对应。
cd /home/rain/Documents/k8s_ins
STAMP=$(date +%Y%m%d-%H%M%S); D=agent-efficiency-rule-fix-20260930
mkdir -p "$D/backup/user_rules" "$D/backup/skills/ops-execution-efficiency/references"
cp -a ~/.trae-cn/user_rules/rule-skill-index.md "$D/backup/user_rules/rule-skill-index.md.bak.$STAMP"
cp -a ~/.trae-cn/user_rules/rule-agent-efficiency.md "$D/backup/user_rules/rule-agent-efficiency.md.bak.$STAMP"
cp -a ~/.trae-cn/skills/ops-execution-efficiency/references/lessons-and-retractions.md \
"$D/backup/skills/ops-execution-efficiency/references/lessons-and-retractions.md.bak.$STAMP"
预期：三个 .bak. 文件生成（本次实测 2195 B / 1568 B / 7765 B）。
失败判断：任一 cp 非 0 → 停止，不得进入后续步骤（无备份不回滚）。
坑：~ 在非交互 shell 下不会展开，必须用 $HOME 或 ~ 由 shell 展开；
本命令在交互 shell 中执行，~ 可用。
步骤 2：rule-skill-index.md 触发表加横切项¶
在原触发表首行之前插入一行。这是本次最关键的改动——它把「效率技能」从「靠自觉加载」 变成「规则要求加载」。
坑：不能按「表格第 N 行」定位，SearchReplace 之类按文本匹配的工具会因全/半角引号差异
匹配失败（本次实际踩到一次）；用表头行 + 幂等关键字定位最稳。
python3 - <<'PY'
import pathlib
p = pathlib.Path.home() / ".trae-cn/user_rules/rule-skill-index.md"
text = p.read_text(encoding="utf-8")
if "任何多步执行类任务" in text:
print("已存在，跳过")
else:
row = ("| **任何多步执行类任务**（部署 / 巡检 / 排障 / 改造，或任务已出现反复探索、"
"往返与耗时明显超出预期） | `ops-execution-efficiency` |\n")
anchor = "| 触发情形 | 加载技能 |\n|---|---|\n"
assert anchor in text, "定位锚缺失，人工确认表头"
p.write_text(text.replace(anchor, anchor + row, 1), encoding="utf-8")
print("已插入")
PY
预期：首次输出「已插入」，重跑输出「已存在，跳过」。
失败判断：AssertionError: 定位锚缺失 → 表头被改过，人工确认后再插入，不要盲写。
步骤 3：rule-agent-efficiency.md 执行方式表加两行¶
python3 - <<'PY'
import pathlib
p = pathlib.Path.home() / ".trae-cn/user_rules/rule-agent-efficiency.md"
text = p.read_text(encoding="utf-8")
if "PROJECT-MAP.md" in text and "检索与列举" in text:
print("已存在，跳过")
else:
rows = (
"| 涉及具体工程的任务 | 动手前先读 `docs/PROJECT-MAP.md` 第 1 节路由表定位工程与入口命令，"
"不靠扫目录猜结构 |\n"
"| 检索与列举 | 限定目录并排除 `.venv`、`__pycache__`、依赖目录；"
"不在项目根用 `**/*` 通配；结果设上限 |\n"
)
anchor = "| 情形 | 要求 |\n|---|---|\n"
assert anchor in text, "定位锚缺失，人工确认表头"
p.write_text(text.replace(anchor, anchor + rows, 1), encoding="utf-8")
print("已插入")
PY
预期：首次「已插入」，重跑「已存在，跳过」。
步骤 4：案例与待办入档（技能 references）¶
把本次案例（第 10 条）与「对照验证」待办写入
~/.trae-cn/skills/ops-execution-efficiency/references/lessons-and-retractions.md：
案例插在「## 三、待办」之前，待办条目插在该节首条之前。
grep -n "有 PROJECT-MAP 却越过路由表\|A/B 规则改动的对照验证" \
~/.trae-cn/skills/ops-execution-efficiency/references/lessons-and-retractions.md
预期：输出两行行号（本次实测第 91 行与第 115 行）。 说明：本步骤内容为整段中文叙述，逐字写入本主题 SOP 的附录 C 与本文件同目录的案例段， 不再复制到命令块中，避免两处漂移。
6. 验证¶
| 检查 | 命令 | 预期 | 本次实测 |
|---|---|---|---|
| A 落地 | grep -n "任何多步执行类任务" ~/.trae-cn/user_rules/rule-skill-index.md |
命中 1 行 | 命中（第 14 行） |
| B 落地 | grep -n "第 1 节路由表\|检索与列举" ~/.trae-cn/user_rules/rule-agent-efficiency.md |
命中 2 行 | 命中（第 11、12 行） |
| D 落地 | grep -n "有 PROJECT-MAP 却越过路由表\|A/B 规则改动的对照验证" <references 路径> |
命中 2 行 | 命中（第 91、115 行） |
| 生效 | 开新会话后观察首轮 cache_miss 是否较旧基线抬高一次（前缀 3 行变化） |
抬高约等于 3 行 token 量 | 待下次会话确认 |
| 行为 | ≥3 个同类任务或 3 个可比工作日复测步/轮与成本 | 步数与成本不劣化 | 已登记为待办（lessons-and-retractions.md §三） |
7. 回滚¶
备份位置与台账：agent-efficiency-rule-fix-20260930/backup/README.md
（三份 .bak.20260930-224938）。回滚即用备份覆盖原名：
D=/home/rain/Documents/k8s_ins/agent-efficiency-rule-fix-20260930/backup
cp -a "$D/user_rules/rule-skill-index.md.bak.20260930-224938" ~/.trae-cn/user_rules/rule-skill-index.md
cp -a "$D/user_rules/rule-agent-efficiency.md.bak.20260930-224938" ~/.trae-cn/user_rules/rule-agent-efficiency.md
cp -a "$D/skills/ops-execution-efficiency/references/lessons-and-retractions.md.bak.20260930-224938" \
~/.trae-cn/skills/ops-execution-efficiency/references/lessons-and-retractions.md
回滚后验证：上面第 6 章的三条 grep 应全部无命中。
回滚触发条件（任一达标即回滚）：新会话出现规则相关异常；效率技能被滥加载到明显拖慢简单任务；
复测显示成本或步数连续两个可比样本恶化。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 横切触发行让简单任务也加载长技能（SKILL.md 约 7.6 KB），反而增成本 | 技能 description 已声明「不用于单条只读命令答疑与一步到位的简单改动」；触发行限定「多步执行类」并给出「已出现反复探索/往返超预期」的备选条件；复测若发现滥加载即收紧 |
| 全局规则每轮注入，篇幅增长永久计入上下文 | 本次仅 +3 行（≈60 token），实测边际成本 0.0000012 元/步，可忽略（见附录 B）；后续新增须同样核算 |
| 改后旧会话前缀失效，在旧会话继续会反复重建 | 改完当轮即提醒开新会话；不在旧会话重复加载新内容 |
| 触发表与技能 description 可能漂移 | 触发行只写触发条件与技能名，不复制技能正文；技能自身改动时两者一起检查 |
附录¶
A. 交付物清单¶
| 交付物 | 路径 | 说明 |
|---|---|---|
| 本档案 | agent-efficiency-rule-fix-20260930/SOP.md |
八章变更档案 |
| 备份台账 | agent-efficiency-rule-fix-20260930/backup/README.md |
三条备份的登记与回滚指引 |
| 备份文件 | agent-efficiency-rule-fix-20260930/backup/{user_rules,skills}/…bak.20260930-224938 |
三份 |
| 被改文件 | ~/.trae-cn/user_rules/rule-skill-index.md、~/.trae-cn/user_rules/rule-agent-efficiency.md、~/.trae-cn/skills/ops-execution-efficiency/references/lessons-and-retractions.md |
均在项目外 |
B. 缓存计费实测（本次核心事实，来自 token_proxy/logs/usage.jsonl）¶
最后一轮逐步（同一会话，seq=3）：
| 步 | 未命中 | 命中 |
|---|---|---|
| 1 | 571 | 241920 |
| 2 | 4890 | 242432 |
| 7 | 271 | 267776（距上一步 9 分钟，仍命中） |
结论： 1. 每会话首次请求把整个前缀（system + 全部 user_rules + HANDOFF 注入 + 工具定义）计入未命中； 此后每步、每轮均按命中价（0.02 元/百万）重放——不是「每轮重新未命中」； 2. 缓存可跨轮、跨 9~14 分钟有效；真正触发大额未命中的是前缀变化（加载新技能、改规则/技能、开新会话）； 3. 本任务链基线（21:30 后，同一会话）：58 步 / 0.7925 元，四段占比 命中 23.4% / 未命中 22.3% / 输出 54.3%；单步均价 0.0137 元，其中上下文重放仅 0.0032 元/步； 4. 推论（推翻此前「规则每轮付费所以要省着加」的顾虑）：加 1 行 ≈ 0.0000012 元/步， 而省掉一次多余工具调用 ≈ 0.0137 元 —— 相差约四个数量级，规则该加就加，真正的杠杆是步数与输出。
C. 术语与口径¶
- 「步」= 一次请求（一次工具调用）；「轮」= 一次用户提问内的全部步进；口径与
cost_audit/daily_review.py一致。 - 计费（元/百万 token）：命中 0.02 / 未命中 1.0 / 输出 4.0。
- 复测方法见
ops-execution-efficiency的 SKILL.md「效率优化的对照验证」。
来源：
/home/rain/Documents/k8s_ins/agent-efficiency-rule-fix-20260930/SOP.md｜ 最后更新：2026-09-30 22:50（由build/sync.py同步，请勿在站点侧修改）