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/development-tools/local-debugging.md.

本地调试与预览

概述

dbx dev 是豆包应用插件的本地开发调试入口。启动后,它会加载当前项目并启动本地调试服务,主要支持:

  • 打开 Web 模拟器;
  • 打开真机调试器;
  • 查看可用的页面和卡片;
  • 直接执行端工具,检查调用参数和返回结果;
  • 向已打开全页手动触发 Agent 事件,验证页面订阅与更新;

开发者可以先使用 Web 模拟器预览和验证交互;需要验证真实设备表现时,再通过 PC 端开发者工具连接手机进行调试。

功能简介

在终端运行 dbx dev,即可启动本地调试服务。控制台会显示项目信息和可用命令。

在控制台输入 status 可查看服务状态。服务就绪后,就可以打开 Web 模拟器预览,或连接真机调试页面和卡片。

也可以让 AI 运行 dbx dev,保持服务运行并打开终端显示的 Web 地址。如果需要让 AI 输入下文的控制台命令,请使用交互式终端(TTY)。启动命令不支持 --json。

以下命令均在 dbx dev 启动后的调试控制台中执行。

dbx dev 启动后的调试控制台

命令一览

命令作用
web打开 Web 模拟器。
desktop启动真机调试。
status查看本地调试服务以及 APP、SERVER、WEB 等子服务状态。

使用 Web 模拟器调试

Web 模拟器用于在浏览器中预览页面和卡片,适合验证基本交互和页面展示,不需要连接真机。

使用真实 AppID 调试沙箱环境

新版 CLI 支持使用真实应用的 db_app_* AppID 调用本地调试沙箱。AppID 用于标识应用,运行环境则由平台 OpenAPI 域名区分;使用真实 AppID 不代表调试请求会进入正式环境。

开始调试前,请确保以下三处使用同一个真实 AppID:

  • 项目根目录 manifest.yaml 中的 app_key
  • 前端配置中的 runtimeConfig.appId
  • 业务 Server 实际读取的 AppID

业务 Server 仍使用该真实应用对应的 AppSecret,并按项目现有的安全配置方式读取。AppSecret 只能保存在服务端安全配置中,不要写入前端代码、Manifest、Skill 或日志。

提示

本地调试时,业务 Server 调用豆包平台 OpenAPI 必须使用沙箱域名: DOUBAO_OPENAPI_BASE_DOMAIN=https://api-sandbox.doubao-dev.com Web 模拟器生成的登录码、手机号授权码、支付订单和回调状态均位于该沙箱环境。若业务 Server 调用正式 OpenAPI 域名,将无法识别这些调试数据。

注意:runtimeConfig.apiBaseUrl 是前端访问业务 HTTP Server 的地址;manifest.mcp_server.end_point 和 dbx dev --mcp-endpoint 是 MCP Server 地址。它们都不是豆包平台 OpenAPI 域名,不要混用。

原有的 doubao-sandbox-app-* 沙箱 AppID 仍然支持。先执行 dbx sandbox info 确认当前项目沙箱和 Secret 是否存在;只有确实需要 AppSecret 时,才执行 dbx sandbox info --include-secret。

在调试控制台中执行:

web

命令会打开 Web 模拟器页面。开发者可以在模拟器中选择调试内容、预览运行效果,并使用右侧调试面板定位问题。

调试内容包括对话、卡片、全页和工具:

  • 对话:模拟用户对话,查看卡片渲染、消息流、日志、Agent Trace,以及登录、支付等沙箱流程。

图片展示的是使用Web模拟器调试时的对话调试面板界面。左侧模拟手机界面显示时间为09:30,有消息输入框。右侧是调试信息区域,包含基础信息、资源状态、MCP等板块,如技能ID、MCP工具等信息,部分信息被遮挡。右侧还有常驻的Chrome DevTools区域,包括Elements、Console、Agent Trace/Sandbox/Preact等调试工具。该图直观呈现了对话调试面板的布局与内容,与上下文介绍的对话调试功能相契合。

  • 卡片:选择卡片模板,编辑 structuredContent JSON 后重新渲染,并检查卡片运行状态。

图片展示了使用Web模拟器调试时的Chrome DevTools界面。左侧是模拟器界面,显示“请选择卡片模板,编辑structuredContent JSON后重新渲染,并检查卡片运行状态”等内容。右侧是DevTools区域,Elements标签下可查看和高亮元素,当前选中“Filter”;Console标签下显示运行日志;Agent Trace/Sandbox/Preact标签下可查看调试链路、沙箱状态和React组件信息。该图与文档中介绍使用Web模拟器调试的内容相关,直观呈现了调试时的界面情况。

  • 全页:调试页面跳转、页面路径、返回和刷新,查看页面运行时内容。

该图片展示了Web模拟器本地调试的操作界面,左侧是模拟手机界面,呈现“豆包商超助手 Demo”的应用页面;右侧是Chrome DevTools的开发者工具区域,当前选中“Elements”选项卡,顶部标签栏有Overview、Agent Trace、Sandbox等多个调试选项,DevTools左侧可查看页面对应的HTML代码结构,上方是各调试功能的入口,用于辅助调试与预览本地开发的应用效果。

  • 工具:选择工具、填写调用参数并运行,查看返回结果,也可以将结果填入卡片预览。

Web 模拟器的工具调试界面:左侧选择工具、填写参数并查看执行结果,右侧显示 DevTools 调试信息。

右侧是常驻的 Chrome DevTools 区域,提供:

  • Elements:查看和高亮元素
  • Console:查看运行日志
  • Agent Trace / Sandbox / Preact:查看调试链路、沙箱状态和 React 组件信息

使用真机调试

真机调试用于验证页面和卡片在真实设备上的运行效果。连接真机后,可以通过 CLI 推送调试包,再使用 PC 端开发者工具观察和定位问题。

连接真机

开始前请确认:

提示
  • 手机已登录豆包账号并且与开发者工具使用的豆包账号一致;
  • 手机登录账号已加入目标应用插件的调试白名单;
  • 手机已通过数据线连接 PC,并保证手机和 PC 在同一 WIFI 环境下。
  • Android 设备需要开启开发者模式和 USB 调试。iOS 设备连接 USB 后,请在“是否信任此设备”提示中选择“信任”。

在调试控制台中执行 desktop。首次使用或工具版本更新时,CLI 会先准备本机开发者工具,再自动用默认浏览器打开二维码页面,默认等待 60 秒连接。

desktop

用手机上的豆包 App 扫描与客户端版本对应的二维码:

  • 客户端版本 < 1470:扫描页面中标注 < 1470 的二维码。
  • 客户端版本 >= 1470:扫描页面中标注 >= 1470 的二维码。

浏览器中的真机调试二维码页面,按豆包客户端版本提供两种二维码(二维码已脱敏)

等待连接时请保持二维码页面打开,关闭页面会取消本次等待。连接成功后,CLI 会记录当前活跃设备,后续 page 和 widget 命令默认使用该设备。若设备已连接且可直接调试,CLI 会复用连接并跳过扫码。

二维码过期或需要重新连接时,执行:

qr

推送页面和卡片

设备连接成功后,可以先查看项目中可用的页面和卡片:

pages
widgets

然后使用完整页面 URL 或卡片 ID 推送目标:

page "<page-url>"
widget hello-world --data '{"title":"今日推荐"}'
  • page [url] 使用 pages 列出的完整 URL,页面参数写入 URL query;省略 URL 时可交互选择页面;
  • widget [id] 使用 widgets 列出的卡片 ID,省略 ID 时可交互选择卡片;
  • widget --data 接收合法 JSON,作为卡片的 widgetData 传递;page 不支持 --data。

端到端调试

在 dbx dev 控制台中执行:

desktop --mcp

选择已上传的版本后,在应用插件 Debugger 中调试该版本的 UI 和 MCP 链路。

执行 desktop --mcp 后选择已上传的版本

这张图展示了一个本地调试相关的界面,上方是用户与助手的对话:用户询问昨天的睡眠时长后,助手回复用户昨晚22:30入睡、今早9:30起床,一共睡了11小时,提示本次睡眠时间偏长可调整作息。下方是睡眠记录的详细卡片,显示记录日期为8月18日,本次睡眠时长为11小时,标注“睡眠时间偏长”,还呈现了入睡、起床时间的滑动选择栏,以及“跨年夜是”“醒后感受未填写”等内容,底部有提示本次睡眠超过参考范围的文字,左下角标注了“Local Debug”字样,和文档中本地调试与预览的主题相关。

使用 PC 端开发者工具调试

真机连接成功后,可以使用 PC 端开发者工具查看页面或卡片的实际运行效果,并使用 Elements、Console 等面板定位问题。

首次使用时,工具会自动下载对应版本的开发者工具。

图片展示了使用PC端开发者工具调试时的界面。左侧为调试目标选择区域,可选择页面或卡片。中间是实时预览区域,显示“睡眠打卡”页面,有“7小时40分钟”倒计时。右侧是开发者调试区域,包含Elements、Console、Sources等面板,Elements面板突出显示了“home_page”相关代码。该图片与文档中“使用PC端开发者工具调试”内容相关,直观呈现了调试时的操作界面及关键功能区域。

选择页面或组件并注入测试数据,在模拟器或真机中预览,同时使用 Elements、Console 和 JSB 完成调试。

在 GUI 中推送页面或卡片

  1. 在左侧 调试目标 下拉框中选择页面或卡片。
  2. 在 JSON data 中填写可选的业务 JSON。
  3. 点击 推卡到真机。
  4. 在 输出结果 中查看成功结果或失败诊断。

图片展示了使用PC端开发者工具调试时的调试器界面。左侧显示了app key、host、调试内容等信息,下方有“选择页面或卡片”下拉框,列出“douban_apps_expired_widget”等选项,底部有“推卡到真机”按钮。右侧有“选择页面或卡片”“点击‘推卡到真机’”“真机加载目标并进入调试”三个步骤说明,以及“调试页面准备中,请从‘页面目标’中选择”的提示框。该图与文档中使用PC端开发者工具调试的内容相关,直观呈现了调试操作步骤及界面。

JSON 输入规则:

  • 留空时只发送目标 ID,不传 pageData 或 widgetData;
  • 非空时必须是合法 JSON;
  • 页面目标使用 pageData,卡片目标使用 widgetData;
  • 目标 ID 由下拉框负责,不需要写进 JSON。

GUI 发送推送前会检查设备连接状态:

  • 没有连接设备时,显示 no_connected_device;
  • 选择的设备已断开时,显示 selected_device_not_connected;
  • 连接多个设备时,需要明确选择目标设备。

选择调试 session

推送页面或卡片后,会产生对应的调试 session。顶部工具栏会显示当前 session,并优先跟随最新可用的 Lynx session。

如果当前 session 消失,GUI 会回退到其他可用 session;没有可用 session 时,右侧进入空状态。

图片展示了使用PC端开发者工具调试时的界面。左侧为调试设置区域,显示app key、host等信息。中间是调试session选择弹窗,突出显示“client 3 - session 6: SleepCheckCard”。右侧是调试内容区域,呈现代码和调试信息。该图片与上下文紧密相关,直观呈现了选择调试session的操作及界面情况,辅助说明推送页面或卡片后会产生对应的调试session,顶部工具栏会显示当前session等内容。

常见问题

扫码后提示 fail to decode debug info

先确认扫描的是与豆包客户端版本对应的二维码,再确认扫码手机登录的豆包 UID 已加入目标应用插件的调试白名单。不要在终端日志、截图或文档中暴露 UID;由应用管理员通过受控渠道添加后,重新生成二维码扫码。

二维码超时了怎么办

在 dbx dev 控制台里执行:

qr

命令会重新打开浏览器中的二维码页面,按豆包客户端版本选择对应二维码扫码。

页面总是打开成同一个页面

执行 page,从列表中选择目标页面:

page

也可先执行 pages,再将目标页面的完整 URL 传给 page "<page-url>"。不要传页面 ID 或源码路径;页面参数写入 URL query。

CLI 提示找不到设备

先确认:

  1. 手机已经扫码并授权真机调试。
  2. 当前 dbx dev 控制台还在运行。
  3. 没有连接多个未指定的设备。
  4. 如果之前设备断开过,重新执行 qr 扫码,或在 GUI 顶部选择最新调试目标。

PC 工具中显示 调试页面准备中

这表示当前还没有可用 Lynx 调试 session。可以:

  1. 确认手机已扫码连接。
  2. 在 CLI 中执行 status 查看 dev runtime 是否 running。
  3. 推送一个页面或卡片。
  4. 点击 GUI 顶部重载按钮刷新 DevTools iframe。

JSON data 写什么

只写业务数据,不写页面 id 或卡片 id。例如:

{
  "title": "今日推荐",
  "source": "debug"
}

目标 id 由 CLI 参数或 GUI 下拉框负责。