@lark-apaas/miaoda-cli 0.1.36 → 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';
@@ -57,13 +84,14 @@ function syncCodingSteering(opts) {
     // 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,
@@ -93,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');
@@ -101,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 = [
@@ -115,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 } : {}),
         };
     }
@@ -164,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()) {
@@ -174,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/sandbox-skills.js

@@ -146,6 +146,10 @@ function syncSandboxSkills(opts) {
         const skillsRoot = opts.type === 'openclaw'
             ? node_path_1.default.join(targetDir, 'skills')
             : node_path_1.default.join(targetDir, '.agent', 'skills');
+        // skillsRoot 全部由字面量拼成（没有用户可控段），所以不存在 traversal；但 `rm -rf` 与
+        // `readdirSync` 会穿透**祖先软链** —— 把 `.agent/skills` 换成指向外部目录的软链，下面
+        // 的按条目整清就会删到软链指向处的真实文件。破坏性操作前先验真这条链。
+        (0, file_ops_1.assertNoSymlinkedAncestor)(targetDir, opts.type === 'openclaw' ? ['skills'] : ['.agent', 'skills']);
         // `.keep` 短路：对齐 update-skills.sh:149-152，沙箱侧放了这个文件即表示
         // 「我手改过 skills，别覆盖我」，整体跳过同步（含 steering —— 调用方看到
         // skipped 就不该再往下写）。
@@ -168,60 +172,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.36",
+  "version": "0.1.37",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {