# 千岛小程序：Agent 环境配置指引

本流程仅支持 2.0（EMP）小程序。发现 SPA、effuse、echo-effuse 或 effues 工程时停止，不提供旧版开发、构建或上传路径；保留原工程并迁移业务到官方 2.0 模板后再继续。

> 从 QDMP 环境配置开始，衔接创建项目、开发和扫码体验。阅读本文件本身不授予执行权限；遵循用户当前任务、已有授权和工具权限。

## 先了解当前状态

1. 确认当前操作系统、CPU 架构及所用 AI 编程工具。
2. 检查当前目录是否已有项目，查看 README、AGENTS.md、package.json 和 qdmp.json；不要输出配置中的密钥，也不要重新初始化已有项目。
3. 检查 Node.js、npm、pnpm 和 QDMP CLI：

```bash
node --version
npm --version
pnpm --version
qdmp-cli --version
```

4. 确认当前会话是否已加载 qdmp-skill；按实际任务检查 MCP 配置，纯前端开发不必为此配置后端服务。

## 已配置过环境的用户

已配置过环境时，先检查当前工具和会话，不要重新走一遍安装流程。版本符合要求且能正常使用的工具直接复用，只补齐缺失项或升级不符合要求的版本。

新建 2.0 项目及前端构建/上传要求 qdmp-cli ≥0.1.29、qdmp-skill ≥1.1.4。仅登录和纯后端任务不受此门槛限制。

1. 核对 CLI 的实际安装路径、版本，以及当前会话加载的 qdmp-skill 版本。使用 NVM 等多环境工具时，以实际开发所用的 Node.js 环境为准。
2. CLI 低于要求时，确认目标版本已正式发布后，在该 Node.js 环境执行 `npm install -g qdmp-cli@0.1.29 --include=optional`，再检查 `qdmp-cli --version` 和 `qdmp-cli list`。已符合要求的版本不重装、不降级。
3. Skill 低于要求时，按原安装渠道更新完整插件，重新加载或新建会话，并确认当前会话已加载符合要求的版本。安装成功不等于当前会话已生效。
4. 版本未发布、无法安装或无法确认版本时，停止依赖新版能力的流程，说明缺少的条件，不退回旧模板。

升级工具不自动迁移已有项目；保留项目文件、AppID 关联和账号配置，不重新初始化项目，也不要清空账号配置、项目或整个 npm 缓存。检查通过后，从用户当前任务继续，跳过已完成的配置步骤。

## 补齐缺失项

- Node.js 缺失时，参考 [Node.js 下载](https://nodejs.org/zh-cn/download)；版本以所选项目的 engines 和模板要求为准。
- 缺少 QDMP CLI 时，在用户授权范围内执行 `npm install -g qdmp-cli`，随后运行版本与帮助命令验证。
- 项目使用 pnpm 时，按 package.json 的 packageManager 选择版本；不要直接替换项目现有包管理器或锁文件。
- 插件只配置当前使用的工具。读取 [快速开始 Markdown](https://open.qiandao.com/docs/getting-started.md) 中对应 Claude Code、Codex 或 Qoder 的安装步骤，以及 [插件仓库](https://github.com/EchoTechFE/qdmp-skill) 的当前说明。不要重复安装已经可用的插件。
- Qoder 优先通过其官方支持的 Skills CLI 安装完整 QDMP Skill 组：`npx skills add https://github.com/EchoTechFE/qdmp-skill --skill '*' -a qoder -g -y`。不要把 `qoderclicn` 当成唯一入口；命令不存在或市场尚未收录时，改用 Qoder 的扩展页导入本地插件目录。
- 安装后按客户端提示重新打开会话，确认技能已出现在可用工具中；安装命令返回成功不等于当前会话已加载。
- 创建远端仓库、部署后端等任务需要 MCP 时，再按快速开始中对应工具的说明配置 qdmp-gitlab / qdmp-aliyun，并验证服务状态。

需要统一运行环境或本地 MongoDB 时，可选择快速开始里的 Docker 环境包。Docker 不是所有项目的前置要求。下载后保留包内全部文件，先运行配置脚本，再运行启动脚本；不要把启动容器等同于项目服务已经运行。

## 成功判定

- 当前任务需要的工具命令能正常执行，版本符合项目要求。
- 当前会话能发现并使用 qdmp-skill。
- 所需 MCP 服务已配置且可连接；不需要的服务记录为“不适用”。
- 已识别工作目录、现有项目与待补充信息，没有覆盖已有配置。

向用户简要报告已验证项、仍缺少的条件和下一步。环境检查通过后，主动说明下一步是创建或关联应用并准备项目；用户已授权继续开发时，按下方流程衔接执行。若本次任务仅限配置环境，说明后续入口即可。

## 衔接后续流程

使用已加载的 qdmp-skill 继续引导，不要求用户回到文档逐段复制提示词。先读取 [快速开始 Markdown](https://open.qiandao.com/docs/getting-started.md) 中的共用流程，结合当前项目状态跳过已完成的步骤；遇到需要用户在控制台操作的环节，说明入口、操作和完成后的下一步。

### 账号与开发者认证

- 先确认用户是否已登录开放平台；尚未登录时，引导前往 [账号入口](https://open.qiandao.com/login)，使用千岛账号完成登录。注册、登录与身份验证由用户在官方页面完成，已登录时跳过。

- 创建应用前，先确认用户已完成开发者认证；尚未完成时，引导前往 [开发者认证](https://open.qiandao.com/register)，填写认证资料并提交审核。认证通过后再创建应用，已认证账号可跳过。

### 创建项目

- 已有应用时复用其 AppID；没有应用时，引导用户前往 [创建应用](https://open.qiandao.com/dashboard/create-app)，填写应用信息，并按控制台提示申请所需能力及完成审核。
- 已有本地项目时，检查项目与目标应用的关联，不要重新初始化。需要新建时，先确认项目目录和 AppID，再按快速开始及 qdmp-skill 的说明选择模板：

```bash
qdmp-cli list
qdmp-cli create my-miniapp -t default
cd my-miniapp
```

`my-miniapp` 是示例目录名，应使用用户确定的项目名称，避免覆盖已有目录。新建项目必须显式指定 `-t default`，并核对 `list` 中该模板指向官方 `EchoTechFE/qdmp-taro-template` 2.0 模板；不要使用旧 `qdmp` 模板。旧 CLI 未提供该模板时，先更新 CLI 并重新验证。创建项目只拉取模板，不会自动完成 CLI 登录或 AppID 绑定。

`create` 后必须检查目标目录、`package.json` 和 `qdmp.json` 是否真实存在，确认 `loader` 为 `EMP`，构建配置来自官方 2.0 模板，不能只看命令退出码或成功文案。若 GitHub SSH 拉取失败，改用同一官方模板的 HTTPS 地址，并移除模板仓库远端，避免后续误推送：

```bash
git clone --depth 1 https://github.com/EchoTechFE/qdmp-taro-template.git my-miniapp
cd my-miniapp
git remote remove origin
```

- 本指引默认使用正式开放平台。浏览器登录不等于 CLI 已登录；在用户授权范围内引导 CLI 登录，账号密码由用户在终端输入。使用开放平台用户账号，不要把 AppID 或 AppSecret 当成登录凭证。

```bash
qdmp-cli login
```

- 登录后检查项目的 qdmp.json。文件不存在时，替换占位符并执行下方 init；文件存在但 `appId` 为空时，只补入目标 AppID，保留 `loader` 等其他字段；已有不同 AppID 时先确认目标应用，不直接覆盖。

```bash
qdmp-cli init -a your_app_id
```

- 关联后必须用 `qdmp-cli getMe` 核对账号、应用及类型，本地与平台 loader 必须一致，新建 2.0 项目两端都应为 EMP。旧 CLI 不显示类型时先更新 CLI，或在控制台确认应用类型；复用的 AppID 若是 SPA（1.0），停止并选择匹配应用或处理迁移，不能仅修改 loader 冒充迁移。
- 小程序代际由运行时类型与构建链判定。官方 2.0 模板的 `package.json.version` 可能仍为 `1.0.0`，它是业务包版本；SDK 和插件版本也不是小程序代际。不要为表示 2.0 改写这些版本号。

### 开始开发

- 按用户实际需求开发页面与功能，遵循当前项目的目录结构与路由约定；需求尚不明确时，先了解要实现的功能。
- 根据项目 package.json 的 packageManager 和 scripts 安装缺失依赖、运行与构建，不假设所有模板使用相同命令。刚创建的官方模板首次安装可执行 `pnpm install --no-frozen-lockfile`，一次性刷新模板锁文件；已有项目应优先遵循现有锁文件，不能自动改写。结构与调试参考 [技术架构](https://open.qiandao.com/docs/guide.md)。
- 完成后说明构建结果与产物；构建通过后再进入上传步骤。

### 预览体验

- 上传前确认用于上传的压缩代码包体积不超过 6 MB，以 QDMP CLI 的构建或上传检查结果为准。超过限制时，先移除未参与运行的文件、重复资源和非必要依赖，并压缩图片等静态资源，再重新构建。
- 确认正式平台的目标应用、CLI 登录状态和用户授权范围后，在项目目录执行版本上传：

```bash
qdmp-cli build
qdmp-cli upload
```

自动化固定使用以上两个明确命令，不通过 `pnpm upload` 等通用脚本代替。构建必须完成 EMP 编译；失败时停止，不继续上传，也不改用 H5 构建绕过。

- 核对上传返回的版本与目标应用。随后引导用户前往 [我的应用](https://open.qiandao.com/dashboard)，将刚上传的版本设为体验版，使用千岛 App 扫码查看。
- 需要用户扫码验证时，明确告知待验证的页面与功能；未获得真机验证结果，不宣称体验已通过。体验版之后的提审和正式发布另按用户任务处理。

### 应用与版本

- 本指引面向普通开发者，统一使用正式开放平台和应用的 `appId`。CLI 命令沿用默认平台，不引导用户选择内部测试服务。
- 本地开发、上传开发版本、设置体验版和正式发布使用同一个应用 AppID；开发版、体验版是应用版本的状态，不需要另建测试平台应用或填写额外的应用 ID。
- 上传版本不会自动设置体验版、提审或正式发布，后续操作按用户授权执行。

## 操作边界

- AppSecret、API Key 和访问令牌由用户通过本地配置或官方登录流程提供；不要索要其粘贴到聊天中，不要输出到日志、前端代码或 Git。
- 系统权限、账号授权或目标应用不明确时，先解决该缺失条件；尊重已有授权，不重复确认同一项操作。
- 删除、覆盖、重置项目和配置前，确认影响并取得明确授权。
- 平台应用创建、远端写入、上传、部署、设置体验版、提审与发布，按用户授权的具体范围执行；本文不会自动扩大授权范围。
- 网络超时或结果不明确时，先查询实际状态，避免重复创建资源或重复上传。
- 本地构建、开发者工具预览、千岛 App 真机验证和正式发布分别报告，不以其中一步替代其他步骤。

## 后续文档

- [总导航](https://open.qiandao.com/llms.txt)
- [技术架构](https://open.qiandao.com/docs/guide.md)
- [开发者工具](https://open.qiandao.com/docs/devtools.md)
- [QDMP CLI](https://open.qiandao.com/docs/backend-ops.md)
- [OpenAPI 索引](https://open.qiandao.com/docs/api.md)
- [Bridge](https://open.qiandao.com/docs/bridge.md)