开发概览
本文档面向正在完成具体前端开发任务的开发者,说明从选择视图形态到调用宿主能力的完整开发路径。豆包应用插件前端主要提供三种面向用户的形态:Widget、Page 和多任务。三者解决的问题不同,但可以围绕同一个业务流程协作。
开始前
进入本组文档前,项目应满足以下条件:
- 已完成项目初始化,并能在项目根目录找到
src/app.config.ts; - 项目根目录包含
manifest.yaml; - 已安装前端依赖,并准备好本地调试环境;具体安装、启动和调试操作见开发工具文档;
前端开发文档回答“如何完成一次开发任务”,包括入口注册、数据读取、界面实现、能力调用和调试验证。本组文档会直接给出独立开发所需的最小框架规则,不把必要步骤只放在框架文档中。端侧框架文档则回答“这些能力在运行时如何工作”,用于理解生命周期、数据更新、渲染线程和完整能力边界。
先选择合适的形态
一个常见的组合方式如下。MCP Tool 执行结果不会直接变成 Widget;是否出卡、使用哪个 Widget,由产品出卡协议根据 MCP Tool、实体类型和 widget_id 绑定关系决定。
这不是固定流程:简单结果可以只使用 Widget,纯页面型服务可以直接打开 Page;只有需要持续运行和回访的业务才需要接入多任务。
让 Agent 调用能力和理解页面
Widget、Page 是交互载体;端工具和全页事件负责 Agent 与端侧的协作,不是新的视图形态。
先判断数据来自哪里:端工具不能直接读取另一个 Page 的组件 state;事件不会自动打开页面或持久化业务数据。两条链路可以围绕同一业务流程配合,但需要独立验证。
从需求到可验证界面
前端开发可以按以下顺序推进:
- 根据交互空间和业务时长选择 Widget、Page,必要时组合使用;
- 在
src/app.config.ts注册入口,确认 Widget ID 或 Page URL; - 在视图代码中读取 View Data,完成展示、空态和交互;
- 需要路由、网络、权限或卡片更新时,从
@doubao-dev/framework/api调用公开 API; - 先在 Web 模拟器中验证视图,再验证 MCP Tool 到 Widget 的完整出卡链路;工具操作见开发工具文档;
一次前端开发会涉及哪些文件
先区分“界面代码”和“界面如何被触达”。Page 只做独立页面预览时,不需要配置出卡协议;Widget 需要在正式对话中出现时,除了前端代码,还必须接通 ToolResult 和 Manifest。
运行态 Skill 以目录为入口,并按业务领域拆成多份 SKILL.md。dbx dev 会递归读取 skill/
下的所有 SKILL.md;不要再用单份文件承载整个应用的行为。
推荐的目录如下:
编写 Page 和 Widget 的最小规则
只阅读本组文档开发界面时,至少遵守以下规则:
以下骨架展示了这些规则如何组合。示例中的 /orders/<id> 是业务接口路径,需要替换为实际服务契约;request 只负责发起请求,不会自动校验业务数据。
使用环境变量区分业务环境
应用插件默认使用原有的 reload 路径。需要在卡片复用时重新执行 JS 入口时,可以显式开启此行为:
这是构建进程的环境变量,需要重启开发服务或重新构建产物后生效;不是页面运行时开关。仅当该变量的值为 1 时启用;未设置或设置为其他值时保持关闭。SDK 的 External Bundle 构建也支持相同变量。
环境变量用于把会随开发环境变化的非敏感配置与 TSX 源码分离。例如,不同开发者或调试环境需要连接不同的测试服务时,页面代码不需要因此修改请求地址。
本地开发需要连接测试服务时,可以在项目根目录创建 .env.local:
在 Page / Widget 中读取该变量并拼接具体接口路径:
如果另一位开发者需要连接不同的测试服务,只需把自己的 .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已完成完整链路验证;
调试时先判断问题在哪一层
调试工具显示请求已发送,不代表视图已经完成渲染。最终以 Web 模拟器中的实际渲染结果为准。启动、选择入口、注入测试数据和查看日志的方式见开发工具文档。
从哪里继续阅读
建议先读完本页,再按任务进入对应文档。只完成单一视图时,不要求先读完端侧框架文档。
本组文档已经覆盖独立完成常规 Page / Widget 开发所需的流程。需要继续理解运行时内部机制或排查复杂问题时,再进入端侧框架文档: