> 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、Page 和多任务。三者解决的问题不同，但可以围绕同一个业务流程协作。

## 开始前

进入本组文档前，项目应满足以下条件：

- 已完成项目初始化，并能在项目根目录找到 `src/app.config.ts`；
- 项目根目录包含 `manifest.yaml`；
- 已安装前端依赖，并准备好本地调试环境；具体安装、启动和调试操作见[开发工具文档](/apps-plugin/docs/development-tools/index.md)；

前端开发文档回答“如何完成一次开发任务”，包括入口注册、数据读取、界面实现、能力调用和调试验证。本组文档会直接给出独立开发所需的最小框架规则，不把必要步骤只放在框架文档中。端侧框架文档则回答“这些能力在运行时如何工作”，用于理解生命周期、数据更新、渲染线程和完整能力边界。

## 先选择合适的形态

| 形态     | 适合承载的内容                    | 典型入口                            |
| ------ | -------------------------- | ------------------------------- |
| Widget | 对话中的结构化结果、确认操作和轻量反馈        | MCP Tool 返回实体后，由出卡协议选择对应 Widget |
| Page   | 需要更多空间、连续操作或完整流程的界面        | Widget 点击、应用内路由或宿主打开 Page       |
| 多任务    | 离开当前页面后仍需持续执行、查看进度或返回处理的任务 | 通过任务 API 创建、更新和查询任务             |

一个常见的组合方式如下。MCP Tool 执行结果不会直接变成 Widget；是否出卡、使用哪个 Widget，由产品出卡协议根据 MCP Tool、实体类型和 `widget_id` 绑定关系决定。

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 48, "rankSpacing": 36, "htmlLabels": true}}}%%
flowchart TB
  TOOL["MCP Tool<br/>执行服务能力"] -->|"返回结构化实体"| PROTOCOL["产品出卡协议<br/>匹配实体与 widget_id"]
  PROTOCOL -->|"创建展示容器"| WIDGET["Widget<br/>展示结果与快捷操作"]
  WIDGET -->|"需要完整交互"| PAGE["Page<br/>承载详情或业务流程"]
  PAGE -->|"需要持续运行和回访"| TASK["多任务<br/>展示状态与返回入口"]

  classDef tool fill:#FFF4E5,stroke:#D97706,color:#7C2D12;
  classDef view fill:#EEF4FF,stroke:#4C6FFF,color:#172B4D;
  classDef task fill:#ECFDF3,stroke:#299764,color:#14532D;
  class TOOL,PROTOCOL tool;
  class WIDGET,PAGE view;
  class TASK task;
```

这不是固定流程：简单结果可以只使用 Widget，纯页面型服务可以直接打开 Page；只有需要持续运行和回访的业务才需要接入多任务。

## 让 Agent 调用能力和理解页面

Widget、Page 是交互载体；端工具和全页事件负责 Agent 与端侧的协作，不是新的视图形态。

| 需求               | 能力与方向                        | 接入入口                                                                                                               |
| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 按用户意图执行端侧能力并返回结果 | Agent → Client Tool → Result | `tools.json`、`app.config.ts.tools`、默认导出的 handler；见[端工具开发](/apps-plugin/docs/frontend-development/client-tools.md)  |
| 更新已经打开的页面        | Agent → 宿主 → Page            | `events.json`、Skill 事件占位符、`useAgentEvent`；见[全页事件](/apps-plugin/docs/frontend-development/full-page.md#响应-agent-事件) |

先判断数据来自哪里：端工具不能直接读取另一个 Page 的组件 state；事件不会自动打开页面或持久化业务数据。两条链路可以围绕同一业务流程配合，但需要独立验证。

## 从需求到可验证界面

前端开发可以按以下顺序推进：

1. 根据交互空间和业务时长选择 Widget、Page，必要时组合使用；
2. 在 `src/app.config.ts` 注册入口，确认 Widget ID 或 Page URL；
3. 在视图代码中读取 View Data，完成展示、空态和交互；
4. 需要路由、网络、权限或卡片更新时，从 `@doubao-dev/framework/api` 调用公开 API；
5. 先在 Web 模拟器中验证视图，再验证 MCP Tool 到 Widget 的完整出卡链路；工具操作见[开发工具文档](/apps-plugin/docs/development-tools/index.md)；

## 一次前端开发会涉及哪些文件

先区分“界面代码”和“界面如何被触达”。Page 只做独立页面预览时，不需要配置出卡协议；Widget 需要在正式对话中出现时，除了前端代码，还必须接通 ToolResult 和 Manifest。

| 文件或目录                                      | 负责内容                                          | 何时修改                               |
| ------------------------------------------ | --------------------------------------------- | ---------------------------------- |
| `src/app.config.ts`                        | 注册 Page / Widget 入口和 metadata                 | 新增入口或修改标题、卡片形态时                    |
| `src/pages/<name>/index.tsx`               | Page 的数据读取、状态和交互                              | 开发全页功能时                            |
| `src/widgets/<name>/index.tsx`             | Widget 的模板选择和字段映射                             | 开发对话卡片时                            |
| 同目录 `index.scss`                           | 当前视图的布局和样式                                    | 视图使用自定义样式时                         |
| `skill/<name>/SKILL.md`                    | 按业务领域拆分的 Agent 行为和工具使用说明                      | 新增或调整一组 Agent 能力时                  |
| `manifest.yaml`                            | MCP Tool 输出、实体 schema、权限和 `tool_card_binding` | Widget 需要从对话 MCP Tool 出卡或前端使用受权能力时 |
| `tools.json` / `src/tools/<name>/index.ts` | 工具声明（支持端工具与远程工具）与端侧 handler                   | Agent 需要调用端侧能力时                    |
| `events.json`                              | Agent 业务事件名称和 payload schema                  | Agent 需要更新已打开页面时                   |
| MCP Tool 实现                                | 返回符合 Manifest 的 ToolResult                    | 需要验证完整出卡链路时                        |

运行态 Skill 以目录为入口，并按业务领域拆成多份 `SKILL.md`。`dbx dev` 会递归读取 `skill/`
下的所有 `SKILL.md`；不要再用单份文件承载整个应用的行为。

推荐的目录如下：

```text
<project>/
├── manifest.yaml
├── package.json
├── skill/
│   ├── order/SKILL.md
│   └── customer-service/SKILL.md
├── src/
│   ├── app.config.ts
│   ├── pages/order-detail/
│   │   ├── index.tsx
│   │   └── index.scss
│   └── widgets/order-card/
│       └── index.tsx
└── tsconfig.json
```

## 编写 Page 和 Widget 的最小规则

只阅读本组文档开发界面时，至少遵守以下规则：

| 关注点       | 开发规则                                                                                 |
| --------- | ------------------------------------------------------------------------------------ |
| 入口        | Page 和 Widget 默认导出 React 函数组件，并在 `src/app.config.ts` 注册                              |
| React API | `useState`、`useEffect` 等从 `@doubao-dev/framework` 导入，不直接从 `react` 导入                 |
| 输入数据      | 一次性读取使用 `getViewData<T>()`；宿主更新后需要自动刷新时使用 `useViewData<T>()`                         |
| 元素        | 布局使用 `view`，文本必须放在 `text` 中，图片使用 `image`，长内容显式使用 `scroll-view` 或 `list`              |
| 事件        | SDK 内置组件使用 `onClick`、`onTouchStart` 等驼峰属性；不要自行改写为 `bindtap` 等原生事件名，除非组件文档明确要求        |
| 状态        | 交互状态使用 `useState` / `useReducer`；依赖组件数据的请求和订阅使用 `useEffect`；依赖 View 显示或隐藏的任务使用对应生命周期 |
| 样式        | 导入同目录样式文件，关键容器显式声明布局和尺寸；不要使用 HTML 标签、DOM API 或假设 Web CSS 默认值                         |
| 端能力       | 路由、网络、权限和宿主能力从 `@doubao-dev/framework/api` 导入，并按 JS API 文档处理参数与失败结果                  |

以下骨架展示了这些规则如何组合。示例中的 `/orders/<id>` 是业务接口路径，需要替换为实际服务契约；`request` 只负责发起请求，不会自动校验业务数据。

```tsx
import { useEffect, useState, useViewData } from '@doubao-dev/framework';
import { request } from '@doubao-dev/framework/api';
import './index.scss';

interface PageData {
  orderId?: string;
}

interface Order {
  id: string;
  title: string;
}

async function loadOrder(orderId: string): Promise<Order | null> {
  const apiBase = process.env.PUBLIC_API_BASE;
  if (!apiBase) throw new Error('PUBLIC_API_BASE is not configured');

  const result = await request({
    url: `${apiBase}/orders/${encodeURIComponent(orderId)}`,
    method: 'GET',
    dataType: 'json'
  });

  if (result.statusCode === 404) return null;
  if (result.statusCode < 200 || result.statusCode >= 300) {
    throw new Error(`request failed: ${result.statusCode}`);
  }

  const data = result.data;
  if (
    !data ||
    typeof data !== 'object' ||
    !('id' in data) ||
    typeof data.id !== 'string' ||
    !('title' in data) ||
    typeof data.title !== 'string'
  ) {
    throw new Error('invalid order response');
  }

  return { id: data.id, title: data.title };
}

export default function OrderPage() {
  const { orderId } = useViewData<PageData>();
  const [order, setOrder] = useState<Order | null>(null);
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');

  useEffect(() => {
    if (!orderId) {
      setStatus('idle');
      return;
    }

    let disposed = false;
    setStatus('loading');

    void loadOrder(orderId)
      .then(result => {
        if (!disposed) {
          setOrder(result);
          setStatus('success');
        }
      })
      .catch(() => {
        if (!disposed) setStatus('error');
      });

    return () => {
      disposed = true;
    };
  }, [orderId]);

  if (!orderId) return <text>缺少订单标识</text>;
  if (status === 'loading') return <text>加载中</text>;
  if (status === 'error') return <text>加载失败，请稍后重试</text>;
  if (!order) return <text>暂无订单</text>;

  return <text>{order.title}</text>;
}
```

### 使用环境变量区分业务环境

应用插件默认使用原有的 reload 路径。需要在卡片复用时重新执行 JS 入口时，可以显式开启此行为：

```sh
ENABLE_RE_EVAL_JS_ON_RELOAD=1 dbx dev
ENABLE_RE_EVAL_JS_ON_RELOAD=1 dbx build local
```

这是构建进程的环境变量，需要重启开发服务或重新构建产物后生效；不是页面运行时开关。仅当该变量的值为 `1` 时启用；未设置或设置为其他值时保持关闭。SDK 的 External Bundle 构建也支持相同变量。

环境变量用于把会随开发环境变化的非敏感配置与 TSX 源码分离。例如，不同开发者或调试环境需要连接不同的测试服务时，页面代码不需要因此修改请求地址。

本地开发需要连接测试服务时，可以在项目根目录创建 `.env.local`：

```text
PUBLIC_API_BASE=https://api-test.example.com
```

在 Page / Widget 中读取该变量并拼接具体接口路径：

```ts
import { request } from '@doubao-dev/framework/api';

const apiBase = process.env.PUBLIC_API_BASE;
if (!apiBase) throw new Error('PUBLIC_API_BASE is not configured');

const result = await request({
  url: `${apiBase}/orders/order_001`,
  method: 'GET',
  dataType: 'json'
});
```

如果另一位开发者需要连接不同的测试服务，只需把自己的 `.env.local` 改为 `PUBLIC_API_BASE=https://api-staging.example.com`，不需要修改上面的请求代码。`.env.local` 是可选的本地配置文件；修改后需要重新启动本地开发服务。

只有 `PUBLIC_` 前缀变量会进入前端产物。密钥、Token、Cookie 和服务端凭证不能放入 `PUBLIC_` 变量，也不能写进 Page / Widget 源码。

## 完成一次前端开发的判断标准

无论开发 Widget 还是 Page，交付前都应确认：

- 入口已经在 `src/app.config.ts` 注册，并能被本地调试工具识别；
- TSX 只使用当前公开的 Lynx 元素或内置组件，样式文件已经导入，文本、滚动和图片尺寸符合端侧规则；
- 视图能够读取并校验 View Data，对缺失字段提供合理的空态；
- 加载、成功、空结果和失败状态已经处理，异步任务不会在视图销毁后继续回写状态；
- 点击、路由和宿主能力只使用当前公开的 Framework API，并处理 Promise 失败；
- 已在 Web 模拟器中确认目标视图的实际渲染结果；
- Widget 的 ToolResult、实体类型和 `tool_card_binding` 已完成完整链路验证；

## 调试时先判断问题在哪一层

| 现象                     | 优先检查                                 | 使用工具                 |
| ---------------------- | ------------------------------------ | -------------------- |
| Page / Widget 没有被发现    | `app.config.ts`、入口路径和编译日志            | 本地开发日志               |
| 视图已打开但白屏               | View Data、运行时错误、文本元素和样式导入            | Web 模拟器日志            |
| 点击或路由没有结果              | 事件属性、目标 Page URL、Promise 错误          | Web 模拟器交互            |
| MCP Tool 已执行但没有 Widget | ToolResult、实体类型、`tool_card_binding`  | 完整链路日志               |
| 端工具没有执行                | 工具声明、入口名称、Skill 调用条件和 handler 错误     | 工具面板与 Agent Trace    |
| Agent 回复已更新但页面不变       | 事件声明、Skill 占位符、订阅和 payload 校验        | 全页事件面板、App / Page 日志 |
| Widget 已出现但字段错误        | Widget 的 View Data 类型、空值和模板 Props 映射 | Web 模拟器中的测试数据        |

调试工具显示请求已发送，不代表视图已经完成渲染。最终以 Web 模拟器中的实际渲染结果为准。启动、选择入口、注入测试数据和查看日志的方式见[开发工具文档](/apps-plugin/docs/development-tools/index.md)。

## 从哪里继续阅读

建议先读完本页，再按任务进入对应文档。只完成单一视图时，不要求先读完端侧框架文档。

| 文档                                                                                   | 内容范围                                |
| ------------------------------------------------------------------------------------ | ----------------------------------- |
| [卡片（Widget）开发](/apps-plugin/docs/frontend-development/widget.md)                     | 模板选型与安装、字段映射、出卡协议，以及卡片预览与链路验证       |
| [全页（Full Page）开发](/apps-plugin/docs/frontend-development/full-page.md)               | Page 入口、事件订阅，以及 Widget 与 Page 的联动   |
| [端工具（Client Tool）开发](/apps-plugin/docs/frontend-development/client-tools.md)         | 工具声明、handler 注册、结果与出卡，以及 Agent 调用验证 |
| [对话相关 JS API 使用与权限声明](/apps-plugin/docs/frontend-development/conversation-js-api.md) | 卡片/页面与宿主双向通信时的桥接 API 选型与使用状态        |

本组文档已经覆盖独立完成常规 Page / Widget 开发所需的流程。需要继续理解运行时内部机制或排查复杂问题时，再进入[端侧框架文档](/apps-plugin/docs/client-framework/index.md)：

| 需要解决的问题                          | 对应文档                                                         |
| -------------------------------- | ------------------------------------------------------------ |
| App、Page、Widget 分别负责什么           | [框架概述与应用配置](/apps-plugin/docs/client-framework/overview.md)  |
| View Data、View Context 和状态更新如何工作 | [数据流与状态更新](/apps-plugin/docs/client-framework/data-flow.md)  |
| ReactLynx 如何渲染，元素和事件如何使用         | [视图渲染与交互](/apps-plugin/docs/client-framework/rendering.md)   |
| 创建、挂载、显示、隐藏和销毁何时发生               | [生命周期与错误处理](/apps-plugin/docs/client-framework/lifecycle.md) |
