@lark-apaas/miaoda-cli 0.1.6 → 0.1.7-alpha.785a451

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

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * nestjs-react-fullstack stack 的 sync 规则。
+ *
+ * 跟沙箱里 `npm run upgrade → npx fullstack-cli sync --disable-gen-openapi` 行为对齐
+ * （fullstack-cli/src/config/sync.ts），新增的 miaoda-cli 本地开发规则单独标注。
+ *
+ * 改这里请同步把 user app 端到端 smoke 跑一次（init → sync → npm run dev）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_CONFIG = void 0;
+const fullstack_cli_pin_1 = require("../../config/fullstack-cli-pin");
+exports.SYNC_CONFIG = {
+    sync: [
+        // ===== fullstack-cli sync 同款规则（对齐沙箱行为） =====
+        // 1. 派生 scripts 目录（包含 dev.sh / dev-local.js / dev.js / build.sh / run.sh /
+        //    lint.js / prune-smart.js / hooks/run-precommit.js；directory rule 自动给 .sh +x）
+        {
+            type: 'directory',
+            from: 'scripts',
+            to: 'scripts',
+            overwrite: true,
+        },
+        // 1a. 同步 .githooks 目录（hook 入口，可执行 sh 脚本）
+        {
+            type: 'directory',
+            from: '.githooks',
+            to: '.githooks',
+            overwrite: true,
+        },
+        // 1b. scripts.prepare：npm install 后自动激活 git hooks（原生 git，无第三方依赖）
+        //     直接写 core.hooksPath，并保底给 pre-commit 加执行位；非 git 仓库下静默退出
+        {
+            type: 'add-script',
+            name: 'prepare',
+            command: 'chmod +x .githooks/pre-commit 2>/dev/null; git config core.hooksPath .githooks 2>/dev/null || true',
+            overwrite: false,
+        },
+        // 1c. scripts.precommit = pre-commit 真正的执行体（跑 npm run lint）
+        {
+            type: 'add-script',
+            name: 'precommit',
+            command: 'node scripts/hooks/run-precommit.js',
+            overwrite: false,
+        },
+        // 2. 智能合并 nest-cli.json 配置（保留用户自定义的 assets、plugins 等）
+        {
+            type: 'merge-json',
+            from: 'nest-cli.json',
+            to: 'nest-cli.json',
+            arrayMerge: {
+                'compilerOptions.assets': { key: 'include' },
+                'compilerOptions.plugins': { key: 'name' },
+            },
+        },
+        // 3. 删除 .swc 缓存目录（如果存在）
+        {
+            type: 'delete-directory',
+            to: '.swc',
+        },
+        // 4. 从 .gitignore 中移除 package-lock.json
+        {
+            type: 'remove-line',
+            to: '.gitignore',
+            pattern: 'package-lock.json',
+        },
+        // 5. 注册 postinstall 脚本，自动恢复 action plugins。
+        //    用 npx -y 形式而不是裸 fullstack-cli：用户项目的 deps 没有 fullstack-cli，
+        //    bare 形式在新机器（PATH 没全局 fullstack-cli）下 npm i 立即 ENOENT。
+        //    fullstack-cli 版本临时钉到 FULLSTACK_CLI_PIN_SPEC，避免 npx 走 latest 碰外部回归版本。
+        {
+            type: 'add-script',
+            name: 'postinstall',
+            command: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
+            overwrite: false,
+        },
+        // 5a. 迁移已有应用的老形式 postinstall（裸 fullstack-cli → npx -y 钉版）。
+        //     patch-script 只在脚本以指定前缀开头时改写，用户真正手改过的脚本保持原样。
+        {
+            type: 'patch-script',
+            name: 'postinstall',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
+            ifStartsWith: 'fullstack-cli action-plugin init',
+        },
+        // 5b. 迁移已有应用 npx 未钉版的 postinstall —— sync 之前的版本生成的是
+        //     `npx -y @lark-apaas/fullstack-cli action-plugin init`（无版本号），现在统一钉版。
+        {
+            type: 'patch-script',
+            name: 'postinstall',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} action-plugin init`,
+            ifStartsWith: 'npx -y @lark-apaas/fullstack-cli action-plugin init',
+        },
+        // 5c. gen:db-schema —— 把裸 `fullstack-cli gen-db-schema` 迁到钉版 npx。
+        //     这条只在 user app 自己 package.json 已经有 gen:db-schema 时才动（patch-script
+        //     语义），新模板里如果有就一并升级。
+        {
+            type: 'patch-script',
+            name: 'gen:db-schema',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} gen-db-schema`,
+            ifStartsWith: 'fullstack-cli gen-db-schema',
+        },
+        // 6. 替换 drizzle.config.ts（仅当文件存在时）
+        {
+            type: 'file',
+            from: 'drizzle.config.ts',
+            to: 'drizzle.config.ts',
+            overwrite: true,
+            onlyIfExists: true,
+        },
+        // 7. 确保 .gitignore 包含 .agent/ 目录
+        {
+            type: 'add-line',
+            to: '.gitignore',
+            line: '.agent/',
+        },
+        // 8. 同步 .spark_project 配置文件（总是覆盖）
+        {
+            type: 'file',
+            from: '.spark_project',
+            to: '.spark_project',
+            overwrite: true,
+        },
+        // 9. 把模板版本的 lint 脚本替换为支持 --files 的 runner
+        //    只识别平台模板生成的 `concurrently ...` 形态，用户真正改写过的脚本保持原样
+        {
+            type: 'patch-script',
+            name: 'lint',
+            to: 'node ./scripts/lint.js',
+            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）；
+        //     本地走 miaoda app sync 兜底 + dev-local.js。
+        {
+            type: 'patch-script',
+            name: 'dev',
+            to: './scripts/dev.sh',
+            ifStartsWith: 'npm run upgrade && ',
+        },
+        // 11. 把 `upgrade` 脚本里裸 `fullstack-cli sync` 改成钉版 npx。
+        //     跟 postinstall 同款根因：fullstack-cli 不是用户应用的 dep，新机器无全局命令会 ENOENT。
+        {
+            type: 'patch-script',
+            name: 'upgrade',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
+            ifStartsWith: 'fullstack-cli sync',
+        },
+        // 11a. 迁移已有 npx 未钉版的 upgrade
+        {
+            type: 'patch-script',
+            name: 'upgrade',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
+            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
+        //     用于 agent 在本地稳定调试，不受任何 env 影响。
+        {
+            type: 'add-script',
+            name: 'dev:local',
+            command: 'node ./scripts/dev-local.js',
+            overwrite: false,
+        },
+        // M2. tsconfig.node.json 合并 watchOptions.preserveWatchOutput —— tsc --watch 默认每次
+        //     重编译都会 clear screen + scrollback，本地 nest start --watch 跑下来日志全没。打开
+        //     preserveWatchOutput 让 watch 模式追加而不是清屏。模板只放需要 merge 的几个字段，
+        //     不动用户的 compilerOptions / include / exclude。
+        {
+            type: 'merge-json',
+            from: 'tsconfig.node.json',
+            to: 'tsconfig.node.json',
+        },
+    ],
+};
+exports.default = exports.SYNC_CONFIG;

package/dist/config/sync.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * SyncRule 类型定义 —— miaoda app sync 的核心抽象。
+ *
+ * 完整搬自 @lark-apaas/fullstack-cli（packages/tools/fullstack-cli/src/config/sync.ts），
+ * 保持 rule shape 与 fullstack-cli 严格一致。沙箱里跑的 `npm run upgrade →
+ * npx fullstack-cli sync` 走 fullstack-cli 一侧；本地 `miaoda app sync` 走 miaoda-cli
+ * 一侧。两边的 apply 行为对齐，rule 配置则按 stack 拆开（每个 stack 一份
+ * upgrade/templates/<stack>/sync.config.ts）。
+ *
+ * 不同于 fullstack-cli 把 rule 全局 hardcode 在包内：miaoda-cli 把 rule 拆到 stack 级别
+ * 文件，便于 nestjs-react-fullstack / vite-react / html / design-stack 各自维护。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/app/init/install.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installDependencies = installDependencies;
+exports.resolveNpmInstallRegistry = resolveNpmInstallRegistry;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -44,18 +45,31 @@ function installDependencies(opts) {
                 return { installed: true, source: 'cache', hash, cacheZip };
             }
             (0, logger_1.log)('init', 'Cache zip extracted but node_modules/ missing or empty; falling back to npm install');
-            runNpmInstall(opts.targetDir, childStdio);
-            return { installed: true, source: 'npm', hash };
+            return runInstallSoft(opts.targetDir, childStdio, hash);
         }
         (0, logger_1.log)('init', `Cache miss for ${hash}.zip, falling back to npm install`);
-        runNpmInstall(opts.targetDir, childStdio);
-        return { installed: true, source: 'npm', hash };
+        return runInstallSoft(opts.targetDir, childStdio, hash);
     }
     if (cacheDir && !hasPkg) {
         (0, logger_1.log)('init', `${DEP_CACHE_ENV} set but no package.json in target; running npm install`);
     }
-    runNpmInstall(opts.targetDir, childStdio);
-    return { installed: true, source: 'npm' };
+    return runInstallSoft(opts.targetDir, childStdio);
+}
+/**
+ * 跑 npm install；失败不抛错，返回 source='failed' 让上层 init handler 继续走 writeSparkMeta
+ * 等后续步骤（避免 install 挂了 .spark/meta.json 没写出来，下次 init 看到半渲染状态又得重跑全套）。
+ * 失败信息通过 stderr 直出 + emit data.installError 透传给用户。
+ */
+function runInstallSoft(targetDir, stdio, hash) {
+    try {
+        runNpmInstall(targetDir, stdio);
+        return { installed: true, source: 'npm', hash };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        (0, logger_1.log)('init', `⚠ npm install failed (continuing init): ${msg}`);
+        return { installed: false, source: 'failed', hash, error: msg };
+    }
 }
 function nodeModulesUsable(targetDir) {
     const nm = node_path_1.default.join(targetDir, 'node_modules');
@@ -89,13 +103,30 @@ function extractZip(zipPath, targetDir, stdio) {
         });
     }
 }
+/**
+ * 显式钉死 npmmirror。原因：
+ *   - user 全局 `~/.npmrc` 千奇百怪（bnpm / npmjs / 自定义代理），npm config 层叠下
+ *     CLI flag 优先级最高，写在这里能盖掉所有上游配置，行为可预测。
+ *   - 模板 `_npmrc → .npmrc` 虽然项目级 registry 写得是 npmmirror，但只在 cwd 含 .npmrc
+ *     时才生效，env / CLI 层先到先得，落到这里钉死最稳。
+ *   - 字节内网 DNS 会把 npmmirror 域名透明指向公司镜像，外网就是公网阿里源；同一行配置
+ *     在两套环境都拉得到 @lark-apaas/* 私包（内网经公司镜像，外网经阿里同步过去的副本）。
+ *   - 留 `MIAODA_NPM_REGISTRY` env 应急覆盖。
+ *
+ * `miaoda app sync` 也用同款规则,通过 resolveNpmInstallRegistry() 共享。
+ */
+const NPM_INSTALL_REGISTRY_DEFAULT = 'https://registry.npmmirror.com/';
+/**
+ * 解析 miaoda 内部 npm install 命令使用的 registry。init / sync 共用。
+ * 优先级:`MIAODA_NPM_REGISTRY` env > `NPM_INSTALL_REGISTRY_DEFAULT`。
+ */
+function resolveNpmInstallRegistry() {
+    return process.env.MIAODA_NPM_REGISTRY ?? NPM_INSTALL_REGISTRY_DEFAULT;
+}
 function runNpmInstall(targetDir, stdio) {
     (0, logger_1.log)('init', `npm install in ${targetDir}...`);
-    try {
-        (0, node_child_process_1.execFileSync)('npm', ['install', '--no-audit', '--no-fund'], { cwd: targetDir, stdio });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        throw new error_1.AppError('NPM_INSTALL_FAILED', `npm install 失败: ${msg}`);
-    }
+    (0, node_child_process_1.execFileSync)('npm', ['install', '--no-audit', '--no-fund', '--registry', resolveNpmInstallRegistry()], {
+        cwd: targetDir,
+        stdio,
+    });
 }

package/dist/services/app/init/template.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.SUPPORTED_STACKS = exports.TEMPLATE_PACKAGE_BY_STACK = void 0;
+exports.SUPPORTED_STACKS = exports.TEMPLATE_PINNED_VERSION_BY_STACK = exports.TEMPLATE_PACKAGE_BY_STACK = void 0;
 exports.renderTemplate = renderTemplate;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -14,13 +14,25 @@ const logger_1 = require("../../../utils/logger");
 exports.TEMPLATE_PACKAGE_BY_STACK = {
     'vite-react': '@lark-apaas/coding-template-vite-react',
     html: '@lark-apaas/coding-template-html',
+    'nestjs-react-fullstack': '@lark-apaas/coding-template-nestjs-react-fullstack',
 };
+/**
+ * 短名 → template 包钉版表。renderTemplate 默认按这张表取版本号，表外 stack 跟 npm latest。
+ *
+ * 上线起所有 stack 跟随 latest dist-tag（保留 export + 表结构是为了紧急止血时可以一行钉版
+ * 不动 caller，例如 `'nestjs-react-fullstack': '0.1.0-alpha.6'`）。
+ * 用户显式传 `--conf '{"version": "..."}'` 仍 override 此默认值。
+ */
+exports.TEMPLATE_PINNED_VERSION_BY_STACK = {};
 exports.SUPPORTED_STACKS = Object.keys(exports.TEMPLATE_PACKAGE_BY_STACK);
-// template/ 内以下划线开头的占位文件名在渲染时改名（npm publish 会把 .gitignore / .npmrc 吞掉，
-// 模板里用 _gitignore / _npmrc 提交，渲染时再改回）。
+// template/ 内以下划线开头的占位文件名在渲染时改名。
+// 原因：
+//   1. npm pack 强制剥的：.npmrc（防 auth token 泄露）
+//   2. 沙箱平台特殊处理的：.gitignore（避免与平台仓库 .gitignore 冲突）
+// .env 通过 negation pattern 例外直接 ship；.env.local 完全由 lark-cli +env-pull
+// 运行时下发，模板里不再放占位文件。
 const RENAME_FILES = {
     _gitignore: '.gitignore',
-    '_env.local': '.env.local',
     _npmrc: '.npmrc',
 };
 function renderTemplate(opts) {
@@ -30,8 +42,13 @@ function renderTemplate(opts) {
             next_actions: [`可用 stack：${exports.SUPPORTED_STACKS.join(', ')}`],
         });
     }
-    (0, logger_1.log)('init', `Fetching ${packageName}@${opts.version ?? 'latest'}...`);
-    const fetched = (0, npm_pack_1.fetchNpmPackage)({ packageName, version: opts.version });
+    // 缺省走 latest dist-tag；表里有钉版（紧急止血时填）则用钉版；--conf.version 仍 override。
+    const pinned = Object.prototype.hasOwnProperty.call(exports.TEMPLATE_PINNED_VERSION_BY_STACK, opts.stack)
+        ? exports.TEMPLATE_PINNED_VERSION_BY_STACK[opts.stack]
+        : undefined;
+    const effectiveVersion = opts.version ?? pinned ?? 'latest';
+    (0, logger_1.log)('init', `Fetching ${packageName}@${effectiveVersion}...`);
+    const fetched = (0, npm_pack_1.fetchNpmPackage)({ packageName, version: effectiveVersion });
     try {
         const templateDir = node_path_1.default.join(fetched.extractDir, 'template');
         if (!node_fs_1.default.existsSync(templateDir)) {

package/dist/services/deploy/modern/atoms/local-release.js

@@ -10,8 +10,13 @@ const logger_1 = require("../../../../utils/logger");
  * 创建本地发布单（加锁；不挂 pipeline）。
  * 返回的 releaseId 必须由 finalizeLocalRelease 翻为终态，否则发布单一直挂着。
  */
-async function createLocalRelease(appId, version) {
-    return (0, index_1.createLocalRelease)({ appID: appId, version });
+async function createLocalRelease(appId, version, extra) {
+    return (0, index_1.createLocalRelease)({
+        appID: appId,
+        version,
+        checkPointVersion: extra?.checkPointVersion,
+        commitID: extra?.commitID,
+    });
 }
 /**
  * 把本地发布单翻为终态。Finished / Failed 由 pipeline 视上下游结果决定。

package/dist/services/deploy/modern/pipelines/local.js

@@ -43,7 +43,10 @@ async function localBuildLocalPublishPipeline(opts) {
         });
     }
     (0, logger_1.log)('deploy', 'Creating local release...');
-    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version);
+    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
+        checkPointVersion: opts.checkPointVersion,
+        commitID: opts.commitID,
+    });
     try {
         (0, logger_1.log)('deploy', 'Uploading artifacts...');
         await (0, index_1.uploadArtifacts)({ projectDir: ctx.projectDir, appId: ctx.appId, data });

package/dist/utils/coding-steering.js

@@ -9,67 +9,146 @@ const node_path_1 = __importDefault(require("node:path"));
 const npm_pack_1 = require("../utils/npm-pack");
 const logger_1 = require("../utils/logger");
 const STEERING_PACKAGE = '@lark-apaas/coding-steering';
+function inferMode() {
+    // process.env.SANDBOX_ID 非空 → 沙箱；其他（undefined / 空串）→ 本地
+    return process.env.SANDBOX_ID ? 'sandbox' : 'local';
+}
 /**
- * 把 coding-steering 包内 _common/skills + <stack>/skills 同步到 <targetDir>/.agent/steering/skills/，
- * 同名 stack 子目录覆盖 _common。tech.md 存在时也同步到 .agent/steering/tech.md。
+ * 把 coding-steering 包内 <stack>/skills_common + 专有层（skills 或 skills_local）同步到
+ * user app。
+ *
+ * 包内目录约定（每个 stack 三层）：
+ *   <stack>/skills_common  → 沙箱 + 本地都下发的共有层
+ *   <stack>/skills         → 沙箱专有（沙箱端 update-skills.sh / SANDBOX_ID 非空时拿）
+ *   <stack>/skills_local   → 本地专有（本地 dev / agent 环境拿）
+ *
+ * 下发组合（mode）：
+ *   mode='sandbox' → skills_common + skills
+ *   mode='local'   → skills_common + skills_local
+ *
+ * 目标路径形态（outputLayout）：
+ *   'nested' (默认，向后兼容)：拷到 .agent/skills/steering/<stack>/skills/，tech.md 同目录
+ *   'flat'：拷到 .agents/skills/（平铺），tech.md → .agents/tech.md，并创建 .claude/skills
+ *           软链指向 ../.agents/skills 让 Claude Code 识别同一份
+ *
+ * 同名 skill 覆盖顺序：common < 专有（专有覆盖 common 同名）。mode 缺省按 SANDBOX_ID env
+ * 推断（沙箱平台运行时注入应用所属沙箱 ID；空 / undefined 则视为本地）。
  *
  * 纯本地 atom（pull npm package + 拷贝文件），不属于任何 cli 域；放在 utils 让
  * app init handler 与独立 skills sync handler 都能复用。
  */
 function syncCodingSteering(opts) {
     const logPrefix = opts.logPrefix ?? 'skills';
-    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${opts.version ?? 'latest'}...`);
+    const effectiveVersion = opts.version ?? 'latest';
+    const mode = opts.mode ?? inferMode();
+    const layout = opts.outputLayout ?? 'nested';
+    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${effectiveVersion} (mode=${mode}, layout=${layout})...`);
     const fetched = (0, npm_pack_1.fetchNpmPackage)({
         packageName: STEERING_PACKAGE,
-        version: opts.version,
+        version: effectiveVersion,
     });
     try {
         const steeringRoot = node_path_1.default.join(fetched.extractDir, 'steering');
         const stackDir = node_path_1.default.join(steeringRoot, opts.stack);
-        const commonSkillsDir = node_path_1.default.join(steeringRoot, '_common', 'skills');
-        // steering 落到 .agent/skills/steering/<stack>/。.agent/skills/ 是 agent skills 的
-        // 公共容器，steering 是其中一个 producer，<stack> 再做命名空间隔离。内部仍保留
-        // 包内 steering/<stack>/skills/ 的结构，便于按"包内子目录 → 本地子目录"一一对应排查。
-        const dstRoot = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack);
-        const dstSkillsDir = node_path_1.default.join(dstRoot, 'skills');
+        // 目标路径按 layout 切：
+        //   nested → .agent/skills/steering/<stack>/{skills, tech.md}（老链路、stack 命名空间）
+        //   flat   → .agents/{skills, tech.md}（平铺，无 stack 命名空间，跟 .claude/skills 软链对齐）
+        const { dstSkillsDir, dstTechPath } = layout === 'flat'
+            ? {
+                dstSkillsDir: node_path_1.default.join(opts.targetDir, '.agents', 'skills'),
+                dstTechPath: node_path_1.default.join(opts.targetDir, '.agents', 'tech.md'),
+            }
+            : {
+                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'),
+            };
         node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
         let techSynced = false;
         const techSrc = node_path_1.default.join(stackDir, 'tech.md');
         if (node_fs_1.default.existsSync(techSrc)) {
-            node_fs_1.default.copyFileSync(techSrc, node_path_1.default.join(dstRoot, 'tech.md'));
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(dstTechPath), { recursive: true });
+            node_fs_1.default.copyFileSync(techSrc, dstTechPath);
             techSynced = true;
         }
         const synced = [];
-        // 先拷 _common/skills/，再拷 <stack>/skills/。stack 同名覆盖 common
-        if (node_fs_1.default.existsSync(commonSkillsDir)) {
-            for (const name of node_fs_1.default.readdirSync(commonSkillsDir)) {
-                const src = node_path_1.default.join(commonSkillsDir, name);
-                if (!node_fs_1.default.statSync(src).isDirectory())
-                    continue;
-                copyDir(src, node_path_1.default.join(dstSkillsDir, name));
-                synced.push(`_common/skills/${name}`);
-            }
-        }
-        const stackSkillsDir = node_path_1.default.join(stackDir, 'skills');
-        if (node_fs_1.default.existsSync(stackSkillsDir)) {
-            for (const name of node_fs_1.default.readdirSync(stackSkillsDir)) {
-                const src = node_path_1.default.join(stackSkillsDir, name);
+        // 顺序拷贝，后者覆盖前者：skills_common 铺底，专有层（skills 或 skills_local）覆盖同名
+        const exclusiveLayer = mode === 'sandbox' ? 'skills' : 'skills_local';
+        const layers = [
+            { dir: node_path_1.default.join(stackDir, 'skills_common'), label: `${opts.stack}/skills_common` },
+            { dir: node_path_1.default.join(stackDir, exclusiveLayer), label: `${opts.stack}/${exclusiveLayer}` },
+        ];
+        for (const layer of layers) {
+            if (!node_fs_1.default.existsSync(layer.dir))
+                continue;
+            for (const name of node_fs_1.default.readdirSync(layer.dir)) {
+                const src = node_path_1.default.join(layer.dir, name);
                 if (!node_fs_1.default.statSync(src).isDirectory())
                     continue;
                 const dst = node_path_1.default.join(dstSkillsDir, name);
                 if (node_fs_1.default.existsSync(dst))
                     node_fs_1.default.rmSync(dst, { recursive: true, force: true });
                 copyDir(src, dst);
-                synced.push(`${opts.stack}/skills/${name}`);
+                synced.push(`${layer.label}/${name}`);
             }
         }
-        (0, logger_1.log)(logPrefix, `Synced ${String(synced.length)} skill(s), tech.md ${techSynced ? 'yes' : 'no'}`);
-        return { version: fetched.version, syncedSkills: synced, techSynced };
+        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})`);
+        return {
+            version: fetched.version,
+            syncedSkills: synced,
+            techSynced,
+            ...(claudeSkillsLink !== undefined ? { claudeSkillsLink } : {}),
+        };
     }
     finally {
         fetched.cleanup();
     }
 }
+/**
+ * flat layout 下创建 `<targetDir>/.claude/skills` 软链 → `../.agents/skills`，让 Claude Code
+ * 默认的 skills 加载路径跟 user app 的 .agents/skills 是同一份内容。
+ *
+ * 用相对路径软链（不是 absolute）—— user app 移动目录 / clone 到别处不会断链。
+ *
+ * 处理 4 种已有状态：
+ *   - 已是软链且指向对的：noop
+ *   - 已是软链但指错地方：删旧的，建新的（updated）
+ *   - 已是普通目录 / 文件：不覆盖，警告并跳过（conflict）—— 用户可能手动放了别的 skills
+ *   - 不存在：建新的（created）
+ */
+function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
+    const linkPath = node_path_1.default.join(targetDir, '.claude', 'skills');
+    const linkTarget = node_path_1.default.join('..', '.agents', 'skills');
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(linkPath), { recursive: true });
+    let existing = null;
+    try {
+        existing = node_fs_1.default.lstatSync(linkPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    if (existing === null) {
+        node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
+        (0, logger_1.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink created)`);
+        return 'created';
+    }
+    if (existing.isSymbolicLink()) {
+        const current = node_fs_1.default.readlinkSync(linkPath);
+        if (current === linkTarget) {
+            return 'noop';
+        }
+        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})`);
+        return 'updated';
+    }
+    (0, logger_1.log)(logPrefix, `  ⚠ .claude/skills 已是普通目录/文件，跳过软链创建`);
+    return 'conflict';
+}
 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/file-ops.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeLineFromFile = removeLineFromFile;
+exports.removeLineFromContent = removeLineFromContent;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("./logger");
+/**
+ * 从文件中移除匹配的行。
+ * 搬自 @lark-apaas/fullstack-cli/src/utils/file-ops.ts，行为完全对齐：精确匹配（trim 后）。
+ *
+ * @returns 是否真的移除过内容
+ */
+function removeLineFromFile(filePath, pattern, logPrefix = 'sync') {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${node_path_1.default.basename(filePath)} (not found)`);
+        return false;
+    }
+    const content = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    const trimmed = pattern.trim();
+    const lines = content.split('\n');
+    const filtered = lines.filter((line) => line.trim() !== trimmed);
+    if (filtered.length === lines.length) {
+        (0, logger_1.log)(logPrefix, `  ○ ${node_path_1.default.basename(filePath)} (pattern not found: ${pattern})`);
+        return false;
+    }
+    node_fs_1.default.writeFileSync(filePath, filtered.join('\n'));
+    (0, logger_1.log)(logPrefix, `  ✓ ${node_path_1.default.basename(filePath)} (removed: ${pattern})`);
+    return true;
+}
+/**
+ * 纯函数版本：便于单测，不读写文件。
+ */
+function removeLineFromContent(content, pattern) {
+    const trimmed = pattern.trim();
+    const lines = content.split('\n');
+    const filtered = lines.filter((line) => line.trim() !== trimmed);
+    return {
+        result: filtered.join('\n'),
+        changed: filtered.length !== lines.length,
+    };
+}

package/dist/utils/githooks.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activateGitHooks = activateGitHooks;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const logger_1 = require("../utils/logger");
+/**
+ * 把 `.githooks/` 注册为本仓库的 git hooks 目录，让 pre-commit 等 hook 立即生效。
+ *
+ * 三件事，都先检查再写（幂等）：
+ *   1. `.git` 存在（非 git 仓库直接跳）
+ *   2. `.githooks/pre-commit` 存在（没 hook 文件直接跳，且不写 git config 防止误指空目录）
+ *   3. `core.hooksPath` 是 `.githooks`（已经是就短路）
+ *
+ * 镜像 fullstack-cli `src/commands/sync/activate-hooks.ts`，逻辑保持一致；本地用户
+ * 通过 `miaoda app upgrade` 走的这一份，沙箱用户走 `npm run upgrade`（fullstack-cli sync）
+ * 那一份，两条通道结果应等价。
+ */
+function activateGitHooks(targetDir) {
+    if (!node_fs_1.default.existsSync(node_path_1.default.join(targetDir, '.git'))) {
+        return { action: 'skipped-no-git' };
+    }
+    const hookFile = node_path_1.default.join(targetDir, '.githooks', 'pre-commit');
+    if (!node_fs_1.default.existsSync(hookFile)) {
+        return { action: 'skipped-no-hook-file' };
+    }
+    // copyFileSync 不保留 mode，确保 +x（重要：没 +x 时 git 不会执行 hook）
+    const currentMode = node_fs_1.default.statSync(hookFile).mode & 0o777;
+    if ((currentMode & 0o111) !== 0o111) {
+        node_fs_1.default.chmodSync(hookFile, 0o755);
+    }
+    const probe = (0, node_child_process_1.spawnSync)('git', ['config', '--get', 'core.hooksPath'], {
+        cwd: targetDir,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const currentHooksPath = probe.stdout.toString().trim();
+    if (currentHooksPath === '.githooks') {
+        return { action: 'already-active' };
+    }
+    const res = (0, node_child_process_1.spawnSync)('git', ['config', 'core.hooksPath', '.githooks'], {
+        cwd: targetDir,
+        stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    if (res.status !== 0) {
+        const stderr = res.stderr.toString().trim();
+        (0, logger_1.log)('githooks', `⚠️  failed to set core.hooksPath: ${stderr}`);
+        return { action: 'skipped-no-git' };
+    }
+    (0, logger_1.log)('githooks', `activated: core.hooksPath = .githooks`);
+    return { action: 'activated' };
+}