SOP — 全局技能 deployment-tool-engineering 条款修订（第三轮）¶

对应主题目录 skill-clause-fix/，记录 2026-09-24 对全局技能 deployment-tool-engineering 的第三轮改造（条款缺陷修订）。变更对象是全局资产（技能正文），不在本工程 git 内。第一轮（改名与三层分离）见 skill-portability/SOP.md，第二轮（设计深化）见 skill-design-refine/SOP.md。

本轮与前两轮的触发点不同：前两轮来自复读正文的自我审查；本轮来自以真实工程（本工程 lustre_ins）为对象、按技能条款实跑一遍的实战验证。

1. 背景¶

第二轮改造新增了「存量工程的规范化改造」节与「阻断 / 建议」分级的交付前自检，留下一项未验证事项：两项新条款未经实战检验。

本轮以本工程为验证对象。lustre_ins 属典型的存量工程——2026-09-22 起按早期版本技能建成，已有门禁（precheck 子命令 + 配置校验 + 变更前自动门禁）、幂等三态探测、共享库挂载，但无 bundle、无环境契约文件、无独立只读漂移检测入口。以此逐条比对现状与规范，检验新条款是否可操作、分级能否拦住真阻断项。

验证结论：新条款可用且有价值。

「安全网向内」的改造顺序与本工程实际演进史吻合：先做 precheck-hardening（门禁与配置校验），再上移共享库，bundle 与环境契约至今未做；先有门禁确实使后续改动可验证。
分级自检抓到了两个纸面推演发现不了的真问题（详见附录 B），均属阻断级。

同时暴露技能自身三处缺陷，即本轮修订对象。

2. 目标¶

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

--force 条款区分「放行校验」与「高危不可逆动作的显式确认」两种语义，后者不再被判为不符
存量工程渐进改造期间，尚未补齐的契约 / bundle 类阻断项按差距清单登记，不再与「交付前自检」的阻断判据冲突
「多主机一次性全量下发」的分级限定为「数据面不可逆」；仅服务与配置面且动作可重入时降为建议
frontmatter 可解析、name 与目录名一致、行数 < 500、正文引用的 references/ 齐全
技能正文不含本机绝对路径与领域词

3. 前置条件¶

项	要求	检查命令
变更对象	`/home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md`（唯一受改文件）	`ls -l /home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md`
权限	普通用户可写，无需提权	`test -w /home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md && echo writable`
依赖	`python3` 可用	`python3 --version`
备份台账	前两轮备份仍在（`skill-portability/backup/`、`skill-design-refine/backup/`），本轮与之并列、不混用	`ls skill-portability/backup skill-design-refine/backup`

4. 影响范围¶

维度	说明
主机	本机（操作机），不涉及任何远端主机
组件	全局技能 `deployment-tool-engineering` 的 `SKILL.md`
受影响资产	`SKILL.md` 三处修订（净增 3 行，309 → 312 行）
是否停服	否
窗口期	无限制。改完技能会使上游前缀缓存失效，按 Hook 提醒收尾后开新会话
在跑业务	无。不涉及 Slurm / LSF 节点
数据影响	无。仅改技能正文，不触碰任何被管理主机

5. 分步操作¶

本次变更由 Agent 直接编辑文件完成，没有实现体脚本；以下为与实现等价的操作序列，供复核与手工复现。以实现体（SKILL.md 本身）为准。

# 1. 备份受改文件（高危前置：备份先于一切修改）
TS=$(date +%Y%m%d-%H%M%S)                         # 备份时间戳
DEST=/home/rain/Documents/lustre_ins/skill-clause-fix/backup/global-skills/deployment-tool-engineering
mkdir -p "$DEST"
cp -p /home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md \
      "$DEST/SKILL.md.bak.$TS"

# 2. 修订 SKILL.md 三处（均为定点替换，不重写整文件）
#    2a 「工程结构与编码规范」节 →「--force 的边界」：
#       由「只用于放行可恢复场景」改为「只承担两类语义」——
#       ① 放行可恢复场景；② 高危不可逆动作的显式执行确认；
#       并补明「校验必须先于 --force 判定完成」
#    2b 「存量工程的规范化改造」节末新增一条「渐进期不与交付分级冲突」：
#       未补齐的契约 / bundle 类项按差距清单登记，不按阻断判交付未完成
#    2c 「分批与失败容忍」节新增「分级」一条；反例表「多主机一次性全量下发」
#       拆为两行：数据面不可逆 → 阻断；仅服务与配置且可重入 → 建议

失败判断依据：任一步返回码非 0、或第 6 章校验任一项不通过，即视为失败，按第 7 章回滚。

6. 验证¶

# 1. 结构校验：frontmatter、name、description、行数、references 齐全、三处修订命中
python3 - <<'PY'
import re, pathlib
root = pathlib.Path('/home/rain/.trae-cn/skills/deployment-tool-engineering')
t = (root/'SKILL.md').read_text(encoding='utf-8')
fm = re.match(r'^---\n(.*?)\n---\n', t, re.S).group(1)
name = re.search(r'^name:\s*(.+)$', fm, re.M).group(1).strip()
desc = re.search(r'^description:\s*(.+)$', fm, re.M).group(1).strip()
print('frontmatter 可解析: True')
print('name 与目录名一致:', name == root.name, '| 合法:', bool(re.fullmatch(r'[a-z0-9]+(-[a-z0-9]+)*', name)))
print('desc 合规:', ': ' not in desc and '<' not in desc and '>' not in desc and 'Use when' in desc)
print('SKILL.md 行数:', len(t.splitlines()))
print('缺失 references:', [r for r in set(re.findall(r'references/([\w.\-]+\.md)', t)) if not (root/'references'/r).exists()] or '无')
for key in ['只承担两类语义', '校验必须先于', '渐进期不与交付分级冲突', '数据面不可逆变更', '动作可重入']:
    print(f'修订点命中 [{key}]:', t.count(key))
PY

# 2. 本机路径与领域词残留清零
grep -rn "lustre\|/home/rain/Documents" /home/rain/.trae-cn/skills/deployment-tool-engineering   # 预期无输出

实测结果（2026-09-24 01:11）：

校验项	结果
frontmatter 可解析	True
name 与目录名一致 / 合法	True（`deployment-tool-engineering`）
description 无冒号空格与尖括号、含 Use when	True
SKILL.md 行数	312（修订前 309，< 500）
正文引用的 references 齐全	True（`skeleton.md` / `python-stack.md` / `shared-lib-contract.md`）
修订点命中	5 处全部命中（「动作可重入」2 处：分批节 + 反例表）
本机路径 / 领域词残留	0 命中

7. 回滚¶

备份位置：skill-clause-fix/backup/，逐条登记见 skill-clause-fix/backup/README.md。

# 高危：覆盖，执行前先确认目标路径与本轮时间戳
cp -p /home/rain/Documents/lustre_ins/skill-clause-fix/backup/global-skills/deployment-tool-engineering/SKILL.md.bak.20260924-011014 \
      /home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md

回滚后验证：grep -c "渐进期不与交付分级冲突" /home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md 应为 0（该条属本轮新增）；再跑一次第 6 章的结构校验应通过。

与其它轮次的关系：skill-portability/backup/ 与 skill-design-refine/backup/ 的备份本轮未动，三轮互不覆盖。若需连续回滚多轮，按第三轮 → 第二轮 → 第一轮倒序执行，否则中间轮的备份会覆盖目标状态。

8. 风险说明¶

风险	等级	缓解措施
定点替换匹配失败或误匹配到别处	中	每处替换的匹配段含足够上下文；替换后逐处 diff 复核，并用第 6 章的命中计数确认
frontmatter 写坏导致技能无法加载	中	改后跑 frontmatter 校验（可解析、name 一致、description 合规、行数）
三处修订改变条款语义，影响既有工程判据	中	三处均为「放宽误判」方向：收紧的是表达精度，未放松任何安全要求；三项无开关的红线原文未动
新增「渐进期不与交付分级冲突」被用作跳过阻断项的借口	中	条文限定为「按差距清单逐条登记（含豁免理由与补齐计划）」，且仅在存量工程渐进改造期间适用；清单清零后回到原分级
「仅服务与配置面」的判断被扩大化以规避分批	低	条文以「动作可重入」为限定条件，并要求仍做前置逐台可用性复核
缓存前缀失效导致后续成本上升	低	变更集中在一次会话内完成，收尾后开新会话

附录 A — 交付物清单¶

文件	说明
`skill-clause-fix/SOP.md`	本文件
`skill-clause-fix/backup/README.md`	备份台账（1 条）
`skill-clause-fix/backup/global-skills/deployment-tool-engineering/SKILL.md.bak.20260924-011014`	技能正文的修订前版本

改造后资产位置：/home/rain/.trae-cn/skills/deployment-tool-engineering/（SKILL.md 312 行 + references/{skeleton,python-stack,shared-lib-contract}.md）。

本轮未产出独立验证报告：验证过程与发现直接写入本 SOP 的「背景」与「附录 B」，避免同一事实两处维护。

附录 B — 验证发现与决策记录¶

B.1 验证抓到的两个真问题（对象：本工程 `lustre_ins`）¶

#	问题	证据	技能条款判定
1	危险目标覆盖可放宽	共享库 `precheck_module.derive_system_disks` 中 `if override: return {...}`——`disk_safety.system_disks` 非空即整体替换推导结果，推导不执行；`docs/SOP.md` 第 8 章更明写「若判定有误，可在 `disk_safety.system_disks` 中人工覆盖」	违反「覆盖只能收窄不能放宽」，且无 WARN、无与推导结果同台输出。技能条款抓对了
2	探测失败被当成「需要变更」	`utils/idempotent_utils.is_lustre_target_formatted` 返回 bool，文件头注释直言「False 表示未完成或检测失败」；探测失败即判未格式化 → 进入 `mkfs.lustre` 分支，仅靠下游 `_validate_device()` 二次 BLOCK 兜底	违反「unknown 一律中止」。技能条款抓对了，同时暴露漏点在「把三态折成 bool 的包装函数」

对照：同工程的 modules/mount_targets.py 已正确三态（unknown 报错跳过），说明是局部漏点而非全局失守。

B.2 本轮修订的三处（决策理由）¶

#	修订	结论	理由
1	`--force` 语义	由「只用于放行可恢复场景」改为「放行 + 高危不可逆动作的显式确认」两类	原措辞把 `lustre_ins` 的合法用法（`--force` 确认 mkfs、校验在 force 之前完成、未被绕过）判成不符，属条款过窄；同时补明校验顺序，防止「确认」被误读成「放行」
2	存量工程渐进期分级	存量节新增一条，未补齐的契约 / bundle 类阻断项按差距清单登记	原条文自相冲突：改造顺序要求 bundle 与契约放最后，而自检把它们列为阻断项——改造中途按阻断判即等于永远不可交付
3	分批判据	「多主机一次性全量下发」按数据面可分性拆为两行（阻断 / 建议）	原分级对所有场景一刀切；服务与配置面且动作可重入时，失败只是半途而废，不触数据安全

来源：/home/rain/Documents/lustre_ins/skill-clause-fix/SOP.md ｜最后更新：2026-09-24 01:11（由 build/sync.py 同步，请勿在站点侧修改）