LESSON 11 / 2026.11.10
第 11 课要你把已经钉死的 version id 放进灰度流量,并给高风险工具调用加上白名单与观察期。上一课的发布清单见:https://school.myshirtai.com/archives/4770The
发布清单回答合入前能否说清版本、兼容与回滚;本课回答上线时先切给谁、哪些工具能调、看多久再决定推全或回滚。
本课是文档与练习。作者未在本机切换灰度或生产流量,文中没有第一手跑通记录。
没有观察期的灰度,只是把事故面从「全量」改成「一部分人先中招」,仍然不可验收。
前置与可验证目标
请先完成第 10 课《把 Skill 发布清单写进仓库:版本、变更日志、兼容与回滚》:https://school.myshirtai.com/archives/4770。手头至少要有:可加载的目标 Skill、已填写的 reference/release-checklist.md、能改权限规则或能提 PR 的权限。
更早基础可回补:第 1 课 https://school.myshirtai.com/archives/3378; Lesson 2 https://school.myshirtai.com/archives/3462; Lesson 3 https://school.myshirtai.com/archives/3521; Lesson 4 https://school.myshirtai.com/archives/3661; Lesson 5 https://school.myshirtai.com/?p=3948; Lesson 6 https://school.myshirtai.com/?p=4048; Lesson 7 https://school.myshirtai.com/?p=4191;第 8 课 https://school.myshirtai.com/?p=4331;第 9 课 https://school.myshirtai.com/?p=4478The
今晚九十分钟只给One已发布 Skill 补灰度与白名单,不要顺便重写全部工具。
- 目标 A:提交
reference/canary-mcp-allowlist.md(含钉死的 version id、灰度比例、观察指标、白名单字段、回滚触发)。 - 目标 B:挂两条失败样例——缺白名单、缺观察期——并能被第 6 课评测钩子点名。
- 目标 C:写明生产与灰度都禁止只写
latest。未实测流量切换时,标注「未本机跑灰度」即可。
灰度:钉死版本并设观察指标
官方 Skills API 把 version id 写成可寻址、可钉死的标识;请求里也可以写字面量 latest。文档的生产建议是:钉死具体版本,避免工作区里任何人新上传,都立刻改变全体 Agent 的行为。
Claude Code 插件依赖也有同类纪律:不写版本约束时,依赖会跟随市场里的最新发布;写上 ^2.0 或 ~2.1.0 这类约束,才能按你测过的范围更新。

灰度本身不是 Skills API 里单独的「金丝雀接口」,而是团队路由约定:绝大多数会话或请求继续钉旧 version id,一小部分钉新 version id,观察后再决定晋升或回滚。旧版本仍可用原 id 寻址,这是回滚能写进清单的前提。
观察指标至少写三项,并指定负责人和窗口天数:任务失败率、未授权或未预期的工具调用、回滚耗时上限。没有这三项,灰度比例只是一个口号。
白名单:高风险工具怎么写
Claude Code 文档把 MCP 工具写成 mcp__<server>__<tool>。要匹配某服务器的全部工具,写 mcp__<server>__*;要匹配单个工具,写全名,例如 mcp__puppeteer__puppeteer_navigateThe
规则按 deny、ask、allow 的顺序生效。允许规则里的通配,只能出现在已经写明的服务器名之后,不能用光秃秃的 mcp__* 一键放行全部 MCP。

组织侧还可以用 allowedMcpServers together with allowManagedMcpServersOnly 限制哪些服务器能加载。Agent SDK 则可用 allowedTools 预批指定工具,并用 skills 选项限制本会话能调用哪些 Skill。
高风险工具(写库、发消息、删数据、调付款或生产变更)默认写 ask 或 deny,并在白名单表里留下 owner 与观察截止日期。不要用 bypassPermissions 代替白名单:它会跳过绝大多数确认,比你需要的权限更宽。
练习:模板与失败样例
在目标 Skill 下新建 reference/canary-mcp-allowlist.md。下面模板可直接粘贴后改尖括号字段;代码块仅作文档练习,未本机跑灰度。
# Canary & MCP allowlist — <skill-name>
## Pinned versions
- skill_id:
- production version id (do not use latest):
- canary version id:
- git tag / SKILL.md version (align with lesson 10):
- pin method: API version field | agent config | plugin constraint
## Canary traffic
- population: session | request | workspace | team-subset
- canary percent:
- promote rule: after observation window AND metrics green
- note: team routing practice; not a built-in canary endpoint
## Observation
- window_days:
- metrics:
- task_fail_rate:
- unexpected_or_unauthorized_tool_calls:
- rollback_time_budget:
- check_owner:
- check_cadence: daily | per N sessions
## High-risk tool allowlist
| tool_or_server | rule (allow/ask/deny) | risk | owner | observe_until |
| mcp__<server>__<tool> | | high/med | | YYYY-MM-DD |
## Rollback triggers
- fail signals:
- rollback to:
- owner / timebox:
- stop if: no rollback target OR empty observation window
## Lesson 6 eval hooks
- missing-allowlist sample:
- missing-observation-window sample:
至少准备两条应失败样例,并写进第 6 课评测目录:
| 样例 | 缺什么 | 期望评测结果 |
|---|---|---|
| 缺白名单 | 已切新 version id,高风险 MCP 工具未写入 allow/ask/deny | 门禁红灯,禁止扩大流量 |
| 缺观察期 | 无 window_days、无指标负责人,当天从低比例提到全量 | 门禁红灯,禁止晋升 |
| 追 latest | 生产或灰度只写 latest,未钉 version id | 门禁红灯(接第 10 课) |

把样例路径写进模板的「Lesson 6 eval hooks」两行,例如 evals/canary-missing-allowlist.md。这样第 6 课钩子、第 10 课发布门禁和第 11 课灰度门禁共用同一套路径约定。
Note:本文未本机切换灰度流量,也未在生产环境验证白名单。练习验收标准是「清单文件 + 两条失败样例 + PR 勾选」齐备;不要把文档练习写成「已灰度上线」。
Preview of the Next Lesson
下一课预告:把灰度观察指标接到第 6 课评测与告警——失败率、越权调用、回滚耗时怎么写成可验收门槛。本课先把 version id、白名单和观察窗口写进仓库;没有可点名的指标,告警只会变成事后回忆。
Table of Contents for This Series
- Lesson 1: Write Your First Claude Agent Skill That Triggers Automatically in 30 Minutes — https://school.myshirtai.com/archives/3378
- Lesson 2: Adding a Reference to Skill / Validation Loop for “Write the Plan First, Then Execute” — https://school.myshirtai.com/archives/3462
- Lesson 3: Scripted Skills and Security Audits — https://school.myshirtai.com/archives/3521
- Lesson 4: Iterating Using Real-World Failure Cases description — https://school.myshirtai.com/archives/3661
- Lesson 5: Integrating Skill with a Real Repository's CI / Team-Shared Directory — https://school.myshirtai.com/?p=3948
- Lesson 6: Performing Regression on a Skill Using a Validation Set — https://school.myshirtai.com/?p=4048
- Lesson 7: Multi-Skill Choreography: Decomposing and Recombining Boundaries and Arbitrating Trigger Conflicts — https://school.myshirtai.com/?p=4191
- Lesson 8: Implementing the Task/Subagent Pattern in a Skill: Parallelism Boundaries and Context Isolation — https://school.myshirtai.com/?p=4331
- 第 9 课:把 computer-use 坐标契约与 Harness 边界写进 Skill — https://school.myshirtai.com/?p=4478
- 第 10 课:把 Skill 发布清单写进仓库:版本、变更日志、兼容与回滚 — https://school.myshirtai.com/archives/4770
- 第 11 课:生产灰度与 MCP 白名单:把钉死的 version id 放进灰度流量(本文)
Our assessment:灰度的可验收之处,不是比例数字本身,而是「钉死的新旧 version id + 白名单 + 观察窗口 + 回滚对象」四件套能被评测钩子点名。缺任何一件,就不要把流量从低比例往上加。
Reference Links
- Claude API Docs:Skill Versions
- Claude Docs:Using Agent Skills with the API
- Claude Code Docs:Configure permissions
- Claude Code Docs:Control MCP server access
- Claude Code Docs:Connect to external tools with MCP
- Claude Code Docs:Extend agents with skills
- Claude Code Docs:Plugin dependencies
- 第 10 课:把 Skill 发布清单写进仓库
- 第 6 课:用评测集给 Skill 做回归


Comment List (0):
Load More Comments Loading...