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/ai-assisted-development.md.

AI 辅助开发

概述

你可以让 AI 按豆包应用插件的开发规范编写代码,再结合页面和日志排查问题。建议按下面的步骤开始:

  1. 读取项目 Skill 和现有代码。
  2. 实现最小必要改动。
  3. 使用 dbx dev 运行并定位问题。
  4. 按改动范围完成验证,由开发者检查代码差异。
提示
  • Terminal Coding Agent、AI IDE 和豆包 PC 任务模式均可使用本流程。
  • 请从豆包应用插件项目根目录启动 AI,并确保其具备文件读取和终端执行能力。
  • 如果 AI 使用的终端无法让服务持续运行,请另开一个终端运行 dbx dev。

使用前准备

  1. 初始化项目。 进入准备存放项目的文件夹,用一个还没有创建的目录名运行:

    dbx init my-app
    cd my-app
  2. 完成交互配置。 按提示选择你使用的 Agent,并确认是否初始化 Git 仓库。CLI 会直接在新项目的根目录生成前端工程。省略目录名、直接运行 dbx init 时,会先提示输入项目文件夹名,如下图所示。

初始化项目的终端输出

初始化完成后,项目根目录同时包含 manifest.yaml、package.json、src/ 和 skill/SKILL.md。已有项目更新开发 Skill 时,在项目根目录执行 dbx skills sync。

  1. 加载项目规则。 初始化完成后,项目会生成 manifest.yaml、skill/SKILL.md、AGENTS.md,并安装所选 Agent 的开发 Skill。

描述开发任务

直接告诉 AI 想做什么即可,一句话也可以:

帮我在首页增加一个天气卡片。

任务较复杂时,再补充关键效果和验收方式:

帮我在首页增加一个天气卡片,展示当前城市、温度和天气状态,加载失败时可以重试,完成后用 dbx dev 验证。

如果不需要 AI 帮忙开发一项完整能力,只需要 AI 帮忙解决卡点,也可以让 AI 进行答疑:

我想给我的xxx mcp配置一张widget id为xxx的卡片,应该如何配置?entity应该如何设计?

开发一项完整能力

如果任务涉及新增完整能力,只需告诉 AI 功能要做什么、是否需要出卡、卡片展示什么,以及点击后去哪。例如:

帮我增加查询天气功能:展示城市、温度和天气状态;在对话中显示天气卡片,点击后进入详情页。请补齐需要的实现和配置,并用 dbx dev 验证。

AI 会同时检查以下部分:

交付项要求
skill/SKILL.md说明模型何时、如何调用 Tool。
MCP Server / Tool至少提供一个可用的 Tool,实现业务逻辑。
manifest.yaml配置真实 app_key、mcp_server.end_point 和 Tool。
Page至少提供一个 Page。
src/app.config.ts注册 Page;有 Widget 时一并注册。

使用 dbx dev 调试

启动本地服务和 Web 模拟器

在豆包应用插件项目根目录运行:

dbx dev

服务启动后,在控制台输入 web,或打开终端显示的完整 Web 地址,即可预览。也可以让 AI 运行 dbx dev 并保持服务运行;如果需要它继续操作控制台,请让它使用交互式终端(TTY)。启动命令不支持 --json。

项目包含本地 MCP Server 时,可以让 AI 一起启动:

请启动项目的本地 MCP Server 和 dbx dev,打开 Web 模拟器。如果启动失败,先检查项目配置和日志,再告诉我缺少什么。

dbx dev 启动后的调试控制台

在控制台输入 <命令> --help 可查看对应命令的用法。更多命令和真机流程见 本地调试与预览。

让 AI 读取调试现场

打开 Web 模拟器后,可以直接让 AI 复现和排查问题,只需要这样告诉 AI:

请检查当前 Web 模拟器,复现【问题】,结合页面、日志和调用链定位根因并修复;完成后用相同输入复验。

如果 AI 暂时读不到调试信息,先确认 dbx dev 和 Web 模拟器仍在运行,再复现一次问题。

调试循环

  1. 用同一输入或操作稳定复现问题。
  2. 让 AI 检查 Web 模拟器和运行日志,定位根因并只修改必要文件。
  3. 用相同输入再次验证,确认问题已解决且没有引入新问题。
  4. 只有 AI 判断配置、目录或端口发生变化时,才重启 dbx dev。

验证与交付

不同命令覆盖不同链路:

验证目标推荐方式
前端类型、依赖和打包在项目根目录运行项目定义的构建命令,例如 pnpm build
Manifestdbx check --file manifest.yaml --json
Skill / MCP / Manifest / 出卡链路dbx check --query '<query>' --expect-card required --verbose
Page / Widget 运行和视觉dbx dev --mcp-endpoint <endpoint>,必要时按本地调试与预览做真机验证

--expect-card required 仅用于当前 Query 应该出卡的场景;不应出卡时使用 none,不确定时使用默认值 auto。

运行 check 前,确认 Manifest 中的 MCP 地址指向本次要测试的服务。dev --mcp-endpoint 只影响调试服务,不会修改 check 使用的地址;需要使用另一份配置时,给 check 添加 --manifest <path>。

交付时要求 AI 说明:

  • 修改了哪些文件。
  • 执行了哪些验证,结果是否通过。
  • 哪些链路尚未验证。

安全边界

  • 不把 AppSecret、access token、cookie、手机号或真实用户数据放入提示词、代码、截图、日志和 Git。
  • 不把本地调试服务或 MCP Server 暴露到公网。
  • 未经开发者确认,不让 AI 上传产物、触发云构建、提交审核、发布版本、删除资源或修改线上配置。
  • 交付前 review git diff,重点检查无关改动、新增依赖、权限扩大,以及调试地址或沙箱配置残留。

常见问题

AI 使用了错误的框架或组件 API

确认从豆包应用插件项目根目录启动,并要求它先读取 AGENTS.md 和 doubao-agentic-service-development Skill。

Widget 已修改,但对话不出卡

检查 MCP Tool、manifest.tools、entity、tool_card_binding 和运行态 Skill,再用 dbx check --query '<query>' --expect-card required 验证出卡链路。

Web 模拟器没有更新

让 AI 确认改动位于当前项目根目录的 src/,并刷新 Web 模拟器;若仍无法定位,保持 dbx dev 和模拟器运行后复现一次。