ops-execution-efficiency 技能改写 SOP¶

变更日期：2026-09-30 ｜性质：C 类变更（全局技能文本改写，无系统服务改动）交付物目录：agent-efficiency-skill-20260930/

一、背景¶

全局技能 ops-execution-efficiency 于 2026-09-30 上午创建后，经逐条审阅发现六类缺陷：

定义了档位却一条没用——成长机制规定标 【实测】/【经验】/【存疑】，正文全部条目均无标注；
turn_seq 类口径混用——「命令数就是成本」与自身实测矛盾（瓶颈是握手不是命令）；
范围与案例冲突——开头限定「多主机（≥3 台）」，但最佳案例是单节点 K8s 排障；
正文违反自身体量预算——声称数字进 references/，却在正文 §实测基线里直接放数字；
「已推翻条目」分类失效——把从未进过正文的条目混入，使该信号失去判别力；
目标定位缺失——通篇讲「省时间/省往返」，未区分「墙钟 / agent token / 目标端资源」三种代价，导致「并发」被误读为省钱手段。

触发条件：用户要求验证「提高 agent 执行效率」的机制，讨论中确认该技能是改进行为的落点，并为此建立实时度量口径。

二、目标¶

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

技能开头显式给出「约束 / 首要目标 / 次要目标」与三种代价对照表；
§6 拆为「脚本日志量」与「agent 轮次与上下文」两节，后者锚定既有度量口径；
新增「收尾自查清单」（口径与每日审查一致）与「实时消耗自查」（带阶段开关）；
新增红线 8：改动 skill / rule / command 后当轮提醒开新会话；
范围解除「≥3 台」限制；description 修掉断句歧义并把触发时机前移；
正文条目实际使用档位标注；正文不再承载实测数字（改为指针）。

三、前置条件¶

#	条件	校验命令
1	目标技能目录存在	`ls -l /home/rain/.trae-cn/skills/ops-execution-efficiency/`
2	本机 Python 3 可用（校验脚本 + 实时自查）	`python3 -V`
3	`token_proxy` 工程的 `logs/usage.jsonl` 可读（实时自查依赖）	`test -r /home/rain/Documents/services/token_proxy/logs/usage.jsonl && echo ok`
4	交付物目录可写	`touch agent-efficiency-skill-20260930/.w && rm -f agent-efficiency-skill-20260930/.w`

四、影响范围¶

涉及对象：全局技能 ops-execution-efficiency 的三份文件（SKILL.md + 2 份 references）；
不涉及：任何主机、服务、K8s 资源、token_proxy 工程文件；无端口、无进程、无 systemd 单元；
是否需停服：否。技能为纯文本，加载时才读取；
窗口期：不限。唯一副作用是改写后当前会话的前缀缓存失效一次（【实测】同类操作单条 miss=128,816、0.13 元），故改完需开新会话续接；
在跑作业：无。

RUNBOOK 判定：本次不产出 RUNBOOK.md。该技能无运行时、无服务状态、无值班操作，其使用说明即 SKILL.md 自身，无法填出 RUNBOOK 任一章节。变更产物为纯文本规则，回滚方式见第七章。

五、分步操作¶

步骤 1：备份三份原文件¶

改写前先把原文件按 backup/<相对主题目录的原路径>/ 结构落盘，保留来源路径层次，便于一眼对应。高危：覆盖原文件前必须完成本步。

TS=$(date +%Y%m%d-%H%M%S)
DEST=/home/rain/Documents/k8s_ins/agent-efficiency-skill-20260930
SRC=/home/rain/.trae-cn/skills/ops-execution-efficiency
B="$DEST/backup/home/rain/.trae-cn/skills/ops-execution-efficiency"
mkdir -p "$B/references"
cp -p "$SRC/SKILL.md"                       "$B/SKILL.md.bak.$TS"
cp -p "$SRC/references/lessons-and-retractions.md" "$B/references/lessons-and-retractions.md.bak.$TS"
cp -p "$SRC/references/measured-baselines.md"      "$B/references/measured-baselines.md.bak.$TS"
sha256sum "$SRC/SKILL.md" "$SRC/references/"*.md

预期：三份 .bak.<时间戳> 文件出现，sha256sum 输出三个校验和。失败判断：cp 非 0 或目标缺失 → 停止，不得进入步骤 2。

本次实测：TS=20260930-022457，校验和见 backup/README.md。

步骤 2：改写 `SKILL.md`¶

叙述：由 agent 以文件写入方式改写（非 shell 拼接），共 8 处变更：目标与边界表（新增）、红线 8（新增，原 7 条保留）、§2 成本口径改「会话数」、 §3 补正确性定性、§6 拆两节、收尾自查清单（新增）、实时消耗自查（新增，含阶段开关）、反例表补 2 行、§实测基线改指针、成长机制补档位使用说明；同时改写 frontmatter 的 description。

坑：① description 是唯一触发文本，必须无半角冒号+空格（:）、无尖括号，否则 YAML 需引号包裹；② name 必须与目录名一致，改名则目录也要改； ③ 技能一旦改写，当前会话 system prompt 变化会触发前缀全量重建，改完必须开新会话。

# 等价的校验动作（写入本身由 agent 的 Write 工具完成，见第六章）
python3 - <<'PY'
import re, pathlib
p = pathlib.Path("/home/rain/.trae-cn/skills/ops-execution-efficiency/SKILL.md")
t = p.read_text()
m = re.match(r"^---\n(.*?)\n---\n", t, re.S)
assert m, "frontmatter 缺失"
d = dict(re.findall(r"^(\w+):\s*(.+)$", m.group(1), re.M))
assert d["name"] == p.parent.name
assert ": " not in d["description"] and not any(c in d["description"] for c in "<>")
print("OK", d["name"], len(t.splitlines()), "行")
PY

预期：输出 OK ops-execution-efficiency 201 行。失败判断：断言失败 → 修正后重跑；连续 2 次失败即按第七章回滚。

步骤 3：改写两份 references¶

叙述：lessons-and-retractions.md 做归类修正（把 node_exporter.service、 --no-collector.cmdline 两条从「已推翻」移入「踩坑」，并补 3 条新增踩坑、4 项待办）； measured-baselines.md 补「归因说明」（126→14 是合并独享、耗时是合并+并发合计，两者从未拆分测量），新增第六节（agent 实时自查字段口径与样例）与第七节（agent 行为基线）。

坑：两处极易出错——① 原文件里已有一条「同日重复执行会覆盖本文件」类说明，改写不可丢；② 引用路径为 references/xxx.md，不要写成绝对路径。

预期：两个文件均保留原有全部表格与案例，仅做增补与归类调整。失败判断：与原文件 diff 出现大段删除 → 回滚重来。

步骤 4：登记备份台账与本文档¶

叙述：写 backup/README.md（逐条登记备份文件、原路径、时间、用途、回滚什么、何时可删，并附回滚命令与备份时点校验和）与本 SOP.md，供日后复盘与交接。

预期：backup/README.md 与 SOP.md 存在且非空。

六、验证¶

变更后逐条确认：

# 1) 结构校验（与步骤 2 同一脚本，含 references 存在性检查）
python3 - <<'PY'
import re, pathlib
p = pathlib.Path("/home/rain/.trae-cn/skills/ops-execution-efficiency/SKILL.md")
t = p.read_text(); m = re.match(r"^---\n(.*?)\n---\n", t, re.S)
assert m
d = dict(re.findall(r"^(\w+):\s*(.+)$", m.group(1), re.M))
assert d["name"] == p.parent.name and ": " not in d["description"] and not any(c in d["description"] for c in "<>")
assert all((p.parent/"references"/f).exists() for f in ["lessons-and-retractions.md","measured-baselines.md"])
print("PASS 结构校验 | 行数", len(t.splitlines()), "| description", len(d["description"]), "字")
PY

# 2) 实跑新增的实时自查命令（应输出「本轮 步数=…」且退出码 0）
cd /home/rain/Documents/services/token_proxy
python3 - <<'PY'
import json
rows=[]
with open("logs/usage.jsonl") as f:
    for line in f:
        line=line.strip()
        if line:
            try: rows.append(json.loads(line))
            except Exception: pass
tk=None
for r in reversed(rows):
    if r.get("turn_key"): tk=r["turn_key"]; break
acc=[r for r in rows if r.get("turn_key")==tk]
h=sum(r.get("cache_hit_tokens") or 0 for r in acc)
m=sum(r.get("cache_miss_tokens") or 0 for r in acc)
o=sum(r.get("completion_tokens") or 0 for r in acc)
print(f"本轮 步数={len(acc)} 命中={h} 未命中={m} 输出={o} 成本≈{h*0.02e-6+m*1e-6+o*4e-6:.4f}元")
PY

3) 开新会话后确认技能可被注册表读到（Skill 工具的可用技能列表中出现 ops-execution-efficiency），并确认新 description 生效。

本次实测结果：

检查	结果
结构校验 8 项	全部 PASS
SKILL.md 行数 / description 字数	201 行 / 90 字
实时自查命令实跑	`本轮步数=5 命中=642560 未命中=29037 输出=21481 成本≈0.1278元`，退出码 0

七、回滚¶

备份位置：agent-efficiency-skill-20260930/backup/，台账见 agent-efficiency-skill-20260930/backup/README.md。

SRC=/home/rain/.trae-cn/skills/ops-execution-efficiency
B=/home/rain/Documents/k8s_ins/agent-efficiency-skill-20260930/backup/home/rain/.trae-cn/skills/ops-execution-efficiency
TS=20260930-022457
cp -p "$B/SKILL.md.bak.$TS"                          "$SRC/SKILL.md"
cp -p "$B/references/lessons-and-retractions.md.bak.$TS" "$SRC/references/lessons-and-retractions.md"
cp -p "$B/references/measured-baselines.md.bak.$TS"      "$SRC/references/measured-baselines.md"
sha256sum "$SRC/SKILL.md" "$SRC/references/"*.md

回滚后校验和应与 backup/README.md 记录的三个原值一致；随后开新会话验证技能可加载。

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

结构校验任一 FAIL 且修正 2 次仍不通过；
技能在Skill 工具可用列表中消失（加载失败）；
校验和与备份台账不符（写入被截断）。

八、风险说明¶

风险	等级	缓解
改完在旧会话继续 → 前缀全量重建（实测单条 0.13 元）	中	已升为正文红线 8：改完当轮即提醒用户开新会话
`description` 写法非法导致技能不被注册	中	第六章结构校验含 6 项 description 约束；回滚即恢复旧 description
正文变长推高每轮加载成本	低	正文控制在 201 行，实测数字仅留指针；体量预算写入成长机制
实时自查被滥用（每步都查）反增成本	低	正文明确「不是每步都查」，并给出触发时机与读法
阶段开关遗忘，长期留在正文	低	已登记为 `lessons-and-retractions.md` 第三节待办项

附录：本次变更点清单¶

文件	变更
`SKILL.md`	frontmatter `description` 重写；新增「目标与边界」表（三种代价对照）；红线新增第 8 条；§2 改「会话数（握手数）就是成本」；§3 补 MaxStartups 的正确性定性；§6 拆为 6.1/6.2；新增「收尾自查清单」；新增「实时消耗自查（阶段开关）」；反例表补 2 行；§实测基线改指针；成长机制补档位使用说明
`references/lessons-and-retractions.md`	§一剔除 2 条从未进正文的条目并补 2 条真正被推翻的；§二新增 3 条踩坑（含「改完 skill 在旧会话继续」）；§三待办补 3 项
`references/measured-baselines.md`	新增「归因说明」（两个数字归因不同，未拆分测量）；新增第六节 agent 实时自查（字段口径、样例、不要自造聚合）；新增第七节 agent 行为基线（09-23~09-29 步/轮与四段占比）
`backup/README.md`	备份台账（新建）
`SOP.md`	本文档（新建）

九、第二轮变更（2026-09-30 02:33）：缺陷修复¶

本章为独立变更档案（第二轮），八章要素对应 9.1–9.8；第一轮见第一～八章。

9.1 背景¶

第一轮改写后，用户对技能本身提出四项质疑（是否在可用列表、description 是否新版、定位是否为「效果与效率优先、能省 token 才省」、有无表述缺陷与不自洽）。核对后确认 description 已更新且定位正确，但发现 8 项缺陷，其中 1 项为正文内部硬矛盾：

硬矛盾：§6.2 开头称「这一节才是真正省 token 的地方。前六节省的是时间」，与同文件「三种代价」表末两行（合并取数、不打成功 stdout 标注省 token 大）及表下注「想降 token 只有一条路…」冲突；且「前六节」把 §6.1/§6.2 自身包含在内，自指混乱；
description 触发退化：新版删掉了旧版两个有效信号（一次操作明显慢于预期、需要反复远程往返），且「开始…任务时使用」把排障中途转效率的场景挡在门外；
规则冲撞：§2「变更类命令保留逐条执行」易被读成与全局「复杂变更以幂等 Python 工程承载」相冲突；
术语与指针落空：收尾自查清单的「零输出步 / 无返工 / >5min 空档」在引用的 references 中无定义（真实定义在 token_proxy 的 cost-deep-review），且「零输出步」与 §6.1「默认不打成功 stdout」字面冲突；
歧义：「目标不是让被管机器上的动作变快」与「首要目标…更短等待」读起来矛盾；
表格口径未注明：门禁缓存标「省 agent token 0」仅在「手段自身直接效果」口径下成立；
开关阈值不可判定：实时自查关闭条件写「连续若干天」；
体量预算自违：成长机制称实测数字进 references/，正文却仍带环境特定数字。

触发条件：用户发起 A 类只读审阅，评估结论列出缺陷后选择「1–8 项全修」。

9.2 目标¶

description 同时表达「效果为约束、效率为首要、token 为次要」，并恢复两个触发信号；
§6.2 与表格、表下注口径一致，取消唯一性断言；
§2 界定「逐条」约束的是 agent 侧调用粒度；
三项自查术语在 references 中有可核对的生成方与口径；
关闭条件可判定；体量预算允许「量级参照」例外；
结构校验、备份校验和与复跑全部通过。

9.3 前置条件¶

#	条件	校验命令
1	第一轮变更已完成且可解析	`python3 -c "import re,pathlib;t=pathlib.Path('/home/rain/.trae-cn/skills/ops-execution-efficiency/SKILL.md').read_text();print(bool(re.match(r'^---',t)))"`
2	备份目录可写	`test -w /home/rain/Documents/k8s_ins/agent-efficiency-skill-20260930/backup && echo ok`
3	术语口径可溯源（本轮新增依据）	`grep -n "zero_out\\|gaps>5min" /home/rain/Documents/services/token_proxy/.trae/skills/cost-deep-review/scripts/session_deep_dive.py`
4	Python 3 可用（校验脚本）	`python3 -V`

9.4 影响范围¶

涉及对象：SKILL.md、references/measured-baselines.md（lessons-and-retractions.md 本轮未改）；
不涉及：任何主机、服务、K8s 资源、token_proxy 工程文件；无端口、无进程、无 systemd 单元；
是否需停服：否。技能为纯文本，加载时才读取；
窗口期：不限；在跑作业：无；
副作用：改完当轮即失效上游前缀缓存（【实测】同类操作单条 miss=128,816、0.13 元），改完必须开新会话续接。

RUNBOOK 判定：本轮同样不产出。变更产物是纯文本规则，其使用说明即 SKILL.md 自身（无运行时、无服务状态、无值班操作），填不出 RUNBOOK 任一章节；与第一轮判定一致。

9.5 分步操作¶

步骤 1：备份本轮涉及的两份文件¶

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

坑：必须用新时间戳，不得覆盖第一轮的 20260930-022457 备份——两轮回滚语义不同（第一轮回滚 = 回到最初创建版；第二轮回滚 = 回到「第一轮改写后」）。

TS=$(date +%Y%m%d-%H%M%S)
DEST=/home/rain/Documents/k8s_ins/agent-efficiency-skill-20260930
SRC=/home/rain/.trae-cn/skills/ops-execution-efficiency
B="$DEST/backup/home/rain/.trae-cn/skills/ops-execution-efficiency"
mkdir -p "$B/references"
cp -p "$SRC/SKILL.md" "$B/SKILL.md.bak.$TS"
cp -p "$SRC/references/measured-baselines.md" "$B/references/measured-baselines.md.bak.$TS"
sha256sum "$SRC/SKILL.md" "$SRC/references/measured-baselines.md"

预期：出现两个 .bak.<时间戳> 文件并输出两个校验和。失败判断：cp 非 0 或目标缺失 → 停止，不得进入步骤 2。本次实测 TS=20260930-023331，校验和见 backup/README.md 第二轮节。

步骤 2：修 `SKILL.md`（8 处）¶

叙述：由 agent 以文件写入方式逐处精确替换（不重写全文）： ① description（补回触发信号 + 明确首要/次要）；② 开头目标句消歧； ③「三种代价」表下注补「手段自身直接效果」口径；④ §2 变更类命令改为「逐条下发 + 调用粒度」； ⑤ §6.2 开头改为「降 token 的最大杠杆」并指向 §2/§6.1；⑥ 收尾自查清单补三项术语口径表； ⑦ 实时自查关闭条件量化为 3 个工作日；⑧ 体量预算允许「量级参照」。

坑：① 收尾自查表内含反引号包裹的代码（如 `completion_tokens == 0`），校验断言漏掉反引号会误报「缺失新表述」——本轮真实踩到一次； ② description 是唯一触发文本，改完必须开新会话，否则旧会话前缀全量重建。

# 等价的定位核对（写入本身由 agent 的 Edit 工具完成，校验见 9.6）
grep -n "效率不降时再省 token\|这一节是降 token 的最大杠杆\|零输出步\|量级参照" \
  /home/rain/.trae-cn/skills/ops-execution-efficiency/SKILL.md

预期：四处命中，分别落在 frontmatter、§6.2、收尾自查清单、成长机制。失败判断：命中不足 → 停止，按 9.7 回滚。

步骤 3：修 `references/measured-baselines.md`¶

叙述：第六节补「三项易混指标的生成方与口径」，口径照抄源码并标行号： 零输出步 = 轮内 completion_tokens == 0 的请求条数（session_deep_dive.py L110）； >5min 空档 = 轮内相邻请求间隔 > 300 秒（L112–L114）；无返工 = 人判读，脚本不出该指标。

坑：口径必须溯源到实现体行号；凭记忆转述会把「模型无输出」写成「命令无输出」，与 §6.1 抑制 stdout 直接冲突——这正是被修的那处不自洽。

预期：第六节新增 3 条口径与 1 条「按此取口径、不另立定义」的说明。失败判断：出现大段删除 → 回滚重来。

步骤 4：登记台账与档案¶

叙述：backup/README.md 追加第二轮台账（含校验和、回滚命令，并注明回滚会让第一轮缺陷重现）；本 SOP.md 追加本章与附录二。

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

9.6 验证¶

python3 - <<'PY'
import re, pathlib, hashlib
P = pathlib.Path("/home/rain/.trae-cn/skills/ops-execution-efficiency")
t = P.joinpath("SKILL.md").read_text()
m = re.match(r"^---\n(.*?)\n---\n", t, re.S); assert m, "frontmatter 缺失"
d = dict(re.findall(r"^(\w+):\s*(.+)$", m.group(1), re.M))
assert d["name"] == P.name and ": " not in d["description"] and not any(c in d["description"] for c in "<>")
assert len(d["description"]) <= 200
must = ["目标不是缩短单个动作的物理耗时","手段自身的直接效果","agent 侧调用\n  粒度",
        "这一节是降 token 的最大杠杆","`completion_tokens == 0` 的请求步数",
        "连续 3 个工作日","量级参照","效率不降时再省 token","反复远程往返"]
gone = ["让被管机器上的动作变快","前六节省的是时间","保留逐条执行","连续若干天","只有一条路：减少工具调用轮次"]
for s in must: assert s in t, f"缺失新表述: {s}"
for s in gone: assert s not in t, f"残留旧表述: {s}"
rb = P.joinpath("references/measured-baselines.md").read_text()
assert "零输出步" in rb and "300 秒" in rb and "人判读" in rb
B = pathlib.Path("/home/rain/Documents/k8s_ins/agent-efficiency-skill-20260930/backup/home/rain/.trae-cn/skills/ops-execution-efficiency")
exp = {"SKILL.md.bak.20260930-023331":"db0455034b8d0dbdb040c979b8b38735800209889d8137d59f8c990e503a7bd3",
       "references/measured-baselines.md.bak.20260930-023331":"d569effc5e9e2453a43272414ec0663909b17869dff768ab04d78b79f9f5788d"}
for f, h in exp.items():
    assert hashlib.sha256(B.joinpath(f).read_bytes()).hexdigest() == h, f"备份不一致 {f}"
print("PASS 全部")
PY