LESSON 11 / 2026.11.10
第 11 课要你把已经钉死的 version id 放进灰度流量,并给高风险工具调用加上白名单与观察期。上一课的发布清单见:https://school.myshirtai.com/archives/4770.
发布清单回答合入前能否说清版本、兼容与回滚;本课回答上线时先切给谁、哪些工具能调、看多久再决定推全或回滚。
本课是文档与练习。作者未在本机切换灰度或生产流量,文中没有第一手跑通记录。
没有观察期的灰度,只是把事故面从「全量」改成「一部分人先中招」,仍然不可验收。
前置与可验证目标
请先完成第 10 课《把 Skill 发布清单写进仓库:版本、变更日志、兼容与回滚》:https://school.myshirtai.com/archives/4770。手头至少要有:可加载的目标 Skill、已填写的 reference/release-checklist.md、能改权限规则或能提 PR 的权限。
更早基础可回补:第 1 课 https://school.myshirtai.com/archives/3378;第2課 https://school.myshirtai.com/archives/3462;第3課 https://school.myshirtai.com/archives/3521;第4課 https://school.myshirtai.com/archives/3661;第5課 https://school.myshirtai.com/?p=3948;第6課 https://school.myshirtai.com/?p=4048;第7課 https://school.myshirtai.com/?p=4191;第 8 课 https://school.myshirtai.com/?p=4331;第 9 课 https://school.myshirtai.com/?p=4478.
今晚九十分钟只给一つ已发布 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_navigate.
规则按 deny、ask、allow 的顺序生效。允许规则里的通配,只能出现在已经写明的服务器名之后,不能用光秃秃的 mcp__* 一键放行全部 MCP。

组织侧还可以用 allowedMcpServers とともに 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 课灰度门禁共用同一套路径约定。
注意:本文未本机切换灰度流量,也未在生产环境验证白名单。练习验收标准是「清单文件 + 两条失败样例 + PR 勾选」齐备;不要把文档练习写成「已灰度上线」。
次回の予告
下一课预告:把灰度观察指标接到第 6 课评测与告警——失败率、越权调用、回滚耗时怎么写成可验收门槛。本课先把 version id、白名单和观察窗口写进仓库;没有可点名的指标,告警只会变成事后回忆。
本シリーズの目次
- 第1課:30分で、自動的にトリガーされる最初のClaude Agent Skillを作成する — https://school.myshirtai.com/archives/3378
- 第2課:Skillに参照を追加する/「まず計画文書を作成してから実行する」という検証ループ — https://school.myshirtai.com/archives/3462
- 第3課:スクリプト付きスキルとセキュリティ監査 — https://school.myshirtai.com/archives/3521
- 第4課:実際の失敗事例を用いた反復的な説明 — https://school.myshirtai.com/archives/3661
- 第5課:Skillを実際のリポジトリのCI/チーム共有ディレクトリに接続する — https://school.myshirtai.com/?p=3948
- 第6課:評価データセットを用いたSkillの回帰分析 — https://school.myshirtai.com/?p=4048
- 第7課:マルチスキル・シーケンス:結合・分離の境界とトリガー競合の仲裁 — https://school.myshirtai.com/?p=4191
- 第8課:SkillにTask/サブエージェントパターンを組み込む:並行処理の境界とコンテキストの分離 — 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 放进灰度流量(本文)
当社の判断:灰度的可验收之处,不是比例数字本身,而是「钉死的新旧 version id + 白名单 + 观察窗口 + 回滚对象」四件套能被评测钩子点名。缺任何一件,就不要把流量从低比例往上加。
参考リンク
- 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の回帰分析


评论列表 (0条):
加载更多评论 読み込み中...