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

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

@@ -6,7 +6,7 @@ const index_1 = require("../../../cli/handlers/app/index");
 const error_1 = require("../../../utils/error");
 function registerAppCommands(program, opts = {}) {
     const description = opts.includeInit
-        ? '应用元数据管理：查看 / 修改 / 初始化'
+        ? '应用元数据管理：查看 / 修改 / 初始化 / 升级平台资产'
         : '应用元数据管理：查看 / 修改';
     const appCmd = program.command('app').description(description);
     appCmd.action(() => {
@@ -21,8 +21,57 @@ function registerAppCommands(program, opts = {}) {
     registerAppUpdate(appCmd);
     if (opts.includeInit) {
         registerAppInit(appCmd);
+        registerAppSync(appCmd);
     }
 }
+function registerAppSync(parent) {
+    const cmd = parent
+        .command('sync')
+        .alias('upgrade')
+        .description('一站式同步：按 stack 的 SyncRule 全套 apply + 按钉死版本表升 @lark-apaas/* deps + npm install')
+        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .addHelpText('after', `
+别名
+  miaoda app sync 与 miaoda app upgrade 等价（upgrade 是历史别名，新调用方请用 sync）。
+
+流程
+  1. 按 stack 的 SyncRule[] 全套 apply（src/config/sync-configs/<stack>.ts 定义）：
+       directory      → 整个目录拷贝（.sh 自动 +x）
+       file           → 单文件覆盖（可选 onlyIfExists / overwrite）
+       merge-json     → JSON deep merge（可选 arrayMerge by key 去重）
+       add-script     → npm script 不存在时添加（overwrite=false 默认不覆盖）
+       patch-script   → npm script 以指定前缀开头时改写（守护用户自定义）
+       add-line       → 行不存在时追加到文件
+       remove-line    → 行存在时移除
+       delete-file/delete-directory → 删除
+     沙箱里跑的 fullstack-cli sync 走同一套 rule 类型，行为对齐；miaoda app sync 在此之上
+     补 dev:local 等本地开发独有规则。
+  2. 平台 deps 指 latest：按 handlers/app/sync.ts 里 MANAGED_PLATFORM_PACKAGES 白名单把
+     user app 已装的 @lark-apaas/* 包改写为 "latest"；表外 / 未装的不动。
+  3. activateGitHooks：core.hooksPath 一次性指向 .githooks/。
+  4. npm install --no-audit --no-fund --ignore-scripts。--ignore-scripts 是为绕开
+     action-plugin postinstall 在 npm install 时缺平台 env 的卡点（需要时再
+     FORCE_AUTHN_INNERAPI_DOMAIN=... npm install 手动跑一次）。
+
+JSON 输出
+  {"data": {"stack": "...",
+            "appliedRules": [{"type": "...", "action": "...", "path": "...", "detail": "..."}],
+            "syncedFiles": [...],
+            "mergedJsonFiles": [{"path": "...", "keys": [...]}],
+            "patchedScripts": [...],
+            "upgradedPackages": [{"name": "...", "from": "...", "to": "...", "section": "..."}]}}
+
+示例
+  $ miaoda app sync
+  $ miaoda app sync --dir /path/to/app
+  $ miaoda app upgrade        # 等价于 miaoda app sync
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleAppSync)({
+            dir: rawOpts.dir,
+        });
+    }));
+}
 function registerAppGet(parent) {
     const cmd = parent
         .command('get')
@@ -70,20 +119,28 @@ JSON 输出
 function registerAppInit(parent) {
     const cmd = parent
         .command('init')
-        .description('初始化应用代码：抓 template 渲染、装 .agent/steering/ skills、写 .spark/meta.json。.spark/meta.json 已存在则直接退出')
+        .description('初始化应用代码：抓 template 渲染、同步 upgrade/templates、装 .agent/steering/ skills、写 .spark/meta.json。.spark/meta.json 已存在则直接退出')
         .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
         .option('--conf <json>', 'init 配置 JSON。支持 {"version": "<template 版本>"} / {"steeringVersion": "<steering 版本>"}，均默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
+        .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
 幂等
   .spark/meta.json 已存在时直接退出（initialized=false, reason=already_initialized），
-  不再触发 template 渲染、不重新拉 skills、不安装依赖。
+  不再触发 template 渲染、不重新跑 upgrade/templates 同步、不重新拉 skills、不安装依赖。
   meta.json 在 init 流程最后才写，写了 = 已完整成功一次；
   上一次失败留下半渲染状态时（package.json 在但 meta.json 没在）允许重跑。
 
-应用身份（appId）
-  init 不再持久化 appId。运行端命令（deploy / file / plugin 等）始终从 MIAODA_APP_ID env 读，
-  init 阶段也无需感知 appId。
+应用身份（app_id）
+  --app-id <id>（或 MIAODA_APP_ID env）提供时写入 .spark/meta.json 的 app_id 字段；
+  未提供则不写。运行端命令（deploy / file / plugin 等）仍优先读 MIAODA_APP_ID env，
+  env 未设置时回退到 meta.json.app_id。
+
+平台同步（upgrade/templates）
+  init 内嵌一次 upgrade/templates 同步（跟 app upgrade 共用同一份 util）：
+  从 miaoda-cli 自带的 upgrade/templates/<stack>/ 同步 files/（覆盖）+ patches/
+  （JSON deep merge，含 scripts.dev:local 等）。目标 stack 未纳入 upgrade/templates/
+  时跳过（不报错）。后续要把 @lark-apaas/* 平台包统一指 latest，跑 'miaoda app upgrade'。
 
 依赖安装
   默认：npm install --no-audit --no-fund
@@ -97,11 +154,13 @@ function registerAppInit(parent) {
 JSON 输出
   已初始化：{"data": {"initialized": false, "reason": "already_initialized", "targetDir": "..."}}
   新初始化：{"data": {"initialized": true, "template": "...", "templateVersion": "...", "steeringVersion": "...",
+                     "appId": "...", "platformStackFound": true, "platformSyncedFiles": [...],
                      "installed": true, "installSource": "cache|npm|skipped", "installHash": "...", ...}}
 
 示例
   $ miaoda app init --template vite-react
-  $ miaoda app init --template vite-react --conf '{"version": "0.1.0-alpha.1"}'
+  $ miaoda app init --template nestjs-react-fullstack --app-id app_xxx
+  $ miaoda app init --template vite-react --conf '{"version": "0.1.0"}'
   $ miaoda app init --template vite-react --conf '{"steeringVersion": "0.1.0"}'
   $ miaoda app init --template vite-react --skip-install
   $ MIAODA_DEP_CACHE_DIR=/tmp/dep-cache miaoda app init --template vite-react
@@ -112,6 +171,7 @@ JSON 输出
             template: rawOpts.template,
             conf,
             skipInstall: rawOpts.skipInstall,
+            appId: rawOpts.appId,
         });
     }));
 }

package/dist/cli/commands/index.js

@@ -9,24 +9,59 @@ const index_4 = require("../../cli/commands/app/index");
 const index_5 = require("../../cli/commands/deploy/index");
 const modern_1 = require("../../cli/commands/deploy/modern");
 const index_6 = require("../../cli/commands/skills/index");
+// scene 跟 dispatcher(MIAODA_APP_TYPE)同语义层级 —— app 业务类型维度,
+// 对齐后端 devops app_common.AppType 枚举:
+//   3 = AppType_APPLICATION(全栈应用,当前仅 nestjs-react-fullstack 一个 stack)
+//   4 = AppType_DESIGN(design-stack,SSR 渲染、无业务逻辑、无数据库)
+//   7 = miaoda-cli 自定义 modern 占位(后端枚举无 7,沙箱目前不传)
+//   其它(0/1/2/5/6 / 未设)→ default(命令全开,本地 dev / CI / 兼容回退)
+// stack 维度(nestjs-react-fullstack / vite-react / ...)是正交的,
+// skills sync 内部按 .spark/meta.json.stack 拉对应 coding-steering/steering/<stack>/ 子目录。
 function resolveScene(appType, _archType) {
     if (appType === '7')
         return 'modern';
+    if (appType === '3')
+        return 'application';
+    if (appType === '4')
+        return 'design';
     return 'default';
 }
 const SCENE_REGISTRARS = {
     default: (p) => {
-        (0, index_4.registerAppCommands)(p);
+        // init / upgrade / skills 都挂出来：本地用户不需要 export MIAODA_APP_TYPE=3
+        // 就能跑 `miaoda app init` / `miaoda app upgrade` / `miaoda skills sync`。
+        // 其它 scene 的差异（design 裁 db/file，modern 拆 deploy）仍按 MIAODA_APP_TYPE 路由
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, index_5.registerDeployCommands)(p);
         (0, index_2.registerDbCommands)(p);
         (0, index_1.registerFileCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
+        (0, index_6.registerSkillsCommands)(p);
     },
     modern: (p) => {
         (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, modern_1.registerDeployCommandsModern)(p);
         (0, index_6.registerSkillsCommands)(p);
     },
+    // application scene(AppType_APPLICATION=3):
+    // 在 default 命令集基础上加 skills(按 meta.json.stack 拉对应 stack 技能)
+    // + app init(新一代应用走 init 写 .spark/meta.json)
+    application: (p) => {
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
+        (0, index_5.registerDeployCommands)(p);
+        (0, index_2.registerDbCommands)(p);
+        (0, index_1.registerFileCommands)(p);
+        (0, index_3.registerObservabilityCommands)(p);
+        (0, index_6.registerSkillsCommands)(p);
+    },
+    // design scene(AppType_DESIGN=4):design-stack 仅 SSR 渲染、无后端业务逻辑、
+    // 无数据库、无 UGC 文件。命令集裁掉 db / file,保留 deploy / observability / app(init) / skills。
+    design: (p) => {
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
+        (0, index_5.registerDeployCommands)(p);
+        (0, index_3.registerObservabilityCommands)(p);
+        (0, index_6.registerSkillsCommands)(p);
+    },
 };
 function readEnv(name) {
     const v = process.env[name]?.trim();

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

@@ -21,18 +21,33 @@ function registerSkillsCommands(program) {
 function registerSkillsSync(parent) {
     const cmd = parent
         .command('sync')
-        .description('同步 coding-steering（latest 或指定版本）到 .agent/steering/')
+        .description('同步 coding-steering（latest 或指定版本）到 user app')
         .argument('[version]', 'coding-steering 包版本或 dist-tag，缺省 latest')
         .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .option('--local', '走本地 dev / agent 输出形态：拷到 .agents/skills 平铺 + 创建 .claude/skills 软链。' +
+        '不传时退回老形态：拷到 .agent/skills/steering/<stack>/skills/（跟沙箱端 update-skills.sh 对齐）', false)
         .addHelpText('after', `
 前置要求
   当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack）
 
+输出形态（--local 切换）
+  默认（不传 --local）：
+    .agent/skills/steering/<stack>/skills/<skill>/...
+    .agent/skills/steering/<stack>/tech.md
+    （老链路，沙箱端 update-skills.sh 也输出这套结构）
+
+  传 --local：
+    .agents/skills/<skill>/...      ← 平铺，无 stack 命名空间
+    .agents/tech.md
+    .claude/skills → ../.agents/skills（软链，让 Claude Code 识别同一份）
+
 JSON 输出
-  {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false}}
+  {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false,
+            "claudeSkillsLink": "created|updated|noop|conflict"  // 仅 --local 时}}
 
 示例
   $ miaoda skills sync
+  $ miaoda skills sync --local           # 本地 dev / agent 用
   $ miaoda skills sync 0.2.0
   $ miaoda skills sync --dir ./my-app
 `);
@@ -40,6 +55,7 @@ JSON 输出
         await (0, index_1.handleSkillsSync)({
             dir: rawOpts.dir,
             version,
+            local: rawOpts.local,
         });
     }));
 }

package/dist/cli/handlers/app/index.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_STACKS = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.SUPPORTED_STACKS = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
 Object.defineProperty(exports, "handleAppUpdate", { enumerable: true, get: function () { return update_1.handleAppUpdate; } });
 var init_1 = require("./init");
 Object.defineProperty(exports, "handleAppInit", { enumerable: true, get: function () { return init_1.handleAppInit; } });
+var sync_1 = require("./sync");
+Object.defineProperty(exports, "handleAppSync", { enumerable: true, get: function () { return sync_1.handleAppSync; } });
+Object.defineProperty(exports, "handleAppUpgrade", { enumerable: true, get: function () { return sync_1.handleAppUpgrade; } });
 // commands 层渲染 help 时需要这份枚举；从 handler barrel 转发，避免 commands → services 越界
 var index_1 = require("../../../services/app/init/index");
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return index_1.SUPPORTED_STACKS; } });

package/dist/cli/handlers/app/init.js

@@ -8,13 +8,17 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../../../services/app/init/index");
 const coding_steering_1 = require("../../../utils/coding-steering");
+const logger_1 = require("../../../utils/logger");
+const githooks_1 = require("../../../utils/githooks");
+const sync_1 = require("../../../cli/handlers/app/sync");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 /**
  * miaoda app init
  *
- * 只负责本地脚手架：render template、sync skills、install deps，把 {stack, version, archType}
- * 写入 .spark/meta.json。appId 不在此处持久化——deploy 等运行端通过 MIAODA_APP_ID env 拿。
+ * 一站式本地脚手架：render template → upgrade/templates sync → skills sync → install deps，把
+ * {stack, version, archType, app_id?} 写入 .spark/meta.json。--app-id（或 MIAODA_APP_ID）提供时
+ * 持久化 app_id；运行端命令仍优先读 env，未设置时回退到 meta.json。
  *
  * 幂等：.spark/meta.json 存在即表示已完整成功一次，直接退出，不重跑任何子步骤。
  * 半渲染状态（package.json 在但 meta.json 不在）会重新跑完整流程。
@@ -50,24 +54,52 @@ async function handleAppInit(opts) {
     const version = opts.conf?.version;
     const projectName = node_path_1.default.basename(targetDir);
     const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
-    const steeringResult = (0, coding_steering_1.syncCodingSteering)({
-        stack,
-        targetDir,
-        version: opts.conf?.steeringVersion,
-        logPrefix: 'init',
-    });
+    // sync 紧跟 template 渲染之后，赶在 install 之前：
+    // 这样 directory / merge-json / add-script 等 rule 都已落地，install 出来的 lockfile
+    // 与最终态对齐；patches 还能覆盖 template 提供的同名文件。
+    const syncRunResult = (0, sync_1.runStackSync)(stack, targetDir, 'init');
+    const syncSummary = (0, sync_1.summarizeSyncResults)(syncRunResult);
+    // template 渲染下来的 @lark-apaas/* 版本可能落后 MANAGED_PLATFORM_PACKAGES 白名单，赶在
+    // install 之前统一指 latest，这样一次 npm install 就直接装最新版本，不需要 install 完再补。
+    const upgradedPackages = (0, sync_1.upgradePlatformDeps)(targetDir, 'init');
+    // skills 同步软失败：拉不到 coding-steering 包不该阻断 writeSparkMeta /
+    // activateGitHooks（之前会让 .spark/meta.json 没写，下次 init 半渲染状态又得重跑全套）。
+    let steeringResult;
+    let steeringError;
+    try {
+        steeringResult = (0, coding_steering_1.syncCodingSteering)({
+            stack,
+            targetDir,
+            version: opts.conf?.steeringVersion,
+            logPrefix: 'init',
+        });
+    }
+    catch (err) {
+        steeringError = err instanceof Error ? err.message : String(err);
+        (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
+        steeringResult = { version: 'unknown', syncedSkills: [], techSynced: false };
+    }
     const installResult = (0, index_1.installDependencies)({
         targetDir,
         skip: opts.skipInstall,
         quietStdout: (0, output_1.isJsonMode)(),
     });
+    // template 自带 .githooks/pre-commit；如果用户项目已 git init,顺便设上 core.hooksPath。
+    const hookActivation = (0, githooks_1.activateGitHooks)(targetDir);
     (0, index_1.writeSparkMeta)(targetDir, {
         stack,
         version: tplResult.version,
         archType: tplResult.archType,
+        app_id: opts.appId,
+        steeringVersion: steeringResult.version,
     });
+    const syncedSummary = syncRunResult.stackFound
+        ? syncRunResult.rulesApplied.length > 0
+            ? `${syncRunResult.rulesApplied.length.toString()} rule(s)`
+            : 'legacy'
+        : 'skipped';
     if (!(0, output_1.isJsonMode)()) {
-        process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+        process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, sync ${syncedSummary}, install ${installResult.source}) in ${targetDir}\n`);
     }
     (0, output_1.emit)({
         data: {
@@ -77,12 +109,24 @@ async function handleAppInit(opts) {
             templateVersion: tplResult.version,
             steeringVersion: steeringResult.version,
             archType: tplResult.archType,
+            appId: opts.appId,
             syncedSkills: steeringResult.syncedSkills,
             techSynced: steeringResult.techSynced,
+            steeringError,
+            // sync 流程的产出：rule-driven 时 appliedRules + 一系列汇总字段；fallback 到旧 platform-sync
+            // 时只填 platformSyncedFiles / platformMergedJsonFiles；stack 不识别时全空且 platformStackFound=false。
+            platformStackFound: syncRunResult.stackFound,
+            appliedRules: syncSummary.appliedRules,
+            platformSyncedFiles: syncSummary.syncedFiles,
+            platformMergedJsonFiles: syncSummary.mergedJsonFiles,
+            patchedScripts: syncSummary.patchedScripts,
+            upgradedPackages,
+            gitHooks: hookActivation.action,
             installed: installResult.installed,
             installSource: installResult.source,
             installHash: installResult.hash,
             cacheZip: installResult.cacheZip,
+            installError: installResult.error,
         },
     });
 }

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

@@ -0,0 +1,220 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAppUpgrade = void 0;
+exports.handleAppSync = handleAppSync;
+exports.runStackSync = runStackSync;
+exports.summarizeSyncResults = summarizeSyncResults;
+exports.upgradePlatformDeps = upgradePlatformDeps;
+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 sync_configs_1 = require("../../../config/sync-configs");
+const sync_rule_1 = require("../../../utils/sync-rule");
+const platform_sync_1 = require("../../../utils/platform-sync");
+const githooks_1 = require("../../../utils/githooks");
+const spark_meta_1 = require("../../../utils/spark-meta");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const logger_1 = require("../../../utils/logger");
+/**
+ * 由 `miaoda app sync` / `miaoda app init` 管控的平台包白名单 —— user app 已装这些包时，
+ * sync 把 package.json 里的版本规范统一改写成 `"latest"`，npm install 时解析到当前 latest。
+ *
+ * 白名单外的 @lark-apaas/* 包：sync 不动；user app 未装的包：sync 不引入。
+ *
+ * 之前曾按表钉死具体 alpha 版本（避免外部 prerelease 回归），上线切 latest 通道后简化为
+ * 仅维护包名白名单。若某个包出现回归需要临时止血，把对应行从 `"latest"` 改为具体版本号
+ * 即可（用 Record<string, string> 结构而不是 Set，保留这个 escape hatch 的可能性）。
+ */
+const MANAGED_PLATFORM_PACKAGES = {
+    '@lark-apaas/auth-sdk': 'latest',
+    '@lark-apaas/client-toolkit': 'latest',
+    '@lark-apaas/client-toolkit-lite': 'latest',
+    '@lark-apaas/dataloom': 'latest',
+    '@lark-apaas/db-schema-sync': 'latest',
+    '@lark-apaas/express-core': 'latest',
+    '@lark-apaas/fullstack-cli': 'latest',
+    '@lark-apaas/fullstack-nestjs-core': 'latest',
+    '@lark-apaas/fullstack-rspack-preset': 'latest',
+    '@lark-apaas/fullstack-vite-preset': 'latest',
+    '@lark-apaas/http-client': 'latest',
+};
+/**
+ * miaoda app sync [--dir <path>]
+ *
+ * 一站式同步：把当前 stack 的 sync 规则全套 apply 到 user app，对齐沙箱里
+ * `npm run upgrade → npx fullstack-cli sync` 的行为，并补 miaoda-cli 本地开发独有规则。
+ *
+ * 执行流：
+ *   1. SyncRule[] 全量 apply —— 来自 src/config/sync-configs/<stack>.ts。每个 stack
+ *      自带模板资源在 upgrade/templates/<stack>/templates/。表里没有该 stack 时回退到
+ *      旧 platform-sync 兜底（兼容尚未迁移的 stack）。
+ *   2. 平台 deps 指 latest —— user app 已装的 @lark-apaas/* 按 MANAGED_PLATFORM_PACKAGES
+ *      白名单改写为 "latest"（紧急止血时表里可填具体版本）。
+ *   3. activateGitHooks —— 设置 core.hooksPath（template 自带 .githooks/pre-commit）。
+ *   4. npm install --no-audit --no-fund --ignore-scripts —— 物化新版本，绕开
+ *      action-plugin postinstall 在缺平台 env 时的 ENOENT。
+ *
+ * 需要 .spark/meta.json 已含 stack（走过 `miaoda app init`）。
+ * 不动 .agent/skills/（那是 `miaoda skills sync` 的事）。
+ */
+async function handleAppSync(opts) {
+    await Promise.resolve();
+    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+    if (meta.stack === undefined || meta.stack === '') {
+        throw new error_1.AppError('SYNC_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+    }
+    // 1. apply SyncRule[]，stack 没注册时回退到旧 platform-sync 兜底；都不识别就报错
+    const syncResults = runStackSync(meta.stack, targetDir, 'sync');
+    if (!syncResults.stackFound) {
+        throw new error_1.AppError('SYNC_STACK_NOT_SUPPORTED', `stack '${meta.stack}' has no SyncConfig and no upgrade/templates/${meta.stack}/ — 该 stack 暂未纳入 sync 范围`, {
+            next_actions: [
+                `src/config/sync-configs/${meta.stack}.ts 加 SyncConfig 并在 STACK_REGISTRY 注册`,
+            ],
+        });
+    }
+    // 2. @lark-apaas/* dep 统一指 latest（按 MANAGED_PLATFORM_PACKAGES 白名单，user app 已装才升）
+    const upgradedPackages = upgradePlatformDeps(targetDir, 'sync');
+    // 3. activate git hooks（template 自带 .githooks/pre-commit，core.hooksPath 一次性设置）
+    const hookActivation = (0, githooks_1.activateGitHooks)(targetDir);
+    // 4. npm install —— 跟 init 一样软失败，install 挂了不该阻断 emit / sync 总结输出
+    (0, logger_1.log)('sync', 'Running npm install --ignore-scripts...');
+    let installError;
+    try {
+        (0, node_child_process_1.execFileSync)('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts'], {
+            cwd: targetDir,
+            stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+        });
+    }
+    catch (err) {
+        installError = err instanceof Error ? err.message : String(err);
+        (0, logger_1.log)('sync', `⚠ npm install failed (continuing): ${installError}`);
+    }
+    (0, output_1.emit)({
+        data: {
+            stack: meta.stack,
+            ...summarizeSyncResults(syncResults),
+            upgradedPackages,
+            gitHooks: hookActivation.action,
+            installError,
+        },
+    });
+}
+/** 老命令 `miaoda app upgrade` 的 handler 名，保留为 sync handler 的 alias。 */
+exports.handleAppUpgrade = handleAppSync;
+/**
+ * 给 stack 应用 sync rules（sync handler + init handler 共用）。
+ * stack 在 STACK_REGISTRY 注册时走新 SyncRule 机制，否则回落到旧 platform-sync。
+ *
+ * stack 完全不识别（既不在 STACK_REGISTRY 也无 upgrade/templates/<stack>/ 目录）时返回
+ * `stackFound: false` 而非抛错 —— 让调用方按场景决定：sync handler 抛 AppError，init handler
+ * 允许（fresh init 时 stack 还在加注册的过渡期）。
+ */
+function runStackSync(stack, targetDir, logPrefix) {
+    const config = (0, sync_configs_1.getSyncConfig)(stack);
+    if (config !== null) {
+        const sourceRoot = (0, sync_configs_1.getStackTemplatesRoot)(stack);
+        if (!node_fs_1.default.existsSync(sourceRoot)) {
+            throw new error_1.AppError('SYNC_TEMPLATES_MISSING', `upgrade/templates/${stack}/templates/ not found at ${sourceRoot} — cli 安装异常?`);
+        }
+        (0, logger_1.log)(logPrefix, `Applying ${config.sync.length.toString()} sync rule(s) for stack '${stack}'`);
+        const rulesApplied = (0, sync_rule_1.applySyncRules)(config.sync, { sourceRoot, targetDir, logPrefix });
+        return { stackFound: true, rulesApplied };
+    }
+    // fallback：表外 stack 仍用旧 platform-sync 机制（files/ overlay + patches/ deep merge）
+    (0, logger_1.log)(logPrefix, `Stack '${stack}' not in new sync registry, falling back to legacy platform-sync`);
+    const legacy = (0, platform_sync_1.syncPlatformControlled)({ stack, targetDir, logPrefix });
+    return {
+        stackFound: legacy.stackFound,
+        rulesApplied: [],
+        legacy: { syncedFiles: legacy.syncedFiles, mergedJsonFiles: legacy.mergedJsonFiles },
+    };
+}
+/** 把 SyncRuleResult[] / legacy 输出汇总成 emit data 里的几组字段，便于诊断。 */
+function summarizeSyncResults(result) {
+    if (result.legacy !== undefined) {
+        return {
+            appliedRules: [],
+            syncedFiles: result.legacy.syncedFiles,
+            mergedJsonFiles: result.legacy.mergedJsonFiles,
+            patchedScripts: [],
+        };
+    }
+    const appliedRules = result.rulesApplied.map((r) => ({
+        type: r.rule.type,
+        action: r.action,
+        path: r.path,
+        detail: r.detail,
+    }));
+    const syncedFiles = [];
+    for (const r of result.rulesApplied) {
+        if ((r.action === 'synced' || r.action === 'created') && r.path !== undefined) {
+            syncedFiles.push(r.path);
+        }
+    }
+    const mergedJsonFiles = [];
+    for (const r of result.rulesApplied) {
+        if (r.rule.type !== 'merge-json')
+            continue;
+        if (r.action !== 'merged' && r.action !== 'created')
+            continue;
+        if (r.path === undefined)
+            continue;
+        mergedJsonFiles.push({
+            path: r.path,
+            keys: r.detail !== undefined ? r.detail.split(',').filter(Boolean) : [],
+        });
+    }
+    const patchedScripts = result.rulesApplied
+        .filter((r) => (r.rule.type === 'patch-script' || r.rule.type === 'add-script') &&
+        (r.action === 'patched' || r.action === 'created'))
+        .map((r) => r.rule.name);
+    return { appliedRules, syncedFiles, mergedJsonFiles, patchedScripts };
+}
+function readPackageJson(pkgJsonPath) {
+    if (!node_fs_1.default.existsSync(pkgJsonPath))
+        return null;
+    return JSON.parse(node_fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));
+}
+/**
+ * 把 user app package.json 里已装的 @lark-apaas/* 平台包改写成 MANAGED_PLATFORM_PACKAGES
+ * 表里的目标 spec（缺省 `"latest"`）。由 `miaoda app sync` 和 `miaoda app init`（template
+ * 渲染后、install 之前）共用。
+ *
+ * - user app 已装的管控包 → 写表里的目标 spec（默认 latest，紧急止血时可改具体版本）
+ * - user app 未装的管控包 → 不引入（sync 的职责是对齐，不是塞依赖）
+ * - 装着但不在白名单的 @lark-apaas/* 包 → 完全不动
+ *
+ * @param logPrefix 用于 `[<prefix>]   deps.xxx: a → b` 日志前缀；sync 流程传 'sync'，init 流程传 'init'。
+ */
+function upgradePlatformDeps(targetDir, logPrefix = 'sync') {
+    const pkgJsonPath = node_path_1.default.join(targetDir, 'package.json');
+    const pkg = readPackageJson(pkgJsonPath);
+    if (!pkg)
+        return [];
+    const updated = [];
+    for (const section of ['dependencies', 'devDependencies']) {
+        const deps = pkg[section];
+        if (!deps || typeof deps !== 'object')
+            continue;
+        for (const name of Object.keys(deps)) {
+            if (!Object.prototype.hasOwnProperty.call(MANAGED_PLATFORM_PACKAGES, name))
+                continue;
+            const target = MANAGED_PLATFORM_PACKAGES[name];
+            const from = deps[name];
+            if (from === target)
+                continue;
+            deps[name] = target;
+            updated.push({ name, from, to: target, section });
+            (0, logger_1.log)(logPrefix, `  ${section}.${name}: ${from} → ${target}`);
+        }
+    }
+    if (updated.length > 0) {
+        node_fs_1.default.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    return updated;
+}

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

@@ -10,10 +10,10 @@ const spark_meta_1 = require("../../../utils/spark-meta");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 /**
- * miaoda skills sync [--dir <path>] [--version <ver>]
+ * miaoda skills sync [version] [--dir <path>]
  *
- * 从 .spark/meta.json 读 stack，把 coding-steering 包内对应 stack 的 skills + tech.md
- * 同步到 <dir>/.agent/steering/。需要先跑过 `miaoda app init`。
+ * 从 .spark/meta.json 读 stack（+ 默认 steeringVersion），把 coding-steering 包内对应 stack
+ * 的 skills + tech.md 同步到 <dir>/.agent/steering/。需要先跑过 `miaoda app init`。
  */
 async function handleSkillsSync(opts) {
     await Promise.resolve();
@@ -22,17 +22,28 @@ async function handleSkillsSync(opts) {
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('SKILLS_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
     }
+    const version = opts.version ?? meta.steeringVersion;
+    const versionSource = opts.version
+        ? 'cli-arg'
+        : meta.steeringVersion
+            ? 'meta.json'
+            : 'default-latest';
     const result = (0, coding_steering_1.syncCodingSteering)({
         stack: meta.stack,
         targetDir,
-        version: opts.version,
+        version,
+        outputLayout: opts.local === true ? 'flat' : 'nested',
     });
     (0, output_1.emit)({
         data: {
             stack: meta.stack,
             version: result.version,
+            versionSource,
             syncedSkills: result.syncedSkills,
             techSynced: result.techSynced,
+            ...(result.claudeSkillsLink !== undefined
+                ? { claudeSkillsLink: result.claudeSkillsLink }
+                : {}),
         },
     });
 }

package/dist/config/fullstack-cli-pin.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FULLSTACK_CLI_PIN_SPEC = void 0;
+/**
+ * `@lark-apaas/fullstack-cli` 的 npx 调用 spec。
+ *
+ * 用于 user app `package.json` 里所有 `npx -y @lark-apaas/fullstack-cli ...` 调用 ——
+ * sync 规则会按本常量生成 `npx -y <FULLSTACK_CLI_PIN_SPEC> ...`。常量化是为了：
+ *   - 跟 src/cli/handlers/app/sync.ts 里 MANAGED_PLATFORM_PACKAGES['@lark-apaas/fullstack-cli']
+ *     的 spec 保持一致（user app deps 跟 npm script 里 npx 调用同步切渠道）
+ *   - 紧急止血时改一行就能把所有 user app 的 npm script 改回钉版（例如 `@1.1.49-alpha.0`）
+ */
+exports.FULLSTACK_CLI_PIN_SPEC = '@lark-apaas/fullstack-cli@latest';