Claude Cookbooks 中的 /link-review 命令解析：Claude Code 斜杠命令如何守护文档与 Notebook 的链接质量
【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks
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 工作流步骤拆解
- 确定 PR 编号：区分
workflow_dispatch（取inputs.pr_number）与pull_request（取github.event.pull_request.number），写入steps.pr-number.outputs.number，最终通过PR_NUMBER环境变量传给 Claude。 - Checkout PR：
fetch-depth: 0拉全量历史，手动触发时通过refs/pull/{number}/head检出 PR head。 - 计算变更文件：从 PR base 分支
git fetch后用git diff --name-only origin/<base>...HEAD | grep -E '\.(md|mdx|ipynb)$'得到变更文件列表，写入changed_files.txt；若列表为空则置has_files=false并跳过后续步骤。 - 运行 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:*)。
- 身份认证：工作流使用
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 自定义斜杠命令的完整工程模式：
- frontmatter 最小权限：
allowed-tools只开放gh pr comment/diff/view三个子命令，配合 CI 中--allowedTools按需放宽； - 范围约束前置：首行强约束"只审查 prompt 列出的文件"，使其天然适配 CI 参数化调用；
- 分层检查规则：通用四维检查（失效/过时/安全/最佳实践）+ Anthropic 内容专项（文档版本、模型时效、仓库路径），与 model-check 等姊妹命令职责切分清晰；
- 模板化输出：✅/⚠️/❌ 三级报告 + 通过时一句话确认，控制 PR 评论噪音；
- 确定性兜底：lychee 全量/增量链接检查（lychee.toml、links.yml）负责可达性事实，AI 审查负责语义质量，双轨并行。
对于维护文档密集型仓库（notebook、Markdown 占比高的开源项目）的团队，这套"斜杠命令 + 变更文件注入 + gh pr comment 回传 + lychee 兜底"的链路可以直接作为参考模板复用。
【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
