@lark-apaas/miaoda-cli 0.1.24-alpha.495fda7 → 0.1.24-alpha.4ac18f6

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

@@ -26,10 +26,11 @@ function registerSkillsSync(parent) {
         .option('--version <ver>', 'coding-steering 包版本或 dist-tag，缺省 latest')
         .option('--local', '走本地 dev / agent 输出形态：拷到 .agents/skills 平铺 + 创建 .claude/skills 软链。' +
         '不传时退回老形态：拷到 .agent/skills/steering/<stack>/skills/（跟沙箱端 update-skills.sh 对齐）', false)
-        .option('--type <type>', '走 sandbox-skills 分支：miaoda | miaoda-modern | miaoda-design | openclaw。' +
-        '有值时忽略 --version/--local，改从 @lark-apaas/coding-<pkg>-sandbox 拉对应包写入 .agent/skills/')
+        .option('--type <type>', '走 sandbox 分支：miaoda | miaoda-modern | miaoda-design | openclaw。有值时忽略 --local，' +
+        '从 @lark-apaas/coding-<pkg>-sandbox-skills 拉包平铺写入，并额外同步 steering ' +
+        '到 .agent/skills/steering/<stack>/（--version 对后者仍生效）')
         .option('--tgz-key <key>', '配合 --type 使用；老 TCC skillsUpdateTgzKey 值透传，' +
-        '从 skills_versions/all_<X>.tgz 反推出 dist-tag lane-<X>；缺省走 @latest')
+        '从 skills_versions/all_<X>.tgz 反推出 lane 名 X，再过滤出 -alpha.<X> 版本；缺省走 @latest')
         .addHelpText('after', `
 前置要求
   当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack）
@@ -45,15 +46,28 @@ function registerSkillsSync(parent) {
     .agents/tech.md
     .claude/skills → ../.agents/skills（软链，让 Claude Code 识别同一份）
 
+  传 --type（沙箱链路，两部分都同步）：
+    .agent/skills/<skill>/...                        ← 业务线 skill，平铺
+    .agent/skills/steering/<stack>/skills/<skill>/   ← steering，同上面默认形态
+    （openclaw 的业务线部分落 skills/ 而非 .agent/skills/）
+
 JSON 输出
   {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false,
             "claudeSkillsLink": "created|updated|noop|conflict"  // 仅 --local 时}}
 
+  传 --type 时：
+  {"data": {"mode": "sandbox", "type": "...", "packageName": "...", "version": "...",
+            "lane": "...", "syncedTop": [...], "targetDir": "...",
+            "steering": {"status": "synced|skipped|failed", ...}}}
+  steering 失败或无 stack 不影响整体成功——业务线 skill 已同步，不该因增量部分阻断
+
 示例
   $ miaoda skills sync                              # 拉 @latest
   $ miaoda skills sync --local                      # 本地 dev / agent 用
   $ miaoda skills sync --version 0.2.0              # 显式指定版本
   $ miaoda skills sync --dir ./my-app
+  # 沙箱链路（由 feida-ai 下发）：业务线 skill + steering 一次同步到位
+  $ miaoda skills sync --type miaoda-modern --tgz-key 'skills_versions/all_demo-lane.tgz'
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         await (0, index_1.handleSkillsSync)({

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

@@ -7,9 +7,61 @@ exports.handleSkillsSync = handleSkillsSync;
 const node_path_1 = __importDefault(require("node:path"));
 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 error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
+/**
+ * sandbox 分支下补同步 steering（`.agent/skills/steering/<stack>/`）。
+ *
+ * **绝不抛错**，因为它在 sandbox 链路里是「附加项」而非门禁：
+ *   - 无 `.spark/meta.json` / 无 stack → skipped。对齐老 cp-skills.sh 的
+ *     `[ -n "$STACK" ] && [ "$STACK" != "null" ]` 判断（无 stack 就跳过 steering）。
+ *   - 拉包 / 写盘失败 → failed，但仍让整条 sync 算成功。
+ *
+ * 为什么不能抛：feida-ai 侧 TCC 可配 `allowFailure: false`，一抛就阻断 agent 启动。
+ * 平铺业务线 skill 已经同步好了，不该因为 steering 这个增量部分让用户开不了会话。
+ */
+function syncSteeringForSandbox(params) {
+    let stack;
+    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;
+    }
+    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);
+    try {
+        const r = (0, coding_steering_1.syncCodingSteering)({
+            stack,
+            targetDir: params.targetDir,
+            version: effectiveVersion,
+            // 必须显式传 mode，不能落到 inferMode()：它靠 env MIAODA_DEP_CACHE_DIR 嗅探，
+            // 而 mode 决定读包内哪个 layer（sandbox→`skills/`，local→`skills_local/`）。
+            // `--type` 分支本身就是沙箱语义，嗅探失手会去读不存在的 skills_local/、
+            // 静默同步 0 个 skill。
+            mode: 'sandbox',
+            // 同理固定 nested：落 .agent/skills/steering/<stack>/，与老链路一致
+            outputLayout: 'nested',
+        });
+        return {
+            status: 'synced',
+            stack,
+            version: r.version,
+            syncedSkills: r.syncedSkills,
+            techSynced: r.techSynced,
+        };
+    }
+    catch (err) {
+        return { status: 'failed', reason: err.message };
+    }
+}
 /**
  * miaoda skills sync [--dir <path>] [--version <ver>]
  *
@@ -27,11 +79,39 @@ const output_1 = require("../../../utils/output");
 async function handleSkillsSync(opts) {
     await Promise.resolve();
     const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    // --type 走 sandbox-skills 分支（迁仓后沙箱内 update-skills.sh 调用），跟本地 dev 的
-    // steering 同步逻辑并列——两条路径的目标 / 拉包 / 目录结构完全不同，用 --type 显式路由。
+    // --type 走 sandbox-skills 分支（迁仓后沙箱内由 feida-ai 直接下发调用）。
+    //
+    // 这条分支必须**同时**同步两部分，缺一不可 —— 线上老链路 update-skills.sh 也是两步
+    // （自己 rsync 平铺，再于第 230 行调不带 --type 的 `miaoda skills sync` 写 steering）：
+    //   ① syncSandboxSkills：平铺业务线 skill，rsync 式对齐（保 .keep/.config/steering）
+    //   ② steering：`.agent/skills/steering/<stack>/`，按 .spark/meta.json 的 stack 过滤
+    //   ③ lockDirReadonly：锁只读收尾（update-skills.sh:241），仅沙箱侧路径
+    //
+    // 历史 bug：早期这里 ① 完就 return，steering 既不同步、又被当时的整目录清空删掉，
+    // 沙箱少掉整批技术栈 skill（BOE 实测 scanAllSkills 从 59 掉到 34）。
+    //
+    // `.keep` 语义（update-skills.sh:149）：目标目录挂了 .keep 表示「我手改过，别覆盖」，
+    // ① 会跳过并回报 skippedByKeepFile，此时 ② 也必须跳过 —— 否则 steering 仍被覆写，
+    // 冻结只冻结了一半。
     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',
@@ -40,7 +120,11 @@ async function handleSkillsSync(opts) {
                 version: result.version,
                 lane: result.lane,
                 syncedTop: result.syncedTop,
+                deleted: result.deleted,
+                skippedByKeepFile: result.skippedByKeepFile,
+                lockedReadonly,
                 targetDir: result.targetDir,
+                steering,
             },
         });
         return;

package/dist/utils/coding-steering.js

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const npm_pack_1 = require("../utils/npm-pack");
 const logger_1 = require("../utils/logger");
 const env_1 = require("../utils/env");
+const file_ops_1 = require("../utils/file-ops");
 const STEERING_PACKAGE = '@lark-apaas/coding-steering';
 function inferMode() {
     // 沙箱（MIAODA_DEP_CACHE_DIR 非空）→ sandbox；本地 → local
@@ -63,6 +64,21 @@ function syncCodingSteering(opts) {
                 dstSkillsDir: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'skills'),
                 dstTechPath: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'tech.md'),
             };
+        // 写入前解锁 `.agent/skills`：沙箱链路每轮同步末尾会把它 chmod -R a=rX 锁成只读
+        // （file-ops 的 lockDirReadonly，对齐 update-skills.sh:241），不解锁下面 mkdir/cp
+        // 就 EACCES。老链路的解锁在 update-skills.sh:160-165 脚本层、每次必跑；这里下沉到
+        // 写入方，沙箱 `--type` 与本地 `skills sync` / `app init` 任一入口都不会漏。
+        //
+        // 解锁的是**锁定根**而非 dstSkillsDir：锁是 chmod -R 打在根上的，只解 dst 那一层，
+        // 祖先目录仍不可写 → 照样失败。
+        //
+        // **仅 nested**：flat 的输出根是 `.agents/`，而 lockDirReadonly 只作用于 --type 分支的
+        // `.agent/skills` 或 `skills`，`.agents/` 永远不会被我们锁上。对它 chmod 纯属多余——
+        // 白跑一遍递归 I/O，还会改本地开发者文件的权限位。目录不存在时 unlockDirForWrite
+        // 直接返回 false，所以本地首次 init 也不会有额外开销。
+        if (layout === 'nested') {
+            (0, file_ops_1.unlockDirForWrite)(node_path_1.default.join(opts.targetDir, '.agent', 'skills'));
+        }
         node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
         let techSynced = false;
         const techSrc = node_path_1.default.join(stackDir, 'tech.md');

package/dist/utils/file-ops.js

@@ -5,6 +5,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeLineFromFile = removeLineFromFile;
 exports.removeLineFromContent = removeLineFromContent;
+exports.unlockDirForWrite = unlockDirForWrite;
+exports.lockDirReadonly = lockDirReadonly;
+exports.forceRemove = forceRemove;
+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");
@@ -43,3 +47,77 @@ function removeLineFromContent(content, pattern) {
         changed: filtered.length !== lines.length,
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// 目录权限：沙箱 skill 目录被刻意锁成只读，写入前须解锁、写完须锁回。
+//
+// 背景：老 update-skills.sh 同步末尾 `chmod -R a=rX "$TARGET_DIR"`（:241）把
+// skills 锁成只读——skills 是平台下发的资产，不该被用户/agent 手改；下一轮同步
+// 开头再 `chmod -R u+w`（:160-165）解锁。目录 owner 是沙箱当前用户，虽无写位但
+// 有权改权限，所以不需要 sudo（沙箱容器带 no_new_privileges，sudo 本就被禁）。
+//
+// 放在 file-ops 而非 sandbox-skills：coding-steering 与 sandbox-skills 两条写入
+// 路径都要用，避免其中一方 import 另一方造成方向混乱。
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 解锁目录使其可写（`chmod -R u+w`）。
+ *
+ * 写入被只读锁保护的目录前必须调用，否则 `fs.cpSync` / `fs.rmSync` 报 EACCES。
+ * 只加 owner 写位、不动 g/o，与老链路一致。目录不存在直接返回 false（调用方
+ * 通常紧接着 mkdir）。失败只 debug 不抛：解锁是尽力而为，真写不进去让后续
+ * 写操作自己报错，错误信息更具体。
+ */
+function unlockDirForWrite(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)('chmod', ['-R', 'u+w', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: chmod -R u+w ${dir} failed: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * 把目录锁成只读（`chmod -R a=rX`），对齐 update-skills.sh:241。
+ *
+ * `a=rX`：所有人只读；`X` 是大写，只给目录和「原本已有执行位」的文件加 x，
+ * 不会把 SKILL.md 变成可执行。会连 owner 写位一并清掉，所以下一轮写入前必须
+ * {@link unlockDirForWrite}。
+ *
+ * **调用时机必须是全部写入完成之后**——锁上就写不进去了。
+ */
+function lockDirReadonly(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)('chmod', ['-R', 'a=rX', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: chmod -R a=rX ${dir} failed: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * 强制删除文件或目录，三层兜底：`chmod -R u+w` → `rm -rf` → `fs.rmSync`。
+ *
+ * 为什么不能直接 `fs.rmSync`：删条目需要**父目录**写权限，而 skill 目录常处于
+ * 只读锁下；另外老 update.sh 曾以 root 跑过，可能留下异主文件（如 root-owned 的
+ * `.last-update`），`rmSync{force:true}` 只忽略 ENOENT、遇 EACCES 仍抛。
+ * shell `rm -rf` 对异主文件 / 怪符号链接比 rmSync 宽容，故作主档。
+ */
+function forceRemove(target) {
+    if (!node_fs_1.default.existsSync(target))
+        return;
+    unlockDirForWrite(target);
+    try {
+        (0, node_child_process_1.execFileSync)('rm', ['-rf', target], { stdio: ['ignore', 'ignore', 'pipe'] });
+        if (!node_fs_1.default.existsSync(target))
+            return;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: rm -rf ${target} failed: ${err.message}`);
+    }
+    node_fs_1.default.rmSync(target, { recursive: true, force: true });
+}

package/dist/utils/sandbox-skills.js

@@ -6,49 +6,60 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractLaneFromTgzKey = extractLaneFromTgzKey;
 exports.syncSandboxSkills = syncSandboxSkills;
 exports.validateSandboxSyncOpts = validateSandboxSyncOpts;
-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 npm_pack_1 = require("../utils/npm-pack");
 const error_1 = require("../utils/error");
 const logger_1 = require("../utils/logger");
-/**
- * 覆盖式清空目录，权限兜底：`chmod -R u+w` → `rm -rf` → `fs.rmSync`。
- *
- * 为什么要 chmod：沙箱里 skill 目录 owner 是当前用户 (gem)，但老
- * `update-skills.sh` 会显式 `chmod -R a-w` 把 skill 目录锁只读（防用户改 skill 内容）。
- * gem 是 owner 但没 write 权限，unlink 里面文件挂 EACCES；shell `rm -rf` 也过不去。
- * 因为 gem 是 owner，`chmod -R u+w` 能自己给自己加写权限（不需要 sudo，绕过沙箱
- * "no new privileges" 容器 flag）。
- */
-function forceRemoveDir(dir) {
-    if (!node_fs_1.default.existsSync(dir))
-        return;
-    // 先 chmod -R u+w 恢复写权限（应对老 update.sh 的 `chmod -R a-w` 只读锁）
-    try {
-        (0, node_child_process_1.execFileSync)('chmod', ['-R', 'u+w', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
-    }
-    catch (err) {
-        (0, logger_1.debug)(`sandbox-skills: chmod -R u+w ${dir} failed: ${err.message}`);
-    }
-    // 主档：shell rm -rf
-    try {
-        (0, node_child_process_1.execFileSync)('rm', ['-rf', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
-        if (!node_fs_1.default.existsSync(dir))
-            return;
-    }
-    catch (err) {
-        (0, logger_1.debug)(`sandbox-skills: rm -rf ${dir} failed: ${err.message}`);
-    }
-    // Fallback：Node fs.rmSync 尽力而为
-    node_fs_1.default.rmSync(dir, { recursive: true, force: true });
-}
+const file_ops_1 = require("../utils/file-ops");
 const PACKAGE_BY_TYPE = {
     miaoda: '@lark-apaas/coding-miaoda-sandbox-skills',
     'miaoda-modern': '@lark-apaas/coding-miaoda-sandbox-skills',
     'miaoda-design': '@lark-apaas/coding-miaoda-sandbox-skills',
     openclaw: '@lark-apaas/coding-openclaw-sandbox-skills',
 };
+/**
+ * 目标根目录下**永不删除**的控制文件（对齐 `update-skills.sh` 的删除白名单）：
+ *   - `.keep`        沙箱级「冻结 skills」开关，存在即整体跳过同步（见 {@link syncSandboxSkills}）
+ *   - `.config`      沙箱级 tgzKey 覆盖，feida-ai 的 `enableConfigFileOverride` 读它
+ *                    （`getKeepFileTgzKey` → `.agent/skills/.config`），删了会让版本钉死失效
+ *   - `.last-update` 同步时间戳，feida-ai freshness 检查读它；每轮末尾会重写，列进来只是语义完备
+ */
+const PRESERVED_ENTRIES = new Set(['.keep', '.config', '.last-update']);
+/** `.keep` 存在时整体跳过同步的标记文件名，语义同 `update-skills.sh:149`。 */
+const KEEP_FILE = '.keep';
+/**
+ * rsync 式对齐：删掉目标里「源包已不提供」的顶层条目，对齐 `update-skills.sh:196-218`。
+ *
+ * 与整目录清空的区别（后者是本函数取代的旧实现）：
+ *   - 保住 {@link PRESERVED_ENTRIES} 里的控制文件
+ *   - 保住 `steering/` 子树 —— 它由 handler 层的 syncCodingSteering 独占管理
+ *     （`update-skills.sh:207` 平铺型分支同样明确「归 miaoda CLI 管，update.sh 不删不覆盖」）
+ *
+ * 只处理顶层：源包内容本身就是「一个 skill 一个顶层目录」，逐文件比对没有额外收益。
+ */
+function pruneStaleEntries(skillsRoot, sourceTopEntries) {
+    if (!node_fs_1.default.existsSync(skillsRoot))
+        return [];
+    const deleted = [];
+    for (const entry of node_fs_1.default.readdirSync(skillsRoot)) {
+        if (PRESERVED_ENTRIES.has(entry) || entry === 'steering')
+            continue;
+        if (sourceTopEntries.has(entry))
+            continue;
+        const target = node_path_1.default.join(skillsRoot, entry);
+        try {
+            // forceRemove 的 chmod→rm -rf→rmSync 三层兜底对文件同样适用：
+            // 老 update.sh 以 root 跑过、且会 chmod -R 锁只读，直接 rmSync 会 EACCES
+            (0, file_ops_1.forceRemove)(target);
+            deleted.push(entry);
+        }
+        catch (err) {
+            (0, logger_1.debug)(`sandbox-skills: prune ${entry} failed: ${err.message}`);
+        }
+    }
+    return deleted;
+}
 // 合并包内的业务线子目录（miaoda / miaoda-modern / miaoda-design）；shared 单独处理。
 const BUSINESS_LINE_BY_TYPE = {
     miaoda: 'miaoda',
@@ -88,8 +99,15 @@ function extractLaneFromTgzKey(tgzKey) {
 /**
  * 主流程：按 type 拉包 + sync 到目标目录。
  *
- * sync 策略：**覆盖式写入 + 老文件清理**，对齐老 cp-skills.sh 行为
- * （`rm -rf $TARGET; mkdir -p $TARGET; cp -r ...`）。
+ * sync 策略：**rsync 式对齐**，逐条对应线上真实跑的 `update-skills.sh`（不是
+ * `cp-skills.sh`——那个脚本线上不执行，日志里的 `copied/skipped/deleted` 出自前者）：
+ *   1. 目标目录有 `.keep` → 整体跳过（`update-skills.sh:149`）
+ *   2. 覆盖式写入源包提供的顶层条目
+ *   3. 删掉源包已不提供的顶层条目（{@link pruneStaleEntries}），但保住
+ *      {@link PRESERVED_ENTRIES} 与 `steering/`
+ *
+ * 不用整目录清空：那会删掉 `.config`（沙箱级 tgzKey 覆盖）、`.keep`（冻结开关）
+ * 和 handler 层刚写的 `steering/`，而老链路对这三者都有保护。
  */
 function syncSandboxSkills(opts) {
     const targetDir = node_path_1.default.resolve(opts.targetDir ?? process.cwd());
@@ -137,13 +155,33 @@ function syncSandboxSkills(opts) {
         const skillsRoot = opts.type === 'openclaw'
             ? node_path_1.default.join(targetDir, 'skills')
             : node_path_1.default.join(targetDir, '.agent', 'skills');
-        // 覆盖式：清空目标 skill 根目录（对齐 cp-skills.sh 行为，避免遗留老 skill）
-        // 用 forceRemoveDir 兜底：老沙箱可能残留其他用户写的 stale 文件（例如老 update.sh
-        // 以 root 跑，写下 root owned 的 `.last-update`），fs.rmSync {force:true} 遇到 EACCES
-        // 会 throw。见 forceRemoveDir 注释。
-        forceRemoveDir(skillsRoot);
+        // `.keep` 短路：对齐 update-skills.sh:149-152，沙箱侧放了这个文件即表示
+        // 「我手改过 skills，别覆盖我」，整体跳过同步（含 steering —— 调用方看到
+        // skipped 就不该再往下写）。
+        if (node_fs_1.default.existsSync(node_path_1.default.join(skillsRoot, KEEP_FILE))) {
+            (0, logger_1.debug)(`sandbox-skills: ${KEEP_FILE} found in ${skillsRoot}, skip sync`);
+            return {
+                packageName,
+                version: fetched.version,
+                lane,
+                syncedTop: [],
+                deleted: [],
+                skippedByKeepFile: true,
+                targetDir: skillsRoot,
+            };
+        }
+        // 写入前解锁，对齐 update-skills.sh:160-165：
+        //   上一轮同步末尾会 chmod -R a=rX 锁只读（见 file-ops 的 lockDirReadonly），
+        //   不先解锁，下面 fs.cpSync 覆盖已存在的 skill 目录必 EACCES。
+        // 只加 u+w（不动 g/o），与老链路一致；owner 是沙箱当前用户，无需 sudo。
+        (0, file_ops_1.unlockDirForWrite)(skillsRoot);
         node_fs_1.default.mkdirSync(skillsRoot, { recursive: true });
         const syncedTop = [];
+        // 源包提供的全部顶层条目 —— prune 的保留集。与 syncedTop 分开维护：syncedTop 是
+        // 「本轮实际写入」，用于对外汇报；prune 只能依据「源包提供了什么」来判断 stale，
+        // 两者一旦哪天再次分叉（比如某分支又加了跳过写入的条件），拿 syncedTop 当保留集
+        // 就会把没重写的条目误判成 stale 删掉、下一轮再写回来，反复抖动。
+        const sourceTop = new Set();
         if (businessLine !== null) {
             // 合并包 miaoda/miaoda-modern/miaoda-design：cp <extractDir>/<business-line>/* 到 target
             const sourceDir = node_path_1.default.join(fetched.extractDir, businessLine);
@@ -151,6 +189,7 @@ function syncSandboxSkills(opts) {
                 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);
                 }
@@ -158,17 +197,21 @@ function syncSandboxSkills(opts) {
             else {
                 (0, logger_1.debug)(`sandbox-skills: source dir ${sourceDir} not found in package (skipped)`);
             }
-            // shared：sync 合并包内 shared/* 到 target（对齐老 build.sh 的 shared 分发行为）
+            // 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）。
             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);
-                    if (node_fs_1.default.existsSync(to)) {
-                        // shared 命中已存在的 skill（如同名）— 保留业务线版本，跳过 shared（对齐老 build.sh：shared 是补丁，同名不覆盖）
-                        (0, logger_1.debug)(`sandbox-skills: shared/${entry} conflicts with business-line skill, skipped`);
-                        continue;
-                    }
+                    sourceTop.add(entry);
                     node_fs_1.default.cpSync(from, to, { recursive: true });
                     syncedTop.push(entry);
                 }
@@ -184,10 +227,15 @@ function syncSandboxSkills(opts) {
                 if (!stat.isDirectory())
                     continue;
                 const to = node_path_1.default.join(skillsRoot, entry);
+                sourceTop.add(entry);
                 node_fs_1.default.cpSync(from, to, { recursive: true });
                 syncedTop.push(entry);
             }
         }
+        // rsync 式收尾：删掉源包已不提供的顶层条目（对齐 update-skills.sh 的 deleted）。
+        // 保留集用 sourceTop（源包提供的全部）而非 syncedTop（本轮实际写入的）——原因见
+        // sourceTop 声明处的注释：否则 shared skill 会被反复删了又写。
+        const deleted = pruneStaleEntries(skillsRoot, sourceTop);
         // 写 .last-update 时间戳（对齐老 update-skills.sh；供 feida-ai freshness 检查用）
         const lastUpdatePath = node_path_1.default.join(skillsRoot, '.last-update');
         node_fs_1.default.writeFileSync(lastUpdatePath, String(Date.now()));
@@ -195,6 +243,8 @@ function syncSandboxSkills(opts) {
             packageName,
             version: fetched.version,
             lane,
+            deleted,
+            skippedByKeepFile: false,
             syncedTop,
             targetDir: skillsRoot,
         };

package/package.json

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