@playcraft/cli 0.1.36-beta1 → 0.1.38-beta

package/README.md

@@ -7,14 +7,34 @@
 
 PlayCraft CLI（Command-Line Interface，命令行工具）支持本地代码与云端编辑器实时同步，以及将 PlayCanvas/PlayCraft 项目打包为多平台 Playable Ads。
 
-## 云端工作台 Runtime（计划能力）
+## 云端工作台 Runtime
 
-云端工作台计划以 `@playcraft/cli` 承载自定义 AGS（Agent Sandbox，Agent 沙箱服务）内的常驻运行服务，新增 `playcraft workspace-runtime serve` 命令，管理多个 Workspace、一个 Codex App Server、文件/Git/终端/预览及持久恢复。该命令尚未实现，当前发布版本不可调用；现有 `playcraft start` 仍用于单项目本地开发。
+`playcraft workspace-runtime serve --config <json>` 已注册。它前台常驻、跳过升级检查，读取 Runtime Server 下发的引导配置，只绑定回环并校验 control token。`runtime.ensure` 会执行到终态；设置 `PLAYCRAFT_NATIVE_ADAPTER=loopback` 或测试注入 loopback 适配器后，可跑会话 create/turn/interrupt/审批，以及本地 journal 检查点/恢复/销毁。工作空间相对路径的 `file.write` 与文件检查点不依赖 loopback。相同幂等键上的 `uncertain` 操作不会新开 turn。这不是 Codex App Server。现有 `playcraft start` 仍用于单项目本地开发，二者不要混用。
 
-新服务采用固定版本、前台非交互运行，由镜像监管器启动；独立 Runtime Server 在沙箱外部署。具体代码归属、进程权限、发布与恢复契约见 [云端工作台后端架构方案](../../docs/architecture/backend/cloud-workspace/backend-architecture.md#cli-runtime)。
+实现与模块边界见 [Sandbox Agent Server](./src/workspace-runtime/README.md)；契约见 [云端工作台后端架构方案](../../docs/architecture/backend/cloud-workspace/backend-architecture.md#cli-runtime)。
+
+## 下载云工作区并推送本地修改
+
+文件面板的下载弹窗可复制下列命令。需要发布包含 `workspace` 命令的新版 `@playcraft/cli`，并部署对应的工作区传输端点；旧版 Remix 命令保持兼容。
+
+```bash
+npx @playcraft/cli@latest login --url 'https://playcraft.example.com/__env/test-a'
+npx @playcraft/cli@latest workspace clone --workspace-id '<workspace-id>' --directory root --url 'https://playcraft.example.com/__env/test-a' --dir './my-workspace'
+cd './my-workspace'
+# 完成本地编辑后提交，再同步回原工作区
+git add -A
+git commit -m 'Update workspace'
+npx @playcraft/cli@latest workspace push
+```
+
+`--directory root` 下载整个工作区的工程目录；也可指定 `basic` 或已有工程目录。独立工作区无需关联平台项目。下载包含当前未提交文件、二进制素材和 `dist/` 产物，使用只有当前快照的新 Git 历史；排除 `.git`、`node_modules`、凭据文件和运行时路由信息。本地 `.playcraft-workspace.json` 保存目标工作区、目录、完整环境基址和快照摘要，不含访问令牌，默认不进入提交。服务基址的环境路径前缀会完整保留。
+
+`workspace push` 要求本地修改已经提交，将提交的文件同步回同一个云工作区；云端文件变化或有正在运行的任务时拒绝覆盖，需重新克隆并合并后再推送。云端现有 Git 仓库和分支元数据会保留，保存到远端项目仍使用工作区原有保存流程；针对项目分支的操作可继续使用 `remix clone` / `remix push`。传输限制为 20,000 个文件、256 MiB（Mebibyte，二进制兆字节）内容及压缩包，超限可使用弹窗中的直接下载。命令支持 `--token`、`--dir` 与 `--json`。
 
 ## ✨ 特性
 
+远程技能的上传、更新、发布、审核、查询与下载见 [技能注册表命令](./SKILLS_REGISTRY.md)。入口为 `playcraft skills registry`，复用已有登录；本地技能发现与项目技能命令保持原有语义。
+
 - 🚀 **本地开发隧道** - 在本地 IDE 编写代码，云端编辑器实时预览与热更新
 - 📦 **Playable Ads 打包** - 支持 10 个主流广告平台的一键打包
 - 🎬 **智能场景选择** - 交互式场景选择，可减小 30-60% 文件大小（**新功能**）
@@ -141,6 +161,17 @@ playcraft login --url https://your-playcraft.example.com
 
 登录成功后，`tools`、`recommend`、`fix-ids` 等所有需要后端 API 的命令均无需额外配置，直接使用。
 
+账号提示待激活时，使用同一目标环境及已保存的个人访问令牌主动激活：
+
+```bash
+playcraft login --activate
+playcraft login --activate --url https://your-playcraft.example.com
+```
+
+也可通过 `PLAYCRAFT_TOKEN` 提供个人访问令牌。激活只发送一次请求，成功后重新执行原业务命令；该动作不会打开浏览器或续签令牌。目标服务须已接入身份服务的激活入口；封禁、停用账号及沙箱执行令牌不能用于激活。
+
+若本地、全局或环境变量配置冲突，激活会要求明确指定 `--url`、所需的 `PLAYCRAFT_ENV` 和对应的个人访问令牌。
+
 ### 沙箱环境（CI / Agent）
 
 在沙箱或 CI 中可通过 `.playcraft.json` 或环境变量配置：
@@ -188,6 +219,30 @@ echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
 | `recommend improvements`  | Tag 改进建议        | `playcraft recommend improvements --channel Facebook`                 |
 | `recommend random`        | 随机 Tag 组合推荐   | `playcraft recommend random --channel Google`                         |
 
+### 业务工具请求恢复
+
+业务工具写请求要求服务支持持久操作协议。命令行先保存请求编号、路径和输入摘要到 `~/.playcraft/tool-requests/`，再发送请求；记录不包含凭证或请求正文。可用绝对路径环境变量 `PLAYCRAFT_TOOL_REQUEST_DIR` 指定可持久保留的目录。
+
+原样重跑同一条命令（路径与参数都相同）时，命令行按上一次的结果决定是否沿用原请求编号：
+
+| 上一次的结果                                                         | 原样重跑时                                               |
+| -------------------------------------------------------------------- | -------------------------------------------------------- |
+| 成功（2xx）                                                          | 新操作                                                   |
+| 请求被拒绝（4xx，下列 409 除外）：请求没有被执行                     | 新操作                                                   |
+| 服务端错误（5xx）、超时或连接中断：结果未知                          | 沿用原编号，不会另起一次操作；服务端按下文的恢复方式处理 |
+| 409 `business_operation_in_progress`：原操作仍在执行                 | 沿用原编号，稍后重跑取得结果                             |
+| 409 `business_operation_requires_reconciliation`：结果未知，需要核对 | 沿用原编号，不会再执行                                   |
+
+沿用原编号时，服务端按原操作的状态处理：已完成则返回原结果；仍在执行则返回 409 `business_operation_in_progress`；没有拿到结果就结束时，按该工具声明的恢复方式决定，可以安全重做的工具（生图、构建、发布到 COS 等）用原编号再执行一次，其余返回 409 `business_operation_requires_reconciliation`。原调用的执行租约有效期间（执行中每 20 秒续期，60 秒未续即过期），同一编号不会被再次执行；续期因服务或数据库故障中断超过 60 秒时，重做可能与仍在运行的原调用重叠。
+
+需要核对的操作，只有确认它没有生效后，才可设置 `PLAYCRAFT_TOOL_NEW_REQUEST=1` 强制发起新操作；不要删除记录来绕过。也可以显式指定编号，只查询原操作的确定结果（不会重新执行；声明了恢复方式的工具若上次报错，返回那次的错误）。只查询时即使是可以安全重做的工具，没有结果也返回需要核对；去掉 `PLAYCRAFT_TOOL_REQUEST_ID` 原样重跑即可续做：
+
+```bash
+PLAYCRAFT_TOOL_REQUEST_ID=<错误中显示的请求编号> playcraft tools build-project --project-id <原项目编号>
+```
+
+能力检查失败时命令会明确说明尚未发送操作。服务不兼容时命令会在发送业务请求前停止；沙箱命令行与 Business 须排空旧调用后同步升级。
+
 ### 构建相关
 
 | 命令             | 说明                                     | 示例                                                   |

package/SKILLS_REGISTRY.md

@@ -0,0 +1,149 @@
+# 远程技能管理
+
+`playcraft skills registry` 管理已部署注册表中的技能、不可变版本和发行审核。它与现有离线 `skills list/match/read`、项目 `skills project` 命令并存。服务端需要提供 `/api/agent/skill-registry/managed` 路由。
+
+网页管理复用现有技能控制台的“发布与更新”页签：系统管理入口为 `/admin/system?tab=agentSkills`，技能工作台入口为 `/agent/skills?view=management`。不新增 Skills 一级导航，旧 `/skills` 仅保留兼容重定向。
+
+2026-10-15 已在当前开发配置指定的目标数据库执行并验证 0186 和 [0187_add_skill_scope_governance.sql](../backend-business-server/drizzle/migrations/0187_add_skill_scope_governance.sql)。其他环境启用前仍须应用对应迁移，并部署配套服务与客户端。本次目标数据库升级不代表生产已上线或命令包已发行。
+
+## 登录与目标环境
+
+```bash
+playcraft login --url 'https://playcraft.example.com/__env/test-a'
+playcraft skills registry list --scope private --json
+```
+
+命令复用登录保存的 PAT (Personal Access Token, 个人访问令牌)。所有命令支持 `--url`、`--token`、`--json`、`--scope private|team|platform` 和 `--team <teamId>`。环境地址顺序为 `--url`、`PLAYCRAFT_API_URL`、`PLAYCRAFT_URL`、已保存地址、默认云端。令牌优先使用 `--token` 或 `PLAYCRAFT_TOKEN`，否则仅使用该环境保存的凭据。环境路径前缀完整保留，向其他环境不会自动发送原环境令牌。
+
+`private` 是默认范围；`team` 必须明确传入 `--team`，其他范围不能携带 `--team`。`--json` 成功时只输出一个结果对象，运行错误时只输出一个 `error` 对象并以非零状态退出。未知参数或缺少必填参数由命令解析器报告到标准错误。
+
+## 查询与下载
+
+```bash
+playcraft skills registry list --scope private --query video --limit 20 --json
+playcraft skills registry list --scope team --team '<teamId>' --cursor '<nextCursor>' --json
+playcraft skills registry list --scope platform --json
+playcraft skills registry info author/video-helper@1.2.0 --files --json
+playcraft skills registry info author/video-helper --versions --json
+playcraft skills registry pull author/video-helper@1.2.0 --out ./downloaded-skill --json
+```
+
+`list` 支持关键词、1–100 条分页和返回的 `nextCursor`；不会自动取完所有页面。`info` 默认省略正文与文件清单，`--files` 返回文件清单，`--versions` 返回可访问版本。查询与下载可省略版本，此时先解析所选发行范围的当前版本，再按其精确版本标识下载。
+
+`pull` 同时验证元数据、响应头和压缩包的 SHA-256 (Secure Hash Algorithm 256-bit, 256 位安全散列算法) 摘要。包内已声明的 `skillRef/version` 必须匹配；历史制品可缺少声明，仍按服务端精确版本与摘要校验，不重写原制品。内容先写入临时目录，校验完成后原子落地；目标须不存在或为空，路径不能包含符号链接。拉取不会执行资源中的脚本，不修改项目声明、锁或运行时绑定。`.playcraft-skill.json` 保存环境、身份、版本和摘要，不含凭据；再次打包时自动排除。
+
+## 上传与发布
+
+技能目录必须包含非空 `SKILL.md`，可包含 `manifest.json`、`references/`、`scripts/`、`assets/` 等完整资源。`manifest.json` 可直接声明 `skillRef/version`；否则通过参数明确提供。标识必须是小写 `namespace/slug`，以字母或数字开头，允许连字符和下划线，slug 还允许点号。版本目前支持无前导零的精确 `x.y.z`，最多 32 字符；不支持预发行、构建后缀、`latest` 或版本范围。
+
+首期上传接受 Markdown 技能包（`bundleType: "markdown"`），Atom 技能的查询与下载可用，上传管理尚未开放。正式发行还要求有效名称和描述，建议在 `SKILL.md` 的 frontmatter 中声明 `name` 与 `description`，或在清单中声明。平台发行还要求上传时通过 `--changelog` 提供变更说明，并完成平台评估与管理员审核。
+
+```bash
+# 只登记草稿，不发布
+playcraft skills registry push ./my-skill --ref author/video-helper --version 1.2.0 --json
+
+# 上传后发布到本人范围；本人发布与更新免管理员审核
+playcraft skills registry publish ./my-skill --ref author/video-helper --version 1.2.0 --scope private --json
+
+# 上传新版本，明确旧版本；先同步修改清单中的 version（若已声明）
+playcraft skills registry update author/video-helper --from ./my-skill --version 1.3.0 --base-version 1.2.0 --changelog 'Improve examples' --json
+playcraft skills registry publish author/video-helper@1.3.0 --scope private --json
+
+# 同一精确版本推广到团队或平台，不重新分配身份
+playcraft skills registry publish author/video-helper@1.3.0 --scope team --team '<teamId>' --json
+playcraft skills registry publish author/video-helper@1.3.0 --scope platform --json
+```
+
+目录打包仅在内存中补充缺失的清单字段，不改动源目录。显式参数与现有清单身份或版本冲突时拒绝上传。`publish <ref>@<version>` 只发布已上传版本，不能同时传入目录上传参数 `--ref`、`--version`、`--base-version` 或 `--changelog`。排除根目录 `.git`、`node_modules` 和拉取回执；其他文件按目录完整收录，发布前应确保目录只包含需要分享的技能资源。拒绝符号链接、硬链接、不安全路径及大小超限：最多 512 个文件，单文件 16 MiB (Mebibyte, 二进制兆字节)，内容总量与压缩包各 64 MiB。清单中的文件引用和显式摘要必须匹配实际文件。
+
+全平台同一 `skillRef@version` 唯一；同内容重传复用版本，改内容必须增加版本号。已有命名空间占用或所有权冲突不会转换为更新他人技能。平台保留标识和新建平台归属技能由服务端管理员权限控制，普通作者可先上传本人技能，再向平台发行提审。
+
+`push/update` 返回 `published: false`。`publish` 先检查当前发行指针，再携带该指针提交；并发发行变更由服务端拒绝。本人发行免审核；团队发行须目标团队管理员批准；平台发行须平台管理员批准。没有有效批准时，发布返回 `status: "review_pending"`、`published: false` 和审核标识。以返回字段为准，命令成功不代表已经发行。
+
+## 审核、历史与回滚
+
+```bash
+playcraft skills registry publish-check author/video-helper@1.3.0 --scope team --team '<teamId>' --json
+playcraft skills registry review submit author/video-helper@1.3.0 --scope team --team '<teamId>' --json
+playcraft skills registry review list --scope team --team '<teamId>' --json
+playcraft skills registry review approve '<reviewId>' --json
+playcraft skills registry review reject '<reviewId>' --reason 'Add usage examples' --json
+
+# 审核后显式发布相同版本、相同目标范围
+playcraft skills registry publish author/video-helper@1.3.0 --scope team --team '<teamId>' --json
+playcraft skills registry history author/video-helper --scope team --team '<teamId>' --json
+playcraft skills registry rollback author/video-helper@1.2.0 --scope team --team '<teamId>' --reason 'Regression in 1.3.0' --json
+```
+
+审核决定只批准或拒绝指定申请，不自动执行发布。审核授权与申请目标范围由服务端校验。`publish-check` 显示硬性问题、评估问题、审核要求和当前发行指针；检查通过仍可能因发布时权限或指针改变而失败。回滚只移动选定范围的发行指针，复用已有精确版本，仍受该范围授权、审核和并发检查约束，不重写旧项目锁。
+
+## 中断与恢复
+
+修改请求不自动重试。命令在发出请求前将请求键及 `pending` 状态写入 `~/.playcraft/registry-requests/`，收到明确结果后记录 `completed/rejected`；回执不保存令牌或技能内容。发布与回滚同时保存操作目标、精确版本、摘要和首次检查得到的发行指针。超时、断线或响应无法确认目标时保留 `pending`；相同环境、凭据和操作的重试复用原请求键及原发行指针，不重新检查后覆盖其他人后来发布的版本。已明确完成或拒绝后，再次执行属于新的操作，会重新检查并分配请求键。服务端精确版本、内容摘要及发行指针是最终事实来源。上传后发布中断时，也可运行 `info <ref>@<version>`、`publish-check` 和 `history` 核对，再继续精确版本发布。
+
+## 原生平台视频技能首次登记
+
+云工作区默认使用的两个引用是 `remix/playcraft-video-understanding` 和 `remix/playcraft-replica-validation`。它们必须通过 `platform push` 登记，服务端会创建 `kind=platform`、`source=platform` 的原生身份。普通 `push --scope platform` 创建的是托管工作区技能，不能替代这一入口。
+
+```bash
+playcraft skills registry platform push ./playcraft-video-understanding-1.0.1.tar.gz --changelog '更新视频理解指引与评估用例' --json
+playcraft skills registry platform push ./playcraft-replica-validation-1.0.1.tar.gz --changelog '更新复刻验收指引与评估用例' --json
+```
+
+`platform push <source>` 接受完整目录或已准备的压缩包。目录必须已含原生 `manifest.json`；命令保留其文件内容，不补充托管技能默认字段。已有压缩包原样发送，不重打包。可选的 `--ref`、`--version` 必须与清单一致；可用 `--evaluation-template <templateId>` 指定初始评估模板。原生入口当前仅接受上述两个引用，要求平台类型、单一 `sandbox-agent` surface、对齐的名称与版本、无 imports/relationships；服务端执行完整校验与摘要归一化，并返回最终 `artifactHash`。登记不会自动评估、审核或发布。
+
+此入口要求具有平台管理权限的真实账号凭据；命令复用目标环境登录，不发送本地身份模拟请求头。服务端需已部署允许真实管理员个人访问令牌访问原生登记和评估接口的版本。
+
+## 真实评估
+
+评估会使用指定工作区的模型和配置，在服务端评估执行器中实际运行用例。命令不构造通过记录，也不调用内部执行步骤接口。评估队列、执行器、模型和证据存储均须可用。先明确目标环境、工作区以及精确 `ref@version`，再选择模板和模型：
+
+```bash
+playcraft skills registry evaluation templates list --json
+playcraft skills registry evaluation models --workspace '<workspaceId>' --json
+playcraft skills registry evaluation config get remix/playcraft-video-understanding@1.0.1 --scope platform --json
+```
+
+没有可用模板时，管理员可创建并启用模板：
+
+```bash
+playcraft skills registry evaluation templates create --input ./evaluation-template.json --json
+playcraft skills registry evaluation templates enable '<templateId>' --json
+# 停用模板会使相关发布检查不再接受该模板
+playcraft skills registry evaluation templates disable '<templateId>' --json
+```
+
+模板输入文件只接受 `{ "key": "...", "name": "...", "spec": { ... } }`。`spec` 使用现有评估模板字段：`executor`、`dockerImage`、`cloudTemplateId`、`nodeVersion`、`opencodeVersion`、`modelConfigId`、`graderVersion`、`caseTimeoutSeconds`、`runTimeoutSeconds`、`globalConcurrency`。填写实际运行镜像与工具版本；使用本地 Docker 时不要填写虚构的云模板标识。运行平台如何选择执行器由部署配置决定，命令不会自动切换。模板创建会分配新修订，**不保证请求键幂等**；若响应丢失，先用 `templates list` 核对，再决定是否重试。
+
+配置输入文件只接受 `{ "templateId": "...", "expectedRevision": 0, "spec": { ... } }`。`expectedRevision` 使用 `config get` 返回的修订号；`spec` 包含 `modelConfigId`、`caseTimeoutSeconds`、`cases`。用例结构及断言种类见 [共享评估类型](../common/src/skill-evaluation.ts)。填写有意义的真实提示词、输入文件、断言和必要的模型评审要求；服务端校验完整性、运行证据与发布条件。
+
+```bash
+playcraft skills registry evaluation config set remix/playcraft-video-understanding@1.0.1 --scope platform --input ./video-evaluation-config.json --json
+playcraft skills registry evaluation run remix/playcraft-video-understanding@1.0.1 --scope platform --workspace '<workspaceId>' --config '<configId>' --request-key 'video-1-0-1-run-001' --wait --timeout 1800 --interval 3 --json
+```
+
+`--config` 必须是保存返回的精确配置标识；工作区标识不要求是通用唯一标识符。请求键允许 8–128 位字母、数字、下划线或连字符；重新执行一次评估需新键，断线恢复同一次评估需复用原键及全部原参数。`--compare` 可同时评估当前稳定版作为基线。省略 `--wait` 时返回已创建评估；带 `--wait` 时只有 `phase=completed` 且 `verdict=passed` 才成功退出，失败或取消会返回包含评估记录的结构化错误并非零退出。
+
+```bash
+playcraft skills registry evaluation status '<runId>' --json
+playcraft skills registry evaluation runs remix/playcraft-video-understanding@1.0.1 --scope platform --workspace '<workspaceId>' --json
+playcraft skills registry evaluation wait '<runId>' --timeout 1800 --interval 3 --json
+playcraft skills registry evaluation evidence '<runId>' --case '<caseResultId>' --json
+playcraft skills registry evaluation cancel '<runId>' --json
+```
+
+`--case` 使用状态结果中的 `results[].id`，不是逻辑用例名 `normal/boundary/regression`。状态含用例结果和检查项；`evidence` 读取对应归档证据。轮询默认最多 600 秒、间隔 3 秒；超时只停止等待，不取消后台评估，也不自动重新发起。修改请求不自动重试；配置写入使用预期修订号，断线后先读取配置确认实际结果。
+
+## 同一原生版本的正式发布
+
+应用治理迁移后，原生平台身份也使用托管注册表的审核、检查和发布命令；不要调用旧发布接口。评估配置变化会使旧配置的审核和证据失效。完成真实评估后，对同一精确版本提交审核、查看证据并由有权限的管理员批准，然后发布：
+
+```bash
+playcraft skills registry review submit remix/playcraft-video-understanding@1.0.1 --scope platform --json
+playcraft skills registry review approve '<reviewId>' --json
+playcraft skills registry publish-check remix/playcraft-video-understanding@1.0.1 --scope platform --json
+playcraft skills registry publish remix/playcraft-video-understanding@1.0.1 --scope platform --json
+playcraft skills registry history remix/playcraft-video-understanding --scope platform --json
+```
+
+对 `remix/playcraft-replica-validation@1.0.1` 独立完成同样流程。检查必须没有硬性或评估问题；最终核对 `published: true`、返回的精确版本与摘要，以及发行历史。命令没有例外发布选项，不跳过真实评估或审核。这里描述的是操作流程，新增命令的自动测试通过不代表任一环境已完成真实评估或正式发布。工作区预览绑定仍不属于本命令组。

package/dist/agent/local-backend.js

@@ -2,7 +2,7 @@ import express from 'express';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import { eq, inArray } from 'drizzle-orm';
+import { eq, inArray } from '@playcraft/common/database/operators';
 import pc from 'picocolors';
 import { createSqliteAdapter } from '@playcraft/common/database';
 import { AssetModel, ProjectModel, SceneModel } from '@playcraft/common/models';

package/dist/auth/account-activation.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadGlobalConfig } from '../config.js';
+import { accountActivationMessage } from './messages.js';
+export const ACCOUNT_PENDING_ACTIVATION = 'account_pending_activation';
+export class AccountActivationError extends Error {
+    code;
+    status;
+    retryable = false;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'AccountActivationError';
+    }
+}
+export function responseErrorCode(payload) {
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const { error, code } = payload;
+    return typeof error?.code === 'string' ? error.code : typeof code === 'string' ? code : undefined;
+}
+export function pendingAccountActivationError(status, payload) {
+    return status === 403 && responseErrorCode(payload) === ACCOUNT_PENDING_ACTIVATION
+        ? new AccountActivationError(ACCOUNT_PENDING_ACTIVATION, `${ACCOUNT_PENDING_ACTIVATION}: ${accountActivationMessage('pending')}`, status)
+        : undefined;
+}
+export function parseErrorPayload(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function localActivationConfig() {
+    for (const path of [
+        join(process.cwd(), '.playcraft.json'),
+        '/project/.playcraft.json',
+        join(homedir(), '.playcraft.json'),
+    ]) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const config = JSON.parse(readFileSync(path, 'utf8'));
+            if (config && typeof config === 'object' && !Array.isArray(config))
+                return config;
+        }
+        catch {
+            // Follow the existing local credential lookup when a file is unreadable.
+        }
+    }
+    return {};
+}
+function stringValue(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+function activationBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw new Error();
+        url.pathname = url.pathname.replace(/\/+$/, '').replace(/\/api$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        throw new AccountActivationError('INVALID_ACTIVATION_TARGET', accountActivationMessage('invalidTarget'));
+    }
+}
+function savedTokenForTarget(config, rawUrl, target, environment) {
+    if (!rawUrl || (stringValue(config.env)?.trim() || '') !== environment)
+        return undefined;
+    try {
+        return activationBaseUrl(rawUrl) === target ? stringValue(config.token) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizedSavedUrl(raw) {
+    try {
+        return raw ? activationBaseUrl(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function activateAccount(options, defaultBaseUrl) {
+    const local = localActivationConfig();
+    const global = loadGlobalConfig();
+    const localUrl = stringValue(local.apiUrl);
+    const globalUrl = stringValue(global.backendUrl) || stringValue(global.url);
+    const explicitUrl = options.url || process.env.PLAYCRAFT_API_URL || process.env.PLAYCRAFT_URL;
+    const target = activationBaseUrl(explicitUrl || localUrl || globalUrl || defaultBaseUrl);
+    const explicitToken = options.token || process.env.PLAYCRAFT_TOKEN || process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const savedUrls = [normalizedSavedUrl(localUrl), normalizedSavedUrl(globalUrl)].filter(Boolean);
+    const savedTokens = [stringValue(local.token), stringValue(global.token)].filter(Boolean);
+    const environmentsConflict = savedUrls.length === 2 &&
+        savedUrls[0] === savedUrls[1] &&
+        (stringValue(local.env)?.trim() || '') !== (stringValue(global.env)?.trim() || '');
+    const environmentTokensConflict = process.env.PLAYCRAFT_TOKEN &&
+        process.env.PLAYCRAFT_SANDBOX_TOKEN &&
+        process.env.PLAYCRAFT_TOKEN !== process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const environmentUrlsConflict = process.env.PLAYCRAFT_API_URL &&
+        process.env.PLAYCRAFT_URL &&
+        normalizedSavedUrl(process.env.PLAYCRAFT_API_URL) !==
+            normalizedSavedUrl(process.env.PLAYCRAFT_URL);
+    if ((!explicitUrl && new Set(savedUrls).size > 1) ||
+        (!explicitToken && new Set(savedTokens).size > 1) ||
+        (environmentsConflict && !process.env.PLAYCRAFT_ENV) ||
+        (environmentTokensConflict && !options.token) ||
+        (environmentUrlsConflict && !options.url)) {
+        throw new AccountActivationError('AMBIGUOUS_ACTIVATION_TARGET', accountActivationMessage('ambiguous'));
+    }
+    const environment = (process.env.PLAYCRAFT_ENV ||
+        (!explicitUrl ? (localUrl ? stringValue(local.env) : stringValue(global.env)) : '') ||
+        '').trim();
+    const token = explicitToken ||
+        savedTokenForTarget(local, localUrl, target, environment) ||
+        savedTokenForTarget(global, globalUrl, target, environment);
+    if (!token)
+        throw new AccountActivationError('AUTH_REQUIRED', accountActivationMessage('missingToken'));
+    if (!/^playcraft_pat_[A-Za-z0-9_-]{32}$/.test(token)) {
+        throw new AccountActivationError('INVALID_ACTIVATION_TOKEN', accountActivationMessage('invalidToken'));
+    }
+    let response;
+    try {
+        response = await fetch(`${target}/api/settings/personal-access-tokens/activate`, {
+            method: 'POST',
+            redirect: 'error',
+            signal: AbortSignal.timeout(30_000),
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...(environment ? { 'playcraft-env': environment } : {}),
+            },
+        });
+    }
+    catch {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'));
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new AccountActivationError('ACTIVATION_FAILED', accountActivationMessage('failed'), response.status);
+    }
+    const result = await response.json().catch(() => undefined);
+    if (!result ||
+        typeof result !== 'object' ||
+        result.accountStatus !== 'active') {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'), response.status);
+    }
+    console.log(accountActivationMessage('success'));
+}

package/dist/auth/messages.js

@@ -0,0 +1,30 @@
+const messages = {
+    en: {
+        activateOption: 'Explicitly activate the account using the current personal access token',
+        tokenOption: 'Personal access token for --activate (or use PLAYCRAFT_TOKEN)',
+        pending: 'Account activation is required. Run `playcraft login --activate` with the same token and target environment, then rerun your command.',
+        success: 'Account activated. Rerun your original command to continue.',
+        missingToken: 'No personal access token matches this target environment. Provide PLAYCRAFT_TOKEN or log in to this environment first.',
+        invalidToken: 'Account activation requires a personal access token. A sandbox token cannot activate an account.',
+        ambiguous: 'Activation credentials or target environments conflict. Specify --url, PLAYCRAFT_ENV when needed, and an explicit personal access token using --token or PLAYCRAFT_TOKEN.',
+        invalidTarget: 'Use a web service base address (http:// or https://) without credentials, a query, or a fragment.',
+        failed: 'Account activation failed. Check the target environment and token before trying again.',
+        unavailable: 'Account activation could not be confirmed. Check your account status before explicitly trying again.',
+    },
+    zh: {
+        activateOption: '明确使用当前个人访问令牌激活账号',
+        tokenOption: '用于 --activate 的个人访问令牌（也可使用 PLAYCRAFT_TOKEN）',
+        pending: '账号需要激活。请使用同一令牌和目标环境主动运行 `playcraft login --activate`，然后重新执行原命令。',
+        success: '账号已激活，请重新执行原命令继续。',
+        missingToken: '没有与目标环境匹配的个人访问令牌。请提供 PLAYCRAFT_TOKEN，或先登录此环境。',
+        invalidToken: '激活账号需要个人访问令牌，沙箱令牌不能用于激活账号。',
+        ambiguous: '激活凭据或目标环境存在冲突。请明确指定 --url、所需的 PLAYCRAFT_ENV，并通过 --token 或 PLAYCRAFT_TOKEN 提供个人访问令牌。',
+        invalidTarget: '激活目标必须是网页服务基址（http:// 或 https://），不能包含凭据、查询参数或片段。',
+        failed: '账号激活失败，请检查目标环境和令牌后再尝试。',
+        unavailable: '无法确认账号是否已激活。请先检查账号状态，再主动决定是否重试。',
+    },
+};
+export function accountActivationMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/cli-root-help.js

@@ -5,8 +5,10 @@ export function getCliTopicsHelpText() {
         '',
         '  本地开发   create, init, start, stop, status, logs, config, sync, fix-ids',
         '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>  |  prefab <子命令>',
+        '  视频理解   video models | video understand | video jobs get/cancel',
         '  平台       build, build-base, build-playable, build-all, analyze, inspect, upgrade',
         '             tools 除 generate-* 外（Git / 沙箱构建 / 发布 / 列表 / Prefab 等，需后端 API）',
+        '  沙箱常驻   workspace-runtime serve（Cloud Workspace，由 Runtime 引导配置启动）',
         '',
         '也可运行: playcraft topics',
         '',

package/dist/commands/build-all.js

@@ -4,6 +4,7 @@ import pc from 'picocolors';
 import ora from 'ora';
 import { BaseBuilder, ViteBuilder, PlayableBuilder, EngineDetector, detectAmmoUsage, } from '@playcraft/build';
 import { loadBuildConfig } from '../build-config.js';
+import { cleanupBuildTempDirectory, createBuildTempDirectory } from './build-temp.js';
 import inquirer from 'inquirer';
 /**
  * 所有可用的渠道平台
@@ -141,6 +142,7 @@ export async function buildAllCommand(projectPath, options) {
     const spinner = ora(pc.cyan('🚀 批量打渠道包...')).start();
     let isBaseBuild = false;
     let baseBuildDir;
+    let tempBuildDir;
     try {
         // 1. 确定要构建的平台列表
         let targetPlatforms;
@@ -415,9 +417,9 @@ export async function buildAllCommand(projectPath, options) {
         }
         else {
             spinner.text = pc.cyan('执行阶段1: 基础构建（仅一次）...');
-            const tempDir = path.join(resolvedProjectPath, '.playcraft-temp', `base-build-${Date.now()}`);
+            tempBuildDir = await createBuildTempDirectory(resolvedProjectPath);
             const baseBuilder = new BaseBuilder(resolvedProjectPath, {
-                outputDir: tempDir,
+                outputDir: tempBuildDir,
                 selectedScenes,
                 analyze: options.analyze,
             });
@@ -593,6 +595,7 @@ export async function buildAllCommand(projectPath, options) {
         if (failCount > 0) {
             process.exit(1);
         }
+        await cleanupBuildTempDirectory(tempBuildDir);
     }
     catch (error) {
         spinner.fail(pc.red('批量构建失败'));
@@ -602,21 +605,4 @@ export async function buildAllCommand(projectPath, options) {
         }
         process.exit(1);
     }
-    finally {
-        // 清理临时目录，避免磁盘空间浪费
-        if (!isBaseBuild && baseBuildDir && baseBuildDir.includes('.playcraft-temp')) {
-            try {
-                await fs.rm(baseBuildDir, { recursive: true, force: true });
-                // 如果 .playcraft-temp 父目录为空，也一并清理
-                const tempParent = path.dirname(baseBuildDir);
-                const remaining = await fs.readdir(tempParent);
-                if (remaining.length === 0) {
-                    await fs.rm(tempParent, { recursive: true, force: true });
-                }
-            }
-            catch {
-                // 清理失败不影响构建结果
-            }
-        }
-    }
 }

package/dist/commands/build-temp.js

@@ -0,0 +1,26 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+export async function createBuildTempDirectory(projectPath) {
+    const parent = path.join(projectPath, '.playcraft-temp');
+    await mkdir(parent, { recursive: true });
+    const directory = path.join(parent, `base-build-${randomUUID()}`);
+    // mkdir 继承工程的共享组和权限掩码；mkdtemp 固定使用 0700。
+    await mkdir(directory);
+    return directory;
+}
+export async function cleanupBuildTempDirectory(directory) {
+    if (!directory)
+        return;
+    if (process.env.PLAYCRAFT_KEEP_BUILD_TEMP === '1') {
+        console.log(`构建临时目录保留在: ${directory}`);
+        return;
+    }
+    try {
+        // 只删除本次创建的目录，保留并发构建与用户输入；父目录不做递归清理。
+        await rm(directory, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.warn(`清理构建临时目录失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}