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/client-framework/overview.md.

框架概述与应用配置

豆包应用插件的端侧框架面向“AI 对话中的可交互服务”组织应用。本文依次介绍框架分层、应用组成、构建与运行机制,以及对应的工程约定和入口定义方式。

框架分层

应用插件前端的运行职责可以分为四层:业务入口、Framework、UI 渲染器和豆包宿主。UI 渲染器底层由 Lynx 提供,负责将组件树转换为原生视图。四层之间的关系如下图所示。

实线表示开发者代码进入视图渲染的主要链路,虚线表示宿主向 Framework 提供运行环境。App 负责应用级生命周期,不进入 UI 渲染链路;只有 Page 和 Widget 会挂载组件树。

各层职责如下表所示。

层次包含内容主要职责
业务入口App、Page、Widget、Client Tool描述应用结构和交互载体
Framework入口定义、生命周期、View Data / Context、端能力接口把业务入口接入豆包宿主,并管理视图运行时
UI 渲染器JSX、组件、Hooks、状态和事件执行组件函数,并把 props 或 state 变化转换为原生视图更新
豆包宿主容器、上下文和端能力创建或绑定视图容器,传入宿主侧运行参数,提供路由、网络和设备能力

注意

Page 和 Widget 不是浏览器网页。开发时不要直接套用 HTML DOM、浏览器 CSS 默认值或同步主线程的执行假设。

开发时按以下文档确认可用能力:

应用组成

一个应用插件可以包含 App、Page、Widget 和 Client Tool 入口。各入口承担不同职责,并分别进入对应的运行上下文。

入口定义与位置什么时候运行主要职责
AppdefineApp();src/app.ts应用插件启动时不渲染界面,处理应用级生命周期和应用实例
Page默认导出 Page 函数组件;src/pages/<name>/index.tsx宿主打开对应页面时渲染全页,承载详情、编辑和连续操作
Widget默认导出 Widget 函数组件;src/widgets/<name>/index.tsx宿主展示对应卡片时渲染卡片,承载轻量结果、状态和操作
Client Tool默认导出 handler;src/tools/<name>/index.ts,在 app.config.ts.tools 注册宿主调用工具时执行端侧能力,返回 Tool Result,不渲染 UI

这些入口之间存在明确边界:

  • App 负责应用级生命周期,不直接渲染 Page / Widget;
  • Page 由路由或宿主按页面 URL 打开,Widget 由宿主按出卡协议选择并展示;
  • 每个 Page / Widget 都有独立的视图实例,不应依赖其他入口的局部变量或组件状态;
  • App 与视图、不同视图之间通过 View Data、路由参数、开放 API 或业务存储显式传递数据;

开发者只需要定义 App、Page、Widget 和需要的 Client Tool。应用启动代码、视图启动代码以及组件树根节点由构建工具生成,不应在业务代码中手动调用 Framework 内部的 bootstrap 方法。

Page / Widget 的创建、挂载、显示和销毁顺序见生命周期与错误处理,宿主输入和组件状态如何驱动刷新见数据流与状态更新。

构建与运行

构建工具不会把所有入口打进同一个视图。它先分析目录约定和 app.config.ts,再分别生成 App、Page 和 Widget 产物;配置端工具时还会生成独立端工具运行时产物。

这些产物进入运行时后,分别经过以下链路。

运行时由豆包宿主和 Framework 协作完成:

  • App:宿主接收应用插件运行请求并启动应用入口,Framework 执行 App 生命周期;
  • Page:宿主解析页面 URL,查找 Page,创建页面容器并传入页面渲染参数;
  • Widget:宿主解析出卡数据,构造 Widget 渲染上下文并绑定卡片视图;
  • 视图就绪后:Framework 建立对应的 Page / Widget View 实例,并挂载 UI 组件树;

App 运行链路

Page 运行链路

Widget 运行链路

开发者不需要调用宿主内部的容器创建或视图绑定接口,也不应依赖宿主原生上下文的字段结构。Page / Widget 只通过 Framework 提供的 View Data / Context 接口读取对前端开放的数据。

这套构建与运行方式有四个直接影响开发的结论:

  1. App 随应用运行时启动,不依赖某个 Page / Widget 是否已经显示;
  2. Page / Widget 是独立视图产物,不能依赖彼此的模块内存或组件 state;
  3. Page 按 URL 打开,Widget 根据出卡数据绑定,二者的宿主入口不同;
  4. 业务代码只定义入口和组件,构建工具负责生成 bootstrap、视图根节点和产物清单;

端工具没有 Page 的组件树和视图状态,不应依赖某个页面先初始化。工具返回值与 Agent 事件经过不同链路,具体见Agent 与端侧交互。

工程约定

公开包的导入边界

导入路径职责
@doubao-dev/frameworkApp 入口定义、Hooks、View Data / Context、页面栈
@doubao-dev/framework/configdefineAppConfig、defineConfig 和配置类型
@doubao-dev/framework/api路由、网络、Storage、设备和业务开放能力
@doubao-dev/framework/componentsFramework 组件声明

导入 API 时注意区分:

  • React Hooks 从 @doubao-dev/framework 导入,以保持依赖与豆包应用插件内置的 React 运行时一致;
  • 端能力从 @doubao-dev/framework/api 导入;

推荐目录

src/
├── app.ts
├── app.config.ts
├── pages/
│   └── order-detail/
│       ├── index.tsx
│       └── index.scss
└── widgets/
    └── order-card/
        ├── index.tsx
        └── index.scss

入口发现遵循以下规则:

  1. 一级 src/pages/*/index.tsx 和 src/widgets/*/index.tsx 可按约定自动发现;
  2. Page / Widget 的多级目录、首页顺序和 metadata 在 src/app.config.ts 中显式声明;
  3. 显式 pages 数组的第一项作为首页入口;

Page 使用由完整入口派生的 URL 作为身份。旧 Page ID 打开方式仅作为兼容入口保留,新代码和调试流程应使用 URL。Widget 默认 id 由入口目录名推导;需要被 Manifest 长期引用时,建议在配置对象中显式声明稳定且全局唯一的 id。查询和调试方式见全页(Full Page)开发。

应用配置

前端配置、Manifest 和视图代码分别解决不同问题:

配置位置负责内容不负责内容
src/app.config.tsPage / Widget 入口、名称、标题和卡片形态实体 schema、权限和出卡绑定
manifest.yamlAppID、MCP Server、实体、权限和出卡绑定模板 Props、字段格式化和组件状态
Page / Widget TSXView Data 校验、模板映射、交互和本地状态替代 Manifest 权限配置

构建流程会同时消费前端入口配置与工程配置,但二者不会互相覆盖业务字段。工程目录、Manifest 和调试流程见前端开发(卡片 / 全页)。出现“入口能预览但正式对话不出卡”时,应检查 Manifest 和出卡绑定,而不是继续修改 app.config.ts 中的 UI metadata。

src/app.config.ts 集中维护以下信息:

  • 应用的 appId、name、描述和关键词;
  • Page / Widget 入口及其 metadata;
  • Widget 的卡片形态;

应用配置应同时提供 appId 和 name;标题、描述和卡片形态在 src/app.config.ts 中集中维护。

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

export default defineAppConfig({
  appId: 'your-app-id',
  name: '订单助手',
  description: '查询订单并展示处理进度',
  keywords: ['订单', '进度'],
  pages: [
    {
      entry: 'pages/order-detail/index',
      title: '订单详情'
    }
  ],
  widgets: [
    {
      entry: 'widgets/order-card/index',
      name: '订单卡片',
      description: '展示订单摘要与当前状态',
      boxType: 'inbox',
      border: true,
      titleType: 'none'
    }
  ]
});

配置时注意:

  • pages 对象项用于补充标题等 metadata;
  • widgets 对象项还可配置名称、描述、边框和标题形态;
  • 只有确有 Web 目标时才配置入口的 web 字段;

配置 web 字段不代表豆包应用插件的 UI 渲染环境与 Web 行为完全一致。

入口定义

三类入口分别承担应用生命周期和界面渲染职责。下面只展示入口定义的最小结构;数据、生命周期和交互逻辑分别在对应专题文档中说明。

Page / Widget 直接导出函数组件,并在 src/app.config.ts 中注册入口。视图生命周期使用 useShow()、useHide()、useMounted() 等 Hooks。

App 示例

// src/app.ts
import { defineApp } from '@doubao-dev/framework';

export default defineApp({
  onError(error) {
    console.error('app error', error);
  }
});

Widget 示例

// src/widgets/order-card/index.tsx
export default function OrderCard() {
  return <view className="order-card" />;
}

Page 示例

// src/pages/order-detail/index.tsx
export default function OrderDetailPage() {
  return <view className="page" />;
}

函数组件只负责返回组件树。请求、订阅、计时器和宿主 API 调用应放在 useEffect、生命周期 Hooks 或事件处理函数中。完整实现方式见卡片(Widget)开发和全页(Page)开发。