卡片(Widget)开发
Widget 是展示在豆包对话中的轻量视图,适合承载 MCP Tool 返回的结构化结果、确认操作和下一步入口。一个完整的出卡链路包括 Widget 注册、业务实体协议、MCP Tool 与 Widget 绑定,以及 Widget 对 View Data 的渲染。
开发流程
按下面的顺序开发和检查:
- 在
src/app.config.ts注册 Widget 入口和稳定的widget_id; - 根据展示场景选择模板,在 Widget 代码中把 View Data 映射为模板 Props;
- 在
manifest.yaml声明 MCP Tool 输出的实体类型,并通过tool_card_binding绑定widget_id; - 让 MCP Tool 按协议返回
structuredContent.entities; - 在 Web 模拟器中预览 Widget,再检查 MCP Tool、实体和出卡协议组成的完整链路;
选择和安装模板
当前文档版本的 @doubao-dev/template 提供以下模板。实际开发时,以项目已安装版本导出的组件和 TypeScript 类型为准:
模板选型、通用约定和各模板完整示例见卡片模板。
项目尚未安装模板包时执行:
模板以 npm 包和 TypeScript 类型提供,不需要下载源码。模板的可用 Props 以已安装包的类型声明为准,实际渲染和交互在 Web 模拟器中预览。
注册 Widget
在 src/app.config.ts 中声明 Widget。id 是 Manifest 和调试工具引用的 widget_id,必须在应用内全局唯一,
发布后不应随意修改。重复 ID 会导致构建失败,需要为对应入口配置不同的 id。
entry 对应 src/widgets/order-card/index.tsx。如果使用字符串简写,框架会根据入口推导 id;需要与 Manifest 长期绑定时,建议显式声明 id。
把 View Data 映射到模板
Manifest 不负责把业务字段逐一映射到模板 Props。字段选择、格式化、空态和点击行为都应在 Widget 的 TypeScript 代码中完成。
映射时重点处理:
- 为模板列表项提供稳定的
key; - 对可选字段提供空态或省略策略;
- 在进入模板前完成金额、日期和状态等业务格式化;
- 需要响应宿主数据更新时使用
useViewData<T>(); - Widget 根节点直接返回模板,避免增加没有必要的布局容器;
上面的 onClick 展示了一条完整的前端联动路径:Widget 从 View Data 读取稳定业务 ID,用户点击模板项后通过 navigateTo 打开 Page,并只在 URL 中传递定位业务对象所需的参数。
配置出卡协议
下面的 Manifest 片段表示:query_order MCP Tool 返回 order 实体时,使用 order-card Widget 渲染。
MCP Tool 成功结果使用 MCP ToolResult 结构:
能够出卡需要同时满足:
- MCP Tool 在 Manifest 中声明
output.kind: entities,并包含返回的实体类型; - ToolResult 的业务数据位于
structuredContent.entities; - 每个实体都包含匹配的
entity_type和被is_entity_id: true标记的稳定业务 ID; tool_card_binding的 key 是实际 MCP Tool 名,value 是app.config.ts中注册的widget_id;- Widget 代码能够处理实体实际返回的字段和空值;
tool_card_binding 只决定“使用哪个 Widget”,不声明模板名称,也不承担字段到 UI 的映射。
预览与验证
Widget 需要分别验证视图和出卡链路:
出现“MCP Tool 已执行但没有卡片”时,先检查 ToolResult 和 Manifest;卡片已出现但内容或样式错误时,再检查 Widget 的字段映射和 Lynx 样式。调试工具显示请求已发送,不代表卡片已经完成渲染,最终以 Web 模拟器中的实际结果为准。
开发服务启动、Widget 选择、测试数据注入和链路日志查看方式见开发工具文档。
完成检查
app.config.ts中的 Widget id、Manifest 中的tool_card_binding和调试目标使用同一个值;- ToolResult 的
structuredContent.entities与 Manifest schema 一致; - Widget 能处理必填字段缺失、可选字段为空和宿主数据更新;
- 模板项点击后能够打开目标 Page,路由参数可以被目标 Page 读取;
- 已在 Web 模拟器中验证实际渲染,并完成 MCP Tool 到 Widget 的完整出卡链路验证;