> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# MCP Server 概念与设计原则

:::info 提示

本文面向准备在豆包中提供业务工具能力的开发者，重点说明 MCP Server 的定位、能力边界和高层设计原则。本文不展开字段协议、开发步骤和调试命令；具体实现与精确协议分别参见 [MCP Server 开发](/apps-plugin/docs/skill-development/mcp-server.md) 和 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md)。

<div hidden data-lark-callout-end></div>

:::

## 定位与术语

MCP Server 是遵循 MCP 向模型提供工具能力的服务端组件。一个 MCP Server 可以提供一个或多个 MCP 工具；MCP Server 是能力的服务载体，MCP 工具是模型可以发现和调用的具体业务能力。本文讨论 MCP Server 的整体边界，也重点说明其中 MCP 工具的设计原则。

在豆包能力体系中，业务系统继续负责领域数据和业务逻辑，MCP Server 负责把可复用的业务能力表达为稳定的工具契约，配套 Skill 负责说明这些工具在具体场景中的使用方式。业务方不需要为了接入模型而改变已有业务系统的核心实现。

MCP Server 不是普通业务 API 的简单转发层，也不应把已有接口逐个复制为工具。普通业务 API 主要服务确定性的程序调用；MCP 工具还需要让模型理解它代表什么业务意图、何时适合调用，以及调用结果意味着什么。

| 比较维度   | 普通业务 API     | MCP 工具                 |
| ------ | ------------ | ---------------------- |
| 主要服务对象 | 应用、服务或固定程序流程 | 模型及其承载的智能场景            |
| 设计起点   | 系统功能和接口边界    | 用户目标和可理解的业务能力          |
| 核心关注   | 程序能够正确调用接口   | 模型能够正确发现、选择并理解调用结果     |
| 能力组合   | 由上游程序预先编排    | 由模型依据配套 Skill 在场景中组合使用 |

## MCP Server 与 Skill、卡片的关系

MCP Server 是能力主体，回答“能做什么”；Skill 是使用说明，回答“在什么场景、以什么方式使用”；卡片是可选的展示能力，回答“如何把结果更合适地呈现给用户”。

| 组成部分       | 核心职责                | 交付要求                |
| ---------- | ------------------- | ------------------- |
| MCP Server | 提供稳定、可理解、可调用的业务工具能力 | 能力交付的主体             |
| Skill      | 说明工具的适用场景、选择方式和组合策略 | 必须与 MCP Server 配套交付 |
| 卡片         | 承接结构化展示和必要的用户交互     | 根据业务场景选配            |

**MCP Server 与 Skill 必须配套。**&#x4EC5;提供工具而没有 Skill，模型可能无法稳定判断何时使用，或者无法在多工具之间形成正确的调用策略。二者应在工具语义、使用条件和结果理解上保持一致，并作为同一个能力单元共同演进。多个工具共同完成一个业务流程时，应由配套 Skill 描述选择条件、调用顺序和必要的衔接方式。MCP Server 保持每项能力边界稳定，Skill 负责把这些能力组合为面向具体场景的解决方案。

**卡片按场景选配。**&#x5F53;结果包含适合结构化浏览、比较或操作的信息时，可以通过卡片提升体验；当自然语言已经能够清楚表达结果时，无需为了展示形式强行接入卡片。卡片不应改变工具的业务语义，也不应成为理解工具结果的唯一前提。

**MCP Server 的业务数据需要与卡片展示解耦。**&#x4D;CP Server 表达业务事实和操作结果，卡片负责展示结构与交互方式。这样可以在不改变工具能力的情况下调整展示，也可以让没有卡片的场景继续使用同一项能力。

## 适用场景与能力边界

MCP Server 应提供具有明确业务含义、能够独立说明并可被模型安全调用的能力。它面向模型表达必要的输入、业务结果和失败语义，但不承担与工具能力无关的会话编排、界面展示或业务系统治理职责。

一项能力通常在满足以下条件时适合通过 MCP Server 提供：

- 对应清晰、可描述的用户目标或业务目标；
- 能够形成相对稳定的业务语义，而不是短期页面操作或内部流程步骤；
- 模型可以基于明确上下文判断是否需要调用；
- 调用结果能够帮助模型或用户继续完成任务；
- 能力所涉及的身份、权限、隐私和风险边界可以被清楚界定。

对话策略和多工具使用流程由 Skill 表达，展示样式和用户交互由卡片等展示能力承接。业务逻辑、业务鉴权、数据治理和服务稳定性继续遵循业务团队自身的研发规范；豆包侧的用户身份和权限模型参见 [用户身份与权限模型](/apps-plugin/docs/core-concepts/identity-and-permissions.md)。平台内部链路和实现细节不应成为业务方设计工具时的依赖。

如果一项能力只能依赖大量隐含上下文才能使用，或只是内部实现中的一个过细步骤，通常应先重新梳理业务边界，而不是直接设计为 MCP 工具。

## 设计原则

### 选对该实现的 Tool，而不是把 API 全搬过来

**工具设计需要以业务能力为中心。**&#x4ECE;用户希望完成的目标出发抽象工具，而不是从已有接口列表出发。工具名称和边界应表达业务含义，避免把内部服务名、流程节点或技术实现直接暴露给模型。

**工具设计需要边界清晰且可组合。**&#x4E00;个工具应承担一个连贯的业务职责，能够独立说明、独立判断是否调用，同时可以通过 Skill 与其他工具组合成完整流程。

常见错误是把已有的 REST 接口逐个封装为 Tool。模型上下文有限，`list_all_*` 这类返回大列表的 Tool 会消耗大量 token，且无法帮助模型做出决策。

- **少而准 > 多而散**：一个 MCP Server 内的 Tool 数量不超过 15 个，超过时应拆分或合并。
- **每个 Tool 都要有清晰、唯一的目的**：让模型能够像人一样把任务拆解到正确的 Tool 上；功能重叠的 Tool 会让模型反复犹豫。
- **每个决策节点对应一个 Tool**：例如，“查门店 → 查商品 → 下单”三个步骤对应 3 个 Tool。
- **用搜索代替罗列**：把 `list_contacts` 换成 `search_contacts(query)`，让服务端做过滤，只返回模型真正要的几条。

工具拆分应围绕用户可感知的业务子目标进行。理想的工具粒度既不是内部接口的一一映射，也不是覆盖整个业务领域的“万能工具”，而是在单次调用中完成一个边界明确、结果可判断的业务动作。

拆分时可以依次判断：用户是否能够说清这次调用要完成什么；工具是否可以独立描述其成功结果；模型是否能够与相邻工具区分；调用是否包含不同风险或不同性质的动作。如果一个工具同时包含查询、选择和不可逆执行等多类职责，通常应重新评估边界。

| 常见问题         | 可能影响             | 建议调整                 |
| ------------ | ---------------- | -------------------- |
| 按内部接口逐个创建工具  | 工具数量过多，模型难以选择和组合 | 围绕用户可感知的业务目标重新归并     |
| 一个工具承载过多职责   | 使用条件模糊，结果和风险难以预期 | 按独立业务意图拆分清晰边界        |
| 把固定流程写入工具能力  | 工具难以被其他场景复用      | 保留稳定能力，将场景策略交给 Skill |
| 工具结果与某个卡片强绑定 | 展示变化会反向影响业务能力    | 分离业务数据与展示配置          |

### 命名与 Schema 要严格，字段要语义化

**工具 Schema 需要语义化，对模型友好。**&#x6A21;型应当能够从显式信息中理解工具用途，不依赖只有业务研发人员知道的隐含知识。不同工具之间应有清楚的语义区分，避免名称相近、职责重叠或使用条件冲突。

关于命名与 Namespace：

- **需要动词开头 + lowercase snake\_case**：`brewnow_create_order` ✅；禁止 `search` / `get` / `find` 这类泛名 ❌（模型会乱选）。
- **服务前缀必加**：`brewnow_*`、`kfc_*`，避免跨 MCP Server 同名工具混淆。
- **需要时再加资源前缀**：工具量大时用 `brewnow_orders_search`、`brewnow_stores_search` 这样的"服务\_资源\_动作"三段式，帮模型按资源做选择。
- **参数命名要消歧**：用 `user_id` 而不是 `user`，用 `store_id` 而不是 `store`，避免模型把名字、ID、对象混在一起。

关于参数命名：

- **所有参数都带 description**，enum 必须穷举合法值，关键字段附 `examples`。
- **`additionalProperties: false` + `strict: true`**：拒绝模型瞎传字段，宁可报错也不要静默吞掉。
- **返回结构稳定**：无论有没有结果，顶层字段集合不变；schema 描述的字段必须真实存在，schema 没承诺的字段不要默默冒出来。
- **返回有意义的上下文**：优先用 `name` / `store_name` / `file_type` 这种语义化字段，避免把 `uuid` / `mime_type` / `256px_image_url` 这种纯技术 ID 当主键暴露给模型。
- **支持 `response_format: "concise" | "detailed"`**：默认 concise 省 token，模型需要下钻时再换 detailed；必要时也可以把分页 / 截断 / 过滤参数加上默认值，避免一次返回打爆上下文。

### 错误必须告诉模型“下一步怎么改”

**错误响应是最被忽视、但对模型最关键的部分**——正常路径出错的概率约 10%，而错误路径出错后模型继续做错事的概率高达 90%。失败需要可理解、可恢复。失败结果应帮助模型和用户判断发生了什么，以及是否可以补充信息、调整请求或稍后重试。具体错误结构遵循协议规范。

| 字段               | 作用                                                                                                                                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error.code`（必填） | 业务错误码，**必须是 JSON number**（不使用字符串枚举）。按下方分类细分，严禁所有错误都返回同一个码（如 50000）。平台会把它映射为内部顶层 `error_code`。                                                                                                             |
| `error.msg`（必填）  | 业务错误文案，**字段名必须是 `msg`**（不要用 `message` / `error_message` / `detail`）。面向模型和最终用户的自然语言说明，建议遵循 CARS 公式：Cause（错在哪）+ Allowed values（合法值）+ Received value（收到了什么）+ Suggested fix（下一步怎么改）。平台会把它映射为内部顶层 `error_msg`。 |
| 其他字段             | **不支持**。业务接口顶层只允许 `output` / `error`；`error_type` / `param_path` / `received_value` / `retryable` / `retry_after_sec` / `instance` 等定位 & 重试信息请直接写进 `error.msg` 的 CARS 文案里，由模型理解。                          |

### 升级时需同步评估对 Skill 及卡片的影响

**契约稳定且可演进。**&#x5DE5;具一旦被 Skill 和场景使用，其核心语义就形成了对外承诺。新增能力应优先采用兼容方式；必须改变既有语义时，应明确升级路径并同步评估相关 Skill 和卡片。

### 隐私原则

**最小必要暴露。**&#x53EA;向模型提供完成目标所必需的能力和数据，避免暴露与当前任务无关的信息。涉及用户数据、敏感操作或不可逆行为时，应优先明确权限、隐私和风险边界。

:::info 提示

以上原则关注 MCP Server 对外能力的设计，不替代业务服务已有的安全、稳定性、合规和工程质量要求。

<div hidden data-lark-callout-end></div>

:::

## 能力演进与设计检查

MCP Server 的能力设计可以先在边界明确的场景中验证。验证重点是模型能否稳定理解和选择工具、工具结果能否支持后续任务，以及能力边界是否适合复用。能力升级应以保持既有语义为默认原则，MCP Server、Skill 和选配的卡片需要同步评估和更新。

在进入开发前，建议检查：

- 该能力是否确实适合由模型调用；
- 工具是否对应清晰、可描述的业务目标；
- 职责是否连贯，是否存在过细、过宽或与其他工具重叠的问题；
- 模型是否能在不依赖内部知识的情况下理解并选择工具；
- 调用结果是否足以支持模型或用户继续完成任务；
- 是否提供了与工具实际能力一致的配套 Skill；
- 是否确有卡片展示需要，无卡片时结果是否仍可理解；
- 工具核心语义是否稳定，后续扩展是否能够保持兼容；
- 身份、权限、隐私和高风险操作边界是否明确。

如果其中多个问题无法明确回答，建议先调整能力抽象，再进入具体开发和协议设计。

开发过程中，建议按照下述七个维度的规则进行自检；工具定义以 MCP Server 的 `tools/list` 返回为准，工具结果以 `tools/call` 的原始返回（raw MCP response）为准，重点检查其中的 `content`、`structuredContent` 和 `isError`。

### MCP 小程序开发产物质量 Checker 规则目录

#### 七维规则总览

| 维度        | 规则编号     | 自检方式                                                          | 检测目标                  |
| --------- | -------- | ------------------------------------------------------------- | --------------------- |
| 协议与结构     | T-PROTO  | 分别检查工具成功和失败时的原始返回字段与类型。                                       | ToolResult 成功、失败结构合法  |
| 命名与描述     | T-NAME   | 检查工具名称、数量、description 和实际能力边界。                                | 工具可发现、可路由且能力边界准确      |
| 入参 Schema | T-SCHEMA | 检查参数定义、枚举、类型、权限配置及真实调用时的参数行为。                                 | 输入定义清晰，非法输入被拒绝，业务约束落实 |
| 输出与数据契约   | T-OUT    | 检查原始返回的体量、必要字段、Manifest 和 outputSchema 一致性、结构化数据完整性、分页及多模态内容。 | 输出精简、完整并符合声明契约        |
| 错误处理      | T-ERR    | 实际触发错误，检查原始返回的错误码、原因、定位信息、恢复建议及最终业务状态。                        | 错误分类、原因、定位和恢复信息准确     |
| 性能稳定性     | T-PERF   | 重复调用同一工具，记录响应耗时、限流、成功失败状态及服务调用链异常。                            | 响应时长及重复调用稳定           |
| 安全与副作用    | T-SAFE   | 检查敏感业务字段、幂等保护、Manifest 登录配置和高风险操作确认机制。                        | 敏感字段、登录绑定及写操作风险可控     |

**规则明细与执行方式**

以下表格中的返回字段均指 MCP Server 直接返回的 ToolResult；实体数据位于 `structuredContent.entities[].result`，执行结果直接位于 `structuredContent`。具体结构参见 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md)。

#### T-PROTO 协议与结构

| ID           | Checker  | 通过条件                                                                                                                                                                                                                                                                                  | 正反示例                                                                                                                                                          | 级别   | 检查方式与证据来源                                                                                                |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------- |
| `T-PROTO-01` | 成功返回协议合法 | 成功时，`isError` 缺失或为 `false`，`structuredContent` 必须是对象。`content` 可选；包含文本项时，`text` 必须是字符串。Manifest 声明 `output.kind=entities` 时，`structuredContent.entities` 必须是数组，每项包含非空字符串 `entity_type`；声明 `execution_result` 时直接返回执行结果对象，不增加 `entities` 包装。实体是否出卡由 Manifest 的 `tool_card_binding` 决定。 | **正例：**&#x6267;行结果返回 `{"isError":false,"structuredContent":{"order_id":"ord_demo"}}`。<br/>**反例：**&#x5C06; `structuredContent` 返回为 `"ok"`，或实体缺少 `entity_type`。 | FAIL | 分别调用返回实体和执行结果的工具，检查原始 ToolResult 的字段、类型与 Manifest 的输出类型；实体字段映射另按 T-OUT-03 检查。                            |
| `T-PROTO-02` | 失败返回协议合法 | 失败时，`isError` 必须为 `true`，`structuredContent` 必须是对象，其中 `code` 为 JSON number、`message` 为字符串。`content` 可选，可用于说明业务错误。                                                                                                                                                                     | **正例：**`{"isError":true,"structuredContent":{"code":40001,"message":"订单不存在"}}`。<br/>**反例：**`code` 为字符串 `"40001"`，或缺少 `message`。                               | FAIL | 实际触发工具失败，检查 MCP Server 原始返回的 `isError`、`structuredContent.code`、`structuredContent.message` 和 `content`。 |

#### T-NAME 命名与描述

| ID          | Checker         | 通过条件                                                                | 正反示例                                                                                                                                               | 级别   | 检查方式与证据来源                                                      |
| ----------- | --------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------- |
| `T-NAME-01` | 工具命名规范          | 使用“品牌名缩写\_动作\_对象”格式，名称为小写英文和下划线，至少包含三段。品牌缩写作为命名空间前缀，动作与对象应准确表达业务含义。 | **正例：**`ddmc_query_order_status`、`demo_orchestrate_inventory`。<br/>**反例：**`ddmc_get` 只有两段，`ddmcQueryOrderStatus` 或 `ddmc-query-order-status` 格式不符。 | WARN | 查看 `tools/list` 中的名称，检查格式，并结合工具实际职责核对动作与对象是否准确。                |
| `T-NAME-02` | 单 Server 工具数量适中 | 单 Server 工具数量不超过 30，每个决策节点对应一个职责清晰的工具。                              | **正例：**&#x6CE8;册 18 个职责清晰的工具。<br/>**反例：**&#x6CE8;册 31 个工具，超过建议上限。                                                                                  | WARN | 统计同一 MCP Server 的 `tools/list` 工具总数，检查职责是否重叠或过细。               |
| `T-NAME-03` | 工具描述语义完整        | description 应说明核心能力、调用时机、路由边界及必要约束。未涵盖这些要素且少于 30 字时，建议补充。           | **正例：**“查询指定订单的配送状态；用户询问订单进度时调用；不用于取消订单。”<br/>**反例：**&#x4EC5;写“订单工具”。                                                                              | WARN | 阅读 `tools/list` 中的 description，核对模型能否据此理解工具用途、调用条件与边界。         |
| `T-NAME-04` | 描述不超出 Schema 能力 | 工具描述不得承诺 Input Schema 不支持的能力或特殊值。                                   | **正例：**&#x63CF;述支持按 `order_id` 查询，Schema 也声明该字段。<br/>**反例：**&#x63CF;述支持按手机号查询，但 Schema 没有对应参数。                                                     | FAIL | 对照 `tools/list` 的 description、Input Schema 和实际可传入的参数，逐项核对能力承诺。 |
| `T-NAME-05` | 描述明确能力边界        | 描述明确不支持的操作、服务商和场景，不得夸大或虚构能力。                                        | **正例：**“仅查询本平台订单状态，不支持取消订单或查询其他平台订单。”<br/>**反例：**&#x5B9E;际只支持查询，却描述为“处理所有订单相关操作”。                                                                  | WARN | 结合业务范围、相邻工具定义与实际调用结果，核对 description 的能力边界。                     |

#### T-SCHEMA 入参与校验

| ID            | Checker             | 通过条件                                                                                                                                                              | 正反示例                                                                                                                              | 级别   | 检查方式与证据来源                                                                                                           |
| ------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------- |
| `T-SCHEMA-01` | 参数描述与枚举含义完整         | 每个参数有描述，枚举穷举合法值并解释每个值的业务含义；允许“1配送 2自提”等明确的自然语言映射，仅列出值不算解释。                                                                                                        | **正例：**`delivery_type` 为 `[1,2]`，描述“1=配送，2=自提”；`baseCabin` 为 `[Y,C]`，描述“Y经济舱 C公务头等舱”。<br/>**反例：**&#x53EA;写“可填 1 或 2”或“可选 Y/C”。    | FAIL | 逐字段检查 `tools/list` 的 Input Schema、description 和 enum，确认每个枚举值都有含义说明。                                                 |
| `T-SCHEMA-02` | 身份与诊断参数不入 Schema    | 由平台注入的身份凭据和诊断参数不应进入业务 Input Schema，不应要求模型填写 access\_token、cookie、user\_id 或 debug\_trace\_id 等字段。业务自身的不透明令牌需与身份凭据明确区分。                                            | **正例：**&#x53;chema 只声明 `order_id`，登录凭据通过身份与权限链路获取。<br/>**反例：**&#x8981;求模型填写 `access_token` 或 `cookie`。                            | FAIL | 对照 Input Schema 与 [用户身份与权限模型](/apps-plugin/docs/core-concepts/identity-and-permissions.md)，确认业务参数不包含平台负责提供的身份和诊断信息。 |
| `T-SCHEMA-03` | 参数语义、约束与行为一致        | 参数缺失、使用默认值或取不同值时，真实行为应符合声明；数量、库存、金额、时间窗、服务范围等明确硬约束必须生效。无法满足时明确拒绝，或说明原因并提供合法替代；不要求固定回显字段。                                                                          | **正例：**`include_history=false` 只返回当前状态；库存不足时明确拒绝或提供合法数量。<br/>**反例：**&#x53C2;数变化不影响行为，或结果突破已声明约束且不解释。                              | WARN | 使用合法入参进行成对调用，对照参数与约束原文、实际请求及原始 ToolResult，排除数据巧合后判断参数是否生效。                                                          |
| `T-SCHEMA-04` | 结构化入参不使用 JSON 字符串   | 结构化业务数据使用对象或不透明 token，不用 JSON 外观字符串承载。                                                                                                                            | **正例：**`address` 为 object，包含 `city`、`detail`；或传 `address_token`。<br/>**反例：**`address` 为 string，却要求传入 `"{\"city\":\"北京\"}"`。       | FAIL | 检查 Input Schema 的类型和描述，确认对象或数组没有被声明成承载 JSON 的字符串。                                                                   |
| `T-SCHEMA-05` | 业务枚举映射闭环            | 对外枚举与真实业务含义一致，不同服务商对同一含义的编码差异由业务映射层统一。                                                                                                                            | **正例：**&#x5BF9;外统一使用 `delivery`，内部将服务商的 `1`、`DELIVERY` 映射到该值。<br/>**反例：**&#x540C;一配送方式随服务商变化直接返回 `1` 或 `DELIVERY`，没有统一含义。         | FAIL | 对照 Schema、业务枚举定义和不同服务商的原始 ToolResult，核对同一字段的映射。                                                                     |
| `T-SCHEMA-06` | 互斥参数显式声明            | 互斥参数建议通过 `oneOf`、`anyOf` 等表达，或由 Server 明确校验并返回可定位错误；不强制固定 Schema 写法，缺少这些声明本身不等于协议失败。                                                                              | **正例：**`order_id` 与 `external_order_id` 只能二选一，Schema 或 Server 明确校验。<br/>**反例：**&#x540C;时传入时静默忽略其中一个。                              | WARN | 核对参数关系说明和 Input Schema，实际传入冲突参数，检查 Server 原始错误返回是否指出冲突。                                                             |
| `T-SCHEMA-07` | 数组 items 完整         | 数组的 items 必须是有效 Schema，至少声明 `type`、`$ref`、`anyOf`、`oneOf`、`allOf`、`enum` 或 `const` 之一；不要求元素必须为 object。                                                            | **正例：**`{"type":"array","items":{"type":"string"}}`。<br/>**反例：**&#x53EA;有 `{"type":"array"}`，未声明元素类型。                             | WARN | 检查 Input Schema 中每个数组字段的 items 是否具备可验证的定义。                                                                          |
| `T-SCHEMA-08` | 参数类型明确              | 禁止 `type:any`，参数必须声明明确类型，或通过 `oneOf`、`anyOf`、`$ref` 等给出可验证的类型定义。                                                                                                  | **正例：**`count` 为 integer，`address` 为 object 并声明子字段。<br/>**反例：**`payload` 为 `type:any`，或没有任何类型定义。                                  | FAIL | 遍历 Input Schema 的参数及嵌套字段，检查类型声明是否明确。                                                                                |
| `T-SCHEMA-09` | 参数数量与嵌套适中           | 单工具顶层参数建议不超过 10 个，嵌套深度不超过 2 层。                                                                                                                                    | **正例：**&#x32; 个参数，最深为 `address.city` 两层。<br/>**反例：**&#x31;4 个顶层参数，或 `order.user.address.city` 四层嵌套。                               | WARN | 统计 Input Schema 的顶层 properties 数量与最大对象嵌套层数。                                                                         |
| `T-SCHEMA-10` | 位置权限与 location 入参一致 | 工具绑定 `scope.userLocation` 或 `scope.userFuzzyLocation` 时，应声明可选的顶层 `location` 对象，其中 `longitude`、`latitude` 均为可选 number；未绑定这两个权限时，不声明业务 `location`。平台注入容器内的字段不算业务入参。 | **正例：**&#x4D;anifest 绑定位置权限，Schema 声明可选 `location` 及两个可选 number 坐标。<br/>**反例：**&#x7ED1;定权限却缺少 location、坐标类型不符，或将 location、坐标设为必填。 | FAIL | 对照 Manifest 的 `tools.<tool>.tool_permissions` 与 `tools/list` 的 Input Schema，检查位置对象、坐标类型、可选性及旧顶层坐标字段。                |

#### T-OUT 输出与数据契约

| ID         | Checker             | 通过条件                                                                                                                                                                     | 正反示例                                                                                                                                                 | 级别   | 检查方式与证据来源                                                                                                                            |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `T-OUT-01` | 输出体量不超预算            | 原始 ToolResult 的 `content` 不超过 4000 token；该预算不对 `structuredContent` 计数。                                                                                                   | **正例：**&#x63;ontent 为 600 token 的简短摘要。<br/>**反例：**&#x63;ontent 展开完整商品明细，估算 5200 token。                                                               | FAIL | 直接读取 MCP Server 返回的 content，按 JSON 序列化后的内容估算 token：中文等 CJK 字符按每字 1 token，其余字符按每 4 字符约 1 token。                                       |
| `T-OUT-02` | 返回字段最小化             | 原始 `content` 只保留完成任务所需的信息，不混入诊断元数据、重复映射或非必要长 ID；不要求 content 重复展开 structuredContent 的全部业务数据。                                                                              | **正例：**&#x63;ontent 简要说明订单状态，完整业务字段放在 structuredContent。<br/>**反例：**&#x63;ontent 包含内部请求头、traceId、重复数据或与任务无关的长 ID。                                    | FAIL | 对照任务目标检查原始 content；文本中包含 JSON 时逐字段核对必要性。超过 64 字符的非凭据类 ID 应检查是否确有必要，完整链接应使用语义明确的 URL 字段。                                              |
| `T-OUT-03` | Manifest 输出字段映射一致   | Manifest schema 声明的字段必须出现在 Server 的原始结构化结果中，类型、枚举和嵌套结构一致；允许返回额外业务字段，额外字段本身不按本规则判错。                                                                                       | **正例：**&#x58F0;明 `order_id`、`status`，原始结果包含二者且类型、取值符合声明，并额外返回 `updated_at`。<br/>**反例：**&#x58F0;明 status 为 string，实际缺失、为 object，或返回声明外枚举值。            | WARN | 逐次对照 Manifest 与原始 structuredContent；实体字段检查 `structuredContent.entities[].result`，执行结果检查 structuredContent。定位到实体类型和具体缺失、类型错误或枚举错误的字段。 |
| `T-OUT-04` | 输出枚举含义完整            | 输出枚举和状态码应为每个值解释含义；明确的自然语言映射、括号说明和单位说明均可，仅引用取值不算解释。                                                                                                                       | **正例：**&#x73;tatus 为 `[1,2]`，明确写“1=处理中，2=已完成”。<br/>**反例：**&#x4EC5;写“状态为 1 或 2”。                                                                      | WARN | 检查 Manifest 和工具输出字段说明中的枚举值及 description，逐值核对业务含义。                                                                                    |
| `T-OUT-05` | 结果符合输入筛选约束          | 车型、时间、服务商、排序和过滤等已声明筛选参数必须真实生效；无法满足时说明原因与替代方案，不强制固定参数回显字段。                                                                                                                | **正例：**&#x8BF7;求服务商 A 并按时间升序，结果只含 A 且正确排序。<br/>**反例：**&#x8FD4;回服务商 B，未说明原因。                                                                          | FAIL | 对照实际筛选参数和原始 structuredContent 的业务结果；检查匹配范围、顺序及替代原因，缺少固定回显字段本身不判错。                                                                    |
| `T-OUT-06` | 空结果语义明确             | 明确区分无数据、无订单和执行异常，不用空对象伪装成功；成功空结果通过 `next_step_hint` 或 content 给出与本次结果相关、可执行的下一步。                                                                                         | **正例：**&#x8FD4;回空订单列表并提示“建议调整日期范围后重新查询”。<br/>**反例：**&#x53EA;返回空列表而无下一步建议；上游超时却返回 `{}` 并标记成功。                                                         | WARN | 分别触发正常无结果和执行异常，检查原始 ToolResult 的状态、空结果说明与下一步建议；错误分支的恢复动作按 T-ERR-04 检查。                                                               |
| `T-OUT-07` | 实际返回符合 outputSchema | 工具 description 和 outputSchema 声明的结构应与实际 structuredContent 一致。                                                                                                            | **正例：**&#x6F;utputSchema 声明 status 为 string，实际返回字符串。<br/>**反例：**&#x7F3A;少必需的 order\_id，或声明数组字段却返回对象。                                                 | FAIL | 直接将 `tools/list` 的 outputSchema、description 与每次原始 structuredContent 逐字段比较，检查必需字段、类型和约束。                                              |
| `T-OUT-08` | 对外句柄不可预测            | 明确的 handle、token、cursor 使用 UUID、slug 或不透明字符串，不直接暴露可推断的数字主键；不泛化到普通业务 ID。                                                                                                  | **正例：**&#x8FD4;回不可推断的 `next_page_token`。<br/>**反例：**`next_handle` 为可猜测的递增数字 123。                                                                     | WARN | 检查原始结构化结果中明确的句柄字段和值，确认续取或引用凭据不能通过枚举数字猜测。                                                                                             |
| `T-OUT-09` | 结构化业务数据完整           | 需要后续工具引用或结构化展示的关键业务数据，应完整保留在原始 `structuredContent.entities[].result` 或执行结果对象中；不能只在 content 文本中说明，而让结构化结果缺失或为空。不要求 content 逐字段复制结构化数据。                                    | **正例：**&#x5B9E;体 result 包含订单号、金额和状态，content 简要说明查询成功。<br/>**反例：**&#x63;ontent 写出完整订单信息，但对应实体 result 为空或缺少下游必需的订单号。                                   | FAIL | 对照实际业务结果、Manifest 和下游参数要求，检查原始结构化结果的关键字段及值是否完整；正常无结果不按本规则判错。                                                                         |
| `T-OUT-10` | 描述与真实输出语义一致         | description 明确声明不返回某类业务数据时，Server 原始结果不得包含该类非空数据；只有声明与字段含义可直接对应时才判定，不对模糊描述泛化推断。                                                                                          | **正例：**&#x58F0;明不提供实时余票，返回不含余票字段。<br/>**反例：**&#x58F0;明不返回余票，却返回 `seatDesc=有票`、`seatNum=21`。                                                          | WARN | 对照 tools/list 的明确否定声明与原始 structuredContent 的非空字段，核实字段自身的业务语义。                                                                        |
| `T-OUT-11` | 分页截断可继续             | 适用于声明分页、截断、续取能力或实际返回这些标记的工具。应明确总量、当次返回量和截断状态；有剩余内容时提供续取位置，并通过 content 或 `next_step_hint` 说明如何继续。                                                                         | **正例：**&#x8FD4;回 total\_length、returned\_length、truncated=true、next\_offset，并提示使用 offset 继续。<br/>**反例：**&#x6807;记 truncated=true，却缺少当次返回量、续取位置或续取提示。 | WARN | 对照 description、page/offset/cursor 参数和原始返回标记，检查续取信息；total\_count、returned\_count、has\_more、next\_page\_token 等同义字段也可使用。               |
| `T-OUT-12` | 多模态 Content 类型合法    | 适用于原始 content 实际包含非 text 内容或媒体内嵌载荷的情况。image/audio 使用 data 和 mimeType，不使用 source 包装；resource\_link 包含 uri、name；resource 包含 resource.uri，并以 text 或 blob 承载内容。媒体数据不拼进 text。 | **正例：**`{"type":"image","data":"...","mimeType":"image/png"}`。<br/>**反例：**&#x69;mage 使用 source 包装，resource\_link 缺少 uri/name，或将媒体 data URI 放入 text。  | WARN | 逐项检查原始 content 的类型与必需字段；仅声明图片输入但本次没有多模态输出时不适用。是否支持该类型仍以平台接入协议为准。                                                                     |

#### T-ERR 错误处理

| ID         | Checker     | 通过条件                                                                                                                     | 正反示例                                                                                                                      | 级别   | 检查方式与证据来源                                                              |
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------------- |
| `T-ERR-01` | 错误码类型与分类明确  | 工具失败的 `structuredContent.code` 为五位整数：4xxxx 表示参数类，5xxxx 表示业务处理类，6xxxx 表示模型使用类；工具自身不返回预留的 3xxxx 码段。错误码与明确语义匹配，不跨错误类别混用同一码。 | **正例：**&#x53C2;数错误 40001、业务错误 50001、模型使用错误 60001；无权限可使用 50401。<br/>**反例：**&#x8FD4;回 30000、四位码 4001、非整数值，或用同一码表示鉴权失败和上游超时。 | WARN | 实际触发不同错误，检查原始 code 的数值类型、整数值、长度、码段及 message 语义；JSON number 不使用字符串编码。   |
| `T-ERR-02` | 错误原因准确可定位   | 失败必须提供可见原因，明确区分无结果、参数、授权、超时和上游失败；说明应与真实原因一致。                                                                             | **正例：**&#x65E0;订单明确说明无结果，上游超时明确说明超时。<br/>**反例：**&#x6CA1;有原因、统一返回“操作失败”，或把上游超时说成无结果。                                       | FAIL | 对照请求场景、业务执行记录和原始 message/content，核实说明是否准确、可定位。                         |
| `T-ERR-03` | 错误信息无底层泄漏   | 错误返回不包含语言异常、反序列化信息或调用堆栈。                                                                                                 | **正例：**“上游服务暂不可用，请稍后重试。”<br/>**反例：**&#x8FD4;回 NullPointerException、JSON decode error 或完整堆栈。                               | FAIL | 检查原始失败返回的 message 和 content，确认没有向模型或用户暴露底层实现细节。                        |
| `T-ERR-04` | 恢复动作明确      | 失败信息应提供与原因匹配、用户可执行的下一步，不强制固定字段或句式。                                                                                       | **正例：**“登录已过期，请重新登录后重试。”<br/>**反例：**&#x4EC5;写“登录已过期”，没有恢复建议。                                                              | WARN | 实际触发错误分支，检查原始 message/content 中的恢复建议是否可执行并符合错误原因。                      |
| `T-ERR-05` | 前置条件拒绝与错误定位 | 非法输入或真实业务对象不满足已声明状态前置条件时，应阻断业务执行；错误信息指出字段或对象状态、违反的规则，并提供允许范围、实际值或其他可定位原因。                                                | **正例：**&#x4EBA;数只允许 1～8，传 9 时明确拒绝并定位字段；未支付订单退款时指出状态不满足。<br/>**反例：**&#x975E;法输入或对象状态不满足时仍执行并返回成功。                          | FAIL | 构造违反明文约束的请求，或使用状态不满足的真实有效对象调用工具，对照原始错误返回和业务执行结果；对象 ID 应来自真实业务返回。       |
| `T-ERR-06` | 结果与成功失败语义一致 | 真实成功不报失败，真实失败不报成功；批量或复合操作存在部分失败时，不得声称全部成功，不强制固定状态或计数字段。                                                                  | **正例：**&#x6279;量操作部分失败时，明确说明未全部成功及失败项。<br/>**反例：**&#x5B58;在子项失败，顶层仍声称全部成功。                                                | FAIL | 对照原始 isError、content、structuredContent 与业务最终状态、子项结果或后续查询结果，检查成功失败语义一致。 |

#### T-PERF 性能与稳定性

| ID          | Checker  | 通过条件                                                 | 正反示例                                                                              | 级别   | 检查方式与证据来源                                                        |
| ----------- | -------- | ---------------------------------------------------- | --------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------- |
| `T-PERF-01` | 调用响应时长达标 | 搜索列表 P95 不超过 500ms，一般单调用 P95 不超过 5000ms。             | **正例：**&#x641C;索 P95 为 420ms，一般工具 P95 为 3200ms。<br/>**反例：**&#x641C;索 P95 为 760ms。 | FAIL | 在固定测试环境重复直接调用 MCP Server，记录从请求发出到完整响应收到的耗时，统计 P95，并注明网络环境与样本数。   |
| `T-PERF-02` | 限流策略合理   | 重复评测调用不应触发非预期限流；至少支持 5 QPS 的评测调用，命中限流时记录响应码和错误信息。    | **正例：**&#x35; QPS 重复调用未出现非预期限流。<br/>**反例：**&#x8BE5;调用负载下频繁返回限流。                   | WARN | 记录完整的重复调用请求量、并发、响应状态及原始错误信息，核对限流是否符合预期。                          |
| `T-PERF-03` | 重复调用结果稳定 | 相同基线用例重复调用不应同时出现成功与失败；不设置独立的错误率或超时率百分比阈值。            | **正例：**&#x540C;一用例重复调用全部成功。<br/>**反例：**&#x31;00 次调用中 99 次成功、1 次失败，仍存在成败波动。        | FAIL | 固定有效入参和业务前置条件，逐用例统计原始调用状态；限流、登录拒绝等单独记录，超时或服务调用链异常按 T-PERF-04 检查。 |
| `T-PERF-04` | 服务调用链稳定  | 重复调用 MCP Server 时，不应出现非预期超时、连接异常或 Server 所依赖的上游服务异常。 | **正例：**&#x5B8C;整调用记录中没有超时或连接异常。<br/>**反例：**&#x8C03;用超时、连接中断，或 Server 返回上游服务不可用。   | WARN | 直接检查 MCP Server 的请求耗时、HTTP/连接状态与原始错误返回，结合服务端日志定位自身或上游链路问题。       |

#### T-SAFE 安全与副作用

| ID          | Checker    | 通过条件                                                                                                     | 正反示例                                                                                       | 级别   | 检查方式与证据来源                                                                             |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---- | ------------------------------------------------------------------------------------- |
| `T-SAFE-01` | 敏感业务字段标记   | 确需模型提供的密码或密钥类业务字段，建议以扩展字段 `x-sensitive` 标记；缺少标记仅提示风险，不等于已发生明文泄漏。平台身份与诊断参数不得进入业务 Schema，按 T-SCHEMA-02 检查。 | **正例：**&#x4E1A;务 password 字段声明 `x-sensitive=true`。<br/>**反例：**&#x654F;感业务字段未标记，记为建议改进项。    | WARN | 检查 Input Schema 的字段名、description 和敏感标记；是否发生泄漏需另查真实数据传输和返回。                            |
| `T-SAFE-02` | 写操作具备幂等保护  | 非天然幂等写操作建议声明 `idempotency_key`；缺少该固定字段仅提示风险，实际是否幂等应通过重复请求核验。                                             | **正例：**&#x63;reate\_order 提供幂等键，同一键重试只创建一单。<br/>**反例：**&#x672A;声明幂等键，需要进一步核对 Server 的幂等机制。 | WARN | 检查工具名称、description 和 Input Schema；使用相同幂等请求重复调用，并通过原始返回和后续查询确认没有重复副作用。                 |
| `T-SAFE-03` | 登录绑定与预期一致  | description 明确声明无需登录、游客可用或公共数据时，应与 Manifest 中的 `login_type` 保持一致；明确免登录声明与实际登录依赖冲突时提示改进。                  | **正例：**&#x63CF;述无需登录，`login_type=no_login`。<br/>**反例：**&#x63CF;述游客可用，却配置为需要登录的类型。          | WARN | 对照 tools/list 的 description、Manifest 的 login\_type 及实际调用要求，检查明确冲突；未明确免登录的场景结合业务需求判断。  |
| `T-SAFE-04` | 高风险写操作确认保护 | 不可逆写操作建议提供布尔型 `dry_run`、布尔型 `preview` 或字符串 `confirm_token` 中至少一种；缺少这些字段仅提示风险，不等于实际没有确认机制。                | **正例：**&#x64;elete\_account 支持预览或确认令牌。<br/>**反例：**&#x6CA1;有这些字段，需要进一步核对实际确认机制。             | WARN | 检查名称、description 与 Input Schema，核对确认参数的类型及 Server 行为；验证预览不会产生实际副作用，确认条件不满足时不会执行不可逆操作。 |

## 下一步

- [MCP Server 开发](/apps-plugin/docs/skill-development/mcp-server.md)：了解实现、接入和验证流程。
- [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md)：查阅工具定义和返回协议的精确要求。
- [Skill 规范](/apps-plugin/docs/core-concepts/skill-guidelines.md)、[Skill 开发](/apps-plugin/docs/skill-development/overview.md)：了解配套 Skill 的设计与编写方法。
- [卡片设计规范](/apps-plugin/docs/design-principles/card-design.md)、[卡片（Widget）开发](/apps-plugin/docs/frontend-development/widget.md)：在确有展示或交互需要时设计和开发卡片。
- [Manifest 配置规范](/apps-plugin/docs/core-concepts/manifest.md)：查阅工具、实体和卡片配置要求。
