SOP — 部署工具工程技能通用性与可移植性改造¶

本文档对应主题目录 skill-portability/，记录 2026-09-24 对全局技能 deployment-tool-engineering（原名 developing-python-deploy-scripts）的改造。变更对象是全局资产（技能 + 规则 + slash 命令），不在本工程 git 内。

1. 背景¶

该技能的既定目标用户已明确为「符合通用部署行业规范的技能，Python 只是当前唯一的落地实现」。但改造前状态有三处偏离：

层次混杂：正文同时装着机制层（通用）、Python 实现层（venv/编码规范/基类写法）与领域层（Lustre 样例），无法判断哪条规则与语言或领域绑定。
领域样例干扰复用：references/lustre-reference.md 把「照抄的骨架」与「必须删除的领域特征」写在同一份文件里，跨领域复用时须先读懂 Lustre 才能提取骨架。
名实不符：技能名与边界表把实现栈写死为 Python，机制层无法被其它实现语言引用。

此外对照通用部署行业规范，缺三项机制：制品来源可信、独立漂移检测入口、多主机分批与失败容忍阈值。

2. 目标¶

技能名与领域、实现语言解耦，机制层正文零领域词、零实现栈绑定。
references/ 按主题分流：通用骨架、Python 实现栈、共享库契约各一份，互不嵌套。
三项机制写入正文，并同步进「交付前自检」与「常见反例」，具备验收判据。
正文明确声明变更单元边界（主机型 / 声明式），并加「一个工程只用一种变更单元」红线。
全仓（~/.trae-cn/）无旧技能名残留引用。

3. 前置条件¶

变更对象：全局技能目录、user_rules/ 三份规则、commands/ 一个 slash 命令、另一技能正文。
权限：普通用户可写，无需提权。
依赖：无外部服务依赖；python3 可用（用于 frontmatter 校验）。
执行前检查：先列出全部引用点，避免漏改。

# 列出所有引用旧技能名的位置（执行前核验，共 5 个文件 + 技能自身 + 台账）
grep -rIl "developing-python-deploy-scripts" /home/rain/.trae-cn

4. 影响范围¶

项	内容
主机 / 组件	本机（操作机），不涉及任何远端主机
受影响资产	`/home/rain/.trae-cn/skills/deployment-tool-engineering/`（改名 + 重写）、`user_rules/rule-skill-index.md`、`user_rules/rule-ops-scenario-routing.md`、`user_rules/rule-python-script-safety.md`、`commands/deploy-py.md`、`skills/writing-ops-change-sop/SKILL.md`
是否需停服	否
窗口期	无限制；但改完后按 Hook 提醒应开新会话，避免在失效的缓存前缀上继续累积成本
在跑业务	无。不涉及 Slurm / LSF 节点
最大风险	引用点漏改会使技能索引指向不存在的技能名；规则文件语法损坏会影响所有新会话的规则加载

5. 分步操作¶

本次变更由 Agent 直接编辑文件完成，没有实现体脚本；以下为与实现等价的操作序列，供复核与手工复现。删除与覆盖均属高危动作，各自的前置备份已在第 1 步完成。

# 1. 备份全部受改文件（高危前置：备份先于一切修改）
TS=$(date +%Y%m%d-%H%M%S)                    # 备份时间戳
DEST=/home/rain/Documents/lustre_ins/skill-portability
# 备份技能正文、技能目录内旧台账、3 份规则、1 个命令、1 个技能
cp -p <各原文件> "$DEST/backup/..."           # 结构见 backup/README.md

# 2. 技能目录改名（name 必须与目录名一致）
mv /home/rain/.trae-cn/skills/developing-python-deploy-scripts \
   /home/rain/.trae-cn/skills/deployment-tool-engineering

# 3. 技能目录内旧 backup/ 迁出（高危：删除前先 cmp 校验副本一致）
cmp <技能目录内副本> <备份区副本> && rm -rf <技能目录内 backup/>

# 4. 重写 SKILL.md：frontmatter 改名 + 正文分层 + 三项机制 + 变更单元红线
#    （写入后核对：行数 < 500、name 与目录名一致、description 无冒号空格与尖括号）

# 5. references 重建（高危：删除领域样例前已留档）
rm <技能目录>/references/lustre-reference.md
# 新增 references/skeleton.md（领域无关骨架）、references/python-stack.md（Python 实现栈）
# 重写 references/shared-lib-contract.md（执行通道表述通用化）

# 6. 同步 5 处外部引用：旧名 → deployment-tool-engineering
#    rule-skill-index.md ×2 处、rule-ops-scenario-routing.md ×2 处（含「单一源」章节指向）、
#    rule-python-script-safety.md ×1 处、commands/deploy-py.md ×1 处、
#    skills/writing-ops-change-sop/SKILL.md ×1 处

失败判断依据：任一步返回码非 0、cmp 不一致、或第 6 步后仍能检索到旧名残留，即视为失败，按第 7 章回滚。

6. 验证¶

# 1. 旧名残留清零（预期只剩 permission/tasks/*.json 历史授权记录，那是审计留痕、不参与加载）
grep -rIn "developing-python-deploy-scripts" /home/rain/.trae-cn

# 2. frontmatter 与结构校验（实测输出见下）
python3 -c "<校验脚本：name 与目录名一致、name 合法、description 合规、references 齐全、行数>"

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

校验项	结果
name 与目录名一致	True（`deployment-tool-engineering`）
name 合法（kebab-case、2–64）	True
description 无冒号空格 / 尖括号 / TODO，含 Use when 与 Do not use	True
正文引用的 references 齐全	True（`skeleton.md` / `python-stack.md` / `shared-lib-contract.md`）
SKILL.md 行数	282（< 500）
5 个被改文件 frontmatter 完好	True
旧名残留	仅 4 条 permission 历史记录

7. 回滚¶

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

# 1. 技能目录名改回（回滚必须先改名，否则备份无处覆盖）
mv /home/rain/.trae-cn/skills/deployment-tool-engineering \
   /home/rain/.trae-cn/skills/developing-python-deploy-scripts

# 2. 技能正文与 references 还原（高危：覆盖，先确认目录名已改回）
cp -p <backup>/global-skills/developing-python-deploy-scripts/SKILL.md.bak.20260924-004859 \
      /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md
cp -p <backup>/global-skills/developing-python-deploy-scripts/references/lustre-reference.md.bak.20260924-004859 \
      /home/rain/.trae-cn/skills/developing-python-deploy-scripts/references/lustre-reference.md
cp -p <backup>/global-skills/developing-python-deploy-scripts/references/shared-lib-contract.md.bak.20260924-004859 \
      /home/rain/.trae-cn/skills/developing-python-deploy-scripts/references/shared-lib-contract.md
# 删除本轮新增的 references/skeleton.md、references/python-stack.md

# 3. 五处外部引用还原（cp -p 覆盖回原路径）
#    user_rules/ 三份、commands/deploy-py.md、skills/writing-ops-change-sop/SKILL.md
# 4. 技能目录内 backup/ 还原（可选，若要完全回到改造前布局）

回滚后验证：grep -rIl "deployment-tool-engineering" /home/rain/.trae-cn 应无残留（除 permission 历史），技能目录名与 name 一致。

8. 风险说明¶

风险	缓解措施
5 处引用漏改，技能索引指向不存在的名字	执行前先 `grep -rIl` 列全清单；执行后再次全仓检索验证
规则文件写坏 frontmatter 或误删内容	改前逐份备份；改后校验 frontmatter 完好 + 逐行 diff 复核
技能正文重写导致机制条款丢失	以原正文为基线逐节迁移，机制条款只增不减；行数与章节数可比对
重建备份的局限：`references/` 两个改造前版本由 Agent 读取内容重建，不是文件系统副本	台账已如实标注；如回滚后发现与原版有差异，以功能等价为准
删除技能目录内 `backup/` 造成备份丢失	删除前 `cmp` 校验副本一致；已迁入本主题 `backup/` 并登记台账
缓存前缀失效导致后续成本上升	变更集中在一次会话内完成，收尾后开新会话

附录 A — 交付物清单¶

文件	说明
`skill-portability/SOP.md`	本文件
`skill-portability/backup/README.md`	备份台账（10 条）
`skill-portability/backup/global-skills/…`	技能与另一技能的改造前版本
`skill-portability/backup/user_rules/…`	三份规则文件的改造前版本
`skill-portability/backup/commands/…`	slash 命令的改造前版本

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

附录 B — 本轮决策记录¶

决策	结论	理由
技能改名	`developing-python-deploy-scripts` → `deployment-tool-engineering`	目标定位是语言无关的通用部署工程规范，旧名把实现栈写死
领域样例	删除 `lustre-reference.md`，代之以领域无关的 `skeleton.md`	参考物带领域载荷会污染复用；骨架诉求保留
实现层归属	Python 落地（venv/依赖/编码/基类写法）下沉 `python-stack.md`	正文保持纯机制层；「Python 环境单一源」由规则文件改指向该文件
共享库契约	上移判据、改动影响面、不复制副本三条留在正文	属语言无关的通用契约，不是 Python 实现细节
三项机制	制品来源可信、漂移检测入口、分批与失败阈值全部纳入	用户确认；均同步进自检与反例
变更单元边界	正文明写主机型假设 + 单一变更单元红线	避免规则被声明式场景误引；K8s 类目标本次不写内容，只留边界

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