SOP — 部署工具工程技能设计深化¶
对应主题目录
skill-design-refine/，记录 2026-09-24 对全局技能deployment-tool-engineering的第二轮改造（设计缺陷修复）。变更对象是全局资产（技能正文与 references），不在本工程 git 内。上一轮（改名与三层分离）见skill-portability/SOP.md。
1. 背景¶
上一轮完成技能改名与「机制层 / 实现层 / 领域层」分层后，复读正文发现四类缺陷：
- 自洽性漏洞：
references/skeleton.md的「参考实现」节把/home/rain/Documents/lustre_ins写成绝对路径。该文件是跨机器复用的全局资产，硬编码本机路径即随机器失效；且等于把上一轮已删除的领域样例换了个位置保留，与「机制层零领域词」的目标冲突。 - 三处边界未定义：
--force与「校验不通过即中止、不提供跳过开关」并存却未划清边界，实现者可用--force绕过制品来源校验；危险目标「允许配置覆盖推导结果」会被用来固化白名单；预检查「一次性汇总全部不符合项」与幂等「unknown 一律中止」的粒度差异未区分。 - 措辞归属错位：适用边界称「三档无条件生效」，而第 1 档写的是「不加载本技能」——三条红线实际来源是全局规则，非本技能授予，措辞把归属搞混。
- 缺存量工程改造路径：全部条款以「新建工程」为前提（「新建工程不从空白文件开始」、自检项「新工程骨架是否同构」），对按旧约定建成的工程如何向本规范收敛无任何条款。
2. 目标¶
references/skeleton.md不再出现任何本机路径，领域工程只以类目方式被引用。--force与危险目标配置覆盖两条边界写死，并同步进反例表。- 门禁与幂等的 unknown 粒度差异写进正文。
- 适用边界的三条红线明写来源为全局规则。
- 新增「存量工程的规范化改造」节，含对应自检项与反例。
- 交付前自检与常见反例分「阻断 / 建议」两级，标出拒收线。
3. 前置条件¶
- 变更对象：
/home/rain/.trae-cn/skills/deployment-tool-engineering/下的SKILL.md与references/skeleton.md。 - 权限：普通用户可写，无需提权。
- 依赖：
python3可用（用于 frontmatter 与结构校验）。 - 执行前检查：确认上一轮备份台账仍在（
skill-portability/backup/），本轮备份与之并列存放、不混用。
4. 影响范围¶
| 项 | 内容 |
|---|---|
| 主机 / 组件 | 本机（操作机），不涉及任何远端主机 |
| 受影响资产 | SKILL.md（六处修订）、references/skeleton.md（一处修订） |
| 是否需停服 | 否 |
| 窗口期 | 无限制；改完按 Hook 提醒应开新会话，避免在失效的缓存前缀上继续累积成本 |
| 在跑业务 | 无。不涉及 Slurm / LSF 节点 |
| 最大风险 | 写坏 frontmatter 会使技能无法加载，影响所有新会话的技能路由 |
5. 分步操作¶
本次变更由 Agent 直接编辑文件完成，没有实现体脚本；以下为与实现等价的操作序列，供复核与手工复现。以实现体（上述两个文件本身）为准。
# 1. 备份受改文件（高危前置：备份先于一切修改）
TS=$(date +%Y%m%d-%H%M%S) # 备份时间戳
DEST=/home/rain/Documents/lustre_ins/skill-design-refine/backup/global-skills/deployment-tool-engineering
mkdir -p "$DEST/references"
cp -p /home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md \
"$DEST/SKILL.md.bak.$TS"
cp -p /home/rain/.trae-cn/skills/deployment-tool-engineering/references/skeleton.md \
"$DEST/references/skeleton.md.bak.$TS"
# 2. 修订 SKILL.md 六处（均为定点替换，不重写整文件）
# 2a 适用边界：三条红线写明来源为全局规则，与是否加载本技能无关
# 2b 门禁节：补 unknown 粒度差异（门禁汇总、幂等中止）
# 2c CLI 条款：新增「--force 的边界」——制品来源、环境契约、危险目标三项无开关
# 2d 危险目标判定：配置覆盖改为「只能收窄不能放宽」，须与推导结果同台输出
# 2e 新增「存量工程的规范化改造」节（置于「工程结构与编码规范」之后）
# 2f 交付前自检与常见反例分级：阻断项 / 建议项，反例表加「级别」列
# 3. 修订 references/skeleton.md 一处（高危：覆盖，改前已备份）
# 「参考实现」节 → 「适用对象与参照物」：删除本机绝对路径，改为类目表述，
# 并补存量工程的反向指引（不套用骨架照抄）
失败判断依据：任一步返回码非 0、或第 6 章校验任一项不通过，即视为失败，按第 7 章回滚。
6. 验证¶
# 1. 本机路径与领域词残留清零（预期无输出）
grep -rn "lustre\|/home/rain/Documents" /home/rain/.trae-cn/skills/deployment-tool-engineering
# 2. frontmatter 与结构校验：可解析、name 与目录名一致且合法、
# description 无 ": " 与尖括号且含 Use when、行数 < 500、引用的 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('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('行数:', len(t.splitlines()))
print('缺失 references:', [r for r in set(re.findall(r'references/([\w.\-]+\.md)', t)) if not (root/'references'/r).exists()] or '无')
PY
实测结果（2026-09-24 01:00）：
| 校验项 | 结果 |
|---|---|
| frontmatter 可解析 | True |
| name 与目录名一致 | True（deployment-tool-engineering） |
| name 合法（kebab-case、2–64） | True |
| description 无冒号空格 / 尖括号，含 Use when | True |
| SKILL.md 行数 | 309（< 500） |
| 正文引用的 references 齐全 | True（skeleton.md / python-stack.md / shared-lib-contract.md） |
| 本机路径 / 领域词残留 | 0 命中 |
7. 回滚¶
备份位置：skill-design-refine/backup/，逐条登记见 skill-design-refine/backup/README.md。
# 高危：覆盖，执行前先确认目标路径与本轮时间戳
cp -p <backup>/global-skills/deployment-tool-engineering/SKILL.md.bak.<TS> \
/home/rain/.trae-cn/skills/deployment-tool-engineering/SKILL.md
cp -p <backup>/global-skills/deployment-tool-engineering/references/skeleton.md.bak.<TS> \
/home/rain/.trae-cn/skills/deployment-tool-engineering/references/skeleton.md
回滚后验证：grep -rn "存量工程的规范化改造" /home/rain/.trae-cn/skills/deployment-tool-engineering 应无命中（该节属本轮新增）；再跑一次第 6 章的 frontmatter 校验应通过。
与上一轮回滚的关系：skill-portability/backup/ 的备份本轮未动，两轮互不覆盖。但上一轮回滚会把技能目录名改回旧名，若只回滚本轮、不动上一轮，目录名保持 deployment-tool-engineering 即可。
8. 风险说明¶
| 风险 | 缓解措施 |
|---|---|
| 定点替换匹配失败或误匹配到别处 | 每处替换的匹配段含足够上下文；替换后逐处 diff 复核 |
| frontmatter 写坏导致技能无法加载 | 改后跑 frontmatter 校验（可解析、name 一致、description 合规、行数） |
| 分级削弱原有自检力度，漏掉真阻断项 | 阻断判据固定为「不可逆性、数据安全、门禁或幂等失效」，不按主观排序 |
| 新增节与既有条款重复或冲突 | 新节只写存量工程特有做法，通用条款一律用引用指向既有节 |
| 缓存前缀失效导致后续成本上升 | 变更集中在一次会话内完成，收尾后开新会话 |
附录 A — 交付物清单¶
| 文件 | 说明 |
|---|---|
skill-design-refine/SOP.md |
本文件 |
skill-design-refine/backup/README.md |
备份台账（2 条） |
skill-design-refine/backup/global-skills/deployment-tool-engineering/SKILL.md.bak.20260924-010000 |
技能正文的改造前版本 |
skill-design-refine/backup/global-skills/deployment-tool-engineering/references/skeleton.md.bak.20260924-010000 |
骨架文件的改造前版本 |
改造后资产位置：/home/rain/.trae-cn/skills/deployment-tool-engineering/（SKILL.md 309 行 + references/{skeleton,python-stack,shared-lib-contract}.md）。
附录 B — 本轮决策记录¶
| 决策 | 结论 | 理由 |
|---|---|---|
| 变更单元粒度 | 维持工程级红线不变 | 用户决定；工程级能让幂等、门禁与回滚的定义天然统一 |
--force 边界 |
制品来源、环境契约、危险目标拒绝三项无开关 | 与「不提供跳过校验开关」的红线保持一致，消除条文矛盾 |
| 危险目标配置覆盖 | 只能收窄不能放宽，且与推导结果同台输出 | 覆盖口子只允许让工具更保守，无法被用来放行危险目标 |
| 存量工程改造 | 新增独立一节，不散写进既有条款 | 新建与改造的操作序列相反（骨架照抄 vs 差距评估），混写易误用 |
| 自检分级判据 | 不可逆性 / 数据安全 / 门禁或幂等失效 → 阻断，其余建议 | 与既有红线体系一致，避免分级退化为主观排序 |
来源：
/home/rain/Documents/lustre_ins/skill-design-refine/SOP.md｜ 最后更新：2026-09-24 01:01（由build/sync.py同步，请勿在站点侧修改）