05
Link Rot · workflow
docs-link-rot
05-docs-link-rot.md
◉
WHAT IS THIS
定位Markdown 文档断链巡查。它检查相对路径、锚点、旧目录名、图片、跨文档引用，重点解决重构后文档看似存在但跳转失败的问题。
⚡
TRIGGERS
触发场景▸大量移动目录或重命名模块后。
▸文档里出现旧目录名。
▸Obsidian、GitHub、docs site 三种链接规则混用。
▸架构文档引用的 ADR、PRD 或 plan 已被删除。
▸发布前需要保证 docs site 不出现 404。
↹
INPUT & OUTPUT
输入 / 产出↘ INPUT
- 所有
.md、.mdx。 - 静态图片和附件目录。
- docs site 路由生成规则。
- 旧目录到新目录的 mapping，可选。
↗ OUTPUT
- 断链报告。
- 锚点失效报告。
- 旧目录名映射建议。
- 可提交的链接修复 patch。
🪜
STEPS
编排步骤- 1收集链接从 Markdown AST 或稳定 parser 提取 link、image、HTML anchor。
- 2分类链接分为相对路径、绝对路径、URL、Obsidian wiki link、锚点、图片。
- 3验证文件存在相对当前文档目录解析，检查目标文件。
- 4验证锚点对目标 Markdown 提取 heading，生成 slug，检查
#section。 - 5识别旧目录名用历史 mapping 或 git rename 找候选修复路径。
- 6批量修复对确定唯一映射的链接直接改。多候选的进入人工确认列表。
- 7跑 docs build如果有 docs site，跑 build 或 preview smoke。
⚙
AGENT ROLES
Agent 分工⚙
Link Extractor
提取所有链接。
⚙
Path Verifier
验证文件存在。
⚙
Anchor Verifier
验证 heading slug。
⚙
Migration Mapper
推断旧目录到新目录。
⚙
Patch Agent
只改确定链接。
✓
ACCEPTANCE GATE
验收 gate- ✓所有相对路径存在。
- ✓所有 Markdown 锚点存在。
- ✓图片路径存在。
- ✓旧目录名没有生产引用。
- ✓docs build 或 link check 通过。
- ✓不把外部 URL 当成本地路径误修。
⊘
FAILURE HANDLING
失败处理多个候选路径时不自动改，输出候选。
GitHub slug 和 docs site slug 不同，按目标发布面选择规则。
Obsidian wiki link 不强行转 Markdown link，除非仓库约定要求。
⌘
TEMPLATE
报告模板## Broken Links
| Source | Link | Problem | Suggested fix |
| --- | --- | --- | --- |
## Broken Anchors
| Source | Target | Missing anchor | Candidate |
| --- | --- | --- | --- |