link-validation

链接验证技能

使用 lychee 验证工作区中的 Markdown 链接。

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方法，请立即修正此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 检查 Markdown 文件中是否有失效链接
• 提交文档前验证链接路径
• 确认文档更改没有留下失效的内部链接

如何运行

工作路径是 tasks/link-check.sh 中的离线 lychee 检查。在 cc-skills 仓库中，它属于质量门禁的一部分：

moon run repo:link-check     # this check alone
moon run repo:check          # the whole gate, link-check included
bash tasks/link-check.sh     # the same script without moon

在其他工作区中，从仓库根目录运行相同的 lychee 命令：

lychee --offline --no-progress --root-dir "$(git rev-parse --show-toplevel)" './**/*.md'

如果仓库中有 lychee.toml，请添加 --config lychee.toml；lychee 也会自动加载 ./lychee.toml。

检查内容

tasks/link-check.sh：

1. 将目录切换到工作树根目录（git rev-parse --show-toplevel，因此在 worktree 中也能正确运行）
2. 运行 bunx lychee --config lychee.toml --offline --no-progress --root-dir <repo root> './**/*.md'
3. 排除 plugins/statusline-tools/tests/fixtures，其中的链接是故意设置为失效的
4. 打印 lychee 的摘要行，然后打印 ✓ every internal link resolves 或 ✗ broken internal links found (lychee exit N)，并以 lychee 的退出代码结束

它会检查相对链接、根目录相对链接（/docs/adr/x.md，通过 --root-dir 解析）和 #anchor 片段。此检查按设计离线运行：外部 URL 是否有效取决于网络和其他站点的运行状态，因此不会检查。除 lychee 自身的 .lycheecache 外，不会向磁盘写入任何内容；结果会显示在终端输出和退出代码中。

仅在某台机器上存在的路径（~/...、其他仓库）无法通过检查。请将其写成行内代码，而不是链接。

要求

• lychee：tasks/link-check.sh 通过 bunx 运行它，因此只需安装 Bun；在其他情况下请安装 lychee（brew install lychee）

配置

cc-skills 使用一个 lychee 配置文件，即仓库根目录下的 lychee.toml。该文件包含路径和 URL 排除项，以及 include_fragments = "anchor-only"（lychee 0.24 不接受旧的布尔值 true）。statusline-tools Stop 钩子在该文件存在时也会读取它。

相关检查

• 技能中的链接可移植性（安装后会失效的绝对仓库路径）：link-validator 技能
• 会话结束时的路径策略：statusline-tools Stop 钩子会运行 lint-relative-paths 和 lychee，并写入 .lychee-results.json 以供状态行使用

历史记录

此技能以前描述了一个 Stop 钩子 hooks/stop-link-check.py，它会写入 .link-check-results.md。link-tools 从未有过 hooks.json，因此该钩子从未运行；它已在 issue #33 中删除。

参考资料

• ADR：链接检查器插件提取
• lychee 文档

---

故障排除

问题	原因	解决方案
找不到 lychee	尚未安装	brew install lychee，或通过 bunx lychee 运行
配置加载失败	include_fragments = true	使用 include_fragments = "anchor-only"（lychee 0.24 及更高版本）
所有 /docs/... 链接均失败	未指定 --root-dir	使用绝对仓库根目录作为参数传入 --root-dir
指向 ~/... 的链接失败	该路径仅在一台机器上存在	将其写成行内代码，而不是链接
fixture 中的失效链接导致失败	未排除 fixture	将其添加到 --exclude-path 或配置的 exclude_path 中

执行后反思

此技能完成后，关闭前请检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表格。
2. 参数或输出是否发生变化？ — 如果底层工具的接口有所变化，请更新用法示例和参数表，使其与之匹配。
3. 是否需要变通处理？ — 如果你不得不临时调整（使用不同的标志、增加额外步骤），请更新此 SKILL.md，以便下次调用时无需采用相同的变通方法。

仅当问题真实且可复现时才更新，不要基于猜测更新。