# 千岛小程序：Agent 环境配置指引 > 从 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 配置，纯前端开发不必为此配置后端服务。 先检查已有版本是否满足当前项目与模板要求，避免无依据升级、降级或重置环境。 ## 补齐缺失项 - 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) 的当前说明。不要重复安装已经可用的插件。 - 安装后按客户端提示重新打开会话，确认技能已出现在可用工具中；安装命令返回成功不等于当前会话已加载。 - 创建远端仓库、部署后端等任务需要 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 cd my-miniapp ``` `my-miniapp` 是示例目录名，应使用用户确定的项目名称，避免覆盖已有目录。`create` 默认使用第一个模板；需要其他模板时，先用 `list` 查看名称，再通过 `-t` 指定。创建项目只拉取模板，不会自动完成 CLI 登录或 AppID 绑定。 - 本指引默认使用正式开放平台。浏览器登录不等于 CLI 已登录；在用户授权范围内引导 CLI 登录，账号密码由用户在终端输入。使用开放平台用户账号，不要把 AppID 或 AppSecret 当成登录凭证。 ```bash qdmp-cli login ``` - 登录后检查项目的 qdmp.json。已有配置时核对 AppID 与目标应用是否一致，保留其他字段，不重新初始化。仅在文件不存在时，替换占位符并执行： ```bash qdmp-cli init -a your_app_id ``` - 关联后用 `qdmp-cli getMe` 核对账号和应用；本地文件存在不等于账号有操作该应用的权限。 ### 开始开发 - 按用户实际需求开发页面与功能，遵循当前项目的目录结构与路由约定；需求尚不明确时，先了解要实现的功能。 - 根据项目 package.json 的 packageManager 和 scripts 安装缺失依赖、运行与构建，不假设所有模板使用相同命令。结构与调试参考 [技术架构](https://open.qiandao.com/docs/guide.md)。 - 完成后说明构建结果与产物；构建通过后再进入上传步骤。 ### 预览体验 - 确认正式平台的目标应用、CLI 登录状态和用户授权范围后，在项目目录执行版本上传： ```bash qdmp-cli upload ``` - 核对上传返回的版本与目标应用。随后引导用户前往 [我的应用](https://open.qiandao.com/dashboard)，将刚上传的版本设为体验版，使用千岛 App 扫码查看。 - 需要用户扫码验证时，明确告知待验证的页面与功能；未获得真机验证结果，不宣称体验已通过。体验版之后的提审和正式发布另按用户任务处理。 ### 环境选择 - 以上 CLI 命令不传 `-e`，默认使用正式平台，与账号、应用和体验版入口保持一致。正式环境上传也不会自动设置体验版、提审或发布。 - `-e dev` 选择的是测试服务，不是“开发版本”。只有用户明确要求测试平台时才使用，并改用 https://dev-open.qiandao.com 的账号与应用；先核对当前 CLI 各命令的环境参数行为，不要假设所有命令都一致。 - 文档、Markdown 和 llms.txt 可以使用当前预览站点地址；这不会改变上述 CLI 操作的目标环境。 ## 操作边界 - 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)