框架概述与应用配置
豆包应用插件的端侧框架面向“AI 对话中的可交互服务”组织应用。本文依次介绍框架分层、应用组成、构建与运行机制,以及对应的工程约定和入口定义方式。
框架分层
应用插件前端的运行职责可以分为四层:业务入口、Framework、UI 渲染器和豆包宿主。UI 渲染器底层由 Lynx 提供,负责将组件树转换为原生视图。四层之间的关系如下图所示。
实线表示开发者代码进入视图渲染的主要链路,虚线表示宿主向 Framework 提供运行环境。App 负责应用级生命周期,不进入 UI 渲染链路;只有 Page 和 Widget 会挂载组件树。
各层职责如下表所示。
注意
Page 和 Widget 不是浏览器网页。开发时不要直接套用 HTML DOM、浏览器 CSS 默认值或同步主线程的执行假设。
开发时按以下文档确认可用能力:
应用组成
一个应用插件可以包含 App、Page、Widget 和 Client Tool 入口。各入口承担不同职责,并分别进入对应的运行上下文。
这些入口之间存在明确边界:
- 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 接口读取对前端开放的数据。
这套构建与运行方式有四个直接影响开发的结论:
- App 随应用运行时启动,不依赖某个 Page / Widget 是否已经显示;
- Page / Widget 是独立视图产物,不能依赖彼此的模块内存或组件 state;
- Page 按 URL 打开,Widget 根据出卡数据绑定,二者的宿主入口不同;
- 业务代码只定义入口和组件,构建工具负责生成 bootstrap、视图根节点和产物清单;
端工具没有 Page 的组件树和视图状态,不应依赖某个页面先初始化。工具返回值与 Agent 事件经过不同链路,具体见Agent 与端侧交互。
工程约定
公开包的导入边界
导入 API 时注意区分:
- React Hooks 从
@doubao-dev/framework导入,以保持依赖与豆包应用插件内置的 React 运行时一致; - 端能力从
@doubao-dev/framework/api导入;
推荐目录
入口发现遵循以下规则:
- 一级
src/pages/*/index.tsx和src/widgets/*/index.tsx可按约定自动发现; - Page / Widget 的多级目录、首页顺序和 metadata 在
src/app.config.ts中显式声明; - 显式
pages数组的第一项作为首页入口;
Page 使用由完整入口派生的 URL 作为身份。旧 Page ID 打开方式仅作为兼容入口保留,新代码和调试流程应使用
URL。Widget 默认 id 由入口目录名推导;需要被 Manifest 长期引用时,建议在配置对象中显式声明稳定且全局唯一的
id。查询和调试方式见全页(Full Page)开发。
应用配置
前端配置、Manifest 和视图代码分别解决不同问题:
构建流程会同时消费前端入口配置与工程配置,但二者不会互相覆盖业务字段。工程目录、Manifest 和调试流程见前端开发(卡片 / 全页)。出现“入口能预览但正式对话不出卡”时,应检查 Manifest 和出卡绑定,而不是继续修改 app.config.ts 中的 UI metadata。
src/app.config.ts 集中维护以下信息:
- 应用的
appId、name、描述和关键词; - Page / Widget 入口及其 metadata;
- Widget 的卡片形态;
应用配置应同时提供 appId 和 name;标题、描述和卡片形态在 src/app.config.ts 中集中维护。
配置时注意:
pages对象项用于补充标题等 metadata;widgets对象项还可配置名称、描述、边框和标题形态;- 只有确有 Web 目标时才配置入口的
web字段;
配置 web 字段不代表豆包应用插件的 UI 渲染环境与 Web 行为完全一致。
入口定义
三类入口分别承担应用生命周期和界面渲染职责。下面只展示入口定义的最小结构;数据、生命周期和交互逻辑分别在对应专题文档中说明。
Page / Widget 直接导出函数组件,并在 src/app.config.ts 中注册入口。视图生命周期使用 useShow()、useHide()、useMounted() 等 Hooks。
App 示例
Widget 示例
Page 示例
函数组件只负责返回组件树。请求、订阅、计时器和宿主 API 调用应放在 useEffect、生命周期 Hooks 或事件处理函数中。完整实现方式见卡片(Widget)开发和全页(Page)开发。