> 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.

# 本地调试与预览

## 概述

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

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

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

## 功能简介

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

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

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

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

![dbx dev 启动后的调试控制台](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/dbx-dev.6999c4f9d4.png)
**命令一览**

| 命令        | 作用                                |
| --------- | --------------------------------- |
| `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 或日志。

:::info 提示

本地调试时，业务 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`。

在调试控制台中执行：

```text
web
```

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

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

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

![图片展示的是使用Web模拟器调试时的对话调试面板界面。左侧模拟手机界面显示时间为09:30，有消息输入框。右侧是调试信息区域，包含基础信息、资源状态、MCP等板块，如技能ID、MCP工具等信息，部分信息被遮挡。右侧还有常驻的Chrome DevTools区域，包括Elements、Console、Agent Trace/Sandbox/Preact等调试工具。该图直观呈现了对话调试面板的布局与内容，与上下文介绍的对话调试功能相契合。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/Vl1mwzOqxi5E28keflecEmzQnug-02.95a1997c31.png)

- 卡片：选择卡片模板，编辑 `structuredContent` JSON 后重新渲染，并检查卡片运行状态。

![图片展示了使用Web模拟器调试时的Chrome DevTools界面。左侧是模拟器界面，显示“请选择卡片模板，编辑structuredContent JSON后重新渲染，并检查卡片运行状态”等内容。右侧是DevTools区域，Elements标签下可查看和高亮元素，当前选中“Filter”；Console标签下显示运行日志；Agent Trace/Sandbox/Preact标签下可查看调试链路、沙箱状态和React组件信息。该图与文档中介绍使用Web模拟器调试的内容相关，直观呈现了调试时的界面情况。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/Vl1mwzOqxi5E28keflecEmzQnug-03.9dd5d39998.png)

- 全页：调试页面跳转、页面路径、返回和刷新，查看页面运行时内容。

![该图片展示了Web模拟器本地调试的操作界面，左侧是模拟手机界面，呈现“豆包商超助手 Demo”的应用页面；右侧是Chrome DevTools的开发者工具区域，当前选中“Elements”选项卡，顶部标签栏有Overview、Agent Trace、Sandbox等多个调试选项，DevTools左侧可查看页面对应的HTML代码结构，上方是各调试功能的入口，用于辅助调试与预览本地开发的应用效果。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/Vl1mwzOqxi5E28keflecEmzQnug-04.54a2f7b62f.png)

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

![Web 模拟器的工具调试界面：左侧选择工具、填写参数并查看执行结果，右侧显示 DevTools 调试信息。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/web-simulator-tool-debug.74e4dd3f6e.png)

右侧是常驻的 Chrome DevTools 区域，提供：

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

## 使用真机调试

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

### 连接真机

开始前请确认：

:::info 提示

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


:::

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

```text
desktop
```

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

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

![浏览器中的真机调试二维码页面，按豆包客户端版本提供两种二维码（二维码已脱敏）](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/dbx-dev-desktop-qr.2b954bb674.png)
等待连接时请保持二维码页面打开，关闭页面会取消本次等待。连接成功后，CLI 会记录当前活跃设备，后续 `page` 和 `widget` 命令默认使用该设备。若设备已连接且可直接调试，CLI 会复用连接并跳过扫码。

二维码过期或需要重新连接时，执行：

```text
qr
```

### 推送页面和卡片

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

```text
pages
widgets
```

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

```text
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` 控制台中执行：

```text
desktop --mcp
```

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


<img alt="执行 desktop --mcp 后选择已上传的版本" src={image6} />

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

### 使用 PC 端开发者工具调试

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

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

![图片展示了使用PC端开发者工具调试时的界面。左侧为调试目标选择区域，可选择页面或卡片。中间是实时预览区域，显示“睡眠打卡”页面，有“7小时40分钟”倒计时。右侧是开发者调试区域，包含Elements、Console、Sources等面板，Elements面板突出显示了“home_page”相关代码。该图片与文档中“使用PC端开发者工具调试”内容相关，直观呈现了调试时的操作界面及关键功能区域。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/Vl1mwzOqxi5E28keflecEmzQnug-06.b3008a7a49.png)

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

#### 在 GUI 中推送页面或卡片

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

![图片展示了使用PC端开发者工具调试时的调试器界面。左侧显示了app key、host、调试内容等信息，下方有“选择页面或卡片”下拉框，列出“douban_apps_expired_widget”等选项，底部有“推卡到真机”按钮。右侧有“选择页面或卡片”“点击‘推卡到真机’”“真机加载目标并进入调试”三个步骤说明，以及“调试页面准备中，请从‘页面目标’中选择”的提示框。该图与文档中使用PC端开发者工具调试的内容相关，直观呈现了调试操作步骤及界面。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/Vl1mwzOqxi5E28keflecEmzQnug-07.67736b2a08.png)

**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等内容。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/Vl1mwzOqxi5E28keflecEmzQnug-08.0249cf8208.png)

## 常见问题

### 扫码后提示 `fail to decode debug info`

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

### 二维码超时了怎么办

在 `dbx dev` 控制台里执行：

```text
qr
```

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

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

执行 `page`，从列表中选择目标页面：

```text
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。例如：

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

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