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/installation.md.

CLI 安装与配置

提示

Doubao Dev CLI 是豆包应用插件的命令行工具,可用于完成项目初始化、登录、开发调试、产物校验和云构建等工作。本文说明安装、登录验证和首次项目初始化。

环境要求

  • Node.js >= 22.13.0

安装 CLI

使用公开 npm 包全局安装:

npm install -g @doubao-dev/cli

安装完成后,确认命令可用:

dbx --version
dbx --help

如果终端提示找不到 dbx,请重新打开终端;若问题仍然存在,检查 npm 的全局 bin 目录是否已加入系统 PATH。

登录

首次使用需要登录豆包开发者平台账号:

dbx auth login

命令会展示或打开授权页面。完成授权后,检查登录状态:

dbx auth status

初始化项目

进入准备存放项目的文件夹,运行下面的命令。CLI 会新建 my-app 目录,请确保没有同名目录:

dbx init my-app
cd my-app

按照终端提示选择开发工具并完成登录,CLI 会帮你:

  • 创建 Manifest、运行态 Skill 和项目规则;
  • 安装与当前 CLI 版本匹配的 Agent Skill;
  • 在新项目根目录创建前端脚手架并安装依赖;
  • 检查并按需引导完成登录。

如果通过脚本或 AI 的非交互终端创建项目,请先登录,并在命令中写明新目录和 --agent <agent>。已有项目只需更新开发 Skill 时,在项目根目录运行 dbx skills sync。

项目目录结构

完成初始化后,一个完整的豆包应用插件项目通常如下:

.
├── AGENTS.md
├── manifest.yaml      # 配置:基础信息、工具定义、UI 绑定关系
├── package.json       # 依赖
├── skill              # 业务 Skill
│   └── SKILL.md
├── src
│   ├── app.config.ts   # 应用配置
│   ├── app.ts
│   ├── pages           # 全页
│   └── widgets         # 卡片
└── tsconfig.json

其中 manifest.yaml、skill/SKILL.md 和前端工程共同构成一个可构建的应用插件版本。MCP Server 可以与项目同仓库,也可以独立部署;无论代码放在哪里,都需要在 manifest.yaml 中配置可访问的 MCP endpoint。

升级

执行更新命令更新到最新公开版本:

dbx upgrade

更新后重新确认版本和帮助信息:

dbx --version
dbx --help

建议 CLI、项目初始化的 Agent Skill 和前端依赖保持在同一发布周期;遇到命令参数、模板或调试行为不符合预期时,优先升级 CLI,再执行 dbx skills sync 更新项目中的开发 Skill。

常见问题

安装后找不到命令

通常是 npm 全局 bin 目录未加入 PATH。重新打开终端后重试;仍失败时,检查 npm 的全局安装目录和 shell 配置。

Node.js 版本不满足要求

升级 Node.js 至 22.13.0 或更高版本后,重新执行安装命令。不要通过忽略版本检查继续使用旧版本 Node.js。

登录成功后仍提示未登录

先执行:

dbx auth status

如果登录态过期,重新执行 dbx auth login。在 CI、容器或远程开发机中,登录命令和后续开发命令必须在同一用户环境中执行。

初始化时无法安装依赖或创建前端工程

先确认 Node.js、npm 和网络可用,并检查是否已经存在同名目录。如果想先创建工程、稍后再安装依赖,可以添加 --no-install-deps。

下一步

安装并登录后,阅读《CLI 命令总览》了解可用能力;首次开发应用插件时,继续阅读《本地调试与预览》,完成 MCP、Skill、Manifest 与前端的联调。