适合已经有本地 React + Vite 项目，或从 QMuse 下载了模板代码的用户。完成后，你可以把本地代码导入 QMuse、在后续修改后更新同一个应用、本地连接真实云服务开发，并把版本发布上线。也可以直接用需求创建网页、H5、AI 或游戏应用。 开始前 安装 Node.js 20 或更高版本，可运行 node --version 检查；使用 qmuse dev 连接真实云资源开发时，需要 Node.js 20.19 或更高版本。 准备可以登录 QMuse 的账号，并确认代码要放入哪个空间。 推荐使用 QMuse 下载的模板代码。普通 React + Vite 项目也可以导入，但可能需要根据检查结果调整入口或依赖。 先保存或提交本地改动，方便在出现问题时对照和恢复。 完整流程 步骤 做什么 完成标志 1 安装 QMuse CLI qmuse --version 能显示版本 2 登录 QMuse 浏览器确认后，终端显示登录成功 3 选择空间 qmuse space info 显示目标空间 4 导入项目，或用需求创建应用 / 游戏 终端返回应用地址并自动打开 QMuse 5 修改后再次导入 原应用中出现新版本 6 用对话继续修改（可选） 应用页面出现本轮改动 7 拉取平台上更新的代码（可选） 本地源码与平台最新版本一致 8 本地连接云资源开发（可选） 浏览器能打开本地地址并读到真实数据 9 发布版本 终端返回发布地址，状态为已发布 1. 安装 QMuse CLI 在终端执行： npm install -g @qmuse/qmuse-cli@latest qmuse --version 如果你使用 cnpm，也可以执行： cnpm install -g @qmuse/qmuse-cli@latest 你会看到： 终端显示 QMuse CLI 的版本号。 以后升级用一条命令： qmuse upgrade CLI 会自动提示是否有新版本。如果终端出现「当前版本已停止支持」，说明平台已不兼容旧版，执行 qmuse upgrade 即可恢复；升级命令本身不会被拦。 为 AI 编程工具安装官方 Skill 官方 Skill 随 CLI 包一起分发，安装时无需另外下载技能文件。支持以下七种工具： 工具 --agent 标识 默认 skills 父目录 Codex codex /.codex/skills Claude Code claude /.claude/skills Cursor cursor /.cursor/skills Trae trae /.trae/skills CodeBuddy codebuddy /.codebuddy/skills Qoder qoder /.qoder/skills Qwen Code qwen /.qwen/skills 先查看支持的工具、本机目录和安装状态，再为当前使用的工具安装： qmuse agent-skill list qmuse agent-skill install --agent codex qmuse agent-skill status --agent codex --json 把示例中的 codex 换成上表对应标识。CLI 会在 skills 父目录下创建 qmuse-cli/ ，例如 Codex 的技能文件位于 /.codex/skills/qmuse-cli/SKILL.md 。 也可以直接执行 qmuse agent-skill install ：只发现一个工具目录时自动选中，多个目录时在终端选择；脚本或 JSON 模式发现多个目录时，需要用 --agent 或 --target 显式指定。存在工具目录只表示发现了该目录，不代表已安装或启用技能。 其他工具或自定义目录使用： qmuse agent-skill install --target "$HOME/my-tool/skills" qmuse agent-skill status --target "$HOME/my-tool/skills" --json 把示例路径换成该工具实际读取的 skills 目录。 --target 是父目录，CLI 会自动追加 /qmuse-cli ，不要在参数末尾重复添加技能名。 安装后确认 installed.address 指向当前工具， installed.upToDate 为 true。状态会同时核对版本与文件，分别列出 missingFiles （缺失）、 outdatedFiles （过期）和 modifiedFiles （用户修改）；缺失或过期时可对同一目标重新安装。用户修改会被保护，确实需要覆盖时再使用 --force 。省略目标运行 qmuse agent-skill status 可查看全部目标。 qmuse upgrade 会同步已有的默认安装和已登记的自定义目录，保留用户修改，不向未安装技能的工具目录新增技能。更新后重新读取 SKILL.md ，必要时刷新工具的技能列表或开启新会话，加载方式以工具自身为准。 2. 登录 QMuse qmuse login CLI 会打开 QMuse 登录确认页。完成登录并确认后，返回终端继续执行。 你会看到： 终端提示登录成功。可以用下面的命令再次确认： qmuse whoami 3. 选择目标空间 先查看你可以使用的空间： qmuse space list 找到目标空间 ID 后，将它设为当前空间： qmuse space use <空间ID> qmuse space info 例如 <空间ID> 可能是 S640459450135 。空间决定新应用创建在哪里；导入前应确认终端显示的空间名称正确。 没有本地工程？直接创建游戏或其他应用 完成登录和空间选择后，也可以直接让 QMuse 根据需求创作。支持 web 网页、 h5 移动页面、 ai AI 应用和 game 游戏应用。 把玩法、操作方式和计分规则写入 游戏需求.md ，然后执行： qmuse app create game --file ./游戏需求.md --json 你会看到： CLI 创建游戏应用并开始首轮生成，返回 appId 、 chatId 、 sprintId 等信息。创建后可按第 6 节继续对话修改玩法或界面，按第 9 节发布指定版本；不在绑定目录发布时，显式添加 --app-id <appId> 。 使用这条入口时，无需先准备本地工程或执行导入；已有本地源码的用户按下面的导入流程继续。 4. 检查并导入项目 进入项目目录，安装依赖并确认项目可以构建： cd /path/to/your-project cnpm install npm run build 构建通过后执行： qmuse import . 导入过程中，QMuse 会检查项目结构、静态资源、内容安全和云服务配置，并生成可以继续编辑的应用版本。 你会看到： 终端返回 QMuse 应用地址，浏览器打开应用，页面中出现“代码已完成导入并生成首个版本”。 5. 更新同一个应用 QMuse 使用项目目录中的 .qmuse/project.json 保存项目信息和应用绑定。模板可能已经带有这个文件；普通 React + Vite 项目首次成功导入后，也会自动保存应用绑定。请保留这个文件，在原目录中继续开发，不要把绑定复制到另一个项目。 修改代码后，在同一目录再次执行： qmuse import . 你会看到： appId 保持不变，原应用中新增一个版本。代码没有变化时，CLI 会直接提示无改动，不会重复生成版本。 普通项目只在首次导入时创建新应用。只要保留成功导入后的绑定，后续 qmuse import . 就会更新同一个应用，无需重新下载模板。 6. 在命令行里继续对话修改 除了改代码再导入，也可以直接把需求发给 QMuse 的 AI。先确认 appId 和 chatId；已有应用与迭代 ID 时，可先查询历史取得 chatId： qmuse chat history --app-id <appId> --sprint-id <sprintId> 发送本轮需求： qmuse chat send --app-id <appId> --chat-id <chatId> --file - <<'EOF' 把首页标题改成「我的待办清单」 EOF --file - 表示从标准输入读内容，命令会等这一轮生成结束再返回。 你会看到： 成功时终端提示“本轮对话完成”，刷新应用页面即可看到改动。需要结构化结果时，在 chat send 命令中追加 --json ，成功结果中的 status 为 SUCCEEDED 。 生成到一半断开时，先查状态再恢复： qmuse chat state <chatId> 它会列出正在等待你回答的问题、可选答案、答案结构，以及可以复制的恢复命令。按返回的答案结构准备 JSON 文件，再恢复原会话： qmuse chat resume <chatId> --app-id <appId> --interrupt-id <interruptId> --file 回答.json chatId 沿用原会话；interruptId 使用状态查询返回的值。没有待恢复中断时，先查看状态和历史，不要重新创建应用。 7. 拉取平台上更新的代码 如果有人在 QMuse 网页或对话里改过代码，先把这些改动同步到本地再继续开发： qmuse pull 拉取的是平台最新已保存的版本。命令会先比对你本地源码与上次同步的基线： 只要本地有改动（新增、修改、删除都算），就直接停下 ，不会覆盖你的代码。Git 提交不改变这个判断。 你会看到： 有平台新版本时提示已拉取平台版本；本地与平台最新已保存版本已经一致时，提示本地已是平台最新版本。 实际更新本地源码前，会把原源码和绑定自动备份到终端返回的 .qmuse/pull-backups/ 目录中，需要回退时可以从那里找回。 不想动本地目录、只想看平台代码，改用导出： qmuse code export --app-id <appId> --output ./exported 8. 本地连接云资源开发 应用用到了数据库、文件或云函数时，可以让本地服务连真实云资源，边改边看： qmuse dev 终端会打印本地地址（默认 http://127.0.0.1:5173 ），浏览器打开即可。页面改动热更新；数据库结构和云函数的改动仍需执行 qmuse import . 才会生效。 CLI 只把公开的云配置交给浏览器，登录凭证不会下发到页面。 你会看到： 终端打印应用名、当前用户和后端版本，随后可以打开本地地址。 关闭时在终端按 Ctrl+C 。不确定是否还有会话在跑： qmuse dev status # 查看当前会话 qmuse dev stop # 停止会话 9. 发布版本 导入只生成版本，正式对外的页面需要发布： qmuse version list --app-id <appId> # 找到要发布的最新版本号 qmuse deploy --version <版本号> deploy 从当前目录的 .qmuse/project.json 识别应用，因此在项目目录内执行；不在项目目录时加 --app-id <appId> 。 发布前会做内容安全和静态扫描，命令会一直等到有结果。 你会看到： 输出中 status 为 DEPLOYED ，同时列出安全检查结果和发布地址。 不想一直等，加 --no-wait 受理后立即返回，之后查询结果： qmuse release status <发布ID> 发布一直是进行中怎么办 说明还在跑安全检查。查具体原因： qmuse release status <发布ID> 输出里的 infosecStatus 、 mosecStatus 分别对应内容安全与静态扫描；失败时 error 字段会给出原因，按提示修改后重新发布即可，历史版本随时可以重发。 使用 QMuse 云服务 如果应用需要登录、数据库、数据持久化或云函数，先让当前大模型工具按照模板内的 QMuse 云服务技能完成代码和配置，再执行导入。 qmuse cloud init -d "<应用功能描述>" qmuse import . --cloud-mode QMUSE --confirm-cloud-service 应用尚未创建时，先在本地完成代码和配置声明，再通过导入创建应用、生成版本及相应云资源。已有成功导入和就绪云资源的应用，可以使用上文的 qmuse dev 连接真实云服务开发。 使用现有外部云服务时，只提交浏览器本来就可以读取的公开配置： qmuse import . --cloud-mode EXTERNAL --public-config @public-config.json 不要在公开配置中放入密码、私钥、服务端密钥或其他敏感信息。 导入失败时怎么处理 如果问题来自源代码，CLI 会在项目中生成 .qmuse/last-import-error.json 。可以直接告诉 Codex 或其他大模型工具： 请读取 .qmuse/last-import-error.json ，根据其中的原因修复当前项目，然后重新执行 qmuse import . 。 如果只是终端中断，服务端任务仍会继续。使用 CLI 返回的任务 ID 恢复查询： qmuse import status <任务ID> --wait 遇到网络或平台错误时，不要反复修改源码；稍后重试，或保留完整错误信息和任务 ID 后提交反馈。 相关内容 空间：创建、切换与成员管理 云服务使用说明 发布与分享作品 问题排查指南