Claude Cookbooks 中的 /link-review 命令解析：Claude Code 斜杠命令如何守护文档与 Notebook 的链接质量

Claude Cookbooks（anthropic-cookbook）是一个以 Jupyter Notebook 与 Markdown 文档为主的仓库，链接失效、文档过时是这类仓库最常见的维护问题之一。本文以仓库内置的 link-review 斜杠命令 为核心，完整拆解它的命令定义结构、链接质量检查维度、报告格式规范，并结合触发它的 Claude Link Review 工作流 与 lychee 配置文件，讲清楚"AI 审查 + 确定性工具"双轨并行的链接质检体系是如何在本地开发和 CI 中落地的。读完本文，你可以掌握在 Claude Code 中编写自定义斜杠命令（slash command）的完整套路，并了解如何把一条本地命令无缝接入 GitHub Actions。

一、命令定义文件：一个斜杠命令的完整结构

link-review.md 是 Claude Code 的自定义斜杠命令。按照 Claude Code 的约定，存放在 .claude/commands/ 目录下的 Markdown 文件会注册为可用命令，文件名即命令名——因此该文件对应 /link-review。CONTRIBUTING.md 中明确列出了仓库可用的三条质检命令：

• /link-review - Validate links in markdown and notebooks（校验 Markdown 与 Notebook 中的链接）
• /model-check - Verify Claude model usage is current（校验 Claude 模型引用是否为当前版本）
• /notebook-review - Comprehensive notebook quality check（Notebook 质量综合检查）

该命令文件整体分为两部分：YAML frontmatter 与 Markdown 提示词正文。

1.1 Frontmatter：权限白名单

文件开头两行元数据：

---
allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)
description: Review links in changed files for quality and security issues
---

• allowed-tools 声明了该命令执行期间被允许使用的工具，且只开放了三个 gh 子命令：gh pr comment（发表评论）、gh pr diff（获取 PR 差异）、gh pr view（查看 PR 信息）。这是典型的最小权限设计——命令最终只需要把审查结果评论回 PR，因此不给它任何写文件、执行任意 Bash 的权限。
• 值得注意的是，这条白名单只是"下限"。在 CI 中运行时，工作流通过 claude_args 追加了更完整的工具列表（见第四节），两者叠加生效。
• description 字段用于说明命令用途："Review links in changed files for quality and security issues"。

仓库里另一个同类型命令 model-check.md 使用了完全相同的 allowed-tools 组合，说明这是一套统一的"只读审查 + 评论回传"权限模式。

1.2 提示词正文：范围约束先行

正文第一行就是一条强约束：

IMPORTANT: Only review the files explicitly listed in the prompt above. Do not search for or review additional files.

这直接回应了该命令的典型使用方式：CI 会先把"本次 PR 变更过的文件列表"塞进 prompt（例如 README.md、capabilities/summarization/README.md），命令必须只审查列出的文件，不能自行扩大扫描范围。这种约束对控制审查时长、避免误报无关文件至关重要，也是把"本地命令"改造成"CI 参数化命令"的关键设计。

二、链接质量检查：四个维度

命令正文的 "Link Quality Checks" 一节定义了四条通用检查规则，覆盖了链接审查从可用性到安全性的完整梯度：

检查维度	原文要求	落地含义
1. Broken Links（失效链接）	Identify any links that might be broken or malformed	找出无法访问或格式畸形的链接（如拼错的域名、缺失协议头）
2. Outdated Links（过时链接）	Check for links to deprecated resources or old documentation	指向已下线资源、旧版本文档的链接
3. Security（安全性）	Ensure no links to suspicious or potentially harmful sites	检查是否指向可疑或潜在有害站点
4. Best Practices（最佳实践）	Links should use HTTPS where possible; Internal links should use relative paths; External links should be to stable, reputable sources	外部链接尽量 HTTPS；内部链接应使用相对路径；外部链接指向稳定、可信的来源

其中"内部链接应使用相对路径"与仓库的既有约定相互印证：lychee.toml 的注释里写明，notebook 中指向仓库文件的链接约定使用绝对 GitHub URL（house convention），唯一允许保留相对链接的是 notebook 自身的图片（相对路径才能在 GitHub 上正常渲染），而检查相对链接时若精确路径不存在，会按 fallback_extensions = ["ipynb", "md", "html", "py"] 依次尝试补全扩展名。这些细节让"相对路径"这条规则在真实场景中有了明确的边界条件。

三、Anthropic 内容专项检查

通用规则之外，命令还为"Anthropic/Claude 相关内容"单列了一个专项检查小节，这正是该命令针对本仓库领域定制的部分：

• 指向 Claude 文档的链接应指向最新版本（Links to Claude documentation should point to the latest versions）；
• API 文档链接应保持时效（API documentation links should be current）；
• 模型文档应引用当前模型，而非已弃用模型（Model documentation should reference current models, not deprecated ones）；
• GitHub 链接应使用正确的仓库路径（GitHub links should use the correct repository paths）。

前两条与同目录的 model-check 命令 形成职责分工：/model-check 负责核对代码里的模型名是否仍在当前公开模型列表中（它会拉取 docs.claude.com 的模型概览页做比对，并建议改用 -latest 后缀的模型别名），而 /link-review 则负责文档链接层面的时效性——例如把旧版 API 参考页的链接更新为新路径。CONTRIBUTING.md 也呼应了这一点："Claude will automatically validate model usage in PR reviews"，并建议 Notebook 使用模型别名以提高可维护性。

四、CI 集成：claude-link-review.yml 工作流

/link-review 并非只能在本地手动执行。claude-link-review.yml 展示了它如何被参数化后接入 GitHub Actions，这也是理解该命令"为什么只开放三个 gh 子命令"的完整拼图。

4.1 触发条件

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - '**.md'
      - '**.mdx'
      - '**.ipynb'
      - 'README.md'
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'PR number to review'
        required: true
        type: number

即：PR 打开或更新且涉及 .md / .mdx / .ipynb 文件时自动触发；同时支持手动 workflow_dispatch 指定任意 PR 编号。此外工作流用 if 条件限制仅对非 fork（内部贡献者）的 PR 自动运行，外部 fork 只能通过手动触发，从而控制 API 消耗。

4.2 工作流步骤拆解

1. 确定 PR 编号：区分 workflow_dispatch（取 inputs.pr_number）与 pull_request（取 github.event.pull_request.number），写入 steps.pr-number.outputs.number，最终通过 PR_NUMBER 环境变量传给 Claude。
2. Checkout PR：fetch-depth: 0 拉全量历史，手动触发时通过 refs/pull/{number}/head 检出 PR head。
3. 计算变更文件：从 PR base 分支 git fetch 后用 git diff --name-only origin/<base>...HEAD | grep -E '\.(md|mdx|ipynb)$' 得到变更文件列表，写入 changed_files.txt；若列表为空则置 has_files=false 并跳过后续步骤。
4. 运行 Claude 审查：使用 anthropics/claude-code-action（sha 固定于 v1.0.132），核心配置如下：

prompt: |
  /link-review

  Changed files to review:
  $(cat changed_files.txt)
claude_args: |
  --allowedTools "Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(echo:*),Read,Glob,Grep,WebFetch"

可以看到 prompt 正是把第 2 步算出的文件列表拼接进 /link-review 命令——与命令正文"只审查 prompt 中列出的文件"的约束严格对应。claude_args 中的 --allowedTools 在 frontmatter 白名单基础上追加了 Read、Glob、Grep、WebFetch（读取变更文件内容、抓取目标 URL 验证可达性所需）与 Bash(echo:*)。

5. 身份认证：工作流使用 permissions: id-token: write，通过 Anthropic Workload Identity Federation（WIF）把 GitHub OIDC token 交换成短时效访问令牌，而非在仓库中存放静态 API key——配置中的 anthropic_federation_rule_id、anthropic_organization_id、anthropic_service_account_id 三项即该联邦规则的身份标识。

4.3 回传结果

命令正文最后一行规定了唯一的输出动作：

IMPORTANT: Post your review as a comment on the pull request using the command: gh pr comment $PR_NUMBER --body "your review content"

这与工作流声明的 pull-requests: write 权限、PR_NUMBER 环境变量三者在闭环上互相印证：Claude 审查完成后，直接以 gh pr comment 把结构化审查结果评论回 PR，整个链路无需人工中转。

五、报告格式：三级分类的审查结论

命令对输出格式做了显式模板化要求（Report Format 一节），审查结论必须按三档分类呈现：

• ✅ Valid and well-formed links：有效且格式规范的链接；
• ⚠️ Links that might need attention：可能需要关注的链接，例如用了 HTTP 而非 HTTPS；
• ❌ Broken or problematic links that must be fixed：必须修复的失效或有问题的链接。

若全部链接正常，则只给一段简短确认（"If all links look good, provide a brief confirmation"）。这种"通过时一句话、不通过时分级列出"的约定，保证了 PR 评论在绝大多数"无问题"场景下不会造成噪音，同时又保留了可操作的修复清单。

六、与 lychee 确定性检查的分工配合

Claude 审查是"智能层"，仓库同时保留了一套确定性链接检查作为兜底，两者互补：

• links.yml（Link Check 工作流）：PR 触发时仅检查变更文件——先用 jupyter nbconvert --to markdown 把变更的 .ipynb 转成临时 Markdown（temp_md/），再交给 lycheeeverse/lychee-action（sha 固定于 v2.8.0）执行检查，结果通过 sticky-pull-request-comment（header 为 link-check）贴到 PR；此外每周日 00:00 的 cron 任务会对 skills/**/*.md、全部转换后的 notebook 和 README.md 做全量检查。
• lychee.toml：核心参数包括 timeout = 30、max_redirects = 10、include_fragments = true、1 天缓存（max_cache_age = "1d"）、3 次重试（retry_wait_time = 2）；accept 列表在标准 2xx/3xx 之外额外接受 403（需登录站点）与 429（限流），并注释明确"该列表会替换 lychee 默认值，因此 2xx 必须显式列出"；exclude 则屏蔽了 api.anthropic.com、console.anthropic.com、localhost 等无需外呼检查的地址。

从两套机制的分工看：lychee 负责"链接是否可达"这一客观事实（含 404/超时/重定向），Claude /link-review 则覆盖 lychee 无法判断的语义层——指向的文档是否已换版本、模型引用是否已过时、链接指向是否可疑。require_https = false 的 lychee 配置也侧面说明：HTTPS 合规性检查交给 Claude 审查的"⚠️ 关注"档来处理，而不是硬性失败。

七、本地使用方式

按 CONTRIBUTING.md 的说明，开发者在本地用 Claude Code 打开该仓库时，同一批命令定义（.claude/commands/ 目录）会自动可用，可以直接在 push 之前运行与 CI 相同的校验逻辑：

# Run the same validations that CI will run
/notebook-review skills/my-notebook.ipynb
/model-check
/link-review README.md

也就是说，本地调用 /link-review 时把待审查文件（如 README.md）作为参数传入，Claude 即按同一份提示词完成四级检查与三级分类报告；在 CI 中则是由工作流注入变更文件列表与 PR_NUMBER 环境变量，最终自动评论回 PR。命令定义、本地交互、CI 集成三者共用同一份 Markdown，这正是 Claude Code 斜杠命令"一次编写、双端复用"的典型价值。

八、小结

link-review.md 虽然只有 30 余行，却浓缩了 Claude Code 自定义斜杠命令的完整工程模式：

1. frontmatter 最小权限：allowed-tools 只开放 gh pr comment/diff/view 三个子命令，配合 CI 中 --allowedTools 按需放宽；
2. 范围约束前置：首行强约束"只审查 prompt 列出的文件"，使其天然适配 CI 参数化调用；
3. 分层检查规则：通用四维检查（失效/过时/安全/最佳实践）+ Anthropic 内容专项（文档版本、模型时效、仓库路径），与 model-check 等姊妹命令职责切分清晰；
4. 模板化输出：✅/⚠️/❌ 三级报告 + 通过时一句话确认，控制 PR 评论噪音；
5. 确定性兜底：lychee 全量/增量链接检查（lychee.toml、links.yml）负责可达性事实，AI 审查负责语义质量，双轨并行。

对于维护文档密集型仓库（notebook、Markdown 占比高的开源项目）的团队，这套"斜杠命令 + 变更文件注入 + gh pr comment 回传 + lychee 兜底"的链路可以直接作为参考模板复用。