Docs Alignment Maintainer 是一项面向工作区多仓库场景的文档一致性维护技能。
用途 它用于在给定工作区根目录下的各个仓库中进行确定性的两轮文档对齐工作流：先检测文档漂移（drift），再按需应用有界且高置信度的修复。
输入参数 运行时输入从调用提示中传入：
- --workspace <path>
- --exclude <path>（可重复）
- 可选 --exclude-file <path>（每行一个路径） 技能正文中不硬编码默认值，以便自动化按每次运行控制范围。
工作流
- 使用 scripts/docs_alignment_maintainer.py 运行第一轮发现与检查。
- 查看未对齐的仓库和问题类别。
- 如需安全修复，使用 --apply-fixes 运行第二轮。
- 重新检查被触及的仓库（由脚本处理）并检查剩余问题。
- 从 Markdown 与 JSON 输出中报告结果。
命令示例
仅审计：
python3 scripts/docs_alignment_maintainer.py
--workspace ~/Workspace
--exclude ~/Workspace/services
--print-md
--print-json
审计并安全修复：
python3 scripts/docs_alignment_maintainer.py
--workspace ~/Workspace
--exclude ~/Workspace/services
--apply-fixes
--md-out /tmp/docs-alignment-report.md
--json-out /tmp/docs-alignment-report.json
存在未解决问题时使运行失败：
python3 scripts/docs_alignment_maintainer.py
--workspace ~/Workspace
--exclude ~/Workspace/services
--apply-fixes
--fail-on-issues
安全规则
- 绝不自动提交更改。
- 仅编辑文档（例如 README.md、CONTRIBUTING.md、ROADMAP.md、docs/*.md）。
- AGENTS.md 不在本技能范围内，由专门的 AGENTS 维护工作流负责。
- 绝不编辑源代码、lockfile 或清单文件。
- 仅在证据明确时应用有界替换和简洁的 quickstart 插入。
- 保持最小差异并保留现有格式风格。
输出契约 脚本输出：
- Markdown 摘要，包含运行上下文、发现摘要、未对齐仓库、已应用修复、剩余问题、修改的文件和错误。
- JSON 报告，包含：run_context、repos_scanned、unaligned_repos、fixes_applied、post_fix_status、errors。 JSON 用于自动化流水线，Markdown 用于操作者审阅。
自动化模板 在自动化提示中使用 $docs-alignment-maintainer，以便 Codex 可靠加载该技能上下文。 用于可直接填写的 Codex App 与 Codex CLI（codex exec）模板（含护栏、占位符和自定义开关）请参见 references/automation-prompts.md。
参考文档
- 常见检查与发现规则：references/checks-common.md
- Swift 指南：references/checks-swift.md
- JS/TS 指南：references/checks-js-ts.md
- Python 指南：references/checks-python.md
- Rust 指南：references/checks-rust.md
- 安全修复策略边界：references/fix-policies.md
- 报告模式与分节契约：references/output-contract.md
- 自动化提示模板：references/automation-prompts.md
限制 官方文本未提供，具体支持范围与失败处理细节暂未提供。