@lark-apaas/miaoda-cli 0.1.35 → 0.1.37

package/dist/utils/coding-steering.js

@@ -7,9 +7,36 @@ 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 error_1 = require("../utils/error");
+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';
+/** nested 目标的祖先链，破坏性操作前逐段验真（见 `assertNoSymlinkedAncestor`）。 */
+const NESTED_ANCESTORS = ['.agent', 'skills', 'steering'];
+/**
+ * 合法 stack 名：单个路径段，首字符必须是字母数字。
+ *
+ * 为什么必须校验：`stack` 直接来自用户仓库里的 `.spark/meta.json`，而 `readSparkMeta`
+ * （spark-meta.ts:22）只做 `as SparkMeta` 类型断言、没有任何运行时校验。它会被 join 进
+ * 删除路径，而本文件的清理是**整目录 forceRemove**，所以 traversal 的后果是删掉整棵树：
+ *
+ * ```
+ * stack = ""          → forceRemove <targetDir>/.agent/skills/steering  （整个 steering 根）
+ * stack = "../.."     → forceRemove <targetDir>/.agent
+ * stack = "../../.."  → forceRemove <targetDir>                         （整个用户仓库）
+ * ```
+ *
+ * 首字符限定字母数字，顺带排掉了 `.` / `..` 与隐藏目录名。
+ */
+const STACK_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function assertSafeStack(stack) {
+    if (!STACK_NAME_PATTERN.test(stack)) {
+        throw new error_1.AppError('SKILLS_INVALID_STACK', `stack 名非法：${JSON.stringify(stack)}。只允许单个路径段（首字符为字母数字，其余可含 . _ -）；` +
+            `请检查 .spark/meta.json 的 stack 字段`);
+    }
+}
 function inferMode() {
     // 沙箱（MIAODA_DEP_CACHE_DIR 非空）→ sandbox；本地 → local
     return (0, env_1.isSandboxEnv)() ? 'sandbox' : 'local';
@@ -40,10 +67,31 @@ 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，不影响现有行为。
+    assertSafeStack(opts.stack);
+    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 +121,20 @@ 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') {
+            (0, file_ops_1.assertNoSymlinkedAncestor)(opts.targetDir, NESTED_ANCESTORS);
+            const steeringRootDst = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering');
+            const stackDst = node_path_1.default.join(steeringRootDst, opts.stack);
+            (0, file_ops_1.assertStrictlyInside)(steeringRootDst, stackDst);
+            (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 +143,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 +167,58 @@ 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') {
+            (0, file_ops_1.assertNoSymlinkedAncestor)(opts.targetDir, NESTED_ANCESTORS);
+            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 {
+                        const entryDst = node_path_1.default.join(steeringDst, entry);
+                        (0, file_ops_1.assertStrictlyInside)(steeringDst, entryDst);
+                        (0, file_ops_1.forceRemove)(entryDst);
+                        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 +252,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 +262,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/exclude-patterns.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCLUDES = void 0;
+/**
+ * 与模板 `scripts/build.sh` 的 rsync EXCLUDES 对齐：这些名字（任意层级 basename）不进产物/不计入路由。
+ *
+ * 放在 `utils/` 而非某个 domain 的 service 下，是因为它被 `deploy`（`source-scan.ts` 的
+ * `listSourceFiles`）与 `app`（`pack` 的 `copyTree`）两个 domain 共用 ——
+ * service 层跨域互调被 `boundaries/dependencies` 禁止（见 docs/dependency-rules.md F4），
+ * 共享的纯数据/纯逻辑必须下沉到 `utils/`。
+ */
+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',
+]);

package/dist/utils/file-ops.js

@@ -8,10 +8,13 @@ exports.removeLineFromContent = removeLineFromContent;
 exports.unlockDirForWrite = unlockDirForWrite;
 exports.lockDirReadonly = lockDirReadonly;
 exports.forceRemove = forceRemove;
+exports.assertNoSymlinkedAncestor = assertNoSymlinkedAncestor;
+exports.assertStrictlyInside = assertStrictlyInside;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const logger_1 = require("./logger");
+const error_1 = require("../utils/error");
 /**
  * 从文件中移除匹配的行。
  * 搬自 @lark-apaas/fullstack-cli/src/utils/file-ops.ts，行为完全对齐：精确匹配（trim 后）。
@@ -124,3 +127,43 @@ function forceRemove(target) {
     }
     node_fs_1.default.rmSync(target, { recursive: true, force: true });
 }
+/**
+ * 破坏性操作前，确认 `baseDir` 往下经过 `segments` 的这条祖先链上**没有一段是软链**（也不是
+ * 普通文件）。任一段不合法就抛 `SKILLS_UNSAFE_TARGET`。
+ *
+ * `existsSync` / `readdirSync` / `rm -rf` 都会穿透祖先软链。把 `.agent/skills` 换成指向
+ * 外部目录的软链，「删掉目标里多余的条目」就会删到软链指向处的真实文件，随后的
+ * `mkdirSync` + 拷贝也会写到项目外。软链祖先不是合法状态，直接拒绝而不是带着它继续跑。
+ *
+ * 某一段还不存在 → 放行：调用方随后的 `mkdirSync(recursive)` 会创建真实目录，且其下没有
+ * 任何东西可删。
+ */
+function assertNoSymlinkedAncestor(baseDir, segments) {
+    let cur = node_path_1.default.resolve(baseDir);
+    for (const seg of segments) {
+        cur = node_path_1.default.join(cur, seg);
+        let st;
+        try {
+            st = node_fs_1.default.lstatSync(cur);
+        }
+        catch {
+            return;
+        }
+        if (st.isSymbolicLink() || !st.isDirectory()) {
+            throw new error_1.AppError('SKILLS_UNSAFE_TARGET', `${cur} 不是真实目录（软链或普通文件），拒绝在其下做清理与写入`);
+        }
+    }
+}
+/**
+ * 兜底 containment 断言：`target` 必须严格位于 `root` **之内**（不含 root 自身）。
+ *
+ * 各调用方对拼进路径的用户输入都有自己的校验（如 coding-steering 的 `assertSafeStack`），
+ * 这里防的是后续重构换一种方式拼路径时把破坏性操作指到了树外 —— 破坏性操作的边界值得
+ * 留一道断言。
+ */
+function assertStrictlyInside(root, target) {
+    const rel = node_path_1.default.relative(node_path_1.default.resolve(root), node_path_1.default.resolve(target));
+    if (rel === '' || rel.startsWith('..') || node_path_1.default.isAbsolute(rel)) {
+        throw new error_1.AppError('SKILLS_UNSAFE_TARGET', `拒绝删除 ${target}：不在 ${root} 之内`);
+    }
+}

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