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, and this page is available as Markdown at /apps-plugin/docs/core-concepts/manifest.md.

Manifest 配置规范

提示

本指南解决什么:手把手讲清楚豆包应用插件项目根目录中的 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 协议规范 为唯一规范来源;开发和接入流程参见 MCP Server 开发。

产物包目录结构

目录 / 文件说明
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 信息定义

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

manifest_version: 2         # Manifest 协议版本,当前固定为 2
app_key: route-mcp-demo     # 应用插件唯一标识,由平台分配/绑定
name: Route MCP Demo        # 应用插件展示名称
字段类型说明
manifest_versionnumberManifest 协议版本,当前固定为 2
app_keystring应用插件唯一标识,用于版本归属与产物绑定
namestring应用插件展示名称

四、tools:工具定义

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

4.1 基础字段

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 中有对应定义)
提示

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

4.2 运行时扩展字段(鉴权 / 登录 / 端能力 / 权限)

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

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)从端侧直接调用该工具并获取结果
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:两种输出类型

提示

kind: entities 工具返回业务实体集合 structuredContent.entities。实体可用于出卡(命中 tool_card_binding 时),或仅作模型参考。

提示

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

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 的列表字段,语义为「模型可对列表内容做筛选」
提示

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

5.3 tool_card_binding:卡片固定字段绑定

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

  • key = 工具名(如 search_routes)
  • value = 该工具返回该实体时使用的 card_template_id(如 tpl_route_card)

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

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

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

5.4 完整 entity 示例

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 字段值。

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 也不需要返回。

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

匹配键来自 is_refresh_key=true 标记的字段值,按「app_key + refresh_key」语义匹配同一会话内的历史卡片。仅当新卡真正出卡(命中 tool_card_binding)时才生效;仅作模型参考的实体不触发。实体 schema 中必须声明 is_refresh_key 字段才能使用历史卡刷新。

提示

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。

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。

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 声明接入点、通信协议、请求头鉴权和用户鉴权回调地址。

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_pointMCP Server 接入地址
descriptionMCP 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删除用户信息的回调地址(用于合规注销)
提示

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

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

Manifest 负责声明工具输出类型以及平台如何解释结构化结果,不定义 MCP ToolResult 本身。业务 MCP Server 的 content、structuredContent、isError 以及实体、执行结果和错误返回结构,统一遵循 MCP Server 协议规范。

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

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

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

八、完整 Manifest 示例

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

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 规定的实际返回
卡片关联仅在选配卡片时声明绑定关系,绑定的工具、实体和卡片产物保持一致
权限引用工具引用的权限已在权限字典中声明,强弱依赖符合真实业务效果

本文不重复容易随开发工具版本变化的调试和上传命令。具体本地联调流程参见 本地调试与预览,打包与版本交付参见 打包与提审。

十、配置速查清单

配置项所属块要点
manifest_versionmeta固定为 2
app_key / namemeta应用插件身份
tools.*.input_schematools工具入参 JSON Schema
tools.*.output.kindtoolsentities 或 execution_result
tools.*.visibilitytools调用入口可见性,取值 model(必填)/ app,缺省 [model]
tools.*.login_type / login_paramstools登录依赖与需获取的用户信息
tools.*.tool_permissionstools工具级索权,is_must_need 标记强/弱关联
entities.*.schemaentities字段定义 + is_entity_id + is_refresh_key + llm_visible + llm_modifiable
entities.*.tool_card_bindingentities工具名 → card_template_id(卡片固定字段绑定)
entities.*.history_card_refreshentities历史同刷新键卡刷新(可选)
mcp_servermcp_server接入点、协议、headers、user_auth
permissionspermissionsscopes 字典:scope_name + description + type