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 顶层结构总览
一份完整的 manifest.yaml 由以下几个配置块组成,按职责划分:
放在文件最顶部,声明应用插件身份与版本。
manifest_version: 2 # Manifest 协议版本,当前固定为 2
app_key: route-mcp-demo # 应用插件唯一标识,由平台分配/绑定
name: Route MCP Demo # 应用插件展示名称
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 时,声明允许返回的实体类型
提示
是否出卡不由工具本身决定。工具只声明 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 # 弱关联:缺失该权限工具仍可降级运行
visibility:工具调用入口可见性
visibility 声明工具的调用入口可见性,即哪些消费方可以调用该工具。它是一个字符串数组,缺省等价于 ["model"]。
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 的四个同级配置项
5.2 schema:字段定义
schema 中每个字段用 { type: ..., description: ..., ... } 描述。字段级可用属性如下:
提示
字段用途由 Manifest 决定,不由业务返回表达。entity.schema 是模型与平台侧的字段契约,不是卡片数据的透传白名单。需要被模型感知或参与模型处理的业务字段,必须在 schema 中显式定义;未在 schema 中声明的业务字段不会进入模型上下文,但不会被过滤或丢弃,仍会随实体数据正常透传给卡片,由对应的卡片前端代码消费。字段是否对模型可见、是否允许模型筛选,以及实体使用哪张卡片,统一由 Manifest 声明。业务返回只表达业务事实,不应包含平台内部生成的运行时标识、内部路由字段或卡片模板配置。
这是「卡片固定字段绑定」的关键。它声明「哪个工具返回哪类实体 → 用哪张卡片模板渲染」:
- 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 规则。
5.7 history_card_refresh:历史同刷新键卡片刷新
可选配置,声明「该实体作为卡片返回时,如何处理同一会话历史消息中同刷新键的旧卡」。它属于平台卡片生命周期策略,不属于业务 schema,业务 ToolResult 也不需要返回。
history_card_refresh:
enabled: true # 是否开启历史卡刷新
scope: same_conversation # 刷新范围:首期仅支持同一会话
refresh_to: fixed_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.userLocation:精确定位权限
scope.userFuzzyLocation:模糊定位权限
scope.userLocationBackground:后台持续定位权限
scope.record:录音权限(麦克风)
scope.bluetooth:蓝牙权限
scope.addPhoneCalendar:日历权限
scope.camera:相机权限
在工具定义中通过 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 # 弱关联:缺失该权限工具仍可降级运行
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 # 删除用户信息
提示
豆包采用云端 MCP 模式:开发者需自行实现账号登录与身份绑定(绑定豆包 OpenID 与三方系统账号),用户凭证与豆包身份绑定并存储在云端。user_auth 三个回调地址即用于该套鉴权/注销链路。
七、Manifest 与工具返回的对应关系
Manifest 负责声明工具输出类型以及平台如何解释结构化结果,不定义 MCP ToolResult 本身。业务 MCP Server 的 content、structuredContent、isError 以及实体、执行结果和错误返回结构,统一遵循 MCP Server 协议规范。
配置与返回必须一致。工具名称、输出类型、实体类型、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 后,应先验证配置之间以及配置与实际能力之间的一致性,再进入本地联调和版本交付。
本文不重复容易随开发工具版本变化的调试和上传命令。具体本地联调流程参见 本地调试与预览,打包与版本交付参见 打包与提审。
十、配置速查清单