QMuse CLI

将本地 React 项目导入 QMuse。

安装

需要 Node.js 20 或更高版本。

npm install -g @qmuse/qmuse-cli

快速开始

qmuse login
qmuse space list
qmuse space use <spaceId>
qmuse import /path/to/react-project

登录时，在自动打开的浏览器页面中核对确认码并确认登录。导入成功后会自动打开应用页面。

账号与空间

qmuse whoami
qmuse login --status
qmuse logout
qmuse space list
qmuse space use <spaceId>
qmuse space info

使用 qmuse whoami 查看当前账号和空间，使用 qmuse space use <spaceId> 切换后续导入使用的空间。

导入

qmuse import /path/to/react-project --space-id <spaceId>

已选择空间时，可省略 --space-id。不希望自动打开浏览器时，添加 --no-open。

首次导入时，可通过 --title "应用名称" 指定标题；不指定时，QMuse 会根据代码生成标题。应用描述由 QMuse 根据代码生成。

导入遵循项目根目录的 .gitignore，自动排除依赖目录、构建产物和 .env* 等文件。检测到私钥或凭证时会停止导入，请按提示处理后重试。

导入失败时，按终端提示处理；如果生成了 .qmuse/last-import-error.json，可查看该文件定位问题。修复后重新执行导入命令。

更新已有应用

没有关联应用时，首次导入会创建新应用并自动保存本地绑定。之后在同一项目目录执行 qmuse import .，即可更新对应应用。请保留 .qmuse/project.json，从 QMuse 下载且带有绑定的项目也使用相同命令更新。

平台已有新版本时，终端会询问是否用本地全部源码覆盖，不会自动合并平台修改。确认覆盖可执行 qmuse import . --force；脚本或 --json 模式须显式指定该参数。覆盖会在原应用创建新版本，仍需通过正常导入校验。

外部云服务

qmuse import ./app --cloud-mode EXTERNAL \
  --public-config '{"VITE_API_URL":"https://example.test"}'

--public-config 用于传入公开配置，请勿填写私钥、Service Role Key 等秘密。

QMuse 云服务

qmuse cloud init -d "<应用功能描述>"
qmuse import ./app --cloud-mode QMUSE \
  --confirm-cloud-service

先用 cloud init 检查当前空间的云服务权益，导入时使用 --confirm-cloud-service 确认云资源计划。外部项目切换到 QMuse 云服务时，还需添加 --acknowledge-empty-cloud-data，确认外部已有数据不会自动迁移。

恢复任务

qmuse import status <jobId> --wait
qmuse import configure <jobId> --cloud-mode EXTERNAL \
  --public-config @public-config.json

本地等待中断不会取消任务。回到原项目目录，使用 status <jobId> --wait 继续等待；任务提示需要补充云服务配置时，使用 configure。

本地云联调

需要 Node.js 20.19+（或满足项目 Vite 的版本要求）、已安装依赖的 QMuse 模板、一次成功导入和 READY 云后端。首次需要云服务时，先生成最小业务代码与真实 Schema 并导入，再启动：

qmuse dev . --port 5173

命令使用项目自己的 Vite 和配置，监听 127.0.0.1。端口占用时自动选择可用端口，以终端打印的 URL 为准。--env prod|pre|local 选择 QMuse 平台环境；云资源固定为对应应用的开发环境。终端打印应用、用户和后端版本；单环境应用可能与正式页面共用数据。

CLI 获取服务端解析的公开云配置，复用 Vite 的 MUSE_RUNTIME_CONFIG_PATH 注入机制。配置放在系统临时目录，退出时删除。Token 按需获取且不落盘，CLI 登录凭据不交给页面。数据库、文件和函数请求由浏览器通过用户 Session 直接访问云端，不使用管理 API Key 或 Dev Key。

CLI 将本地 Runtime 的 __MUSE__.domain 设置为实际监听地址（如 http://127.0.0.1:5173），保留真实的 appwrite.endpoint。SDK 使用默认 fetch，将配置、Token 和操作上报发往本地三个固定接口，由 CLI 处理或转发；数据库、文件、函数仍直连云端。接口仅接受同源 JSON POST，并校验 Host、Fetch Metadata 和应用绑定。

不解析或改写业务源码，不注入自定义 fetch，不要求固定服务文件路径，也无需修改或发布 qmuse-cloud、Runtime SDK。已下载的模板使用原版云服务资产即可。普通开发和生产构建使用原有配置。其他自行基于 __MUSE__.domain 拼接的平台 API 不会被通用转发，需要单独确认接入方式。

服务端必须先部署 /api/appwrite/local-dev/context 和 /api/appwrite/local-dev/mutation-events，再发布并安装新版 CLI；缺少接口时不会降级为模拟云服务。

页面改动热更新，Schema/函数改动继续执行 qmuse import .。CLI 启动期间设置 QMUSE_HMR_GATE_ENABLED=false，退出后恢复原值；项目的 @qmuse/vite-config 必须支持此开关，否则平台批量改码门禁仍会暂存本地修改。导入更新本地绑定后，连接会重新获取配置并刷新页面。切换登录账号或应用绑定需重启连接；退出 CLI 不会自动撤销浏览器已经建立的 AppBase Session。SDK 的匿名降级行为保持不变，验收必须检查实际 Session 用户，不能只看页面是否显示。

联调验收包括 CRUD、刷新读回、文件上传/预览、函数调用和权限拒绝；浏览器 Cookie 限制需在目标浏览器验证。.muse-tmp、.qmuse 和系统临时配置不进入导入包。

研发验证：npm test、npm run build。浏览器集成测试使用已安装依赖的模板与相邻 qmuse-cloud 源仓库，运行 QMUSE_DEV_TEMPLATE_ROOT=/path/to/installed-template npm run test:browser，需本机 Chrome；测试中的云接口是隔离模拟后端，不代表真实云验收。

更多命令

运行 qmuse help 查看完整命令和参数，运行 qmuse --version 查看版本。