claude-cookbooks 的 CI 模型校验流水线：/model-check 斜杠命令与 Claude Model Check 工作流详解

在 claude-cookbooks 这类以 Jupyter Notebook 为核心的示例仓库中，代码会频繁引用 Claude 模型名，而模型是滚动迭代的——一旦 Notebook 里写死了已下线的模型名，示例就无法复现。本仓库通过一条「斜杠命令 + GitHub Actions 工作流」的组合自动化地解决该问题：PR 中所有涉及模型引用的改动，都会由 Claude Code 对照官方当前公开模型清单进行校验，并把结果以评论形式回写到 PR。读完本文，你可以理解这条校验流水线的完整触发与执行链路，并掌握在自己的仓库中搭建同类「模型名漂移」检查所需的命令定义、权限收敛与无密钥（WIF）鉴权配置。

/model-check：一条定义明确的模型引用校验命令

命令定义在 .claude/commands/model-check.md，是一个标准的 Claude Code 斜杠命令文件，由 YAML frontmatter 加 Markdown 指令两部分组成。

frontmatter 声明了命令的身份与工具边界（model-check.md 第 1–4 行）：

---
allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)
description: Validate Claude model usage against current public models
---

• description 是一句话功能说明：将 PR 中的 Claude 模型用法与当前公开模型清单进行校验。
• allowed-tools 只放行了三个 gh 子命令族：gh pr comment（回写结果）、gh pr diff（查看差异）、gh pr view（查看 PR 信息）。注意这里没有 gh pr checkout 和 gh pr review——该命令的定位是「只读校验 + 评论」，不能切换分支，也不能做出 approve/request-changes 这类结论性评审动作，属于典型的工具最小权限设计。

正文部分给出了命令的执行步骤，可拆为四段职责：

1. 评审范围强约束（第 6 行）：开头即声明 “Only review the files explicitly listed in the prompt above. Do not search for or review additional files.”——只检查上游 prompt 中显式列出的变更文件，禁止自行扩大搜索范围。这条约束直接服务于 CI 场景：变更文件清单由工作流动态生成后注入，命令不得越界审查全仓库。
2. 以官方模型总览页为事实基准（第 10–11 行）：要求先从官方文档的模型总览页（source of truth 的完整地址见源文件）抓取当前允许的模型清单，再进行比对。也就是说，命令不依赖模型名硬编码在 prompt 里，而是运行时拉取最新清单，天然免疫模型版本漂移。
3. 四条具体检查规则（第 13–17 行）：
   • 所有模型引用必须出自当前公开模型清单；
   • 标记已弃用的模型（文档中明确列举了“更早期的 Sonnet 3.5、Opus 3 系列”）；
   • 标记内部/非公开模型名（防止 Notebook 中误用不可对外分发的模型标识）；
   • 建议改用 -latest 结尾的别名（alias），以获得更好的可维护性——这类别名始终指向同族的最新稳定版本，避免每次模型升级都改代码。
4. 结果回写（第 19、21 行）：要求输出「清晰、可执行」的反馈，并强制通过命令 gh pr comment $PR_NUMBER --body "your findings" 将结论作为评论发布到对应 PR 上。$PR_NUMBER 这个环境变量由 CI 侧注入（见下文工作流的 env 配置），命令本身不关心 PR 号从哪来。

触发链路：Claude Model Check 工作流如何驱动这条命令

命令不会凭空运行，它由 .github/workflows/claude-model-check.yml 工作流编排触发。逐段看这条流水线：

触发条件与路径过滤

工作流监听 pull_request 的 opened / synchronize 事件，并用 paths 过滤器把触发范围限定在与模型引用最相关的文件类型上（claude-model-check.yml 第 3–15 行）：

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

同时支持 workflow_dispatch 手动触发，输入一个必填的 PR 号即可对历史 PR 补跑校验。

作业级还有一个准入条件（第 25 行）：if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository，即仅内部贡献者（非 fork）的 PR 自动触发，fork PR 需手动 dispatch。这一模式在仓库的 code-reviewer 规范中也被明确列为 CI 设计惯例——昂贵的 AI 评审工作流只跑在可信来源上（参见 .claude/agents/code-reviewer.md 第 94–106 行）。

权限与无静态密钥鉴权

工作流权限声明为 contents: read、pull-requests: write 和 id-token: write（第 17–20 行）。其中 id-token: write 是整条链路的关键：它启用 Anthropic Workload Identity Federation（WIF），由 anthropics/claude-code-action 把作业自身的 GitHub OIDC 令牌换取一个短时效的 Anthropic 访问令牌，全程不需要在 Secrets 中存放静态 API Key。工作流中通过三个字段完成 WIF 对接（第 76–78 行）：

anthropic_federation_rule_id: fdrl_01SqmTwzmEE547mtaYN1mqHL
anthropic_organization_id: 1ec12c5c-6542-4da8-bf2f-c15919aef01c
anthropic_service_account_id: svac_01BHcBBa1UWFvNrHMqJjuaUZ

这三项分别指认 Anthropic 侧的联邦规则、组织与 Service Account，是「GitHub CI 身份 → Anthropic 服务账号身份」的信任锚点。

动态生成变更文件清单

「只检查指定文件」这条命令约束，靠工作流里的两步实现：

1. 解析 PR 号（第 29–36 行）：自动事件直接取 github.event.pull_request.number；手动 dispatch 则取 inputs.pr_number，结果写入 $GITHUB_OUTPUT 供后续步骤引用。
2. Checkout PR 头（第 38–42 行）：fetch-depth: 0 拉取完整历史；手动触发时用 format('refs/pull/{0}/head', inputs.pr_number) 拼出 refs/pull/<N>/head 作为 checkout ref。
3. 计算变更文件（第 44–67 行）：先 git fetch origin <base_ref>，再 git diff --name-only origin/<base>...HEAD，并用 grep -E '\.(ipynb|py|md)$' 过滤出三类相关扩展名。有变更时把清单落盘为 changed_files.txt 并置 has_files=true；无变更则直接打印 “No relevant files changed” 并短路后续步骤（Claude 校验步骤带 if: steps.changed-files.outputs.has_files == 'true' 条件）。手动触发分支还会先 gh pr view ... --json baseRefName 解析出 PR 基线分支再取 diff，并显式传入 GH_TOKEN——这两点同样与 code-reviewer 规范中总结的 workflow 模式一一对应。

调用 Claude Code 执行 /model-check

核心步骤（第 69–88 行）把前两步的产物组装成命令调用：

- name: Claude Model Validation
  if: steps.changed-files.outputs.has_files == 'true'
  uses: anthropics/claude-code-action@bbfaf8e1ffe3e688f7ab65ceee78de241e24a238 # v1.0.132
  with:
    anthropic_federation_rule_id: ...
    anthropic_organization_id: ...
    anthropic_service_account_id: ...
    github_token: ${{ secrets.GITHUB_TOKEN }}
    prompt: |
      /model-check

      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"
  env:
    PR_NUMBER: ${{ steps.pr-number.outputs.number }}

几个值得注意的细节：

• prompt 即命令调用现场：/model-check 触发斜杠命令，随后紧跟 Changed files to review: 与 $(cat changed_files.txt) 展开的文件清单——这正好对应命令正文中「explicitly listed in the prompt above」的措辞，范围约束与清单注入在此闭环。
• CI 侧工具授权是 frontmatter 的超集：frontmatter 里只有三个 gh 命令，而 claude_args --allowedTools 额外追加了 Bash(echo:*)、Read、Glob、Grep 与 WebFetch。从源码结构看，WebFetch 正是命令第 10 步「抓取官方模型总览页」所需的能力——frontmatter 声明的是命令的最小工具面，CI 环境按需放宽为「最小够用」。
• PR_NUMBER 经 env 注入：命令最后一步的 gh pr comment $PR_NUMBER --body "..." 由此解析到具体 PR。

在命令族中的位置与对比

.claude/commands/ 目录下共有多条评审类命令，从工具权限的对比能清楚看出各命令的职责分层：

命令	工具授权要点	职责
model-check.md	gh pr comment/diff/view	只读校验模型引用，仅回写评论
notebook-review.md	同 model-check，另加 echo、Read/Glob/Grep/WebFetch	Notebook 与 Python 脚本质量评审
link-review.md	同 model-check	变更文件内链接的质量与安全审查
review-pr-ci.md / review-pr.md	增加 gh pr review、gh pr checkout、Task 等	完整代码评审并做出 APPROVE/REQUEST_CHANGES 结论

model-check 是最「窄」的一条：无 Task（不派生子 agent）、无 gh pr review（不阻塞合并）、无 checkout（不切换工作区）。而 claude-pr-review.yml 走的是完整的 /review-pr-ci 链路并授权了 gh pr review，与 model-check 形成「轻量专项检查 vs 全量评审」的分工。两条工作流共享同一套 WIF 鉴权字段与 PR 号解析模式，说明仓库内已把「事件解析 → 变更检测 → 斜杠命令执行 → 结果回写 PR」沉淀为可复制的模板。值得注意的是 link-review.md 第 22 行 也把「模型文档应引用当前模型而非已弃用模型」列入链接检查项——model-check 命令正是把这一条从「顺带检查」升级为「专职流水线」。

可复用的设计要点

从这份命令与工作流的实现中，可以提炼出四条对自建「AI 辅助模型名漂移检查」直接有用的经验：

1. 基准外置：模型清单不写进 prompt，而是运行时抓取官方总览页，命令本身永远不需要随模型发布而修改。
2. 范围由编排层注入：命令只承诺「审列出的文件」，具体清单由工作流用 git diff --name-only 动态计算并注入 prompt，既控制 token 消耗，也杜绝评审漂移。
3. 工具最小授权 + 环境级放宽：frontmatter 声明最小工具面（只读 gh 三件套），CI 通过 --allowedTools 精准补齐 WebFetch/Read/Grep 等必要能力；不需要 approve 权限的专项检查，就不给 approve 工具。
4. WIF 替代静态密钥：id-token: write + 联邦规则三元组让 CI 用 OIDC 身份换取短时效令牌，Secrets 中无长期 API Key，fork PR 又受「仅内部来源自动触发」的准入条件保护，成本控制与凭证安全同时成立。

复用到自己的仓库时，最小改动路径是：保留 claude-model-check.yml 的事件/路径过滤、PR 号解析与变更文件检测骨架，替换 WIF 三元组为自己的 Anthropic 组织配置，再按 model-check.md 的 frontmatter + 步骤化正文格式重写检查规则即可；若暂时用静态 API Key，也可将 WIF 三个字段换成 action 对应的密钥输入，链路其余部分不变。