> 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.

# Manifest 配置规范

:::info 提示

**本指南解决什么**：手把手讲清楚豆包应用插件项目根目录中的 `manifest.yaml` 怎么写——包括每个字段的定义与取值、鉴权与索权（scopes）声明，以及卡片固定字段（实体 schema + tool\_card\_binding）的绑定规则。看完即可独立完成一份可上传、可出卡的 Manifest。


:::

## 一、Manifest 是什么

`manifest.yaml` 位于豆包应用插件项目根目录，是项目对接平台的**唯一声明式配置文件（SSOT，Single Source of Truth）**。它把运行所需的元信息、MCP 工具定义、业务实体 schema、卡片绑定关系和权限声明内聚在项目中，**无需在开发者后台做额外配置**——写好 `manifest.yaml`，本地测试通过后打包上传即可。

本文只定义平台接入所需的 Manifest 配置。MCP Server 实际提供的工具定义与 ToolResult 返回要求，以 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md) 为唯一规范来源；开发和接入流程参见 [MCP Server 开发](/apps-plugin/docs/skill-development/mcp-server.md)。

### 产物包目录结构

| 目录 / 文件               | 说明                                          |
| --------------------- | ------------------------------------------- |
| `manifest.yaml`       | 基础配置：app\_key、版本、MCP 工具定义、实体与卡片绑定关系、权限声明等   |
| `package.json`、`src/` | 前端代码包（package.json、src、pages、卡片源码）          |
| `skill/`              | 业务编排说明（SKILL.md，描述模型应如何使用工具），由豆包主 Bot 渐进式加载 |

## 二、Manifest 顶层结构总览

一份完整的 `manifest.yaml` 由以下几个配置块组成，按职责划分：

| 配置块           | 解决的问题                                   | 是否必填         |
| ------------- | --------------------------------------- | ------------ |
| `meta 信息`     | 声明应用插件基础元信息                             | 必填           |
| `tools`       | 声明每个工具的输出类型、可返回实体类型，以及鉴权/登录/权限等运行时配置    | 必填           |
| `entities`    | 声明业务实体 schema、模型可见性、模型可修改性、卡片绑定、历史卡刷新策略 | 出卡场景必填       |
| `mcp_server`  | 声明 MCP Server 接入点、协议、请求头、用户鉴权回调地址       | 接入外部 MCP 时必填 |
| `permissions` | 声明应用插件索取的设备/系统权限（scopes）字典              | 需要端能力时必填     |

## 三、meta 信息定义

放在文件最顶部，声明应用插件身份与版本。

```yaml
manifest_version: 2         # Manifest 协议版本，当前固定为 2
app_key: route-mcp-demo     # 应用插件唯一标识，由平台分配/绑定
name: Route MCP Demo        # 应用插件展示名称
```

| 字段                 | 类型     | 说明                      |
| ------------------ | ------ | ----------------------- |
| `manifest_version` | number | Manifest 协议版本，当前固定为 `2` |
| `app_key`          | string | 应用插件唯一标识，用于版本归属与产物绑定    |
| `name`             | string | 应用插件展示名称                |

## 四、tools：工具定义

`tools` 是一个以「工具名」为 key 的字典。每个工具声明入参 schema、输出类型、可返回的实体类型，以及鉴权、超时、登录、端能力、权限索取等运行时属性。**工具名会作为 `tool_card_binding` 的查找 key**，因此工具名要稳定、语义清晰。

### 4.1 基础字段

```yaml
tools:                       # 业务工具定义（字典，key 为工具名）
  search_routes:
    description: 搜索路线      # 工具描述，供模型理解何时调用
    output:                  # 工具输出类型声明
      kind: entities         # entities | execution_result
      entity_types: [route]  # kind=entities 时，声明允许返回的实体类型
```

| 字段                    | 说明                                                                           |
| --------------------- | ---------------------------------------------------------------------------- |
| `description`         | 工具描述，帮助模型判断何时调用该工具                                                           |
| `output.kind`         | 工具输出类型，取值 `entities`（返回业务实体，可进入出卡链路）或 `execution_result`（返回一次动作/指令的执行结果，不出卡） |
| `output.entity_types` | 仅当 `kind=entities` 时声明；列出该工具允许返回的业务实体类型（须在 `entities` 中有对应定义）                |

:::info 提示

**是否出卡不由工具本身决定**。工具只声明 `output.kind` 和可返回的 `entity_types`；某类实体是否渲染成卡片，取决于该实体的 `tool_card_binding` 是否包含当前工具名。


:::

### 4.2 运行时扩展字段（鉴权 / 登录 / 端能力 / 权限）

在基础字段之外，工具还可声明以下运行时属性，用于控制调用鉴权、超时、登录依赖\`和权限关联：

```yaml
tools:
  search_routes:
    description: 搜索路线
    output:
      kind: entities
      entity_types: [route]
    auth_header_key: 123        # 工具调用鉴权 header key
    request_timeout: 5000       # 请求超时（毫秒）
    connection_timeout: 5000    # 连接超时（毫秒）
    login_type: douyin          # 登录依赖类型
    login_params: [field1, field2]  # 需要获取的登录信息字段
    tool_permissions:           # 工具级权限关联（索取的 scopes）
      - scope_name: scope.userLocation
        priority: 1
        is_must_need: true      # 强关联：缺失该权限则工具不可用
      - scope_name: scope.record
        priority: 1
        is_must_need: false     # 弱关联：缺失该权限工具仍可降级运行
```

| 字段                   | 说明                                      |
| -------------------- | --------------------------------------- |
| `auth_header_key`    | 工具调用时使用的鉴权 header key                   |
| `request_timeout`    | 请求超时时间，单位毫秒                             |
| `connection_timeout` | 连接超时时间，单位毫秒                             |
| `login_type`         | 登录依赖类型，见下方枚举                            |
| `login_params`       | 登录后需要获取的用户信息字段列表，见下方枚举                  |
| `tool_permissions`   | 工具级权限索取，声明该工具运行需要哪些 scopes，见「第六章 鉴权与索权」 |
| `visibility`         | 工具调用入口可见性，控制工具结果可被哪些消费方使用，见下方说明         |

#### visibility：工具调用入口可见性

`visibility` 声明工具的调用入口可见性，即哪些消费方可以调用该工具。它是一个字符串数组，缺省等价于 `["model"]`。

| 取值      | 含义                                           |
| ------- | -------------------------------------------- |
| `model` | 工具对模型可见。**必须包含**                             |
| `app`   | 工具对 App 可见，允许通过 CallTool（JSB）从端侧直接调用该工具并获取结果 |

```yaml
tools:
  search_routes:
    description: 搜索路线
    output:
      kind: entities
      entity_types: [route]
    visibility: [model, app]    # 模型和 App 均可调用

  internal_audit:
    description: 内部审计（仅模型调用）
    output:
      kind: execution_result
    # visibility 缺省，等价于 [model]
```

**约束规则**：

- `visibility` 必须包含 `model`，否则校验失败
- 不能出现重复取值
- 配置了 `app` 时，该工具不能是客户端工具（`is_client_tool` 不能为 `true`）
- 配置了 `app` 时，不能声明 `tool_permissions`（App 可见工具不支持工具级索权）

**与 CallTool 的关系**：

卡片 CallTool（端侧 JSB 调用工具）要求工具的 `visibility` 包含 `app`。若未包含，调用时会返回 `CALL_TOOL_APP_CALL_NOT_ENABLED` 错误。仅需模型调用的工具无需配置 `app`。

#### login\_type 枚举

- `douyin`：抖音登录
- `douyin_weak`：抖音登录（弱依赖，登录失败仍可降级运行）
- `normal`：普通登录
- `no_login`：无需登录

#### login\_params 枚举

- `user_base_info`：用户基础信息（头像、昵称等）
- `soda_music_info`：汽水音乐收藏列表
- `user_mobile`：用户手机号

### 4.3 output.kind：两种输出类型


:::info 提示
**kind: entities**
工具返回业务实体集合 `structuredContent.entities`。实体可用于出卡（命中 tool\_card\_binding 时），或仅作模型参考。
:::

:::info 提示
**kind: execution\_result**
工具返回一次动作/指令的执行结果 object。不生成实体、不进入卡片渲染链路，模型直接消费结果文本。
:::

```yaml
tools:
  search_routes:          # 实体集合型：可出卡
    output:
      kind: entities
      entity_types: [route]

  start_navigation:       # 执行结果型：不出卡
    output:
      kind: execution_result
```

## 五、entities：业务实体与卡片固定字段绑定

`entities` 是以「实体类型名」为 key 的字典，用于声明业务实体的字段 schema、模型可见性、模型可修改性、卡片模板绑定以及历史卡刷新策略。它是「卡片固定字段绑定」的核心配置块。

### 5.1 entity 的四个同级配置项

| 配置项                    | 说明                                                                       |
| ---------------------- | ------------------------------------------------------------------------ |
| `schema`               | 实体字段 schema，描述业务字段类型、语义、模型可见性、模型可修改性，以及用 `is_entity_id` 标记的稳定业务 ID 字段    |
| `tool_card_binding`    | 卡片渲染绑定，与 `schema` 同级。**key 是工具名，value 是该工具返回该实体时使用的 card\_template\_id** |
| `history_card_refresh` | 卡片生命周期配置（可选），与 `schema` 同级。声明该实体出卡时是否刷新历史同刷新键旧卡                          |

### 5.2 schema：字段定义

schema 中每个字段用 `{ type: ..., description: ..., ... }` 描述。字段级可用属性如下：

| 字段级属性                  | 说明                                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                 | 字段类型：`string` / `number` / `int` / `boolean` / `object` / `array`                                                                                       |
| `description`          | 字段语义说明，用于平台校验和模型理解                                                                                                                                      |
| `is_entity_id: true`   | 标记该业务字段为实体的稳定业务 ID。**字段名可自定义**（示例用 entity\_id，也可叫 route\_id、song\_id 等）                                                                                 |
| `is_refresh_key: true` | 标记该字段为卡片刷新键。卡片下发时，该字段的值会作为卡片的 `refresh_key`；服务端可通过「刷新卡片实例」API 用相同的 `refresh_key` 更新卡片数据。同一实体 schema 内最多一个字段可被标记为刷新键，允许位于顶层或 object 内，不能位于 array items 内 |
| `llm_visible`          | 是否投影给模型，**默认 true**。仅不希望进入模型上下文的字段（如 entity\_type、deeplink）才显式设为 false                                                                                  |
| `llm_modifiable`       | 是否允许模型修改字段内容，**默认 false**。首期仅支持 `type: array` 的列表字段，语义为「模型可对列表内容做筛选」                                                                                    |

:::info 提示

**字段用途由 Manifest 决定，不由业务返回表达。**`entity.schema` 是模型与平台侧的字段契约，不是卡片数据的透传白名单。需要被模型感知或参与模型处理的业务字段，必须在 `schema` 中显式定义；未在 `schema` 中声明的业务字段不会进入模型上下文，但不会被过滤或丢弃，仍会随实体数据正常透传给卡片，由对应的卡片前端代码消费。字段是否对模型可见、是否允许模型筛选，以及实体使用哪张卡片，统一由 Manifest 声明。业务返回只表达业务事实，不应包含平台内部生成的运行时标识、内部路由字段或卡片模板配置。


:::

### 5.3 tool\_card\_binding：卡片固定字段绑定

这是「卡片固定字段绑定」的关键。它声&#x660E;**「哪个工具返回哪类实体 → 用哪张卡片模板渲染」**：

- **key** = 工具名（如 `search_routes`）
- **value** = 该工具返回该实体时使用的 `card_template_id`（如 `tpl_route_card`）

运行时平台用「当前工具名 + entity\_type」查到对应模板。同一个 entity\_type 可以按不同工具名绑定不同卡片模板。模板由业务前端包或平台卡片代码注册，Manifest 只引用模板 ID，**不内联模板定义，也不描述字段映射**。

```yaml
tool_card_binding:                    # 与 schema 同级
  search_routes: tpl_route_card       # 搜索路线工具 → 用路线卡
  get_routes_detail: tpl_route_detail_card  # 路线详情工具 → 用详情卡
```

:::info 提示

**「固定字段绑定」的边界**：Manifest 只固定「实体类型 → 卡片模板」这层绑定关系。至于卡片上哪个字段放标题、哪个放价格、按钮点击拼什么参数、列表如何排序截断，全部由 `card_template_id` 对应的**业务卡片前端代码**处理，不在 Manifest 中声明。


:::

### 5.4 完整 entity 示例

```yaml
entities:
  route:
    schema:
      entity_id: { type: string, description: 路线业务 ID, is_entity_id: true, is_refresh_key: true }
      entity_type: { type: string, description: 业务实体类型, llm_visible: false }
      title: { type: string, description: 路线标题 }
      origin_name: { type: string, description: 起点名称 }
      destination_name: { type: string, description: 终点名称 }
      duration_minutes: { type: number, description: 预计耗时分钟数 }
      price_yuan: { type: number, description: 预估价格元 }
      mode: { type: string, description: 出行方式 }
      summary: { type: string, description: 路线摘要 }
      selection_reason: { type: string, description: 推荐理由 }
      deeplink: { type: string, description: 应用插件跳转链接, llm_visible: false }
    tool_card_binding:
      search_routes: tpl_route_card
    history_card_refresh:
      enabled: true
      scope: same_conversation
      refresh_to: fixed_style
```

### 5.5 列表实体与 llm\_modifiable

当实体包含数组字段（如商品候选列表），且希望模型能从列表中筛选出要展示的子集时，在该数组字段上声明 `llm_modifiable: true`。首期该能力**仅支持列表字段的筛选**——模型只能从原始 item 中选出子集，不能新增 item、不能改写 item 字段值。

```yaml
entities:
  product_list:
    schema:
      entity_id: { type: string, description: 商品列表业务 ID, is_entity_id: true, is_refresh_key: true }
      entity_type: { type: string, description: 业务实体类型, llm_visible: false }
      title: { type: string, description: 列表标题 }
      summary: { type: string, description: 列表摘要 }
      products:
        type: array
        description: 商品候选列表
        llm_modifiable: true      # 允许模型对该列表做筛选
        items:
          type: object
          properties:
            product_id: { type: string, description: 商品 ID }
            name: { type: string, description: 商品名称 }
            selling_point: { type: string, description: 推荐理由 }
            price_yuan: { type: number, description: 商品价格 }
    tool_card_binding:
      search_products: tpl_product_list_card
```

### 5.6 嵌套 schema

schema 支持递归定义 `object` 与 `array`，可表达起终点、地址、途经站点等结构化子对象。嵌套字段同样遵循 `llm_visible` / `llm_modifiable` 规则。

| 字段形态   | schema 写法                                                                                           |
| ------ | --------------------------------------------------------------------------------------------------- |
| 对象     | `type: object` + `properties`：用于起终点、地址、联系人等结构化子对象                                                   |
| 基础类型数组 | `type: array` + `items.type`：用于标签、关键词等基础类型列表                                                        |
| 对象数组   | `items.type: object` + `properties`：用于列表卡 item、途经站点、商品明细等；配 `llm_modifiable: true` 时 item 会被打平为模型候选 |

### 5.7 history\_card\_refresh：历史同刷新键卡片刷新

可选配置，声明「该实体作为卡片返回时，如何处理同一会话历史消息中同刷新键的旧卡」。它属于平台卡片生命周期策略，不属于业务 schema，业务 ToolResult 也不需要返回。

```yaml
history_card_refresh:
  enabled: true               # 是否开启历史卡刷新
  scope: same_conversation    # 刷新范围：首期仅支持同一会话
  refresh_to: fixed_style     # 旧卡刷新为平台固定历史态样式
```

| 字段           | 建议取值                | 说明                                |
| ------------ | ------------------- | --------------------------------- |
| `enabled`    | `true` / `false`    | 是否开启。未配置或 false 时不触发历史卡刷新         |
| `scope`      | `same_conversation` | 刷新范围，首期仅支持同一会话内历史消息               |
| `refresh_to` | `fixed_style`       | 旧卡刷新为平台固定历史态样式（由平台控制，业务无需实现历史态模板） |

:::info 提示

**匹配键**来自 `is_refresh_key=true` 标记的字段值，按「app\_key + refresh\_key」语义匹配同一会话内的历史卡片。仅当新卡真正出卡（命中 tool\_card\_binding）时才生效；仅作模型参考的实体不触发。实体 schema 中必须声明 `is_refresh_key` 字段才能使用历史卡刷新。


:::

:::info 提示

**`history_card_refresh` 与「刷新卡片实例」API 的区别**：两者都基于 `is_refresh_key` 标记的刷新键匹配卡片，但触发方式和作用范围不同：

- `history_card_refresh`：平台卡片生命周期策略，**同一会话内**新卡出卡时自动刷新同刷新键的旧卡为固定历史态样式。
- 「刷新卡片实例」API：服务端主动调用，可**跨用户、跨会话**更新所有匹配刷新键的卡片数据。

两者可同时使用。


:::

## 六、鉴权与索权（scopes）

豆包应用插件的鉴权与索权分为三个层面：**工具调用鉴权**（tools 内的鉴权字段）、**MCP Server 鉴权**（mcp\_server 配置）、**设备/系统权限索取**（permissions 字典 + tool\_permissions 关联）。

### 6.1 permissions：权限字典定义

`permissions` 是一个数组，集中声明应用插件会用到的所有 scopes。每一项定义权限名、描述和类型。工具通过 `tool_permissions` 引用这里声明的 `scope_name`。

```yaml
permissions:
  - scope_name: scope.addPhoneCalendar
    description: 日历权限
    type: JSB
  - scope_name: scope.camera
    description: 相机权限
    type: JSB
  - scope_name: scope.userLocation
    description: 精确定位权限
    type: Tool
  - scope_name: scope.record
    description: 录音权限
    type: Tool
```

| 字段            | 说明                                            |
| ------------- | --------------------------------------------- |
| `scope_name`  | 权限名，取值见下方 scope\_name 枚举                      |
| `description` | 权限用途描述，用于向用户展示索权理由                            |
| `type`        | 权限类型：`JSB`（通过端能力 JSBridge 调用）或 `Tool`（通过工具调用） |

#### scope\_name 枚举

- `scope.userLocation`：精确定位权限
- `scope.userFuzzyLocation`：模糊定位权限
- `scope.userLocationBackground`：后台持续定位权限
- `scope.record`：录音权限（麦克风）
- `scope.bluetooth`：蓝牙权限
- `scope.addPhoneCalendar`：日历权限
- `scope.camera`：相机权限

### 6.2 tool\_permissions：工具级索权关联

在工具定义中通过 `tool_permissions` 声明该工具运行需要哪些权限，并标记强/弱关联。每项引用 `permissions` 字典中声明的 `scope_name`。

```yaml
tool_permissions:
  - scope_name: scope.userLocation
    priority: 1
    is_must_need: true      # 强关联：缺失该权限工具不可用
  - scope_name: scope.record
    priority: 1
    is_must_need: false     # 弱关联：缺失该权限工具仍可降级运行
```

| 字段             | 说明                                                        |
| -------------- | --------------------------------------------------------- |
| `scope_name`   | 引用 permissions 中声明的权限名                                    |
| `priority`     | 权限优先级（数值越小优先级越高）                                          |
| `is_must_need` | **强/弱关联标记**：`true` 表示强关联（缺失则工具不可用），`false` 表示弱关联（缺失可降级运行） |

### 6.3 mcp\_server：MCP Server 与用户鉴权

当应用插件对接外部 MCP Server 时，通过 `mcp_server` 声明接入点、通信协议、请求头鉴权和用户鉴权回调地址。

```yaml
mcp_server:
  end_point: https://developer.doubao.com/demo/mcp/delivery
  description: 打车 mcp
  mcp_config:
    headers:                 # 调用 MCP Server 时注入的请求头
      - key: auth1
        source: constant     # 来源：constant 表示固定值
        value: 1
      - key: auth2
        source: constant
        value: 2
    protocol: Streamable      # 协议：Streamable | SSE
  user_auth:                  # 用户鉴权回调地址（三方账号与豆包身份绑定）
    fetch_token_url: http://123.com     # 获取用户 token
    refresh_token_url: http://123.com   # 刷新用户 token
    delete_userinfo_url: http://123.com # 删除用户信息
```

| 字段                              | 说明                                                    |
| ------------------------------- | ----------------------------------------------------- |
| `end_point`                     | MCP Server 接入地址                                       |
| `description`                   | MCP Server 描述                                         |
| `mcp_config.headers`            | 调用时注入的请求头列表；每项含 `key`、`source`（来源，如 constant）、`value` |
| `mcp_config.protocol`           | 通信协议，取值 `Streamable` 或 `SSE`                          |
| `user_auth.fetch_token_url`     | 获取用户 token 的回调地址                                      |
| `user_auth.refresh_token_url`   | 刷新用户 token 的回调地址                                      |
| `user_auth.delete_userinfo_url` | 删除用户信息的回调地址（用于合规注销）                                   |

:::info 提示

豆包采用**云端 MCP** 模式：开发者需自行实现账号登录与身份绑定（绑定豆包 OpenID 与三方系统账号），用户凭证与豆包身份绑定并存储在云端。`user_auth` 三个回调地址即用于该套鉴权/注销链路。


:::

## 七、Manifest 与工具返回的对应关系

Manifest 负责声明工具输出类型以及平台如何解释结构化结果，不定义 MCP ToolResult 本身。业务 MCP Server 的 `content`、`structuredContent`、`isError` 以及实体、执行结果和错误返回结构，统一遵循 [MCP Server 协议规范](/apps-plugin/docs/skill-development/mcp-server-protocol.md)。

| Manifest 声明                    | 对应的工具返回 | 一致性要求                                     |
| ------------------------------ | ------- | ----------------------------------------- |
| `output.kind=entities`         | 实体集合返回  | `entity_types`、实体类型、稳定业务 ID 和字段类型必须覆盖实际返回 |
| `output.kind=execution_result` | 执行结果返回  | `structuredContent` 直接表达操作结果，不使用实体集合包装    |
| 错误分支不单独配置 `output.kind`        | 工具执行错误  | 任一类型的工具失败时，都按照 13.1 返回错误分支                |

**配置与返回必须一致。**&#x5DE5;具名称、输出类型、实体类型、Schema 字段和稳定 ID 声明必须与 MCP Server 的实际工具及返回保持一致。Manifest 不能替代业务工具返回，业务工具也不能在返回中携带 `kind` 或卡片模板配置来替代 Manifest。

**卡片按场景选配。**&#x5B9E;体返回不等于一定展示卡片；只有配置了对应卡片产物和 `tool_card_binding` 时才建立展示关联。没有卡片时，合法的实体结果仍可供模型理解和后续调用。

## 八、完整 Manifest 示例

下面的整合示例覆盖：meta 信息、普通实体出卡工具、列表筛选工具、执行结果工具、MCP Server、权限字典与工具级索权。可直接作为接入模板参考。

```yaml
manifest_version: 2
app_key: demo-mcp
name: Demo MCP
version: 1.0.0

# ============ MCP Server ============
mcp_server:
  end_point: https://developer.doubao.com/demo/mcp/delivery
  description: 示例 mcp
  mcp_config:
    headers:
      - key: auth1
        source: constant
        value: 1
    protocol: Streamable
  user_auth:
    fetch_token_url: https://example.com/fetch_token
    refresh_token_url: https://example.com/refresh_token
    delete_userinfo_url: https://example.com/delete_userinfo

# ============ 工具定义 ============
tools:
  search_routes:
    description: 搜索路线
    input_schema:
      type: object
      properties:
        origin: { type: string }
        destination: { type: string }
      required: [origin, destination]
    output:
      kind: entities
      entity_types: [route]
    # visibility 缺省，等价于 [model]：仅模型可调用（因声明了 tool_permissions，不能配置 app）
    login_type: douyin
    login_params: [user_base_info]
    tool_permissions:
      - scope_name: scope.userLocation
        priority: 1
        is_must_need: true

  search_products:
    description: 搜索商品
    output:
      kind: entities
      entity_types: [product_list]
    visibility: [model, app]    # 模型和 App 均可调用，无 tool_permissions

  start_navigation:
    description: 发起导航
    output:
      kind: execution_result
    visibility: [model, app]

# ============ 业务实体与卡片绑定 ============
entities:
  route:
    schema:
      entity_id: { type: string, description: 路线业务 ID, is_entity_id: true, is_refresh_key: true }
      entity_type: { type: string, description: 业务实体类型, llm_visible: false }
      title: { type: string, description: 路线标题 }
      duration_minutes: { type: number, description: 预计耗时分钟数 }
      price_yuan: { type: number, description: 预估价格元 }
      summary: { type: string, description: 路线摘要 }
      deeplink: { type: string, description: 应用插件跳转链接, llm_visible: false }
    tool_card_binding:
      search_routes: tpl_route_card
    history_card_refresh:
      enabled: true
      scope: same_conversation
      refresh_to: fixed_style

  product_list:
    schema:
      entity_id: { type: string, description: 商品列表业务 ID, is_entity_id: true, is_refresh_key: true }
      entity_type: { type: string, description: 业务实体类型, llm_visible: false }
      title: { type: string, description: 列表标题 }
      summary: { type: string, description: 列表摘要 }
      products:
        type: array
        description: 商品候选列表
        llm_modifiable: true
        items:
          type: object
          properties:
            product_id: { type: string, description: 商品 ID }
            name: { type: string, description: 商品名称 }
            selling_point: { type: string, description: 推荐理由 }
            price_yuan: { type: number, description: 商品价格 }
    tool_card_binding:
      search_products: tpl_product_list_card

# ============ 权限字典 ============
permissions:
  - scope_name: scope.userLocation
    description: 精确定位权限
    type: Tool
  - scope_name: scope.camera
    description: 相机权限
    type: JSB
```

## 九、验证与交付

完成 `manifest.yaml` 后，应先验证配置之间以及配置与实际能力之间的一致性，再进入本地联调和版本交付。

| 检查项           | 要求                                         |
| ------------- | ------------------------------------------ |
| MCP Server 接入 | 接入地址和通信配置与已部署服务一致，目标环境可以访问                 |
| 工具声明          | 工具名称、输入 Schema 和输出类型与 MCP Server 实际提供的工具一致 |
| 实体声明          | 实体类型、字段类型和稳定业务 ID 能覆盖 13.1 规定的实际返回         |
| 卡片关联          | 仅在选配卡片时声明绑定关系，绑定的工具、实体和卡片产物保持一致            |
| 权限引用          | 工具引用的权限已在权限字典中声明，强弱依赖符合真实业务效果              |

本文不重复容易随开发工具版本变化的调试和上传命令。具体本地联调流程参见 [本地调试与预览](/apps-plugin/docs/development-tools/local-debugging.md)，打包与版本交付参见 [打包与提审](/apps-plugin/docs/release/package-and-submit.md)。

## 十、配置速查清单

| 配置项                                  | 所属块         | 要点                                                                        |
| ------------------------------------ | ----------- | ------------------------------------------------------------------------- |
| manifest\_version                    | meta        | 固定为 2                                                                     |
| app\_key / name                      | meta        | 应用插件身份                                                                    |
| tools.\*.input\_schema               | tools       | 工具入参 JSON Schema                                                          |
| tools.\*.output.kind                 | tools       | entities 或 execution\_result                                              |
| tools.\*.visibility                  | tools       | 调用入口可见性，取值 model（必填）/ app，缺省 \[model]                                     |
| tools.\*.login\_type / login\_params | tools       | 登录依赖与需获取的用户信息                                                             |
| tools.\*.tool\_permissions           | tools       | 工具级索权，is\_must\_need 标记强/弱关联                                              |
| entities.\*.schema                   | entities    | 字段定义 + is\_entity\_id + is\_refresh\_key + llm\_visible + llm\_modifiable |
| entities.\*.tool\_card\_binding      | entities    | 工具名 → card\_template\_id（卡片固定字段绑定）                                        |
| entities.\*.history\_card\_refresh   | entities    | 历史同刷新键卡刷新（可选）                                                             |
| mcp\_server                          | mcp\_server | 接入点、协议、headers、user\_auth                                                 |
| permissions                          | permissions | scopes 字典：scope\_name + description + type                                |
