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

# AI 辅助开发

## 概述

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

1. 读取项目 Skill 和现有代码。
2. 实现最小必要改动。
3. 使用 `dbx dev` 运行并定位问题。
4. 按改动范围完成验证，由开发者检查代码差异。

:::info 提示

- Terminal Coding Agent、AI IDE 和豆包 PC 任务模式均可使用本流程。
- 请从豆包应用插件项目根目录启动 AI，并确保其具备文件读取和终端执行能力。
- 如果 AI 使用的终端无法让服务持续运行，请另开一个终端运行 `dbx dev`。


:::

## 使用前准备

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

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

![初始化项目的终端输出](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/dbx-init.b9d14fa43a.png)
初始化完成后，项目根目录同时包含 `manifest.yaml`、`package.json`、`src/` 和 `skill/SKILL.md`。已有项目更新开发 Skill 时，在项目根目录执行 `dbx skills sync`。

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

## 描述开发任务

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

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

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

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

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

```xml
我想给我的xxx mcp配置一张widget id为xxx的卡片，应该如何配置？entity应该如何设计？
```

### 开发一项完整能力

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

```bash
帮我增加查询天气功能：展示城市、温度和天气状态；在对话中显示天气卡片，点击后进入详情页。请补齐需要的实现和配置，并用 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 模拟器

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

```bash
dbx dev
```

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

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

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

![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)
在控制台输入 `<命令> --help` 可查看对应命令的用法。更多命令和真机流程见 [本地调试与预览](/apps-plugin/docs/development-tools/local-debugging.md)。

### 让 AI 读取调试现场

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

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

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

### 调试循环

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

## 验证与交付

不同命令覆盖不同链路：

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

`--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` 和模拟器运行后复现一次。
