MCP 与 Agent Skill 实战

📄 第 1 章 · MCP 是什么：核心概念与设计动机 01-what-is-mcp.md✓ 标记已学

本章目标：理解 MCP 解决什么问题、由哪些角色组成、能提供哪三类能力，并能用自己的话向别人解释"MCP 是 AI 应用的 USB-C 接口"这句话的含义。

1.1 从一个真实的痛点说起

假设你在开发一个 AI 编程助手，希望它能做到三件事：

1. 读取用户本地的代码文件；
2. 查询公司的工单系统；
3. 往监控平台发送告警。

没有标准协议时，你需要为每一个 AI 应用 × 每一个数据源写一份定制集成代码：

                 ┌──────────────┐
                 │  AI 应用 A    │──── 自研胶水代码 ────▶ 文件系统
                 │ (Claude Desktop) │─── 自研胶水代码 ───▶ 工单系统
                 └──────────────┘──── 自研胶水代码 ─────▶ 监控平台

                 ┌──────────────┐
                 │  AI 应用 B    │──── 又一份胶水代码 ──▶ 文件系统
                 │  (Cursor)    │──── 又一份胶水代码 ──▶ 工单系统
                 └──────────────┘        ……（同样的工作再做一遍）

这就是 M×N 集成难题：M 个 AI 应用要接 N 个数据源/工具，就要写 M×N 份集成代码。每换一个模型厂商、一个客户端、一个内部系统，工作都要重做。

MCP（Model Context Protocol，模型上下文协议） 的思路是把 M×N 降为 M+N：

   M 个 AI 应用 ──┐
                  │        ┌──────────────────────────┐
                  ├────────│  MCP 协议（开放标准）        │
                  │        └──────────────────────────┘
   N 个数据源 ────┘              每个数据源实现一次 MCP 服务器，
                                每个 AI 应用实现一次 MCP 客户端

• 数据源方：把能力封装成 MCP 服务器，写一次，所有支持 MCP 的 AI 应用都能用；
• 应用方：内置 MCP 客户端（或接入 MCP 网关），接一次，就能使用生态里所有的 MCP 服务器。

类比：MCP 之于 AI 应用，就像 USB-C 之于电脑外设——键盘、硬盘、显示器、网卡都做成 USB-C 接口，电脑只需要一种接口。Anthropic 在 2024 年 11 月开源发布了这一协议，如今已成为事实上的行业标准，OpenAI、Google、Microsoft 等主流厂商的 Agent 产品均已支持。

1.2 一句话定义

MCP 是一个基于 JSON-RPC 2.0 的开放协议，标准化了 AI 应用（客户端）与外部能力提供方（服务器）之间的通信方式，让"模型能调用什么工具、能读到什么数据、能用什么提示模板"变得可插拔、可复用。

三个关键词：

1. 开放协议：规范公开（modelcontextprotocol.io），官方提供 TypeScript / Python / Java / C# / Go / Kotlin 等语言的 SDK，任何人都可以实现。
2. 客户端-服务器：MCP 遵循 C/S 架构。注意方向——服务器是能力的提供方，客户端内嵌在 AI 应用中。
3. 上下文（Context）：协议的名字点明了目的。模型的能力上限很大程度上取决于它"看得见"什么上下文。MCP 就是一条把外部上下文与操作能力安全、标准化地送进模型工作区的通道。

1.3 核心角色

一次 MCP 调用涉及四个角色：

┌──────────────────────────────────────────────────────────┐
│ Host（宿主应用）                                            │
│  例如：Claude Desktop、ZCode、Cursor、你自研的 Agent 应用      │
│  ┌────────────────┐                                       │
│  │ Client（客户端） │─── MCP 协议 ───▶ ┌────────────────┐  │
│  │ 1:1 连接一个服务器 │                 │ Server（服务器）  │  │
│  └────────────────┘                 │ 封装：数据库/API/  │  │
│  ┌────────────────┐                 │ 文件/SaaS 等能力   │  │
│  │ Client × N     │─── MCP 协议 ───▶ └────────────────┘  │
│  └────────────────┘        ▲                             │
│                            │ 内部再调用真实的数据源           │
│  ┌────────────────┐        │                             │
│  │ LLM（大模型）    │── 决定"何时调用哪个工具" ──┘             │
│  └────────────────┘                                       │
└──────────────────────────────────────────────────────────┘

理解最后一行非常关键：MCP 协议是 Host 与 Server 之间的通信协议，模型自始至终只面对自然语言。这既是 MCP 设计的优雅之处（模型无关），也是后续安全问题的根源（模型可能被工具描述中的恶意文本操纵，见第 12 章）。

1.4 服务器提供的三类能力（三大原语）

一个 MCP 服务器可以提供三类核心能力，称为三大原语（primitives）。理解它们的控制权归属差异，是用好 MCP 的关键：

1.4.1 Tools（工具）——模型执行的动作

工具是由模型决定调用的函数。模型看到工具的名称、描述和参数 schema，在推理过程中判断"现在应该调用它"，由宿主执行实际的调用。

• 形态：类似函数调用（function calling），但定义在服务器侧、协议标准化、跨应用复用。
• 特点：可以有副作用（写数据库、发消息、删文件），因此是安全管控的重点。
• 一个工具的描述质量（description 写得清不清楚）直接决定模型会不会在正确的时机正确地使用它——这是后续章节反复强调的主题。

1.4.2 Resources（资源）——应用提供的数据

资源是可被读取的原始数据，用 URI 标识（如 file:///logs/app.log、postgres://db/users/schema）。

• 形态：类似 GET 请求或文件读取，只读、无副作用。
• 控制权在应用：例如 Claude Desktop 会在界面上让用户挑选要附加哪些资源；IDE 客户端可能自动把当前打开的文件作为资源注入。
• 支持静态资源与资源模板（URI Template，如 db://{database}/{table}/schema，按需生成）。

1.4.3 Prompts（提示模板）——用户触发的模板

提示是预定义的提示词模板，可带参数。

• 控制权在用户：用户在客户端界面显式选择（常以斜杠命令形式出现，如 /code-review），客户端向服务器请求渲染后的消息列表，再交给模型。
• 价值：把领域最佳实践固化下来。比如数据库服务器可以提供 explain-query 模板，把"如何分析执行计划"的专业提示词沉淀在服务器里，所有接入该服务器的应用自动获得这套话术。

1.4.4 一张图记住控制权

谁决定用不用？
   用户 ──────▶ Prompts   （我主动选一个模板）
   应用 ──────▶ Resources （宿主把数据放进上下文）
   模型 ──────▶ Tools     （模型自己决定调工具）

除了三大原语，MCP 还定义了一些客户端能力（sampling、roots、elicitation），允许服务器反过来请求宿主的帮助，如"请宿主让模型帮我补全一次推理"。入门阶段只需知道有这回事，第 2 章会展开。

1.5 一次完整的交互：从头到尾发生了什么

场景：用户对 Claude Desktop 说 "帮我把桌面上的发票整理成一个清单"，宿主接入了本地文件系统 MCP 服务器。

 ① 用户输入需求
      │
      ▼
 ② Host 收集上下文：当前会话可用的 MCP 服务器清单，
    把其中所有工具的「名称+描述+参数schema」注入模型提示词
      │
      ▼
 ③ LLM 推理："我需要先列出桌面文件" ——
    输出工具调用请求： list_directory(path="~/Desktop")
      │
      ▼
 ④ Host 中的 Client 通过 MCP 协议把请求发给文件服务器
    （tools/call 报文，JSON-RPC 格式）
      │
      ▼
 ⑤ Server 执行（真实读目录），返回结果
    （content: [{type:"text", text:"发票1.pdf, 发票2.pdf, …"}]）
      │
      ▼
 ⑥ Host 把结果作为工具消息回填给 LLM
      │
      ▼
 ⑦ LLM 继续推理，可能再次调用工具（读取每个 PDF）……循环 ③-⑥
      │
      ▼
 ⑧ LLM 汇总生成最终回答："已整理 3 张发票，总额 …，清单如下…"

注意三个要点：

1. 循环（agent loop）：复杂任务 = 多轮"模型推理 → 工具调用 → 结果回填"，MCP 为每一轮提供标准化的传输。
2. 模型只见到自然语言与结构化结果，完全不知道底下是本地文件还是某公司的 Oracle 数据库。
3. 能力发现是动态的：连接建立时客户端通过 tools/list 获得工具清单，服务器甚至可以在运行中通知"我新增了工具"（notifications/tools/list_changed）。

1.6 MCP 不是什么（常见误解澄清）

1.7 适用场景速览

MCP 特别适合：

• 连接企业内部系统：数据库、工单、监控、CRM、数据仓库——每个系统封装一个服务器，全公司所有 AI 应用复用；
• 连接 SaaS 生态：GitHub、Slack、Jira、Figma 等已有大量社区服务器；
• 本地开发工具链：文件系统、Git、终端、浏览器自动化；
• 需要跨应用复用能力的场景：写一次，处处可用。

不太适合：

• 只想给单一应用加个一次性功能（直接在应用里写函数调用更简单）；
• 纯粹的静态知识注入（用系统提示词或 Skill 更轻量，见第 3、6 章）。

1.8 小结

• MCP = 模型上下文协议，把 M×N 集成降为 M+N 的开放标准。
• 四角色：Host、Client、Server、LLM；协议在 Host 与 Server 之间，模型只见自然语言。
• 三大原语：Tools（模型控制、可执行）、Resources（应用控制、可读取）、Prompts（用户控制、模板）。
• 交互本质：动态能力发现 + 模型驱动的"推理-调用-回填"循环。

动手练习

1. 概念自测：不看上文，写出三大原语的名称、控制者、有无副作用，并举一个例子。（对照 1.4 节检查）
2. 观察现实：如果你装有 Claude Desktop 或 ZCode，进入其 MCP 设置界面，观察已配置的服务器列表与它们暴露的工具数量。思考：哪些能力如果做成资源而不是工具会更合适？
3. 纸上谈兵：选择你所在公司的一个内部系统（如 OA、Jira、监控平台），用 1.4 节的三原语框架，在纸上列出"如果为它写一个 MCP 服务器，应该暴露哪些工具、哪些资源、哪些提示模板"。（这个练习的产出会在此后章节反复用到）
4. 思考题：为什么 MCP 要把"工具描述"设计成给模型看的自然语言，而不是给程序员看的 API 文档？这带来了什么好处与风险？（提示：好处——模型能理解语义并自主决策；风险——描述本身可能包含注入攻击，第 12 章详述）

下一章：第 2 章 · MCP 基本原理：协议、架构与生命周期 —— 我们打开协议的引擎盖，看 JSON-RPC 报文和握手流程。

📄 第 2 章 · MCP 基本原理：协议、架构与生命周期 02-mcp-internals.md✓ 标记已学

本章目标：理解 MCP 的分层架构（JSON-RPC 2.0 消息层 + 传输层）、完整连接生命周期、能力协商机制，并亲手用裸 JSON-RPC 报文"扮演"一次 MCP 客户端。

2.1 分层视角：MCP 的两层结构

┌─────────────────────────────────────────────┐
│ 应用层：JSON-RPC 2.0                          │
│  定义了方法名、参数、结果、通知的语义              │
│  initialize / tools/list / tools/call / ...   │
├─────────────────────────────────────────────┤
│ 传输层（Transport）                            │
│  stdio：本地子进程，标准输入输出                 │
│  Streamable HTTP：远程 HTTP 服务（可流式）       │
└─────────────────────────────────────────────┘

协议与应用场景解耦：无论服务器是本机的 Python 脚本还是公司内网的一个微服务，上层的消息语义完全一致。写好的工具代码通常只需改一行传输配置，就能从本地迁移到远程部署（第 13 章）。

2.2 消息格式：JSON-RPC 2.0

MCP 的每条消息都是一行 JSON（stdio 模式下以换行分隔）。JSON-RPC 2.0 有三种消息形态：

2.2.1 请求（Request）——期待响应

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "北京" }
  }
}

字段说明：id 是调用方生成的唯一标识，响应会带回它以配对；method 是方法名；params 是参数。

2.2.2 响应（Response）——成功或失败二选一

成功：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "北京：晴，26°C，西北风 3 级" }],
    "isError": false
  }
}

失败（协议级错误，如方法不存在）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32601, "message": "Method not found: tools/xxx" }
}

区分两种"失败"：协议级错误（error 字段，标准 JSON-RPC 错误码）表示通信本身出了问题；而工具执行失败（如"城市不存在"）用 result.isError: true 表示——因为对模型来说，"工具报错"也是有用的上下文信息，不是通信故障。这个区别在第 8 章最佳实践中会再次出现。

2.2.3 通知（Notification）——单向，无 id

{ "jsonrpc": "2.0", "method": "notifications/initialized" }

{ "jsonrpc": "2.0", "method": "notifications/tools/list_changed" }

通知没有 id，不需要响应。服务器用它来主动"广播"状态变化（如工具清单变了、资源更新了）。

2.3 连接生命周期：从握手到关闭

MCP 客户端与服务器建立连接后的完整生命周期：

 客户端                                服务器
   │  ① initialize 请求                  │
   │───────────────────────────────────▶│  声明协议版本、客户端能力、名字
   │  ② initialize 响应                  │
   │◀───────────────────────────────────│  返回协议版本、服务器能力、名字
   │  ③ notifications/initialized 通知   │
   │───────────────────────────────────▶│  确认握手完成
   │                                    │
   │  ④ 正常工作阶段                       │
   │    tools/list → tools/call          │
   │    resources/read、prompts/get ...  │
   │◀───────────── 通知（可选）────────────▶│
   │                                    │
   │  ⑤ 关闭（stdio: 关闭 stdin；HTTP: 断开/DELETE 会话）│

2.3.1 握手报文（值得亲眼看一遍）

① 客户端发出 initialize：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": { "name": "claude-desktop", "version": "1.2.0" }
  }
}

② 服务器响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {},
      "prompts": {}
    },
    "serverInfo": { "name": "fs-server", "version": "1.0.0" }
  }
}

2.3.2 能力协商（Capability Negotiation）的含义

握手的核心是双方互相声明"我会什么"：

• 客户端声明的能力（如 sampling）告诉服务器：你可以反过来请求我做这些事；
• 服务器声明的能力（如 tools.listChanged）告诉客户端：我提供工具，且工具清单变化时会发通知；
• 约定规则：握手之后，任何一方都不得使用未声明的能力。这是协议保持向后兼容的基石——新客户端遇到旧服务器，自动降级。

版本协商规则：客户端带来它支持的最高版本，服务器若支持则原样返回；不支持则返回它支持的最高版本，客户端据此决定继续（兼容时）或断开。

2.4 三大原语的协议方法速查

tools/list 返回的工具定义示例

{
  "tools": [
    {
      "name": "get_weather",
      "title": "查询天气",
      "description": "获取指定城市的当前天气。city 传中文或拼音城市名，如 '北京' 或 'shanghai'。",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名称" }
        },
        "required": ["city"]
      }
    }
  ]
}

inputSchema 是标准 JSON Schema——这就是宿主可以自动做参数校验、模型可以生成合法参数的原因。description 不是给人看的注释，而是模型的决策依据（第 8 章会讲怎么把它写好）。

tools/call 的典型结果形态

{
  "content": [
    { "type": "text", "text": "2026-09-29 北京：晴 26°C" }
  ],
  "structuredContent": { "city": "北京", "weather": "晴", "temp_c": 26 },
  "isError": false
}

content 是给模型看的（文本最通用）；structuredContent（2025-06-18 规范引入）是给程序看的结构化输出，便于客户端做后续处理。

2.5 传输层：stdio 与 Streamable HTTP

2.5.1 stdio——本地子进程

• 宿主把服务器作为子进程启动，通过 stdin/stdout 收发 JSON 行，stderr 留给服务器打日志。
• 优点：零网络配置、天然本机权限、适合个人开发与桌面场景。
• 限制：只在本机可用；每个宿主各自拉起一份进程实例；无法集中管控。

2.5.2 Streamable HTTP——远程 HTTP 服务

• 服务器是一个 HTTP 服务（如 FastAPI/Express 起的进程）；客户端向固定的 MCP 端点（如 /mcp）发 POST，响应可以是普通 JSON，也可以升级为 SSE 流式返回多条消息。
• 支持会话管理（Mcp-Session-Id 头）、断线重连、无状态水平扩展（配合外部会话存储）。
• 2025-03-26 版规范用 Streamable HTTP 取代了旧的 HTTP+SSE 双端点方案；如果你在老文章里看到 SSE 传输，理解为其前身即可。

2.5.3 选型对照

建议：开发阶段一律用 stdio（简单、Inspector 支持最好），需要共享或上生产时切换到 Streamable HTTP——同一份工具代码几乎不用改。

2.6 客户端能力：服务器也可以"反客为主"

规范同时定义了服务器可请求宿主提供的能力，三者都属可选：

这三个能力把"双向协作"纳入了协议：服务器不必自带模型密钥（sampling）、不必猜测权限边界（roots）、可以用标准方式向用户要确认（elicitation）。企业实践中 elicitation 常用于高危操作的双确认（第 12 章）。

2.7 规范版本演进（建立时间感）

对本教程而言：所有示例兼容 2025-06-18 及以后版本。SDK 会替你处理版本协商，你只需要知道历史版本的存在，以便读懂老代码与老文章。

2.8 动手：用 5 条报文手动扮演 MCP 客户端

不写一行代码，体验协议本身。

方法 A（推荐）：用官方调试器观察真实报文。

# 在任意目录创建一个最小服务器后（第 4 章），运行：
npx @modelcontextprotocol/inspector python examples/python/minimal_server.py
# 浏览器自动打开调试界面 → Connect → 在右边面板观察消息日志

方法 B：直接向一个 stdio 服务器"喂"报文。创建文件 handshake.jsonl（五条消息，每行一条）：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"0.0.1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"北京"}}}
{"jsonrpc":"2.0","id":4,"method":"prompts/list"}

然后（Linux/macOS）：

cat handshake.jsonl | python examples/python/minimal_server.py

你会看到服务器逐条返回 JSON 响应——刚才那 5 行，就是宿主应用背后真正发生的事。

Windows PowerShell 用户注意编码问题：建议在 Git Bash 中执行，或用 WSL。

2.9 小结

• MCP = JSON-RPC 2.0 消息语义 + 可替换传输层（stdio / Streamable HTTP）。
• 生命周期：initialize 握手 → 能力协商 → notifications/initialized → 正常交互 → 关闭；握手后只能用双方声明过的能力。
• 三原语各有 list/get 类发现方法与调用方法；工具结果区分 isError（业务失败）与协议级 error。
• Streamable HTTP 是远程部署的标准传输；stdio 适合本地开发。
• Sampling / Roots / Elicitation 让服务器可以请求宿主侧的能力。

动手练习

1. 报文阅读：解释下面这条消息的性质（请求/响应/通知？谁发给谁？），并推测其触发时机： { "jsonrpc": "2.0", "method": "notifications/resources/list_changed" }
2. 动手：完成 2.8 节的方法 B，把你看到的 5 条响应原文贴进笔记，并标注每条对应生命周期的哪个阶段。
3. 设计思考：你的公司要把"订单查询"做成共享 MCP 服务器，供 200 名员工的 Agent 使用。选择 stdio 还是 Streamable HTTP？列出三个理由。（提示：用户数、权限隔离、运维方式）
4. 版本思考：2025-11-25 引入的 Tasks（长任务）解决什么问题？想象一个"批量导出 10 万条数据"的工具，没有 Tasks 时协议会遇到什么困难？（提示：HTTP 请求超时、进程重启后任务丢失）

下一章：第 3 章 · Skill 是什么：概念、原理与适用场景 —— 换一个视角：除了给模型"装手"，还可以给模型"教流程"。

📄 第 3 章 · Skill 是什么：概念、原理与适用场景 03-what-is-skill.md✓ 标记已学

本章目标：理解 Agent Skill 解决什么问题、SKILL.md 的文件结构与渐进式披露机制、Skill 与 MCP 及传统提示词工程的关系，并能在头脑中把一项"团队流程知识"翻译成 Skill 的形态。

3.1 从另一个真实痛点说起

假设你的团队有一套成熟的代码审查流程：

1. 先跑静态检查工具；
2. 按清单检查安全、性能、可读性；
3. 按"必须修复 / 建议 / 可选"三档输出意见；
4. 最后按公司模板生成审查报告。

每次让 AI 助手做代码审查，你都得把这四步重新打一遍字——或者贴一大段精心调教过的提示词，而它只躺在某个人的聊天记录里，无法复用、无法版本管理、无法随团队改进。

Agent Skill 的思路：把这类流程性知识（procedural knowledge）打包成一个文件夹，放在约定位置，AI 在需要时自己发现并加载它。

没有 Skill                          有 Skill
──────────────                     ──────────────
每个人手敲/粘贴流程提示词              流程沉淀在 skills/code-review/
  ├─ 版本散落在聊天记录里              ├─ SKILL.md（步骤+规范）
  ├─ 新人拿到的是三个月前的旧版          ├─ scripts/lint.sh（配套脚本）
  └─ 换个 AI 应用全部重来               └─ review-template.md（输出模板）
                                   任何支持 Agent Skills 的应用自动发现、
                                   按需加载、随 Git 版本管理

一句话定义：

Skill 是一个以 SKILL.md 为核心的文件夹：用结构化元数据描述"我是什么、什么时候用"，用 Markdown 正文描述"怎么做"，用可选的脚本与参考文件承载配套资产。AI Agent 根据任务语义自动发现并按需加载它。

Anthropic 于 2025 年 10 月推出 Agent Skills，同年 12 月将 SKILL.md 格式开放为跨平台标准——如今 Claude、ZCode、以及大量第三方 Agent 都遵循同一格式。你可以把它理解为"给 AI 用的开源插件，只是插件的内容主要是知识，而不是代码"。

3.2 解剖一个 Skill：目录结构

code-review/                 ← Skill 名称 = 文件夹名
├── SKILL.md                 ← 必需：入口文件（元数据 + 指令）
├── reference.md             ← 可选：详细参考资料（按需加载）
├── scripts/
│   └── run_linters.sh       ← 可选：确定性脚本（由 Agent 执行）
└── assets/
    └── report-template.md   ← 可选：模板/素材（输出时使用）

SKILL.md 的两部分

---
name: code-review                ← 唯一标识（小写字母、数字、连字符）
description: 审查 Git 代码变更并按公司
  规范输出结构化审查报告。当用户要求
  review 代码、检查 PR 或评估提交质量
  时使用。                        ← 【最关键的字段：触发条件】
---

# 代码审查流程

## 步骤
1. 先运行 `scripts/run_linters.sh` 收集静态检查结果
2. 按以下维度逐一检查：安全性 → 性能 → 可读性 …
3. 意见分三档：必须修复 / 建议 / 可选
4. 用 assets/report-template.md 的格式输出报告

## 详细规范
补充检查清单见 reference.md（仅在需要时阅读）

• YAML frontmatter（元数据）：name 和 description 是核心。description 尤其重要——它是 Agent 判断"当前任务是否该用这个 Skill"的唯一依据（详见 3.3 的渐进式披露）。
• 正文（指令）：用自然语言写给模型看的操作手册。可以引用同目录下的脚本、参考文件、模板。

不同宿主对 frontmatter 的扩展字段略有差异（如允许的工具白名单、版本号等），但 name + description 是全平台通用的最小集。写 Skill 时先保证这两个字段，再考虑扩展。

3.3 核心机制：渐进式披露（Progressive Disclosure）

Skill 最精妙的设计是三级按需加载，解决了"知识越多，上下文越贵"的矛盾：

 第 1 级：元数据（始终在上下文里）
 ┌────────────────────────────────────────┐
 │ 所有已安装 Skill 的 name + description    │   ≈ 每个 Skill 仅 ~50–100 token
 │ 例：code-review —— "审查 Git 代码变更…"   │   装几十个 Skill 也几乎无感
 └───────────────┬────────────────────────┘
                 │ 模型判断当前任务匹配 → 触发
                 ▼
 第 2 级：SKILL.md 正文（触发时加载）
 ┌────────────────────────────────────────┐
 │ 完整流程指令，一般 < 5k token             │
 └───────────────┬────────────────────────┘
                 │ 正文引用了某个文件 → 按需读取
                 ▼
 第 3 级：附属文件（用到才加载）
 ┌────────────────────────────────────────┐
 │ reference.md / 脚本 / 模板                │   想多大就多大，不占常驻上下文
 └────────────────────────────────────────┘

对比传统方案：

设计启示：Skill 的大小与成本是解耦的——你可以放心写一份 50 页的《公司安全编码规范》作为 reference 文件，而它的常驻成本只有 frontmatter 里那一小段描述。把"触发判断所需的浓缩信息"写进 description，把"执行所需的完整细节"放进正文与附属文件。

3.4 触发方式：模型自主 vs 用户显式

Skill 有两种触发路径：

1. 模型自主触发（默认）：Agent 每轮推理时扫描所有 Skill 的 description，判断与当前任务的相关性，匹配则加载执行。→ description 的质量 = 触发的准确率。
2. 用户显式调用：很多宿主支持以斜杠命令直接调用（如 /code-review），跳过语义判断。适合"我就要跑这个流程"的场景。

另外，Skill 是知识，不是权限：Skill 正文可以指挥模型"调用某个工具"，但真正的执行仍走宿主的工具体系（内置工具或 MCP 工具）。这一性质使 Skill 天然可以与 MCP 组合（第 6 章）。

3.5 什么样的知识适合做成 Skill

判断标准（满足越多越适合）：

• [ ] 有固定流程：步骤明确、可复述，而不是每次即兴发挥；
• [ ] 有团队约定：规范、模板、检查清单——需要"每次都一样"的输出；
• [ ] 有明确的触发场景：能用一两句话描述"什么任务该想起我"；
• [ ] 可以借力工具：流程中包含可执行的操作（跑脚本、调 API），Skill 负责编排；
• [ ] 需要沉淀与迭代：希望进 Git、可评审、可传承。

典型例子：

反例（不适合 Skill）：一次性任务、"帮我翻译这段话"这类通用能力（模型本来就会）、纯事实查询（适合做成工具或资源）。

3.6 Skill 与周边概念的关系

┌────────────────────────────────────────────────────┐
│                    AI Agent（宿主）                   │
│                                                    │
│  内置能力（读写文件、执行命令…）                          │
│  + MCP 工具（连接外部系统，见第 1–2 章）                  │
│  + Skills（流程知识，告诉模型"何时/如何编排这些能力"）      │
│                                                    │
│  简记：MCP 给模型「手」，Skill 给模型「操作手册」           │
└────────────────────────────────────────────────────┘

3.7 一个完整的 SKILL.md 示例

以下是一个真实可用的 Skill（配套文件见 examples/skills/commit-helper/）：

---
name: commit-helper
description: 按团队规范生成 Git 提交信息与提交。当用户要求
  提交代码、写 commit message、或说"帮我 commit"时使用。
---

# 提交助手

## 流程
1. 运行 `git status` 与 `git diff --staged` 了解本次改动
2. 判断改动类型：feat / fix / refactor / docs / test / chore
3. 按以下格式生成提交信息：
   - 标题行：`<type>(<scope>): <不超过 50 字的概括>`
   - 空一行后写正文，说明**为什么**改，而不是罗列改了什么
4. 展示建议的提交信息，征得用户同意后再执行 git commit
5. 【禁止】未经确认执行 push、rebase、reset 等破坏性操作

## 约定
- 本仓库使用中文提交信息
- 一次提交只做一件事；发现改动混杂时，先建议用户拆分

注意第 5 步：Skill 正文是执行安全约束的好位置——它只在流程被触发时生效，能针对该场景收紧 Agent 的行为。

3.8 小结

• Skill = SKILL.md（元数据+指令）+ 可选的脚本/参考/模板，承载流程性知识。
• 渐进式披露三级加载：元数据常驻（极小）→ 正文按需 → 附属文件用到才读，让知识规模与上下文成本解耦。
• 触发靠 description 与任务语义匹配；格式是跨平台开放标准。
• Skill 与 MCP 是互补关系：MCP 提供能力，Skill 提供使用能力的套路。

动手练习

1. 逆向工程：打开 examples/skills/incident-review/SKILL.md，回答：它的触发场景是什么？哪些内容被放进了附属文件而不是正文？为什么这样拆？
2. 知识盘点：写下你团队里"每次都要口头交接一遍"的三个流程（如发版、值班交接、数据导出申请）。按 3.5 节的标准逐条打分，选出最适合做成 Skill 的一个。
3. description 诊所：下面两个 description 哪个触发更可靠？为什么？试着改写差的那个：
   • A：帮助用户处理各种文档相关工作。
   • B：将会议录音的转写文本整理成符合公司模板的会议纪要。当用户给出录音转写稿并要求生成会议纪要时使用。
4. 思考题：Skill 的第 3 级（附属文件）为什么不直接全部塞进 SKILL.md 正文？（提示：从"上下文成本"与"维护成本"两个角度想）

下一章：第 4 章 · 动手实战：构建第一个 MCP 服务器 —— 打开编辑器，20 行代码让你的第一个工具接入 AI 客户端。

📄 第 4 章 · 动手实战：构建第一个 MCP 服务器 04-first-mcp-server.md✓ 标记已学

本章目标：从零构建、运行一个真实可用的 MCP 服务器，把它接入 AI 客户端，并完成一次端到端的工具调用。预计用时 30 分钟。

本章的完整代码在仓库中：examples/python/minimal_server.py。

4.1 我们要做什么

一个"天气查询"服务器，暴露一个工具 get_weather(city)。演示用天气数据是硬编码的（教学目的）；第 7 章会把它升级为调用真实 HTTP API 的版本，第 13 章再部署上线。

选它做第一个例子的原因：参数简单、无副作用、结果直观——把注意力全部留给协议接入流程本身。

4.2 环境准备

# Python 3.10+，安装官方 MCP SDK（含 CLI 与 FastMCP 高层封装）
pip install "mcp[cli]"

# 验证
python -c "import mcp; print(mcp.__version__)"
mcp --help   # SDK 自带的命令行工具

4.3 十分钟写一个 MCP 服务器

新建 server.py：

"""最小 MCP 服务器：一个天气查询工具。

运行方式（本地调试）：
    mcp dev server.py          # 启动调试器（推荐）
    python server.py           # stdio 传输，供客户端直接拉起
"""
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo-weather")

# 演示用硬编码数据；真实实现请调用天气 API（密钥从环境变量读取）
_FAKE_WEATHER = {
    "北京": "晴，26°C，西北风 3 级",
    "上海": "多云，28°C，湿度 70%",
    "广州": "阵雨，31°C，湿度 85%",
}


@mcp.tool()
def get_weather(city: str) -> str:
    """获取指定城市的当前天气。

    Args:
        city: 城市中文名，如 "北京"。
    """
    if city not in _FAKE_WEATHER:
        return f"暂无 {city} 的天气数据，当前支持：{', '.join(_FAKE_WEATHER)}"
    return f"{city}：{_FAKE_WEATHER[city]}"


if __name__ == "__main__":
    mcp.run(transport="stdio")

就这么简单。 逐行解读关键部分：

这就是 FastMCP 高层 API 的哲学：你写普通 Python 函数，框架负责协议。参数类型注解（str、int、list[str]、Pydantic 模型等）都会被转成规范的 inputSchema。

注意：SDK 里有两类 FastMCP——官方 SDK 内置的 mcp.server.fastmcp（本教程使用），与社区增强版 fastmcp 包（v2，额外提供中间件、代理、组合等企业特性，见第 11 章）。API 高度相似，教程代码可平滑迁移。

4.4 第一次运行：用调试器验证

不接客户端，先单测服务器本身。官方调试器（Inspector）是最好的起点：

mcp dev server.py
# 等价于：npx @modelcontextprotocol/inspector python server.py

浏览器会打开调试界面：

1. 点击 Connect —— 观察右侧消息面板：initialize 握手、能力协商（第 2 章的知识活起来了）；
2. 切到 Tools 标签 → List Tools —— 应看到 get_weather 及由 docstring 生成的描述；
3. 填入 city = "北京" → Run Tool —— 返回 "北京：晴，26°C…"。

✅ 若一切正常，服务器逻辑与协议接入都已验证。开发期请养成"先 Inspector、后客户端"的习惯——排查问题时先隔离变量。

4.5 接入 AI 客户端实测

Claude Desktop

编辑配置文件（Windows：%APPDATA%\Claude\claude_desktop_config.json；macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "demo-weather": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ 三个新手高频坑：

1. args 必须是绝对路径，相对路径在不同启动目录下会失败；
2. Windows 下若装了多个 Python，建议用绝对路径指向目标解释器（如 C:/Python312/python.exe），或把 command 设为解释器绝对路径；
3. 配置为 JSON，不要有注释和多余逗号；修改后需完全重启客户端（托盘退出，不是关窗口）。

重启 Claude Desktop，应看到工具图标（锤子）出现。发起对话：

🧑 用户：北京今天天气怎么样？ 🤖 助手：（内部调用 get_weather(city="北京")） 北京今天是晴天，26°C，有 3 级西北风……

ZCode / Cursor 等其他客户端

各家客户端均支持标准的 mcpServers 配置，格式与上面一致，只需放到对应客户端的配置文件中（具体位置见其文档）。本项目根目录的 .mcp.json 也使用同一格式，团队可随仓库共享服务器配置。

不装客户端也能测：命令行开发工具

# SDK 自带的 CLI 直接调用，做冒烟测试
mcp run server.py   # 以默认传输启动服务器（观察启动日志）

4.6 端到端验证清单

4.7 常见首次失败排查

更系统的排错方法（日志、协议级调试、测试）见第 10 章。

4.8 小结

• FastMCP 让"写 MCP 服务器"退化为"写带类型注解和 docstring 的 Python 函数"。
• 函数签名 → inputSchema；docstring → 工具描述——这两处就是模型的全部决策依据。
• 标准开发循环：Inspector 自测 → 接入客户端 → 自然语言实测。
• stdio 服务器的 stdout 是协议通道，调试输出走 stderr。

动手练习

1. 基础：照做一遍本章流程，截图保存"Inspector 调用成功"与"客户端真实对话"两张结果。
2. 加一个工具：给服务器新增 list_supported_cities()，无参数，返回支持的城市列表。重启客户端后问模型："这个天气工具支持哪些城市？"观察模型是否正确地选择了新工具——体会"模型通过 description 自主决策"。
3. 参数升级：把 get_weather 改为接受两个参数 city: str, date: str = "today"，docstring 说明 date 取值。测试模型对默认参数的行为。
4. 排错演练（重要）：故意把配置中的路径改成不存在的文件，观察客户端的报错表现；再故意在 get_weather 里加一行 print("debug")，观察协议如何被污染。记录这两种失败的现象——第 10 章它们会再次出现。

下一章：第 5 章 · 动手实战：创建第一个 Skill —— 十分钟把一段流程知识装进 AI 的工作习惯。

📄 第 5 章 · 动手实战：创建第一个 Skill 05-first-skill.md✓ 标记已学

本章目标：从零编写、安装、触发一个真实可用的 Skill，理解"写 Skill"与"写提示词"的差别，并完成一次带触发验证的闭环。预计用时 15 分钟。

本章示例的成品在仓库中：examples/skills/commit-helper/。

5.1 我们要做什么

commit-helper：一个教 AI 按团队规范生成提交信息的 Skill。选它的理由：

• 流程明确（看 diff → 判断类型 → 生成信息 → 确认后提交），是教科书式的"流程知识"；
• 有真实约束（中文提交信息、禁止未确认的 push），能演示 Skill 如何收紧行为；
• 触发场景清晰，容易验证"模型是否自己想到了用它"。

5.2 十分钟创建 Skill

第 1 步：建目录

Skill 就是普通文件夹，放到宿主约定的发现路径即可。常见路径（以 name 为目录名）：

# 以「项目级、随仓库共享」为例
mkdir -p .claude/skills/commit-helper

第 2 步：写 SKILL.md

创建 .claude/skills/commit-helper/SKILL.md：

---
name: commit-helper
description: 按团队规范生成 Git 提交信息并完成提交。当用户
  要求提交代码、写 commit message、或说"帮我 commit"时使用。
---

# 提交助手

## 流程
1. 运行 `git status` 与 `git diff --staged` 了解本次改动；
   若暂存区为空，提示用户先 `git add`，不要自行选择文件暂存。
2. 判断改动类型：feat / fix / refactor / docs / test / chore。
3. 按以下格式生成提交信息：
   - 标题行：`<type>(<scope>): <不超过 50 字的概括>`
   - 空一行后写正文：解释**为什么**改，而不是罗列改了什么
4. 先展示建议的提交信息，征得用户同意后，再执行 `git commit`。
5. 【禁止】未经用户明确确认执行 push、rebase、reset 等任何
   改写历史或对外发布的操作。

## 约定
- 本仓库使用中文提交信息。
- 一次提交只做一件事；发现改动混杂时，先建议用户拆分。

写法要点（第 3 章知识的落地）：

• description 同时写了"做什么"和"何时用"（触发条件），这是触发准确率的关键；
• 正文只写模型不知道且需要遵守的东西——不要写"使用 git 命令"这种废话，要写"标题不超过 50 字"这种约定；
• 危险动作显式禁止（第 5 步），Skill 是场景级安全约束的天然挂载点。

第 3 步：重启 / 重载会话

宿主在会话启动时扫描 Skill 目录。新建 Skill 后需要重启会话或执行重载命令（各宿主不同，Claude Code 中新会话自动生效）。

第 4 步：验证触发

# 在仓库里随便改点东西并暂存
echo "test" >> README.md && git add README.md

然后对 AI 说："帮我把这个改动提交了"。

通过标准：AI 的行为符合 SKILL.md——先跑 git status/git diff，产出 docs(readme): … 风格的中文标题行，先征求确认再提交。

若没有触发（AI 直接乱提交或反问格式），几乎都是 description 写得不够"撞词"——练习 3 会专门训练这一点。

5.3 进阶半步：给 Skill 配一个脚本

Skill 的正文是自然语言，但流程中"确定性的部分"应该写成脚本让模型执行——比"请仔细检查暂存区是否混入了大文件"这种叮嘱可靠得多。

改造目录：

commit-helper/
├── SKILL.md
└── scripts/
    └── preflight.sh        ← 新增

scripts/preflight.sh：

#!/usr/bin/env bash
# 提交前检查：暂存区状态、大文件、敏感文件
set -euo pipefail

echo "== 暂存文件 =="
git diff --staged --name-only

echo "== 大于 5MB 的暂存文件 =="
git diff --staged --name-only -z | xargs -0 -r du -m 2>/dev/null | awk '$1 >= 5'

echo "== 疑似敏感文件（.env / 密钥） =="
git diff --staged --name-only | grep -Ei '\.(env|pem|key)$' || echo "（无）"

在 SKILL.md 的流程第 1 步后插入：

1.5. 运行 `bash scripts/preflight.sh`；若发现大文件或疑似敏感
     文件，先中止流程并向用户报告，不要继续生成提交信息。

重新触发一次：如果暂存区里有 config.env，AI 应当中止并警告。体会这个模式：判断逻辑写在脚本里（确定、可测试），决策流程写在正文里（灵活、可解释）。

安全提醒：Skill 会随仓库分发，脚本也会。永远不要把密钥、内网地址等敏感信息写进 Skill 的任何文件；脚本对外部输入保持与普通 shell 脚本相同的警惕（见第 12 章）。

5.4 Skill 的生命周期心智模型

编写 ──▶ 安装（放入发现路径）──▶ 发现（宿主扫描，元数据常驻）
     ──▶ 触发（语义匹配 / 显式调用）──▶ 加载正文 ──▶ 执行
     ──▶ 迭代（改 description / 正文 / 脚本）—— 和改代码一样

两个实践习惯：

1. 把 Skill 当代码管理：放 Git、走 PR 评审、写变更说明。它是团队资产。
2. 触发验证纳入迭代：每次修改 description，都用 2–3 句"用户真实会说的话"测一遍触发与不触发两侧（"帮我提交"应触发；"帮我把这段话翻译成英文"不应触发）。

5.5 小结

• Skill = 放对位置的一个文件夹；name + description 决定发现与触发，正文决定执行质量。
• 确定性判断写成脚本，决策流程写在正文。
• 新 Skill 修改后要重载会话；触发验证（正例 + 反例）是基本测试。
• Skill 随仓库分发 = 知识随代码版本化，这是它相对"聊天记录里的提示词"的本质优势。

动手练习

1. 基础：完成 commit-helper 的创建与触发验证，并补做脚本版检查。
2. 写一个你自己的：把你在第 3 章练习 2 中选出的团队流程写成 Skill（先只写 SKILL.md）。用三个真实说法测试触发；不触发就迭代 description，直到稳定。
3. 触发训练：为 commit-helper 的 description 做一次"撞词"升级测试——分别用以下 5 句话测试，记录哪些触发了：
   • "帮我提交一下" ✅ 预期触发
   • "commit 一下" ✅ 预期触发
   • "把这个文件删了" ❌ 预期不触发
   • "写个提交说明" ✅ 预期触发
   • "帮我写个周报" ❌ 预期不触发 对误触发/漏触发的句子，调整 description 用词（补充同义词、排除词）后重测。
4. 观察渐进式披露：如果宿主支持查看上下文用量，对比"安装 1 个 Skill"与"安装 10 个 Skill"后的基础上下文差异——直观感受第 3 章"每个 Skill 常驻仅几十 token"的说法。

下一章：第 6 章 · MCP 与 Skill：如何选择与组合 —— 两把都拿到手了，什么时候用哪把？

📄 第 6 章 · MCP 与 Skill：如何选择与组合 06-mcp-vs-skill.md✓ 标记已学

本章目标：建立一个可复用的决策框架——面对一个需求，能快速判断该用 MCP、Skill、还是两者组合；并识别常见的误用模式。

6.1 核心差异：一张对照表

6.2 决策框架：三连问

面对"我想让 AI 能做 X"的需求，依次问：

Q1. X 需要访问模型本来够不着的「外部系统或数据」吗？
    ├─ 是 ──▶ 需要 MCP（或至少需要某个工具）
    └─ 否 ──▶ 进 Q2
Q2. X 有一套「希望每次都执行一致的流程/规范/模板」吗？
    ├─ 是 ──▶ 需要 Skill
    └─ 否 ──▶ 什么都不用，直接问就行
Q3. （常见情况：两者都答"是"）
    ▶ 组合：MCP 提供能力，Skill 提供编排
      例：Skill 指导模型按正确顺序、正确参数调用 MCP 工具

用例子校准

最常见的错误：把该做成 Skill 的东西做成了 MCP 服务器。例如有人写了一个"提交信息生成服务器"，暴露 generate_commit_message() 工具——这是把一段流程知识硬编码成了协议服务，失去了迭代灵活性，还平白增加常驻上下文。反过来也成立：指望用 Skill 让 AI 获得"访问数据库的能力"，则完全用错了工具——知识不会凭空长出接口。

6.3 组合模式详解

生产环境中，MCP 与 Skill 大多以组合形态出现。三种典型模式：

模式 A：Skill 作为 MCP 工具的"使用说明书"

工具定义（JSON Schema + 一两句描述）只能承载有限的使用知识：参数怎么填、什么场景用哪个工具、工具间如何搭配。把这些知识放进 Skill：

---
name: incident-response
description: 线上故障应急处理流程。当用户报告线上故障、
  服务异常告警，或要求排查生产问题时使用。
---

# 应急流程
1. 调用 monitoring 服务器（MCP）的 `query_alerts(service=…)`，
   先取最近 30 分钟告警，**不要**先问用户是哪个服务——
   从告警中推断。
2. 若 P0/P1 告警存在 → 调用 `page_oncall()`（MCP）通知值班，
   再继续排查；任何回滚操作必须先征得用户确认。
3. 用 kb 服务器（MCP）的 `search_runsheets(service=…)` 查
   历史预案，找到相似故障时优先按预案处理。
4. 处置结束后，引导用户使用 incident-review Skill 写复盘。

这就是企业实践中最值钱的组合：MCP 服务器提供原子能力，Skill 沉淀"哪一步用哪个工具、什么条件下禁止哪个工具"的组织记忆。工具是员工，Skill 是 SOP。

模式 B：Skill 生成"给 MCP 的正确输入"

很多 MCP 工具的参数（如 SQL、JQL 查询语句）需要专业技巧。Skill 可以承载"如何构造参数"的领域知识：

---
name: sql-conventions
description: 为内部数据仓库编写查询时的规范。当需要调用
  warehouse 服务器执行查询时使用。
---

# 查询规范
- 一律先 `EXPLAIN` 再执行；扫描行数预估超过 1 亿时必须改写
- 时间过滤条件必须带时区：`ts >= '2026-09-01 00:00:00+08'`
- 生产查询强制 `LIMIT`，分页用 `LIMIT 5000 OFFSET n`
- 禁止 `SELECT *`：只选需要的列，减少网络与内存开销

模式 C：Prompt 原语与 Skill 的分界

MCP 的 Prompts 原语与 Skill 看起来很像（都是模板），分界线是归属与分发：

• 提示模板与某个系统能力强绑定（如数据库服务器的"执行计划分析"模板）→ 放进 MCP 服务器的 prompts/，让能力自带最佳实践；
• 提示模板跨越多个工具/系统，或属于团队通用规范 → 做成 Skill。

6.4 反模式清单（真实世界高频踩坑）

6.5 一张总图：AI 能力栈中的位置

┌─────────────────────────────────────────────────────┐
│ 用户                                                 │
└───────────────┬─────────────────────────────────────┘
                │ 自然语言
┌───────────────▼─────────────────────────────────────┐
│ Agent 宿主（Host）                                    │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │ 会话/记忆     │  │ Skills       │  │ 内置工具     │  │
│  └─────────────┘  │ （流程知识）   │  │ （文件/终端） │  │
│                   └──────┬───────┘  └────────────┘  │
│                          │ 编排                       │
│                   ┌──────▼───────┐                   │
│                   │ MCP Clients  │                   │
│                   └──────┬───────┘                   │
└──────────────────────────┼──────────────────────────┘
                           │ MCP 协议（stdio / HTTP）
     ┌─────────────┬───────┴──────┬─────────────┐
     ▼             ▼              ▼             ▼
 ┌────────┐  ┌────────┐   ┌──────────┐  ┌──────────┐
 │ 数据库   │  │ 工单系统 │   │ 监控平台   │  │ 知识库     │
 │ server │  │ server │   │ server   │  │ server   │
 └────────┘  └────────┘   └──────────┘  └──────────┘

记住这张图的分层，后面第 11 章（企业架构）会在此基础上加"网关层"。

6.6 小结

• 决策三连问：需要新能力吗（→MCP）？需要一致流程吗（→Skill）？多数真实需求是组合。
• 组合的本质：MCP 是员工（能力），Skill 是 SOP（编排）。
• Prompts 原语与 Skill 的分界：能力绑定的模板进服务器，跨系统的规范进 Skill。
• 高频反模式：万物皆工具、工具泛滥、描述空洞、用 Skill 管权限。

动手练习

1. 决策演练：判断以下 6 个需求各该用什么（MCP / Skill / 组合 / 都不用），写出理由： a. 让 AI 能在 Notion 里创建页面 b. 让 AI 按公司格式写 OKR 初稿 c. 让 AI 能查 Notion，且按公司格式生成周报（引用本周页面） d. 让 AI 的回复总是简明扼要 e. 让 AI 能重启内部 K8s 中的服务 f. 让 AI 重启服务前必须按应急手册确认影响范围 （参考答案：a-MCP；b-Skill；c-组合；d-提示词/系统提示；e-MCP+高危管控；f-组合，且权限在工具层）
2. 体检你现有的配置：打开你 AI 客户端里已装的 MCP 服务器与 Skill，用 6.4 的反模式清单逐条体检，找出至少一个可优化点。
3. 设计题：为公司"数据导出"场景设计完整方案：员工说"把这批用户数据导出发我邮箱"，涉及数据仓库（MCP）、邮件（MCP）、以及导出合规流程（Skill：脱敏规则、审批要求）。画出 6.5 风格的架构草图，标注每个部件的职责。

至此入门篇完成。 你已经理解了两者的原理并能动手搭建。进入进阶篇，我们将系统化地提升开发质量：先从 第 7 章 · MCP 开发全流程 开始。

📄 第 7 章 · MCP 开发全流程：工具、资源与提示 07-mcp-dev-workflow.md✓ 标记已学

本章目标：掌握从需求到发布的完整开发流程；深入 Tools / Resources / Prompts 的设计细节（参数设计、错误处理、生命周期管理）；能独立开发一个封装真实 HTTP API 的生产级服务器。完整示例代码：examples/python/full_server.py。

7.1 开发流程总览

 ① 需求分析          ② 能力设计             ③ 实现
 「谁在什么场景用？」  「该暴露哪些原语？」      「FastMCP/TS SDK」
     │                  │                     │
     │        ┌─────────▼─────────┐           │
     │        │ 工具清单表           │           │
     │        │ (名称/参数/副作用/   │           │
     │        │  权限/错误路径)      │           │
     │        └─────────┬─────────┘           │
     ▼                  ▼                     ▼
 ④ 自测（Inspector）──▶ ⑤ 自动化测试 ──▶ ⑥ 打磨描述与文档 ──▶ ⑦ 发布
        ▲                                                        │
        └──────────────── 迭代 ◀─────────────────────────────────┘

与普通后端开发的最大差异集中在 ② 能力设计：你要设计的不是 REST 接口，而是给模型看的操作面。原则：

1. 面向任务，不面向数据：不要照搬 REST 的 CRUD（get_user/update_user/list_users…），要合并成模型视角的任务（find_customer(query) 一步到位）；
2. 少即是多：每多一个工具，模型的决策空间就大一分。一个域 5–10 个工具是舒适区；
3. 先只读，后写入：第一版只发布查询类工具，写入工具配合确认机制后单独灰度（第 12 章）。

能力设计清单（每个工具一行）：

7.2 Tools 深入设计

7.2.1 参数设计规范

from pydantic import BaseModel, Field

class SearchArgs(BaseModel):
    """（可选）复杂参数用 Pydantic 模型，校验规则一处声明。"""
    query: str = Field(description="关键词，支持中文，如 '登录超时'")
    status: str = Field(default="open", description="open/closed/all")
    limit: int = Field(default=10, ge=1, le=50, description="返回条数上限")

参数设计四原则：

1. 平铺优于嵌套：模型生成嵌套 JSON 的错误率更高；
2. 必填最少化：每个必填参数都是一次失败调用机会。合理默认值 + description 说明；
3. 枚举用字面量联合类型：Literal["open", "closed"] 会被转成 enum schema，显著减少非法值；
4. 描述里写"好例子"：description="关键词，如 '登录超时'" 比只写 "关键词" 好得多——模型会模仿例子。

7.2.2 错误处理：isError 是设计出来的

第 2 章说过，工具的业务失败应返回 isError: true 的结果（而不是抛异常导致协议错误）——这样模型能读到错误信息并自行修正。FastMCP 中，让函数抛出 ToolError 或直接返回错误文本均可；关键在于错误信息是写给模型看的恢复指南：

from mcp.server.fastmcp.exceptions import ToolError

@mcp.tool()
async def create_ticket(title: str, body: str, priority: str) -> str:
    """创建工单。priority 取值：P0(紧急)/P1(高)/P2(普通)。"""
    if priority not in {"P0", "P1", "P2"}:
        # 错误信息 = 现象 + 如何修正，模型收到后通常会自我纠正
        raise ToolError(
            f"非法优先级 {priority!r}，必须是 P0、P1 或 P2。"
            "请与用户确认紧急程度后重试。"
        )
    ...

错误信息三层结构：出了什么事 → 为什么 → 模型下一步该怎么办。

7.2.3 注解（Annotations）：声明副作用

工具定义可携带 annotations 向客户端声明行为特征，宿主据此渲染 UI 或触发审批：

@mcp.tool(
    annotations={
        "readOnlyHint": False,      # 会产生副作用
        "destructiveHint": True,    # 可能破坏性（如删除）
        "idempotentHint": False,    # 重复调用结果不同
        "openWorldHint": True,      # 依赖外部世界状态
    }
)
async def delete_ticket(ticket_id: str) -> str:
    ...

注意 Hint 的含义——供客户端参考，不是安全边界。真正的权限管控在第 12 章的服务器与网关层实现。

7.2.4 长任务与进度（Context 参数）

给函数加一个 ctx: Context 参数即可获得协议级能力（进度上报、日志、取消、sampling），FastMCP 自动识别：

from mcp.server.fastmcp import Context

@mcp.tool()
async def export_report(month: str, ctx: Context) -> str:
    """导出指定月份的运营报告。month 格式：2026-09。"""
    steps = ["拉取数据", "计算指标", "渲染表格"]
    for i, step in enumerate(steps, 1):
        await ctx.report_progress(i, len(steps))   # 进度通知
        await ctx.info(f"开始：{step}")             # 结构化日志 → 客户端日志面板
        ...  # 真实工作
    return "报告已生成：/tmp/report-2026-09.xlsx"

超长任务（分钟级）在当前协议下的更优解：立即返回任务 ID + 提供查询进度的配套工具（start_export / check_export），或关注规范的 Tasks 能力（第 2、14 章）。

7.3 生命周期管理：把重资源挂在 lifespan 上

数据库连接池、HTTP 客户端这类启动一次、全程复用的资源，应放在 lifespan 中，避免每次调用重建：

from contextlib import asynccontextmanager
from collections.abc import AsyncIterator
from dataclasses import dataclass
import httpx

@dataclass
class AppContext:
    http: httpx.AsyncClient          # 复用连接池（性能关键，见第 14 章）

@asynccontextmanager
async def app_lifespan(server) -> AsyncIterator[AppContext]:
    async with httpx.AsyncClient(
        base_url="https://api.example-issues.internal",
        timeout=10,
        # 密钥一律从环境变量读取，绝不硬编码
        headers={"Authorization": f"Bearer {os.environ['ISSUE_API_TOKEN']}"},
    ) as client:
        yield AppContext(http=client)

mcp = FastMCP("issues", lifespan=app_lifespan)

@mcp.tool()
async def search_issues(query: str, ctx: Context) -> str:
    resp = await ctx.request_context.lifespan_context.http.get(
        "/issues", params={"q": query}
    )
    resp.raise_for_status()
    ...

7.4 Resources：给模型"可读的数据面"

# 静态资源
@mcp.resource("issues://stats/summary")
def issues_summary() -> str:
    """工单系统概况（JSON 文本）。"""
    return json.dumps({...}, ensure_ascii=False)

# 资源模板：按参数动态生成 URI
@mcp.resource("issues://{ticket_id}/detail")
def ticket_detail(ticket_id: str) -> str:
    return fetch_detail(ticket_id)

工具 vs 资源的选型：

• 模型需要主动决定去查什么 → 工具（如 search_issues）；
• 宿主/用户需要把某块数据放进上下文 → 资源（如"把这个工单详情附加进来"）；
• 不确定时选工具——它的适用面更广。

7.5 Prompts：把最佳实践固化进服务器

@mcp.prompt()
def triage_issue(ticket_id: str) -> str:
    """生成"工单分诊"提示模板。用户在客户端以 /triage_issue 调用。"""
    detail = fetch_detail(ticket_id)
    return f"""你是一线支持工程师。请按以下顺序分析工单 {ticket_id}：
1. 复现路径与影响范围
2. 初步分类：bug / 配置 / 使用问题 / 疑似缺陷
3. 建议的下一步（含责任方）

工单内容：
{detail}"""

适合做成 Prompts 的：与该系统能力强绑定的分析框架（分诊、执行计划解读、日志归因）。

7.6 TypeScript 对照（同构能力）

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-weather", version: "1.0.0" });

server.registerTool("get_weather", {
  title: "查询天气",
  description: "获取指定城市的当前天气。city 传中文城市名，如 '北京'。",
  inputSchema: { city: z.string().describe("城市名称") },
  annotations: { readOnlyHint: true },
}, async ({ city }) => ({
  content: [{ type: "text", text: `${city}：晴，26°C` }],
}));

await server.connect(new StdioServerTransport());

选择建议：Python 生态（数据分析、内部工具）选官方 mcp SDK；TS 生态（前端团队、Node 服务）选官方 TS SDK。两者协议能力对等。

7.7 发布前的打磨清单

• [ ] 每个工具的 description 能独立回答："这是什么、什么时候用、参数是什么意思、有什么限制"
• [ ] 所有工具标注了 readOnlyHint 等注解
• [ ] 错误信息都是"现象+修正建议"格式（在 Inspector 里故意传错参数测一遍）
• [ ] 重资源在 lifespan 中管理；密钥全部来自环境变量
• [ ] --help、README、服务器版本号齐备
• [ ] 自动化测试通过（第 10 章）

7.8 小结

• 流程七步：需求 → 能力设计（工具清单表）→ 实现 → 自测 → 测试 → 打磨 → 发布。
• 工具面向任务而非数据；参数平铺、必填最少、枚举用字面量、描述带例子。
• 业务失败用 isError + 可恢复的错误信息；注解声明副作用特征。
• lifespan 承载连接池；Context 提供进度/日志/取消。
• Resources 供应用注入数据，Prompts 沉淀能力绑定的最佳实践。

动手练习

1. 升级天气服务器：为第 4 章的 get_weather 接入真实 API（任何免费天气 API；密钥用环境变量 WEATHER_API_KEY 读取），增加：超时处理、非 200 的错误信息格式化、lifespan 中的连接复用。
2. 设计一个域：为你熟悉的内部系统（如 CI 平台）列出"工具清单表"（名称/语义/参数/副作用/错误路径/权限），控制在 8 个工具以内，并说明合并了哪些 REST 接口。
3. 实现它：把练习 2 实现到 full_server.py 的骨架上，至少包含 1 个资源、1 个提示模板、1 个带进度的长任务工具。
4. 对比实验：把某个工具的 description 从一句话改成"三句话（用途/时机/示例）"，在 Inspector 中观察生成的 schema 差异，并在真实客户端中对比模型的调用正确率。

下一章：第 8 章 · 常见模式与最佳实践 —— 从"能跑"到"好用"：真实项目中反复出现的工程模式。

📄 第 8 章 · 常见模式与最佳实践 08-common-patterns.md✓ 标记已学

本章目标：掌握真实 MCP 项目中反复出现的工程模式——工具命名与组织、大结果处理、副作用控制、无状态设计、工具发现模式——并知道每个模式解决什么问题、什么时候不用它。

8.1 模式一：写给模型的文档（描述工程）

模型的全部决策依据 = 工具名 + description + 参数 schema。这是 MCP 项目里投入产出比最高的地方。

工具命名：动词_宾语， Snake Case，一个域内保持动词词汇表一致：

✅ search_issues / get_issue / create_ticket / list_services
❌ getData       / handleIssue / do_query / issueSearch

description 三段式（用途 / 时机 / 边界与示例）：

@mcp.tool()
async def search_issues(query: str, status: str = "open") -> str:
    """按关键词搜索工单。

    适用：用户想找相关工单但不知道具体编号时；返回标题、
    状态、负责人的摘要列表。若用户给出了确切工单号，
    应改用 get_issue。

    Args:
        query: 关键词，支持中文，如 "登录超时"。
        status: open / closed / all，默认 open。
    """

检查标准：遮住工具名，只看 description，能猜出工具是干什么的、什么时候该用/不该用。

8.2 模式二：控制工具数量——从扁平到分层

单个服务器工具过多时（经验值 >20），出现三重问题：模型选错工具、宿主上下文成本上升、维护面失控。三种收敛策略：

策略 A：语义合并

❌ 4 个工具：get_user_by_id / get_user_by_email /
             get_user_by_phone / search_users
✅ 1 个工具：find_customer(query="13800000000 或邮箱或姓名")
   （内部自动识别查询类型）

策略 B：拆分服务器（按业务域）

工具没少，但按域分组、按需挂载：客户端只连当次会话需要的服务器（数据分析师只挂 warehouse，运维只挂 ops）。

策略 C：元工具 + 动态发现（search_tools 模式）

当工具数巨大（企业级，上百个）时，只暴露少数几个"入口工具"，由它们动态发现并转发：

@mcp.tool()
async def search_tools(query: str) -> str:
    """在全部企业工具目录中搜索合适的工具。返回工具名与用途。
    找到后用 call_tool(name, args) 执行。"""

@mcp.tool()
async def call_tool(name: str, args: dict) -> str:
    """执行 search_tools 找到的工具。"""

权衡：多一次发现调用的延迟与 token，换来工具面恒定可控。企业网关（第 11 章）常内建此模式。

8.3 模式三：大结果处理

模型上下文有限且昂贵，工具动辄返回 10 万字符是灾难。三层防线：

@mcp.tool()
async def search_logs(query: str, page: int = 1) -> str:
    """搜索应用日志。每次最多返回 20 条，用 page 翻页。"""
    hits = es.search(query, size=20, from_=(page - 1) * 20)

    if not hits:
        return "无匹配日志。可尝试放宽时间范围或更换关键词。"

    lines = [fmt(h) for h in hits]
    if len(hits) == 20:
        lines.append(f"\n（第 {page} 页，共约 {hits.total} 条。"
                     f"继续请用 page={page + 1}）")
    return "\n".join(lines)

1. 默认限量 + 分页：在工具层强制 LIMIT，结果尾部提示"如何取下一页"（把分页协议写进返回值，模型自己会翻页）；
2. 截断 + 引用：超大输出落盘/上传，返回摘要 + 引用句柄：

   if len(result) > 50_000:
       path = save_to_file(result)          # 服务器侧存储
       return f"结果过大（{len(result)} 字符），已保存至 {path}。"
       # 客户端可用资源读取方式按需取用
   

3. 面向摘要的设计：先返回 list_*（标题列表），由模型决定对哪一条调用 get_* 拿全文——浏览与详情分离，是最有效的上下文节约手段。

8.4 模式四：副作用控制——让危险操作"可控可逆"

@mcp.tool(annotations={"destructiveHint": True})
async def delete_records(table: str, ids: list[str],
                         dry_run: bool = True) -> str:
    """删除指定记录。默认 dry_run=True 只返回将被删除的行，
    确认无误后需显式传 dry_run=False 再次调用。"""
    rows = db.fetch(table, ids)
    if dry_run:
        return f"【预演】将删除 {table} 中 {len(rows)} 行：\n" + \
               "\n".join(str(r) for r in rows) + \
               "\n确认请再次调用并传 dry_run=false。"
    ...

配合宿主的"高危工具人工审批"配置（主流宿主都支持按工具粒度确认），形成双保险。

8.5 模式五：无状态与幂等

服务器尽量无状态，是水平扩展（第 13 章）的前提：

• 会话状态由宿主持有；服务器不存"用户上次查了什么"；
• 必须有状态时（如导出任务），把状态外置到 Redis/DB，返回可续查的句柄（task_id），而不是依赖内存；
• 写操作尽量幂等：create_ticket(idempotency_key=…)——模型偶尔会重试，幂等键防止重复创建。

8.6 模式六：代理与聚合服务器

企业中最常见的服务器形态：薄代理——MCP 工具只是内部 API 的翻译层：

@mcp.tool(annotations={"readOnlyHint": True})
async def get_order(order_id: str) -> str:
    """查询订单详情。order_id 为 12 位数字单号。"""
    try:
        r = await ctx.request_context.lifespan_context.http.get(
            f"/orders/{order_id}"
        )
        r.raise_for_status()
    except httpx.TimeoutException:
        raise ToolError("订单服务超时，请稍后重试或减少查询频率。")
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 404:
            return f"未找到订单 {order_id}，请核对单号。"
        raise ToolError(f"订单服务错误（{e.response.status_code}），"
                        "请联系平台组。")
    return json.dumps(r.json(), ensure_ascii=False)

代理服务器的设计要点：

• 不发明新语义：错误码、字段名尽量忠实转译，避免"二次翻译"失真；
• 边界处理集中在这一层：超时、重试、熔断在这里做，别让模型面对底层网络错误；
• 鉴权信息从环境/请求上下文注入，绝不写死（第 12 章细讲身份传递）。

8.7 模式七：Skill × MCP 的编排层（回顾与深化）

第 6 章已给结论：MCP 是能力、Skill 是 SOP。在进阶视角补充三条工程化建议：

1. 工具描述管"是什么"，Skill 管"怎么做"：不要在工具 description 里写多步流程（放不下也没人维护），流程进 Skill；
2. Skill 中引用工具用全名：写 monitoring 服务器（MCP）的 query_alerts()，避免模型混淆同名工具；
3. 把"禁止项"写进对应场景的 Skill：全局禁止放系统提示词，场景禁止（如"故障排查时禁止重启"）放该场景的 Skill。

8.8 反模式速查

8.9 小结

• 描述工程是第一生产力；三段式 description + 一致命名。
• 工具数量的三个收敛阀：语义合并、按域拆分、动态发现。
• 大结果：限量分页 → 截断引用 → 浏览/详情分离。
• 危险操作：dry-run 默认 + 注解声明 + 确认句柄；服务器无状态、写操作幂等。
• 薄代理是企业服务器的默认形态；边界处理（超时/重试/错误转译）集中在代理层。

动手练习

1. 改造：给第 7 章练习中的 search_issues 落实 8.3 的三层防线（分页、截断、浏览/详情分离），在 Inspector 中用极端参数验证。
2. 安全化：为 delete_records 完整实现 dry-run + 确认句柄流程，写一段用户对话模拟（两轮调用）验证模型行为。
3. 架构判断：你负责的平台已有 35 个工具，模型选错率约 8%。分别评估三种收敛策略的适用性，选出首选并说明落地顺序。
4. 描述 A/B：挑两个使用率低的工具，用 8.1 的三段式重写 description，上线前后各统计一周调用正确率（有 eval 环境更好，第 15 章会介绍）。

下一章：第 9 章 · Skill 开发进阶 —— 把 Skill 从"能用"带到"专业"：渐进式披露的工程化与触发准确率调优。

📄 第 9 章 · Skill 开发进阶 09-skill-advanced.md✓ 标记已学

本章目标：掌握 Skill 的工程化开发——渐进式披露的内容拆分策略、脚本与模板的规范用法、触发准确率调优、多 Skill 协作，以及使用 skill-creator 类工具加速开发。示例：examples/skills/incident-review/。

9.1 进阶 Skill 的目录全貌

incident-review/
├── SKILL.md                      ← 正文 < 500 行；只写流程与决策
├── scripts/
│   ├── fetch_timeline.py         ← 从告警/日志系统拉取事件时间线
│   └── validate_report.py        ← 校验报告格式完整性
├── references/
│   ├── RCA-framework.md          ← 根因分析框架（长文，按需读）
│   ├── severity-matrix.md        ← 定级矩阵（查表用）
│   └── postmortem-examples.md    ← 3 篇标杆复盘范例（学习用）
└── assets/
    └── report-template.md        ← 输出模板

对应 SKILL.md 的结构骨架：

---
name: incident-review
description: 为线上故障编写标准复盘报告。当用户要求复盘故障、
  写 postmortem、或故障处置结束后总结时使用。覆盖定级、时间线、
  根因与改进项四个环节。
---

# 故障复盘流程

## 前置：确定故障与定级
1. 运行 `python scripts/fetch_timeline.py --incident <id>` 获取时间线
2. 依据 references/severity-matrix.md 定级（P0–P3）

## 撰写：按模板生成初稿
3. 使用 assets/report-template.md 作为报告骨架
4. 根因分析遵循 references/RCA-framework.md 的五问法
   （仅 P0/P1 必须完整执行）

## 校验：格式与完整性
5. 运行 `python scripts/validate_report.py <draft>`；
   所有 ERROR 级问题必须修复后才可提交

## 写作红线
- 只陈述可验证的事实，时间线精确到分钟
- 责任指向系统与流程，不指向个人（无责复盘原则）

9.2 内容拆分：渐进式披露的工程决策

第 3 章讲过三级加载机制，这里是拆什么、放哪里的决策表：

拆分信号：当 SKILL.md 正文超过 ~500 行、或某部分只在分支场景用到、或某部分需要高频独立更新——就拆出去。

反模式：把所有知识塞进正文（常驻成本高、模型注意力被稀释）；反过来，把三行流程也拆五个文件（模型来回读文件，效率更低）。正文管流程主干，文件管深度细节。

9.3 脚本规范：确定性优先

Skill 脚本的三条铁律：

1. 退出码与输出结构化：脚本输出要能被模型可靠解析（每行一个事实、明确的 OK/FAIL、JSON 亦可）；
2. 失败信息面向模型：validate_report.py 的输出像第 7 章的工具错误一样写"现象+怎么改"；
3. 自包含 + 相对路径：脚本只依赖 Skill 目录自身（$(dirname "$0")/.. 定位资源）与宿主已有能力，不假设用户环境装了什么。

# scripts/validate_report.py（节选）——面向模型的输出风格
problems = []
if "## 改进项" not in text:
    problems.append("ERROR: 缺少 '## 改进项' 章节。"
                    "请参照模板补充，至少 1 条可执行的改进。")
if re.search(r"[123] 天内", text) is None:
    problems.append("WARN: 未写明改进项完成期限，"
                    "请为每条改进项标注负责人与期限。")

if not problems:
    print("OK: 报告结构完整。")
else:
    print("\n".join(problems))
    sys.exit(1)

脚本 vs MCP 工具的分工：脚本随 Skill 走、本地执行、适合"这个流程专用"的操作；MCP 工具集中部署、跨场景复用、适合"企业共享能力"。同一个 fetch_timeline，若只有复盘流程用 → 脚本；若运维/值班/复盘都要用 → MCP 工具，Skill 里引用它。

9.4 触发准确率：description 的调优方法

触发是 Skill 的生命线。系统化调优步骤：

第 1 步：收集触发样本（正例 + 反例）

正例（应触发）：
  "复盘一下昨晚的支付故障"      "帮我写 postmortem"
  "这次故障的根因分析怎么做"     "把今天的处理过程整理成复盘"
反例（不应触发）：
  "复盘一下这局游戏"（语义陷阱）  "帮我写周报"
  "分析一下这个函数的性能问题"    "故障恢复了，重启一下服务"

第 2 步：对照 description 逐条推演

问自己：这句话和 description 的关键词/意图有重叠吗？会与其它已装 Skill 抢触发吗？

第 3 步：修改 description 的四个手法

第 4 步：回归测试

每次改 description，把样本清单全部重测一遍。团队将样本清单存进 Skill 目录（如 evals.md），评审时作为测试用例——这是把"提示词调优"变成工程实践的关键一步。

9.5 多 Skill 协作

当团队积累了多个 Skill，注意两点：

1. 职责互斥：两个 Skill 的触发范围重叠会导致模型随机二选一。定期用"触发样本互测"检查。若确实重叠（如 incident-review 与 postmortem-template），合并；
2. 显式交接：流程之间用正文显式引导（如复盘 Skill 的最后一步："报告通过校验后，提示用户可用 action-tracker Skill 登记改进项"），比依赖模型自己联想可靠。

9.6 用工具生成 Skill：skill-creator

主流宿主生态提供 Skill 生成器（如 Claude 生态的 skill-creator，ZCode 等也有同类命令/插件），典型用法：

让 AI "帮我创建一个 Skill：把会议录音转写整理成公司格式的纪要" → 生成器引导你回答关键问题（触发场景、输入形态、输出模板、有无配套脚本），产出结构完整的 SKILL.md 草稿。

定位：生成器解决"从 0 到 0.6"（结构不缺、格式规范）；从 0.6 到 1.0 的触发调优与流程细节仍需你按 9.4 完成。生成后务必：核对 frontmatter → 补充真实样本 → 回归测试。

9.7 Skill 质量检查清单

• [ ] name 全小写连字符；description 含"做什么 + 何时用（含同义词）+（必要时）排除边界"
• [ ] 正文 < 500 行，只有流程与决策，无大段知识堆砌
• [ ] 长知识在 references/，确定性操作在 scripts/，输出在 assets/
• [ ] 脚本自包含、相对路径、结构化输出
• [ ] evals.md 触发样本齐备且全部通过
• [ ] 危险操作有明确红线（确认、禁止项）
• [ ] 进 Git、有 README 或元信息（负责人、适用范围）

9.8 小结

• 拆分即架构：description 管发现、正文管流程、references 管深度、scripts 管确定性、assets 管一致性。
• 脚本输出面向模型（现象+怎么改），Skill 与 MCP 工具按"场景专用 vs 企业共享"分工。
• 触发准确率是可以工程化的：样本集 → 推演 → 四手法修改 → 回归测试，全程留档。
• 用生成器提速，但触发调优不可省。

动手练习

1. 拆分实操：拿第 5 章你写的 Skill，按 9.2 决策表重新审计：有没有该进 references 的长知识？有没有该脚本化的确定性步骤？完成一次拆分并对比改造前后模型的执行稳定性。
2. 触发调优：为 incident-review 建立 8 条样本（4 正 4 反），执行完整的四步调优流程，记录每轮的触发结果变化。
3. 脚本化：把"报告校验"从正文叮嘱改写为一个 validate_*.py（可自定义校验规则），并验证：故意缺章节时，模型能根据脚本输出完成自修复。
4. 协作设计：设计 incident-review 与一个新 Skill action-tracker（改进项跟踪）的显式交接流程，并测试两个 Skill 连续触发的体验。

下一章：第 10 章 · 调试排错与测试 —— 把第 4 章埋下的那些坑系统性地填掉。

📄 第 10 章 · 调试排错与测试 10-debugging-testing.md✓ 标记已学

本章目标：建立三层调试方法（工具层 → 协议层 → 网络层），掌握官方调试器、日志系统与自动化测试，并能按清单快速定位 90% 的常见故障。

10.1 调试分层模型

MCP 链路比普通程序多一跳（宿主↔服务器），出问题时先定位在哪一层：

┌─────────┐  ①模型决策   ┌────────┐  ②协议   ┌────────┐  ③下游   ┌────────┐
│ LLM     │ ◀─────────▶ │ Host/  │ ◀──────▶ │ Server │ ◀──────▶ │ API/DB │
│         │  工具选择错?  │ Client │  报文对吗? │        │  下游挂了? │        │
└─────────┘             └────────┘          └────────┘          └────────┘

核心方法论：隔离变量。先用 Inspector 绕过宿主直连服务器——若 Inspector 正常而宿主异常，问题在宿主配置/集成；若 Inspector 也异常，问题在服务器本身。

10.2 首选工具：MCP Inspector

官方交互式调试器，同时支持两种传输：

# stdio 服务器：直接指定启动命令
npx @modelcontextprotocol/inspector python server.py
# 或经 SDK CLI：mcp dev server.py

# HTTP 服务器：打开 UI 后填 URL 连接
npx @modelcontextprotocol/inspector

界面分区与用法：

• 连接面板：传输方式、命令/URL、环境变量、认证头；
• Tools / Resources / Prompts 标签：List → 查看真实协议返回 → 手填参数调用 → 查看原始 JSON 结果与错误；
• 消息日志：完整的 JSON-RPC 报文流——第 2 章学的报文知识在这里变现，initialize 握手、能力协商、每次调用一览无余。

典型定位手法：

1. 服务器不出现 → Inspector 连不上 ⇒ 看启动命令/依赖；Inspector 连得上 ⇒ 问题在宿主配置；
2. 工具行为诡异 → 在 Inspector 手工构造极端参数（空串、超长、非法枚举），观察返回的是友好业务错误还是协议崩溃；
3. 验证修复 → 改代码后 Inspector 里重跑，无需重启整个客户端。

10.3 日志：stdio 服务器的黄金法则

stdio 模式下，stdout 是协议通道。 任何 print() 到 stdout 都会被宿主当成 JSON-RPC 报文解析，直接破坏会话。规则：

import logging, sys

# 日志一律走 stderr（logging 默认就是 stderr）
logging.basicConfig(
    level=logging.INFO,
    stream=sys.stderr,
    format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
log = logging.getLogger("issues")

# ❌ 禁止：print("debug info")        # 会污染协议流
# ✅ 正确：log.info("查询工单 q=%r", query)

宿主侧查看日志：

• Claude Desktop：~/Library/Logs/Claude/mcp*.log（macOS）或 %APPDATA%\Claude\logs\（Windows）；
• ZCode / Cursor 等：各自的 MCP 日志面板或输出目录，见其文档；
• 服务器自己打的 stderr 日志会出现在宿主对应服务器条目的日志里。

协议内的日志：第 7 章的 await ctx.info(...) / ctx.warning(...) 走 MCP 的 notifications/message，会显示在宿主的 MCP 日志面板——面向用户的执行说明用 ctx 日志，面向开发者的诊断用 stderr。

10.4 常见故障速查表

10.5 网络层调试（HTTP 传输）

Streamable HTTP 服务器可以先当普通 HTTP 服务调：

# 健康检查（若实现了自定义路由）
curl -i http://localhost:8000/health

# 直接 POST 一条 initialize（体验协议，也验证服务活着）
curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"curl","version":"0"}}}'

若服务无响应：查端口监听（netstat/lsof -i :8000）、防火墙、反向代理配置。生产环境的 HTTP 链路排错与普通微服务一致（第 13 章部署与第 15 章观测性会覆盖）。

10.6 测试金字塔

        ╱  E2E：真实客户端对话  ╲        少而关键（上线前手工清单）
       ╱  集成：ClientSession   ╲       中量：协议行为回归
      ╱  单元：工具函数直测        ╲     大量：纯逻辑、秒级、全覆盖

10.6.1 单元测试：绕过协议直接测函数

工具函数是普通 Python 函数，大部分逻辑直接测：

# test_tools.py
import pytest
from server import get_weather   # 直接 import 工具函数

def test_known_city():
    assert "晴" in get_weather("北京")

def test_unknown_city_is_friendly():
    out = get_weather("火星")
    assert "暂无" in out and "支持" in out   # 错误信息含恢复指引

10.6.2 集成测试：真实 ClientSession 走一遍协议

# test_integration.py
import sys
import pytest
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


@pytest.fixture
def anyio_backend():
    return "asyncio"


@pytest.mark.anyio
async def test_server_lifecycle_and_tools():
    params = StdioServerParameters(
        command=sys.executable, args=["server.py"]   # 用当前解释器，避免环境漂移
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()                      # 真实握手

            tools = await session.list_tools()
            names = {t.name for t in tools.tools}
            assert "get_weather" in names

            result = await session.call_tool(
                "get_weather", {"city": "北京"}
            )
            assert not result.isError
            assert "北京" in result.content[0].text

            bad = await session.call_tool(
                "get_weather", {"city": ""}
            )
            # 业务错误必须走 isError，而不是抛协议异常
            assert bad.isError

运行：pip install pytest anyio 后 pytest -v。集成测试覆盖了"单元测试看不见"的问题：装饰器注册、schema 生成、错误通道选择。

10.6.3 E2E 冒烟清单（上线前手工）

• [ ] 真实客户端能看到服务器与全部工具
• [ ] 每个工具用"正常值 + 1 个极端值"各调一次
• [ ] 长任务工具的进度显示正常
• [ ] 重启客户端后自动重连成功

10.7 调试思维小结

问题出现
  → Inspector 能复现吗？
      ├─ 能：服务器内部问题 → 日志(stderr) → 极端参数 → 单测复现 → 修复
      └─ 不能：宿主侧问题 → 宿主配置/日志 → 版本兼容 → 最小配置二分
  → 修复后：先单测，再集成测试，再 Inspector，最后真实客户端

10.8 小结

• 三层定位 + Inspector 隔离变量，是 MCP 调试的主轴。
• stdio 的 stdout 铁律：print 毁协议，日志走 stderr；用户可见说明用 ctx 日志。
• 12 条常见故障速查表覆盖绝大多数日常问题。
• 测试金字塔：函数直测为主，ClientSession 集成测试防协议回归，E2E 冒烟收尾。

动手练习

1. 复现与修复：完成第 4 章练习 4 的两种故障复现（路径错误、print 污染），对每种写下"症状 → 定位手段 → 修复 → 验证"四步记录。
2. 测试补齐：为 full_server.py 写测试：≥6 个单元测试 + 1 个完整集成测试（含一次故意失败调用验证 isError），接入 CI。
3. 排错演练：搭一个故意有 3 个 bug 的服务器（可在小组内互换互埋），限时 20 分钟按 10.4 速查表定位修复，并复盘"哪个信号最先指向根因"。
4. 日志升级：给练习 2 的服务器加上结构化日志（请求参数、耗时、结果码），用 Inspector 触发调用后在 stderr 日志中还原完整调用链。

至此进阶篇完成。 你已具备独立交付高质量服务器与 Skill 的能力。企业篇从 第 11 章 · 企业级架构设计 开始：把个人技能升级为组织能力。

📄 第 11 章 · 企业级架构设计 11-architecture.md✓ 标记已学

本章目标：为企业环境设计 MCP 能力接入体系——从个人工具到组织平台的演进路径、网关模式、服务器拆分原则与多租户方案，并能画出自己公司的目标架构图。

11.1 演进路径：四个阶段

企业引入 MCP 通常经历四个阶段，不要跳级：

阶段 1：个人探索          阶段 2：团队共享           阶段 3：平台化            阶段 4：生态化
─────────────          ─────────────            ─────────────           ─────────────
stdio + 本地服务器       少量 Streamable HTTP      MCP 网关 + 服务器目录      能力市场 + 自助接入
每人自配 mcpServers     部署在测试服、口口相传      统一认证、审计、配额        内部服务器集市、评分
风险：野配置蔓延         风险：权限裸奔            风险：过度中心化           治理自动化

11.2 目标架构：分层参考图

┌───────────────────────────────────────────────────────────────┐
│  用户层    Claude Desktop / ZCode / Cursor / 自研 Agent / IDE   │
└──────────────────────────┬────────────────────────────────────┘
                           │ MCP over Streamable HTTP（企业 SSO）
┌──────────────────────────▼────────────────────────────────────┐
│  网关层（MCP Gateway）—— 企业的"能力总闸"                          │
│  · 统一认证（SSO/OIDC → 下发短时 token）                          │
│  · 授权（按 用户×服务器×工具 的 RBAC/ABAC）                        │
│  · 路由与聚合（一个端点路由到 N 个后端服务器）                       │
│  · 审计日志、限流配额、密钥保管、注入防护（第 12 章）                  │
│  · 工具目录与动态发现（第 8 章模式 C）                              │
└──────┬───────────────┬───────────────┬───────────────┬────────┘
       │               │               │               │
┌──────▼─────┐  ┌──────▼─────┐  ┌──────▼─────┐  ┌──────▼─────┐
│ kb-server  │  │ ops-server │  │ fin-server │  │ hr-server  │
│ 知识库检索   │  │ 运维工具     │  │ 财务数据     │  │ 人事流程     │
└──────┬─────┘  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘
       │               │               │               │
   ES/向量库        K8s/监控          数仓/ERP          OA 系统

分层职责铁律：

• 宿主层不碰企业数据（凭据不下发到个人电脑）；
• 网关层不实现业务逻辑（只做横切关注点）；
• 服务器层不实现横切关注点（认证、限流交给网关，自己只管业务域）。

这条边界让"新增一个业务服务器"变成纯业务开发工作——注册进网关即上线，这是平台化的核心价值。

11.3 两种拓扑：直连 vs 网关

务实建议：两者并存。本地文件/Git 等无敏感数据的工具走直连 stdio；一切涉企业数据与写操作的能力必须经网关。网关可用开源方案（如 Higress 的 MCP 能力、Kong/Azure APIM 等具备 MCP 转发的网关，或社区 MCP Gateway 项目），也可基于标准反向代理 + 轻量鉴权服务自研——先满足认证/审计/工具目录三个最小集，再逐步增强。

11.4 服务器拆分原则

按业务域 + 数据敏感级双轴拆分：

             低敏感                      高敏感
 业务域 A  │  kb-server（公开文档）      │  fin-server（财务，独立部署+白名单）
 业务域 B  │  ops-server（只读监控）     │  ops-admin（高危写操作，独立审批）

• 一个服务器一个 owner（团队），独立仓库、独立发布节奏（第 15 章）；
• 敏感级决定部署位置：高敏感服务器部署在独立网段/集群，网关到它的路由加额外鉴权；
• 高危操作单独成服务器（如 ops-admin），便于整体下线、单独审批、单独审计——比在一个大服务器里"挑工具"管控简单得多；
• 拒绝"万能服务器"：跨域能力通过聚合在网关完成，而不是把代码塞进一个服务器。

11.5 多租户与上下文传递

网关模式下要回答："同一个 kb-server，怎么知道是谁、在什么权限范围内调用？"

两种模型：

1. 服务器信任模型（服务账号）：网关持服务账号调服务器，服务器只区分"网关来的请求"，用户身份放请求头/元数据里传递（如 X-On-Behalf-Of）。实现简单，适合内部低敏场景；
2. 端到端身份模型（令牌交换）：用户先向企业 IdP 取自己的 token（带 scope），网关校验后转发，服务器独立验证 token 并按其 scope 裁剪数据。严格、可审计，适合敏感域——这是 OAuth 2.1 + Resource Indicator 规范设计的场景（第 12 章展开）。

服务器代码上的体现：工具实现里基于调用者身份过滤数据，而不是返回"网关能看到的一切"：

@mcp.tool(annotations={"readOnlyHint": True})
async def search_tickets(query: str, ctx: Context) -> str:
    """搜索工单。仅返回调用者有权访问的部门的数据。"""
    user = get_caller_identity(ctx)          # 从传输层/头解析身份
    allowed = await acl.departments_of(user)  # 数据权限在业务内生效
    return await tickets.search(query, dept_ids=allowed)

11.6 与 Agent 编排体系的关系

企业通常同时存在：IDE 内的编码 Agent、客服机器人、数据流水线里的自主任务。MCP 的位置是能力层标准接口——所有形态的 Agent 都通过同一批服务器/同一个网关取能力：

 ┌─ IDE Agent ──────┐
 ├─ 客服机器人 ──────┤    同一批 MCP 服务器（不同挂载子集 + 不同权限档）
 ├─ 数据流水线 Job ──┤    （流水线用服务账号 token，人来用用户 token）
 └─ 定时巡检任务 ────┘

配套地，第 6 章的 Skill 分层也按主体划分：个人 Skill（自己习惯）、团队 Skill（随仓库）、企业 Skill（统一分发、含合规约束）。

11.7 技术选型速查

11.8 演进路线示例（可直接套用的 90 天计划）

11.9 小结

• 四阶段演进：探索 → 共享 → 平台 → 生态；由真实痛点触发升级，不跳级。
• 三层职责铁律：宿主不碰数据、网关不管业务、服务器不管横切。
• 拆分双轴：业务域 × 敏感级；高危操作独立成服务器。
• 多租户两种模型：服务账号信任 vs 端到端令牌；数据权限必须在服务器业务内生效。
• MCP 是全企业 Agent 形态共享的能力层标准接口。

动手练习

1. 现状评估：判断你的组织处于哪个阶段，找出触发下一阶段的两个具体信号。
2. 架构草图：为你所在公司画 11.2 风格的目标架构图（至少 3 个业务域服务器 + 网关），标注每个服务器的敏感级与 owner 团队。
3. 拆分决策：以下能力如何拆分与部署？写出服务器清单与理由：文档检索、数据库只读查询、生产发布操作、HR 假期查询。
4. 深思考：如果只有你一个人维护网关，第 2 阶段的"权限裸奔"问题你会优先解决哪三件事？（提示：认证、审计、高危操作隔离——对应第 12 章内容）

下一章：第 12 章 · 安全与权限管控 —— 企业落地中最硬核也最容易被低估的一章。

📄 第 12 章 · 安全与权限管控 12-security.md✓ 标记已学

本章目标：建立 MCP 特有的威胁模型；掌握 OAuth 2.1 授权、工具级权限、注入防护、审计与密钥管理的落地做法；能为自己负责的服务器产出一份安全基线。

12.1 为什么 MCP 的安全面不同于传统 API

传统 API 安全的三件套（认证、鉴权、输入校验）在 MCP 里全部适用，但 MCP 多了一个独特的风险源：协议的"调用方"是一个可以被文本操纵的概率系统。

传统调用链：用户代码 → 你的 API          （调用方逻辑是确定性的）
MCP 调用链：用户意图 → 模型推理 → 工具调用   （中间有一步可被注入操纵）

由此衍生出 MCP 特有的攻击类别。理解它们是设计防线的前提。

12.2 威胁模型：五类核心攻击

记住结构性结论：模型层防线（提示词约束）永远不是可靠边界。安全边界必须落在确定性组件上：网关、服务器代码、网络与权限体系。Skill 里写的"禁止项"是体验优化，不是安全控制。

12.3 认证与授权：OAuth 2.1 正确姿势

Streamable HTTP 服务器在规范中是 OAuth 2.1 资源服务器。企业落地架构：

 宿主/Agent ──①用户登录──▶ 企业 IdP（OIDC：Okta/Entra/Keycloak…）
     │◀──────────②用户级 access token（短时、含 scope/aud）────────┘
     │ ③带 token 调用
     ▼
 MCP 网关 ──④校验 token：签名、过期、受众(aud=本网关)──▶ 放行
     │ ⑤（可选）令牌交换/收窄 scope 后转发
     ▼
 MCP 服务器 ──⑥再次校验 aud + scope，按 scope 裁剪数据──▶ 下游 API

关键实践：

1. 受众校验（audience）不可省：为 MCP 体系签发的 token 必须绑定本资源（RFC 8707 Resource Indicator 思路），防止"别处偷来的 token 到处用"；
2. scope 粒度到能力域：tickets:read / tickets:write / ops:admin，服务器按 scope 拒绝，不按"登录了没有"；
3. 用户身份传递（第 11.5 节两种模型）：敏感域必须端到端身份——服务器独立验 token，数据权限在业务内生效；
4. 本地 stdio 服务器：无 OAuth，等价于"以你的全部本机权限运行"——所以第 11 章建议：涉敏能力走网关，个人电脑只挂无害的本地工具；
5. 密钥保管：服务器自身调下游 API 的凭据，从环境变量或密钥管理服务（Vault/KMS/Secret Manager）读取；源码、示例、测试、配置文件、Skill 里一律不出现真实凭据字面量，CI 加密钥扫描兜底。

12.4 权限模型：从粗到细的四层

第 1 层  网络层   服务器部署位置、网段隔离、出口白名单
第 2 层  服务器层 scope 校验、数据行级过滤（11.5）
第 3 层  工具层    用户×工具 的允许表；高危工具强制审批
第 4 层  会话层    宿主的工具确认 UI、dry-run 默认（第 8 章）

工具层允许表（网关或服务器均可实现）示例：

配套规则：

• 默认拒绝（deny by default）：未列入即拒绝；
• 读宽写严：只读工具可放宽，写工具逐个评估；
• 写操作三要素：审批（人或策略）+ dry-run + 幂等键（第 8 章）；
• 允许表随服务器注册由 owner 声明，安全团队复核——进第 15 章的注册流程。

12.5 注入防护：纵深防御清单

无法根治注入（文本进上下文就有风险），目标是提高攻击成本、限制爆炸半径：

服务器侧（你的责任区）

1. 工具描述只写功能，不写指令：描述里出现"必须先…再…"类长指令本身就是坏味道（也是投毒检测的特征）；
2. 输出消毒：工具返回的内容视为不可信文本——返回给模型的拼装文本里剔除控制性语句模式（如"ignore previous"），长文档检索结果优先走 Resources 或附件而非拼进回复；
3. 参数校验从严：枚举、正则、长度上限——模型被骗时产生的畸形参数应在这里被挡下；
4. 出口白名单：任何"服务器替用户发起网络请求"的工具（抓取网页、发消息），目标地址走白名单，杜绝"把数据发到攻击者域名"的外泄通道。

宿主与治理侧（平台的责任区）

5. 服务器准入：只装可信来源的服务器；第三方服务器先进沙箱评估（第 11 章注册流程）；
6. 版本锁定：stdio 服务器锁版本（锁 mcpServers 配置 + 锁依赖），自动更新= rug pull 打开大门；HTTP 服务器由平台统一升级灰度；
7. 组合监控：审计层对"读后即写"的调用序列告警（读客户数据 → 出网请求），这是外泄链路的指纹；
8. 敏感数据分级：最高敏数据（密钥、全量 PII）不进模型上下文——不给攻击面留素材；服务器在数据出库前先脱敏（手机号、身份证掩码）。

12.6 审计与追溯

企业最低要求：任何工具调用都能回答"谁、何时、调了什么工具、传了什么参数、动了什么数据、结果如何"。

审计事件 schema（网关统一产出，示例）：

{
  "ts": "2026-09-29T10:21:33+08:00",
  "actor": { "user_id": "u10086", "dept": "ops", "auth_via": "oidc" },
  "agent": { "host": "zcode", "session_id": "s-9f2e" },
  "call": {
    "server": "ops-server", "tool": "restart_service",
    "arguments": { "service": "payment-api", "env": "prod" },
    "approved_by": "u20001",
    "result": "ok", "latency_ms": 812
  },
  "trace_id": "4bf92f3577b34da6"
}

落地要点：

• 审计日志只增不改，独立存储、独立权限，保留期满足合规（如等保要求）；
• trace_id 贯穿网关→服务器→下游（OpenTelemetry 传播，第 15 章观测性）；
• 对高危工具（写/删/发外部）设置独立告警通道，值班可实时看到；
• 定期复盘审计数据本身就是治理输入：哪些工具没人用？哪些总被拒绝？（第 15 章）

12.7 服务器安全基线（Checklist）

发布一个生产 MCP 服务器前逐项过：

• [ ] 认证：HTTP 传输已接入 OAuth 2.1/企业 IdP，aud 校验开启；stdio 服务器只处理本机无害任务
• [ ] 授权：scope 校验 + 用户级数据过滤；默认拒绝
• [ ] 输入：参数枚举/长度/格式校验完备；无 shell 拼接（确需执行命令用参数数组形式）
• [ ] 输出：返回内容消毒；大结果截断；PII 脱敏
• [ ] 副作用：写工具带 dry-run/确认/幂等键，注解如实标注
• [ ] 凭据：全部来自环境变量/密钥服务；代码与示例零凭据字面量
• [ ] 依赖：锁定版本；CI 跑漏洞扫描（如 pip-audit）
• [ ] 网络：最小出网白名单；敏感服务器在隔离网段
• [ ] 日志：审计事件齐全；trace_id 打通；日志无敏感明文
• [ ] 降级：下游故障时的行为明确（快速失败，不 hang）

12.8 小结

• MCP 独有风险源于"调用方是可被文本操纵的模型"；提示词不是安全边界。
• 五类核心攻击：提示注入、工具投毒、糊涂代理人、劣化服务器、数据外泄。
• OAuth 2.1 + audience 校验 + scope 到能力域 + 端到端身份（敏感域）。
• 四层权限（网络/服务器/工具/会话），默认拒绝、读宽写严、写操作三要素。
• 注入防护是纵深防御：消毒、白名单、版本锁定、组合监控、高敏数据不进上下文。
• 审计六要素 + trace 贯穿，让每一次调用可追溯。

动手练习

1. 威胁建模：选你公司一个规划中的服务器（如 HR 查询），按 12.2 五类攻击逐一推演"这个服务器上该攻击长什么样、防线在哪一层"，输出威胁模型表。
2. scope 落地：给 full_server.py 加 scope 校验中间件：从请求头取 X-Scope（模拟），实现 tickets:read/tickets:write 两档，写测试覆盖越权路径。
3. 注入演练：构造一份含注入句子的"工单正文"，让接入后的模型总结它；分别在"无防护"与"服务器输出消毒 + 工具白名单"两种配置下观察差异，记录防线效果。
4. 审计落地：设计你们网关的审计事件 schema（对照 12.6），并用 10 分钟向一个不熟悉 MCP 的同事讲清楚"为什么这条链路能追责"。

下一章：第 13 章 · 部署方案 —— 把服务器从本机送到生产：四种形态、容器化、K8s 与发布策略。

📄 第 13 章 · 部署方案 13-deployment.md✓ 标记已学

本章目标：为不同规模与安全要求选择部署形态；掌握 Docker 容器化、K8s 清单、健康检查与优雅停机、Serverless 取舍、配置密钥注入与渐进发布。

13.1 四种部署形态

选择逻辑：默认 C（企业平台）；个人/低敏走 A；过渡期或无 K8s 的团队走 B；稀疏调用的查询类服务器可评估 D。

13.2 传输切换：从 stdio 到 Streamable HTTP

同一份业务代码，传输由配置决定（第 2 章"协议与场景解耦"的变现）：

# server.py —— 通过环境变量切换传输，部署形态无关
import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("issues", host="0.0.0.0", port=int(os.getenv("PORT", "8000")))

# ... 工具定义（与本地版完全一致）...

if __name__ == "__main__":
    transport = os.getenv("MCP_TRANSPORT", "stdio")
    mcp.run(transport=transport)   # "stdio" | "streamable-http"

本地 MCP_TRANSPORT=stdio python server.py；容器里设 MCP_TRANSPORT=streamable-http。

13.3 容器化（形态 B/C 的地基）

Dockerfile（多阶段构建，非 root 运行）：

FROM python:3.12-slim AS base
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1

FROM base AS deps
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM base AS runtime
WORKDIR /app
COPY --from=deps /usr/local/lib/python3.12/site-packages \
                 /usr/local/lib/python3.12/site-packages
COPY --from=deps /usr/local/bin /usr/local/bin
COPY server.py .
# 容器内禁止 root
RUN useradd -r mcp && chown -R mcp /app
USER mcp

ENV MCP_TRANSPORT=streamable-http PORT=8000
EXPOSE 8000
CMD ["python", "server.py"]

requirements.txt：锁定版本（mcp==<x.y.z>、httpx==<x.y.z>…），保证可复现构建（供应链要求见第 12.7 节）。

本地验证：

docker build -t issues-mcp:0.3.0 .
docker run --rm -p 8000:8000 \
  -e ISSUE_API_TOKEN="$ISSUE_API_TOKEN" \      # 密钥经环境变量注入，绝不写进镜像
  issues-mcp:0.3.0

# 冒烟：用第 10 章的 curl initialize 打一次 /mcp
curl -s -X POST http://localhost:8000/mcp -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

13.4 K8s 部署（形态 C）

最小可用清单（生产请叠加网关、HPA、PDB 等）：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: issues-mcp
  labels: { app: issues-mcp, owner: platform-team }
spec:
  replicas: 3
  selector: { matchLabels: { app: issues-mcp } }
  template:
    metadata:
      labels: { app: issues-mcp }
    spec:
      containers:
        - name: issues-mcp
          image: registry.internal/issues-mcp:0.3.0   # 固定 tag，禁止 latest
          ports: [{ containerPort: 8000 }]
          env:
            - name: MCP_TRANSPORT
              value: streamable-http
            - name: ISSUE_API_TOKEN                    # 密钥来自 Secret，不落明文
              valueFrom:
                secretKeyRef: { name: issues-mcp-secrets, key: issue-api-token }
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits:   { cpu: "1",  memory: 512Mi }
          readinessProbe:                              # 就绪：能接受 MCP 请求
            httpGet: { path: /health, port: 8000 }
            initialDelaySeconds: 3
            periodSeconds: 10
          livenessProbe:                               # 存活：进程未僵死
            httpGet: { path: /health, port: 8000 }
            initialDelaySeconds: 15
            periodSeconds: 20
          lifecycle:
            preStop:                                   # 优雅停机：先摘流再退出
              exec: { command: ["sleep", "5"] }
      terminationGracePeriodSeconds: 30
---
apiVersion: v1
kind: Service
metadata: { name: issues-mcp }
spec:
  selector: { app: issues-mcp }
  ports: [{ port: 80, targetPort: 8000 }]

健康检查端点（FastMCP 自定义路由示例）：

from mcp.server.fastmcp.utilities.types import ...  # 若版本无便捷封装，用 ASGI 层实现

# 通用做法：包一层 FastAPI/Starlette 挂载 /health，
# 或使用 SDK 提供的自定义路由能力（不同版本 API 略异，查所用版本文档）：
# @mcp.custom_route("/health", methods=["GET"])
# async def health(request):
#     return JSONResponse({"status": "ok", "version": APP_VERSION})

说明：不同 SDK 版本对自定义 HTTP 路由的支持方式有差异。核心要求只有一条：探针端点必须不依赖 MCP 会话，只反映"进程活着 + 依赖可达（可选）"。实现方式以所用 SDK 文档为准。

优雅停机的含义：SIGTERM 到达后——停止接新请求 → 等在途 MCP 请求完成（Streamable HTTP 的流要正常收尾）→ 释放连接池 → 退出。上面的 preStop sleep + 宽限期配置就是给这条路径留时间。客户端侧配合：宿主收到断连会自动重连（会话重建）。

13.5 Serverless（形态 D）取舍

适合：调用稀疏（如每天数百次）、无长任务、无会话粘性的只读查询服务器。

• 技术路径：把 MCP 端点做成函数的 HTTP 处理器（各云厂商均有 MCP 适配示例），或经 API 网关转发到容器实例；
• 三个硬约束：冷启动延迟（首次调用 +1~3s，影响对话体验）；无长连接（流式能力受限）；执行时长上限（分钟级长任务不可行）；
• 结论：查询密集型共享服务器请用形态 C；Serverless 是特定场景的优化，不是默认答案。

13.6 配置与密钥注入

铁律（与第 12.7 呼应）：镜像与代码库零凭据；Secret 轮转周期化；服务器日志严禁打印环境变量内容。

13.7 发布策略：渐进放量

新版本 v1.3.0
  ① CI：单测 + 集成测试 + 镜像扫描（第 15 章流水线）
  ② 部署 staging：第 10 章 E2E 冒烟清单跑一遍
  ③ 金丝雀：1/10 流量 → 观察 P95 延迟、错误率、工具调用成功率（第 14/15 章指标）
  ④ 全量：灰度逐级放大；任意指标劣化即回滚（旧镜像秒级切回）
  ⑤ 破坏性变更（改工具签名/删除工具）：走第 15 章弃用流程，双版本并存过渡

MCP 特有注意点：

• 工具清单变更对线上模型是即时生效的（listChanged 通知或重连后刷新）——新增工具风险低，改描述/删工具会影响存量对话中的调用行为，按破坏性变更对待；
• 客户端可能长驻会话，发布后留意"旧会话 + 新服务器"的组合行为；
• 网关层保留按服务器回滚能力（路由指向旧版本 Deployment），回滚时间 < 1 分钟。

13.8 部署检查清单

• [ ] 传输切换经环境变量控制；本地/容器行为一致
• [ ] 镜像非 root、依赖锁版本、扫描通过
• [ ] 探针端点独立于 MCP 会话；优雅停机验证过（发布新版本时观察无请求失败）
• [ ] 密钥全部经 Secret 注入，审计代码与镜像无凭据
• [ ] 副本数 ≥2、跨可用区；有 HPA 或容量评估依据
• [ ] 金丝雀指标面板就绪；回滚预案演练过
• [ ] 接入第 11 章网关：路由、权限表、审计打通

13.9 小结

• 四形态按"规模×敏感级"选择，企业默认 K8s 常驻 + 网关。
• 传输切换一行环境变量——业务代码与部署形态解耦。
• 容器化四要点：锁版本、非 root、密钥外部注入、探针独立。
• 发布走金丝雀；工具描述/清单变更按破坏性变更管理。

动手练习

1. 容器化：把 http_server.py 构建为镜像并在本机跑通（含 curl initialize 冒烟），再故意断掉下游 API，观察工具返回的错误信息是否友好（第 7 章错误设计的回响）。
2. K8s 实操（有集群则做，无集群用 kind/minikube）：部署 3 副本，验证探针、滚动更新（改个 tag 触发）、删除 pod 观察自愈；用 kubectl rollout undo 演练回滚。
3. 优雅停机验证：发布新版本期间从客户端持续发起工具调用，统计失败数；调大 preStop 与宽限期对比效果。
4. Serverless 评估：挑一个你的查询类服务器，按 13.5 的三个硬约束逐项评估是否适合上函数计算，写出结论与理由。

下一章：第 14 章 · 性能优化 —— 上线只是开始：延迟、成本、吞吐的系统性优化。

📄 第 14 章 · 性能优化 14-performance.md✓ 标记已学

本章目标：建立 MCP 场景的延迟与成本模型；掌握缓存、连接管理、上下文成本控制三大优化方向；会用指标化方法定位瓶颈，而不是凭感觉调参。

14.1 先建模：一次工具调用的延迟构成

用户体感 = 模型推理延迟 + 工具调用延迟。后者可分解为：

工具调用总延迟
├── T1  协议与序列化          通常 <5ms，基本可忽略
├── T2  服务器内部处理        你的代码：校验、组装、逻辑
├── T3  下游调用              ★ 大头：HTTP API / DB / 检索引擎
└── T4  结果回传与模型再推理    与结果大小正相关（token 越多越慢越贵）

定位口诀：先量 T3，再砍 T4，最后抠 T2。 绝大多数慢的 MCP 工具，慢在下游没做缓存/连接复用，或者返回了模型根本用不到的巨大文本。

14.2 优化 T3：下游调用

14.2.1 连接复用（第一优先级）

每次工具调用都新建 TCP/TLS 连接，是最常见的隐性延迟源。所有 HTTP 客户端进 lifespan（第 7 章）：

@asynccontextmanager
async def app_lifespan(server):
    async with httpx.AsyncClient(
        base_url=os.environ["ISSUE_API_BASE"],
        timeout=httpx.Timeout(5.0, connect=2.0),   # 显式超时是可靠性的前提
        limits=httpx.Limits(max_connections=50,
                            max_keepalive_connections=20),
    ) as client:
        yield AppContext(http=client)

数据库同理：连接池常驻，池大小 ≈ 并发调用峰值 ÷ 单请求耗时占比（第 13 章 K8s 副本数 × 池大小要一起算）。

14.2.2 缓存分层

from cachetools import TTLCache
_cache: TTLCache = TTLCache(maxsize=1024, ttl=300)

@mcp.tool(annotations={"readOnlyHint": True})
async def get_project(proj_id: str, ctx: Context) -> str:
    """查询项目详情。数据延迟约 5 分钟（缓存）。"""
    key = f"proj:{proj_id}"
    if key in _cache:                       # 命中：微秒级
        return _cache[key]
    raw = await fetch_downstream(proj_id)   # 未命中：真实调用
    out = render_summary(raw)
    _cache[key] = out
    return out

缓存三纪律：

1. 在工具描述里如实声明数据延迟（"约 5 分钟"），模型会向用户转述，避免误导；
2. 写操作后主动失效相关缓存键，防止"改了还显示旧值"被模型复述；
3. 只读工具才放心缓存；写工具绝不缓存。

14.2.3 并行与批量

• 模型一次可发起并行多工具调用（宿主支持时），设计工具时避免"必须按序调用"的隐藏顺序依赖；
• 提供批量参数减少往返：get_issues(ids: list[str]) 优于让模型循环调用 20 次 get_issue(id)——每省一次往返，就是省一整轮模型推理。

14.3 优化 T4：上下文成本（最容易被忽视的成本项）

工具定义与结果都要消耗 token；token = 延迟 + 费用。三个抓手：

14.3.1 控制工具定义开销

• 挂载的服务器/工具数量就是常驻成本——第 8 章的工具收敛策略直接就是性能优化；
• description 够用即可，不要写成论文；参数描述一句到位。

14.3.2 控制返回体积

第 8 章 8.3 的三层防线（限量分页 / 截断引用 / 浏览详情分离）在这个视角下全部是性能优化。量化感受：

返回 500 token 的摘要     ≈ 0.4s 额外推理 + 微量费用
返回 50,000 token 的原文  ≈ 数十秒推理 + 可观费用 + 挤掉其他上下文

14.3.3 善用宿主的上下文控制

主流宿主支持给工具结果标记"不随对话历史长期保留"（类似 cache/ephemeral 语义）。日志、大段参考文档类结果优先走这种通道，别让它们永久占据每轮对话的上下文。

14.4 优化 T2：服务器自身

• 异步优先：I/O 型工具一律 async，一个慢下游不阻塞其他请求（FastMCP 基于 asyncio）；
• CPU 型任务别挡事件循环：重解析/重计算用 asyncio.to_thread 或进程池；
• 边界超时：对下游的每个调用设超时与熔断，"快速失败"好过"挂 30 秒"（第 8 章代理模式）。

14.5 长任务的性能与体验

分钟级任务的正确姿势（结合第 7/2 章）：

立即返回 task_id  →  check_status(task_id) 轮询/订阅进度
                  →  完成后返回结果引用（文件/资源 URI）

• 状态外置到 Redis/DB（第 8.5 节），副本重启任务不丢；
• 关注规范的 Tasks 能力（2025-11-25 起）：把"启动/查询/取消/恢复"标准化，减少自研轮子；
• UX 细节：进度通知（report_progress）让用户看到"活着"，比真实快慢更影响体感。

14.6 指标与压测

核心指标面板（与第 15 章观测性衔接）：

压测方法：绕开模型，直接对 MCP 端点压（脚本循环 tools/call，或用 Inspector 批量调用），变量只留服务器本身；按 2×/5×/10× 预期负载找拐点。不要用"真实对话"当压测手段——变量不受控。

性能预算示例（贴在服务器 README 里）：

search_issues：P95 < 800ms（缓存命中 <50ms），返回 ≤ 2k token
create_ticket：P95 < 1.5s，无缓存，含幂等去重

14.7 优化优先级决策树

用户抱怨慢/贵
 ├─ 模型推理就慢（无工具调用也慢）→ 与 MCP 无关，查模型/上下文长度
 ├─ 工具返回巨大 → 14.3 收敛结果（性价比最高，先做）
 ├─ 下游调用慢 → 14.2：连接复用 → 缓存 → 批量/并行
 ├─ 服务器 CPU 打满 → 14.4 异步/线程化 + 扩副本
 └─ 长任务拖体验 → 14.5 异步化 + 进度通知

14.8 小结

• 延迟四段：T3（下游）与 T4（上下文）是大头；口诀"先量 T3，再砍 T4，后抠 T2"。
• 连接复用是第一优先级；缓存三层、只读可缓存、描述里声明数据延迟。
• token 成本优化 = 工具收敛 + 结果收敛 + 临时上下文通道。
• 长任务异步化 + 状态外置 + 进度通知；规范 Tasks 值得跟进。
• 一切优化以指标驱动：P95、错误率、命中率、token 预算。

动手练习

1. 量化基线：给 full_server.py 每个工具加耗时日志（含 T3 细分），跑 50 次调用，算出 P50/P95，写出你的第一份性能预算表。
2. 缓存落地：为最热的查询工具加 TTLCache（练习 1 数据证明值得缓存的那个），对比命中率与 P95 变化；再验证写操作后的缓存失效逻辑。
3. token 审计：取一次真实会话，统计每个工具定义与每条工具结果的 token 占用（多数宿主可查用量），找出前 3 大"上下文吞金兽"并按 14.3 收敛。
4. 压测：用脚本对 Streamable HTTP 服务器压 search_issues（1→50 并发阶梯），记录 P95 与错误率拐点，据此给出 K8s 副本数与连接池参数建议。

下一章：第 15 章 · 可维护性与治理 —— 让 20 个团队、50 个服务器还能像一个人维护的那样运转。

📄 第 15 章 · 可维护性与治理 15-maintainability-governance.md✓ 标记已学

本章目标：为多团队、多服务器的 MCP 体系建立工程治理：版本与兼容策略、CI/CD 流水线、可观测性、注册目录、评估回归与团队协作规范——目标不是"写得多"，而是"多年后还改得动、查得到、信得过"。

15.1 治理的对象：一个服务器的完整生命周期

提出 → 注册评审 → 开发(CI/CD) → 发布(灰度) → 运行(观测) → 迭代/弃用 → 下线归档
        ▲                                                            │
        └────────────── 数据反哺（调用统计、事故复盘）◀──────────────────┘

治理 = 让这个循环里每个环节都有明确的责任人、标准与工具。

15.2 版本管理与兼容

15.2.1 服务器版本：语义化 + 双通道

• 服务器版本遵循 SemVer：改参数 schema/删除工具/变更语义 = 破坏性（major）；加工具/加可选参数 = minor；修 bug = patch；
• 版本号出现在握手 serverInfo 与镜像 tag 中，一一对应（第 13 章）；
• 协议版本（protocolVersion）由 SDK 自动协商，团队无需手工管理，但升级 SDK 时要看 changelog。

15.2.2 破坏性变更的黄金流程

工具的消费者是模型 + 存量会话，变更比普通 API 更敏感：

① 弃用标记：description 末尾加 "（将于 vX.Y 弃用，请改用 new_tool）"
② 双版本并存 ≥2 周：旧工具保留但行为降级为"引导迁移"
   （调用旧工具返回迁移提示，不真正执行）
③ 监控旧工具调用量 → 归零或低于阈值
④ major 版本移除；changelog 记录迁移指南

为什么要两步走而不是直接删：客户端会话可能存活数天；且"工具突然消失"会让依赖它的 Skill 全体失效。Skill 对工具的引用也要纳入兼容性检查——删工具前全库检索 Skill 引用。

15.3 CI/CD 流水线模板

每个服务器仓库的标准流水线（GitHub Actions 示例，GitLab CI 同理）：

name: ci
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12", cache: pip }
      - run: pip install -r requirements.txt -r requirements-dev.txt
      - name: Lint & 类型检查
        run: |
          ruff check .
          ruff format --check .
          mypy .
      - name: 安全扫描
        run: |
          pip-audit                     # 依赖漏洞
          # 凭据泄露扫描（接入公司扫描器或 gitleaks）
          gitleaks detect --no-git -v
      - name: 测试
        run: pytest -v                  # 第 10 章：单元 + 集成
      - name: 协议冒烟
        run: |
          timeout 10 python server.py & # stdio 起服
          sleep 2                       # + 基本握手脚本断言，防"起不来"合入主干

  build:
    needs: quality
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 构建并推送镜像（tag = 版本号）
        run: echo "docker build/push — 按公司流水线实现"
      - name: 部署 staging
        run: echo "触发第 13 章的金丝雀流程"

流水线承载的门禁（可合入 = 质量下限）：

1. 静态检查 + 类型检查通过；
2. 测试全绿（含一次真实协议集成测试）；
3. 依赖无已知漏洞、无凭据泄露（第 12 章供应链要求）；
4. 工具 schema 变更被检测：PR 里 diff 出 schema 变化时自动打标 schema-change，触发对应评审级别（新增=owner 审；破坏=major 流程）。

15.4 可观测性：三支柱映射到 MCP

服务器侧最小实现（代码内即可完成，无需重型平台）：

import time, uuid, logging
log = logging.getLogger("issues")

@mcp.tool(annotations={"readOnlyHint": True})
async def search_issues(query: str, ctx: Context) -> str:
    """按关键词搜索工单。"""
    rid = uuid.uuid4().hex[:8]
    t0 = time.perf_counter()
    try:
        out = await _do_search(query)
        log.info("tool=search_issues rid=%s q=%r ms=%.0f ok", rid, query,
                 (time.perf_counter() - t0) * 1000)
        return out
    except Exception as e:
        log.error("tool=search_issues rid=%s q=%r err=%s", rid, query, e)
        raise

进阶：接入公司 APM/OTel SDK，把耗时直方图与 trace 上报（第 14 章"先量 T3"依赖这里的埋点）。

告警三基线：错误率突增、P95 劣化超预算、副本来调用量异常（安全联动，第 12.6 节）。

15.5 注册目录：让服务器"可被发现、可被信任"

第 8 章解决了"服务器内工具太多"，本节解决"企业内服务器太多"。内部目录最小字段（可先做成一个 Git 仓库的 registry.yaml，长成服务）：

- name: issues-mcp
  owner: platform-team            # 唯一责任人，接警就是他
  repo: git@internal:platform/issues-mcp.git
  endpoint: https://mcp-gateway/issues   # 或 stdio 安装说明
  version: 1.4.2
  sensitivity: normal             # low / normal / high（第 11 章双轴）
  scopes: [tickets:read, tickets:write]
  sla: { p95_ms: 1500, availability: "99.5%" }
  health: /health
  docs: https://wiki/issues-mcp
  review_status: approved         # 注册评审结论（12.5 准入）
  last_audit: 2026-09-10

注册评审 Checklist（对应第 12.7 安全基线 + 第 13.8 部署清单）：工具清单与用途说明、威胁模型表、权限声明、性能预算、回滚预案。通过后进目录、进网关路由、进审计白名单——三处同步。

官方生态方向：MCP 官方 Registry 已推行 server.json 描述格式（预览阶段），企业内目录建议保持字段兼容，未来可平滑对接。

15.6 评估与回归：防"改好工具，用坏效果"

工具描述/参数/Skill 的变更，影响的不是测试通过率，而是模型的调用正确率。补一层数据驱动的回归：

1. Eval 样本集：每个服务器维护 20–50 条"用户说法 → 期望调用的工具与参数"样本（第 9.4 节 Skill 触发样本的同族实践）；
2. 变更触发 eval：PR 修改了 description/schema/Skill 时，CI 提示跑 eval（人工或接入 LLM 评审流水线）；
3. 线上反哺：从审计日志抽样真实调用，人工标注"调用是否合理"，月度回顾——工具描述的持续改进来自真实分布，不是作者想象。

15.7 团队协作规范（一页纸版）

• 责任：每个服务器一个 owner 团队；网关与目录由平台团队运营；Skill 归属随其所在仓库。
• 评审：PR 至少一人审；schema 变更按 15.3 门禁升级；高危工具上线需安全团队签字。
• 文档：README 必含——工具清单表（第 7 章）、权限与 scope、性能预算（第 14 章）、runbook（常见故障与处置，链接第 10 章速查表）。
• 节奏：每双周治理例会看四个数字：服务器总数、告警数、eval 通过率、审计异常数。
• 变更通知：服务器 breaking change 提前一周在目录公告；订阅制（依赖方登记）。

15.8 治理成熟度自评

15.9 小结

• 版本双通道 + 弃用两步走：工具变更的消费者是模型与存量会话。
• CI 门禁四件套：静态、测试、供应链扫描、schema 变更检测。
• 观测三支柱在 MCP 的映射：按工具维度指标、结构化日志、贯穿 trace。
• 注册目录让服务器可发现、可信任；评审三同步（目录/网关/审计）。
• Eval 回归防"改好工具用坏效果"；线上调用分布反哺描述优化。
• 治理成熟度四级，用自评找差距，一年内到 L3 是务实目标。

动手练习

1. 流水线落地：为 full_server.py 配置完整的 GitHub Actions（或公司 CI），本地验证门禁四件套全部可拦截一次故意劣化的 PR（注入假凭据 → gitleaks 拦截）。
2. 目录起草：用 15.5 的 YAML 为你负责的所有服务器建档，找出"说不出 owner 的服务器"——它们就是治理的第一批风险。
3. Eval 建设：为你最常用服务器写 20 条 eval 样本，跑一次基线；然后故意改坏一条 description 再跑，体会回归网的价值。
4. 弃用演练：把某个旧工具按 15.2.2 流程模拟一遍（标记→引导→观察→移除），输出一份迁移公告文案。

下一章：第 16 章 · 综合实战：企业知识库智能助手 —— 把前 15 章全部串成一个可上线的完整案例。

📄 第 16 章 · 综合实战：企业知识库智能助手 16-case-study.md✓ 标记已学

本章目标：把前 15 章的能力串成一条完整生产线——从需求、架构、代码、权限、部署到上线检查。读者可将其作为模板，替换业务域后落地自己的第一个企业级 MCP + Skill 项目。

16.1 业务背景与需求

背景：某 800 人科技公司，员工日常高频咨询散落在四个系统：文档库（Confluence 类）、HR 系统（假期/报销政策）、IT 工单系统、代码仓库。现状痛点：

• 员工找答案平均要翻 3 个系统，重复提问占用支持团队 30% 工时；
• 已试用过"把文档全灌给模型"的方案：更新滞后、敏感文档越权可见、无法执行操作（如提单）；
• 管理层要求：答案可溯源、权限跟随个人、全程可审计。

目标方案："KB 助手"——全员可用，具备：检索并引用内部知识库；查询个人 HR 数据；创建/查询 IT 工单；按规范输出标准化产物（如值班交接、故障复盘初稿）。

需求 → 能力映射（第 6 章决策框架实战）：

16.2 架构设计（第 11 章模板落地）

┌──────────────────────────────────────────────────────────────┐
│ 用户层：全员（浏览器内 Agent / 桌面客户端）                        │
└───────────────┬──────────────────────────────────────────────┘
                │ HTTPS + OIDC token
┌───────────────▼──────────────────────────────────────────────┐
│ 网关层 mcp-gateway                                            │
│  SSO 校验(aud) · 工具级 RBAC · 审计 · 限流 · 服务器目录          │
└──────┬──────────────────┬──────────────────┬─────────────────┘
       │                  │                  │
┌──────▼──────┐   ┌───────▼───────┐  ┌───────▼───────┐
│ kb-server   │   │ hr-server     │  │ it-ticket-server│
│ 敏感级: low  │   │ 敏感级: high  │  │ 敏感级: normal  │
│ 3 工具+1资源 │   │ 2 工具(只读)   │  │ 3 工具(1写)     │
└──────┬──────┘   └───────┬───────┘  └───────┬───────┘
       │                  │                  │
   文档检索 API        HR 系统 API         工单系统 API
（kb-server 所在网段可读全部文档；hr-server 端到端用户身份，行级过滤）

设计决策记录（ADR 摘要）：

1. 网关先行：800 用户 × 多客户端，直连模式权限必然失控（11.3）；
2. hr-server 走端到端身份：HR 数据行级权限在服务器内按用户裁剪（11.5 模型 2）；
3. 创建工单是本方案唯一写工具：独立注解 + 网关审批策略 + dry-run（8.4/12.4）；
4. 知识检索走 MCP 工具而非 RAG 预灌：时效性与权限都由服务器侧保证（6.2）；
5. Skill 承载"口径与格式"，服务器承载"能力与权限"——互不越界（6.4 反模式自查）。

16.3 实现一：kb-server（知识检索服务器）

核心代码（节选自可运行骨架，完整模式见 examples/python/full_server.py）：

"""kb-server：企业知识库检索。敏感级 low，全只读。"""
import os, json, logging, sys, time, uuid
from contextlib import asynccontextmanager
from collections.abc import AsyncIterator
from dataclasses import dataclass
from cachetools import TTLCache

import httpx
from mcp.server.fastmcp import FastMCP, Context
from mcp.server.fastmcp.exceptions import ToolError

log = logging.getLogger("kb")           # stderr；stdout 留给协议（第 10 章）
logging.basicConfig(level=logging.INFO, stream=sys.stderr,
                    format="%(asctime)s %(levelname)s %(name)s %(message)s")


@dataclass
class App:
    http: httpx.AsyncClient
    cache: TTLCache


@asynccontextmanager
async def lifespan(server) -> AsyncIterator[App]:
    async with httpx.AsyncClient(
        base_url=os.environ["KB_API_BASE"],          # 下游地址走配置
        timeout=httpx.Timeout(5.0, connect=2.0),     # 显式超时（14.2）
        headers={"Authorization":
                 f"Bearer {os.environ['KB_API_TOKEN']}"},  # 凭据只来自环境（12.3）
        limits=httpx.Limits(max_connections=30),
    ) as client:
        yield App(http=client, cache=TTLCache(maxsize=512, ttl=300))
        # 连接池常驻（14.2.1）；进程退出自动释放


mcp = FastMCP("kb", lifespan=lifespan)


def _audit(tool: str, rid: str, ms: float, ok: bool) -> None:
    log.info("audit tool=%s rid=%s ms=%.0f ok=%s", tool, rid, ms, ok)


@mcp.tool(annotations={"readOnlyHint": True})
async def search_kb(query: str, top_k: int = 5, ctx: Context = None) -> str:
    """检索公司知识库并返回最相关的文档片段。

    适用：员工咨询制度、流程、产品资料时。返回片段均带
    source_id，回答前应先调用 get_doc(source_id) 核对全文。

    Args:
        query: 自然语言问题或关键词，如 "年假可以顺延到明年吗"。
        top_k: 返回片段数，1-10，默认 5。
    """
    if not query.strip():
        raise ToolError("query 不能为空。请向用户确认要检索的问题。")
    top_k = max(1, min(10, top_k))                    # 参数钳制（12.5）

    rid = uuid.uuid4().hex[:8]
    t0 = time.perf_counter()
    try:
        r = await ctx.request_context.lifespan_context.http.get(
            "/search", params={"q": query, "top_k": top_k})
        r.raise_for_status()
        hits = r.json()["hits"]
    except httpx.TimeoutException:
        raise ToolError("知识库服务超时，请稍后重试。")     # 现象+建议（7.2.2）
    except httpx.HTTPStatusError as e:
        raise ToolError(f"知识库服务错误（{e.response.status_code}），"
                        "请联系平台组。")
    _audit("search_kb", rid, (time.perf_counter() - t0) * 1000, True)

    if not hits:
        return "知识库中未找到相关内容。建议：换关键词重试，或引导用户提交工单。"

    lines = [f"[{h['source_id']}] ({h['score']:.2f}) {h['title']}："
             f"{h['snippet'][:200]}" for h in hits]     # 摘要截断（8.3）
    lines.append("\n以上为片段摘要。撰写正式回答前，"
                 "用 get_doc(source_id) 获取全文核对。")
    return "\n".join(lines)


@mcp.tool(annotations={"readOnlyHint": True})
async def get_doc(source_id: str, ctx: Context = None) -> str:
    """按 source_id 获取知识文档全文。source_id 来自 search_kb 的结果。"""
    if not source_id.isalnum():                        # 白名单式校验
        raise ToolError("source_id 格式不合法（应为字母数字编号）。")
    ...  # 取全文，超 2 万字符时截断并附资源引用（8.3 第二层）


@mcp.resource("kb://{doc_id}/meta")
def doc_meta(doc_id: str) -> str:
    """文档元信息（标题/作者/更新时间），供应用侧注入。"""
    ...

要点回看：工具清单表驱动（3 工具+1 资源）；每处错误都是"现象+下一步"；get_doc 的存在就是浏览/详情分离模式（8.3）；缓存挂在 App 上（14.2）；审计日志一行不缺（15.4）。

16.4 实现二：it-ticket-server（含唯一写工具）

@mcp.tool(annotations={"readOnlyHint": True})
async def list_my_tickets(ctx: Context = None) -> str:
    """查询当前用户自己的 IT 工单列表（近 30 天）。"""

@mcp.tool(annotations={"readOnlyHint": True})
async def get_ticket(ticket_id: str, ctx: Context = None) -> str:
    """按编号查询工单详情。仅本人或其部门可见的工单可查。"""

@mcp.tool(
    annotations={"readOnlyHint": False, "destructiveHint": False,
                 "idempotentHint": True},            # 幂等（8.5）
)
async def create_ticket(title: str, description: str,
                        dry_run: bool = True, ctx: Context = None) -> str:
    """创建 IT 工单。

    默认 dry_run=True 仅返回将被创建的内容预览；
    确认无误后需再次调用并显式传 dry_run=false。

    Args:
        title: 一句话标题，如 "VPN 无法连接"。
        description: 现象、影响、已尝试的步骤。
    """
    preview = f"【工单预览】\n标题：{title}\n描述：{description}\n"
    if dry_run:
        return preview + "（预演，未创建。确认请再次调用并传 dry_run=false。）"
    user = await identity(ctx)                        # 端到端身份（11.5）
    idem = f"{user.id}:{hash((title, description))}"  # 幂等键
    ...  # 调下游创建，幂等去重

16.5 实现三：hr-server（高敏感域）

• 部署：独立网段，网关到它的路由追加一层内部校验（11.4 双轴）；
• 身份：只接受携带用户级 token 的请求，aud=hr-server 校验（12.3）；无 token 或服务账号 token 一律 403；
• 数据：仅两个只读工具 get_my_leave_balance / get_my_payslip_summary；输出前 PII 掩码（工号保留前 4 位、银行卡只留尾号）；
• 原则：别人的 HR 数据不存在于任何工具参数里——不是"查了再过滤"，而是接口设计上就只能"查我的"（12.5 第 8 条：不给攻击面留素材）。

16.6 实现四：kb-answering Skill（流程层）

---
name: kb-answering
description: 用公司知识库回答员工咨询并输出带引用的规范答案。
  当用户咨询公司制度、流程、报销假期政策、IT/行政问题，或要求
  "查一下知识库"时使用。不适用于代码技术与产品功能咨询。
---

# 知识库问答规范

## 流程
1. 用 kb 服务器（MCP）的 search_kb 检索，top_k 取 5；
   一次检索无果时，最多换 2 组同义关键词，仍无果则如实告知
   并建议提交工单（用 it-ticket 服务器的 create_ticket，
   先 dry_run 预览、征得用户确认）。
2. 对拟采用的每个片段，调用 get_doc(source_id) 核对全文，
   禁止只凭片段作答。
3. 按以下结构输出：
   - 直接回答（≤3 句）
   - 依据：引用 source_id 与关键原文（≤2 处）
   - 时效提示：文档更新时间超过 6 个月时注明"请以最新制度为准"
4. 多个文档冲突时：以更新时间新者为准，并向用户指出冲突点。

## 红线（不可违反）
- 知识库中查不到的内容，明确说"知识库暂无"，【禁止】编造或
  用通用知识冒充公司制度。
- 涉及薪酬、绩效、纪律类问题，只给政策原文引用，不做个人判断，
  并建议联系 HRBP。

配套按第 9 章方法：8 条触发样本（4 正 4 反，含"帮我写代码"反例）、evals.md 归档、上线前回归通过。

16.7 权限与安全配置（第 12 章落地）

网关侧权限表（12.4）：

安全设计回看：aud 校验 + scope（kb:read / tickets:write…）；审计事件按 12.6 schema，create_ticket 的正式调用实时告警；第三方文档内容进入上下文前由 kb-server 摘要消毒（12.5 第 2 条）；密钥全部 Secret 注入（13.6）。

16.8 部署与发布（第 13 章落地）

# docker-compose.yml —— 演示/小规模形态；>50 用户上 K8s（13.4 清单）
services:
  kb-server:
    build: ./kb-server
    environment:
      MCP_TRANSPORT: streamable-http
      KB_API_BASE: ${KB_API_BASE}          # 从 .env / 密钥服务注入
      KB_API_TOKEN: ${KB_API_TOKEN}
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8000/health"]
      interval: 15s
    restart: unless-stopped
  it-ticket-server: { ...同构... }
  hr-server:
    build: ./hr-server
    networks: [hr-isolated]                # 独立网段（11.4）
networks:
  hr-isolated: { internal: true }          # 无公网出口（12.5）

发布顺序：CI 门禁（15.3）→ staging E2E 冒烟（10.6.3）→ 金丝雀 10%（只放 IT 部门）→ 全员。金丝雀指标：search_kb P95、答案引用率、误挂载率（第 14 章面板）。

16.9 上线检查清单（合并全书清单的场景版）

• [ ] 功能：16.2 需求映射逐条演示通过；Skill 触发样本全绿
• [ ] 工程：CI 门禁四件套生效；集成测试含写工具 dry-run 路径
• [ ] 安全：12.7 基线逐项打勾；权限表评审签字；审计 trace 抽查可还原
• [ ] 性能：性能预算表（search_kb P95<1.5s）在预发达成；压测 2× 预期负载
• [ ] 部署：K8s 探针/优雅停机验证；回滚演练 <1 分钟
• [ ] 治理：registry.yaml 建档、owner 指定、README 齐备、eval 基线入库
• [ ] 运营：值班 runbook（挂 10 章速查表）、用户反馈通道、双周治理例会排期

16.10 上线后两周的真实演进（案例续写）

• 第 1 周数据：search_kb 日均 900 次，P95 1.1s 达标；但"答案引用率"只有 62%——抽样发现模型有时跳过 get_doc 直接凭片段作答。
• 对策（分层修复，而非改服务器）：在 kb-answering Skill 第 2 步加粗并给出反例（"只凭片段作答=不合格"）；同时给 get_doc 的描述补上"作答前必须调用"。一周后引用率 89%——描述工程与 Skill 编排的日常价值；
• 第 2 周需求：业务方要求"直接把答案发到内部 IM"。评估：新能力 → 新 MCP 工具（send_dm），但它是对外发送通道——按 12.5 第 4 条，收件人白名单 + 内容走 DLP 检查 + 注解 openWorldHint: true，并入下个 minor 版本灰度。

16.11 小结

案例把全书要素各就各位：

动手练习

1. 移植：把案例的"知识库"替换为你公司的任一业务域，重画 16.2 架构图并重写工具清单表——这是本教程的毕业设计。
2. 攻防：以 12.2 五类攻击为剧本，对 16.7 的权限表逐条推演防线缺口；至少找出一条并给出加固方案。
3. 容量规划：按"800 人 × 日均 3 次提问 × 平均 1.8 次工具调用"估算各服务器 QPS，结合练习 1 的压测数据给出副本数与缓存容量。
4. 汇报演练：用 10 页以内篇幅向管理层汇报本方案——重点讲清：为什么 MCP+Skill 组合、权限如何跟人、出事怎么查、成本几何。能讲清楚，才算真正掌握。

全书完。 附录提供了 术语表、常见问题 FAQ 与 资源清单，供随时查阅。

📄 附录 B · 常见问题 FAQ faq.md✓ 标记已学

概念与选型

Q1：MCP 和 OpenAI 的 function calling 是什么关系？会互相取代吗？ 不会。function calling 是模型 API 层的结构化输出能力（模型决定"调什么"）；MCP 是应用与外部能力之间的标准协议（决定"能调什么、怎么连"）。一个自研 Agent 可以同时用两者：模型 API 负责 function calling，MCP 负责把企业能力标准化地接进来。

Q2：有了 MCP，还需要 RAG 系统吗？ 经常"两者结合"。MCP 工具可以内部调用你的 RAG 管道（检索引擎、向量库），此时 MCP 是接入协议、RAG 是实现。相比"把文档预先灌进上下文"的静态 RAG，经 MCP 动态检索的优势是：权限实时生效、内容始终最新、可溯源引用（第 16 章案例即此模式）。

Q3：Skill 与 MCP 二选一还是都要？ 多数真实场景是组合：需要新能力/新数据 → MCP；需要一致流程/规范 → Skill；"按规范使用能力" → 两者组合（第 6 章决策框架）。

Q4：Skill 会不会被恶意利用？ 会。Skill 是会进模型上下文的指令，恶意 Skill 与提示注入同源。防线：只安装可信来源的 Skill；入库评审（像审代码一样）；Skill 中的"禁止项"只当体验约束、不当安全边界（第 12 章）。

开发实践

Q5：工具应该返回纯文本还是 JSON？ 给模型看的优先排版过的纯文本/Markdown（token 更省、模型更好读）；需要程序消费时用 structuredContent。原始大 JSON 是上下文杀手（第 8.3 节）。

Q6：一个服务器放多少工具合适？ 无硬性数字；经验舒适区 5–10，超过 20 开始明显劣化。收敛顺序：语义合并 → 按域拆服务器 → 元工具动态发现（第 8.2 节）。

Q7：Python 还是 TypeScript SDK？ 按团队栈选，协议能力对等。数据/内部工具生态选 Python（官方 mcp，内含 FastMCP）；Node 团队选 TS SDK。示例代码互相迁移成本低。

Q8：工具调用很慢，先查什么？ 顺序：返回体积（token 大户？）→ 下游调用（连接复用了吗？缓存了吗？）→ 服务器自身（异步？超时？）。口诀"先量 T3，再砍 T4，后抠 T2"（第 14.1 节）。

Q9：如何在本地同时调试多个服务器？ Inspector 支持逐个连；若要观察宿主内的整体行为，看宿主的 MCP 日志（第 10.3 节）。多服务器联调时给每个服务器取不同的、可辨识的 serverInfo.name。

Q10：Skill 改了不生效？ 宿主在会话启动时扫描 Skill 目录。改完后需要重启会话/新开会话；再检查：目录名与 name 一致、frontmatter 语法正确（YAML 对缩进敏感）、文件在宿主的发现路径下（第 5.2 节）。

企业落地

Q11：第一步应该做什么？ 挑一个低敏感、高频、只读的场景（如文档检索）做试点，用第 7/10 章的工程规范把它做扎实，再谈网关与治理。不要从高危写操作起步（第 11.8 节 90 天计划）。

Q12：网关必须自研吗？ 不必。优先评估存量基础设施：主流云网关与开源网关（Higress、Kong、APIM 等）已有 MCP 转发能力，社区也有 MCP Gateway 项目。自研只在"认证+审计+工具目录"三件套不满足时考虑（第 11.3 节）。

Q13：stdio 服务器在企业里就没有位置了吗？ 有。本机文件、Git、剪贴板等无敏感数据的个人效率工具用 stdio 最合适；原则是"涉企业数据与写操作的，必须走网关"（第 11.3 节）。

Q14：如何向安全团队证明 MCP 体系是可控的？ 用第 12 章的语言讲：威胁模型表（五类攻击逐条对应防线）、aud 校验与 scope 模型、审计事件样例、高危工具的审批链路、版本锁定策略。安全团队要的是确定性组件上的控制点，而不是"提示词里写了不许"。

Q15：协议还在演进，怎么避免被套牢？ 三点：业务代码只依赖 SDK 高层 API（传输与协议细节由 SDK 吸收）；关注规范的向后兼容承诺（版本协商）；新能力（如 Tasks）先用"task_id + 轮询工具"的自研等价物过渡，标准化后再切换（第 14.5 节）。

疑难杂症

Q16：服务器在 Claude Desktop 里时有时无？ 常见根因依次排查：配置 JSON 语法 → 路径是否绝对 → Python 解释器是否是装了依赖的那个 → 服务器启动即崩（手动 python server.py 看 stderr）→ 客户端版本兼容性（第 10.4 节表）。

Q17：为什么我的工具很少被模型调用？ 三个最常见原因：description 太弱（遮住名字猜不出用途）、与其他工具语义重叠（模型随机选）、宿主挂载的服务器太多稀释了注意力。按第 8.1 重写描述，通常立竿见影。

Q18：能否让服务器主动推送消息给模型？ 协议层：服务器可发通知（如 tools/list_changed），但通知不携带给模型的内容；需要"服务器事件驱动对话"时，常用替代是把"拉取更新"做成工具（如 get_latest_alerts），由模型或定时任务调用。真正的双向推送要看宿主的实现能力。

Q19：大模型 context window 里能装多少个工具描述？ 按 token 算而不是个数：每个工具约 50–300 token。20 个工具 ≈ 2–6k token 常驻。预算紧张时优先收敛工具数量与描述长度（第 14.3 节）。

Q20：Windows 上最常见的坑？ 三个：解释器路径（用绝对路径）、路径反斜杠转义（配置里用正斜杠 / 最稳）、stdio 下的控制台编码（建议 UTF-8，调试在 Git Bash/WSL 里做，第 4.5、10.4 节）。

📄 附录 A · 术语表 glossary.md✓ 标记已学

MCP 相关

Skill 相关

工程通用

📄 附录 C · 资源清单 resources.md✓ 标记已学

官方规范与文档

SDK（官方）

调试与测试

治理与企业生态（调研起点）

本教程的配套代码

学习建议

1. 以官方规范为最终依据：教程与博客都会过时，规范的"Security Considerations"与版本 changelog 值得定期回看；
2. 读源码学模式：官方参考服务器（servers 仓库）是最佳的模式教材；
3. 建自己的样本库：把工作中遇到的问题与解法沉淀进团队 wiki/Skill——本教程的方法论只有配合你自己的业务数据才会产生复利。

📄 根因分析框架（RCA-framework.md） RCA-framework.md✓ 标记已学

用途：复盘报告"根因分析"章节的分析方法。仅在需要时阅读本文件。

五问法（5 Whys）执行规范

对每条核心故障链路，连续追问"为什么"，直到可执行的系统性原因为止：

现象：21:02 payment-api P99 延迟突破 3s
问1 为什么超时？        → 下游风控服务响应从 80ms 劣化到 5s
问2 为什么风控劣化？    → v3.7.1 新增的规则引擎在全量流量下 CPU 打满
问3 为什么 CPU 打满才被发现？ → 新版本只做了 1% 灰度压测，未覆盖峰值规则组合
问4 为什么压测没覆盖？   → 发布清单中压测项是"建议项"而非"门禁项"
问5 为什么是建议项？     → 缺少"涉核心链路的新规则引擎必须全量压测"的制度
→ 根因（系统性）：发布门禁未按"改动风险分级"强制压测

停止条件：追问到"流程/制度/可自动化的控制缺失"即停；追到"某人的操作"不是根因——继续问"为什么系统允许该操作无保护地生效"。

直接原因 vs 根因 vs 贡献因素

反模式（校验脚本会拦截的写法）

• 根因写成"人为失误"——说明追问还没到底；
• 根因写成现象复述（"因为服务挂了所以故障"）；
• 只有一个根因没有贡献因素——真实故障通常是多因素叠加；
• 改进项与根因不对应（根因是压测门禁，改进项却是"加强值班培训"）。

📄 提交助手 SKILL.md✓ 标记已学

name: commit-helper description: 按团队规范生成 Git 提交信息并完成提交。当用户 要求提交代码、写 commit message、或说"帮我 commit"时使用。

流程

1. 运行 git status 与 git diff --staged 了解本次改动； 若暂存区为空，提示用户先 git add，不要自行选择文件暂存。
2. 运行 bash scripts/preflight.sh（本 Skill 目录内，相对路径执行）； 若发现大文件或疑似敏感文件，中止流程并向用户报告， 不要继续生成提交信息。
3. 判断改动类型：feat / fix / refactor / docs / test / chore。
4. 按以下格式生成提交信息：
   • 标题行：<type>(<scope>): <不超过 50 字的概括>
   • 空一行后写正文：解释为什么改，而不是罗列改了什么
5. 先展示建议的提交信息，征得用户同意后，再执行 git commit。
6. 【禁止】未经用户明确确认执行 push、rebase、reset 等任何 改写历史或对外发布的操作。

约定

• 本仓库使用中文提交信息。
• 一次提交只做一件事；发现改动混杂时，先建议用户拆分。

📄 故障复盘流程 SKILL.md✓ 标记已学

name: incident-review description: 为线上故障编写标准复盘报告。当用户要求复盘故障、 写 postmortem、故障总结、根因分析，或故障处置结束后要求整理 报告时使用。覆盖定级、时间线、根因与改进项四个环节。 不适用于代码性能分析、游戏对局复盘等非生产故障场景。

前置：确定故障与定级

1. 若用户提供了告警/工单编号，运行 python scripts/fetch_timeline.py --incident <id> 获取事件时间线； 没有编号时，向用户收集：故障开始时间、影响服务、发现渠道。
2. 依据 references/severity-matrix.md 为故障定级（P0–P3）， 并在报告开头标注。

撰写：按模板生成初稿

3. 使用 assets/report-template.md 作为报告骨架，逐节填写。
4. 根因分析遵循 references/RCA-framework.md 的五问法 （P0/P1 必须完整执行；P2/P3 可精简为三问）。
5. 需要 P0/P1 的同类历史案例做参照时，再阅读 references/postmortem-examples.md（避免不必要加载）。

校验：格式与完整性

6. 运行 python scripts/validate_report.py <草稿文件>； 所有 ERROR 级问题必须修复后才可提交，WARN 项向用户提示。

写作红线

• 只陈述可验证的事实，时间线精确到分钟。
• 责任指向系统与流程，不指向个人（无责复盘原则）。
• 未确认的推测必须标注"待验证"，不得写成结论。

交接

报告通过校验后，提示用户可将改进项登记到跟踪系统 （若有 action-tracker 类 Skill 则显式引导使用）。

📄 触发样本（evals.md） evals.md✓ 标记已学

用途：回归测试 incident-review 的触发边界。每次修改 frontmatter description 后必须全部重测（教程第 9.4 节）。

正例（应触发）

反例（不应触发）

变更日志

• 2026-09-29 初版：8 条样本全部通过。

📄 标杆复盘范例（postmortem-examples.md） postmortem-examples.md✓ 标记已学

用途：撰写 P0/P1 复盘时的参照样本。仅按需阅读（SKILL.md 第 5 步）。

范例一：支付网关超时（P1，摘录）

好的写法（事实驱动、系统归因）：

时间线

2026-09-28 21:02 告警触发：payment-api P99 延迟 3.2s（阈值 1s） 2026-09-28 21:05 值班响应，确认影响面：支付成功率 87%→61% 2026-09-28 21:11 定位：下游风控 v3.7.1 全量流量下 CPU 打满 2026-09-28 21:24 回滚至 v3.6.9，流量恢复 2026-09-28 21:31 指标回稳，宣告恢复（持续 29 分钟）

根因分析

直接原因：……（事实）根因：发布门禁未按风险分级强制压测（制度缺失） 贡献因素：延迟告警阈值过松（3s 才触发）

改进项

• [负责人: release-eng, 期限: 2 周内] 发布清单增加"核心链路规则引擎 变更必须 100% 压测"门禁项，CI 强制拦截

坏的写法（校验脚本与评审都会打回）：

根因：开发同学发布时不够谨慎，下次注意。 （✗ 指向个人；✗ 无改进项负责人与期限；✗ 时间线无时间戳）

范例二：配置变更引发的缓存雪崩（P2，三问法精简版）

现象 → 直接原因：TTL 集中在同一秒过期 → 根因：批量写入未加随机抖动 改进项：缓存写入统一走封装库，默认 ±10% TTL 抖动（负责人: infra, 期限: 1 周内）

从范例中提炼的通用标准

1. 时间线每条都可独立验证（来源：告警/oncall/工单）；
2. 根因一定落在"系统、流程、自动化控制"层；
3. 每条改进项 = 动作 + 负责人 + 期限，且与根因/贡献因素一一对应；
4. 影响面用数字表达（成功率、受影响用户比例、持续时间）。

📄 故障复盘报告：{{一句话故障描述}} report-template.md✓ 标记已学

定级: P{{0-3}}（依据 severity-matrix.md） 故障编号: INC-{{XXXX}} 影响服务: {{service}} 状态: 草稿 / 评审中 / 已归档

摘要

{{2–3 句话：发生了什么、影响多大、如何恢复}}

影响范围

• 业务影响：{{用数字：成功率变化 / 受影响用户比例}}
• 持续时间：{{开始 → 恢复，合计 X 分钟}}
• 数据影响：{{是否涉及数据错误/丢失；无则写"无"}}

时间线

• 2026-MM-DD HH:MM {{事件}}（来源：告警 / oncall / 工单）
• 2026-MM-DD HH:MM {{事件}}
• …（精确到分钟；未核实条目标注"待验证"）

根因分析

• 直接原因：{{事实}}
• 根因（系统性）：{{按 RCA-framework.md 五问法得出的制度/流程层结论}}
• 贡献因素：{{0–n 条，单独列出}}

改进项

• [ ] {{动作}}（负责人: {{owner}}，期限: {{X 周内}}）— 对应根因
• [ ] {{动作}}（负责人: {{owner}}，期限: {{X 周内}}）— 对应贡献因素

附录

监控面板截图 / 相关工单链接 / 评审记录

📄 定级矩阵（severity-matrix.md） severity-matrix.md✓ 标记已学

用途：故障定级速查表。定级决定复盘的深度要求（SKILL.md 第 4 步）。

定级判据（从高到低逐条判断，命中即停）

定级后的流程要求

边界情形

• 影响人数与时长都处于临界值 → 就高不定级；
• 复盘过程中发现影响扩大 → 重新定级并在报告中注明变更原因；
• 定级存疑 → 写明两种候选级别与理由，交由值班经理裁定。