部署脚本技能完备性加固 — 变更实施手册（SOP）¶

变更对象：/home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md（全局技能，非 git 管理）变更类型：交付物变更（技能规范文本），不涉及任何主机、服务与生产数据 实现体为准：第 5 章的 shell 代码块用于阅读与手工复现，改动内容本身以第 5.2 节的差异清单为准关联主题：py-skill-hardening/（上一轮，通用能力上移共享库）；本轮只做技能文本，不动共享库与工程代码

1. 背景¶

起因是需求侧的确认题：新建一个部署工具时，只读这份技能，产出的工程能否天然具备通用性与复用性。

复核结论是「部分能保证」：行为纪律与共享库复用已闭环，但有 4 处留白会使产出物在不同工程间分叉：

留白	现象
U1	无入口层骨架、无编排层门禁写法、无"动手前先读参考工程"的指引
U2	配置只规定"校验哪五类"，无顶层结构约定，配置无法跨工程互认
U3	技能只出现 `apply_change()` 等方法名，无签名，且未要求动手前读共享库源码
U4	共享库缺能力时只写"先补共享库"，未定变更规则，也未定改完如何回归全部挂载工程
U5	技能内「发行版/ubuntu/yum/apt」零命中，平台适配无规范
U6	只覆盖首次装机，扩容与卸载无规范
U7	目录结构只是示意树，无起手骨架，复用起点靠人肉重建

此外发现一处口径与事实不符：技能称共享库为「独立 git 仓库」，实测 git -C /home/rain/py_public_modules 报"不是 git 仓库"。

2. 目标¶

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

技能新增 4 个章节：开工前必读、配置顶层结构（跨工程互认的最小集）、共享库变更与回归、平台适配与生命周期边界
自检清单新增 3 条（配置顶层结构、共享库能力确认与回归、骨架同构）
共享库章节的口径修正为与事实一致（"应纳入独立 git 仓库管理"）
文件规模仍满足技能规范（< 500 行）；frontmatter 未改动，触发条件不变
技能新增的唯一命令（列出挂载工程）在真机实测可执行
全部改动为纯新增 + 1 处行替换，无意外删改

3. 前置条件¶

项	要求	检查命令
技能文件	可写，路径存在	`ls -l /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md`
变更前备份	已归档并记录 md5	`ls -l skill-completeness/backup/global-skills/developing-python-deploy-scripts/`
参考工程	存在且骨架完整（新增章节指向它）	`ls /home/rain/Documents/lustre_ins/{main.py,deployer.py,config/deploy.yaml.example}`
挂载工程清单	新增命令可执行	`find /home/rain/Documents -maxdepth 8 -name "modules.pth" -path "/.venv/*"`
变更窗口	无（纯文本，即时生效）	—

4. 影响范围¶

维度	说明
主机	仅操作机上的一个技能文件；不触达任何目标节点
组件	全局技能 `developing-python-deploy-scripts`（被所有引用它的会话加载）
是否停服	否
窗口期	无
连带影响	改动 skill 会使上游前缀缓存失效，建议改完开新会话再继续，避免在失效前缀上反复累积成本
其它工程	不影响共享库与既有工程代码；仅影响"下次新建工程时技能的指导内容"

5. 分步操作¶

5.1 备份（变更前，已执行）¶

cd /home/rain/Documents/lustre_ins
TS=20260923-223135
DEST=skill-completeness/backup/global-skills/developing-python-deploy-scripts
mkdir -p "$DEST"                                      # 保留来源路径层次
cp -p /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md "$DEST/SKILL.md.bak.$TS"
md5sum "$DEST/SKILL.md.bak.$TS"                        # 1a433a02f67ca64d58b064a5ee81fc31，389 行
# 台账见 skill-completeness/backup/README.md

5.2 技能文本改动（共 6 处，纯新增 + 1 处替换）¶

对应实现文件：/home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md

# 1) 新增「## 开工前必读」（置于「改动范围」之后、「预检查与变更门禁」之前）
#    三点：读共享库源码确认签名（不猜 API）；以 /home/rain/Documents/lustre_ins 为起手骨架（列举照抄文件）；
#    骨架照抄、领域重写。达标判据：main.py / deployer.py 与参考工程同构
# 2) 新增「### 配置顶层结构（跨工程互认的最小集）」（置于「配置合法性校验」章末）
#    必备两段 nodes（按角色分组，节点含 host 与 ssh_user 一类执行身份）与 precheck（阈值 + skip_checks）；
#    领域段命名自由但须 snake_case 且样例/校验/实现三处一致；凭据不入版本管理的配置文件
# 3) 新增「## 共享库变更与回归」（置于「共享库 py_public_modules」之后）
#    只追加不改签名；应纳入 git，未纳入时改动前后手工备份并登记台账；
#    改完对全部挂载工程回归（py_compile + 导入 + 入口 --help），给出列举命令；禁止工程内另写通用实现
# 4) 新增「## 平台适配与生命周期边界」（置于「标准执行流程」之前）
#    平台差异下沉到配置或适配分支；覆盖初次安装/增量扩容/巡检/回滚；卸载与退役未覆盖，遇事先出方案
# 5) 自检清单新增 3 条（配置顶层结构、共享库能力确认与回归、骨架同构）
# 6) 口径修正：共享库「独立 git 仓库」→「不属于任何单个工程；应纳入独立 git 仓库管理，见『共享库变更与回归』」

改动量的独立复核（不依赖编辑记录）：

BK=skill-completeness/backup/global-skills/developing-python-deploy-scripts/SKILL.md.bak.20260923-223135
SK=/home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md
diff -u "$BK" "$SK" | grep -c '^+[^+]'     # 新增 29 行（另有 13 行新增空行）
diff -u "$BK" "$SK" | grep '^-[^-]'        # 仅 1 行被替换（共享库位置口径）
wc -l "$SK"                                # 431 行，低于 500 行上限

6. 验证¶

6.1 规范层（技能文件自检，已执行）¶

项	命令	实测结果
行数上限	`wc -l SKILL.md`	431 行（改前 389），符合"well under 500"
代码块闭合	grep -c '```' SKILL.md	6（偶数，3 组），无未闭合围栏
frontmatter	`grep -n "^name:\\|^description:" SKILL.md`	`name` 与目录名一致，description 未改动（无 `:`、无尖括号），触发条件不变
章节结构	`grep -n "^## " SKILL.md`	18 个二级章节（新增 3 个）+ 1 个新增三级小节，位置正确：39 开工前必读 / 86 配置顶层结构 / 276 共享库变更与回归 / 371 平台适配与生命周期边界
交叉引用	手工核对	「共享库 py_public_modules」指向「共享库变更与回归」；「开工前必读」指向参考工程实际存在的文件
领域词泄漏	`grep -niE "lustre\\|ldiskfs\\|ost\\|mgs\\|lnet" SKILL.md`	仅命中新增的参考工程路径（`lustre_ins`），属刻意指向，非规范内容被领域化

6.2 内容正确性（与实现体对齐，已执行）¶

项	核对方式	结果
参考工程骨架描述	读 `main.py` 与 `deployer.py` 结构	技能列举的 `_collect_precheck()` / `_write_precheck_report()` / `_gate()` / `cmd_*()` / `_run_steps()` 均真实存在；`execute()` 中确实调用 `self._gate(self._subcommand)`
配置顶层约定	读 `config/deploy.yaml.example` 顶层键	`nodes`（`mgs_mds` / `oss` / `clients` 按角色分组）与 `precheck` 段均存在；节点字段为 `host` + `ssh_user`，技能措辞已据此对齐
共享库 API 引用	读 `base_module.py` 接口清单	技能点名的 `run()` / `apply_change()` / `auto_backup()` / `check_idempotent()` / `confirm_danger_operation()` 均存在
新增命令可用	真机执行 `find ... -name "*modules.pth"`	列出 11 个挂载点，命令有效
共享库 git 事实	`git -C /home/rain/py_public_modules log`	报"不是 git 仓库"，故技能口径改为"应纳入"而非"已是"

6.3 回滚可用性¶

md5sum /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md   # 与备份 md5 不同，确认确实改过

备份与回滚命令见第 7 章，已按 backup/README.md 登记。

7. 回滚¶

备份位置¶

备份目录：skill-completeness/backup/global-skills/developing-python-deploy-scripts/
备份文件：SKILL.md.bak.20260923-223135（389 行，md5 1a433a02f67ca64d58b064a5ee81fc31）
台账：backup/README.md

回滚步骤¶

cp -p /home/rain/Documents/lustre_ins/skill-completeness/backup/global-skills/developing-python-deploy-scripts/SKILL.md.bak.20260923-223135 \
      /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md   # 覆盖回改前版本

回滚后验证¶

md5sum /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md   # 预期：1a433a02f67ca64d58b064a5ee81fc31
grep -c "^## 开工前必读" /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md   # 预期：0
wc -l /home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md   # 预期：389

回滚只还原技能文本；本次未触碰共享库、工程代码与任何节点，无需联动回滚。

8. 风险说明¶

风险	等级	缓解措施
新增内容与既有章节冲突（如配置约定、共享库约束）	中	逐条比对：配置约定是对既有"校验五类"的补充而非替代；共享库新增章与"三条约束"角度不同（能力粒度 vs 模块粒度），已核对无矛盾
技能膨胀导致加载成本上升	低	净增 42 行（389→431），仍在 500 行上限内；新增内容为可执行指引，非叙述
参考工程路径硬编码	低	位置与既有共享库路径同级，均为本机全局约定；参考工程若移动，需同步该路径（已在章节内明确指向，便于全文检索替换）
改动 skill 使上游前缀缓存失效	低	收尾后开新会话继续，避免在失效前缀上累积成本
规范写了但未被遵守	中	已同步进「交付前自检清单」，使新工程交付时可勾选核对

9. 附录¶

9.1 交付物清单¶

路径	内容
`/home/rain/.trae-cn/skills/developing-python-deploy-scripts/SKILL.md`	加固后的技能本体（389→431 行）
`skill-completeness/SOP.md`	本文档
`skill-completeness/backup/README.md`	备份台账
`skill-completeness/backup/global-skills/developing-python-deploy-scripts/SKILL.md.bak.20260923-223135`	改前备份（回滚用）

9.2 决策记录¶

只改技能文本，不改共享库与工程：本次缺口全在"给 AI 的指令完备性"上，改实现体无法解决；共享库无 git 属基础设施问题，技能里写成"应纳入"并给出未纳入时的补偿动作，是否初始化 git 由用户决定。
采用"参考工程同构"而非"新建脚手架模板"：脚手架要长期维护且会与参考工程漂移；指向一个持续被维护的真实工程，成本最低、失真最小。
配置只约定前两层：nodes + precheck 是跨工程唯一需要互认的部分，领域段强制统一会扼杀工程差异。
平台适配与卸载写"边界"而非"流程"：当前只有 RHEL 9 系与首次安装的实践，硬写流程等于编造未验证的规范，故只声明覆盖面与处置要求。

9.3 遗留事项（需人工决策，本次未改动）¶

共享库 /home/rain/py_public_modules 仍未纳入 git（技能已要求"应纳入"，但未执行）——是否初始化由用户决定。
技能第 326 行起的「标准目录结构」列出 docs/HANDOFF.md 与 troubleshoot.md，正文仍无这两份文档的产出时机与单一源规定；本工程 docs/ 至今无 HANDOFF.md。
存量工程 eda_lsf_luster 仍自带 ops_lib/modules/base_module.py 旧副本，未纳入共享库体系；技能未规定存量工程迁移规则。
lustre_ins 的 .pth 文件名为 public_modules.pth，与技能命令及其它工程使用的 py_public_modules.pth 不一致（功能无碍，口径不一）。

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