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

# 卡片（Widget）开发

Widget 是展示在豆包对话中的轻量视图，适合承载 MCP Tool 返回的结构化结果、确认操作和下一步入口。一个完整的出卡链路包括 Widget 注册、业务实体协议、MCP Tool 与 Widget 绑定，以及 Widget 对 View Data 的渲染。

## 开发流程

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 48, "rankSpacing": 40, "htmlLabels": true}}}%%
flowchart TB
  CONFIG["app.config.ts<br/>注册 widget_id"] --> CODE["Widget 代码<br/>映射数据并选择模板"]
  TOOL["MCP Tool<br/>返回 entities"] --> MANIFEST["manifest.yaml<br/>绑定 MCP Tool、entity 与 widget_id"]
  MANIFEST --> CARD["豆包宿主匹配并展示卡片"]
  CODE --> CARD

  classDef config fill:#FFF4E5,stroke:#D97706,color:#7C2D12;
  classDef runtime fill:#ECFDF3,stroke:#299764,color:#14532D;
  classDef view fill:#EEF4FF,stroke:#4C6FFF,color:#172B4D;
  class CONFIG,MANIFEST config;
  class TOOL runtime;
  class CODE,CARD view;
```

按下面的顺序开发和检查：

1. 在 `src/app.config.ts` 注册 Widget 入口和稳定的 `widget_id`；
2. 根据展示场景选择模板，在 Widget 代码中把 View Data 映射为模板 Props；
3. 在 `manifest.yaml` 声明 MCP Tool 输出的实体类型，并通过 `tool_card_binding` 绑定 `widget_id`；
4. 让 MCP Tool 按协议返回 `structuredContent.entities`；
5. 在 Web 模拟器中预览 Widget，再检查 MCP Tool、实体和出卡协议组成的完整链路；

## 选择和安装模板

当前文档版本的 `@doubao-dev/template` 提供以下模板。实际开发时，以项目已安装版本导出的组件和 TypeScript 类型为准：

| 模板                                                                    | 适合的场景                |
| --------------------------------------------------------------------- | -------------------- |
| [`ContentCard`](/apps-plugin/docs/templates/content-card.md)          | 商品、服务、内容入口等通用列表      |
| [`PriceActionCard`](/apps-plugin/docs/templates/price-action-card.md) | 报价、权益、服务方案等带价格和操作的列表 |
| [`CheckoutCard`](/apps-plugin/docs/templates/checkout-card.md)        | 商品或服务的下单、支付确认        |
| [`TransitCard`](/apps-plugin/docs/templates/transit-card.md)          | 航班、列车、大巴等交通方案列表      |
| [`MapCard`](/apps-plugin/docs/templates/map-card.md)                  | 路线预估、叫车状态、位置详情       |
| [`CompositeCard`](/apps-plugin/docs/templates/composite-card.md)      | 在一个业务语义中组合多个模板已知模块   |
| [`AskHumanCard`](/apps-plugin/docs/templates/ask-human-card.md)       | 让用户在多个候选项中确认选择       |

模板选型、通用约定和各模板完整示例见[卡片模板](/apps-plugin/docs/templates/index.md)。

项目尚未安装模板包时执行：

```bash
pnpm add @doubao-dev/template
```

模板以 npm 包和 TypeScript 类型提供，不需要下载源码。模板的可用 Props 以已安装包的类型声明为准，实际渲染和交互在 Web 模拟器中预览。

## 注册 Widget

在 `src/app.config.ts` 中声明 Widget。`id` 是 Manifest 和调试工具引用的 `widget_id`，必须在应用内全局唯一，
发布后不应随意修改。重复 ID 会导致构建失败，需要为对应入口配置不同的 `id`。

```ts
import { defineAppConfig } from '@doubao-dev/framework/config';

export default defineAppConfig({
  appId: 'your-app-id',
  name: '订单服务',
  widgets: [
    {
      entry: 'widgets/order-card/index',
      id: 'order-card',
      name: '订单结果卡片',
      border: true
    }
  ]
});
```

`entry` 对应 `src/widgets/order-card/index.tsx`。如果使用字符串简写，框架会根据入口推导 id；需要与 Manifest 长期绑定时，建议显式声明 `id`。

## 把 View Data 映射到模板

Manifest 不负责把业务字段逐一映射到模板 Props。字段选择、格式化、空态和点击行为都应在 Widget 的 TypeScript 代码中完成。

```tsx
import { useViewData } from '@doubao-dev/framework';
import { navigateTo } from '@doubao-dev/framework/api';
import { ContentCard } from '@doubao-dev/template';

interface OrderEntity {
  entity_id?: string;
  title?: string;
  summary?: string;
  image_url?: string;
}

export default function OrderCard() {
  const order = useViewData<OrderEntity>() ?? {};

  if (!order.entity_id || !order.title) {
    return <ContentCard items={[{ key: 'empty', title: '暂无可展示的订单信息' }]} />;
  }

  return (
    <ContentCard
      items={[
        {
          key: order.entity_id,
          title: order.title,
          subtitle: order.summary,
          onClick: () =>
            navigateTo({
              url: `/pages/order-detail/index?orderId=${encodeURIComponent(order.entity_id)}`
            }),
          thumbnailSrc: order.image_url
        }
      ]}
    />
  );
}
```

映射时重点处理：

- 为模板列表项提供稳定的 `key`；
- 对可选字段提供空态或省略策略；
- 在进入模板前完成金额、日期和状态等业务格式化；
- 需要响应宿主数据更新时使用 `useViewData<T>()`；
- Widget 根节点直接返回模板，避免增加没有必要的布局容器；

上面的 `onClick` 展示了一条完整的前端联动路径：Widget 从 View Data 读取稳定业务 ID，用户点击模板项后通过 `navigateTo` 打开 Page，并只在 URL 中传递定位业务对象所需的参数。

## 配置出卡协议

下面的 Manifest 片段表示：`query_order` MCP Tool 返回 `order` 实体时，使用 `order-card` Widget 渲染。

```yaml
tools:
  query_order:
    login_type: no_login
    output:
      kind: entities
      entity_types: [order]

entities:
  order:
    schema:
      entity_id:
        type: string
        is_entity_id: true
      entity_type:
        type: string
        llm_visible: false
      title:
        type: string
      summary:
        type: string
      image_url:
        type: string
        llm_visible: false
    tool_card_binding:
      query_order: order-card
```

MCP Tool 成功结果使用 MCP ToolResult 结构：

```json
{
  "content": [{ "type": "text", "text": "已找到订单。" }],
  "structuredContent": {
    "entities": [
      {
        "entity_id": "order_001",
        "entity_type": "order",
        "title": "咖啡订单",
        "summary": "拿铁咖啡 · 中杯 · 热饮"
      }
    ]
  },
  "isError": false
}
```

能够出卡需要同时满足：

- 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 需要分别验证视图和出卡链路：

| 验证范围      | 重点检查                                                 |
| --------- | ---------------------------------------------------- |
| Widget 视图 | View Data 映射、空态、样式和点击行为                              |
| 完整出卡链路    | ToolResult、实体类型、Manifest、`tool_card_binding` 和最终卡片数据 |

出现“MCP Tool 已执行但没有卡片”时，先检查 ToolResult 和 Manifest；卡片已出现但内容或样式错误时，再检查 Widget 的字段映射和 Lynx 样式。调试工具显示请求已发送，不代表卡片已经完成渲染，最终以 Web 模拟器中的实际结果为准。

开发服务启动、Widget 选择、测试数据注入和链路日志查看方式见[开发工具文档](/apps-plugin/docs/development-tools/index.md)。

## 完成检查

- `app.config.ts` 中的 Widget id、Manifest 中的 `tool_card_binding` 和调试目标使用同一个值；
- ToolResult 的 `structuredContent.entities` 与 Manifest schema 一致；
- Widget 能处理必填字段缺失、可选字段为空和宿主数据更新；
- 模板项点击后能够打开目标 Page，路由参数可以被目标 Page 读取；
- 已在 Web 模拟器中验证实际渲染，并完成 MCP Tool 到 Widget 的完整出卡链路验证；
