@lark-apaas/miaoda-cli 0.1.6-alpha.388541c → 0.1.7-alpha.3b4268d

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

@@ -46,8 +46,8 @@ function registerAppSync(parent) {
        delete-file/delete-directory → 删除
      沙箱里跑的 fullstack-cli sync 走同一套 rule 类型，行为对齐；miaoda app sync 在此之上
      补 dev:local 等本地开发独有规则。
-  2. 平台 deps 钉版本：按 handlers/app/sync.ts 里 PINNED_PLATFORM_VERSIONS 升 user app 已装的
-     @lark-apaas/* 包；表外 / 未装的不动。
+  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 的卡点（需要时再
@@ -140,7 +140,7 @@ function registerAppInit(parent) {
   init 内嵌一次 upgrade/templates 同步（跟 app upgrade 共用同一份 util）：
   从 miaoda-cli 自带的 upgrade/templates/<stack>/ 同步 files/（覆盖）+ patches/
   （JSON deep merge，含 scripts.dev:local 等）。目标 stack 未纳入 upgrade/templates/
-  时跳过（不报错）。后续要升 @lark-apaas/* 平台包到最新 alpha，跑 'miaoda app upgrade'。
+  时跳过（不报错）。后续要把 @lark-apaas/* 平台包统一指 latest，跑 'miaoda app upgrade'。
 
 依赖安装
   默认：npm install --no-audit --no-fund
@@ -160,7 +160,7 @@ JSON 输出
 示例
   $ 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-alpha.1"}'
+  $ 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

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

@@ -59,8 +59,8 @@ async function handleAppInit(opts) {
     // 与最终态对齐；patches 还能覆盖 template 提供的同名文件。
     const syncRunResult = (0, sync_1.runStackSync)(stack, targetDir, 'init');
     const syncSummary = (0, sync_1.summarizeSyncResults)(syncRunResult);
-    // template 渲染下来的 @lark-apaas/* 版本可能落后 PINNED 表，赶在 install 之前钉到表版本，
-    // 这样一次 npm install 就直接装最终版本，不需要 install 完再补一遍。
+    // 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 半渲染状态又得重跑全套）。

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

@@ -20,28 +20,27 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const logger_1 = require("../../../utils/logger");
 /**
- * 平台包钉死版本表 —— `miaoda app sync` 不查 npm dist-tags，直接按这张表把
- * user app 已有的 @lark-apaas/* 依赖钉到对应版本。
+ * 由 `miaoda app sync` / `miaoda app init` 管控的平台包白名单 —— user app 已装这些包时，
+ * sync 把 package.json 里的版本规范统一改写成 `"latest"`，npm install 时解析到当前 latest。
  *
- * 为什么不跟 alpha dist-tag：alpha 通道被多个团队共享，外部 prerelease 时常打过去，
- * 自动跟 alpha 会把回归版本（如 fullstack-vite-preset@1.0.24-alpha.5 退化没读 .env.local）
- * 拉进 user app。维护这张白名单可控性更高，每次升基线时人工 review 一次再改这里。
+ * 白名单外的 @lark-apaas/* 包：sync 不动；user app 未装的包：sync 不引入。
  *
- * 表里没有的 @lark-apaas/* 包：sync 不动（既不升也不报错）；user app 没装的包也不引入。
- * 改这张表请同步把 user app 端到端 smoke 跑一次（init → sync → npm run dev）。
+ * 之前曾按表钉死具体 alpha 版本（避免外部 prerelease 回归），上线切 latest 通道后简化为
+ * 仅维护包名白名单。若某个包出现回归需要临时止血，把对应行从 `"latest"` 改为具体版本号
+ * 即可（用 Record<string, string> 结构而不是 Set，保留这个 escape hatch 的可能性）。
  */
-const PINNED_PLATFORM_VERSIONS = {
-    '@lark-apaas/auth-sdk': '0.1.5-alpha.4',
-    '@lark-apaas/client-toolkit': '1.2.47-alpha.0',
-    '@lark-apaas/client-toolkit-lite': '1.1.8-alpha.0',
-    '@lark-apaas/dataloom': '0.1.2-alpha.6',
-    '@lark-apaas/db-schema-sync': '0.1.6-alpha.2',
-    '@lark-apaas/express-core': '1.0.4-alpha.7',
-    '@lark-apaas/fullstack-cli': '1.1.49-alpha.0',
-    '@lark-apaas/fullstack-nestjs-core': '1.1.52-alpha.1',
-    '@lark-apaas/fullstack-rspack-preset': '1.0.56-alpha.8',
-    '@lark-apaas/fullstack-vite-preset': '1.0.24-alpha.9',
-    '@lark-apaas/http-client': '0.1.7-alpha.8',
+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>]
@@ -53,7 +52,8 @@ const PINNED_PLATFORM_VERSIONS = {
  *   1. SyncRule[] 全量 apply —— 来自 src/config/sync-configs/<stack>.ts。每个 stack
  *      自带模板资源在 upgrade/templates/<stack>/templates/。表里没有该 stack 时回退到
  *      旧 platform-sync 兜底（兼容尚未迁移的 stack）。
- *   2. PINNED 平台 deps 钉版本 —— user app 已装的 @lark-apaas/* 升到 PINNED 表。
+ *   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。
@@ -77,15 +77,25 @@ async function handleAppSync(opts) {
             ],
         });
     }
-    // 2. @lark-apaas/* dep pin（按 PINNED_PLATFORM_VERSIONS 表，user app 已装才钉）
+    // 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...');
+    // 4. npm install —— 跟 init 一样软失败，install 挂了不该阻断 emit / sync 总结输出。
+    // 把本次实际有 from→to 变化的管控包**显式**作为位置参数传给 npm install,强制 npm 重新
+    // resolve lockfile entry。原因:user app 老 lockfile 可能锁着 alpha 版本,纯 `npm install`
+    // 看 lockfile 锁定值跟 package.json spec ("latest" range) 兼容会保留 alpha,导致 sync 后
+    // package.json 写了 latest 但实际还是装 alpha。显式 `npm install foo@latest bar@latest`
+    // 会重新解析这些包,lockfile 跟着更新。没变化的包不动,避免 noisy lockfile diff。
+    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT。
+    const installArgs = ['install', '--no-audit', '--no-fund', '--ignore-scripts'];
+    for (const bump of upgradedPackages) {
+        installArgs.push(`${bump.name}@${bump.to}`);
+    }
+    (0, logger_1.log)('sync', `Running npm ${installArgs.join(' ')}...`);
     let installError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts'], {
+        (0, node_child_process_1.execFileSync)('npm', installArgs, {
             cwd: targetDir,
             stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
         });
@@ -181,12 +191,13 @@ function readPackageJson(pkgJsonPath) {
     return JSON.parse(node_fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));
 }
 /**
- * 把 user app package.json 里已装的 @lark-apaas/* 包钉到 PINNED_PLATFORM_VERSIONS 表版本。
- * 由 `miaoda app sync` 和 `miaoda app init`（template 渲染后、install 之前）共用。
+ * 把 user app package.json 里已装的 @lark-apaas/* 平台包改写成 MANAGED_PLATFORM_PACKAGES
+ * 表里的目标 spec（缺省 `"latest"`）。由 `miaoda app sync` 和 `miaoda app init`（template
+ * 渲染后、install 之前）共用。
  *
- * - user app 已装的 PINNED 包 → 钉到表版本
- * - user app 未装的 PINNED 包 → 不引入（sync 的职责是对齐，不是塞依赖）
- * - 装着但不在 PINNED 表的 @lark-apaas/* 包 → 完全不动
+ * - user app 已装的管控包 → 写表里的目标 spec（默认 latest，紧急止血时可改具体版本）
+ * - user app 未装的管控包 → 不引入（sync 的职责是对齐，不是塞依赖）
+ * - 装着但不在白名单的 @lark-apaas/* 包 → 完全不动
  *
  * @param logPrefix 用于 `[<prefix>]   deps.xxx: a → b` 日志前缀；sync 流程传 'sync'，init 流程传 'init'。
  */
@@ -201,9 +212,9 @@ function upgradePlatformDeps(targetDir, logPrefix = 'sync') {
         if (!deps || typeof deps !== 'object')
             continue;
         for (const name of Object.keys(deps)) {
-            if (!Object.prototype.hasOwnProperty.call(PINNED_PLATFORM_VERSIONS, name))
+            if (!Object.prototype.hasOwnProperty.call(MANAGED_PLATFORM_PACKAGES, name))
                 continue;
-            const target = PINNED_PLATFORM_VERSIONS[name];
+            const target = MANAGED_PLATFORM_PACKAGES[name];
             const from = deps[name];
             if (from === target)
                 continue;

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

@@ -2,16 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FULLSTACK_CLI_PIN_SPEC = void 0;
 /**
- * 临时钉死 `@lark-apaas/fullstack-cli` 的 npx 调用版本。
+ * `@lark-apaas/fullstack-cli` 的 npx 调用 spec。
  *
  * 用于 user app `package.json` 里所有 `npx -y @lark-apaas/fullstack-cli ...` 调用 ——
- * sync 规则会按本常量生成 `npx -y <FULLSTACK_CLI_PIN_SPEC> ...`，确保 user app 每次
- * postinstall / gen-db-schema / sync 都拉到验证过能装插件的版本（避免 npx 拉 latest
- * 时碰到外部 prerelease 回归版本）。
- *
- * 维护：
- *   - 跟 src/cli/handlers/app/sync.ts 里 PINNED_PLATFORM_VERSIONS['@lark-apaas/fullstack-cli']
- *     **保持一致**（前者用于 user app dependencies dep bump，后者用于 npm script 里 npx 调用）
- *   - 一旦 latest fullstack-cli 稳定且 token 鉴权回归 OK，可以去掉版本钉，让 npx 走 latest
+ * 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@1.1.49-alpha.0';
+exports.FULLSTACK_CLI_PIN_SPEC = '@lark-apaas/fullstack-cli@latest';

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

@@ -6,15 +6,15 @@
  * 无数据库、无 nestjs-cli。所以规则集是 nestjs-react-fullstack 的子集：只保留
  * scripts/.githooks/ 派生 + 基础 npm scripts，不动 nest-cli.json / drizzle / tsconfig.node.json。
  *
- * dev-local.sh 跟 nestjs-react-fullstack 不同（单进程 npm run dev，MIAODA_APP_TYPE=4），
- * 单独维护在 upgrade/templates/design-stack/templates/scripts/dev-local.sh。
+ * 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.sh + 通用 dev.sh / hooks/run-precommit.js）
+        // 1. 派生 scripts/（含 design 专属 dev-local.js + 通用 dev.sh / hooks/run-precommit.js）
         {
             type: 'directory',
             from: 'scripts',
@@ -90,7 +90,7 @@ exports.SYNC_CONFIG = {
         {
             type: 'add-script',
             name: 'dev:local',
-            command: './scripts/dev-local.sh',
+            command: 'node ./scripts/dev-local.js',
             overwrite: false,
         },
     ],

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

@@ -13,7 +13,7 @@ const fullstack_cli_pin_1 = require("../../config/fullstack-cli-pin");
 exports.SYNC_CONFIG = {
     sync: [
         // ===== fullstack-cli sync 同款规则（对齐沙箱行为） =====
-        // 1. 派生 scripts 目录（包含 dev.sh / dev-local.sh / dev.js / build.sh / run.sh /
+        // 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',
@@ -131,7 +131,7 @@ exports.SYNC_CONFIG = {
         // 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.sh。
+        //     本地走 miaoda app sync 兜底 + dev-local.js。
         {
             type: 'patch-script',
             name: 'dev',
@@ -155,12 +155,12 @@ exports.SYNC_CONFIG = {
         },
         // ===== miaoda-cli 本地开发新增规则（fullstack-cli sync 不会执行） =====
         // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
-        //     dev.sh 在 SANDBOX_ID 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.sh；显式 dev:local
+        //     dev.sh 在 SANDBOX_ID 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.js；显式 dev:local
         //     用于 agent 在本地稳定调试，不受任何 env 影响。
         {
             type: 'add-script',
             name: 'dev:local',
-            command: './scripts/dev-local.sh',
+            command: 'node ./scripts/dev-local.js',
             overwrite: false,
         },
         // M2. tsconfig.node.json 合并 watchOptions.preserveWatchOutput —— tsc --watch 默认每次

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

@@ -17,17 +17,13 @@ exports.TEMPLATE_PACKAGE_BY_STACK = {
     'nestjs-react-fullstack': '@lark-apaas/coding-template-nestjs-react-fullstack',
 };
 /**
- * 短名 → template 包钉死版本。renderTemplate 默认按这张表取版本号，表外 stack 走 npm latest。
+ * 短名 → template 包钉版表。renderTemplate 默认按这张表取版本号，表外 stack 跟 npm latest。
  *
- * 钉死稳定版本而非跟 alpha dist-tag —— alpha 通道被多团队共享，外部 prerelease 时常打过去，
- * 自动跟 alpha 会把回归版本拉进 user app。每次升基线人工 review 一次再改这里。
+ * 上线起所有 stack 跟随 latest dist-tag（保留 export + 表结构是为了紧急止血时可以一行钉版
+ * 不动 caller，例如 `'nestjs-react-fullstack': '0.1.0-alpha.6'`）。
  * 用户显式传 `--conf '{"version": "..."}'` 仍 override 此默认值。
  */
-exports.TEMPLATE_PINNED_VERSION_BY_STACK = {
-    'nestjs-react-fullstack': '0.1.0-alpha.6',
-    html: '0.1.5-alpha.6',
-    // vite-react 暂不钉版，跟 latest dist-tag（新版正常迭代后再纳入钉版）
-};
+exports.TEMPLATE_PINNED_VERSION_BY_STACK = {};
 exports.SUPPORTED_STACKS = Object.keys(exports.TEMPLATE_PACKAGE_BY_STACK);
 // template/ 内以下划线开头的占位文件名在渲染时改名。
 // 原因：
@@ -46,8 +42,7 @@ function renderTemplate(opts) {
             next_actions: [`可用 stack：${exports.SUPPORTED_STACKS.join(', ')}`],
         });
     }
-    // 默认按 TEMPLATE_PINNED_VERSION_BY_STACK 取钉版（避免 npm latest 碰外部 prerelease 回归）；
-    // 表外 stack fallback 到 'latest'；用户显式传 --conf.version 仍 override 钉版。
+    // 缺省走 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;

package/dist/utils/coding-steering.js

@@ -9,11 +9,6 @@ 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';
-// 钉死稳定 alpha 版本而非跟 `alpha` dist-tag —— alpha 通道被多个团队共享，外部 prerelease
-// 时常打过去，自动跟 alpha 会把回归版本拉进 user app。维护这个常量比维护 alpha 通道可控。
-// 用户显式传具体版本（如 `miaoda skills sync 0.2.0`）仍 override 这个默认值。
-// 升基线时：跑端到端 smoke（init → skills sync → 看 skills 内容）→ 改这个常量。
-const DEFAULT_PINNED_VERSION = '0.1.6-alpha.11';
 function inferMode() {
     // process.env.SANDBOX_ID 非空 → 沙箱；其他（undefined / 空串）→ 本地
     return process.env.SANDBOX_ID ? 'sandbox' : 'local';
@@ -44,7 +39,7 @@ function inferMode() {
  */
 function syncCodingSteering(opts) {
     const logPrefix = opts.logPrefix ?? 'skills';
-    const effectiveVersion = opts.version ?? DEFAULT_PINNED_VERSION;
+    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})...`);

package/package.json

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

package/upgrade/templates/README.md

@@ -9,7 +9,7 @@ upgrade/
 └── templates/
     └── <stack>/
         ├── files/                ← 文件模式：按相对路径整文件覆盖
-        │   └── <rel-path>        ← 例如 scripts/dev-local.sh → <app>/scripts/dev-local.sh
+        │   └── <rel-path>        ← 例如 scripts/dev-local.js → <app>/scripts/dev-local.js
         └── patches/              ← JSON merge 模式：按相对路径 deep merge（任意 JSON 文件）
             └── <rel-path>.json   ← 例如 package.json / tsconfig.json / nest-cli.json
 ```

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// ============================================================================
+// 本地开发启动脚本（由 miaoda app sync 维护，请勿手改）
+// Stack: design-stack
+//
+// 流程:
+//   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 拆分）
+//
+// 设计同 nestjs-react-fullstack/dev-local.js,SDK 包不需要自己 require('dotenv'),
+// env 加载收敛在启动脚本单点。SUDA_WEBUSER 适配同 nrf 那份。
+// ============================================================================
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, spawn, spawnSync } = require('node:child_process');
+
+process.chdir(path.resolve(__dirname, '..'));
+
+function warn(msg) {
+  if (process.stderr.isTTY) process.stderr.write(`\x1b[33mWARNING: ${msg}\x1b[0m\n`);
+  else process.stderr.write(`WARNING: ${msg}\n`);
+}
+
+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...');
+const hasLarkCli = spawnSync('command', ['-v', 'lark-cli'], { shell: true, stdio: 'ignore' }).status === 0;
+if (hasLarkCli) {
+  let appId = '';
+  try {
+    appId = JSON.parse(fs.readFileSync('.spark/meta.json', 'utf8')).app_id || '';
+  } catch {
+    /* meta.json 不存在或非法 JSON */
+  }
+  if (appId) {
+    const r = spawnSync('lark-cli', ['apps', '+env-pull', '--app-id', appId, '--as', 'user'], {
+      stdio: 'inherit',
+    });
+    if (r.status !== 0) warn('env pull 失败，继续按 .env.local 现状启动');
+  } else {
+    warn('.spark/meta.json 缺 app_id，请先跑 `miaoda app init --app-id <id>`');
+  }
+} else {
+  warn('lark-cli 未安装，跳过 env pull；请确保 .env.local 已就绪');
+}
+
+// skills sync —— --local 切 flat layout;临时钉 @alpha,等 0.1.7 发到 latest 后切回。
+console.log('[dev-local] (2/4) miaoda skills sync...');
+try {
+  execSync('npx -y @lark-apaas/miaoda-cli@alpha skills sync --local', { stdio: 'inherit' });
+} catch {
+  console.log('  (skills sync 失败，继续启动)');
+}
+
+console.log('[dev-local] (3/4) loading .env / .env.local...');
+const dotenv = require('dotenv');
+dotenv.config({ path: '.env.local' });
+dotenv.config({ path: '.env' });
+
+if (process.env.SUDA_WEBUSER) {
+  const raw = process.env.SUDA_WEBUSER;
+  try {
+    JSON.parse(raw);
+  } catch {
+    try {
+      const unescaped = raw.replace(/\\"/g, '"');
+      JSON.parse(unescaped);
+      process.env.SUDA_WEBUSER = unescaped;
+    } catch {
+      warn(`SUDA_WEBUSER 解析失败,值头部: ${raw.slice(0, 80)}...`);
+    }
+  }
+}
+
+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));
+child.on('error', (err) => {
+  console.error(err);
+  process.exit(1);
+});

package/upgrade/templates/design-stack/templates/scripts/dev.sh

@@ -3,7 +3,7 @@
 #   - SANDBOX_ID 非空（沙箱平台注入应用所属沙箱 ID）→ 直接跑 dev.js
 #       （保活 / restart loop / 文件日志 —— 沙箱生产形态）。脚本同步由平台 pod 启动阶段做过，
 #       dev 入口不再额外 `npm run upgrade`。
-#   - 否则（本地）→ 走 miaoda app sync 兜底 + 跑 dev-local.sh：纯 stdout、崩了就崩、Agent 友好。
+#   - 否则（本地）→ 走 miaoda app sync 兜底 + 跑 dev-local.js：纯 stdout、崩了就崩、Agent 友好。
 # 显式想跑本地路径可用 `npm run dev:local`（绕过 SANDBOX_ID 判断）。
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -12,14 +12,15 @@ if [ -n "${SANDBOX_ID:-}" ]; then
   exec node "$SCRIPT_DIR/dev.js" "$@"
 fi
 
-if [ ! -x "$SCRIPT_DIR/dev-local.sh" ]; then
-  echo "[dev] scripts/dev-local.sh 缺失或不可执行；先跑 \`npx -y @lark-apaas/miaoda-cli@alpha app sync\` 同步平台脚本" >&2
+if [ ! -f "$SCRIPT_DIR/dev-local.js" ]; then
+  echo "[dev] scripts/dev-local.js 缺失；先跑 \`npx -y @lark-apaas/miaoda-cli@alpha app sync\` 同步平台脚本" >&2
   exit 1
 fi
 
 # 本地启动前先跑一次 miaoda app sync：同步 platform-controlled 内容 + 升 @lark-apaas/* 到
-# 钉版 + 迁移老 npm scripts。沙箱不走这里（SANDBOX_ID 分支已经 exec return）。
-# 走 npx 不依赖用户全局装 miaoda；钉到 @alpha dist-tag 跟随最新发布。
+# latest + 迁移老 npm scripts。沙箱不走这里（SANDBOX_ID 分支已经 exec return）。
+# 临时钉 @alpha：latest dist-tag 还停在老版（0.1.6，无 app sync 子命令）；等 0.1.7 发到
+# latest 后切回 @latest。
 npx -y @lark-apaas/miaoda-cli@alpha app sync || echo "[dev] miaoda app sync 失败，按现状继续" >&2
 
-exec "$SCRIPT_DIR/dev-local.sh" "$@"
+exec node "$SCRIPT_DIR/dev-local.js" "$@"

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// ============================================================================
+// 本地开发启动脚本（由 miaoda app sync 维护，请勿手改）
+// Stack: nestjs-react-fullstack
+//
+// 流程:
+//   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）
+//
+// 关键设计：本脚本在 spawn 子进程之前先把 .env / .env.local 加载到 process.env，
+// 然后 spawn 的 server / client 进程通过 env 继承直接拿到——SDK（fullstack-nestjs-core
+// / fullstack-vite-preset / fullstack-rspack-preset）无需自己 require('dotenv')。
+//
+// SUDA_WEBUSER 适配：沙箱 env pull 下发到 .env.local 的形态是
+// `SUDA_WEBUSER="{\"user_id\":\"...\"}"`（shell-quoted JSON），dotenv@17 剥外层引号后
+// 保留内部 `\"` 转义不还原，导致 process.env.SUDA_WEBUSER 是 `{\"user_id\":\"...\"}`
+// 这种带反斜杠串，下游 JSON.parse 直接挂。这里做一次「直接 parse 失败则 unescape
+// 后重 parse」兜底，把容错收敛在启动期单点，下游拿到干净 JSON 字符串。
+// ============================================================================
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, spawn, spawnSync } = require('node:child_process');
+
+process.chdir(path.resolve(__dirname, '..'));
+
+function warn(msg) {
+  if (process.stderr.isTTY) process.stderr.write(`\x1b[33mWARNING: ${msg}\x1b[0m\n`);
+  else process.stderr.write(`WARNING: ${msg}\n`);
+}
+
+if (!process.env.MIAODA_APP_TYPE) process.env.MIAODA_APP_TYPE = '3';
+process.env.MIAODA_LOCAL_DEV = '1';
+
+// 1. env pull
+console.log('[dev-local] (1/4) env pull...');
+const hasLarkCli = spawnSync('command', ['-v', 'lark-cli'], { shell: true, stdio: 'ignore' }).status === 0;
+if (hasLarkCli) {
+  let appId = '';
+  try {
+    appId = JSON.parse(fs.readFileSync('.spark/meta.json', 'utf8')).app_id || '';
+  } catch {
+    /* meta.json 不存在或非法 JSON */
+  }
+  if (appId) {
+    const r = spawnSync('lark-cli', ['apps', '+env-pull', '--app-id', appId, '--as', 'user'], {
+      stdio: 'inherit',
+    });
+    if (r.status !== 0) warn('env pull 失败，继续按 .env.local 现状启动');
+  } else {
+    warn('.spark/meta.json 缺 app_id，请先跑 `miaoda app init --app-id <id>`');
+  }
+} else {
+  warn('lark-cli 未安装，跳过 env pull；请确保 .env.local 已就绪');
+}
+
+// 2. skills sync —— --local 切到 flat layout (.agents/skills + .claude/skills 软链),
+// 跟沙箱 nested layout 区分。临时钉 @alpha:latest dist-tag 还停在老版 (0.1.6,无 skills /
+// app sync 子命令);等 0.1.7 发到 latest 后切回 @latest。
+console.log('[dev-local] (2/4) miaoda skills sync...');
+try {
+  execSync('npx -y @lark-apaas/miaoda-cli@alpha skills sync --local', { stdio: 'inherit' });
+} catch {
+  console.log('  (skills sync 失败，继续启动)');
+}
+
+// 3. 加载 .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...');
+const dotenv = require('dotenv');
+dotenv.config({ path: '.env.local' });
+dotenv.config({ path: '.env' });
+
+// SUDA_WEBUSER 适配（详见文件头注释）
+if (process.env.SUDA_WEBUSER) {
+  const raw = process.env.SUDA_WEBUSER;
+  try {
+    JSON.parse(raw);
+  } catch {
+    try {
+      const unescaped = raw.replace(/\\"/g, '"');
+      JSON.parse(unescaped);
+      process.env.SUDA_WEBUSER = unescaped;
+    } catch {
+      warn(`SUDA_WEBUSER 解析失败,值头部: ${raw.slice(0, 80)}...`);
+    }
+  }
+}
+
+// 4. 并发起前后端 dev server
+console.log('[dev-local] (4/4) 并发起 dev:server + dev:client');
+const child = spawn(
+  'npx',
+  [
+    '--no-install',
+    'concurrently',
+    '--names',
+    'server,client',
+    '--prefix-colors',
+    'blue,green',
+    '--kill-others-on-fail',
+    'npm run dev:server',
+    'npm run dev:client',
+  ],
+  { stdio: 'inherit', env: process.env },
+);
+child.on('exit', (code) => process.exit(code ?? 0));
+child.on('error', (err) => {
+  console.error(err);
+  process.exit(1);
+});

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/dev.sh

@@ -3,7 +3,7 @@
 #   - SANDBOX_ID 非空（沙箱平台注入应用所属沙箱 ID）→ 直接跑 dev.js
 #       （保活 / restart loop / 文件日志 —— 沙箱生产形态）。脚本同步由平台 pod 启动阶段做过，
 #       dev 入口不再额外 `npm run upgrade`。
-#   - 否则（本地）→ 走 miaoda app sync 兜底 + 跑 dev-local.sh：纯 stdout、崩了就崩、Agent 友好。
+#   - 否则（本地）→ 走 miaoda app sync 兜底 + 跑 dev-local.js：纯 stdout、崩了就崩、Agent 友好。
 # 显式想跑本地路径可用 `npm run dev:local`（绕过 SANDBOX_ID 判断）。
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -12,14 +12,15 @@ if [ -n "${SANDBOX_ID:-}" ]; then
   exec node "$SCRIPT_DIR/dev.js" "$@"
 fi
 
-if [ ! -x "$SCRIPT_DIR/dev-local.sh" ]; then
-  echo "[dev] scripts/dev-local.sh 缺失或不可执行；先跑 \`npx -y @lark-apaas/miaoda-cli@alpha app sync\` 同步平台脚本" >&2
+if [ ! -f "$SCRIPT_DIR/dev-local.js" ]; then
+  echo "[dev] scripts/dev-local.js 缺失；先跑 \`npx -y @lark-apaas/miaoda-cli@alpha app sync\` 同步平台脚本" >&2
   exit 1
 fi
 
 # 本地启动前先跑一次 miaoda app sync：同步 platform-controlled 内容 + 升 @lark-apaas/* 到
-# 钉版 + 迁移老 npm scripts。沙箱不走这里（SANDBOX_ID 分支已经 exec return）。
-# 走 npx 不依赖用户全局装 miaoda；钉到 @alpha dist-tag 跟随最新发布。
+# latest + 迁移老 npm scripts。沙箱不走这里（SANDBOX_ID 分支已经 exec return）。
+# 临时钉 @alpha：latest dist-tag 还停在老版（0.1.6，无 app sync 子命令）；等 0.1.7 发到
+# latest 后切回 @latest。
 npx -y @lark-apaas/miaoda-cli@alpha app sync || echo "[dev] miaoda app sync 失败，按现状继续" >&2
 
-exec "$SCRIPT_DIR/dev-local.sh" "$@"
+exec node "$SCRIPT_DIR/dev-local.js" "$@"

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

@@ -1,53 +0,0 @@
-#!/usr/bin/env bash
-# ============================================================================
-# 本地 dev 启动脚本(平台控制,通过 `miaoda app upgrade` 同步,请勿手改)
-# Stack: design-stack(SSR-only,无 server 业务逻辑,无数据库)
-# 流程:env pull → skills sync → 起 dev server
-# ============================================================================
-set -euo pipefail
-ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-cd "$ROOT_DIR"
-
-# Stack 是 design-stack,对应 miaoda CLI 的 design scene
-# 沙箱里这个 env 由平台注入,本地 dev 由本脚本兜底,确保 miaoda 子命令(skills/sync)能看见
-export MIAODA_APP_TYPE="${MIAODA_APP_TYPE:-4}"
-
-# 本地开发总开关:SDK 据此启用本地兜底逻辑(view-context 占位填充 / __runtime__ 反代 / csrf+webuser)
-# 沙箱 dev / 生产不设此 env,SDK 行为完全不变
-export MIAODA_LOCAL_DEV=1
-
-# 临时:绕 npmmirror/bnpm 内网到 npmjs 的同步延迟,等 coding-steering 正式版去掉
-export MIAODA_NPM_REGISTRY="${MIAODA_NPM_REGISTRY:-https://registry.npmjs.org/}"
-
-# === .env.local / .env 加载由 SDK 侧负责，本脚本不再手工 source ===
-# fullstack-nestjs-core 在 module init 通过 dotenv 读 .env.local + .env；
-# fullstack-{vite,rspack}-preset 的 defineConfig 同理。优先级:shell > .env.local > .env。
-
-# 1. 拉本地 dev 所需 ENV(jwt / cookie 等,写入 .env.local)
-#    app_id 从 .spark/meta.json 读 —— `miaoda app init --app-id <id>` 时持久化的权威源,
-#    后续 dev / sync 全部沿用这一个值;不在脚本里 hack 别的推断渠道。
-#    lark-cli 子命令真名是 `+env-pull`（带 + 前缀单 token,不是 `env pull` 空格分隔）;
-#    `--as user` 必须显式:env-pull 只接受 user identity,默认 bot 会校验失败。
-echo "[dev-local] (1/3) env pull..."
-if command -v lark-cli >/dev/null 2>&1; then
-  # 用 node 读 .spark/meta.json,不引 python3 依赖(user app 必装 node)。
-  APP_ID=$(node -e 'try{process.stdout.write(JSON.parse(require("fs").readFileSync(".spark/meta.json","utf8")).app_id||"")}catch(e){}' 2>/dev/null || echo "")
-  if [ -n "$APP_ID" ]; then
-    lark-cli apps +env-pull --app-id "$APP_ID" --as user || echo "  (env pull 失败,后续按 .env.local 现状继续)"
-  else
-    echo "  (.spark/meta.json 缺 app_id,先跑 \`miaoda app init --app-id <id>\` 写入)"
-  fi
-else
-  echo "  (lark-cli 未装,跳过 env pull;请确保 .env.local 已就绪)"
-fi
-
-# 2. 同步 stack 对应 skills(coding-steering)。走 npx 不依赖用户全局装 miaoda;
-#    钉到 @alpha dist-tag 跟随最新发布,miaoda-cli 通道我们自己控制风险小。
-echo "[dev-local] (2/3) miaoda skills sync..."
-npx -y @lark-apaas/miaoda-cli@alpha skills sync || echo "  (skills sync 失败,继续启动)"
-
-# 3. 起 dev server(design-stack 只有 SSR 渲染,单进程即可;不走 scripts/dev.js 的保活)
-#    如果模板的 npm run dev 本身就是裸进程(无保活)则直接调即可;
-#    如果 design-stack 模板的 dev 也是 dev.js 包装,后续需要新增 dev:raw 之类的直通命令
-echo "[dev-local] (3/3) npm run dev"
-exec npm run dev

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

@@ -1,61 +0,0 @@
-#!/usr/bin/env bash
-# ============================================================================
-# 本地 dev 启动脚本（平台控制，通过 `miaoda app upgrade` 同步，请勿手改）
-# Stack: nestjs-react-fullstack
-# 流程：env pull → skills sync → 并发起 server + client
-# ============================================================================
-set -euo pipefail
-ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-cd "$ROOT_DIR"
-
-# === Sentinels（必须由本脚本注入，不属于 .env.local 业务范畴）===
-
-# Stack 对应 miaoda CLI 的 application scene；沙箱里平台注入，本地脚本兜底，
-# 让后续 miaoda 子命令（skills sync 等）走对的 scene。
-export MIAODA_APP_TYPE="${MIAODA_APP_TYPE:-3}"
-
-# 本地开发总开关：SDK（fullstack-vite-preset / fullstack-rspack-preset /
-# fullstack-nestjs-core）据此启用本地兜底逻辑：
-#   - vite/rspack-preset：反代 /__runtime__ 到沙箱（带 cookie / webuser header）
-#   - nestjs-core：从 cookie 补 csrf header + 注入 webuser header
-# 沙箱 dev / 生产不设此 env，SDK 行为完全不变。
-export MIAODA_LOCAL_DEV=1
-
-# 临时：绕 npmmirror/bnpm 内网到 npmjs 的同步延迟，等 coding-steering 正式版去掉。
-export MIAODA_NPM_REGISTRY="${MIAODA_NPM_REGISTRY:-https://registry.npmjs.org/}"
-
-# === .env.local / .env 加载由 SDK 侧负责，本脚本不再手工 source ===
-# fullstack-nestjs-core 在 module init 通过 dotenv 读 .env.local + .env；
-# fullstack-{vite,rspack}-preset 的 defineConfig 同理。优先级：shell > .env.local > .env。
-# 历史版本曾在这里用 bash 自写 parser，引号 / 多行 / 行尾注释处理不全且重复造轮子，已下放到 SDK。
-
-# 1. 拉本地 dev 所需 ENV（jwt / cookie / sandbox URL 等，写入 .env.local）
-#    app_id 从 .spark/meta.json 读 —— `miaoda app init --app-id <id>` 时持久化的权威源，
-#    后续 dev / sync 全部沿用这一个值；不在脚本里 hack 别的推断渠道。
-#    lark-cli 子命令真名是 `+env-pull`（带 + 前缀单 token，不是 `env pull` 空格分隔）；
-#    `--as user` 必须显式：env-pull 只接受 user identity，默认 bot 会校验失败。
-echo "[dev-local] (1/3) env pull..."
-if command -v lark-cli >/dev/null 2>&1; then
-  # 用 node 读 .spark/meta.json，不引 python3 依赖（user app 必装 node）。
-  APP_ID=$(node -e 'try{process.stdout.write(JSON.parse(require("fs").readFileSync(".spark/meta.json","utf8")).app_id||"")}catch(e){}' 2>/dev/null || echo "")
-  if [ -n "$APP_ID" ]; then
-    lark-cli apps +env-pull --app-id "$APP_ID" --as user || echo "  (env pull 失败，后续按 .env.local 现状继续)"
-  else
-    echo "  (.spark/meta.json 缺 app_id，先跑 \`miaoda app init --app-id <id>\` 写入)"
-  fi
-else
-  echo "  (lark-cli 未装，跳过 env pull；请确保 .env.local 已就绪)"
-fi
-
-# 2. 同步 stack 对应 skills（coding-steering）。走 npx 不依赖用户全局装 miaoda；
-#    钉到 @alpha dist-tag 跟随最新发布，miaoda-cli 通道我们自己控制风险小。
-echo "[dev-local] (2/3) miaoda skills sync..."
-npx -y @lark-apaas/miaoda-cli@alpha skills sync || echo "  (skills sync 失败，继续启动)"
-
-# 3. 并发起 dev:server（NestJS）+ dev:client（vite/rspack）
-#    端口、SANDBOX_* 等业务 env 由 SDK 内 dotenv 加载，不在 banner 里假装显示。
-#    不走 scripts/dev.js（保活 / restart / 日志写文件那套）—— 本地崩就崩，错日志直接 stdout。
-echo "[dev-local] (3/3) 并发起 dev:server + dev:client"
-exec npx --no-install concurrently \
-  --names "server,client" --prefix-colors "blue,green" --kill-others-on-fail \
-  "npm run dev:server" "npm run dev:client"