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, and this page is available as Markdown at /apps-plugin/docs/frontend-development/overview.md.

开发概览

本文档面向正在完成具体前端开发任务的开发者,说明从选择视图形态到调用宿主能力的完整开发路径。豆包应用插件前端主要提供三种面向用户的形态:Widget、Page 和多任务。三者解决的问题不同,但可以围绕同一个业务流程协作。

开始前

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

  • 已完成项目初始化,并能在项目根目录找到 src/app.config.ts;
  • 项目根目录包含 manifest.yaml;
  • 已安装前端依赖,并准备好本地调试环境;具体安装、启动和调试操作见开发工具文档;

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

先选择合适的形态

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

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

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

让 Agent 调用能力和理解页面

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

需求能力与方向接入入口
按用户意图执行端侧能力并返回结果Agent → Client Tool → Resulttools.json、app.config.ts.tools、默认导出的 handler;见端工具开发
更新已经打开的页面Agent → 宿主 → Pageevents.json、Skill 事件占位符、useAgentEvent;见全页事件

先判断数据来自哪里:端工具不能直接读取另一个 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 的完整出卡链路;工具操作见开发工具文档;

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

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

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

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

推荐的目录如下:

<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 APIuseState、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 只负责发起请求,不会自动校验业务数据。

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 入口时,可以显式开启此行为:

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:

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

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

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 已执行但没有 WidgetToolResult、实体类型、tool_card_binding完整链路日志
端工具没有执行工具声明、入口名称、Skill 调用条件和 handler 错误工具面板与 Agent Trace
Agent 回复已更新但页面不变事件声明、Skill 占位符、订阅和 payload 校验全页事件面板、App / Page 日志
Widget 已出现但字段错误Widget 的 View Data 类型、空值和模板 Props 映射Web 模拟器中的测试数据

调试工具显示请求已发送,不代表视图已经完成渲染。最终以 Web 模拟器中的实际渲染结果为准。启动、选择入口、注入测试数据和查看日志的方式见开发工具文档。

从哪里继续阅读

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

文档内容范围
卡片(Widget)开发模板选型与安装、字段映射、出卡协议,以及卡片预览与链路验证
全页(Full Page)开发Page 入口、事件订阅,以及 Widget 与 Page 的联动
端工具(Client Tool)开发工具声明、handler 注册、结果与出卡,以及 Agent 调用验证
对话相关 JS API 使用与权限声明卡片/页面与宿主双向通信时的桥接 API 选型与使用状态

本组文档已经覆盖独立完成常规 Page / Widget 开发所需的流程。需要继续理解运行时内部机制或排查复杂问题时,再进入端侧框架文档:

需要解决的问题对应文档
App、Page、Widget 分别负责什么框架概述与应用配置
View Data、View Context 和状态更新如何工作数据流与状态更新
ReactLynx 如何渲染,元素和事件如何使用视图渲染与交互
创建、挂载、显示、隐藏和销毁何时发生生命周期与错误处理