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

package/dist/config/sync-configs/design-stack.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * design-stack 的 sync 规则。
+ *
+ * design-stack 是 SSR-only 全栈 stack（design scene，MIAODA_APP_TYPE=4），无 nest 后端、
+ * 无数据库、无 nestjs-cli。所以规则集是 nestjs-react-fullstack 的子集：只保留
+ * scripts/.githooks/ 派生 + 基础 npm scripts，不动 nest-cli.json / drizzle / tsconfig.node.json。
+ *
+ * dev-local.js 跟 nestjs-react-fullstack 不同（单进程 npm run dev，MIAODA_APP_TYPE=4），
+ * 单独维护在 upgrade/templates/design-stack/templates/scripts/dev-local.js。
+ */
+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: [
+        // 1. 派生 scripts/（含 design 专属 dev-local.js + 通用 dev.sh / hooks/run-precommit.js）
+        {
+            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
+        {
+            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
+        {
+            type: 'add-script',
+            name: 'precommit',
+            command: 'node scripts/hooks/run-precommit.js',
+            overwrite: false,
+        },
+        // 2. .gitignore 卫生：移除 package-lock.json + 加 .agent/
+        {
+            type: 'remove-line',
+            to: '.gitignore',
+            pattern: 'package-lock.json',
+        },
+        {
+            type: 'add-line',
+            to: '.gitignore',
+            line: '.agent/',
+        },
+        // 3. 老 npm scripts 迁移（裸 fullstack-cli → 钉版 npx）。两条 ifStartsWith 分别覆盖
+        //    "裸 fullstack-cli"（最老形态）和 "npx 未钉版" 形态，统一升到 FULLSTACK_CLI_PIN_SPEC。
+        {
+            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',
+        },
+        {
+            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',
+        },
+        {
+            type: 'patch-script',
+            name: 'upgrade',
+            to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
+            ifStartsWith: 'fullstack-cli sync',
+        },
+        {
+            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',
+        },
+        {
+            type: 'patch-script',
+            name: 'dev',
+            to: './scripts/dev.sh',
+            ifStartsWith: 'npm run upgrade && ',
+        },
+        // ===== miaoda-cli 本地开发新增规则 =====
+        // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
+        {
+            type: 'add-script',
+            name: 'dev:local',
+            command: 'node ./scripts/dev-local.js',
+            overwrite: false,
+        },
+    ],
+};
+exports.default = exports.SYNC_CONFIG;

package/dist/config/sync-configs/index.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * 按 stack 短名拿到对应的 SyncConfig + 模板源根目录。
+ *
+ * - 类型化的 SyncConfig 放在 src/config/sync-configs/<stack>.ts（被 tsc 编进 dist 一起发）。
+ * - 模板资源文件放在 upgrade/templates/<stack>/templates/（cli 发布时整个目录原样 ship）。
+ *
+ * handler 拿到 stack 后，先 getSyncConfig 拿 rule 列表，再 getStackTemplatesRoot 拿模板根，
+ * 一起喂给 applySyncRules。
+ *
+ * 新加 stack：
+ *   1. src/config/sync-configs/<stack>.ts 里 export default SYNC_CONFIG
+ *   2. upgrade/templates/<stack>/templates/ 下放对应资源文件
+ *   3. 在 STACK_REGISTRY 里加一条
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSyncConfig = getSyncConfig;
+exports.getStackTemplatesRoot = getStackTemplatesRoot;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const nestjs_react_fullstack_1 = __importDefault(require("./nestjs-react-fullstack"));
+const design_stack_1 = __importDefault(require("./design-stack"));
+/**
+ * 已纳入新 sync 机制的 stack 注册表。未在表里的 stack（如老 vite-react / html）走旧的
+ * `upgrade/templates/<stack>/{files,patches}` 机制，由 sync handler 兜底。
+ */
+const STACK_REGISTRY = {
+    'nestjs-react-fullstack': nestjs_react_fullstack_1.default,
+    'design-stack': design_stack_1.default,
+};
+/** 返回该 stack 的 SyncConfig；表里没有时返回 null。 */
+function getSyncConfig(stack) {
+    return STACK_REGISTRY[stack] ?? null;
+}
+/**
+ * 计算 stack 模板资源根目录（绝对路径）。
+ *
+ * cli 发布时 upgrade/ 目录整个 ship，编译产物在 dist/ 下若干层。从当前模块向上回溯找含
+ * upgrade/ + package.json 的目录就是 cli 根。
+ *
+ * 跟 utils/platform-sync.ts 同款 pattern；保持对齐避免两边漂移。
+ */
+function getStackTemplatesRoot(stack) {
+    return node_path_1.default.join(findCliRoot(), 'upgrade', 'templates', stack, 'templates');
+}
+let cliRootCache = null;
+function findCliRoot() {
+    if (cliRootCache !== null)
+        return cliRootCache;
+    let dir = __dirname;
+    while (dir !== node_path_1.default.dirname(dir)) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, 'upgrade')) && node_fs_1.default.existsSync(node_path_1.default.join(dir, 'package.json'))) {
+            cliRootCache = dir;
+            return dir;
+        }
+        dir = node_path_1.default.dirname(dir);
+    }
+    throw new Error(`miaoda-cli root (containing upgrade/) not found from ${__dirname}`);
+}

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

@@ -44,18 +44,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 +102,22 @@ 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 应急覆盖。
+ */
+const NPM_INSTALL_REGISTRY_DEFAULT = 'https://registry.npmmirror.com/';
 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}`);
-    }
+    const registry = process.env.MIAODA_NPM_REGISTRY ?? NPM_INSTALL_REGISTRY_DEFAULT;
+    (0, node_child_process_1.execFileSync)('npm', ['install', '--no-audit', '--no-fund', '--registry', registry], {
+        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/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 })) {