@playcraft/cli 0.1.54 → 0.1.55-beta

package/README.md

@@ -7,14 +7,38 @@
 
 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` 要求本地修改已经提交，按上次确认的文件树生成增量包，只传输变化的文件内容，并将新增、修改和删除同步回同一个云工作区。旧克隆保留的 `.playcraft-workspace.json` 中已有文件树摘要，可继续使用新版命令推送。大文件随增量包传输，无需 Git LFS（Large File Storage，大文件存储），也无需为本地克隆配置真实远程 Git 仓库。
+
+工作区传输容量按管理员配置的工作区存储额度和沙箱剩余磁盘空间判断。管理员可通过 `PLAYCRAFT_WORKSPACE_STORAGE_QUOTA_BYTES` 设置每个工作区的存储总量上限，值为正整数字节数；额度覆盖整个工作区的实际文件，包括依赖和 Git 元数据。该设置在新沙箱创建时下发，修改环境变量不会自动更新已有沙箱。未设置时，仍检查沙箱可用磁盘空间，并保留总容量的 10% 作为运行余量。传输包与临时快照也需要磁盘空间；容量不足时，应清理不再需要的文件或由管理员调整额度。弹窗中的直接下载用于导出文件，不能代替推送本地修改。
+
+云端文件变化或有正在运行的任务时，推送会拒绝覆盖，需重新克隆并合并后再推送。云端现有 Git 仓库和分支元数据会保留，保存到远端项目仍使用工作区原有保存流程；针对项目分支的操作可继续使用 `remix clone` / `remix push`。命令支持 `--token`、`--dir` 与 `--json`。
 
 ## ✨ 特性
 
+远程技能的上传、更新、发布、审核、查询与下载见 [技能注册表命令](./SKILLS_REGISTRY.md)。入口为 `playcraft skills registry`，复用已有登录；本地技能发现与项目技能命令保持原有语义。
+
 - 🚀 **本地开发隧道** - 在本地 IDE 编写代码，云端编辑器实时预览与热更新
 - 📦 **Playable Ads 打包** - 支持 10 个主流广告平台的一键打包
 - 🎬 **智能场景选择** - 交互式场景选择，可减小 30-60% 文件大小（**新功能**）
@@ -141,6 +165,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` 或环境变量配置：
@@ -175,18 +210,51 @@ echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
 
 > 运行 `playcraft login` 后所有子命令均可直接使用。
 
-| 命令                      | 说明                | 示例                                                                  |
-| ------------------------- | ------------------- | --------------------------------------------------------------------- |
-| `tools generate-image`    | AI 生成图片         | `playcraft tools generate-image --prompt "pixel art sky"`             |
-| `tools generate-sfx`      | AI 生成音效         | `playcraft tools generate-sfx --prompt "UI click"`                    |
-| `tools generate-bgm`      | AI 生成 BGM         | `playcraft tools generate-bgm --prompt "casual game music"`           |
-| `tools list-image-models` | 列出可用生图模型    | `playcraft tools list-image-models`                                   |
-| `tools list-remixes`      | 查看 Remix 项目列表 | `playcraft tools list-remixes`                                        |
-| `tools save-to-git`       | 同步沙箱内容到 Git  | `playcraft tools save-to-git --project-id <id> --message "feat: ..."` |
-| `tools build-project`     | 在沙箱中执行构建    | `playcraft tools build-project --project-id <id>`                     |
-| `recommend similar`       | 相似 Creative 推荐  | `playcraft recommend similar --channel Applovin`                      |
-| `recommend improvements`  | Tag 改进建议        | `playcraft recommend improvements --channel Facebook`                 |
-| `recommend random`        | 随机 Tag 组合推荐   | `playcraft recommend random --channel Google`                         |
+| 命令                                                    | 说明                           | 示例                                                                          |
+| ------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `tools generate-image`                                  | AI 生成图片                    | `playcraft tools generate-image --prompt "pixel art sky"`                     |
+| `tools generate-sfx`                                    | AI 生成音效                    | `playcraft tools generate-sfx --prompt "UI click"`                            |
+| `tools generate-bgm`                                    | AI 生成 BGM                    | `playcraft tools generate-bgm --prompt "casual game music"`                   |
+| `tools list-image-models`                               | 列出可用生图模型               | `playcraft tools list-image-models`                                           |
+| `library search`                                        | 检索有权访问的素材库           | `playcraft library search "角色" --type texture --json`                       |
+| `library download`                                      | 下载单文件或完整素材包         | `playcraft library download <assetId> --output ./assets/character`            |
+| `image decompose-layers`                                | 与云工作区一致的图层分离       | `playcraft image decompose-layers --input scene.png --output-dir dist/layers` |
+| `image analyze-nine-patch`                              | 分析九宫格拉伸边距             | `playcraft image analyze-nine-patch --input panel.png --output panel.json`    |
+| `assets generate`                                       | 创建可恢复的工作区素材生成任务 | `playcraft assets generate --request request.json --client-request-id <uuid>` |
+| `assets tasks` / `get` / `wait` / `cancel` / `download` | 管理工作区生成任务和结果       | `playcraft assets download <taskId> --output ./assets/result`                 |
+| `tools list-remixes`                                    | 查看 Remix 项目列表            | `playcraft tools list-remixes`                                                |
+| `tools save-to-git`                                     | 同步沙箱内容到 Git             | `playcraft tools save-to-git --project-id <id> --message "feat: ..."`         |
+| `tools build-project`                                   | 在沙箱中执行构建               | `playcraft tools build-project --project-id <id>`                             |
+
+| `recommend similar` | 相似 Creative 推荐 | `playcraft recommend similar --channel Applovin` |
+| `recommend improvements` | Tag 改进建议 | `playcraft recommend improvements --channel Facebook` |
+| `recommend random` | 随机 Tag 组合推荐 | `playcraft recommend random --channel Google` |
+
+云工作区工具与命令行的完整对应、权限规则和请求示例见[工具覆盖说明](../../docs/cli/cloud-workspace-tool-parity.md)。
+
+### 业务工具请求恢复
+
+业务工具写请求要求服务支持持久操作协议。命令行先保存请求编号、路径和输入摘要到 `~/.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/assets/client.js

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, mkdtemp, open, readFile, rm } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { assetGenerationTaskSchema, assetGenerationTaskListSchema, animationEditorStateSchema, workspaceSessionScopeSchema, ASSET_GENERATION_REQUEST_MAX_BYTES, } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveVideoWorkspace } from '../video-replication/client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { assetMessage as t } from './messages.js';
+export async function readAssetRequest(path) {
+    const handle = await open(resolve(resolveSandboxPath(path)), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > ASSET_GENERATION_REQUEST_MAX_BYTES)
+            throw new Error(t('requestTooLarge'));
+        return JSON.parse(await handle.readFile('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function resolveAssetScope(options, cwd = process.cwd()) {
+    const workspaceId = await resolveVideoWorkspace(options.workspace, cwd);
+    let inferred;
+    for (let cursor = resolve(cwd);; cursor = dirname(cursor)) {
+        try {
+            const value = JSON.parse(await readFile(join(cursor, '.playcraft/workspace-context.json'), 'utf8'));
+            if (value.workspaceId === workspaceId) {
+                // Cloud project roots are <workspaceRoot>/<workspaceId>/<engineeringDirectory>.
+                if (basename(dirname(cursor)) === workspaceId && workspaceSessionScopeSchema.safeParse(basename(cursor)).success)
+                    inferred = basename(cursor);
+                break;
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (dirname(cursor) === cursor)
+            break;
+    }
+    const parsed = workspaceSessionScopeSchema.safeParse(options.directory ?? inferred ?? 'basic');
+    if (!parsed.success || inferred && options.directory && inferred !== options.directory)
+        throw new Error(t('scopeMismatch'));
+    return { workspaceId, directoryName: parsed.data };
+}
+export function assetContentRoute(input) {
+    const query = new URLSearchParams(Object.entries(input).filter(([, value]) => value !== undefined));
+    return `/workspace-assets/content?${query}`;
+}
+export function scopedAssetTask(scope, value) {
+    const task = assetGenerationTaskSchema.parse(value);
+    if (task.workspaceId !== scope.workspaceId || task.directoryName !== scope.directoryName)
+        throw new Error(t('scopeMismatch'));
+    return task;
+}
+export async function readAssetTasks(client, scope) {
+    const value = assetGenerationTaskListSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'list' }));
+    return { tasks: value.tasks.map(task => scopedAssetTask(scope, task)) };
+}
+export async function readAssetTask(client, scope, taskId) {
+    const task = scopedAssetTask(scope, await client.get('/workspace-assets', { ...scope, action: 'get', taskId }));
+    if (task.taskId !== taskId)
+        throw new Error(t('scopeMismatch'));
+    return task;
+}
+export async function waitForAssetTask(client, scope, taskId, timeoutSeconds = 1800, intervalSeconds = 3) {
+    validateAssetWait(timeoutSeconds, intervalSeconds);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    for (;;) {
+        const task = await readAssetTask(client, scope, taskId);
+        if (!['queued', 'running', 'cancel_requested'].includes(task.status))
+            return task;
+        if (Date.now() >= deadline)
+            throw new Error(t('timeoutReached'));
+        await delay(Math.min(intervalSeconds * 1000, deadline - Date.now()));
+    }
+}
+export function validateAssetWait(timeoutSeconds, intervalSeconds) {
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0 || timeoutSeconds > 86400 || !Number.isFinite(intervalSeconds)
+        || intervalSeconds < 0.1 || intervalSeconds > 60)
+        throw new Error(t('invalidRequest'));
+}
+async function verifyFile(path, file) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        if ((await handle.stat()).size !== file.size)
+            throw new Error(t('invalidContent'));
+        const hash = createHash('sha256');
+        for await (const chunk of handle.createReadStream({ autoClose: false }))
+            hash.update(chunk);
+        if (hash.digest('hex') !== file.contentHash)
+            throw new Error(t('invalidContent'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Stage and verify every member before publishing the new local output. */
+export async function downloadAssetTask(client, scope, taskId, output, versionId) {
+    const task = await readAssetTask(client, scope, taskId);
+    if (!['awaiting_adoption', 'saved'].includes(task.status) || !task.output)
+        throw new Error(t('outputUnavailable'));
+    let bundle = task.bundle, entry = task.output;
+    if (versionId) {
+        const editor = animationEditorStateSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'animation', taskId }));
+        if (editor.taskId !== taskId)
+            throw new Error(t('scopeMismatch'));
+        const version = editor.versions.find(version => version.versionId === versionId);
+        if (!version)
+            throw new Error(t('outputUnavailable'));
+        bundle = version.bundle;
+        entry = version.output;
+    }
+    const destination = resolve(resolveSandboxPath(output));
+    if (await lstat(destination).then(() => true, error => { if (error.code === 'ENOENT')
+        return false; throw error; }))
+        throw new Error(t('outputExists'));
+    await mkdir(dirname(destination), { recursive: true });
+    const staging = await mkdtemp(join(dirname(destination), '.playcraft-asset-'));
+    let createdDestination = false;
+    try {
+        const files = bundle?.files ?? [{ ...entry, path: 'output', fileId: undefined }];
+        const paths = [];
+        for (const file of files) {
+            const temporary = resolve(staging, file.path);
+            const inside = relative(staging, temporary);
+            if (!inside || inside === '..' || inside.startsWith(`..${sep}`))
+                throw new Error(t('invalidContent'));
+            await mkdir(dirname(temporary), { recursive: true });
+            await client.download(assetContentRoute({ ...scope, taskId, ...(bundle ? { fileId: file.fileId } : {}), ...(versionId ? { versionId } : {}) }), temporary);
+            await verifyFile(temporary, file);
+            paths.push(bundle ? join(destination, file.path) : destination);
+        }
+        if (bundle) {
+            // mkdir is exclusive; an existing directory or symbolic link cannot be replaced.
+            await mkdir(destination);
+            createdDestination = true;
+            for (const file of files) {
+                const path = join(destination, file.path);
+                await mkdir(dirname(path), { recursive: true });
+                await link(join(staging, file.path), path);
+            }
+        }
+        else
+            await link(join(staging, 'output'), destination);
+        return { task, paths };
+    }
+    catch (error) {
+        if (createdDestination)
+            await rm(destination, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}

package/dist/assets/messages.js

@@ -0,0 +1,48 @@
+const messages = {
+    en: {
+        topic: 'Generate workspace assets and manage the same tasks shown in the workspace',
+        estimate: 'Estimate generation cost without creating a task', generate: 'Create a durable generation task',
+        tasks: 'List generation tasks', get: 'Read a generation task', cancel: 'Request task cancellation',
+        wait: 'Wait for an existing task; never submit another generation', download: 'Download a verified result, preserving all bundle files',
+        saved: 'Confirm workspace adoption using an existing platform write receipt',
+        libraryTargets: 'List authorized destination teams', librarySave: 'Copy a generated result into the asset library',
+        librarySaves: 'List library copy jobs', libraryRetry: 'Resume a library copy job using its existing identity',
+        animation: 'Inspect and edit generated frame animations', animationGet: 'Read the animation draft and versions',
+        animationDraft: 'Update a draft using its expected revision', animationFrame: 'Upload a replacement frame',
+        animationVersion: 'Export an immutable animation version', animationSaved: 'Confirm adoption of an animation version',
+        workspace: 'Workspace identifier; inferred from the current project when omitted', directory: 'Engineering directory; inferred inside the cloud workspace, otherwise basic',
+        request: 'Path to the request document', receipt: 'Path to a platform write receipt with operationId and path',
+        clientRequest: 'Stable request identity; reuse it after an uncertain submission',
+        output: 'Destination file, or new directory for a complete sprite or animation bundle',
+        waitOption: 'Wait for generation to finish', timeout: 'Maximum wait in seconds', interval: 'Polling interval in seconds',
+        version: 'Animation version identifier', saveId: 'Existing library copy job identifier', release: 'Start this library copy without waiting for workspace adoption',
+        json: 'Print structured results', invalidRequest: 'The request document or command arguments are invalid.',
+        scopeMismatch: 'The returned result belongs to another workspace or engineering directory.',
+        outputUnavailable: 'The task has no completed output to download.', outputExists: 'The output already exists. Choose a new destination.',
+        invalidContent: 'Downloaded content does not match the task size or content digest.', failed: 'Asset operation failed',
+        timeoutReached: 'Waiting timed out. Use assets get or assets wait with the same task identifier; generation was not cancelled.',
+        requestTooLarge: 'The request document exceeds the permitted size.',
+    },
+    zh: {
+        topic: '生成工作区素材，管理工作区面板中同一批任务', estimate: '估算生成费用，不创建任务', generate: '创建可恢复的素材生成任务',
+        tasks: '列出素材生成任务', get: '读取生成任务', cancel: '请求取消任务', wait: '等待已有任务，不会重新生成',
+        download: '校验并下载结果，保留素材包全部文件', saved: '用已有平台写入回执确认素材已采纳',
+        libraryTargets: '列出允许写入的团队素材库', librarySave: '将生成结果保存到素材库', librarySaves: '列出素材库保存任务',
+        libraryRetry: '沿用已有标识恢复素材库保存任务', animation: '查看、编辑生成的帧动画', animationGet: '读取动画草稿和版本',
+        animationDraft: '按预期修订号更新动画草稿', animationFrame: '上传替换帧', animationVersion: '导出不可变的动画版本',
+        animationSaved: '确认动画版本已采纳', workspace: '工作区标识；省略时从当前工程推断', directory: '工程目录；云工作区内自动推断，其余情况默认 basic',
+        request: '请求文档路径', receipt: '平台写入回执路径，需包含 operationId 和 path',
+        clientRequest: '稳定请求标识；提交结果不确定时复用同一标识', output: '目标文件路径；精灵图或动画素材包使用新目录',
+        waitOption: '等待生成完成', timeout: '最长等待秒数', interval: '查询间隔秒数', version: '动画版本标识',
+        saveId: '已有素材库保存任务标识', release: '立即执行此素材库保存任务，不再等待工作区采纳', json: '输出结构化结果',
+        invalidRequest: '请求文档或命令参数无效。', scopeMismatch: '返回结果不属于所选工作区或工程目录。',
+        outputUnavailable: '任务尚无可供下载的完整结果。', outputExists: '目标已存在，请选择新的保存位置。',
+        invalidContent: '下载内容与任务记录的大小或内容摘要不一致。', failed: '素材操作失败',
+        timeoutReached: '等待已超时。请使用同一任务标识运行 assets get 或 assets wait，生成任务未取消。',
+        requestTooLarge: '请求文档超过允许大小。',
+    },
+};
+export function assetMessage(key) {
+    const language = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[language.startsWith('zh') ? 'zh' : 'en'][key];
+}