@lark-apaas/miaoda-cli 0.1.35 → 0.1.37

package/README.md

@@ -48,9 +48,32 @@ miaoda file ls --output json
 | `miaoda observability ...` | 线上日志、链路、前端源码堆栈反查、监控指标、运营指标 |
 | `miaoda comment ...`       | 应用评论：查看评论列表、解决评论（仅 design-html 场景开放）        |
 | `miaoda registry ...`      | 组件 registry：列出 / copy-in SDK 文件（本地执行）                 |
+| `miaoda app ...`           | 应用生命周期：元数据、初始化、平台同步、源码导出、静态产物导出     |
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 打包可本地访问的静态产物
+
+`miaoda app pack`（默认 `--mode standalone`）把当前应用构建成一份自包含静态产物，可脱离妙搭平台本地打开。
+
+```bash
+miaoda app pack                    # → dist/standalone.zip（中间目录打完即删）
+miaoda app pack --out dist/share
+miaoda app pack --json
+miaoda app pack --upload-url 'https://tos.example.com/x.zip?sign=...'
+```
+
+支持 `design-html` / `html` / `vite-react` / `nestjs-react-fullstack`。页面与代码里字面以
+`/spark/app` 开头的存储图片会经沙箱网关（localhost:8080）下载到 `images/` 并改写成相对路径。
+
+默认输出落在 `dist/` 下是刻意的：`dist` 已在部署扫描的 EXCLUDES 与各模板 `.gitignore` 中，
+产物不会污染部署包、不会被误提交；代价是下一次构建会清掉它。
+
+**只保证纯静态可看** —— 接口调用会失败，不做数据快照。多路由 SPA 在 `file://` 下不可用
+（`BrowserRouter` 匹配不上路径），需用本地 HTTP server 打开，命令会在 `warnings` 里提示。
+
+> 与 `miaoda app export` **语义无关**：后者拉的是**其他应用**的源码归档（创意应用升级链路的只读参考物）。
+
 ## 组件 registry
 
 `miaoda registry` 提供 shadcn 式的「组件 registry」：把 SDK 文件**拷进**当前项目（copy-in），而非作为依赖安装。registry 是独立 npm 包，按运行时分发（design-html / html → buildless runtime → `@lark-apaas/coding-registry-buildless`）。

package/dist/cli/commands/app/index.js

@@ -22,6 +22,7 @@ function registerAppCommands(program, opts = {}) {
     registerAppGet(appCmd);
     registerAppUpdate(appCmd);
     registerAppExport(appCmd);
+    registerAppPack(appCmd);
     if (opts.includeInit) {
         registerAppInit(appCmd);
         registerAppSync(appCmd);
@@ -127,6 +128,10 @@ function registerAppExport(parent) {
         .option('--out <dir>', '输出目录（相对当前目录）', 'source_package/creative')
         .option('--checkpoint <n>', '按检查点版本导出；缺省为最新提交（HEAD）')
         .addHelpText('after', `
+与 'miaoda app pack' 的区别（**两个命令语义无关，别选错**）
+  app export             拉「其他应用」的源码归档（本命令）
+  app pack               把「当前应用」打包成产物（默认 standalone 形态）
+
 说明
   从服务端导出源应用（可以不是当前应用）的源码归档并解压到 --out 目录，导出完成后写
   --out/.upgrade-manifest.json（含 sourceAppId / 导出时间 / 文件数），供升级链路幂等
@@ -173,6 +178,82 @@ JSON 输出
         });
     }));
 }
+function registerAppPack(parent) {
+    const cmd = parent
+        .command('pack')
+        .description('打包应用产物。默认 standalone 模式：自包含静态产物（目录 + zip），可脱离妙搭平台本地访问')
+        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .option('--mode <mode>', `打包形态（${index_1.PACK_MODES.join(' / ')}）`, index_1.DEFAULT_PACK_MODE)
+        .option('--out <dir>', '产物路径（相对项目根），实际产出 <out>.zip', index_1.DEFAULT_PACK_OUT)
+        .option('--upload-url <url>', '打包后把 zip 以 PUT 上传到该预签名 URL（http/https）；上传成功后清掉本地产物')
+        .addHelpText('after', `
+与 'miaoda app export' 的区别（**两个命令语义无关，别选错**）
+  app export   拉「其他应用」的源码归档（创意应用升级链路的只读参考物）
+  app pack     把「当前应用」打包成产物（本命令）
+
+打包形态（--mode）
+  standalone（默认）  自包含静态产物，可脱离妙搭平台本地访问
+  后续新增形态时在此列出；不传 --mode 的行为永远等同 standalone。
+
+支持的 stack
+  design-html / html / vite-react / nestjs-react-fullstack
+
+产物
+  <out>.zip       **唯一交付物**。内含 index.html + assets/ + images/
+                  （+ static/，vite 系有 shared/static 时）
+  <out>/          打包用的中间目录，**打完包即删除**——它与 zip 内容重复，
+                  留着占双份磁盘。要预览请先解压。
+  传了 --upload-url 时，zip 会以 PUT 裸 body（Content-Type: application/zip）
+  上传到该地址——预签名 URL 的标准形态，鉴权由 URL 自带签名承担，不加额外 header。
+  **上传成功后本地 zip 也会被清掉**（目录本就已删），交付物以远端为准，
+  JSON 里 localRemoved=true。上传失败则保留 zip，便于修正后重跑或手动上传。
+  默认 <out> 是 dist/standalone —— 落在 dist/ 下是刻意的：dist 已在部署扫描的
+  EXCLUDES 与各模板 .gitignore 中，产物不会污染部署包、不会被误提交。
+  代价：下一次构建会 rm -rf dist，导出产物是易失的。
+
+图片本地化
+  只处理页面/代码里字面以 /spark/app 开头的 URL，经沙箱网关（localhost:8080）下载到
+  <out>/images/ 并改写成相对路径。其它挂载前缀（/spark/p/、/app/<id>、反代）不处理。
+  接口运行时返回的 download_url 属动态 URL，静态扫描覆盖不到。
+
+已知限制
+  只保证纯静态可看——接口调用会失败，不做数据快照。
+  多路由 SPA 在 file:// 下不可用（BrowserRouter 匹配不上路径、pushState 抛 SecurityError），
+  请用本地 HTTP server 打开；检测到时会在 warnings 里给 SPA_ROUTER_FILE_PROTOCOL。
+  design-html 的 cd-elements SDK 是 CDN 外链，断网打开自定义元素不渲染。
+
+JSON 输出
+  {"data": {"appId": "...", "stack": "...", "out": "dist/standalone", "zip": "dist/standalone.zip",
+            "fileCount": N, "bytes": N,
+            "images": {"matched": N, "downloaded": N, "failed": [{"url": "...", "reason": "..."}]},
+            "localRemoved": false,
+            "rewrittenFiles": [...],
+            "warnings": [{"code": "...", "message": "..."}]}}
+
+失败
+  单张图片下载失败 → 跳过并计入 images.failed + warnings，退出码 0。
+  命中 > 0 但全部失败 → PACK_IMAGE_ALL_FAILED，退出码 1（系统性问题）。
+  stack 不支持 → PACK_STACK_UNSUPPORTED。
+  构建失败 → PACK_BUILD_FAILED。
+  上传失败（非 2xx / 网络异常）→ PACK_UPLOAD_FAILED，退出码 1。
+    本地产物保留，可修正 URL 后重跑或手动上传。
+  --upload-url 非 http/https → ARGS_INVALID，退出码 2。
+
+示例
+  $ miaoda app pack
+  $ miaoda app pack --out dist/share
+  $ miaoda app pack --json
+  $ miaoda app pack --upload-url 'https://tos.example.com/x.zip?sign=...'
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleAppPack)({
+            dir: rawOpts.dir,
+            out: rawOpts.out,
+            uploadUrl: rawOpts.uploadUrl,
+            mode: rawOpts.mode,
+        });
+    }));
+}
 function registerAppGet(parent) {
     const cmd = parent
         .command('get')

package/dist/cli/handlers/app/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = exports.handleAppExport = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.PACK_MODES = exports.DEFAULT_PACK_MODE = exports.DEFAULT_PACK_OUT = exports.handleAppPack = exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = exports.handleAppExport = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
@@ -19,3 +19,8 @@ Object.defineProperty(exports, "handleAppMigrate", { enumerable: true, get: func
 // commands 层渲染 help 时需要这份枚举；从 handler barrel 转发，避免 commands → services 越界
 var index_1 = require("../../../services/app/init/index");
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return index_1.SUPPORTED_STACKS; } });
+var pack_1 = require("./pack");
+Object.defineProperty(exports, "handleAppPack", { enumerable: true, get: function () { return pack_1.handleAppPack; } });
+Object.defineProperty(exports, "DEFAULT_PACK_OUT", { enumerable: true, get: function () { return pack_1.DEFAULT_PACK_OUT; } });
+Object.defineProperty(exports, "DEFAULT_PACK_MODE", { enumerable: true, get: function () { return pack_1.DEFAULT_PACK_MODE; } });
+Object.defineProperty(exports, "PACK_MODES", { enumerable: true, get: function () { return pack_1.PACK_MODES; } });

package/dist/cli/handlers/app/init.js

@@ -7,6 +7,7 @@ exports.handleAppInit = handleAppInit;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../../../services/app/init/index");
+const dir_lock_1 = require("../../../utils/dir-lock");
 const coding_steering_1 = require("../../../utils/coding-steering");
 const logger_1 = require("../../../utils/logger");
 const githooks_1 = require("../../../utils/githooks");
@@ -86,16 +87,23 @@ async function handleAppInit(opts) {
         version: 'unknown',
         syncedSkills: [],
         techSynced: false,
+        prunedStacks: [],
     };
     let steeringError;
     if (scaffoldSteering) {
         try {
-            steeringResult = (0, coding_steering_1.syncCodingSteering)({
+            // 与会话期的 `skills sync` 互斥：两者都写 `.agent/skills`，而写入策略是按目录
+            // 整清再拷。线上实测过这条竞态 —— init 的 steering 同步撞上 sync 收尾的
+            // `chmod -R a=rX`，报 `EACCES: mkdir '.agent/skills/steering/<stack>/skills'`。
+            steeringResult = (0, dir_lock_1.withDirLock)(targetDir, () => (0, coding_steering_1.syncCodingSteering)({
                 stack,
                 targetDir,
                 logPrefix: 'init',
                 outputLayout,
-            });
+                // match-template-version 门禁的比对基准：用刚渲染的 template 实际版本，
+                // 与随后写入 .spark/meta.json 的 version 同源（见下方 writeSparkMeta）
+                templateVersion: tplResult.version,
+            }));
         }
         catch (err) {
             steeringError = err instanceof Error ? err.message : String(err);

package/dist/cli/handlers/app/migrate.js

@@ -144,12 +144,10 @@ async function handleAppMigrate(opts) {
     // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
     // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
     //
-    //   - 只在 SANDBOX_ID 非空时做(本地一般不会撞这条链路)
+    //   - 只在沙箱内做(isSandboxEnv;本地一般不会撞这条链路)
     //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
     //   - 软失败:.vite 不存在 / 删失败都不阻断
-    if (installError === undefined &&
-        process.env.SANDBOX_ID !== undefined &&
-        process.env.SANDBOX_ID !== '') {
+    if (installError === undefined && (0, env_1.isSandboxEnv)()) {
         const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
         if (node_fs_1.default.existsSync(viteCacheDir)) {
             (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');

package/dist/cli/handlers/app/pack.js

@@ -0,0 +1,256 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PACK_OUT = exports.DEFAULT_PACK_MODE = exports.PACK_MODES = void 0;
+exports.handleAppPack = handleAppPack;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const exclude_patterns_1 = require("../../../utils/exclude-patterns");
+const spark_meta_1 = require("../../../utils/spark-meta");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const logger_1 = require("../../../utils/logger");
+const index_1 = require("../../../services/app/pack/index");
+/**
+ * 支持的打包形态。当前只有 `standalone`；留成枚举是为了让扩展点显式可见 ——
+ * 新增形态时只需往这里加，命令 help 会自动列出。
+ *
+ * ⚠️ 不传 `--mode` 的行为永远等同 `standalone`，这是对调用方的稳定契约：
+ * 将来加了新形态也不能改默认值，否则存量调用会静默换语义。
+ */
+exports.PACK_MODES = ['standalone'];
+exports.DEFAULT_PACK_MODE = 'standalone';
+/** standalone 形态的默认输出目录。新增形态时各自用自己的目录名。 */
+exports.DEFAULT_PACK_OUT = 'dist/standalone';
+/** 校验相对输出路径：禁绝对路径、禁含 ".." 段（与 app export 的 normalizeOutDir 同口径）。 */
+function normalizeOutDir(rel) {
+    if (node_path_1.default.isAbsolute(rel) || rel.startsWith('/')) {
+        throw new error_1.AppError('ARGS_INVALID', `输出目录不能是绝对路径：${rel}`);
+    }
+    const posix = rel.split(node_path_1.default.sep).join('/').replace(/^\.\//, '');
+    if (posix.split('/').includes('..')) {
+        throw new error_1.AppError('ARGS_INVALID', `输出目录不能包含 "..":${rel}`);
+    }
+    return posix;
+}
+/** 沙箱网关地址：它才是代理 `/spark/app` 的那个服务（响应头 `Server: openresty`）。 */
+const SANDBOX_GATEWAY_BASE = 'http://localhost:8080';
+/** 遍历产物树里的文本文件，返回 posix 相对路径。 */
+function* walkText(dir, rel = '') {
+    for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+        const abs = node_path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* walkText(abs, childRel);
+        else if (index_1.TEXT_EXTENSIONS.has(node_path_1.default.extname(entry.name).toLowerCase()))
+            yield childRel;
+    }
+}
+/** 统计产物树的文件数与总字节数。 */
+function measure(dir) {
+    let fileCount = 0;
+    let bytes = 0;
+    const walk = (cur) => {
+        for (const entry of node_fs_1.default.readdirSync(cur, { withFileTypes: true })) {
+            const abs = node_path_1.default.join(cur, entry.name);
+            if (entry.isDirectory())
+                walk(abs);
+            else {
+                fileCount += 1;
+                bytes += node_fs_1.default.statSync(abs).size;
+            }
+        }
+    };
+    walk(dir);
+    return { fileCount, bytes };
+}
+/**
+ * 扫**项目源码**里是否用了 BrowserRouter。
+ *
+ * preset 在 standalone 下会把它编译期换成 HashRouter（`standaloneRouterPlugin`），
+ * 换完 file:// 下路由完全可用。这里保留检测是为了**覆盖不到时给提示**：插件只替换
+ * 用户源码里字面的 `BrowserRouter` / `createBrowserRouter`，碰不到的情况有——
+ * 用户二次封装（`export const Router = BrowserRouter`）、非 react-router 的路由库、
+ * 代码里硬编码 `window.location.href = '/about'`。
+ *
+ * 命中时只是提示"若路由异常请用本地 server"，不代表一定坏。
+ *
+ * ⚠️ **必须扫源码，不能扫产物**：编译型 stack 的产物经过 minify，`BrowserRouter`
+ * 这个标识符会被改名，扫产物永远命中不了 —— 而那恰恰是最需要这条警告的场景。
+ * 真机踩过：vite-react 应用源码里明明有 BrowserRouter、产物首屏渲染成 404，
+ * 但因为扫的是产物，warnings 是空的。
+ *
+ * 扫描面套 EXCLUDES（跳过 node_modules / dist 等），四个 stack 统一按项目根扫。
+ */
+function detectBrowserRouter(projectDir) {
+    const walk = (dir) => {
+        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            if (exclude_patterns_1.EXCLUDES.has(entry.name))
+                continue;
+            const abs = node_path_1.default.join(dir, entry.name);
+            let isDir;
+            try {
+                isDir = node_fs_1.default.statSync(abs).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                if (walk(abs))
+                    return true;
+                continue;
+            }
+            if (!index_1.TEXT_EXTENSIONS.has(node_path_1.default.extname(entry.name).toLowerCase()))
+                continue;
+            if (/\b(BrowserRouter|createBrowserRouter)\b/.test(node_fs_1.default.readFileSync(abs, 'utf-8'))) {
+                return true;
+            }
+        }
+        return false;
+    };
+    return walk(projectDir);
+}
+/**
+ * miaoda app pack [--mode standalone] [--out <dir>]
+ *
+ * 把当前应用构建成自包含静态产物：按 stack 走各自的 strategy 产出可静态服务的目录树，
+ * 再扫出 `/spark/app` 图片经 dev server 代理下载到 `images/` 并改写成相对路径，最后打 zip。
+ *
+ * 设计文档：docs/superpowers/specs/2026-08-19-app-pack-design.md
+ */
+async function handleAppPack(opts) {
+    const mode = opts.mode ?? exports.DEFAULT_PACK_MODE;
+    if (!exports.PACK_MODES.includes(mode)) {
+        throw new error_1.AppError('ARGS_INVALID', `不支持的打包形态：${mode}`, {
+            next_actions: [`可用形态：${exports.PACK_MODES.join(', ')}`],
+        });
+    }
+    const projectDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    const meta = (0, spark_meta_1.readSparkMeta)(projectDir);
+    if (!meta.stack) {
+        throw new error_1.AppError('ARGS_INVALID', '.spark/meta.json 缺少 stack —— 请先跑 miaoda app init', {
+            next_actions: ['cd 到应用根目录后重试，或先执行 miaoda app init'],
+        });
+    }
+    const strategy = (0, index_1.resolveStrategy)(meta.stack);
+    // 参数校验一律前置：URL 写错不该等到构建 + 下载 + 打包跑完才报（那是几十秒）
+    if (opts.uploadUrl)
+        (0, index_1.assertValidUploadUrl)(opts.uploadUrl);
+    const outRel = normalizeOutDir(opts.out ?? exports.DEFAULT_PACK_OUT);
+    const outDir = node_path_1.default.join(projectDir, outRel);
+    const zipRel = `${outRel}.zip`;
+    const zipPath = node_path_1.default.join(projectDir, zipRel);
+    // 1. stack-specific：产出可静态服务的目录树
+    strategy({ projectDir, outDir });
+    if (!node_fs_1.default.existsSync(outDir) || node_fs_1.default.readdirSync(outDir).length === 0) {
+        throw new error_1.AppError('PACK_EMPTY_OUTPUT', '构建产物为空', {
+            next_actions: ['先手动跑一次该 stack 的构建命令确认工程本身可构建'],
+        });
+    }
+    // 2. 扫描
+    const urls = [];
+    const seen = new Set();
+    for (const rel of walkText(outDir)) {
+        for (const url of (0, index_1.scanSparkAppUrls)(node_fs_1.default.readFileSync(node_path_1.default.join(outDir, rel), 'utf-8'))) {
+            if (seen.has(url))
+                continue;
+            seen.add(url);
+            urls.push(url);
+        }
+    }
+    // 3. 下载
+    const devServerBase = SANDBOX_GATEWAY_BASE;
+    (0, logger_1.log)('pack', `Matched ${String(urls.length)} image url(s), fetching via ${devServerBase}`);
+    const { mapping, failed } = await (0, index_1.downloadImages)(urls, {
+        imagesDir: node_path_1.default.join(outDir, 'images'),
+        devServerBase,
+    });
+    // 命中 > 0 且全部失败 = 系统性问题（代理挂了 / 路径口径错），静默成功会误导调用方
+    if (urls.length > 0 && mapping.size === 0) {
+        throw new error_1.AppError('PACK_IMAGE_ALL_FAILED', `命中 ${String(urls.length)} 张图片但全部下载失败`, {
+            next_actions: [
+                '确认 dev server 正在运行且能代理 /spark/app 路径',
+                `首个失败：${failed[0]?.url ?? '?'} → ${failed[0]?.reason ?? 'unknown'}`,
+                ...(failed.length > 1
+                    ? [`其余 ${String(failed.length - 1)} 条见 --verbose（每条请求地址都会打到 stderr）`]
+                    : []),
+                `实际请求前缀：${devServerBase}（沙箱网关）`,
+            ],
+        });
+    }
+    // 4. 改写
+    const rewrittenFiles = (0, index_1.rewriteTree)(outDir, mapping);
+    // 5. 统计。**必须在打包前做**——目录随后就被删掉，那时量不到了。
+    const { fileCount, bytes } = measure(outDir);
+    // 6. 打包，随后删掉目录。目录是**中间态**，zip 才是交付物；两者内容重复，
+    // 留着等于占双份磁盘。预览需先解压。
+    (0, index_1.zipDir)(outDir, zipPath);
+    node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
+    (0, logger_1.log)('pack', `Packed ${zipRel}, staging dir removed`);
+    // 7. 上传（可选）。放在 emit 之前——传了 --upload-url 就说明上传是目的，
+    // 失败要让整个命令失败（退出码 1），不能先 emit 成功再抛。
+    // JSON 输出里**不回显 URL**（凭证类信息），只给状态码与服务端 log_id。
+    const upload = opts.uploadUrl ? await (0, index_1.uploadZip)(zipPath, opts.uploadUrl) : undefined;
+    const warnings = [];
+    // 8. 上传成功后清掉本地产物：交付物已在远端，沙箱磁盘不必留一份目录 + 一份 zip。
+    //
+    // **只在上传成功后清**。上传失败时产物必须留着——错误提示里明确写了「本地产物已保留，
+    // 可修正 --upload-url 后重跑，或手动上传」，清掉会让那句话变成谎话，且用户得重跑
+    // 整轮构建。失败路径走 uploadZip 抛错，根本到不了这里。
+    //
+    // 清理失败不算命令失败：上传已经成功，目的达到了，删不掉只是留了点垃圾 → 降级为 warning。
+    let localRemoved = false;
+    if (upload) {
+        try {
+            // 目录在打包后已删，这里只需清 zip
+            node_fs_1.default.rmSync(zipPath, { force: true });
+            localRemoved = true;
+            (0, logger_1.log)('pack', `Uploaded, local zip removed (${zipRel})`);
+        }
+        catch (err) {
+            warnings.push({
+                code: 'LOCAL_CLEANUP_FAILED',
+                message: `上传成功但本地产物清理失败：${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    if (failed.length > 0) {
+        warnings.push({
+            code: 'IMAGE_DOWNLOAD_PARTIAL_FAILURE',
+            message: `${String(failed.length)} 张图片下载失败，产物中保留原始绝对路径（离线打不开）`,
+        });
+    }
+    if (detectBrowserRouter(projectDir)) {
+        warnings.push({
+            code: 'SPA_ROUTER_FILE_PROTOCOL',
+            message: '检测到 BrowserRouter：standalone 构建已自动换成 HashRouter，路由形如 index.html#/about。' +
+                '若你对 router 做过二次封装或用了非 react-router 的方案，替换可能覆盖不到 —— ' +
+                '此时产物在 file:// 下路由会失效（首屏落 404 页），请改用本地 HTTP server 并从 / 访问。',
+        });
+    }
+    (0, output_1.emit)({
+        data: {
+            appId: meta.app_id ?? '',
+            stack: meta.stack,
+            mode,
+            out: outRel,
+            zip: zipRel,
+            // ⚠️ out 指向的**目录在打包后即被删除**（它只是中间态），永远不要去读它。
+            // zip 是本地交付物；localRemoved=true 时连 zip 也被清了（已上传到远端）。
+            localRemoved,
+            fileCount,
+            bytes,
+            images: {
+                matched: urls.length,
+                downloaded: mapping.size,
+                failed,
+            },
+            rewrittenFiles,
+            // 只在传了 --upload-url 时出现：{ status, logId? }。刻意不含 URL。
+            ...(upload ? { upload } : {}),
+            warnings,
+        },
+    });
+}

package/dist/cli/handlers/skills/sync.js

@@ -9,6 +9,7 @@ const coding_steering_1 = require("../../../utils/coding-steering");
 const sandbox_skills_1 = require("../../../utils/sandbox-skills");
 const file_ops_1 = require("../../../utils/file-ops");
 const spark_meta_1 = require("../../../utils/spark-meta");
+const dir_lock_1 = require("../../../utils/dir-lock");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 /**
@@ -24,24 +25,35 @@ const output_1 = require("../../../utils/output");
  */
 function syncSteeringForSandbox(params) {
     let stack;
+    // 提到 try 外：下面 syncCodingSteering 要用它做 match-template-version 门禁
+    let templateVersion;
     try {
         const meta = (0, spark_meta_1.readSparkMeta)(params.targetDir);
         if (meta.stack === undefined || meta.stack === '' || meta.stack === 'null') {
             return { status: 'skipped', reason: '.spark/meta.json missing stack' };
         }
         stack = meta.stack;
+        templateVersion = meta.version;
     }
     catch (err) {
         return { status: 'skipped', reason: `read .spark/meta.json failed: ${err.message}` };
     }
-    // 版本口径与下方本地分支保持一致：--version > BOE 的 dist-tag dev > latest
-    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
-    const effectiveVersion = params.version ?? (isBoe ? 'dev' : undefined);
+    // 版本口径：--version > lane（TCC tgzKey）> BOE 的 dist-tag dev > latest。
+    //
+    // **这里不预先把 BOE 解成 'dev'**（下方本地分支为了回报 versionSource 才那么做）：
+    // 一旦提前填进 version，就会盖住 lane —— version 在优先级里高于 lane，BOE 沙箱上
+    // 配了 tgzKey 也永远命中不了。把 version 原样透传（未指定就是 undefined），让
+    // syncCodingSteering 一处算全链：version > lane > dev > latest。
     try {
         const r = (0, coding_steering_1.syncCodingSteering)({
             stack,
             targetDir: params.targetDir,
-            version: effectiveVersion,
+            version: params.version,
+            // TCC 的 X 与平铺 skill 共用：pickLaneVersion 只匹配 `-alpha.<X>` 后缀，
+            // 不看 base 版本，所以一个 key 同时定向 coding-steering 与 sandbox-skills。
+            tgzKey: params.tgzKey,
+            // match-template-version 门禁的比对基准（老 update-skills.sh 读的同一个字段）
+            templateVersion,
             // 必须显式传 mode，不能落到 inferMode()：它靠 env MIAODA_DEP_CACHE_DIR 嗅探，
             // 而 mode 决定读包内哪个 layer（sandbox→`skills/`，local→`skills_local/`）。
             // `--type` 分支本身就是沙箱语义，嗅探失手会去读不存在的 skills_local/、
@@ -56,6 +68,7 @@ function syncSteeringForSandbox(params) {
             version: r.version,
             syncedSkills: r.syncedSkills,
             techSynced: r.techSynced,
+            prunedStacks: r.prunedStacks,
         };
     }
     catch (err) {
@@ -70,9 +83,16 @@ function syncSteeringForSandbox(params) {
  *
  * 版本来源优先级（从高到低）：
  *   1. CLI `--version` flag（显式指定）
- *   2. `FORCE_FRAMEWORK_ENVIRONMENT=boe` → dist-tag `dev`（BOE 测试灰度，跟随
+ *   2. lane：`--type` 分支下由 TCC `skillsUpdateTgzKey` 透传 `--tgz-key`，反推 X 后
+ *      解析出 `-alpha.<X>` 版本。**与平铺 skill 共用同一个 X** —— 匹配只看后缀、
+ *      不看 base 版本，所以 TCC 配一个 key 就同时定向 coding-steering 与 sandbox-skills。
+ *      本地分支（不带 `--type`）没有 tgzKey，这一档天然不参与。
+ *   3. `FORCE_FRAMEWORK_ENVIRONMENT=boe` → dist-tag `dev`（BOE 测试灰度，跟随
  *      publish-alpha.sh 在 develop 分支打的 dev tag，便于在 BOE 沙箱里验证预发 steering）
- *   3. 默认 `latest`
+ *   4. 默认 `latest`
+ *
+ * 2/3/4 档统一在 `syncCodingSteering` 里算（见那边注释），handler 只负责透传，避免
+ * 提前把 `dev` 填进 version 把 lane 挤掉。
  *
  * **不读 meta.json**——steering 版本不在 meta 里钉。
  */
@@ -95,41 +115,57 @@ async function handleSkillsSync(opts) {
     // 冻结只冻结了一半。
     if (opts.type !== undefined && opts.type !== '') {
         const { type, tgzKey } = (0, sandbox_skills_1.validateSandboxSyncOpts)({ type: opts.type, tgzKey: opts.tgzKey });
-        const result = (0, sandbox_skills_1.syncSandboxSkills)({ type, tgzKey, targetDir });
-        const steering = result.skippedByKeepFile
-            ? { status: 'skipped', reason: '.keep file found, sync frozen' }
-            : syncSteeringForSandbox({ targetDir, version: opts.version });
-        // ③ 收尾锁只读（update-skills.sh:241 的 chmod -R a=rX）。必须在 ①② 全部写完之后，
-        //    锁上就写不进去了。`.keep` 冻结时不锁 —— 老链路那条路径是 exit 0 直接走、
-        //    末尾的 chmod 压根不执行，保持一致。
-        //
-        // **只锁沙箱侧**：这里的 result.targetDir 只会是 `.agent/skills` 或 `skills`
-        //   （见 sandbox-skills 的 skillsRoot），都是平台下发的资产根。本地 `--local` 走
-        //   flat layout 输出到 `.agents/`，压根不经过本分支，权限不会被碰。
-        //
-        // 回退风险由解锁侧兜：权限是持久化在磁盘的，代码能回退、磁盘状态不会。所以
-        //   file-ops 的 unlockDirForWrite 在**两处写入前**都调用了（syncSandboxSkills 的
-        //   写入前 + syncCodingSteering 的 nested 分支写入前），任一入口都不会因为
-        //   上一轮的锁而 EACCES。改动这里之前先确认那两处解锁还在。
-        const lockedReadonly = result.skippedByKeepFile ? false : (0, file_ops_1.lockDirReadonly)(result.targetDir);
-        (0, output_1.emit)({
-            data: {
-                mode: 'sandbox',
-                type,
-                packageName: result.packageName,
-                version: result.version,
-                lane: result.lane,
-                syncedTop: result.syncedTop,
-                deleted: result.deleted,
-                skippedByKeepFile: result.skippedByKeepFile,
-                lockedReadonly,
-                targetDir: result.targetDir,
-                steering,
-            },
+        // 并发锁覆盖「平铺同步 + steering 同步 + 收尾 chmod」整段：写入策略是按目录整清再拷，
+        // 两个实例并发会互相看到半清空状态，而 feida-ai 的 scanAllSkills 是会话期按需扫盘。
+        // 对齐老 update-skills.sh:157-159 的 flock。
+        (0, dir_lock_1.withDirLock)(targetDir, () => {
+            syncSandboxAndSteering({ opts, targetDir, type, tgzKey });
         });
         return;
     }
     // 原有 coding-steering 同步逻辑（本地 dev / miaoda app init 用）
+    (0, dir_lock_1.withDirLock)(targetDir, () => {
+        syncSteeringOnly({ opts, targetDir });
+    });
+}
+function syncSandboxAndSteering(params) {
+    const { opts, targetDir, type, tgzKey } = params;
+    const result = (0, sandbox_skills_1.syncSandboxSkills)({ type, tgzKey, targetDir });
+    const steering = result.skippedByKeepFile
+        ? { status: 'skipped', reason: '.keep file found, sync frozen' }
+        : syncSteeringForSandbox({ targetDir, version: opts.version, tgzKey });
+    // ③ 收尾锁只读（update-skills.sh:241 的 chmod -R a=rX）。必须在 ①② 全部写完之后，
+    //    锁上就写不进去了。`.keep` 冻结时不锁 —— 老链路那条路径是 exit 0 直接走、
+    //    末尾的 chmod 压根不执行，保持一致。
+    //
+    // **只锁沙箱侧**：这里的 result.targetDir 只会是 `.agent/skills` 或 `skills`
+    //   （见 sandbox-skills 的 skillsRoot），都是平台下发的资产根。本地 `--local` 走
+    //   flat layout 输出到 `.agents/`，压根不经过本分支，权限不会被碰。
+    //
+    // 回退风险由解锁侧兜：权限是持久化在磁盘的，代码能回退、磁盘状态不会。所以
+    //   file-ops 的 unlockDirForWrite 在**两处写入前**都调用了（syncSandboxSkills 的
+    //   写入前 + syncCodingSteering 的 nested 分支写入前），任一入口都不会因为
+    //   上一轮的锁而 EACCES。改动这里之前先确认那两处解锁还在。
+    const lockedReadonly = result.skippedByKeepFile ? false : (0, file_ops_1.lockDirReadonly)(result.targetDir);
+    (0, output_1.emit)({
+        data: {
+            mode: 'sandbox',
+            type,
+            packageName: result.packageName,
+            version: result.version,
+            lane: result.lane,
+            syncedTop: result.syncedTop,
+            deleted: result.deleted,
+            skippedByKeepFile: result.skippedByKeepFile,
+            lockedReadonly,
+            targetDir: result.targetDir,
+            steering,
+        },
+    });
+}
+/** 不带 --type 的本地 / init 形态：只同步 coding-steering。 */
+function syncSteeringOnly(params) {
+    const { opts, targetDir } = params;
     const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('SKILLS_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
@@ -141,6 +177,7 @@ async function handleSkillsSync(opts) {
         stack: meta.stack,
         targetDir,
         version: effectiveVersion,
+        templateVersion: meta.version,
         outputLayout: opts.local === true ? 'flat' : 'nested',
     });
     (0, output_1.emit)({
@@ -150,6 +187,7 @@ async function handleSkillsSync(opts) {
             versionSource,
             syncedSkills: result.syncedSkills,
             techSynced: result.techSynced,
+            prunedStacks: result.prunedStacks,
             ...(result.claudeSkillsLink !== undefined
                 ? { claudeSkillsLink: result.claudeSkillsLink }
                 : {}),

package/dist/config/sync-configs/design-stack.js

@@ -91,7 +91,7 @@ exports.SYNC_CONFIG = {
             ifStartsWith: 'npm run upgrade && ',
         },
         // ===== miaoda-cli 本地开发新增规则 =====
-        // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
+        // M1. scripts.dev:local —— 本地用户绕过沙箱判定直接跑本地链路（npm run dev:local）。
         {
             type: 'add-script',
             name: 'dev:local',