LESSON 11 / 2026.11.10
第 11 课要你把已经钉死的 version id 放进灰度流量,并给高风险工具调用加上白名单与观察期。上一课的发布清单见:https://school.myshirtai.com/archives/4770.
发布清单回答合入前能否说清版本、兼容与回滚;本课回答上线时先切给谁、哪些工具能调、看多久再决定推全或回滚。
本课是文档与练习。作者未在本机切换灰度或生产流量,文中没有第一手跑通记录。
没有观察期的灰度,只是把事故面从「全量」改成「一部分人先中招」,仍然不可验收。
Voraussetzungen und überprüfbare Ziele
请先完成第 10 课《把 Skill 发布清单写进仓库:版本、变更日志、兼容与回滚》:https://school.myshirtai.com/archives/4770。手头至少要有:可加载的目标 Skill、已填写的 reference/release-checklist.md、能改权限规则或能提 PR 的权限。
更早基础可回补:第 1 课 https://school.myshirtai.com/archives/3378; Lektion 2 https://school.myshirtai.com/archives/3462; Lektion 3 https://school.myshirtai.com/archives/3521; Lektion 4 https://school.myshirtai.com/archives/3661; Lektion 5 https://school.myshirtai.com/?p=3948; Lektion 6 https://school.myshirtai.com/?p=4048; Lektion 7 https://school.myshirtai.com/?p=4191; Lektion 8 https://school.myshirtai.com/?p=4331;第 9 课 https://school.myshirtai.com/?p=4478.
Heute Abend stehen nur 90 Minuten zur VerfügungEiner已发布 Skill 补灰度与白名单,不要顺便重写全部工具。
- Ziel A:Absenden
reference/canary-mcp-allowlist.md(含钉死的 version id、灰度比例、观察指标、白名单字段、回滚触发)。 - Ziel B:挂两条失败样例——缺白名单、缺观察期——并能被第 6 课评测钩子点名。
- Ziel C:写明生产与灰度都禁止只写
Aktuellste。未实测流量切换时,标注「未本机跑灰度」即可。
灰度:钉死版本并设观察指标
官方 Skills API 把 version id 写成可寻址、可钉死的标识;请求里也可以写字面量 Aktuellste。文档的生产建议是:钉死具体版本,避免工作区里任何人新上传,都立刻改变全体 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_navigate.
规则按 deny、ask、allow 的顺序生效。允许规则里的通配,只能出现在已经写明的服务器名之后,不能用光秃秃的 mcp__* 一键放行全部 MCP。

组织侧还可以用 allowedMcpServers zusammen mit allowManagedMcpServersOnly 限制哪些服务器能加载。Agent SDK 则可用 allowedTools 预批指定工具,并用 skills 选项限制本会话能调用哪些 Skill。
高风险工具(写库、发消息、删数据、调付款或生产变更)默认写 ask 或 deny,并在白名单表里留下 owner 与观察截止日期。不要用 bypassPermissions 代替白名单:它会跳过绝大多数确认,比你需要的权限更宽。
练习:模板与失败样例
Unter dem Ziel-Skill neu erstellen 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:
至少准备两条Sollte scheitern样例,并写进第 6 课评测目录:
| Beispiel | Was fehlt? | Erwartete Testergebnisse |
|---|---|---|
| 缺白名单 | 已切新 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 课灰度门禁共用同一套路径约定。
Hinweis:本文未本机切换灰度流量,也未在生产环境验证白名单。练习验收标准是「清单文件 + 两条失败样例 + PR 勾选」齐备;不要把文档练习写成「已灰度上线」。
Vorschau auf die nächste Lektion
下一课预告:把灰度观察指标接到第 6 课评测与告警——失败率、越权调用、回滚耗时怎么写成可验收门槛。本课先把 version id、白名单和观察窗口写进仓库;没有可点名的指标,告警只会变成事后回忆。
Inhaltsverzeichnis dieser Reihe
- Lektion 1: Erstellen Sie in 30 Minuten Ihren ersten automatisch ausgelösten Claude Agent Skill — https://school.myshirtai.com/archives/3378
- Lektion 2: Hinzufügen einer Referenz zu „Skill“ / Der Prüfkreis „Zuerst das Planungsdokument erstellen, dann ausführen“ — https://school.myshirtai.com/archives/3462
- Lektion 3: Skriptbasierte Skills und Sicherheitsaudits — https://school.myshirtai.com/archives/3521
- Lektion 4: Iteratives Arbeiten mit realen Fehlerfällen – Beschreibung — https://school.myshirtai.com/archives/3661
- Lektion 5: Skill in ein echtes Repository (CI) bzw. in ein gemeinsames Teamverzeichnis integrieren — https://school.myshirtai.com/?p=3948
- Lektion 6: Regression für „Skill“ anhand eines Testdatensatzes — https://school.myshirtai.com/?p=4048
- Lektion 7: Multi-Skill-Choreografie: Aufbrechen und Zusammenfügen von Grenzen sowie Schlichtung von Konflikten — https://school.myshirtai.com/?p=4191
- Lektion 8: Implementierung des Task-/Subagent-Musters in einem Skill: Parallelitätsgrenzen und Kontextisolierung — https://school.myshirtai.com/?p=4331
- Lektion 9: Den „Computer-Use“-Koordinatenvertrag und die „Harness“-Grenzen in die Fertigkeit einarbeiten — https://school.myshirtai.com/?p=4478
- 第 10 课:把 Skill 发布清单写进仓库:版本、变更日志、兼容与回滚 — https://school.myshirtai.com/archives/4770
- 第 11 课:生产灰度与 MCP 白名单:把钉死的 version id 放进灰度流量(本文)
Unsere Einschätzung:灰度的可验收之处,不是比例数字本身,而是「钉死的新旧 version id + 白名单 + 观察窗口 + 回滚对象」四件套能被评测钩子点名。缺任何一件,就不要把流量从低比例往上加。
Weiterführende Links
- Claude-API-Dokumentation: Skill-Versionen
- 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 发布清单写进仓库
- Lektion 6: Regression für „Skill“ anhand eines Testdatensatzes


评论列表 (0条):
加载更多评论 Laden...