@lark-apaas/miaoda-cli 0.1.32 → 0.1.33-alpha.07f9284

package/dist/cli/commands/deploy/modern.js

@@ -72,7 +72,7 @@ JSON 输出（stdout）
     }));
     const patchCmd = deployCmd
         .command('patch')
-        .description('design-html 增量发布：按文件 create/update/delete，.html 增删时同步 routes.json')
+        .description('design-html 增量发布：按文件 create/update/delete，.html 变动时同步 routes.json')
         .option('--create <relpath>', '新增文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--update <relpath>', '覆盖已有文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--delete <relpath>', '删除文件（可重复）', shared_1.collectRepeatedOption, [])
@@ -80,10 +80,11 @@ JSON 输出（stdout）
         .addHelpText('after', `
 --dir 为项目目录（与 deploy 同名参数，默认当前目录）。
 仅支持 design-html（design_local_deploy）。路径为工程根相对路径（= 服务端 latest 下 key），
-禁绝对路径与 ".."。--create/--update 的本地文件必须存在。.html 被新增/删除（路由集合变化）
-时自动重算并随包更新 routes.json；纯 --update 现有 .html 只改内容，不动 routes.json。
-routes.json 每项为 {path, file}：path 为相对路径（不含 base 前缀，由消费侧拼接），file 为
-对应源文件（如 / → index.html）。
+禁绝对路径与 ".."。--create/--update 的本地文件必须存在。改动里含任意 .html（增 / 改 / 删）
+时自动重算并随包更新 routes.json；纯非 .html 改动不动 routes.json。
+routes.json 每项为 {path, file, name?}：path 为相对路径（不含 base 前缀，由消费侧拼接），
+file 为对应源文件（如 / → index.html），name 为该 HTML 的 <title> 文本（方案名，可缺省，
+缺省时由消费侧 fallback 到 path）。
 
 JSON 输出
   {"data": {"upsertCount": <n>, "deleteCount": <n>, "actionsSent": <n>, "routesRegenerated": <bool>}}

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/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',

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

@@ -36,8 +36,10 @@ function isHtml(rel) {
 /**
  * 把 changeset 组成 TosFileAction[]：
  *   - create/update 读本地文件、自动编码；delete 仅 FilePath。
- *   - .html 被 create / delete（路由集合变化）时，追加重算 routes.json 的 UPDATE action；
- *     纯 update 现有 .html 只改内容、不改路由集合，不重算 routes.json。
+ *   - 任一 .html 被 create / update / delete 时，追加重算 routes.json 的 UPDATE action。
+ *     update 也算：routes.json 的 name 取自 HTML 的 `<title>`，改方案名就是一次纯 update，
+ *     只按 create/delete 判定会让改名永远进不了 routes.json。
+ *   - 纯非 .html 改动（js / css / 图片）不动 routes.json。
  */
 function buildTosActions(projectDir, cs) {
     const actions = [];
@@ -48,8 +50,8 @@ function buildTosActions(projectDir, cs) {
     for (const rel of cs.deletes) {
         actions.push({ actionType: index_1.TosActionType.DELETE, filePath: normalizeRel(rel) });
     }
-    const routeSetChanged = [...cs.creates, ...cs.deletes].some(isHtml);
-    if (routeSetChanged) {
+    const routesMayChange = [...cs.creates, ...cs.updates, ...cs.deletes].some(isHtml);
+    if (routesMayChange) {
         actions.push({
             actionType: index_1.TosActionType.UPDATE,
             filePath: 'routes.json',

package/dist/services/deploy/modern/patch/html-title.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTitle = extractTitle;
+const node_fs_1 = __importDefault(require("node:fs"));
+/**
+ * 读 `<title>` 时的扫描窗口上限（字节）。title 规范上在 `<head>` 里、正常紧贴文档开头，
+ * 64KB 足以覆盖 head 里塞了内联 style / script 的情况，同时给大 HTML 兜住 IO 上限
+ * （generateRoutes 会遍历工程内所有 .html，不能整文件读）。
+ */
+const HEAD_SCAN_BYTES = 64 * 1024;
+const TITLE_RE = /<title[^>]*>([^<]*)<\/title>/i;
+const HEAD_CLOSE_RE = /<\/head\s*>/i;
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+const ENTITY_RE = /&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi;
+/** HTML 里可能出现在 title 文本中的命名实体。未列出的原样保留，不做全量实体表。 */
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+/** 把 title 文本里的实体还原成明文——name 是给前端直接当文本渲染的，不该带 `&amp;`。 */
+function decodeEntities(s) {
+    return s.replace(ENTITY_RE, (matched, body) => {
+        if (!body.startsWith('#')) {
+            return NAMED_ENTITIES[body.toLowerCase()] ?? matched;
+        }
+        const code = /^#x/i.test(body) ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+        if (!Number.isInteger(code) || code <= 0 || code > 0x10ffff)
+            return matched;
+        return String.fromCodePoint(code);
+    });
+}
+/** 只读文件头部 HEAD_SCAN_BYTES 字节。尾部可能截断多字节字符，对 title 提取无影响。 */
+function readHead(absPath) {
+    const fd = node_fs_1.default.openSync(absPath, 'r');
+    try {
+        const buf = Buffer.alloc(HEAD_SCAN_BYTES);
+        const bytes = node_fs_1.default.readSync(fd, buf, 0, HEAD_SCAN_BYTES, 0);
+        return buf.subarray(0, bytes).toString('utf-8');
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+/**
+ * 取 HTML 的 `<title>` 文本作为该页面的方案名。
+ *
+ * - 扫描范围截到第一个 `</head>`：body 里的 `<title>` 不算——内联 SVG 图标的 a11y
+ *   `<title>` 很常见，抓到就会把图标描述当成方案名。找不到 `</head>` 时退回整个窗口。
+ * - 先剔 HTML 注释，避免抓到被注释掉的 title。
+ * - 实体还原 + 空白折叠 + trim；空 title / 无 title / 读失败一律返回 undefined，
+ *   由消费侧 fallback 到 path（旧应用没有 title 时保持显示页面地址）。
+ */
+function extractTitle(absPath) {
+    let head;
+    try {
+        head = readHead(absPath);
+    }
+    catch {
+        return undefined;
+    }
+    const headClose = HEAD_CLOSE_RE.exec(head)?.index ?? -1;
+    const scope = (headClose >= 0 ? head.slice(0, headClose) : head).replace(COMMENT_RE, '');
+    const raw = TITLE_RE.exec(scope)?.[1];
+    if (raw === undefined)
+        return undefined;
+    const text = decodeEntities(raw).replace(/\s+/g, ' ').trim();
+    return text === '' ? undefined : text;
+}

package/dist/services/deploy/modern/patch/index.js

@@ -11,7 +11,7 @@ const actions_1 = require("./actions");
 var actions_2 = require("./actions");
 Object.defineProperty(exports, "buildTosActions", { enumerable: true, get: function () { return actions_2.buildTosActions; } });
 /**
- * design-html 增量发布：读本地文件组 TosFileAction（create/delete .html 时带重算的
+ * design-html 增量发布：读本地文件组 TosFileAction（改动含 .html 时带重算的
  * routes.json），调后端 applyTosDiff 应用到 latest。scope 限 design_local_deploy。
  */
 async function patchDesignDeploy(opts) {

package/dist/services/deploy/modern/patch/routes.js

@@ -1,6 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateRoutes = generateRoutes;
+const node_path_1 = __importDefault(require("node:path"));
+const html_title_1 = require("./html-title");
 const source_scan_1 = require("./source-scan");
 /**
  * .html → route path 推导（相对路径，不带 base 前缀）。rel 为 posix 相对路径。
@@ -16,8 +21,9 @@ function toRoute(rel) {
 }
 /**
  * 扫描 projectDir 下所有 .html（套 source-scan 的 EXCLUDES），生成 routes.json 文本（含尾换行）。
- * 每项为 { path, file }：path 为相对路径（不带 CLIENT_BASE_PATH 前缀，由消费侧拼接），
- * file 为该路由对应的原始 .html 源文件。按 path 排序、同 path 取字典序靠前的 file 去重。
+ * 每项为 { path, file, name? }：path 为相对路径（不带 CLIENT_BASE_PATH 前缀，由消费侧拼接），
+ * file 为该路由对应的原始 .html 源文件，name 为该文件 `<title>` 解析出的方案名（可缺省）。
+ * 按 path 排序、同 path 取字典序靠前的 file 去重。
  * 零 html 时输出空数组——不伪造解析不到文件的根路由。
  */
 function generateRoutes(projectDir) {
@@ -27,7 +33,11 @@ function generateRoutes(projectDir) {
         if (!byPath.has(entry.path))
             byPath.set(entry.path, entry);
     }
-    const routes = [...byPath.values()];
+    // title 只读去重后胜出的 file：同 path 多源（foo.html / foo/index.html）时不做无用 IO。
+    const routes = [...byPath.values()].map((entry) => {
+        const name = (0, html_title_1.extractTitle)(node_path_1.default.join(projectDir, entry.file));
+        return name === undefined ? entry : { ...entry, name };
+    });
     return JSON.stringify(routes, null, 2) + '\n';
 }
 function byPathThenFile(a, b) {

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,
@@ -73,6 +95,17 @@ function syncCodingSteering(opts) {
         // （老脚本 :179/:208 写明 `steering/ 子树由 miaoda CLI 独占，update.sh 不写不删`），
         // 锁它没收益；而权限逻辑散在写入方会跟收尾的 lockDirReadonly 形成隐式耦合，
         // 范围一旦不对称就会出「跑一次 skills sync 把整个 skills 目录解封」这种事。
+        // nested：把 `steering/<stack>/` 整棵清掉再重建。
+        //
+        // 这一刀同时覆盖了三件事，省掉了此前一堆对账逻辑：源包删掉的 skill、被门禁判否的
+        // skill、源包这版不再提供的 tech.md —— 全都因为「先清后拷」自然消失。
+        //
+        // flat（`.agents/skills`）**刻意不清**：那是本地 dev 目录，开发者会往里放自己手写的
+        // skill，「不在本轮同步清单里就删」等于替用户删东西。老脚本压根没有 flat 概念。
+        if (layout === 'nested') {
+            const stackDst = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack);
+            (0, file_ops_1.forceRemove)(stackDst);
+        }
         node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
         let techSynced = false;
         const techSrc = node_path_1.default.join(stackDir, 'tech.md');
@@ -81,7 +114,17 @@ function syncCodingSteering(opts) {
             node_fs_1.default.copyFileSync(techSrc, dstTechPath);
             techSynced = true;
         }
+        else if (layout === 'flat' && node_fs_1.default.existsSync(dstTechPath)) {
+            // flat 没有整清，源包不再提供 tech.md 时需显式删掉残留；nested 已被整清带走
+            try {
+                (0, file_ops_1.forceRemove)(dstTechPath);
+            }
+            catch (err) {
+                (0, logger_1.debug)(`coding-steering: remove stale tech.md failed: ${err.message}`);
+            }
+        }
         const synced = [];
+        const filteredOut = [];
         // 顺序拷贝，后者覆盖前者：skills_common 铺底，专有层（skills 或 skills_local）覆盖同名
         const exclusiveLayer = mode === 'sandbox' ? 'skills' : 'skills_local';
         const layers = [
@@ -95,22 +138,55 @@ function syncCodingSteering(opts) {
                 const src = node_path_1.default.join(layer.dir, name);
                 if (!node_fs_1.default.statSync(src).isDirectory())
                     continue;
+                if (!matchesTemplate(src, opts.stack, opts.templateVersion, logPrefix)) {
+                    filteredOut.push(`${layer.label}/${name}`);
+                    continue;
+                }
                 const dst = node_path_1.default.join(dstSkillsDir, name);
+                // flat 下目录没被整清，同名仍需先删再拷（skills_common 铺底、专有层覆盖同名）
                 if (node_fs_1.default.existsSync(dst))
                     node_fs_1.default.rmSync(dst, { recursive: true, force: true });
                 copyDir(src, dst);
                 synced.push(`${layer.label}/${name}`);
             }
         }
+        // 收尾（仅 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 = [
+            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,
+            prunedStacks,
             ...(claudeSkillsLink !== undefined ? { claudeSkillsLink } : {}),
         };
     }
@@ -144,7 +220,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 +230,98 @@ 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;
+}
+/** 读 frontmatter 里的 `match-template-name`（同上，取不到返回 undefined）。 */
+function readMatchTemplateName(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-name:(.*)$/m.exec(fm[1]);
+    if (line === null)
+        return undefined;
+    const value = line[1].replace(/["']/g, '').trim();
+    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;
+}
+/**
+ * 组合门禁：`match-template-name` + `match-template-version`。
+ *
+ * `match-template-name` 在这里是**防御性校验**而非过滤主力：包内 skill 本来就住在
+ * `steering/<stack>/` 下、目录结构已经按 stack 隔离，声明值理应等于所在 stack
+ * （实测包里 23 处全是 `nestjs-react-fullstack`）。真正跨 stack 的池化过滤在 feida-ai
+ * 加载时做（`skills.ts:1209` 的 `isTemplateMatched`）。所以这里对不上就是**包结构出问题**，
+ * 用 log（常显）而不是 debug 报出来，别静默下发到错误的 stack。
+ */
+function matchesTemplate(skillDir, stack, templateVersion, logPrefix) {
+    const declaredName = readMatchTemplateName(skillDir);
+    if (declaredName !== undefined && declaredName !== stack) {
+        (0, logger_2.log)(logPrefix, `⚠ ${node_path_1.default.basename(skillDir)} 声明 match-template-name=${declaredName}，` +
+            `但它位于 steering/${stack}/ 下 —— 包结构异常，跳过该 skill`);
+        return false;
+    }
+    return matchesTemplateVersion(skillDir, templateVersion);
+}
 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/dir-lock.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDirLock = withDirLock;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const error_1 = require("../utils/error");
+const logger_1 = require("../utils/logger");
+/**
+ * 跨进程互斥锁，对齐老 `update-skills.sh:157-159` 的 `flock`：
+ *
+ * ```bash
+ * LOCK_FILE="/tmp/update-skills-$(echo "$TARGET_DIR" | md5sum | cut -d' ' -f1).lock"
+ * exec 9>"$LOCK_FILE"; flock 9
+ * ```
+ *
+ * 为什么必须有：skills 同步现在是「按目录整清再拷」，两个实例并发时会互相看到半清空
+ * 状态；而 feida-ai 的 `scanAllSkills`（skills.ts:533）是会话期按需扫盘，正好能撞上这个
+ * 窗口 —— 历史上出过 skill 集合从 59 掉到 34 的事故。触发并发的现实路径：
+ * sandbox_updater 自带重试 + `app init` 与会话期 sync 同时跑。
+ *
+ * 用 `mkdir` 而不是写文件：`mkdirSync` 在 POSIX 与 Windows 上都是原子的「存在即失败」，
+ * 不需要 O_EXCL 之类的平台差异处理，也不依赖第三方库。
+ */
+/** 轮询间隔 */
+const POLL_INTERVAL_MS = 200;
+/** 默认最长等待：另一个实例正常跑完是秒级，给足余量 */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * 陈旧锁接管阈值。进程被 SIGKILL（沙箱重建 / OOM）时 finally 不会执行、锁目录会留下，
+ * 没有接管机制就会把后续所有同步永久堵死。10 分钟远大于一次正常同步的耗时。
+ */
+const STALE_TAKEOVER_MS = 600_000;
+function lockDirFor(key) {
+    const hash = node_crypto_1.default.createHash('md5').update(node_path_1.default.resolve(key)).digest('hex');
+    return node_path_1.default.join(node_os_1.default.tmpdir(), `miaoda-skills-sync-${hash}.lock`);
+}
+/** 锁目录存在且已超过陈旧阈值 → 接管（删掉重建）。返回是否接管过。 */
+function takeoverIfStale(lockDir) {
+    try {
+        const ageMs = Date.now() - node_fs_1.default.statSync(lockDir).mtimeMs;
+        if (ageMs < STALE_TAKEOVER_MS)
+            return false;
+        node_fs_1.default.rmSync(lockDir, { recursive: true, force: true });
+        (0, logger_1.log)('skills', `接管陈旧锁（持有 ${String(Math.round(ageMs / 1000))}s，超过阈值）：${lockDir}`);
+        return true;
+    }
+    catch {
+        // stat 失败通常是刚好被别人释放了，交回上层重试
+        return false;
+    }
+}
+/**
+ * 以 `key`（一般传目标目录）为粒度加锁执行 `fn`。
+ *
+ * 拿不到锁时**抛 AppError 而不是无锁硬跑**：并发方此刻正在把同一棵树刷成最新，硬跑只会
+ * 互相覆盖。抛错让上层（sandbox_updater 有重试）稍后再来，磁盘状态始终是完整的一份。
+ *
+ * 注意不可重入：同进程内嵌套调用同一 key 会等到超时。调用点都在各自的「一次完整同步」
+ * 外层，不存在嵌套。
+ */
+function withDirLock(key, fn, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const lockDir = lockDirFor(key);
+    const deadline = Date.now() + timeoutMs;
+    let acquired = false;
+    while (!acquired) {
+        try {
+            node_fs_1.default.mkdirSync(lockDir, { recursive: false });
+            acquired = true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (takeoverIfStale(lockDir))
+                continue;
+            if (Date.now() >= deadline) {
+                throw new error_1.AppError('SKILLS_SYNC_LOCKED', `另一个 skills 同步正在进行（锁：${lockDir}），等待 ${String(Math.round(timeoutMs / 1000))}s 后仍未释放`);
+            }
+            // 忙等：同步本身是重 IO 的短任务，简单轮询比引入 async 更贴合现有同步调用链
+            const until = Date.now() + POLL_INTERVAL_MS;
+            while (Date.now() < until) {
+                /* spin */
+            }
+        }
+    }
+    (0, logger_1.debug)(`dir-lock: acquired ${lockDir}`);
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            node_fs_1.default.rmSync(lockDir, { recursive: true, force: true });
+            (0, logger_1.debug)(`dir-lock: released ${lockDir}`);
+        }
+        catch (err) {
+            (0, logger_1.debug)(`dir-lock: release failed ${lockDir}: ${err.message}`);
+        }
+    }
+}

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()。

package/dist/utils/sandbox-skills.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractLaneFromTgzKey = extractLaneFromTgzKey;
+exports.extractLaneFromTgzKey = void 0;
 exports.syncSandboxSkills = syncSandboxSkills;
 exports.validateSandboxSyncOpts = validateSandboxSyncOpts;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -68,34 +68,11 @@ const BUSINESS_LINE_BY_TYPE = {
     openclaw: null, // openclaw 独立包，直接展平
 };
 /**
- * 从 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（走 @latest）
- *   任何 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 上实际发出的 `@lane-feat-xxx` 包，而不是静默 fallback 到 @latest。
- *
- * 用 nullable 而不是空字符串 —— 让调用方能判断"没 lane 就走 latest"。
+ * lane 解析已下沉到 `utils/npm-pack`（与 `pickLaneVersion` 同处一地，供
+ * sandbox-skills 与 coding-steering 共用）。这里保留再导出，维持既有引用面。
  */
-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;
-}
+var npm_pack_2 = require("./npm-pack");
+Object.defineProperty(exports, "extractLaneFromTgzKey", { enumerable: true, get: function () { return npm_pack_2.extractLaneFromTgzKey; } });
 /**
  * 主流程：按 type 拉包 + sync 到目标目录。
  *
@@ -113,7 +90,7 @@ function syncSandboxSkills(opts) {
     const targetDir = node_path_1.default.resolve(opts.targetDir ?? process.cwd());
     const packageName = PACKAGE_BY_TYPE[opts.type];
     const businessLine = BUSINESS_LINE_BY_TYPE[opts.type];
-    const lane = extractLaneFromTgzKey(opts.tgzKey);
+    const lane = (0, npm_pack_1.extractLaneFromTgzKey)(opts.tgzKey);
     // ---- lane 拉包 ----
     // 新姿势（2026-08 迁离 lane-<X> dist-tag 之后）：
     //   TCC 里的 X（比如 `feat-migrate-skills-from-miaoda-skills-20260805143512`）
@@ -121,14 +98,25 @@ function syncSandboxSkills(opts) {
     //   过滤 `endsWith('-alpha.' + X)`（因 X 含 timestamp 全局唯一，唯一命中或 0 命中）。
     //   0 命中 → fallback @latest（对齐旧 TCC 值找不到、灰度切换期间的兜底语义）。
     //   `pickLaneVersion` 内部对 `npm view` 报错 / 无匹配都返回 null，绝不 throw ——
-    //   目标就是"不挂掉"。
+    //   目标就是"不挂掉"。**同一个 X 也被 coding-steering 侧用同样方式解析**（见
+    //   `syncCodingSteering`）：匹配只看 `-alpha.<X>` 后缀、不看 base 版本，所以两个包
+    //   base 版本不同也能共用一个 TCC key。
     let fetched;
     const laneVersion = lane === null ? null : (0, npm_pack_1.pickLaneVersion)(packageName, lane, opts.registry);
     if (lane !== null && laneVersion === null) {
         (0, logger_1.debug)(`sandbox-skills: no npm version matched -alpha.${lane}, fallback to @latest ` +
             `(TCC 里的 X 可能是老 lane dist-tag 命名 / 已 unpublish / npm view 挂 / 网络断)`);
     }
-    const primaryVersion = laneVersion ?? 'latest';
+    // 版本优先级：lane（TCC 显式定向）> BOE 默认 @dev > @latest
+    //
+    // `dev` 通道由 miaoda-coding 的 publish-sandbox-skills-dev.sh 在 develop 分支自动发布
+    // （`<base>-dev.<sha>` + dist-tag `dev`），口径与 coding-steering 完全一致 ——
+    // 后者在本仓 coding-steering 侧也是 `FORCE_FRAMEWORK_ENVIRONMENT=boe` 时默认取 `dev`。
+    //
+    // lane 必须压过 dev：TCC 里配了 tgz-key 就说明是定向灰度（钉某个 feat 分支的快照），
+    // 不能被"BOE 就跟 develop"这条默认规则覆盖掉。
+    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
+    const primaryVersion = laneVersion ?? (isBoe ? 'dev' : 'latest');
     try {
         (0, logger_1.debug)(`sandbox-skills: fetching ${packageName}@${primaryVersion}`);
         fetched = (0, npm_pack_1.fetchNpmPackage)({
@@ -138,6 +126,9 @@ function syncSandboxSkills(opts) {
         });
     }
     catch (err) {
+        // @latest 是最后一档，它再挂就没得降了，直接抛。
+        // lane / dev 拉失败都降到 @latest：dev 通道可能因为 develop 还没发过包而不存在
+        // （dist-tag 缺失 → npm pack 404），这时候不该让整条 sync 挂掉。
         if (primaryVersion === 'latest') {
             throw err;
         }
@@ -177,60 +168,73 @@ function syncSandboxSkills(opts) {
         (0, file_ops_1.unlockDirForWrite)(skillsRoot);
         node_fs_1.default.mkdirSync(skillsRoot, { recursive: true });
         const syncedTop = [];
-        // 源包提供的全部顶层条目 —— prune 的保留集。与 syncedTop 分开维护：syncedTop 是
-        // 「本轮实际写入」，用于对外汇报；prune 只能依据「源包提供了什么」来判断 stale，
-        // 两者一旦哪天再次分叉（比如某分支又加了跳过写入的条件），拿 syncedTop 当保留集
-        // 就会把没重写的条目误判成 stale 删掉、下一轮再写回来，反复抖动。
+        // ---- 第一步：只收集「哪个顶层条目由哪些源目录贡献」，先不落盘 ----
+        //
+        // 为什么要分两步：写入策略是**按顶层条目整清再拷**（见第二步），而合并包里业务线与
+        // shared 可能提供同名条目（运行时 union、同名 shared 赢，逐字对齐老 build.sh:33/47）。
+        // 如果边遍历边「清+拷」，shared 那一轮会把业务线刚写进去的独有文件一起清掉。
+        // 先把 union 收集齐、每个条目只清一次，才能既做到镜像又保住 union 语义。
+        //
+        // sourceTop 同时是 pruneStaleEntries 的保留集：它是「源包提供了什么」，
+        // 不能用 syncedTop（本轮实际写入）—— 否则 shared 条目会被反复删了又写、来回抖动。
         const sourceTop = new Set();
+        const plan = new Map();
+        const addSource = (entry, dir) => {
+            sourceTop.add(entry);
+            const list = plan.get(entry);
+            if (list === undefined)
+                plan.set(entry, [dir]);
+            else
+                list.push(dir);
+        };
         if (businessLine !== null) {
-            // 合并包 miaoda/miaoda-modern/miaoda-design：cp <extractDir>/<business-line>/* 到 target
             const sourceDir = node_path_1.default.join(fetched.extractDir, businessLine);
             if (node_fs_1.default.existsSync(sourceDir)) {
                 for (const entry of node_fs_1.default.readdirSync(sourceDir)) {
-                    const from = node_path_1.default.join(sourceDir, entry);
-                    const to = node_path_1.default.join(skillsRoot, entry);
-                    sourceTop.add(entry);
-                    node_fs_1.default.cpSync(from, to, { recursive: true });
-                    syncedTop.push(entry);
+                    addSource(entry, node_path_1.default.join(sourceDir, entry));
                 }
             }
             else {
                 (0, logger_1.debug)(`sandbox-skills: source dir ${sourceDir} not found in package (skipped)`);
             }
-            // shared：合并包内 shared/* 到 target。**无条件覆盖**，逐字对齐老 build.sh:42-52 ——
-            // 那里业务线先 `cp -r`（:33-34）、shared 后 `cp -r`（:47），后写覆盖前写，
-            // 即同名时 **shared 赢**。当前包里两边无同名交集，但语义得跟老链路一致。
-            //
-            // 早期这里写成「`fs.existsSync(to)` 就 continue」，有两个问题：
-            //   1. 同名优先级反了（变成业务线赢）；
-            //   2. 更严重 —— existsSync 分不清「本轮业务线刚写的」和「上一轮 shared 自己写的」，
-            //      于是 shared skill 首次落盘后就永久冻结，包里再更新也同步不到已有沙箱
-            //      （沙箱磁盘跨会话保留，每次 update-skills 都会命中 existsSync）。
+            // shared 排在业务线之后 → 同名时 shared 赢（老 build.sh:47 后写覆盖前写）
             const sharedDir = node_path_1.default.join(fetched.extractDir, 'shared');
             if (node_fs_1.default.existsSync(sharedDir)) {
                 for (const entry of node_fs_1.default.readdirSync(sharedDir)) {
-                    const from = node_path_1.default.join(sharedDir, entry);
-                    const to = node_path_1.default.join(skillsRoot, entry);
-                    sourceTop.add(entry);
-                    node_fs_1.default.cpSync(from, to, { recursive: true });
-                    syncedTop.push(entry);
+                    addSource(entry, node_path_1.default.join(sharedDir, entry));
                 }
             }
         }
         else {
-            // openclaw 独立包：直接把包内所有 skill 目录（除 package.json 等元文件外）平铺到 skillsRoot
+            // openclaw 独立包：包内 skill 目录直接平铺（跳过 package.json 等元文件）
             for (const entry of node_fs_1.default.readdirSync(fetched.extractDir)) {
                 if (entry === 'package.json' || entry === 'README.md' || entry === 'LICENSE')
                     continue;
                 const from = node_path_1.default.join(fetched.extractDir, entry);
-                const stat = node_fs_1.default.statSync(from);
-                if (!stat.isDirectory())
+                if (!node_fs_1.default.statSync(from).isDirectory())
                     continue;
-                const to = node_path_1.default.join(skillsRoot, entry);
-                sourceTop.add(entry);
+                addSource(entry, from);
+            }
+        }
+        // ---- 第二步：逐条目「整清再拷」----
+        //
+        // 整清而非 `cpSync` 覆盖：cpSync 是覆盖不是镜像，源包删掉某个 skill *内部* 的文件
+        // （如 `references/old.md`）时目标那份会永久残留。老脚本靠逐文件比对 + `rm` 达到镜像
+        // （update-skills.sh:196-215），这里用「目录重建」达到同样效果，实现上更简单。
+        //
+        // 清理粒度刻意收在**单个条目**而不是整个 skillsRoot：
+        //   - `.keep` / `.config` / `.last-update` 是控制文件，整清会连它们一起删
+        //     （`.config` 是沙箱级 tgzKey 覆盖，feida-ai `sandbox-updater.ts:30` 读它，删了版本钉死失效）
+        //   - `steering/` 归 syncCodingSteering 管，本函数不该碰
+        //   - 单条目重建是毫秒级、一次只影响一个 skill；整清则会出现「整棵 skills 为空」的窗口，
+        //     而 feida-ai 的 scanAllSkills 会话期按需扫盘，正好能撞上
+        for (const [entry, srcDirs] of plan) {
+            const to = node_path_1.default.join(skillsRoot, entry);
+            (0, file_ops_1.forceRemove)(to);
+            for (const from of srcDirs) {
                 node_fs_1.default.cpSync(from, to, { recursive: true });
-                syncedTop.push(entry);
             }
+            syncedTop.push(entry);
         }
         // rsync 式收尾：删掉源包已不提供的顶层条目（对齐 update-skills.sh 的 deleted）。
         // 保留集用 sourceTop（源包提供的全部）而非 syncedTop（本轮实际写入的）——原因见

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.32",
+  "version": "0.1.33-alpha.07f9284",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/lint.js

@@ -63,13 +63,47 @@ function isStylelintTarget(filePath) {
   return filePath.endsWith('.css');
 }
 
+const STYLELINT_CONFIG_FILES = [
+  '.stylelintrc',
+  '.stylelintrc.js',
+  '.stylelintrc.cjs',
+  '.stylelintrc.json',
+  'stylelint.config.js',
+];
+
+/**
+ * 老模板（fullstack-nestjs-template 1.x 时代）的应用跑不了 stylelint，跑了就挂、把 pre-commit
+ * 卡死。两种形态都实测过：
+ *
+ * - 缺 scripts.stylelint → `npm error Missing script: "stylelint"`
+ * - 缺 .stylelintrc.*    → `ConfigurationError: No configuration provided`
+ *
+ * 注意光判断 stylelint 装没装拦不住：@lark-apaas/fullstack-presets 的 dependencies 里有
+ * stylelint，只要 dep 了 presets 二进制就在。缺任一件就跳过这一步。
+ */
+function canRunStylelint() {
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+  } catch {
+    return false;
+  }
+
+  if (!pkg.scripts || !pkg.scripts.stylelint) return false;
+
+  return STYLELINT_CONFIG_FILES.some(file => fs.existsSync(path.join(cwd, file)));
+}
+
 async function runDefaultLint() {
-  const code = await runCommand(getBinName('npx'), [
-    'concurrently',
-    'npm run eslint',
-    'npm run type:check',
-    'npm run stylelint',
-  ]);
+  const commands = ['npm run eslint', 'npm run type:check'];
+
+  if (canRunStylelint()) {
+    commands.push('npm run stylelint');
+  } else {
+    console.warn('[lint] Skip stylelint: missing scripts.stylelint or stylelint config');
+  }
+
+  const code = await runCommand(getBinName('npx'), ['concurrently', ...commands]);
   process.exit(code);
 }
 
@@ -107,7 +141,9 @@ async function runSelectiveLint(inputFiles) {
     tasks.push(runCommand(getBinName('npx'), ['eslint', '--quiet', ...eslintFiles]));
   }
 
-  if (stylelintFiles.length > 0) {
+  if (stylelintFiles.length > 0 && !canRunStylelint()) {
+    console.warn('[lint] Skip stylelint: missing scripts.stylelint or stylelint config');
+  } else if (stylelintFiles.length > 0) {
     tasks.push(runCommand(getBinName('npx'), ['stylelint', '--quiet', ...stylelintFiles]));
   }