@lark-apaas/miaoda-cli 0.1.17 → 0.1.18-alpha.b094028

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

@@ -166,6 +166,7 @@ function registerAppInit(parent) {
         .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
         .option('--conf <json>', 'init 配置 JSON。支持 {"version": "<template 版本>"}，默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
+        .option('--async-install', '派发后台进程装依赖并立即返回（与 --skip-install 互斥）', false)
         .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
 幂等
@@ -194,17 +195,31 @@ function registerAppInit(parent) {
     为空都会 fallback npm install。
   JSON 模式下子进程 stdout 重定向到 stderr，避免污染最终 emit 的 JSON。
 
+异步安装（--async-install）
+  跳过同步 npm install，派发一个 detached 后台进程装依赖后立即返回。
+  .spark/meta.json 在返回前写出（= 脚手架就绪），install 真实结果由 event marker 表达。
+  仅沙箱（SANDBOX_ID 非空）写 marker（presence 定成败，content 给排障）：
+    成功 → /tmp/event/WORKSPACE_READY
+    失败 → /tmp/event/WORKSPACE_FAILED
+  安装日志：/tmp/async_install_dep.std.log
+  失败恢复：靠后续 'miaoda app sync'（dev.sh 入口 / 沙箱 pod 启动会跑）兜底，init 不重试。
+  与 --skip-install 互斥。
+
 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": "...", ...}}
+  async 模式：{"data": {"initialized": true, "asyncInstall": true, "installed": false,
+                      "installSource": "async", "installPid": 123, "installLogPath": "...",
+                      "eventReadyPath": "...", "eventFailedPath": "..."}}
 
 示例
   $ miaoda app init --template vite-react
   $ 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 --skip-install
+  $ miaoda app init --template vite-react --async-install
   $ MIAODA_DEP_CACHE_DIR=/tmp/dep-cache miaoda app init --template vite-react
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
@@ -214,6 +229,7 @@ JSON 输出
             conf,
             skipInstall: rawOpts.skipInstall,
             appId: rawOpts.appId,
+            asyncInstall: rawOpts.asyncInstall,
         });
     }));
 }

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

@@ -10,6 +10,7 @@ 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 logs_dir_1 = require("../../../utils/logs-dir");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 /**
@@ -60,9 +61,15 @@ async function handleAppInit(opts) {
             next_actions: [`可用 stack：${index_1.SUPPORTED_STACKS.join(', ')}`],
         });
     }
+    if (opts.asyncInstall && opts.skipInstall) {
+        throw new error_1.AppError('ARGS_INVALID', '--async-install 与 --skip-install 互斥');
+    }
     const version = opts.conf?.version;
     const projectName = node_path_1.default.basename(targetDir);
     const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
+    // 先建 logs/,防止 user 跑 dev 之前 AI/工具 redirect 到 logs/*.log 因为父目录不存在直接挂
+    // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)
+    (0, logs_dir_1.ensureLogsDir)(targetDir);
     // skills 同步软失败：拉不到 coding-steering 包不该阻断 writeSparkMeta /
     // activateGitHooks（之前会让 .spark/meta.json 没写，下次 init 半渲染状态又得重跑全套）。
     // 按运行环境（SANDBOX_ID）分流 outputLayout，不绑 stack:
@@ -86,13 +93,17 @@ async function handleAppInit(opts) {
         (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
         steeringResult = { version: 'unknown', syncedSkills: [], techSynced: false };
     }
-    // 装模板钉死的依赖。不带 <pkg>@latest 位置参数,因此 npm 不会改写 package.json/lockfile
+    // 依赖安装：async 模式留到 meta 落盘后派发后台进程（不等装完），同步模式当场装。
+    // 同步：装模板钉死的依赖。不带 <pkg>@latest 位置参数,因此 npm 不会改写 package.json/lockfile
     // —— "升管控包到 latest" 是 sync 的职责,在 dev.sh 入口跑 `miaoda app sync` 时触发。
-    const installResult = (0, index_1.installDependencies)({
-        targetDir,
-        skip: opts.skipInstall,
-        quietStdout: (0, output_1.isJsonMode)(),
-    });
+    let installResult;
+    if (!opts.asyncInstall) {
+        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, {
@@ -101,8 +112,18 @@ async function handleAppInit(opts) {
         archType: tplResult.archType,
         app_id: opts.appId,
     });
+    // async 模式：meta 已落盘（= 脚手架就绪），再派发后台安装并立即返回（不等装完）。
+    let asyncDispatch;
+    if (opts.asyncInstall) {
+        asyncDispatch = (0, index_1.dispatchAsyncInstall)({ targetDir });
+    }
     if (!(0, output_1.isJsonMode)()) {
-        process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+        if (opts.asyncInstall && asyncDispatch) {
+            process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install dispatched in background pid ${String(asyncDispatch.pid)}) in ${targetDir}\n`);
+        }
+        else if (installResult) {
+            process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+        }
     }
     (0, output_1.emit)({
         data: {
@@ -117,11 +138,23 @@ async function handleAppInit(opts) {
             techSynced: steeringResult.techSynced,
             steeringError,
             gitHooks: hookActivation.action,
-            installed: installResult.installed,
-            installSource: installResult.source,
-            installHash: installResult.hash,
-            cacheZip: installResult.cacheZip,
-            installError: installResult.error,
+            ...(opts.asyncInstall && asyncDispatch
+                ? {
+                    asyncInstall: true,
+                    installed: false,
+                    installSource: 'async',
+                    installPid: asyncDispatch.pid,
+                    installLogPath: asyncDispatch.logPath,
+                    eventReadyPath: asyncDispatch.eventReadyPath,
+                    eventFailedPath: asyncDispatch.eventFailedPath,
+                }
+                : {
+                    installed: installResult?.installed,
+                    installSource: installResult?.source,
+                    installHash: installResult?.hash,
+                    cacheZip: installResult?.cacheZip,
+                    installError: installResult?.error,
+                }),
         },
     });
 }

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

@@ -134,14 +134,54 @@ async function handleAppMigrate(opts) {
         installError = err instanceof Error ? err.message : String(err);
         (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
     }
+    // 预热 vite deps cache —— 绕开 dev server 内嵌 optimizer 在沙箱里的 silent hang。
+    //
+    // 背景:migrate 跑完 npm install 后,fullstack user app 的 lockfile 是新的,但
+    // node_modules/.vite/deps/_metadata.json 还是旧/不存在。下一次 dev:client 启动时
+    // vite 看到 lockfile hash 跟 metadata 不一致,触发内嵌 optimizer 重跑 prebundle。
+    // 偶发(看起来跟沙箱 CPU / esbuild worker 状态有关) optimizer 静默 hang —— bundle 不
+    // 完成、不写产物、不报错,但 vite middleware 仍 serve 请求:transform 写一个 hash、
+    // load 又拿到另一个 hash, 持续 504。详见
+    // ~/docs/miaoda-fullstack-vite-deps-504-20260624.md
+    //
+    // 解法:这里 standalone `npx vite optimize --force` 跑一次,只用 vite optimizer 子流程
+    // (不加载 preset 那一堆 plugin 的 dev server lifecycle hook),沙箱里实测 1~2 秒就能
+    // 完成,写出 _metadata.json + 当下 lockfileHash。下一次 dev:client 启动时 vite 看
+    // hash 跟 cache 一致就跳过 Re-optimize, 直接复用 cache,绕开 hang 路径。
+    //
+    //   - 只在 SANDBOX_ID 非空时做(本地环境 vite 自带 optimizer 不卡, 没必要拖慢 migrate)
+    //   - 只在 install 成功时做(install 失败时 node_modules 状态不对, optimize 也会挂)
+    //   - 软失败:optimize 挂了不阻断后续 pkill —— 即使没预热成功, dev server 自己跑
+    //     optimizer 偶尔也能通过, 不要因为这一步丢掉重启 dev 的机会
+    let optimizeError;
+    if (installError === undefined &&
+        process.env.SANDBOX_ID !== undefined &&
+        process.env.SANDBOX_ID !== '') {
+        (0, logger_1.log)('migrate', 'Pre-warming vite deps cache (vite optimize --force)...');
+        try {
+            (0, node_child_process_1.execFileSync)('npx', ['-y', 'vite', 'optimize', '--force'], {
+                cwd: targetDir,
+                stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+                timeout: 120_000,
+            });
+        }
+        catch (err) {
+            optimizeError = err instanceof Error ? err.message : String(err);
+            (0, logger_1.log)('migrate', `⚠ vite optimize prewarm failed (continuing): ${optimizeError}`);
+        }
+    }
     // 沙箱环境下重启 dev process —— scripts/dev.js 被 fullstack 版本覆盖了,但当前正在
     // 跑的 node 进程仍按老逻辑工作(只起 vite,没起 nest),整体没切到 fullstack 模式。
     // 通过 pkill 杀掉 dev.js 主进程,依赖沙箱平台 supervisor 自动重新 exec dev.sh → dev.js,
     // 新进程用新 deps + 新 scripts,正常进入 fullstack 模式。
     //   - 只在 SANDBOX_ID 非空时做(本地环境用户进程混杂,主动 pkill 风险大)
+    //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
+    //     留着旧进程让用户先处理 installError
     //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
     let devRestarted = false;
-    if (process.env.SANDBOX_ID !== undefined && process.env.SANDBOX_ID !== '') {
+    if (installError === undefined &&
+        process.env.SANDBOX_ID !== undefined &&
+        process.env.SANDBOX_ID !== '') {
         (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');
         try {
             (0, node_child_process_1.execFileSync)('pkill', ['-f', 'node.*scripts/dev\\.js'], { stdio: 'ignore' });
@@ -165,6 +205,7 @@ async function handleAppMigrate(opts) {
             ...summarizeResults(results),
             followLatestPackages: followLatest,
             installError,
+            optimizeError,
             devRestarted,
             nextActions: process.env.SANDBOX_ID !== undefined && process.env.SANDBOX_ID !== ''
                 ? [

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

@@ -16,6 +16,7 @@ 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 logs_dir_1 = require("../../../utils/logs-dir");
 const install_1 = require("../../../services/app/init/install");
 const spark_meta_1 = require("../../../utils/spark-meta");
 const error_1 = require("../../../utils/error");
@@ -81,6 +82,10 @@ async function handleAppSync(opts) {
     }
     // 2. activate git hooks（template 自带 .githooks/pre-commit，core.hooksPath 一次性设置）
     const hookActivation = (0, githooks_1.activateGitHooks)(targetDir);
+    // logs/ 兜底:dev.js / dev-local.js 启动后才 mkdir,启动前任何想 redirect 到 logs/*.log 的
+    // shell 命令都会因父目录不存在直接 ENOENT 挂掉。sync 也建一次,长期使用的 user app 老仓库
+    // 第一次升级也能拿到这个目录。
+    (0, logs_dir_1.ensureLogsDir)(targetDir);
     // 3. snapshot 当前 user app 装的管控包版本，供 install 后 diff 用
     const beforeSpecs = snapshotManagedDepSpecs(targetDir);
     // 4. npm install —— 跟 init 一样软失败,install 挂了不该阻断 emit / sync 总结输出。

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

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASYNC_INSTALL_LOG = void 0;
+exports.isSandboxEnv = isSandboxEnv;
+exports.runAsyncInstallWorker = runAsyncInstallWorker;
+exports.dispatchAsyncInstall = dispatchAsyncInstall;
+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 install_1 = require("./install");
+/** event marker 目录，写死；写前 mkdir -p。沙箱里 code server 轮询此目录。 */
+const EVENT_DIR = '/tmp/event';
+/** 安装成功 marker 名 */
+const MARKER_READY = 'WORKSPACE_READY';
+/** 安装失败 marker 名 */
+const MARKER_FAILED = 'WORKSPACE_FAILED';
+/** 后台 worker stdout/stderr 落盘路径 */
+exports.ASYNC_INSTALL_LOG = '/tmp/async_install_dep.std.log';
+/** 沙箱判定：SANDBOX_ID 非空。与 init handler 的 outputLayout 分流口径一致。 */
+function isSandboxEnv() {
+    return process.env.SANDBOX_ID !== undefined && process.env.SANDBOX_ID !== '';
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function clearStaleMarkers(eventDir) {
+    for (const name of [MARKER_READY, MARKER_FAILED]) {
+        const p = node_path_1.default.join(eventDir, name);
+        if (node_fs_1.default.existsSync(p))
+            node_fs_1.default.rmSync(p, { force: true });
+    }
+}
+function writeMarker(eventDir, name, content) {
+    node_fs_1.default.mkdirSync(eventDir, { recursive: true });
+    node_fs_1.default.writeFileSync(node_path_1.default.join(eventDir, name), JSON.stringify(content) + '\n', 'utf-8');
+}
+/**
+ * 后台 install worker 体：跑 installDependencies，按结果写 marker（仅沙箱）。
+ * 由 dispatchAsyncInstall 通过 `node -e` 在 detached 子进程里调用（见下）。
+ * presence 定成败：成功写 WORKSPACE_READY，失败写 WORKSPACE_FAILED；content 给排障。
+ */
+function runAsyncInstallWorker(opts) {
+    const eventDir = opts.eventDir ?? EVENT_DIR;
+    const sandbox = isSandboxEnv();
+    if (sandbox)
+        clearStaleMarkers(eventDir);
+    const start = Date.now();
+    let result;
+    try {
+        result = (0, install_1.installDependencies)({ targetDir: opts.targetDir, quietStdout: false });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (sandbox) {
+            writeMarker(eventDir, MARKER_FAILED, {
+                ts: nowIso(),
+                error: msg,
+                logPath: exports.ASYNC_INSTALL_LOG,
+            });
+        }
+        return;
+    }
+    if (!sandbox)
+        return;
+    if (result.source === 'failed') {
+        writeMarker(eventDir, MARKER_FAILED, {
+            ts: nowIso(),
+            error: result.error ?? 'npm install failed',
+            logPath: exports.ASYNC_INSTALL_LOG,
+        });
+    }
+    else {
+        writeMarker(eventDir, MARKER_READY, {
+            ts: nowIso(),
+            durationMs: Date.now() - start,
+            source: result.source,
+        });
+    }
+}
+/**
+ * 派发 detached 后台进程跑依赖安装并立即返回。
+ * 用 `node -e` 直接 require 本模块（编译产物）调 runAsyncInstallWorker，
+ * 不挂任何 CLI 子命令、对外不暴露；worker 内复用 installDependencies（cache / registry / fallback）。
+ * 沙箱下派发前清旧 marker；stdout/stderr 重定向到 logPath。
+ */
+function dispatchAsyncInstall(opts) {
+    const eventDir = opts.eventDir ?? EVENT_DIR;
+    const logPath = opts.logPath ?? exports.ASYNC_INSTALL_LOG;
+    const sandbox = isSandboxEnv();
+    if (sandbox)
+        clearStaleMarkers(eventDir);
+    // targetDir 走 argv 传，不拼进代码串（免转义）；只把本模块路径 JSON 内联进去。
+    const workerCode = `require(${JSON.stringify(__filename)}).runAsyncInstallWorker({ targetDir: process.argv[1] })`;
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(logPath), { recursive: true });
+    const fd = node_fs_1.default.openSync(logPath, 'w');
+    try {
+        const child = (0, node_child_process_1.spawn)(process.execPath, ['-e', workerCode, opts.targetDir], {
+            detached: true,
+            stdio: ['ignore', fd, fd],
+        });
+        child.unref();
+        return {
+            pid: child.pid,
+            logPath,
+            eventReadyPath: sandbox ? node_path_1.default.join(eventDir, MARKER_READY) : undefined,
+            eventFailedPath: sandbox ? node_path_1.default.join(eventDir, MARKER_FAILED) : undefined,
+        };
+    }
+    finally {
+        // 父进程关掉自己那份 fd；子进程已通过 stdio dup 持有独立副本。
+        node_fs_1.default.closeSync(fd);
+    }
+}

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.TEMPLATE_PACKAGE_BY_STACK = exports.SUPPORTED_STACKS = exports.renderTemplate = void 0;
+exports.ASYNC_INSTALL_LOG = exports.isSandboxEnv = exports.runAsyncInstallWorker = exports.dispatchAsyncInstall = exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.TEMPLATE_PACKAGE_BY_STACK = exports.SUPPORTED_STACKS = exports.renderTemplate = void 0;
 var template_1 = require("./template");
 Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return template_1.SUPPORTED_STACKS; } });
@@ -11,3 +11,8 @@ Object.defineProperty(exports, "writeSparkMeta", { enumerable: true, get: functi
 var install_1 = require("./install");
 Object.defineProperty(exports, "installDependencies", { enumerable: true, get: function () { return install_1.installDependencies; } });
 Object.defineProperty(exports, "resolveNpmInstallRegistry", { enumerable: true, get: function () { return install_1.resolveNpmInstallRegistry; } });
+var async_install_1 = require("./async-install");
+Object.defineProperty(exports, "dispatchAsyncInstall", { enumerable: true, get: function () { return async_install_1.dispatchAsyncInstall; } });
+Object.defineProperty(exports, "runAsyncInstallWorker", { enumerable: true, get: function () { return async_install_1.runAsyncInstallWorker; } });
+Object.defineProperty(exports, "isSandboxEnv", { enumerable: true, get: function () { return async_install_1.isSandboxEnv; } });
+Object.defineProperty(exports, "ASYNC_INSTALL_LOG", { enumerable: true, get: function () { return async_install_1.ASYNC_INSTALL_LOG; } });

package/dist/utils/logs-dir.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureLogsDir = ensureLogsDir;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 确保 user app 根下存在 `logs/` 目录（幂等）。
+ *
+ * 模板的 dev.js / dev-local.js 自己也会 mkdir LOG_DIR,但只在进程启动后才执行 —— AI / 用户
+ * 在 dev 启动前跑 `npm run dev > logs/dev.log 2>&1` 这种 shell redirect 时,shell 先 open
+ * 目标文件,父目录不存在直接 ENOENT,子进程根本不会启动。init / sync 落地阶段先把空目录建出来,
+ * 避免这种「目录不存在导致 redirect 失败」的低级问题。
+ */
+function ensureLogsDir(targetDir) {
+    node_fs_1.default.mkdirSync(node_path_1.default.join(targetDir, 'logs'), { recursive: true });
+}

package/package.json

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

package/upgrade/templates/design-stack/templates/.githooks/pre-commit

@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
 [ "$SKIP_GIT_HOOKS" = "1" ] && exit 0
+
 export PATH="node_modules/.bin:$PATH"
 npm run precommit

package/upgrade/templates/design-stack/templates/scripts/dev-local.js

@@ -5,9 +5,11 @@
 //
 // 流程:
 //   1. env pull —— 拉沙箱身份/凭证到 .env.local
-//   2. skills sync —— 同步当前 stack 的 agent skills
-//   3. dotenv 加载 .env / .env.local 到 process.env（含 SUDA_WEBUSER 适配）
-//   4. 起单进程 dev server（design-stack 单进程，无 server/client 拆分）
+//   2. action-plugin init —— 装 user app 在 package.json.actionPlugins 里声明的插件
+//   3. skills sync —— 同步当前 stack 的 agent skills
+//   4. dotenv 加载 .env / .env.local 到 process.env（含 SUDA_WEBUSER 适配）
+//   5. 起单进程 dev server（design-stack 单进程，无 server/client 拆分），
+//      stdout/stderr 整体 tee 到 logs/dev.std.log
 //
 // 设计同 nestjs-react-fullstack/dev-local.js,SDK 包不需要自己 require('dotenv'),
 // env 加载收敛在启动脚本单点。SUDA_WEBUSER 适配同 nrf 那份。
@@ -26,7 +28,11 @@ function warn(msg) {
 if (!process.env.MIAODA_APP_TYPE) process.env.MIAODA_APP_TYPE = '4';
 process.env.MIAODA_LOCAL_DEV = '1';
 
-console.log('[dev-local] (1/4) env pull...');
+// 先建 logs/,防止任何步骤(尤其是 spawn 子进程前的 shell redirect)因父目录不存在挂掉
+const LOG_DIR = process.env.LOG_DIR || 'logs';
+fs.mkdirSync(LOG_DIR, { recursive: true });
+
+console.log('[dev-local] (1/5) env pull...');
 const hasLarkCli = spawnSync('command', ['-v', 'lark-cli'], { shell: true, stdio: 'ignore' }).status === 0;
 if (hasLarkCli) {
   let appId = '';
@@ -47,15 +53,23 @@ if (hasLarkCli) {
   warn('lark-cli 未安装，跳过 env pull；请确保 .env.local 已就绪');
 }
 
+// action-plugin init —— 装 user app 在 package.json.actionPlugins 里声明的插件。
+console.log('[dev-local] (2/5) action-plugin init...');
+try {
+  execSync('npx -y @lark-apaas/fullstack-cli@latest action-plugin init', { stdio: 'inherit' });
+} catch {
+  warn('action-plugin init 失败，继续启动');
+}
+
 // skills sync —— --local 切 flat layout;不传 --version,handler 默认 coding-steering@latest。
-console.log('[dev-local] (2/4) miaoda skills sync...');
+console.log('[dev-local] (3/5) miaoda skills sync...');
 try {
   execSync('npx -y @lark-apaas/miaoda-cli@latest skills sync --local', { stdio: 'inherit' });
 } catch {
   console.log('  (skills sync 失败，继续启动)');
 }
 
-console.log('[dev-local] (3/4) loading .env / .env.local...');
+console.log('[dev-local] (4/5) loading .env / .env.local...');
 const dotenv = require('dotenv');
 dotenv.config({ path: '.env.local' });
 dotenv.config({ path: '.env' });
@@ -75,10 +89,55 @@ if (process.env.SUDA_WEBUSER) {
   }
 }
 
-console.log('[dev-local] (4/4) npm run dev');
-const child = spawn('npm', ['run', 'dev'], { stdio: 'inherit', env: process.env });
-child.on('exit', (code) => process.exit(code ?? 0));
+const devLogPath = path.join(LOG_DIR, 'dev.std.log');
+console.log('[dev-local] (5/5) npm run dev');
+console.log(`[dev-local] 日志: ${devLogPath}`);
+
+const logFd = fs.openSync(devLogPath, 'a');
+const child = spawn('npm', ['run', 'dev'], {
+  stdio: ['ignore', 'pipe', 'pipe'],
+  env: process.env,
+});
+
+const tee = (src) =>
+  src.on('data', (chunk) => {
+    try {
+      process.stdout.write(chunk);
+    } catch {
+      /* terminal gone */
+    }
+    try {
+      fs.writeSync(logFd, chunk);
+    } catch {
+      /* log fd closed */
+    }
+  });
+tee(child.stdout);
+tee(child.stderr);
+
+// 外部 SIGTERM/SIGHUP 转发给 npm,避免本进程死了 nest 变孤儿
+// (SIGINT 在 TTY 下 shell 直接发给整个前台进程组,不需要转发)
+const forward = (sig) => () => {
+  try {
+    child.kill(sig);
+  } catch {
+    /* already gone */
+  }
+};
+process.on('SIGTERM', forward('SIGTERM'));
+process.on('SIGHUP', forward('SIGHUP'));
+
+// 'close' 而非 'exit':等 child 的 stdio stream drain 完才触发,
+// 保证 tee 把最后一批 chunk 写进 logFd 再关闭,不丢尾。
+child.on('close', (code) => {
+  try {
+    fs.closeSync(logFd);
+  } catch {
+    /* already closed */
+  }
+  process.exit(code ?? 0);
+});
 child.on('error', (err) => {
-  console.error(err);
+  console.error('[dev-local] 启动失败:', err.message);
   process.exit(1);
 });

package/upgrade/templates/design-stack/templates/scripts/hooks/run-precommit.js

@@ -6,6 +6,10 @@ const { spawnSync } = require('node:child_process');
 
 const SEP = '  ' + '─'.repeat(36);
 
+// package-lock.json 锁内网镜像源 → 线上构建无法访问,改用公共镜像源。
+// 后续如有其它内网域名需要拦截,在这里加 pattern 即可。
+const INTERNAL_REGISTRY_PATTERNS = [/bnpm\.byted\.org/];
+
 function failAndExit(step, body) {
   process.stderr.write('\n✗ pre-commit failed: ' + step + '\n');
   process.stderr.write(SEP + '\n');
@@ -17,6 +21,37 @@ function failAndExit(step, body) {
   process.exit(1);
 }
 
+function checkLockfileRegistry() {
+  const res = spawnSync(
+    'git',
+    ['diff', '--cached', '--diff-filter=ACMR', '--', 'package-lock.json'],
+    { stdio: ['ignore', 'pipe', 'pipe'], env: process.env },
+  );
+  // git 不可用 / 不在 git 仓库 → 静默放行,交给 lint 步骤报错
+  if (res.error || res.status !== 0) return;
+  const diff = res.stdout ? res.stdout.toString() : '';
+  // 只看本次新增行(`+` 开头但排除 `+++` 文件头)
+  const hit = diff
+    .split('\n')
+    .some(
+      (line) =>
+        line.startsWith('+') &&
+        !line.startsWith('+++') &&
+        INTERNAL_REGISTRY_PATTERNS.some((p) => p.test(line)),
+    );
+  if (!hit) return;
+  failAndExit(
+    'package-lock.json 使用了内网镜像源',
+    [
+      '线上构建环境无法访问内网镜像源，将导致部署阶段 npm install 失败。',
+      '请使用公共镜像源重新生成 lockfile：',
+      '',
+      '  rm -rf node_modules package-lock.json',
+      '  npm install --registry=https://registry.npmmirror.com',
+    ].join('\n'),
+  );
+}
+
 function runLint() {
   const cwd = process.cwd();
   const res = spawnSync('npm', ['run', 'lint'], {
@@ -34,4 +69,5 @@ function runLint() {
   }
 }
 
+checkLockfileRegistry();
 runLint();

package/upgrade/templates/nestjs-react-fullstack/templates/.githooks/pre-commit

@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
 [ "$SKIP_GIT_HOOKS" = "1" ] && exit 0
+
 export PATH="node_modules/.bin:$PATH"
 npm run precommit

package/upgrade/templates/nestjs-react-fullstack/templates/.spark_project

@@ -1,5 +1,5 @@
 run = ["npm", "run", "dev"] # 默认 spark-cli dev
-hidden = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]
+hidden = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", ".claude", "tmp", ".spark_project", ".playwright-cli"]
 lint = ["npm", "run", "lint"]
 test = ["npm", "run", "test"]
 genDbSchema = ["npm", "run", "gen:db-schema"]
@@ -13,4 +13,4 @@ run = ["npm", "run", "start"]
 [files.restrict]
 pathPatterns = ["client/src/api/gen", "package.json", ".spark_project", ".gitignore"]
 [files.hidden]
-pathPatterns = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]
+pathPatterns = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", ".claude", "tmp", ".spark_project", ".playwright-cli"]

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/dev-local.js

@@ -5,9 +5,12 @@
 //
 // 流程:
 //   1. env pull —— 拉沙箱身份/凭证到 .env.local
-//   2. skills sync —— 同步当前 stack 的 agent skills
-//   3. dotenv 加载 .env / .env.local 到 process.env（含 SUDA_WEBUSER 适配）
-//   4. 并发起 dev:server + dev:client（子进程继承 process.env）
+//   2. action-plugin init —— 装 user app 在 package.json.actionPlugins 里声明的插件
+//   3. skills sync —— 同步当前 stack 的 agent skills
+//   4. dotenv 加载 .env / .env.local 到 process.env（含 SUDA_WEBUSER 适配）
+//   5. concurrently 并发起 dev:server + dev:client,整体 stdout/stderr tee 到
+//      logs/dev.std.log;server / client 输出靠 concurrently 自带 [server]/[client]
+//      前缀区分,`grep '\[server\]' logs/dev.std.log` 拿单边日志
 //
 // 关键设计：本脚本在 spawn 子进程之前先把 .env / .env.local 加载到 process.env，
 // 然后 spawn 的 server / client 进程通过 env 继承直接拿到——SDK（fullstack-nestjs-core
@@ -33,8 +36,12 @@ function warn(msg) {
 if (!process.env.MIAODA_APP_TYPE) process.env.MIAODA_APP_TYPE = '3';
 process.env.MIAODA_LOCAL_DEV = '1';
 
+// 先建 logs/,防止任何步骤(尤其是 spawn 子进程前的 shell redirect)因父目录不存在挂掉
+const LOG_DIR = process.env.LOG_DIR || 'logs';
+fs.mkdirSync(LOG_DIR, { recursive: true });
+
 // 1. env pull
-console.log('[dev-local] (1/4) env pull...');
+console.log('[dev-local] (1/5) env pull...');
 const hasLarkCli = spawnSync('command', ['-v', 'lark-cli'], { shell: true, stdio: 'ignore' }).status === 0;
 if (hasLarkCli) {
   let appId = '';
@@ -55,20 +62,28 @@ if (hasLarkCli) {
   warn('lark-cli 未安装，跳过 env pull；请确保 .env.local 已就绪');
 }
 
-// 2. skills sync —— --local 切到 flat layout (.agents/skills + .claude/skills 软链),
+// 2. action-plugin init —— 装 user app 在 package.json.actionPlugins 里声明的插件。
+console.log('[dev-local] (2/5) action-plugin init...');
+try {
+  execSync('npx -y @lark-apaas/fullstack-cli@latest action-plugin init', { stdio: 'inherit' });
+} catch {
+  warn('action-plugin init 失败，继续启动');
+}
+
+// 3. skills sync —— --local 切到 flat layout (.agents/skills + .claude/skills 软链),
 // 跟沙箱 nested layout 区分。不传 --version,handler 默认拉 coding-steering@latest,
 // 保证每次本地 npm run dev 都把 skills 升到最新。
-console.log('[dev-local] (2/4) miaoda skills sync...');
+console.log('[dev-local] (3/5) miaoda skills sync...');
 try {
   execSync('npx -y @lark-apaas/miaoda-cli@latest skills sync --local', { stdio: 'inherit' });
 } catch {
   console.log('  (skills sync 失败，继续启动)');
 }
 
-// 3. 加载 .env / .env.local 到 process.env
+// 4. 加载 .env / .env.local 到 process.env
 // dotenv 默认 override:false，先到先得 → 先 .env.local 让它优先于 .env；
 // shell env 已在 process.env，两次 config 都不会覆盖。
-console.log('[dev-local] (3/4) loading .env / .env.local...');
+console.log('[dev-local] (4/5) loading .env / .env.local...');
 const dotenv = require('dotenv');
 dotenv.config({ path: '.env.local' });
 dotenv.config({ path: '.env' });
@@ -89,8 +104,12 @@ if (process.env.SUDA_WEBUSER) {
   }
 }
 
-// 4. 并发起前后端 dev server
-console.log('[dev-local] (4/4) 并发起 dev:server + dev:client');
+// 5. 并发起前后端 dev server,整体 tee 到 logs/dev.std.log
+const devLogPath = path.join(LOG_DIR, 'dev.std.log');
+console.log('[dev-local] (5/5) 并发起 dev:server + dev:client');
+console.log(`[dev-local] 日志: ${devLogPath}`);
+
+const logFd = fs.openSync(devLogPath, 'a');
 const child = spawn(
   'npx',
   [
@@ -104,10 +123,49 @@ const child = spawn(
     'npm run dev:server',
     'npm run dev:client',
   ],
-  { stdio: 'inherit', env: process.env },
+  { stdio: ['ignore', 'pipe', 'pipe'], env: process.env },
 );
-child.on('exit', (code) => process.exit(code ?? 0));
+
+const tee = (src) =>
+  src.on('data', (chunk) => {
+    try {
+      process.stdout.write(chunk);
+    } catch {
+      /* terminal gone */
+    }
+    try {
+      fs.writeSync(logFd, chunk);
+    } catch {
+      /* log fd closed */
+    }
+  });
+tee(child.stdout);
+tee(child.stderr);
+
+// 外部 SIGTERM/SIGHUP 转发给 concurrently,避免本进程死了 server/client 变孤儿
+// (SIGINT 在 TTY 下 shell 直接发给整个前台进程组,不需要转发)
+const forward = (sig) => () => {
+  try {
+    child.kill(sig);
+  } catch {
+    /* already gone */
+  }
+};
+process.on('SIGTERM', forward('SIGTERM'));
+process.on('SIGHUP', forward('SIGHUP'));
+
+// 'close' 而非 'exit':等 child 的 stdio stream drain 完才触发,
+// 保证 tee 把最后一批 chunk 写进 logFd 再关闭,不丢尾。
+child.on('close', (code) => {
+  try {
+    fs.closeSync(logFd);
+  } catch {
+    /* already closed */
+  }
+  process.exit(code ?? 0);
+});
 child.on('error', (err) => {
-  console.error(err);
+  console.error('[dev-local] 启动失败:', err.message);
+  console.error('[dev-local] 如缺 concurrently,运行: npm install');
   process.exit(1);
 });

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/hooks/run-precommit.js

@@ -6,6 +6,10 @@ const { spawnSync } = require('node:child_process');
 
 const SEP = '  ' + '─'.repeat(36);
 
+// package-lock.json 锁内网镜像源 → 线上构建无法访问,改用公共镜像源。
+// 后续如有其它内网域名需要拦截,在这里加 pattern 即可。
+const INTERNAL_REGISTRY_PATTERNS = [/bnpm\.byted\.org/];
+
 function failAndExit(step, body) {
   process.stderr.write('\n✗ pre-commit failed: ' + step + '\n');
   process.stderr.write(SEP + '\n');
@@ -17,6 +21,37 @@ function failAndExit(step, body) {
   process.exit(1);
 }
 
+function checkLockfileRegistry() {
+  const res = spawnSync(
+    'git',
+    ['diff', '--cached', '--diff-filter=ACMR', '--', 'package-lock.json'],
+    { stdio: ['ignore', 'pipe', 'pipe'], env: process.env },
+  );
+  // git 不可用 / 不在 git 仓库 → 静默放行,交给 lint 步骤报错
+  if (res.error || res.status !== 0) return;
+  const diff = res.stdout ? res.stdout.toString() : '';
+  // 只看本次新增行(`+` 开头但排除 `+++` 文件头)
+  const hit = diff
+    .split('\n')
+    .some(
+      (line) =>
+        line.startsWith('+') &&
+        !line.startsWith('+++') &&
+        INTERNAL_REGISTRY_PATTERNS.some((p) => p.test(line)),
+    );
+  if (!hit) return;
+  failAndExit(
+    'package-lock.json 使用了内网镜像源',
+    [
+      '线上构建环境无法访问内网镜像源，将导致部署阶段 npm install 失败。',
+      '请使用公共镜像源重新生成 lockfile：',
+      '',
+      '  rm -rf node_modules package-lock.json',
+      '  npm install --registry=https://registry.npmmirror.com',
+    ].join('\n'),
+  );
+}
+
 function runLint() {
   const cwd = process.cwd();
   const res = spawnSync('npm', ['run', 'lint'], {
@@ -34,4 +69,5 @@ function runLint() {
   }
 }
 
+checkLockfileRegistry();
 runLint();