@playcraft/cli 0.0.49 → 0.0.52

package/REMIX.md

@@ -0,0 +1,760 @@
+# PlayCraft CLI Remix 完整命令参考
+
+本文档覆盖 `playcraft remix` 模块当前实际提供的全部命令、参数、交互行为、自动化输出、图片传输和常见工作流。
+
+CLI (Command-Line Interface, 命令行界面) 的 Remix 工作流用于：
+
+- 查询当前用户的团队和可见项目模板。
+- 从模板项目创建真实 Remix 分支。
+- 启动或复用 Remix 沙箱。
+- 打开 Remix Editor。
+- 向当前沙箱的 Agent 会话发送文本需求和参考图片。
+- 在交互式终端或自动化脚本中完成端到端创建流程。
+- 在本地项目中应用 Phaser 或 Three.js 引擎脚手架。
+
+## 1. 命令总览
+
+```text
+playcraft remix init-template
+playcraft remix teams
+playcraft remix templates
+playcraft remix create
+playcraft remix start
+playcraft remix prompt
+playcraft remix run
+```
+
+| 想完成的操作                 | 推荐命令                                                              |
+| ---------------------------- | --------------------------------------------------------------------- |
+| 查看当前账号所属团队         | `playcraft remix teams`                                               |
+| 查看团队内可作为模板的项目   | `playcraft remix templates --team-id <team-id>`                       |
+| 只创建 Remix，不启动沙箱     | `playcraft remix create` 或交互式 `playcraft remix run` 后留空 Prompt |
+| 启动已有 Remix 并打开 Editor | `playcraft remix start --project-id <id> --branch <branch> --open`    |
+| 向已有 Remix 发送需求        | `playcraft remix prompt`                                              |
+| 创建 Remix 并立即运行 Agent  | `playcraft remix run`                                                 |
+| 查询已有 Remix 列表          | `playcraft tools list-remixes`；当前没有 `playcraft remix list`       |
+| 给本地项目应用引擎模板       | `playcraft remix init-template`                                       |
+
+查看当前版本的帮助：
+
+```powershell
+playcraft remix --help
+playcraft remix help start
+playcraft remix prompt --help
+```
+
+## 2. 使用前准备
+
+### 2.1 登录
+
+普通用户推荐先登录：
+
+```powershell
+playcraft login --url https://test-playcraft.aix.intlgame.com
+```
+
+登录后，PAT (Personal Access Token, 个人访问令牌) 保存在：
+
+```text
+~/.playcraft/config.json
+```
+
+同一环境中的现有 Token 有效时，CLI 会直接使用它。Token 已过期、失效或切换到其他环境时，浏览器重新授权会创建新 Token，并替换本地旧 Token。
+
+### 2.2 服务地址优先级
+
+Remix 云端命令按以下顺序选择服务地址：
+
+1. 当前命令的 `--url <url>`。
+2. `PLAYCRAFT_API_URL` 环境变量。
+3. `PLAYCRAFT_URL` 环境变量。
+4. `~/.playcraft/config.json` 中的 `backendUrl`。
+5. `~/.playcraft/config.json` 中的 `url`。
+6. 默认 PlayCraft 云端地址。
+
+PowerShell 示例：
+
+```powershell
+$env:PLAYCRAFT_URL = "https://test-playcraft.aix.intlgame.com"
+playcraft remix teams
+```
+
+### 2.3 Token 优先级
+
+Remix 云端命令按以下顺序选择 Token：
+
+1. 当前命令的 `--token <token>`。
+2. `PLAYCRAFT_TOKEN` 环境变量。
+3. `~/.playcraft/config.json` 中登录保存的 Token。
+
+自动化环境推荐使用环境变量，避免 Token 出现在进程列表或 Shell 历史中：
+
+```powershell
+$env:PLAYCRAFT_TOKEN = "playcraft_pat_replace_with_secret"
+playcraft remix teams --json
+```
+
+### 2.4 项目 ID 与分支
+
+- `--project-id` 是 PlayCraft 对外项目 ID (Identifier, 标识符)。
+- `--branch` 必须使用真实 Remix 分支名，例如 `remix/Arrows-cli-test-0723`。
+- URL (Uniform Resource Locator, 统一资源定位符) 中的分支可能显示为 `remix%2FArrows-cli-test-0723`，传给命令时应恢复为 `remix/Arrows-cli-test-0723`。
+- 不要把 Remix 展示名称直接当成分支名；以 `create` 或 `run` 返回的 `branch` 为准。
+
+## 3. 通用参数与输出
+
+以下参数适用于 `teams`、`templates`、`create`、`start`、`prompt` 和 `run`：
+
+| 参数              | 说明                                                                                               |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| `--url <url>`     | 指定 PlayCraft 服务地址                                                                            |
+| `--token <token>` | 显式指定 PAT                                                                                       |
+| `--json`          | 标准输出只返回一个 JSON (JavaScript Object Notation, JavaScript 对象表示法) 结果；进度写入标准错误 |
+
+成功 JSON 采用统一外层结构：
+
+```json
+{
+  "schemaVersion": "1.0",
+  "ok": true,
+  "command": "remix.start",
+  "requestId": "request-id",
+  "data": {}
+}
+```
+
+失败 JSON 采用统一错误结构：
+
+```json
+{
+  "schemaVersion": "1.0",
+  "ok": false,
+  "command": "remix.prompt",
+  "requestId": "request-id",
+  "error": {
+    "code": "AGENT_REQUEST_FAILED",
+    "message": "错误说明",
+    "retryable": false
+  }
+}
+```
+
+退出码：
+
+| 退出码 | 含义                             |
+| ------ | -------------------------------- |
+| `0`    | 成功                             |
+| `2`    | 参数、附件或沙箱容量错误         |
+| `3`    | 未登录或登录过期                 |
+| `4`    | 团队、模板、资源或权限错误       |
+| `5`    | Agent 超时、不可用或远端请求失败 |
+
+## 4. `remix teams`
+
+列出当前登录账号可访问的团队。
+
+### 用法
+
+```powershell
+playcraft remix teams [--url <url>] [--token <token>] [--json]
+```
+
+### 示例
+
+```powershell
+playcraft remix teams
+```
+
+人类可读输出：
+
+```text
+team-id    UA (Tencent IEGG)
+```
+
+自动化输出：
+
+```powershell
+playcraft remix teams --json
+```
+
+`data.items` 包含团队记录，`data.total` 表示返回数量。
+
+## 5. `remix templates`
+
+列出指定团队中当前用户可见的项目模板。
+
+### 用法
+
+```powershell
+playcraft remix templates `
+  --team-id <team-id> `
+  [--tag <filter>] `
+  [--url <url>] `
+  [--token <token>] `
+  [--json]
+```
+
+### 参数
+
+| 参数             | 必填 | 说明                                   |
+| ---------------- | ---- | -------------------------------------- |
+| `--team-id <id>` | 是   | 团队 ID                                |
+| `--tag <filter>` | 否   | 在模板标签中执行不区分大小写的包含匹配 |
+
+### 示例
+
+```powershell
+playcraft remix templates `
+  --team-id team-id
+```
+
+按标签筛选：
+
+```powershell
+playcraft remix templates `
+  --team-id team-id `
+  --tag arrows `
+  --json
+```
+
+输出中的模板 `id` 可用于 `remix create --project-id` 或 `remix run --template-id`。
+
+## 6. `remix create`
+
+从指定项目和源分支创建真实 Remix 分支。该命令只创建分支，不启动沙箱、不启动 Agent，也不自动打开 Editor。
+
+### 用法
+
+```powershell
+playcraft remix create `
+  --project-id <project-id> `
+  --name <remix-name> `
+  [--team-id <team-id>] `
+  [--source-branch <branch>] `
+  [--url <url>] `
+  [--token <token>] `
+  [--json]
+```
+
+### 参数
+
+| 参数                       | 必填 | 默认值 | 说明                                   |
+| -------------------------- | ---- | ------ | -------------------------------------- |
+| `--project-id <id>`        | 是   | 无     | 源模板项目 ID                          |
+| `--name <name>`            | 是   | 无     | Remix 展示名称；服务端会返回最终分支名 |
+| `--team-id <id>`           | 否   | 无     | 团队权限上下文                         |
+| `--source-branch <branch>` | 否   | `main` | 创建 Remix 时使用的源分支              |
+
+### 示例
+
+```powershell
+playcraft remix create `
+  --project-id 10000086 `
+  --name "Arrows-cli-test-0723" `
+  --source-branch main `
+  --json
+```
+
+保存结果中的以下字段：
+
+- `data.projectId`
+- `data.branch`
+- `data.editorUrl`
+
+后续进入 Editor：
+
+```powershell
+playcraft remix start `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --open
+```
+
+## 7. `remix start`
+
+启动或复用指定 Remix 的沙箱。沙箱就绪后返回 Editor URL；有预览服务时同时返回 Preview URL。该命令不会向 Agent 发送需求。
+
+### 用法
+
+```powershell
+playcraft remix start `
+  --project-id <project-id> `
+  --branch <remix-branch> `
+  [--source-branch <branch>] `
+  [--evict-slot-id <slot-id>] `
+  [--evict-confirmed] `
+  [--open] `
+  [--url <url>] `
+  [--token <token>] `
+  [--json]
+```
+
+### 参数
+
+| 参数                       | 必填 | 说明                                                                    |
+| -------------------------- | ---- | ----------------------------------------------------------------------- |
+| `--project-id <id>`        | 是   | Remix 所属项目 ID                                                       |
+| `--branch <name>`          | 是   | Remix 分支，禁止省略后隐式使用 `main`                                   |
+| `--source-branch <branch>` | 否   | 目标分支不存在时使用的源分支                                            |
+| `--evict-slot-id <id>`     | 否   | 沙箱容量满时指定要释放的槽位                                            |
+| `--evict-confirmed`        | 否   | 确认释放 `--evict-slot-id` 指定的槽位；自动化场景应与前一个参数一起使用 |
+| `--open`                   | 否   | 沙箱就绪后打开 Remix Editor                                             |
+
+### 示例：进入已经创建的 Remix
+
+```powershell
+playcraft remix start `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --open `
+  --url https://test-playcraft.aix.intlgame.com
+```
+
+只取得结构化地址，不打开浏览器：
+
+```powershell
+playcraft remix start `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --json
+```
+
+成功结果的重要字段：
+
+| 字段                   | 说明                                       |
+| ---------------------- | ------------------------------------------ |
+| `data.urls.editor`     | Remix Editor 地址                          |
+| `data.urls.preview`    | 沙箱预览地址；只有服务就绪并提供预览时存在 |
+| `data.sandbox.id`      | 沙箱 ID                                    |
+| `data.sandbox.slotId`  | 沙箱槽位 ID                                |
+| `data.agent.slug`      | 当前 Code Agent 类型                       |
+| `data.agent.sessionId` | 当前 Agent 会话 ID                         |
+
+### 沙箱容量满
+
+交互式终端会显示可释放槽位并要求确认。非交互或 `--json` 模式不会显示选择菜单，应根据错误详情重新运行：
+
+```powershell
+playcraft remix start `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --evict-slot-id <slot-id> `
+  --evict-confirmed `
+  --json
+```
+
+## 8. `remix prompt`
+
+向指定 Remix 沙箱的当前 Agent 会话发送文本需求和可选参考图片。命令会自动启动或复用沙箱，并使用当前会话；不需要先单独运行 `remix start`。
+
+### 用法
+
+```powershell
+playcraft remix prompt `
+  --project-id <project-id> `
+  --branch <remix-branch> `
+  (--prompt <text> | --prompt-file <path>) `
+  [--image <path-1> <path-2>] `
+  [--wait | --no-wait] `
+  [--timeout <seconds>] `
+  [--evict-slot-id <slot-id>] `
+  [--evict-confirmed] `
+  [--open] `
+  [--url <url>] `
+  [--token <token>] `
+  [--json]
+```
+
+### 参数
+
+| 参数                   | 必填   | 默认值   | 说明                                                                                                        |
+| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `--project-id <id>`    | 是     | 无       | Remix 所属项目 ID                                                                                           |
+| `--branch <name>`      | 是     | 无       | Remix 分支                                                                                                  |
+| `--prompt <text>`      | 二选一 | 无       | 直接传入需求；不能与 `--prompt-file` 同时使用                                                               |
+| `--prompt-file <path>` | 二选一 | 无       | 读取 UTF-8 (Unicode Transformation Format 8-bit, Unicode 八位转换格式) 文本文件；不能与 `--prompt` 同时使用 |
+| `--image <path...>`    | 否     | 无       | 一个或多个本地参考图片路径                                                                                  |
+| `--wait`               | 否     | 默认行为 | 等待当前 Agent 回合结束并读取最后一条助手消息                                                               |
+| `--no-wait`            | 否     | 关闭等待 | Agent 接收需求后立即返回，结果中的状态为 `running`                                                          |
+| `--timeout <seconds>`  | 否     | `1800`   | 最少 1 秒；只限制 CLI 等待时间，不代表自动中止远端任务                                                      |
+| `--evict-slot-id <id>` | 否     | 无       | 容量满时指定释放槽位                                                                                        |
+| `--evict-confirmed`    | 否     | `false`  | 确认释放指定槽位                                                                                            |
+| `--open`               | 否     | `false`  | 执行完成或需求被接收后打开 Editor                                                                           |
+
+Prompt 最大为 256 KiB (Kibibyte, 千二进制字节)。空内容会失败。
+
+### 文本示例
+
+```powershell
+playcraft remix prompt `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --prompt "继续完善箭头关卡，并检查移动端交互" `
+  --wait
+```
+
+### 从文件读取需求
+
+```powershell
+playcraft remix prompt `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --prompt-file .\request.md `
+  --json
+```
+
+### 携带参考图片
+
+图片规则：
+
+- 最多 4 张。
+- 每张不超过 5 MB (Megabyte, 兆字节)。
+- 支持 JPEG (Joint Photographic Experts Group, 联合图像专家组)、PNG (Portable Network Graphics, 便携式网络图形)、WebP 和 GIF (Graphics Interchange Format, 图形交换格式)。
+- CLI 先校验本地文件，再启动或复用沙箱。
+- 后端会把图片转换为 PNG 并写入 `tmp/opencode-images/`。
+- Agent 收到的是文本 Prompt 和沙箱图片路径，不是非文本图片消息 part。
+- 任意图片校验或上传失败都会终止发送，不会静默降级为纯文本。
+- CLI 不预判当前模型是否具备视觉输入能力。
+
+示例：
+
+```powershell
+playcraft remix prompt `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --prompt "参考这些图片调整关卡视觉和配色" `
+  --image .\ref-a.png .\ref-b.webp `
+  --wait
+```
+
+### 当前会话存在待回答问题
+
+如果当前 Agent 会话已有待回答问题，CLI 会先处理这些问题，不会重复发送原需求；本次指定的图片也不会上传。自动化调用应检查结构化输出中的附件状态。
+
+## 9. `remix run`
+
+`run` 是高层编排命令，支持以下两种模式：
+
+1. 选择团队和模板，创建新 Remix，可选立即发送 Agent 需求。
+2. 对已有 `projectId + branch` 发送 Agent 需求。
+
+### 用法
+
+```powershell
+playcraft remix run `
+  [--team-id <team-id>] `
+  [--template-id <template-id>] `
+  [--project-id <project-id>] `
+  [--branch <remix-branch>] `
+  [--name <remix-name>] `
+  [--source-branch <branch>] `
+  [--prompt <text> | --prompt-file <path>] `
+  [--image <path-1> <path-2>] `
+  [--wait | --no-wait] `
+  [--timeout <seconds>] `
+  [--open] `
+  [--url <url>] `
+  [--token <token>] `
+  [--json]
+```
+
+### 参数
+
+| 参数                       | 创建模式         | 已有 Remix 模式  | 说明                                            |
+| -------------------------- | ---------------- | ---------------- | ----------------------------------------------- |
+| `--team-id <id>`           | 非交互时必填     | 禁止             | 所选团队 ID                                     |
+| `--template-id <id>`       | 非交互时必填     | 禁止             | 源模板项目 ID                                   |
+| `--project-id <id>`        | 禁止             | 必填             | 已有 Remix 项目 ID                              |
+| `--branch <name>`          | 自动生成         | 必填             | 已有 Remix 分支                                 |
+| `--name <name>`            | 非交互时必填     | 禁止             | 新 Remix 展示名称                               |
+| `--source-branch <branch>` | 可选             | 不使用           | 模板没有配置默认分支时的回退源分支，默认 `main` |
+| `--prompt <text>`          | 可选             | 非交互时必填     | 内联需求                                        |
+| `--prompt-file <path>`     | 可选             | 非交互时必填     | 文件需求；与 `--prompt` 二选一                  |
+| `--image <path...>`        | 有 Prompt 时可选 | 有 Prompt 时可选 | 图片规则与 `remix prompt` 相同                  |
+| `--wait` / `--no-wait`     | 可选             | 可选             | 默认等待 Agent 完成                             |
+| `--timeout <seconds>`      | 可选             | 可选             | 默认 1800 秒                                    |
+| `--open`                   | 可选             | 可选             | Agent 流程启动后打开 Editor                     |
+
+`--project-id + --branch` 不能与 `--team-id`、`--template-id` 或 `--name` 混用。
+
+### 交互式完整流程
+
+```powershell
+playcraft remix run
+```
+
+交互顺序：
+
+1. 选择团队。
+2. 加载模板来源：有模板页权限时显示团队模板和当前团队的系统推荐；无权限时只显示当前团队的系统推荐。系统推荐与 Remix 画廊一致，由推荐 Prompt 模板和推荐 Remix 两部分组成。
+3. 选择模板；输入 `back` 可返回团队列表。
+4. 选择团队模板后加载它的分支，可选择 `main` 或已有 Remix；选择系统推荐时直接使用该推荐配置的基础模板和分支。输入 `back` 可返回模板列表。
+5. CLI 按平台规则自动生成 Remix 名称并创建真实 Remix 分支。
+6. 输入需求描述。
+7. 有需求时启动沙箱并运行 Agent；直接回车或输入 `exit` 时只创建 Remix。
+
+模板权限与网页 `/projects` 保持一致，仅系统管理员可以读取团队模板项目。CLI 只在服务端明确返回 `403 Forbidden` 时降级为仅系统推荐；网络错误或服务端异常会原样报错，不会误判成权限不足。
+
+创建后留空 Prompt 的输出：
+
+```text
+✓ Remix 创建完成：Arrows-cli-test-0723
+Remix 详情地址：https://test-playcraft.aix.intlgame.com/projects/10000086/remixes/remix%2FArrows-cli-test-0723
+已结束：Remix 已创建，未启动 Agent。
+```
+
+此时继续进入 Editor：
+
+```powershell
+playcraft remix start `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --open
+```
+
+### 非交互创建并运行 Agent
+
+```powershell
+playcraft remix run `
+  --team-id team-id `
+  --template-id 10000086 `
+  --name "Arrows-cli-generated" `
+  --prompt "创建三个递进难度的箭头关卡" `
+  --wait `
+  --json
+```
+
+### 非交互只创建 Remix
+
+```powershell
+playcraft remix run `
+  --team-id team-id `
+  --template-id 10000086 `
+  --name "Arrows-cli-created-only" `
+  --json
+```
+
+该模式不会启动沙箱。之后使用 `remix start` 或 `remix prompt`。
+
+### 对已有 Remix 继续运行 Agent
+
+```powershell
+playcraft remix run `
+  --project-id 10000086 `
+  --branch "remix/Arrows-cli-test-0723" `
+  --prompt "继续完成上次未完成的关卡调整" `
+  --wait
+```
+
+`remix run` 的已有 Remix 模式与 `remix prompt` 接近；需要更直接、可预测的调用时推荐使用 `remix prompt`。
+
+## 10. `remix init-template`
+
+该命令是本地脚手架能力，与云端 Remix 分支、沙箱和 Agent 会话无关。
+
+### 用法
+
+```powershell
+playcraft remix init-template `
+  [--engine phaser|threejs] `
+  [--from-atom-tree] `
+  [--project-dir <path>] `
+  [--force] `
+  [--bake] `
+  [--all-engines]
+```
+
+### 参数
+
+| 参数                   | 说明                                                                                                 |
+| ---------------------- | ---------------------------------------------------------------------------------------------------- |
+| `--engine <name>`      | 选择 `phaser` 或 `threejs`                                                                           |
+| `--from-atom-tree`     | 从项目 `docs/atom-tree.json` 的 `meta.engineDecision.adapter` 读取引擎，并自动链接选择的 Atom Skills |
+| `--project-dir <path>` | 项目根目录，默认当前工作目录                                                                         |
+| `--force`              | 当前 `.playcraft-engine` 与目标引擎不一致时仍替换 `game/`；使用前应确认现有内容可恢复                |
+| `--bake`               | 烘焙 CLI 包维护的完整项目模板                                                                        |
+| `--all-engines`        | 与 `--bake` 一起使用，烘焙全部已知引擎模板                                                           |
+
+必须提供 `--engine` 或 `--from-atom-tree`；唯一例外是同时使用 `--bake --all-engines`。
+
+应用 Phaser 模板：
+
+```powershell
+playcraft remix init-template `
+  --engine phaser `
+  --project-dir D:\projects\my-playable
+```
+
+从 Atom Tree 读取引擎：
+
+```powershell
+playcraft remix init-template `
+  --from-atom-tree `
+  --project-dir D:\projects\my-playable
+```
+
+烘焙全部引擎模板：
+
+```powershell
+playcraft remix init-template --bake --all-engines
+```
+
+## 11. 查询已有 Remix
+
+当前 `playcraft remix` 模块没有 `list` 子命令。使用现有工具命令：
+
+```powershell
+playcraft tools list-remixes `
+  --scope my `
+  --page 1 `
+  --limit 20
+```
+
+搜索：
+
+```powershell
+playcraft tools list-remixes `
+  --scope my `
+  --search "Arrows-cli"
+```
+
+参数：
+
+| 参数                 | 默认值 | 说明                                            |
+| -------------------- | ------ | ----------------------------------------------- |
+| `--scope <scope>`    | `my`   | `my` 查询自己可访问的 Remix；`gallery` 查询画廊 |
+| `--search <keyword>` | 无     | 按关键字搜索                                    |
+| `--limit <n>`        | `20`   | 每页最大数量                                    |
+| `--page <n>`         | `1`    | 页码                                            |
+
+该工具命令会把完整结果写入结果文件，并在终端打印数量和文件位置。
+
+## 12. 推荐工作流
+
+### 12.1 第一次使用
+
+```powershell
+playcraft login --url https://test-playcraft.aix.intlgame.com
+playcraft remix teams
+playcraft remix templates --team-id <team-id>
+playcraft remix run
+```
+
+### 12.2 创建、稍后打开 Editor
+
+```powershell
+playcraft remix run
+
+playcraft remix start `
+  --project-id <project-id> `
+  --branch <remix-branch> `
+  --open
+```
+
+### 12.3 创建后立即让 Agent 工作
+
+```powershell
+playcraft remix run `
+  --team-id <team-id> `
+  --template-id <template-id> `
+  --name <remix-name> `
+  --prompt-file .\request.md `
+  --wait `
+  --open
+```
+
+### 12.4 已有 Remix 继续迭代
+
+```powershell
+playcraft remix prompt `
+  --project-id <project-id> `
+  --branch <remix-branch> `
+  --prompt "继续优化视觉、交互和加载性能" `
+  --image .\visual-reference.png `
+  --wait
+```
+
+### 12.5 CI 自动化
+
+CI (Continuous Integration, 持续集成) 中应显式提供所有必需参数，并使用环境变量传 Token：
+
+```powershell
+$env:PLAYCRAFT_URL = "https://test-playcraft.aix.intlgame.com"
+$env:PLAYCRAFT_TOKEN = "playcraft_pat_replace_with_secret"
+
+playcraft remix run `
+  --team-id <team-id> `
+  --template-id <template-id> `
+  --name <remix-name> `
+  --prompt-file .\request.md `
+  --no-wait `
+  --json
+```
+
+## 13. URL 类型说明
+
+Remix 流程可能返回三种不同地址：
+
+| 地址           | 用途                                                                          |
+| -------------- | ----------------------------------------------------------------------------- |
+| Remix 详情地址 | 项目页面中的 Remix 详情，例如 `/projects/{projectId}/remixes/{encodedBranch}` |
+| Editor 地址    | Remix 编辑器，例如 `/editor/remix/{projectId}?branch={encodedBranch}`         |
+| Preview 地址   | 沙箱中的运行预览；只有沙箱就绪时存在                                          |
+
+`remix run` 创建后留空 Prompt 时显示的是 Remix 详情地址，因为沙箱尚未启动。要进入 Editor，运行 `remix start --open`。
+
+## 14. 常见问题
+
+### 14.1 `run` 显示“未启动 Agent”是不是创建失败？
+
+不是。交互式 `run` 在 Prompt 留空或输入 `exit` 时只创建 Remix。之后可以运行：
+
+```powershell
+playcraft remix start --project-id <project-id> --branch <remix-branch> --open
+```
+
+### 14.2 能否不先运行 `start`，直接发送 Prompt？
+
+可以。`remix prompt` 会自动启动或复用沙箱。
+
+### 14.3 为什么 `prompt` 必须同时提供项目 ID 和分支？
+
+项目中可能存在多个 Remix 分支。显式指定二者可以避免需求落到 `main` 或其他 Remix。
+
+### 14.4 `--open` 与 URL 输出有什么区别？
+
+`--open` 会调用系统浏览器。没有 `--open` 时命令仍会返回或打印 Editor URL，适合远程终端和自动化环境。
+
+### 14.5 图片上传失败后是否仍会发送纯文本？
+
+不会。附件校验或上传失败时，整个 Prompt 请求失败，避免 Agent 在缺少参考图的情况下继续执行。
+
+### 14.6 `--no-wait` 是否会取消 Agent？
+
+不会。它只让 CLI 在 Agent 接收请求后立即返回，远端任务继续运行。
+
+### 14.7 超时后 Agent 是否会停止？
+
+不保证。`--timeout` 限制 CLI 等待时间；当前命令不会因为本地等待超时而自动中止远端 Agent。
+
+### 14.8 如何避免测试环境和生产环境 Token 混用？
+
+登录时显式传入环境地址：
+
+```powershell
+playcraft login --url https://test-playcraft.aix.intlgame.com
+```
+
+CLI 只会在保存 Token 的环境与目标环境一致时复用它；浏览器重新授权会创建新 Token 并替换旧值。
+
+## 15. 版本与帮助
+
+本文档描述当前源码中的命令。安装版本可能落后于仓库源码，排查参数差异时先检查：
+
+```powershell
+playcraft --version
+playcraft remix --help
+playcraft remix <command> --help
+```
+
+如果全局安装版本未包含最新命令，需要发布或重新安装 `@playcraft/cli` 后再使用。