---
name: doubao-agentic-service-development
description: 豆包智能服务全链路开发指南。当用户需要从零开发一个豆包智能服务，或涉及前端组件开发、MCP 协议设计、Manifest 配置、卡片模板选型、服务端 OpenAPI 对接、登录流程、手机号一键登录、自定义登录、支付/退款/签约、服务通知、多任务管理、签名认证与加密传输、本地调试以及智能服务生命周期（构建、上传、真机预览、发布）时，统一使用本 Skill。此技能整合了豆包智能服务开发的所有必需知识。
---

# 豆包智能服务全链路开发指南

本 Skill 是开发豆包智能服务的**统一入口**。为了最大限度提升开发和排查效率，这里直接提供了**最核心的代码模板、配置骨架和速查手册**。只有在遇到复杂场景（如高级组件、底层协议排查）时，才需要去查阅 `references` 文档。

**路径解析规则：本文档中所有 `references/xxx.md` 的相对路径，均相对于本 SKILL.md 文件所在目录解析。例如本文件位于 `<skills_dir>/doubao-agentic-service-development/SKILL.md`，则 `references/mcp-protocol.md` 的完整路径为 `<skills_dir>/doubao-agentic-service-development/references/mcp-protocol.md`。使用 Read 工具时，必须拼接为绝对路径，不要使用 `./skills/` 前缀。**

## 宏观认知（先理解再开发）

豆包智能服务不是单纯的前端页面，而是一组“让模型会用、让工具能执行、让结果能展示”的能力包。开发时不要只盯着某一个文件，要先判断当前任务缺的是哪一层能力。

- **运行态 Skill** 负责指导模型：这个智能服务能做什么、什么时候调用哪个 MCP Tool、缺少参数时怎么追问、工具返回后如何回复用户和输出卡片。
- **MCP Tool** 是真正执行业务逻辑的能力，例如查询、搜索、下单、创建、更新、取消。模型通过运行态 Skill 决定调用工具，工具返回结构化结果。
- **Manifest** 是应用版本配置说明书。它告诉平台有哪些 tools、工具返回的数据代表什么、哪些结果可以作为实体出卡、哪些只是执行结果，以及哪些 entity 类型绑定哪个前端 `widget_id`。
- **Widget 卡片** 决定对话中展示给用户的样式和交互。Manifest 只声明 entity 到 `widget_id` 的绑定关系；真正的卡片代码在前端工程里实现，并需要在 `src/app.config.ts` 的 `defineAppConfig({ widgets })` 中注册。
- **Page 全页** 承接更完整的交互。用户通常先在对话中看到卡片，再通过点击卡片进入全页完成更复杂的查看、操作或后续流程。

典型链路：

```text
用户提问
  -> 模型读取运行态 Skill
  -> 运行态 Skill 判断要调用哪个 MCP Tool、缺什么参数、如何追问
  -> MCP Tool 执行业务逻辑并返回 ToolResult
  -> Manifest 解释 ToolResult：entities、execution_result、错误、card binding
  -> 命中 tool_card_binding 的 entity 渲染为前端 widget_id 对应卡片
  -> 用户在对话中看到卡片
  -> 用户点击卡片进入全页 Page 或继续对话操作
```

因此，Agent 的工作不是机械生成文件，而是根据用户目标判断当前缺的是哪一层能力：业务工具、模型使用说明、前端体验、平台配置、本地调试，还是最终云构建。只有理解这条链路，才能在“只修前端”“只改 Manifest”“已有 MCP 只补 Skill”“本地已调通只上传”等场景中选择正确工作范围。

## 用户数据合规指导

只要本轮能力会收集、读取、生成、存储、传输、共享或删除可关联到用户的数据，就必须先读 [references/data-compliance.md](references/data-compliance.md)，并在当前工作范围内遵循目的明确、合理最小必要、公开透明和安全保护原则。

规划和实现时只处理当前功能直接需要的数据，不因未来可能使用而扩大字段、权限或保存范围。数据会进入开发者 MCP Server、业务后端、模型上下文、卡片、日志、调试链路或其它第三方服务时，要识别实际接收方和用途；没有必要的数据不采集、不传输、不返回、不持久化。用户拒绝非必要数据或权限时，不应因此阻断不依赖该数据的基本功能。

## 任务规划清单（完整新应用规划时逐项覆盖）

从零开发完整豆包智能服务时，必须覆盖以下交付物。修改已有应用或只接入服务通知、任务模板、后端 OpenAPI 等局部能力时，先按对应专项文档的范围矩阵确定交付物，不得为了补齐本清单自动新增无关 MCP Tool、Widget、Page 或登录能力。

- **SKILL.md（运行态 Skill）**：描述智能服务功能、MCP tools 调用流程和出卡规则。编写或改写前先读 [references/generate-skill.md](references/generate-skill.md)，并用 `python3 <skill_dir>/scripts/workspace.py skill path --create --json` 获取写入位置；文件写到返回的 `skill_md`，不要手写根目录 `SKILL.md`。
- **manifest.yaml**：项目的 AppID（manifest 字段名为 `app_key`）、mcp_server、entities、tools、tool_card_binding。
- **business-templates.yaml（按需）**：涉及服务通知或多任务管理时声明 `notice_templates` / `task_templates`；每个通知模板必须提供非空 `brief` 作为通知摘要，摘要中的占位符必须在 `variable_list` 声明。它是独立的应用级业务模板配置，不写入 `manifest.yaml`。标准布局中放在项目根目录、与默认 `manifest.yaml` 同目录；自定义 Manifest 路径时，位置和路径解析规则见 [references/business-template-debug.md](references/business-template-debug.md)。
- **MCP Server**：实现 tools/list 和 tools/call，返回符合协议的 structuredContent.entities。
- **Widget（卡片）**：聊天流中的嵌入式卡片，放在 `src/widgets/`，使用 `defineWidget`。每个需要出卡的 tool 对应一个 Widget。
- **Page（全页）**：全屏独立页面，放在 `src/pages/`，使用 `definePage`。**每个豆包智能服务至少需要一个首页 Page**，用于用户点击卡片后跳转查看详情、或作为应用的独立功能页面。如果用户需求涉及"首页"、"详情页"、"设置页"、"全屏展示"、"点击卡片跳转"等，必须规划 Page 开发。
- **app.config.ts**：注册所有 pages 和 widgets。真实 AppID 只维护在项目根目录 `manifest.yaml` 的 `app_key`；`dbx dev` 和上传流程会把它作为运行时 AppID 传给 Kit，不改写该文件。

**完整新应用中的 Page 是必需组成部分。** 只修改现有应用或只接入不需要前端入口的服务端能力时，不得据此扩建无关 Page。

如果用户只要求审核、检查、review、验收或准出已有运行态 Skill，主动使用独立的 `doubao-agentic-service-skill-quality-review` Skill；不要把创建流程或本开发 Skill 当作完整审核流程。

### 能力交付物一致性检查

实现前先判断本轮是否改变能力契约：工具调用、出卡或导航入口变化，需要同步运行态 Skill、MCP、Manifest、Widget/Page 和 `app.config.ts`；纯视觉调整且链路不变时，可以只改前端。脚手架默认 Widget、无关页面、仅注册到 `app.config.ts` 的 Page，都不算可用的智能服务能力入口。

### 最终回复交付边界

最终回复前检查交付边界；不要只写“已完成”“构建通过”或“未启动 dbx dev”。只要只完成局部前端、只做静态检查/build、缺能力入口、缺 `manifest.yaml` / 运行态 Skill / MCP / 真实 `app_key` / MCP endpoint，或未跑通 `dbx dev` / simulator，就要追加“下一步”。

“下一步”用一两句自然语言说明当前验证范围，并只点名实际缺失或未验证的项；不要照抄完整清单，也不要用“这些”“等”“闭环”“真实应用配置”“项目配置”概括。Page 只有 `app.config.ts` 注册时，要说明当前只是前端 Page；若要从对话触达，还缺 Widget 出卡、`tool_card_binding` 和 Page 跳转。完整智能服务交付需要 `manifest.yaml`、运行态 Skill、MCP、真实 `app_key` 和 MCP endpoint；这些产物或配置就绪后，再把 `dbx app artifacts validate <manifest.yaml路径> --json` 和 `dbx dev --mcp-endpoint <mcp_endpoint>` 写成验证下一步；工具/出卡链路再按需用 `dbx simulator eval` 验证。

## 核心速查手册与代码模板 (Cheat Sheet)

### 1. 本地调试速查

#### 选择正确的调试命令

- **`dbx dev`**：需要前台 REPL 或 Web 调试器时使用。默认只启动和使用 Web 调试能力；涉及 App 配置分流、路径、Manifest/Skill 加载、MCP endpoint 或 Web 模拟器排障时，读 [references/local-debug/overview.md](references/local-debug/overview.md)。
- **`dbx simulator eval`**：需要验证 Skill / MCP / Manifest / `card_delta` 的后端链路时使用；它不验证前端视觉效果，具体读 [references/local-debug/simulator-eval.md](references/local-debug/simulator-eval.md)。

两者可以串联，但不要互相替代：先确认当前需要的是交互现场，还是后端协议链路。

**术语边界：**
- **真机调试**专指 `dbx dev` 中通过 `device` 进入真机模式，再使用 `pages` / `page`、`widgets` / `widget` 打开页面或推送卡片。
- **真机预览**专指 UGC Bot 流程：产物上传并完成云构建后，在版本详情页扫码，并进入 UGC Bot 调试对话预览已构建版本。不要再把该流程称为“真机调试”，它也不使用 `dbx dev` 的设备和页面/卡片推送命令。
- 涉及 `business-templates.yaml` 时还要区分 Session 重建、模板单独同步、完整制品上传和真机调试包上传；这些动作不能互相替代，详见 [references/business-template-debug.md](references/business-template-debug.md)。

**真机方式确认门禁：**
- 用户明确选择“UGC Bot”“上传后扫码”“云构建版本”或“版本详情页二维码”时，进入 **UGC Bot 真机预览**，读取 [references/overview.md](references/overview.md) 的 build 流程；不要进入 `device` 真机模式或执行其中的 `page` / `widget`。
- 用户明确选择“`dbx dev`”“直接推送到手机”“推送 Page/Widget/卡片”或“连接调试设备”时，进入 **`dbx dev` 真机调试**，读取 [references/dev-debug.md](references/dev-debug.md)。
- 用户只说“想看真机效果”“测试手机里的渲染”“真机验证页面/卡片”“真机预览一下”等目标，但没有选择上述方式时，**必须先询问并等待回答**：

  > 你想通过哪种方式验证真机效果：使用 UGC Bot 扫码预览已上传并云构建的版本，还是使用 `dbx dev` 连接手机并直接推送页面/卡片？

  在用户选择前，不执行任一路径的专属操作：不上传或触发云构建、不引导 UGC Bot 扫码，也不下载真机工具、不进入 `device` 真机模式或执行其中的 `qr` / `pages` / `page` / `widgets` / `widget` 命令。不要因为用户尚未明确选择 `dbx dev` 就默认改用 Web 模拟器或 simulator；用户已经明确要看手机时，缺少的是预览方式选择。

前端代码中的 Page / Widget、`src/pages/` / `src/widgets/` 不受此门禁影响。

**重要：豆包智能服务的本地调试命令是 `dbx dev`，不是 `npm run dev`。**

默认在 dbx 项目目录下直接执行；不需要进入智能服务前端目录。启动时显式传 MCP endpoint：

```bash
dbx dev --mcp-endpoint <mcp_endpoint>
```

命令把当前目录当作 dbx 项目目录，按项目布局和 `.dbx/config.json` 自动解析前端目录，默认从根目录 `manifest.yaml` 和 `skill/SKILL.md` 解析。`--mcp-endpoint` 使用当前机器可访问的 Streamable HTTP `/mcp` 地址。

使用本地 MCP Server 时，按 [本地调试总流程](references/local-debug/overview.md) 由 Agent 帮用户启动和管理 Server。Agent 从项目脚本或 Server 代码确定实际启动命令，通过环境变量指定 OpenAPI BaseDomain，完成日志检查和 endpoint 验证后再运行 `dbx dev`。

默认直接运行 `dbx dev --mcp-endpoint <mcp_endpoint>`；只有默认解析失败时再补 `--manifest`、`--skill`。
确实需要传路径参数时，优先使用绝对路径；相对路径会按当前目录解析。

`dbx dev` 启动交互式调试控制台；返回 Web 调试地址时必须保留完整 query。出卡链路不确定时再用 `dbx simulator eval` 排查 MCP / Manifest / Skill / card_delta。

`dbx dev` 已运行时，纯前端 Page / Widget / 样式改动不要重启工程；等待热更新后在 REPL 执行 `web` 刷新调试器。业务模板内容变化时先重新校验，再在 Web 调试面板点击“撤回并重建 session”；只刷新页面不会更新已有 Session。Manifest `app_key`、MCP endpoint、PPE 环境或路径等启动边界变化时才重启 `dbx dev`。

### 2. 高频 CLI 命令
在开发排查过程中，最常用的 `dbx` 命令如下（执行操作时优先考虑）：
- **校验配置**：`dbx app artifacts validate <manifest.yaml路径> --json` (修改 `manifest.yaml` 后必须执行，检查格式是否合法)
- **校验业务模板**：`dbx app artifacts validate <business-templates.yaml路径> --type business-templates --json`（修改业务模板后执行兼容校验；通知模板缺少非空 `brief` 时不得继续调试或上传）
- **后端评测**：`dbx simulator eval` (测试 MCP 协议、验证大模型 Tool Call 与 `card_delta` 数据流)
- **本地 Web 调试**：`dbx dev --mcp-endpoint <mcp_endpoint>` (在 dbx 项目目录启动 REPL，默认只使用 Web 调试器)
- **UGC Bot 真机预览**：用户选择上传后扫码预览时，按构建上传流程生成版本，再通过版本详情页二维码和 UGC Bot 调试对话预览
- **`dbx dev` 真机调试**：用户选择直接推送到手机时，才在 REPL 中执行 `device` 进入真机模式；使用 `qr` / `pages` / `page` / `widgets` / `widget` 推送内容，使用 `sessions` / `use-session` / `get-console` / `take-screenshot` / `get-page-tree` / `get-computed-style` 检查已连接真机运行时
- **构建上传**：`dbx app artifacts upload` (开发完成后，触发云端构建并上传产物)

### 3. 标准项目结构
一个新建的豆包智能服务通常包含以下目录结构；对于旧项目，仍兼容根目录 Manifest、`skill/SKILL.md` 以及旧版前端目录（默认目录名为 `miniapp/`）：
```text
.
├── src/                # 前端组件代码目录
│   ├── app.ts          # 应用入口
│   ├── app.config.ts   # 应用配置（引用 runtimeConfig.appId，注册 pages、widgets）
│   ├── config/
│   │   └── runtime.ts  # 非敏感运行时配置（appId、apiBaseUrl）
│   ├── pages/          # 全页目录（全屏 UI）
│   │   └── home/
│   │       ├── index.tsx
│   │       └── index.scss
│   └── widgets/        # 卡片目录（聊天流 UI）
│       └── weather/
│           ├── index.tsx
│           └── index.scss
├── manifest.yaml       # 核心配置文件（必须）
├── skill/
│   └── SKILL.md        # 运行态 Skill（必须）
├── package.json        # 依赖与脚本
└── .gitignore
```

### 4. Manifest.yaml 与出卡绑定 (Tool Card Binding)
当你需要新增一个功能并展示卡片时，必须在 `manifest.yaml` 中定义实体，并配置 `tool_card_binding`。

**关键规则：以下模板中的 `your_app_id`、`<mcp_server_url>` 均为占位符，绝对不能直接使用。必须向用户确认真实的 AppID 和 MCP Server 地址后再填入。**

云构建上传前，`manifest.mcp_server.end_point` 必须是公网可访问 URL。若只剩本地/内网 endpoint，停止真实上传，要求用户提供可用于云构建的公网 MCP URL。

```yaml
manifest_version: 2
app_key: "your_app_id"              # ⚠️ 占位符！manifest 字段名保持 app_key，值必须替换为用户在豆包开放平台申请的真实 AppID
name: "你的智能服务名称"
# MCP 服务端点配置
mcp_server:
  end_point: "<mcp_server_url>"     # ⚠️ 占位符！上传云构建前必须替换为用户提供的公网 MCP URL
  description: "MCP Server 描述"
  mcp_config:
    protocol: Streamable
# 业务实体定义
entities:
  weather_entity:
    schema:
      entity_id: { type: string, description: 天气实体ID, is_entity_id: true }
      city: { type: string, description: 城市名称 }
      temperature: { type: int, description: 温度 }
      description: { type: string, description: 天气描述 }
    tool_card_binding:
      get_weather: WeatherCard       # key 是 MCP tool 名，value 是前端注册的 widget_id
# 工具运行配置
# 工具入参以 MCP Server tools/list 暴露的 inputSchema 为准，manifest 不重复声明。
tools:
  get_weather:
    description: 查询天气
    output:
      kind: entities
      entity_types: [weather_entity]
```

当 entity 结构复杂、字段很多时，不必在 `schema` 中完整枚举业务返回的所有字段。除标记 `is_entity_id: true` 的稳定业务 ID 外，只强制声明明确需要进入模型上下文的字段（`llm_visible` 省略时默认 `true`，也可显式设为 `true`）以及需要 `llm_modifiable` 等平台能力的字段。其余未声明字段仍会随 entity 原样透传给卡片，但不会因为透传而自动进入模型上下文。

### 5. MCP Server 实现规范（必须遵守）

开发 MCP Server 时，**必须**满足以下协议要求，否则 `dbx simulator eval` 会直接失败：

**1. 必须实现标准 Streamable HTTP 协议：**
- 提供 `/mcp` 端点，支持 POST 请求。
- 实现 `initialize` 握手：客户端发送 `{"method":"initialize",...}`，服务端返回协议版本和 capabilities。
- 响应头必须包含 `Mcp-Session-Id`，后续请求需携带此 Session ID。
- 支持 `tools/list`（返回工具列表）和 `tools/call`（执行工具调用）。
- MCP Server 完成后必须先确认本地可以连接：启动本地服务，使用项目配置的 endpoint（通常是 `/mcp`）至少跑通 `initialize` 和 `tools/list`；如果连接失败或工具列表为空，先修复端口、路径、Session ID、JSON-RPC 响应结构等问题。

**2. 必须按 MCP 协议设计工具返回协议：**
- 涉及新增或修改 MCP tool 返回时，必须先按 👉 **[Read `references/mcp-protocol.md`](references/mcp-protocol.md)** 中的业务建模与 ToolResult schema 设计 `content`、`structuredContent`、`isError`、`entities` 和 Manifest 输出声明。
- HTTP 响应体必须是 JSON-RPC 2.0 response 外层包裹：`{ "jsonrpc": "2.0", "id": <与请求一致>, "result": ... }`；失败时使用 `error`，不要把业务 ToolResult 或工具列表对象直接作为 HTTP body 返回。
- `tools/list` 的工具列表必须放在 JSON-RPC `result.tools` 中；`tools/call` 的业务 ToolResult 必须放在 JSON-RPC `result` 中。缺少 `jsonrpc` / `id` / `result` 会导致校验器解析不到工具列表或工具调用结果。

**3. tools/call 返回格式规范：**
- 返回标准 MCP ToolResult 结构：`{ "content": [...], "structuredContent": {...}, "isError": false }`。
- 出卡时 `structuredContent.entities` 必须是**数组**格式，每个 entity 必须包含 `entity_type` 和 `is_entity_id: true` 标记的主键字段。
- **`entity_type` 的值必须与 manifest.yaml 中 `entities` 下声明的 entity 类型名完全一致**（例如 manifest 中声明了 `entities.holding_entity`，则 entity 的 `entity_type` 必须是 `"holding_entity"`，不能是 `"holding"` 或其他变体）。
- entity 中已在 `entities.<entity_type>.schema` 声明的字段必须保持同名且类型一致；未声明的卡片专用字段可以继续随 entity 透传。

**4. 常见错误：**
- ❌ 直接返回工具列表或 ToolResult，缺少 JSON-RPC 2.0 的 `jsonrpc` / `id` / `result` 外层包裹 → ✅ 必须返回标准 JSON-RPC response，业务结果放在 `result` 中
- ❌ entity 返回为对象而非数组：`entities: { ... }` → ✅ 必须是 `entities: [{ ... }]`
- ❌ 缺少 `entity_type` 字段 → ✅ 每个 entity 必须带 `entity_type`
- ❌ 已声明字段的名称或类型与 manifest schema 不一致 → ✅ 已声明部分严格对齐；未声明字段仅透传给卡片
- ❌ 未实现 `initialize` 握手 → ✅ 必须支持标准 MCP 握手流程
- ❌ 未做本地连通性自检就交付 MCP Server → ✅ 先在本地确认 `initialize` 和 `tools/list` 可正常返回

**Server 启动配置（必须遵守）：**
- 支持从 `DOUBAO_OPENAPI_BASE_DOMAIN` 读取平台 OpenAPI BaseDomain，并让所有 OpenAPI 调用统一使用该值。
- 仅在确实调用需要应用凭据的豆包 OpenAPI 时，才从服务端安全配置读取 AppSecret；缺少必需凭据时启动失败并说明缺少哪项配置。AppSecret 不得写入前端、Manifest、运行态 Skill、示例代码或日志，也不得回显。
- 本地调试按 [本地调试总流程](references/local-debug/overview.md) 由 Agent 帮用户启动和观测 Server；根据实际项目确定启动命令，并通过进程环境传入 `DOUBAO_OPENAPI_BASE_DOMAIN`。

**Server 日志（必须遵守）：**
- 工具调用、登录交换、`FetchTokenURL`、`RefreshTokenURL`、用户信息删除和关键 OpenAPI 调用必须输出可定位问题的结构化日志。
- 每次请求记录事件名、request/trace ID、tool 或 endpoint、阶段、耗时、结果码和错误类型；调用平台 OpenAPI 时保留平台返回的 `log_id`。
- 只记录经过脱敏的参数摘要，不打印完整请求体、AppSecret、login/phone code、access/refresh token、手机号、私钥或其它敏感数据。
- 控制日志量：正常请求通常记录开始与结束/失败，不在循环或每个内部步骤重复打印相同上下文。详细规范见 [references/mcp-protocol.md](references/mcp-protocol.md) 和 [references/auth.md](references/auth.md)。

**OpenAPI 报错排查（必须遵守）：**
- OpenAPI 调用报错时，先确认请求域名是否为当前环境和该接口要求的正确域名，再查阅[对应 OpenAPI 文档](references/server/openapi.md)，逐项核对 HTTP method、path、Header、Query/Body 参数、字段类型、必填项和嵌套结构是否正确传递；不要根据其它接口的写法猜测域名或参数。

### 6. 前端卡片开发模板 (Widget)

豆包智能服务支持两种视图形态：**Widget（卡片）** 和 **Page（全页）**。当用户需要开发聊天流中的嵌入式卡片时，使用 Widget 模板。

**关键规则：正式对话卡片优先使用 `@doubao-apps/template` 模板组件。不要手写 `view` / `text` / `image` 拼整张卡片，除非已经查阅 `references/frontend/widget-templates/overview.md` 并确认只能用模板 `children` 自定义内容区。**

### 7. 全页开发模板 (Page)

豆包智能服务支持两种视图形态：**Widget（卡片）** 和 **Page（全页）**。当用户需要开发全屏页面（如首页、设置页、详情页）时，使用 Page 模板。

**Page 组件 (src/pages/home/index.tsx):**
```tsx
import { definePage, getViewData, useState, useEffect } from '@doubao-apps/framework';
import './index.scss';

interface PageViewData {
  title: string;
}

export default definePage({
  // 生命周期：页面显示时调用（包括从其他页面返回）
  onShow() {
    console.log('页面显示');
  },

  // 生命周期：页面隐藏时调用
  onHide() {
    console.log('页面隐藏');
  },

  // 生命周期：页面销毁时调用
  onDestroy() {
    console.log('页面销毁');
  },

  // 渲染函数
  render() {
    const viewData = getViewData<PageViewData>();

    return (
      <scroll-view className="full-page" scroll-orientation="vertical" enable-scroll={true}>
        <view className="full-page__content">
          <view className="full-page__header">{viewData.title || '页面标题'}</view>
          <view className="full-page__body">内容区域</view>
          <view className="full-page__footer">底部</view>
        </view>
      </scroll-view>
    );
  }
});
```

**app.config.ts 注册 Page：**
```ts
import { defineAppConfig } from '@doubao-apps/framework/config';
import { runtimeConfig } from './config/runtime';

export default defineAppConfig({
  appId: runtimeConfig.appId,
  name: '你的豆包应用',
  pages: [
    'pages/home/index',          // 数组第一项为应用首页
    {
      entry: 'pages/profile/index',
      id: 'profile',
      title: '资料页',
      description: '补充 metadata 的页面示例'
    }
  ],
  widgets: [
    {
      entry: 'widgets/weather/index',
      id: 'WeatherCard',
      name: '天气卡片',
      description: '展示天气信息'
    }
  ]
});
```

**Page vs Widget 决策规则：**
- **Widget（卡片）**：聊天流中的嵌入式卡片，由 MCP tool 调用触发出卡，放在 `src/widgets/`，使用 `defineWidget`。
- **Page（全页）**：全屏独立页面，用户点击卡片或导航跳转进入，放在 `src/pages/`，使用 `definePage`。
- 规划任务时，如果用户需求涉及"首页"、"设置页"、"详情页"、"全屏展示"等，必须同时规划 Page 开发。

---

## 深度开发工作流与详细指南 (References)

**如果上述速查模板无法解决问题（例如需要复杂的 UI 组件 API、排查 MCP 协议鉴权、应用发布审核等），必须使用 `Read` 工具查阅以下对应的详细文档：**

### 1. 业务建模与 MCP 协议设计
当涉及与后端/模型的交互、新增 tool、理解 `card_delta` 流式出卡机制时：
👉 **[Read `references/mcp-protocol.md`](references/mcp-protocol.md)**
👉 **[Read `references/generate-skill.md`](references/generate-skill.md)**（需要创建或改写运行态 Skill 时）
👉 **使用独立 `doubao-agentic-service-skill-quality-review` Skill**（只审核、检查、review、验收或准出已有运行态 Skill 时）

### 2. 服务端 OpenAPI 和后端接入
当实现后端服务调用豆包智能服务平台能力，或涉及 app_id/app_secret 获取应用级 Token、login_code 换 OpenID、获取加密手机号、支付/退款/签约、支付回调验签时：
👉 **[Read `references/server/openapi.md`](references/server/openapi.md)**

先读索引，只追加读取命中的接口详情；涉及签名认证、证书、回调验签、手机号密文解密时，按索引进入安全分组。后端凭证和私钥只放服务端，不写入前端 Page/Widget、Manifest 示例或运行态 Skill。

### 3. 登录认证与用户身份识别
当涉及 登录认证、用户身份识别、业务账号绑定、手机号授权时：
👉 **[Read `references/auth.md`](references/auth.md)**

### 4. 支付能力接入
当涉及普通支付、订单查询、支付回调、退款、履约完成、签约或协议支付时：
👉 **[Read `references/payment.md`](references/payment.md)**

### 5. 服务通知
当涉及配置服务通知模板、自定义通知关键词、`brief` 摘要、发送服务通知、通知跳转、Sandbox 通知预览、模板同步或审核发布时：
👉 **涉及 Sandbox Session、模拟器调试或真机调试时，先读 [references/business-template-debug.md](references/business-template-debug.md)**
👉 **[Read `references/service-notice.md`](references/service-notice.md)**

### 6. 多任务管理
当涉及配置任务模板、创建远程任务、更新进度或状态、轮换 `push_token`、任务跳转、Sandbox 任务预览时：
👉 **涉及 Sandbox Session、模拟器调试或真机调试时，先读 [references/business-template-debug.md](references/business-template-debug.md)**
👉 **[Read `references/task-management.md`](references/task-management.md)**

### 7. Manifest 深度配置
当需要配置复杂的端点、权限声明、鉴权机制（OAuth 等）时：
👉 **[Read `references/manifest-guide.md`](references/manifest-guide.md)**

### 8. 前端与卡片开发
当需要使用复杂的 React Lynx 内置组件（如 ScrollView, Image）、或者官方 Widget Template 时：
👉 **[Read `references/frontend-dev.md`](references/frontend-dev.md)**
👉 **[Read `references/frontend/widget-templates/overview.md`](references/frontend/widget-templates/overview.md)**
👉 **[Read `references/frontend/components/overview.md`](references/frontend/components/overview.md)**

### 9. 本地联调与评测
当卡片无法渲染、大模型未调用 Tool、或者 `dbx simulator eval` 报错时：
👉 **[Read `references/local-debug/overview.md`](references/local-debug/overview.md)**
👉 **[Read `references/local-debug/simulator-eval.md`](references/local-debug/simulator-eval.md)**

当用户已明确选择使用 `dbx dev` 连接手机并直接推送页面或卡片时：
👉 **[Read `references/dev-debug.md`](references/dev-debug.md)**

### 10. 构建与发布生命周期
当进行应用打包、上传、版本管理和发布，或用户已明确选择 UGC Bot 扫码预览时：
👉 **[Read `references/overview.md`](references/overview.md)**

### 11. 用户数据合规
当功能涉及用户身份、手机号、位置、联系人、剪贴板、图片、录音、设备信息、支付信息、用户历史、埋点分析、模型上下文，或把用户数据发送到 MCP Server、业务后端及其它第三方服务时：
👉 **[Read `references/data-compliance.md`](references/data-compliance.md)**