@lark-apaas/miaoda-cli 0.1.33-alpha.b340b4a → 0.1.33-alpha.bcb2fec

package/README.md

@@ -48,31 +48,9 @@ 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 export-standalone` 把当前应用构建成一份自包含静态产物，可脱离妙搭平台本地打开。
-
-```bash
-miaoda app export-standalone                    # → dist/standalone/ + dist/standalone.zip
-miaoda app export-standalone --out dist/share
-miaoda app export-standalone --json
-```
-
-支持 `design-html` / `html` / `vite-react` / `nestjs-react-fullstack`。页面与代码里字面以
-`/spark/app` 开头的存储图片会经 dev server 代理下载到 `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,7 +22,6 @@ function registerAppCommands(program, opts = {}) {
     registerAppGet(appCmd);
     registerAppUpdate(appCmd);
     registerAppExport(appCmd);
-    registerAppExportStandalone(appCmd);
     if (opts.includeInit) {
         registerAppInit(appCmd);
         registerAppSync(appCmd);
@@ -128,10 +127,6 @@ function registerAppExport(parent) {
         .option('--out <dir>', '输出目录（相对当前目录）', 'source_package/creative')
         .option('--checkpoint <n>', '按检查点版本导出；缺省为最新提交（HEAD）')
         .addHelpText('after', `
-与 'miaoda app export-standalone' 的区别（**两个命令语义无关，别选错**）
-  app export             导出源码归档（本命令）
-  app export-standalone  导出可本地访问的构建产物
-
 说明
   从服务端导出源应用（可以不是当前应用）的源码归档并解压到 --out 目录，导出完成后写
   --out/.upgrade-manifest.json（含 sourceAppId / 导出时间 / 文件数），供升级链路幂等
@@ -178,65 +173,6 @@ JSON 输出
         });
     }));
 }
-function registerAppExportStandalone(parent) {
-    const cmd = parent
-        .command('export-standalone')
-        .description('把当前应用构建成自包含静态产物（目录 + zip），可脱离妙搭平台本地访问')
-        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
-        .option('--out <dir>', '输出目录（相对项目根）', index_1.DEFAULT_STANDALONE_OUT)
-        .option('--dev-server <url>', 'dev server 基址，默认 http://localhost:${CLIENT_DEV_PORT:-8080}')
-        .addHelpText('after', `
-与 'miaoda app export' 的区别（**两个命令语义无关，别选错**）
-  app export             导出源码归档（创意应用升级链路的只读参考物）
-  app export-standalone  导出可本地访问的构建产物（本命令）
-
-支持的 stack
-  design-html / html / vite-react / nestjs-react-fullstack
-
-产物
-  <out>/          index.html + assets/ + images/（+ static/，vite 系有 shared/static 时）
-  <out>.zip       同内容的压缩包
-  默认 <out> 是 dist/standalone —— 落在 dist/ 下是刻意的：dist 已在部署扫描的
-  EXCLUDES 与各模板 .gitignore 中，产物不会污染部署包、不会被误提交。
-  代价：下一次构建会 rm -rf dist，导出产物是易失的。
-
-图片本地化
-  只处理页面/代码里字面以 /spark/app 开头的 URL，经 dev server 代理下载到
-  <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": "..."}]},
-            "rewrittenFiles": [...],
-            "warnings": [{"code": "...", "message": "..."}]}}
-
-失败
-  单张图片下载失败 → 跳过并计入 images.failed + warnings，退出码 0。
-  命中 > 0 但全部失败 → EXPORT_STANDALONE_IMAGE_ALL_FAILED，退出码 1（系统性问题）。
-  stack 不支持 → EXPORT_STANDALONE_STACK_UNSUPPORTED。
-  构建失败 → EXPORT_STANDALONE_BUILD_FAILED。
-
-示例
-  $ miaoda app export-standalone
-  $ miaoda app export-standalone --out dist/share
-  $ miaoda app export-standalone --json
-`);
-    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
-        await (0, index_1.handleAppExportStandalone)({
-            dir: rawOpts.dir,
-            out: rawOpts.out,
-            devServer: rawOpts.devServer,
-        });
-    }));
-}
 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.DEFAULT_STANDALONE_OUT = exports.handleAppExportStandalone = 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.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,6 +19,3 @@ 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 export_standalone_1 = require("./export-standalone");
-Object.defineProperty(exports, "handleAppExportStandalone", { enumerable: true, get: function () { return export_standalone_1.handleAppExportStandalone; } });
-Object.defineProperty(exports, "DEFAULT_STANDALONE_OUT", { enumerable: true, get: function () { return export_standalone_1.DEFAULT_STANDALONE_OUT; } });

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

@@ -86,6 +86,8 @@ async function handleAppInit(opts) {
         version: 'unknown',
         syncedSkills: [],
         techSynced: false,
+        prunedSkills: [],
+        prunedStacks: [],
     };
     let steeringError;
     if (scaffoldSteering) {
@@ -95,6 +97,9 @@ async function handleAppInit(opts) {
                 targetDir,
                 logPrefix: 'init',
                 outputLayout,
+                // match-template-version 门禁的比对基准：用刚渲染的 template 实际版本，
+                // 与随后写入 .spark/meta.json 的 version 同源（见下方 writeSparkMeta）
+                templateVersion: tplResult.version,
             });
         }
         catch (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/skills/sync.js

@@ -24,24 +24,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 +67,8 @@ function syncSteeringForSandbox(params) {
             version: r.version,
             syncedSkills: r.syncedSkills,
             techSynced: r.techSynced,
+            prunedSkills: r.prunedSkills,
+            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 里钉。
  */
@@ -98,7 +118,7 @@ async function handleSkillsSync(opts) {
         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 });
+            : syncSteeringForSandbox({ targetDir, version: opts.version, tgzKey });
         // ③ 收尾锁只读（update-skills.sh:241 的 chmod -R a=rX）。必须在 ①② 全部写完之后，
         //    锁上就写不进去了。`.keep` 冻结时不锁 —— 老链路那条路径是 exit 0 直接走、
         //    末尾的 chmod 压根不执行，保持一致。
@@ -121,6 +141,7 @@ async function handleSkillsSync(opts) {
                 lane: result.lane,
                 syncedTop: result.syncedTop,
                 deleted: result.deleted,
+                deletedFiles: result.deletedFiles,
                 skippedByKeepFile: result.skippedByKeepFile,
                 lockedReadonly,
                 targetDir: result.targetDir,
@@ -141,6 +162,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 +172,8 @@ async function handleSkillsSync(opts) {
             versionSource,
             syncedSkills: result.syncedSkills,
             techSynced: result.techSynced,
+            prunedSkills: result.prunedSkills,
+            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',

package/dist/config/sync-configs/nestjs-react-fullstack.js

@@ -135,8 +135,8 @@ exports.SYNC_CONFIG = {
             ifStartsWith: 'concurrently ',
         },
         // 10. 把老 `npm run upgrade && ./scripts/dev.sh` 形式迁移到 `./scripts/dev.sh`，
-        //     让本地 `npm run dev` 不再前置跑 fullstack-cli sync。新版 dev.sh 按 SANDBOX_ID 是否非空
-        //     判分支：沙箱直接 exec dev.js（脚本同步由平台 pod 启动时做过，dev 入口不再 upgrade）；
+        //     让本地 `npm run dev` 不再前置跑 fullstack-cli sync。新版 dev.sh 按 MIAODA_DEP_CACHE_DIR
+        //     是否非空判分支：沙箱直接 exec dev.js（脚本同步由平台 pod 启动时做过，dev 入口不再 upgrade）；
         //     本地走 miaoda app sync 兜底 + dev-local.js。
         {
             type: 'patch-script',
@@ -160,8 +160,8 @@ exports.SYNC_CONFIG = {
             ifStartsWith: 'npx -y @lark-apaas/fullstack-cli sync',
         },
         // ===== miaoda-cli 本地开发新增规则（fullstack-cli sync 不会执行） =====
-        // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
-        //     dev.sh 在 SANDBOX_ID 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.js；显式 dev:local
+        // M1. scripts.dev:local —— 本地用户绕过沙箱判定直接跑本地链路（npm run dev:local）。
+        //     dev.sh 在 MIAODA_DEP_CACHE_DIR 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.js；显式 dev:local
         //     用于 agent 在本地稳定调试，不受任何 env 影响。
         {
             type: 'add-script',

package/dist/services/deploy/modern/patch/source-scan.js

@@ -7,8 +7,45 @@ exports.EXCLUDES = void 0;
 exports.listSourceFiles = listSourceFiles;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const exclude_patterns_1 = require("../../../../utils/exclude-patterns");
-Object.defineProperty(exports, "EXCLUDES", { enumerable: true, get: function () { return exclude_patterns_1.EXCLUDES; } });
+// 与模板 scripts/build.sh 的 rsync EXCLUDES 对齐：这些名字（任意层级 basename）不进产物/不计入路由。
+exports.EXCLUDES = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'scripts',
+    'package.json',
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    '.gitignore',
+    '.npmrc',
+    // agent / 编辑器配置目录与指令文件：只服务本地开发，不属于应用资产。
+    // 注意 .claude/skills 在 flat layout 下是指向 ../.agents/skills 的软链，而 listSourceFiles
+    // 会 follow 软链，所以必须按 basename 把 .claude 整个排掉，否则 skills 会从软链侧被带进产物。
+    '.agent',
+    '.agents',
+    '.claude',
+    '.codex',
+    '.cursor',
+    '.gemini',
+    '.trae',
+    '.windsurf',
+    '.vscode',
+    '.idea',
+    'AGENTS.md',
+    'CLAUDE.md',
+    'GEMINI.md',
+    'skills',
+    '.env',
+    '.env.local',
+    'README.md',
+    '.DS_Store',
+    '.spark',
+    // 本地开发的临时/运行时目录：tmp 里的 .html 是草稿或中间产物，logs 是本地日志，
+    // 两者既不进产物也不该出现在 routes.json。
+    'tmp',
+    'logs',
+]);
 /**
  * 递归列出 root 下所有文件的相对 posix 路径，跳过 EXCLUDES（任意层级 basename），
  * 用 statSync 判定目录/文件以 follow 符号链接（含指向目录的软链），断链等无法 stat 的条目跳过。
@@ -17,7 +54,7 @@ function listSourceFiles(root) {
     const out = [];
     const walk = (dir, rel) => {
         for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
-            if (exclude_patterns_1.EXCLUDES.has(entry.name))
+            if (exports.EXCLUDES.has(entry.name))
                 continue;
             const childRel = rel ? `${rel}/${entry.name}` : entry.name;
             const abs = node_path_1.default.join(dir, entry.name);

package/dist/utils/coding-steering.js

@@ -7,7 +7,9 @@ exports.syncCodingSteering = syncCodingSteering;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const npm_pack_1 = require("../utils/npm-pack");
+const file_ops_1 = require("../utils/file-ops");
 const logger_1 = require("../utils/logger");
+const logger_2 = require("../utils/logger");
 const env_1 = require("../utils/env");
 const STEERING_PACKAGE = '@lark-apaas/coding-steering';
 function inferMode() {
@@ -40,10 +42,30 @@ function inferMode() {
  */
 function syncCodingSteering(opts) {
     const logPrefix = opts.logPrefix ?? 'skills';
-    const effectiveVersion = opts.version ?? 'latest';
+    // 版本优先级：--version（显式 pin / 止血）> lane（TCC 定向灰度）> BOE 默认 @dev > @latest
+    //
+    // 与 sandbox-skills 的 syncSandboxSkills 完全同一套口径，只是包名不同。BOE 的 @dev
+    // 由 miaoda-coding develop 分支的自动发布维护；lane 必须压过 dev —— TCC 配了 tgzKey
+    // 就是定向到某个 feat 分支的快照，不该被"BOE 跟 develop"这条默认规则盖掉。
+    //
+    // BOE→dev 这一档在本函数里算，不由调用方预填：`skills sync --type` 分支会带 tgzKey
+    // 进来，调用方若先把 'dev' 塞进 version，version 档位更高，lane 就永远命不中。
+    // 本地分支 / app init 为了回报 versionSource 仍会自己算 dev 再传 version —— 那两条路
+    // 没有 tgzKey，lane 档天然为空，两处口径一致不会打架。
+    //
+    // lane 解析与 sandbox-skills 同一套：`extractLaneFromTgzKey` 反推 X，`pickLaneVersion`
+    // 过滤后缀 `-alpha.<X>`。**匹配只看后缀、不看 base 版本**，所以 coding-steering
+    // （`0.1.3x-alpha.<X>`）和 sandbox-skills（`0.1.x-alpha.<X>`）能共用 TCC 里的同一个
+    // key —— 前提是 lane 发布脚本用同一个 X 把两边一起发出去。这个包没发 `-alpha.<X>`
+    // 时 pickLaneVersion 返回 null（它对报错 / 无匹配都返回 null，绝不 throw），静默
+    // 回落到 dev / latest，不影响现有行为。
+    const lane = (0, npm_pack_1.extractLaneFromTgzKey)(opts.tgzKey);
+    const laneVersion = lane === null ? null : (0, npm_pack_1.pickLaneVersion)(STEERING_PACKAGE, lane);
+    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
+    const effectiveVersion = opts.version ?? laneVersion ?? (isBoe ? 'dev' : 'latest');
     const mode = opts.mode ?? inferMode();
     const layout = opts.outputLayout ?? 'nested';
-    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${effectiveVersion} (mode=${mode}, layout=${layout})...`);
+    (0, logger_2.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${effectiveVersion} (mode=${mode}, layout=${layout})...`);
     const fetched = (0, npm_pack_1.fetchNpmPackage)({
         packageName: STEERING_PACKAGE,
         version: effectiveVersion,
@@ -81,7 +103,21 @@ function syncCodingSteering(opts) {
             node_fs_1.default.copyFileSync(techSrc, dstTechPath);
             techSynced = true;
         }
+        else if (node_fs_1.default.existsSync(dstTechPath)) {
+            // 源包这版不再提供 tech.md → 删掉上一轮留下的，否则永久残留（老脚本逐文件删除会带走它）
+            try {
+                (0, file_ops_1.forceRemove)(dstTechPath);
+            }
+            catch (err) {
+                (0, logger_1.debug)(`coding-steering: remove stale tech.md failed: ${err.message}`);
+            }
+        }
         const synced = [];
+        // 目标目录里「本轮应当存在」的 skill 目录名 —— 下面 prune 的保留集。
+        // 被 match-template-version 判否的**不进**这个集合，于是会被 prune 删掉 ——
+        // 与老脚本 `should_sync` 判否即 `rm`（update-skills.sh:196-215）行为一致。
+        const keep = new Set();
+        const filteredOut = [];
         // 顺序拷贝，后者覆盖前者：skills_common 铺底，专有层（skills 或 skills_local）覆盖同名
         const exclusiveLayer = mode === 'sandbox' ? 'skills' : 'skills_local';
         const layers = [
@@ -95,22 +131,72 @@ function syncCodingSteering(opts) {
                 const src = node_path_1.default.join(layer.dir, name);
                 if (!node_fs_1.default.statSync(src).isDirectory())
                     continue;
+                if (!matchesTemplateVersion(src, opts.templateVersion)) {
+                    filteredOut.push(`${layer.label}/${name}`);
+                    continue;
+                }
                 const dst = node_path_1.default.join(dstSkillsDir, name);
                 if (node_fs_1.default.existsSync(dst))
                     node_fs_1.default.rmSync(dst, { recursive: true, force: true });
                 copyDir(src, dst);
+                keep.add(name);
                 synced.push(`${layer.label}/${name}`);
             }
         }
+        // 收尾 ①：删掉目标里源包已不提供、或被版本门禁判否的 skill 目录。
+        // 新链路此前只在 sandbox-skills 侧做「顶层 prune」且显式跳过 steering/，导致 steering
+        // 下的过期 skill 永久残留。
+        const prunedSkills = [];
+        for (const name of node_fs_1.default.readdirSync(dstSkillsDir)) {
+            if (keep.has(name))
+                continue;
+            try {
+                (0, file_ops_1.forceRemove)(node_path_1.default.join(dstSkillsDir, name));
+                prunedSkills.push(name);
+            }
+            catch (err) {
+                (0, logger_1.debug)(`coding-steering: prune stale skill ${name} failed: ${err.message}`);
+            }
+        }
+        // 收尾 ②（仅 nested）：删掉同级其它 stack 的整棵 steering 目录。
+        // meta.json 的 stack 唯一，切栈后旧 stack 的 steering 不该再留 —— 修的正是
+        // 「vite-react 升级到 nestjs-react-fullstack 后 steering/vite-react/ 永久残留」。
+        // 老脚本靠 should_sync 里 `path_stack != STACK → return 1` + 逐文件删除达到同样效果。
+        // flat layout 没有 stack 命名空间，天然不涉及。
+        const prunedStacks = [];
+        if (layout === 'nested') {
+            const steeringDst = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering');
+            if (node_fs_1.default.existsSync(steeringDst)) {
+                for (const entry of node_fs_1.default.readdirSync(steeringDst)) {
+                    if (entry === opts.stack)
+                        continue;
+                    try {
+                        (0, file_ops_1.forceRemove)(node_path_1.default.join(steeringDst, entry));
+                        prunedStacks.push(entry);
+                    }
+                    catch (err) {
+                        (0, logger_1.debug)(`coding-steering: prune stale stack ${entry} failed: ${err.message}`);
+                    }
+                }
+            }
+        }
         let claudeSkillsLink;
         if (layout === 'flat') {
             claudeSkillsLink = ensureClaudeSkillsSymlink(opts.targetDir, logPrefix);
         }
-        (0, logger_1.log)(logPrefix, `Synced ${String(synced.length)} skill(s), tech.md ${techSynced ? 'yes' : 'no'} (mode=${mode}, layout=${layout})`);
+        const extras = [
+            prunedSkills.length > 0 ? `pruned ${String(prunedSkills.length)} stale skill(s)` : '',
+            prunedStacks.length > 0 ? `pruned stack(s) ${prunedStacks.join(',')}` : '',
+            filteredOut.length > 0 ? `filtered ${String(filteredOut.length)} by version` : '',
+        ].filter((x) => x !== '');
+        (0, logger_2.log)(logPrefix, `Synced ${String(synced.length)} skill(s), tech.md ${techSynced ? 'yes' : 'no'} ` +
+            `(mode=${mode}, layout=${layout})${extras.length > 0 ? ` [${extras.join('; ')}]` : ''}`);
         return {
             version: fetched.version,
             syncedSkills: synced,
             techSynced,
+            prunedSkills,
+            prunedStacks,
             ...(claudeSkillsLink !== undefined ? { claudeSkillsLink } : {}),
         };
     }
@@ -144,7 +230,7 @@ function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
     }
     if (existing === null) {
         node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
-        (0, logger_1.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink created)`);
+        (0, logger_2.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink created)`);
         return 'created';
     }
     if (existing.isSymbolicLink()) {
@@ -154,12 +240,59 @@ function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
         }
         node_fs_1.default.unlinkSync(linkPath);
         node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
-        (0, logger_1.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink updated, was → ${current})`);
+        (0, logger_2.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink updated, was → ${current})`);
         return 'updated';
     }
-    (0, logger_1.log)(logPrefix, `  ⚠ .claude/skills 已是普通目录/文件，跳过软链创建`);
+    (0, logger_2.log)(logPrefix, `  ⚠ .claude/skills 已是普通目录/文件，跳过软链创建`);
     return 'conflict';
 }
+/**
+ * 读 SKILL.md frontmatter 里的 `match-template-version`。逐字对齐老脚本的取值方式
+ * （`update-skills.sh:80-90`）：只看第一段 `---` 围起来的 frontmatter，去掉引号与全部空白。
+ * 没有该字段（或没有 SKILL.md）返回 undefined = 不设版本门禁。
+ */
+function readMatchTemplateVersion(skillDir) {
+    const skillMd = node_path_1.default.join(skillDir, 'SKILL.md');
+    if (!node_fs_1.default.existsSync(skillMd))
+        return undefined;
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(skillMd, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+    if (fm === null)
+        return undefined;
+    const line = /^match-template-version:(.*)$/m.exec(fm[1]);
+    if (line === null)
+        return undefined;
+    const value = line[1].replace(/["']/g, '').replace(/\s/g, '');
+    return value === '' ? undefined : value;
+}
+/**
+ * `match-template-version` 门禁，语义逐字对齐老 `check_version_match`
+ * （`update-skills.sh:76-108`）：
+ *   - skill 没声明该字段            → 放行
+ *   - 声明值是纯整数                → 与用户版本的 **major** 比（`3` 匹配 `3.2.1`）
+ *   - 其它形态（如 `2.2.6`）        → 与用户版本**全等**
+ *   - 用户版本未知（meta 里没 version）→ 放行（见 opts.templateVersion 注释）
+ */
+function matchesTemplateVersion(skillDir, templateVersion) {
+    const required = readMatchTemplateVersion(skillDir);
+    if (required === undefined)
+        return true;
+    if (templateVersion === undefined || templateVersion === '') {
+        (0, logger_1.debug)(`coding-steering: ${node_path_1.default.basename(skillDir)} 声明 match-template-version=${required}，` +
+            `但 .spark/meta.json 无 version，放行不过滤`);
+        return true;
+    }
+    if (/^\d+$/.test(required)) {
+        return templateVersion.split('.')[0] === required;
+    }
+    return templateVersion === required;
+}
 function copyDir(src, dest) {
     node_fs_1.default.mkdirSync(dest, { recursive: true });
     for (const entry of node_fs_1.default.readdirSync(src, { withFileTypes: true })) {

package/dist/utils/env.js

@@ -7,9 +7,9 @@ exports.isSandboxEnv = isSandboxEnv;
  * 口径：`process.env.MIAODA_DEP_CACHE_DIR` 非空（既非 undefined 也非空串）即为沙箱。
  * 沙箱平台运行时会给应用进程注入依赖缓存目录；本地 dev / agent 环境拿不到该变量。
  *
- * 历史上用 `SANDBOX_ID` 判断，但该变量在部分沙箱场景下并不会注入，判断不可靠，已换成
- * `MIAODA_DEP_CACHE_DIR`。注意：下发给 user app 的 `scripts/dev.sh` 仍按 `SANDBOX_ID`
- * 判断（独立 bash 链路，不复用本函数）。
+ * 历史上用 `SANDBOX_ID` 判断，但它由 sandbox_console 在绑定沙箱时才写入
+ * `.force/environment/env`，预热池实例在绑定前拿不到，故换成 `MIAODA_DEP_CACHE_DIR`。
+ * 下发给 user app 的 `scripts/dev.sh` 是独立 bash 链路（不复用本函数），现已同口径。
  *
  * 这是 CLI 运行时沙箱判定的 SSOT —— init outputLayout 分流、migrate 重启 dev process、
  * coding-steering 同步 mode 推断、async-install 写 marker 都走这里，别再各处内联读环境变量。

package/dist/utils/npm-pack.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pickLaneVersion = pickLaneVersion;
+exports.extractLaneFromTgzKey = extractLaneFromTgzKey;
 exports.fetchNpmPackage = fetchNpmPackage;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -44,6 +45,35 @@ function pickLaneVersion(packageName, X, registry) {
         return null;
     }
 }
+/**
+ * 从 TCC skillsUpdateTgzKey 反推 lane 名。
+ *   skills_versions/all_feat-xxx.tgz  → feat-xxx
+ *   skills_versions/all_feat_xxx.tgz  → feat-xxx  (_ sanitize → -)
+ *   skills_versions/all_latest.tgz    → null（走各自的默认版本口径）
+ *   任何 all_<X>.tgz                  → <X> 里 _ 全部转 -
+ *
+ * **宽进严出**：正则允许 `_` 匹配（兼容老 miaoda-skills 时代 TOS key 含 `_` 的存量 TCC
+ * 命名），但返回时 sanitize 成 `-` —— 对齐 publish-sandbox-skills.sh 侧只发 `-` 版
+ * lane 的现实（npm SemVer pre-release 只允许 `[A-Za-z0-9-]`，不允许 `_`）。
+ * 存量 TCC 里如果有 `all_feat_xxx.tgz` 这种命名，反推出 `feat-xxx` 后能正确命中
+ * npm 上实际发出的 `-alpha.feat-xxx-<ts>` 包，而不是静默 fallback。
+ *
+ * 用 nullable 而不是空字符串 —— 让调用方能判断"没 lane 就走默认版本"。
+ */
+function extractLaneFromTgzKey(tgzKey) {
+    if (tgzKey === undefined || tgzKey === '') {
+        return null;
+    }
+    const match = /(?:^|\/)all_([A-Za-z0-9][A-Za-z0-9_-]*)\.tgz$/.exec(tgzKey);
+    if (match === null) {
+        return null;
+    }
+    const lane = match[1].replace(/_/g, '-');
+    if (lane === 'latest') {
+        return null;
+    }
+    return lane;
+}
 /**
  * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
  * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。