alterlab-link-health

链接健康 — 全仓库 Markdown 链接审计方法

一套可重复使用的方法，用于修复文档繁多的仓库中的失效链接检查。该方法总结自一次真实审计：在 8 次提交中，将 AlterLab-IEU/AlterLab-Academic-Skills 的链接检查结果从 1966 个链接中有 1208 个错误降至 1912 个链接中有 0 个错误，并自动检测到 Tier 3 回归问题，验证了防护规则的有效性。

快速开始

完整审计（全新仓库，链接检查失败）：

Audit and repair the link health of <owner/repo>. Run the full four-tier pipeline.

→ 根据 playbooks/full-audit.md 执行 10 个 Agent 的审计，然后进行分级 APPLY 阶段。

针对性残余问题处理（首次调度减少了错误，但仍有残留）：

The link checker is down from 1208 to 67 errors. Close the residuals.

→ 根据 playbooks/followup-pass.md 执行 3 个 Agent 的后续处理。

合并后清理（PR 已通过检查，需要处理完由人工决定的事项）：

Finalize the post-merge cleanup: resolve pending human-decision items, file follow-up issues, document link debt.

→ 根据 playbooks/post-merge.md 执行 4 个 Agent 的合并后处理。

---

何时使用此技能

• 每周运行的 Check Links（或类似的 lychee / markdown-link-check）工作流一直失败。
• 用户提到错误数量很多（数百个以上），并怀疑其中大多数是由配置造成的误报。
• 用户想要修复多个技能 / 文档中的仓库内失效文件引用。
• 用户想要一套可重复使用的流程，以便今后维护链接债务。

触发关键词 — 英文：link audit, dead links, link health, lychee, broken links, link checker, markdown link audit, link-health audit, 404 audit, check-links failing, CI link-check。繁体中文：連結健檢, 死鏈, 失效連結, 斷鏈檢查, 連結審計.

不适用的情况

情况	改用
验证引用的作品是否存在（DOI / 作者解析、虚构或幻觉生成的参考文献、撤稿）	alterlab-citation-verifier — link-health 只修复超链接；不会验证引用的作品是否存在
修复单个文件中的单个失效链接	直接编辑 — 无需使用流水线
审计链接之外的仓库结构（架构、frontmatter、元数据）	单独进行架构漂移审计（不在此处的范围内）

---

流水线概述（4 个 Tier）

每个 Tier 都是一个可单独审查的提交。按顺序执行 — 每个 Tier 都会让错误信号更清晰，从而为下一个 Tier 做好准备。

Tier	范围	典型变化
1 — 配置	引入 .lychee.toml，设置明确的接受范围（它会取代 lychee 的默认值，因此应列出 200..=299）；添加 .lycheeignore 以排除永久性噪声主机；并强化 CI 工作流。	单项收益最大 — 通常可减少 70% 至 90% 的错误。修复“--accept 403 会取代默认范围”的易错点。
2 — 仓库内引用	修复 [ERROR] file:// 条目：单复数目录拼写错误、缺少路径前缀、YAML frontmatter 错误。将教学用占位路径改为行内代码。	消除大部分实际失效链接 — 通常能将 200 至 400 个条目全部清零。
3 — URL 替换	将已迁移的外部 URL 替换为经验证仍可访问的链接；将 DEAD_INFRA URL 替换为替代资源。未经验证，绝不替换。	将残余问题减少到几十个左右。
4 — 排除项	处理所有剩余且无法修复的问题：对机器人不友好的主机、教学用占位符、已过期的上游基础设施、长期不稳定的学术网站。	将错误数降至 0，或稳定在个位数。

有关每个 Tier 的决策规则，请参阅 references/tier1-config.md 至 references/tier4-exclusions.md。

---

Tier 3 防护规则

每次 URL 替换后，重新运行链接检查器，并与基线成功集合进行差异比较。基线中返回 200 OK、替换后却返回非 200 的任何 URL 都属于回归；提交前必须还原。

自检：

diff <(grep "^\[200\]" baseline.log | sort -u) \
     <(grep "^\[200\]" post.log | sort -u)

输出应只显示新增项，不应有删除项。出现删除项意味着某次替换导致之前正常工作的 URL 回归。

制定此规则是因为在源代码审计期间，宽泛的 sed 前缀替换会悄悄拼接到更具体的路径上（例如，将 /v3/ → /v3/docs 会把原本正确的 /v3/docs 变成 /v3/docsdocs）。防护规则在第二次 CI 调度时发现了这个问题，而不是在提交时。假设你的 Tier 3 检查会导致回归。务必验证。

完整详情：references/tier3-substitution.md。

---

验证优先规则

任何 URL 替换前都要先探测并验证。 未经验证的替换会让虚假 URL 混入公开技能。每次进行 [old] → [new] 替换前：

1. 对于 GitHub 仓库：运行 gh api repos/owner/name — 状态必须为 200（仓库存在且未归档）。
2. 对于 HTTP URL：运行 curl -sSI -L --max-time 15 '<new>' — 最终状态必须为 200（包括重定向后的状态）。
3. 对于 PyPI / npm / crates 包：直接检查注册表 API 或落地页。

如果验证失败，请通过 .lycheeignore 排除失效目标，并附上注释说明原因，而不是猜测替代项。排除一个失效链接是诚实的；替换成错误链接则是埋下定时炸弹。

完整详情：references/tier3-substitution.md §“验证规则”。

---

操作手册

三个可直接调度的提示词包，按正确顺序调用此技能的各个层级。

操作手册	适用场景	Agent
playbooks/full-audit.md	全新审计、CI 失败且没有既往处理。	10 个并行子 Agent + 综合整理
playbooks/followup-pass.md	错误已大幅减少，但仍有残留。	3 个定向子 Agent
playbooks/post-merge.md	PR 已通过，接下来处理待人工决策的事项。	4 个并行子 Agent

三者采用相同流程：预检 → 并行调度 → 综合整理 → 提交/PR/合并 → 验证。

---

参考资料

文件	内容
references/tier1-config.md	.lychee.toml 架构、工作流 YAML、accept-code 注意事项
references/tier2-intra-repo.md	仓库内路径审计、目录单复数模式、frontmatter 修复
references/tier3-substitution.md	URL 替换规则、防护规则、sed 安全模式
references/tier4-exclusions.md	何时排除而非替换、.lycheeignore 分类标准
references/known-debt-template.md	供维护者使用的 5 类 KNOWN_LINK_DEBT.md 布局

---

示例

• examples/pr-1-retrospective.md — 生成此技能的源代码审计。错误数从 1208 降至 0，共提交 8 次，在第 5 次提交中自动检测到 Tier 3 回归（9cbd801），最终以 93a72fe 合并。

---

范围纪律

此技能用于修复链接健康状况。它不会：

• 统一仓库中 SKILL.md 的架构。文件架构差异应作为单独问题处理。
• 重构技能内容、示例或说明文字。只修改链接 URL 和 CI 配置。
• 修改 .lychee.toml 的 accept 列表来掩盖真实故障。对于不稳定的上游 5xx / 超时，应按主机逐项排除并说明理由，而不是一概接受。

严格遵守范围可让 PR 易于审查，并确保链接检查信号真实可信。

AlterLab Academic Skills 套件的一部分。