@playcraft/cli 0.0.57 → 0.0.58

package/README.md

@@ -5,7 +5,13 @@
 [![npm version](https://img.shields.io/npm/v/@playcraft/cli.svg)](https://www.npmjs.com/package/@playcraft/cli)
 [![npm downloads](https://img.shields.io/npm/dm/@playcraft/cli.svg)](https://www.npmjs.com/package/@playcraft/cli)
 
-PlayCraft CLI 是一个功能强大的命令行工具，支持本地代码与云端编辑器实时同步，以及将 PlayCanvas/PlayCraft 项目打包为多平台 Playable Ads。
+PlayCraft CLI（Command-Line Interface，命令行工具）支持本地代码与云端编辑器实时同步，以及将 PlayCanvas/PlayCraft 项目打包为多平台 Playable Ads。
+
+## 云端工作台 Runtime
+
+`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` 仍用于单项目本地开发，二者不要混用。
+
+实现与模块边界见 [Sandbox Agent Server](./src/workspace-runtime/README.md)；契约见 [云端工作台后端架构方案](../../docs/architecture/backend/cloud-workspace/backend-architecture.md#cli-runtime)。
 
 ## ✨ 特性
 
@@ -75,7 +81,7 @@ npx @playcraft/cli start --project <project-id> --daemon
 npx @playcraft/cli build
 
 # 命令行打包
-npx @playcraft/cli build --platform facebook --format html --output ./dist
+npx @playcraft/cli build --platform facebook --format zip --output ./dist
 ```
 
 ### 5. 创建并继续编辑 Remix
@@ -182,6 +188,18 @@ 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` 指定可持久保留的目录。
+
+如果请求超时或连接中断，错误会显示请求编号。使用相同参数重跑命令，并设置该编号，只查询原操作的确定结果：
+
+```bash
+PLAYCRAFT_TOOL_REQUEST_ID=<错误中显示的请求编号> playcraft tools build-project --project-id <原项目编号>
+```
+
+恢复不会重新构建。操作尚未完成、结果未知或没有回执时会明确失败；不要换编号或删除记录来强行重试。只有错误明确说明能力检查失败且尚未发送操作时，才可在服务恢复后发起新的正常命令。服务不兼容时命令会在发送业务请求前停止；沙箱命令行与 Business 须排空旧调用后同步升级。
+
 ### 构建相关
 
 | 命令             | 说明                                     | 示例                                                   |
@@ -195,18 +213,18 @@ echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
 
 现已支持 **10 个主流广告平台**：
 
-| 平台              | 格式     | 大小限制                           | SDK/API      |
-| ----------------- | -------- | ---------------------------------- | ------------ |
-| **Facebook**      | HTML/ZIP | HTML: 5MB / ZIP: 5MB（HTML < 2MB） | FbPlayableAd |
-| **Snapchat**      | ZIP      | 5MB                                | MRAID 2.0    |
-| **ironSource**    | HTML     | 5MB                                | MRAID + dapi |
-| **AppLovin**      | HTML     | 5MB                                | MRAID 2.0    |
-| **Google Ads**    | ZIP      | 5MB                                | ExitApi      |
-| **TikTok/Pangle** | ZIP      | 5MB                                | Pangle SDK   |
-| **Unity Ads**     | HTML     | 5MB                                | MRAID 2.0    |
-| **Liftoff**       | ZIP      | 5MB                                | MRAID        |
-| **Moloco**        | HTML     | 5MB                                | FbPlayableAd |
-| **BIGO Ads**      | ZIP      | 5MB                                | BIGO SDK     |
+| 平台              | 格式     | 大小限制             | SDK/API      |
+| ----------------- | -------- | -------------------- | ------------ |
+| **Facebook**      | HTML/ZIP | HTML: 5MB / ZIP: 5MB | FbPlayableAd |
+| **Snapchat**      | ZIP      | 5MB                  | MRAID 2.0    |
+| **ironSource**    | HTML     | 5MB                  | MRAID + dapi |
+| **AppLovin**      | HTML     | 5MB                  | MRAID 2.0    |
+| **Google Ads**    | ZIP      | 5MB                  | ExitApi      |
+| **TikTok/Pangle** | ZIP      | 5MB                  | Pangle SDK   |
+| **Unity Ads**     | HTML     | 5MB                  | MRAID 2.0    |
+| **Liftoff**       | ZIP      | 5MB                  | MRAID        |
+| **Moloco**        | HTML     | 5MB                  | FbPlayableAd |
+| **BIGO Ads**      | ZIP      | 5MB                  | BIGO SDK     |
 
 ## 💡 使用示例
 
@@ -225,8 +243,8 @@ playcraft start --project your-project-id
 ### 打包 Playable Ads
 
 ```bash
-# Facebook 平台（单 HTML）
-playcraft build --platform facebook --format html --output ./dist/facebook
+# Facebook 平台（ZIP，Phaser 产物格式）
+playcraft build --platform facebook --format zip --output ./dist/facebook
 
 # Snapchat 平台（ZIP）
 playcraft build --platform snapchat --format zip --output ./dist/snapchat

package/dist/cli-root-help.js

@@ -7,6 +7,7 @@ export function getCliTopicsHelpText() {
         '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>  |  prefab <子命令>',
         '  平台       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

@@ -33,12 +33,12 @@ const PLATFORM_GROUPS = {
         platforms: [...ALL_PLATFORMS],
     },
     html: {
-        name: '仅 HTML 渠道 (applovin, ironsource, unity, moloco, remerge, adikteev)',
-        platforms: ['applovin', 'ironsource', 'unity', 'moloco', 'remerge', 'adikteev'],
+        name: '仅 HTML 渠道 (applovin, ironsource, unity, moloco, adikteev)',
+        platforms: ['applovin', 'ironsource', 'unity', 'moloco', 'adikteev'],
     },
     zip: {
-        name: '仅 ZIP 渠道 (google, tiktok, liftoff, bigo, snapchat, inmobi, mintegral)',
-        platforms: ['google', 'tiktok', 'liftoff', 'bigo', 'snapchat', 'inmobi', 'mintegral'],
+        name: '仅 ZIP 渠道 (google, tiktok, liftoff, bigo, snapchat, inmobi, mintegral, remerge)',
+        platforms: ['google', 'tiktok', 'liftoff', 'bigo', 'snapchat', 'inmobi', 'mintegral', 'remerge'],
     },
     mainstream: {
         name: '主流渠道 (facebook, google, tiktok, applovin, ironsource, unity)',
@@ -55,7 +55,7 @@ const platformFormatConfig = {
     unity: { formats: ['html'], default: 'html' },
     moloco: { formats: ['html'], default: 'html' },
     adikteev: { formats: ['html', 'zip'], default: 'html', description: 'PlayCanvas/PlayCraft uses HTML, others use ZIP' },
-    remerge: { formats: ['html'], default: 'html' },
+    remerge: { formats: ['zip'], default: 'zip' },
     google: { formats: ['html', 'zip'], default: 'html' },
     tiktok: { formats: ['zip'], default: 'zip' },
     liftoff: { formats: ['zip'], default: 'zip' },
@@ -164,10 +164,11 @@ export async function buildAllCommand(projectPath, options) {
                     name: 'selection',
                     message: '选择要批量构建的渠道:',
                     choices: [
-                        { name: '🌐 全部渠道（13个）', value: 'all' },
-                        { name: '⭐ 主流渠道（facebook, google, tiktok, applovin, ironsource, unity）', value: 'mainstream' },
-                        { name: '📄 仅 HTML 渠道（applovin, ironsource, unity, moloco, remerge）', value: 'html' },
-                        { name: '📦 仅 ZIP 渠道（tiktok, liftoff, bigo, snapchat, inmobi）', value: 'zip' },
+                        { name: `🌐 全部渠道（${ALL_PLATFORMS.length}个）`, value: 'all' },
+                        // 分组文案直接取自 PLATFORM_GROUPS，避免两处渠道清单各写一份导致漂移
+                        { name: `⭐ ${PLATFORM_GROUPS.mainstream.name}`, value: 'mainstream' },
+                        { name: `📄 ${PLATFORM_GROUPS.html.name}`, value: 'html' },
+                        { name: `📦 ${PLATFORM_GROUPS.zip.name}`, value: 'zip' },
                         { name: '🔧 自定义选择', value: 'custom' },
                     ],
                 },

package/dist/commands/build.js

@@ -466,21 +466,20 @@ export async function buildCommand(projectPath, options) {
             'mintegral',
         ];
         // 渠道输出格式配置（根据各渠道Playable规格对照表）
-        // 只支持 HTML: applovin, ironsource, unity, moloco, adikteev, remerge
-        // 只支持 ZIP: bigo, snapchat
-        // 支持两种: facebook, google, tiktok, liftoff, inmobi, mintegral
+        // 单格式（ZIP）: bigo, snapchat, remerge
+        // 单格式（HTML）: applovin, ironsource, unity, moloco
+        // 双格式: facebook, google, tiktok, liftoff, inmobi, mintegral
+        // adikteev: 由引擎决定（PlayCanvas/PlayCraft 用 HTML，其他引擎用 ZIP）
+        // 注：Facebook 在 Phaser（playable-scripts devkit）下的产物格式由其 devkit 输入配置决定（恒为 ZIP），
+        //     平台侧不在此处做引擎判断。
         const platformFormatConfig = {
-            facebook: {
-                formats: ['html', 'zip'],
-                default: 'html',
-                description: 'Facebook 支持两种格式'
-            },
+            facebook: { formats: ['html', 'zip'], default: 'html' },
             applovin: { formats: ['html'], default: 'html' },
             ironsource: { formats: ['html'], default: 'html' },
             unity: { formats: ['html'], default: 'html' },
             moloco: { formats: ['html'], default: 'html' },
             adikteev: { formats: ['html', 'zip'], default: 'html', description: 'PlayCanvas/PlayCraft uses HTML, others use ZIP' },
-            remerge: { formats: ['html'], default: 'html' },
+            remerge: { formats: ['zip'], default: 'zip' },
             google: {
                 formats: ['html', 'zip'],
                 default: 'html',
@@ -532,9 +531,11 @@ export async function buildCommand(projectPath, options) {
                                 ? (selectedPlatform === 'facebook' || selectedPlatform === 'google'
                                     ? 'HTML（单文件，最大 5MB，所有资源内联）'
                                     : 'HTML（单文件）')
-                                : (selectedPlatform === 'facebook' || selectedPlatform === 'google'
-                                    ? 'ZIP（多文件，最大 5MB，HTML 文件需 < 2MB）'
-                                    : 'ZIP（多文件）'),
+                                : (selectedPlatform === 'google'
+                                    ? 'ZIP（多文件，最大 5MB，ZIP 内文件数 ≤ 512）'
+                                    : selectedPlatform === 'facebook'
+                                        ? 'ZIP（多文件，最大 5MB）'
+                                        : 'ZIP（多文件）'),
                             value: f,
                         })),
                         default: formatConfig.default,

package/dist/commands/create.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import { execFileSync, execSync } from 'child_process';
 import inquirer from 'inquirer';
 import fs from 'fs/promises';
@@ -6,8 +7,11 @@ import { fileURLToPath } from 'url';
 import pc from 'picocolors';
 import ora from 'ora';
 import { resolveCreateTemplate, resolveCreateTemplateDir, } from '../scaffold/templates.js';
+import { PLATFORM_SKILL_DIRS } from './platform-skills.generated.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/** `@playcraft/skills` 包内 Platform Skill 的目录名（与 Atom Skill 的 `skills/` 区分）。 */
+const PLATFORM_SKILLS_DIRNAME = 'playcraft-skills';
 /** 生成一个本地占位 Project ID（99xxxxxx），后续可通过 playcraft config set 更新为真实 ID */
 function generateMockProjectId() {
     const suffix = Math.floor(Math.random() * 90_000_000) + 10_000_000;
@@ -849,7 +853,7 @@ function extractSkillBodyForCursor(content) {
  * @param cliCommandsDir CLI 命令所在目录（用于解析 skills 包位置）
  * @param configDir 配置目录名（如 '.claude' 或 '.codebuddy'）
  */
-async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir) {
+export async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir) {
     const skillsLinkDir = path.join(targetDir, configDir, 'skills');
     await fs.mkdir(skillsLinkDir, { recursive: true });
     // 以下 Skill 在项目模板中以静态目录形式存在，不创建软连接覆盖它们。
@@ -868,11 +872,12 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
         'playcraft-image-generation',
         'playcraft-audio-generation',
     ]);
-    // 尝试从 CLI 安装包的位置定位 @playcraft/skills/skills 目录
+    // Platform Skill 住在 playcraft-skills/，与 Atom Skill 的 skills/ 是两个目录。
+    // 尝试从 CLI 安装包的位置定位它（monorepo 内或与 CLI 平级安装时可解析）。
     const candidateDirs = [
-        path.resolve(cliCommandsDir, '..', '..', '..', '..', 'skills', 'skills'),
-        path.resolve(cliCommandsDir, '..', '..', '..', 'skills', 'skills'),
-        path.resolve(cliCommandsDir, '..', '..', 'skills', 'skills'),
+        path.resolve(cliCommandsDir, '..', '..', '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
+        path.resolve(cliCommandsDir, '..', '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
+        path.resolve(cliCommandsDir, '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
     ];
     let resolvedSkillsDir = null;
     for (const dir of candidateDirs) {
@@ -885,18 +890,24 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
             // 继续下一个候选
         }
     }
-    // 相对路径（指向 npm install 后的 node_modules）始终创建，作为安装后激活的备用
-    const relativeSkillsBase = path.join('..', '..', 'node_modules', '@playcraft', 'skills', 'skills');
+    // 相对路径（指向 npm install 后的 node_modules）作为安装后激活的备用
+    const relativeSkillsBase = path.join('..', '..', 'node_modules', '@playcraft', 'skills', PLATFORM_SKILLS_DIRNAME);
     if (resolvedSkillsDir) {
-        // 能立即解析 → 创建指向绝对路径的软连接，当下即可使用
+        // 能立即解析 → 以真实目录为准创建绝对路径软连接，当下即可使用。
+        // 按「是否含 SKILL.md」判定而非 playcraft- 前缀：sound-effects 无前缀但同样是平台技能。
         const entries = await fs.readdir(resolvedSkillsDir, { withFileTypes: true });
         for (const entry of entries) {
-            if (!entry.name.startsWith('playcraft-') || staticSkills.has(entry.name))
+            if (!entry.isDirectory() || staticSkills.has(entry.name))
                 continue;
-            const linkPath = path.join(skillsLinkDir, entry.name);
             const targetPath = path.join(resolvedSkillsDir, entry.name);
             try {
-                await fs.symlink(targetPath, linkPath, 'dir');
+                await fs.access(path.join(targetPath, 'SKILL.md'));
+            }
+            catch {
+                continue;
+            }
+            try {
+                await fs.symlink(targetPath, path.join(skillsLinkDir, entry.name), 'dir');
             }
             catch {
                 // 已存在则跳过
@@ -904,28 +915,9 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
         }
     }
     else {
-        // 无法立即解析 → 创建指向 node_modules 的相对路径软连接，npm install 后自动激活
-        const knownPlatformTools = [
-            'playcraft-asset-management',
-            'playcraft-audio-generation',
-            'playcraft-build',
-            'playcraft-code-editor',
-            'playcraft-create-remix',
-            'playcraft-deploy',
-            'playcraft-image-generation',
-            'playcraft-image-processing',
-            'playcraft-platform-intro',
-            'playcraft-prefab',
-            'playcraft-project-management',
-            'playcraft-remix-workflow',
-            'playcraft-save',
-            'playcraft-skill-recommender',
-            'playcraft-sprite-generation',
-            'playcraft-sprite-remix',
-            'playcraft-sprite-sheet',
-            'playcraft-3d-flip-sprite',
-        ];
-        for (const name of knownPlatformTools) {
+        // 无法立即解析 → 指向 node_modules 的相对路径软连接，npm install 后自动激活。
+        // 清单由 scripts/generate-platform-skills.mjs 从真实目录生成并由 CI 校验，不要手写。
+        for (const name of PLATFORM_SKILL_DIRS) {
             if (staticSkills.has(name))
                 continue;
             const linkPath = path.join(skillsLinkDir, name);
@@ -1289,6 +1281,7 @@ export async function createCommand(projectName, options) {
                 smokeSpinner.warn(`Harness 自检跳过: ${message}`);
             }
         }
+        await prepareLocalSkillLifecycle(targetDir, 'create');
         const gitSpinner = ora(isWorktreeMode ? '提交项目分支...' : '初始化 Git 仓库...').start();
         try {
             if (isWorktreeMode) {

package/dist/commands/platform-skills.generated.js

@@ -0,0 +1,19 @@
+// 此文件由 scripts/generate-platform-skills.mjs 生成，请勿手改。
+// 重新生成：pnpm --filter @playcraft/cli generate:platform-skills
+/** `@playcraft/skills/playcraft-skills/` 下的 Platform Skill 目录名。 */
+export const PLATFORM_SKILL_DIRS = [
+    'playcraft-3d-flip-sprite',
+    'playcraft-asset-management',
+    'playcraft-build',
+    'playcraft-code-editor',
+    'playcraft-create-remix',
+    'playcraft-deploy',
+    'playcraft-iteration-methodology',
+    'playcraft-platform-intro',
+    'playcraft-prefab',
+    'playcraft-project-management',
+    'playcraft-remix-workflow',
+    'playcraft-save',
+    'playcraft-template-upgrade-merge',
+    'sound-effects',
+];

package/dist/commands/skills.js

@@ -18,6 +18,7 @@
  *   3. <cwd>/node_modules/@playcraft/skills/playcraft-skills（兼容旧路径 skills）
  *   4. <CLI 自身>/../../skills/playcraft-skills（monorepo 开发时，兼容旧路径 skills）
  */
+import { registerProjectSkillsCommands } from '../project-skills/commands.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getFusionHintsForGameplayAtoms, } from '../atom-tree/fusion-hints.js';
@@ -1430,6 +1431,7 @@ export function registerSkillsCommands(program) {
     const skills = program
         .command('skills')
         .description('开发时 Skill 发现与脚手架工具（按 engine/intent 推荐 skill 集合，或将 ref 文件复制到项目）');
+    registerProjectSkillsCommands(skills);
     // 公共选项：skills 目录
     const addSkillsDirOption = (cmd) => cmd.option('--skills-dir <path>', '指定 skills 目录路径（默认自动发现）');
     // ── list ──────────────────────────────────────────────────────────────────

package/dist/commands/tools-generation.js

@@ -125,7 +125,7 @@ export function registerGenerationCommands(tools) {
             }
             console.log('');
             console.log('提示：传入模型名（如 gpt-image-2），后端按优先级依次 fallback 各 provider（gpt-image-2：iegg-litellm → mulerouter → 302）。');
-            console.log('      也可传入 provider/model（如 mulerouter/gpt-image-2）直连指定 provider。');
+            console.log('      也可传入 provider/model（如 mulerouter/gpt-image-2、gamepilot/dreamina/dola-seedream-5-0-pro-260628）直连指定 provider。');
             console.log('');
             console.log('CAPABILITY 说明:');
             console.log('  text→image  仅支持文生图（不可传 --reference-image）');

package/dist/commands/workspace-runtime.js

@@ -0,0 +1,54 @@
+import { readFile } from 'node:fs/promises';
+import { INCOMPATIBLE_EXIT_CODE, parseSandboxRuntimeConfig, } from '@playcraft/common/cloud-workspace/runtime';
+import { startWorkspaceRuntime } from '../workspace-runtime/serve.js';
+export async function runWorkspaceRuntimeServe(configPath) {
+    process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
+    let config;
+    try {
+        config = parseSandboxRuntimeConfig(JSON.parse(await readFile(configPath, 'utf8')));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`workspace-runtime config invalid: ${message}`);
+        process.exitCode = INCOMPATIBLE_EXIT_CODE;
+        return;
+    }
+    try {
+        const runtime = await startWorkspaceRuntime(config);
+        console.log(JSON.stringify({
+            status: 'listening',
+            url: runtime.url,
+            phase: 'awaiting_native',
+            protocolMajor: runtime.config.protocolMajor,
+            protocolMinor: runtime.config.protocolMinor,
+        }));
+        await new Promise((resolve) => {
+            const stop = () => {
+                void runtime.close().finally(resolve);
+            };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'protocol_incompatible' || code === 'duplicate_instance') {
+            console.error(error instanceof Error ? error.message : code);
+            process.exitCode = INCOMPATIBLE_EXIT_CODE;
+            return;
+        }
+        throw error;
+    }
+}
+export function registerWorkspaceRuntimeCommands(program) {
+    const workspaceRuntime = program
+        .command('workspace-runtime')
+        .description('沙箱内 Sandbox Agent Server（Cloud Workspace 常驻运行入口）');
+    workspaceRuntime
+        .command('serve')
+        .description('前台常驻：读取 Runtime Server 下发的配置，不启动本地 backend 或旧同步')
+        .requiredOption('--config <path>', 'Runtime 引导配置 JSON')
+        .action(async (options) => {
+        await runWorkspaceRuntimeServe(options.config);
+    });
+}

package/dist/index.js

@@ -27,6 +27,7 @@ import { registerLevelsCommands } from './commands/levels.js';
 import { registerPatternsCommands } from './commands/patterns.js';
 import { registerPradCommands } from './commands/prad.js';
 import { register3DCommands } from './commands/3d.js';
+import { registerWorkspaceRuntimeCommands } from './commands/workspace-runtime.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -36,7 +37,7 @@ program.name('playcraft').description(CLI_ROOT_DESCRIPTION).version(packageJson.
 registerRootProgramHelp(program);
 // 版本检查（非阻塞，后台执行）
 // 只在非 upgrade 命令时检查，避免重复提示
-if (!process.argv.includes('upgrade')) {
+if (!process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
     checkForUpdates(packageJson);
 }
 // create 命令
@@ -368,4 +369,5 @@ registerPatternsCommands(program);
 registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
+registerWorkspaceRuntimeCommands(program);
 program.parse(process.argv);

package/dist/project-skills/commands.js

@@ -0,0 +1,72 @@
+import { verifyLocalProjectSkills } from './validation.js';
+export { verifyLocalProjectSkills } from './validation.js';
+import { downloadLocalProjectSkillArtifacts } from './remote-cache.js';
+import { resolve } from 'node:path';
+import { inspectProjectSkills, } from '@playcraft/common/project-skills';
+import { syncLocalProjectSkills, enableLocalProjectSkill, installFrozenProjectSkills, explainLocalProjectSkills } from './local-store.js';
+import { runLocalProjectSkills, localProjectSkillUsage } from './local-run.js';
+import { projectSkillsMessage as t } from './messages.js';
+import { reconcileLocalProjectSkills } from './reconcile.js';
+export async function inspectLocalProjectSkills(directory) {
+    const inventory = await inspectProjectSkills(directory);
+    // Report metadata only; never print complete skill bytes or project test data.
+    return { declaration: inventory.declaration, discovered: inventory.discovered, issues: inventory.issues,
+        sources: inventory.sources.map((source) => ({ entryKey: source.entryKey, root: source.root,
+            sourceTreeHash: source.sourceTreeHash, files: source.files.map((file) => file.path) })) };
+}
+export function registerProjectSkillsCommands(skills) {
+    const project = skills.command('project').description(t('description'));
+    const output = async (action) => {
+        try {
+            process.stdout.write(`${JSON.stringify(await action(), null, 2)}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    };
+    project.command('run <prompt>').description(t('run')).requiredOption('--model <provider/model>', t('model'))
+        .option('--dir <path>', t('directory'), '.').action((prompt, options) => output(async () => {
+        const result = await runLocalProjectSkills(resolve(options.dir), { prompt, model: options.model });
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+        return result;
+    }));
+    project.command('usage').description(t('usage')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => localProjectSkillUsage(resolve(options.dir))));
+    project.command('sync').description(t('sync')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => syncLocalProjectSkills(resolve(options.dir))));
+    project.command('reconcile').description(t('reconcile')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => reconcileLocalProjectSkills(resolve(options.dir), { write: true })));
+    project.command('install').description(t('install')).requiredOption('--frozen', t('frozen')).option('--dir <path>', t('directory'), '.')
+        .option('--online', t('online')).action((options) => output(async () => {
+        const directory = resolve(options.dir);
+        if (options.online)
+            await downloadLocalProjectSkillArtifacts(directory);
+        return installFrozenProjectSkills(directory);
+    }));
+    for (const enabled of [true, false])
+        project.command(enabled ? 'enable <entryKey>' : 'disable <entryKey>')
+            .description(t(enabled ? 'enable' : 'disable')).option('--dir <path>', t('directory'), '.')
+            .action((entryKey, options) => output(() => enableLocalProjectSkill(resolve(options.dir), entryKey, enabled)));
+    project.command('explain').description(t('explain')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => explainLocalProjectSkills(resolve(options.dir))));
+    project.command('inspect').description(t('inspect')).option('--dir <path>', t('directory'), '.')
+        .action(async (options) => {
+        const result = await inspectLocalProjectSkills(resolve(options.dir));
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (result.issues.length)
+            process.exitCode = 1;
+    });
+    project.command('verify').description(t('verify')).option('--dir <path>', t('directory'), '.')
+        .option('--json', t('json')).action(async (options) => {
+        try {
+            const result = await verifyLocalProjectSkills(resolve(options.dir));
+            process.stdout.write(`${options.json ? JSON.stringify(result) : t('verified')}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/project-skills/lifecycle.js

@@ -0,0 +1,28 @@
+import { spawnSync } from 'node:child_process';
+import { readProjectSkillsLockFile } from '@playcraft/common/project-skills';
+import { syncLocalProjectSkills, readLocalProjectSkillSnapshot, installFrozenProjectSkills } from './local-store.js';
+import { verifyLocalProjectSkills } from './validation.js';
+import { projectSkillsMessage as t } from './messages.js';
+/** Existing formats keep their legacy consumer; format 3 never silently downgrades. */
+export async function prepareLocalSkillLifecycle(directory, action, cache) {
+    const raw = await readProjectSkillsLockFile(directory);
+    const managed = raw !== null && JSON.parse(raw).lockVersion === 3;
+    if (!managed && process.env.PROJECT_SKILLS_ADOPTION_ENABLED !== 'true')
+        return { managed: false };
+    if (raw !== null && !managed)
+        return { managed: false, legacy: true };
+    if (action === 'create' || action === 'push' || !managed)
+        await syncLocalProjectSkills(directory, cache);
+    await verifyLocalProjectSkills(directory);
+    const snapshot = await readLocalProjectSkillSnapshot(directory);
+    if (action === 'push') {
+        const paths = ['.playcraft/skills.json', '.playcraft/skills.lock.json', ...snapshot.declaration.entries.flatMap(entry => entry.source.kind === 'repository' ? [entry.source.root, ...(entry.projectFiles ?? [])] : [])];
+        const status = spawnSync('git', ['status', '--porcelain', '--', ...paths], { cwd: directory, encoding: 'utf8' });
+        if (status.status !== 0 || status.stdout.trim())
+            throw new Error(t('commitRequired'));
+    }
+    // Source-only checkouts work offline. Registry packages remain exact and require an authorized cache fill.
+    if (!snapshot.lock.entries.some(entry => entry.revision.kind === 'release'))
+        await installFrozenProjectSkills(directory, cache);
+    return { managed: true, declarationHash: snapshot.lock.declarationHash };
+}