@playcraft/cli 0.1.24 → 0.1.26

package/README.md

@@ -7,11 +7,11 @@
 
 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)。
 
 ## ✨ 特性
 
@@ -141,6 +141,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 +199,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/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.js

@@ -450,6 +450,7 @@ export async function buildCommand(projectPath, options) {
         const shouldRunPlayableOnly = options.mode === 'playable';
         // 验证平台
         const validPlatforms = [
+            'playcraft',
             'facebook',
             'snapchat',
             'ironsource',
@@ -473,6 +474,7 @@ export async function buildCommand(projectPath, options) {
         // 注：Facebook 在 Phaser（playable-scripts devkit）下的产物格式由其 devkit 输入配置决定（恒为 ZIP），
         //     平台侧不在此处做引擎判断。
         const platformFormatConfig = {
+            playcraft: { formats: ['html'], default: 'html' },
             facebook: { formats: ['html', 'zip'], default: 'html' },
             applovin: { formats: ['html'], default: 'html' },
             ironsource: { formats: ['html'], default: 'html' },
@@ -584,8 +586,11 @@ export async function buildCommand(projectPath, options) {
                     console.log(pc.dim('   无主题目录，跳过主题选择'));
                 }
             }
-            // 输入商店跳转地址（CTA）- 如果配置文件中没有则必填
-            if (!options.storeUrls) {
+            // 输入商店跳转地址（CTA）- 如果配置文件中没有则必填；通用预览（playcraft）不面向渠道，可不填
+            if (selectedPlatform === 'playcraft' && !options.storeUrls) {
+                console.log(pc.dim('\nℹ️  通用预览不需要商店地址'));
+            }
+            else if (!options.storeUrls) {
                 console.log(pc.cyan('\n🔗 商店跳转地址（CTA 按钮目标）'));
                 console.log(pc.dim('   iOS 和 Android 地址均为必填'));
                 const storeUrlAnswer = await inquirer.prompt([
@@ -636,8 +641,8 @@ export async function buildCommand(projectPath, options) {
                 // 未指定格式，使用默认值
                 options.format = formatConfig.default;
             }
-            // 如果命令行未传入 storeUrls，交互式输入（必填）
-            if (!options.storeUrls) {
+            // 如果命令行未传入 storeUrls，交互式输入（必填）；通用预览（playcraft）不面向渠道，可不填
+            if (!options.storeUrls && options.platform !== 'playcraft') {
                 spinner.stop();
                 console.log(pc.cyan('\n🔗 商店跳转地址（CTA 按钮目标）'));
                 console.log(pc.dim('   iOS 和 Android 地址均为必填'));

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/image.js

@@ -677,9 +677,7 @@ async function runBatchStep(cmd, args, inputPath, outputPath) {
             const meta = await sharp(inputPath).metadata();
             const targetW = scale ? Math.round((meta.width ?? 64) * scale) : w;
             const targetH = scale ? Math.round((meta.height ?? 64) * scale) : h;
-            await safeToFile(sharp(inputPath).resize(targetW, targetH, {
-                fit, background: { r: 0, g: 0, b: 0, alpha: 0 },
-            }), outputPath, inputPath);
+            await safeToFile(sharp(inputPath).resize(targetW, targetH, { fit }), outputPath, inputPath);
             break;
         }
         case 'crop': {
@@ -838,9 +836,7 @@ export function registerImageCommands(program) {
                 process.exit(1);
             }
             const fit = parseResizeFitOption(opts.fit);
-            await safeToFile(sharp(opts.input).resize(targetW, targetH, {
-                fit, background: { r: 0, g: 0, b: 0, alpha: 0 },
-            }), opts.output, opts.input);
+            await safeToFile(sharp(opts.input).resize(targetW, targetH, { fit }), opts.output, opts.input);
             const outSz = statSync(resolveSandboxPath(opts.output)).size;
             console.log(`Resized ${w}x${h} → ${targetW ?? '?'}x${targetH ?? '?'} — ${opts.output} (${sizeLabelBytes(outSz)})`);
         }