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/device-debugging.md.

真机预览

真机预览用于在豆包 App 中体验应用插件的指定版本。你需要先在豆包开发者平台选择要预览的应用插件和版本,获取该版本的体验二维码,再使用豆包 App 扫码进入调试状态。进入调试状态后,通过「应用插件 Debugger」发送 Query,即可查看该版本的实际响应。

开始前

开始预览前,请确认:

  • 已经确定需要预览的应用插件和版本。
  • 该版本已经完成云构建,并可在豆包开发者平台的版本管理中查看。
  • 移动设备已经安装并登录豆包 App。
  • 如果扫码账号不是该应用插件的所有者、管理员或开发成员,需要先取得该账号的豆包 UID,并将其加入当前应用插件的调试白名单。平台页面中该区域显示为「体验白名单」。

体验二维码与应用插件版本一一对应,并且具有有效期。切换版本或二维码过期后,需要重新获取二维码并扫码。

1. 选择应用插件和版本

打开豆包开发者平台,在「我的应用插件」中找到需要预览的应用插件并进入详情页。请同时核对应用插件名称和 AppID,避免进入同名或测试用途的其他应用。

在开发者平台选择需要预览的应用插件

选择需要预览的应用插件

在应用插件详情页的「版本管理」中找到目标版本。确认版本号正确,并且产物状态为构建成功,然后进入该版本的配置预览页。

在应用插件详情页选择构建成功的目标版本

选择构建成功的目标版本

2. 确认扫码账号具有预览权限

获取二维码前,先确认移动设备上登录的豆包账号是否具有预览权限:

  • 如果该账号已经是当前应用插件的任一角色,例如所有者、管理员或开发成员,可以直接进行后续操作,无需加入调试白名单。
  • 如果该账号不是当前应用插件的成员,请向预览者获取其豆包 UID,在应用插件详情页的「体验白名单」区域点击「添加白名单」,将该 UID 加入当前应用插件的调试白名单。

加入白名单的 UID 必须属于移动设备上实际用于扫码的豆包账号。豆包 UID 属于账号标识,请勿写入公开文档、代码仓库或日志。

3. 获取体验二维码

进入目标版本的配置预览页后,再次核对页面顶部显示的版本号,然后点击右上角的「体验二维码」。

在目标版本的配置预览页点击“体验二维码”

在目标版本的配置预览页点击“体验二维码”

平台会显示当前版本的体验二维码,同时列出应用插件、版本和二维码有效期。确认这些信息与要预览的目标一致。

如果弹窗提示需要先添加白名单,请返回应用插件详情页完成白名单配置,再重新获取二维码。

体验二维码及其对应的应用插件、版本和有效期

体验二维码及其对应的应用插件、版本和有效期

4. 使用豆包 App 扫码并确认调试版本

打开豆包 App 的侧边栏,点击底部的扫码按钮,扫描平台展示的体验二维码。

扫码成功后,豆包 App 会进入调试确认页。请重点核对以下信息:

  • app_key 是否属于目标应用插件。
  • app_version_tag 是否为需要预览的版本。

确认无误后,点击页面底部的「返回首页开始调试」。如果页面显示的应用插件或版本不正确,请勿继续,退出当前页面并为正确版本重新获取二维码。

在调试确认页核对应用插件和版本并开始调试

核对应用插件和版本并开始调试

完成确认后,豆包 App 会进入该应用插件、该版本的调试状态。接下来需要打开「应用插件 Debugger」发起预览 Query。

5. 打开应用插件 Debugger

根据是否曾经打开过「应用插件 Debugger」,选择对应方式。

首次打开

在移动设备的浏览器中打开 https://www.doubao.com/bot/2xgttdEs,或豆包移动端扫描二维码:

首次打开应用插件 Debugger 的入口二维码

点击“去和应用插件 Debugger 聊天”,进入应用插件 Debugger。

首次使用时通过移动端浏览器打开应用插件 Debugger

首次使用时通过移动端浏览器打开应用插件 Debugger

进入应用插件 Debugger 的详情页。

在应用插件 Debugger 中开启新话题

在应用插件 Debugger 中开启新话题

已经打开过应用插件 Debugger

如果之前已经打开过该 Bot,无需再次访问浏览器链接。打开豆包 App 的侧边栏,直接选择「应用插件 Debugger」。

从豆包 App 侧边栏打开应用插件 Debugger

从豆包 App 侧边栏打开应用插件 Debugger

6. 输入 Query 进行预览

在应用插件 Debugger 的输入框中输入测试内容。

对话页会显示当前调试状态对应的 appKey 和 versionTag。开始验证前,应确认它们与扫码时选择的应用插件和版本一致。

在应用插件 Debugger 中输入 Query 并查看预览结果

在应用插件 Debugger 中输入 Query 并查看预览结果

如果需要切换到另一个应用插件或版本,请重新获取对应版本的体验二维码,扫码确认后再开启新话题,避免旧会话影响验证结果。

常见问题

现象处理方法
扫码后提示没有权限确认扫码账号是否已经是当前应用插件的成员;如果不是,确认该账号的豆包 UID 已加入当前应用插件的「体验白名单」。白名单账号必须与豆包 App 当前登录账号一致。
扫码后显示的应用插件或版本不正确不要进入调试。返回豆包开发者平台,重新选择正确的应用插件和版本,并获取新的体验二维码。
二维码无法扫描或提示已失效体验二维码具有有效期。关闭旧弹窗,在目标版本页面重新获取二维码后再次扫码。
点击开始调试后没有进入对应版本的调试状态重新扫描二维码,在调试确认页核对 app_key、app_version_tag 和 debug_switch,并确认豆包 App 的登录账号没有发生变化。
找不到应用插件 Debugger首次使用时,在移动设备浏览器中打开 https://www.doubao.com/bot/2xgttdEs;此前已经打开过时,从豆包 App 侧边栏选择「应用插件 Debugger」。
修改后预览结果没有变化在应用插件 Debugger 中开启新话题。