xinetzone/SpecWeave / .agents/skills/atomization-finalize-cmd
atomization-finalize-cmd
Verified当用户提到'原子化收尾'、'finalize atomization'、'文档拆分完成'、'文件移动后处理'、'断链修复导航更新'、'一键收尾'、'重构完成后整理'时,必须使用此技能。原子化/文件移动/目录重构后的一键收尾工具:自动断链修复→导航表更新→Spec看板刷新→验证摘要。不要手动逐个执行后处理步骤——本Skill封装了正确的执行顺序和dry-run预览机制,是文档原子化工作流的标准最后一步。
Atomization Finalize 原子化一键收尾 Skill
⚠️ 本Skill是脚本命令门面(L1索引层),遵循渐进式披露三层架构:
- L0:.agents/ONBOARDING.md(入口速查)
- L1:本文件(<500行,触发词+决策树+核心命令+安全清单)
- L2:脚本源码 finalize-atomization.py + commands/atomization.md(完整规范)
1. Skill ID
atomization-finalize-cmd
2. 功能描述
原子化拆分、文件移动、目录重构后的标准一键收尾工具,按正确顺序自动执行三个后处理步骤:
| 步骤 | 功能 | 底层脚本 |
|---|---|---|
| 步骤1:断链修复 | 自动检测并修复相对路径错误、绝对路径转换 | check-links.py --fix |
| 步骤2:导航更新 | 重新生成 README.md / docs/README.md 文档导航表 | docgen.py nav |
| 步骤3:看板刷新 | 更新 .trae/specs/ 执行进度看板和根README状态 | docgen.py dashboard |
提供两种执行模式:
| 模式 | 推荐场景 | 优势 |
|---|---|---|
| 预览模式(--dry-run) | ⭐ 首次执行、验证收尾范围 | 零风险,展示将要执行的所有操作 |
| 实际执行 | ⭐ 预览确认后正式收尾 | 一键完成,输出验证摘要 |
为什么用本Skill而非手动执行三个脚本? 文档原子化后有三个高频遗留问题:断链、导航过时、看板不准。手动逐个执行容易遗漏步骤或顺序错误(比如先更新导航再修复链接,导致导航表引用了断链);本Skill封装了经过验证的执行顺序(链接→导航→看板),且每步都有错误捕获和状态报告,确保收尾质量可预测。
3. 何时使用本技能
当用户提到以下任何内容时触发:
- "原子化收尾"、"finalize atomization"、"一键收尾"、"收尾工作"
- "文档拆分完成"、"文件移动后处理"、"目录重构后整理"
- "断链修复导航更新"、"更新链接和导航"、"刷新看板"
- 使用 atomization-cmd 完成原子化拆分后
- 提到
finalize-atomization.py脚本
关于触发:原子化拆分是高频操作,但"拆分完就完了"是最常见的遗漏——忘记收尾会导致断链、过时导航、看板状态错误,这些问题会在后续使用中陆续暴露且难以追溯来源。只要完成了文件移动/拆分/重构,就应该使用本Skill收尾,不要等到出问题才补救。
4. 方案选择决策树
完成了文件移动/原子化/目录重构?
├─ 首次执行,不确定影响范围? → 预览模式(--dry-run,第5.1节)
├─ 预览确认无误? → 实际执行(第5.2节)
├─ 只做了小范围文件重命名,导航/看板不受影响? → 加 --no-nav --no-dashboard 只修链接
├─ 链接已经用 link-check-cmd 单独修过了? → 加 --no-links 跳过链接修复
└─ 只是单个Spec目录的变更,不需要全项目扫描? → --target <目录> 指定目标
子模块边界:待收尾文档在
projects/<submodule>/内时,本脚本(主仓 check-links/ docgen/看板设施)作用域不覆盖,改用 submodule-atomization-finalize-cmd;vendor/第三方只读子模块禁止修改。
⚠️ 强制:触发时记录输入参数日志
决策前输出CMD_START日志(session前缀 fin-YYYYMMDD-<topic>):
[CMD-LOG] | level=INFO | cmd=atomization-finalize | step=S0 | event=CMD_START | session=fin-... | msg=开始原子化收尾:<简述> | ctx={"target_dir":"..."}
为什么决策前必须记录日志? 收尾操作涉及断链修复和索引更新,影响范围广,CMD_START记录目标目录便于回溯变更范围。
执行原则:必须先用 --dry-run 预览,确认修复范围符合预期再实际执行。
为什么顺序是「链接→导航→看板」不能乱? 导航表和看板都包含文件链接,如果先生成导航再修链接,导航表中会写入断链路径;反过来,先修复链接确保所有路径正确,再生成导航和看板才能保证引用一致性。这就像装修——先修好水电(链接是基础设施),再刷墙铺地(导航/看板是表层展示)。
5. 核心命令(快速开始)
5.1 预览模式(推荐首次执行)
cd d:\spaces\SpecWeave
# 全项目预览(不修改任何文件,强烈推荐先执行)
python .agents/scripts/finalize-atomization.py --dry-run
# 指定目录预览(只扫描目标目录及其相关引用)
python .agents/scripts/finalize-atomization.py --dry-run --target docs/retrospective/
5.2 实际执行(预览确认后)
# 完整收尾(链接修复 + 导航更新 + 看板刷新)
python .agents/scripts/finalize-atomization.py
# 指定目录收尾
python .agents/scripts/finalize-atomization.py --target .agents/skills/
5.3 跳过部分步骤
# 只修复链接,跳过导航和看板(小范围重命名场景)
python .agents/scripts/finalize-atomization.py --no-nav --no-dashboard
# 只更新导航和看板,链接已人工确认
python .agents/scripts/finalize-atomization.py --no-links
# 只刷新看板(Spec状态变更但无文件移动)
python .agents/scripts/finalize-atomization.py --no-links --no-nav
5.4 收尾后验证
实际执行成功后,脚本会提示进一步验证命令:
# 完整链接检查(确认零断链)
python .agents/scripts/check-links.py
# 全量CI检查(所有质量门禁)
python .agents/scripts/ci-check.ps1
完整参数说明见脚本源码
--help输出。
6. 各步骤详情
| 步骤 | 做什么 | 不做什么 | 失败处理 | 幂等性 |
|---|---|---|---|---|
| 断链修复 | 修复相对路径层级、file:///转相对、斜杠补全 | 不删除不存在的文件引用(标注为需人工处理) | 输出"需人工处理"清单,不阻断后续步骤 | 已修复路径不再重复修改 |
| 导航更新 | 扫描docs/和根目录.md,更新README.md导航表 | 不修改导航表以外的内容 | 报告错误,继续执行看板步骤 | 基于当前文件状态重新生成,幂等 |
| 看板刷新 | 扫描.trae/specs/,更新根README.md中的看板区域 | 不修改Spec文件本身 | 报告错误 | 基于当前Spec状态重新生成,幂等 |
链接修复的详细能力说明见 link-check-cmd 第6节。
7. 安全检查清单(执行前逐项确认)
- Git工作区已提交或有备份(防止意外修改可回滚)
- 已执行
--dry-run预览,确认修复范围和变更文件列表符合预期 - 预览中"需人工处理"的断链数量在预期内(文件删除导致的断链是正常的)
- 指定了正确的
--target(如适用),避免全项目扫描 - 明确知道哪些步骤被跳过(如使用了 --no-* 参数)
- 执行后重新运行检查模式确认无遗留问题
- 如有重大变更,考虑运行完整CI检查
为什么执行前必须要求Git工作区有备份? 虽然finalize脚本是幂等的且只修改标记区域,但断链自动修复涉及多个文件的路径替换——在复杂场景(如跨目录移动、符号链接、特殊字符文件名)下,自动修复有极低概率产生非预期修改。有Git备份意味着可以用
git checkout .一键回滚,把"可能出问题"的风险降到零成本回滚。
8. 常见错误处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| 大量"无法自动修复"的断链 | 目标文件确实已被删除 | 人工确认:删除的文件需要移除引用,移动的文件需要检查路径 |
| 导航表更新后格式错乱 | 手动修改过导航表区域标记 | 检查导航表是否被 <!-- nav-start -->/<!-- nav-end --> 标记包裹 |
| 看板更新不反映最新状态 | Spec文件frontmatter缺失status字段 | 检查对应spec.md的TOML frontmatter |
| 跨盘符引用无法修复 | Windows环境限制 | 人工处理,考虑统一盘符或使用绝对路径白名单 |
| 子进程调用失败 | Python环境或依赖问题 | 单独执行底层脚本(check-links.py/docgen.py)定位具体错误 |
脚本输出采用彩色编码:绿色✓是成功,黄色⚠是警告(需关注但不阻断),红色✗是失败。
9. Gotchas(陷阱与反直觉行为)
为什么需要Gotchas? 错误处理记录"已知错误码及修复方式",Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。
- 必须在atomization-cmd完成后立即运行:不要在原子化拆分和收尾之间插入其他文件编辑操作,否则会导致文件状态不一致,断链修复可能基于过时的文件树进行。原子化完成后应第一时间执行收尾。
- dry-run预览不会修改任何文件:首次运行务必先加
--dry-run参数,脚本只会输出将要执行的操作和变更文件列表,不会实际写入磁盘。确认变更范围符合预期后再去掉dry-run正式执行。 - 断链修复会自动调整相对路径层级:自动修复
../层级和斜杠方向时,可能因复杂目录结构产生非预期路径。修复完成后必须人工抽查几个关键链接,确认路径跳转正确。 - docgen会更新所有导航表:导航更新会扫描docs/和根目录并重新生成所有标记区域内的导航表,这属于预期变更,需要一并提交。不要因为"怎么改了这么多文件"而惊讶——这是设计行为。
- 收尾验证失败时需回滚到原子化前状态:如果最终验证发现大面积断链或导航错乱,不要在错误状态上继续尝试修复。使用
git checkout .回滚所有变更,分析问题原因后重新原子化和收尾。
10. 关键参考
| 参考 | 层级 | 路径 | 何时查阅 |
|---|---|---|---|
| 脚本源码(完整参数) | L2 | finalize-atomization.py | 需要高级参数或排障时 |
| 原子化命令规范 | L2 | commands/atomization.md | 理解原子化完整工作流 |
| 链接检查Skill | L1 | link-check-cmd | 单独执行链接检查/修复时 |
| 文档生成Skill | L1 | docgen-cmd | 单独更新导航/看板时 |
| 共享工具库 | L2 | scripts/lib/ | 理解底层实现 |
11. Changelog
- v1.1.0 (2026-07-01): 在§4决策树后添加S0 CMD_START强制日志规范,记录触发时的输入参数(target_dir)便于回溯变更范围;补充第3个Why解释(Git工作区备份的必要性)。
- v1.0.0 (2026-06-30): 初始版本,基于finalize-atomization.py脚本封装为命令门面Skill,遵循五要素模型和渐进式披露三层架构。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |