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

package/upgrade/templates/README.md

@@ -0,0 +1,34 @@
+# upgrade/templates/
+
+平台管控的脚手架增量内容，按 stack 分目录，由 `miaoda app upgrade` 同步到用户项目。
+
+## 目录约定
+
+```
+upgrade/
+└── templates/
+    └── <stack>/
+        ├── files/                ← 文件模式：按相对路径整文件覆盖
+        │   └── <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
+```
+
+## 同步行为
+
+- **files/**：递归遍历，按相对路径全量覆盖 targetDir。`.sh` 后缀文件同步后自动 `chmod +x`。
+- **patches/**：递归遍历，**每个 `.json` 文件** 都跟 targetDir 同路径文件做 deep merge：
+  - 两边都必须是 JSON object（否则报错）
+  - value 是 object → 递归 merge；value 是数组 / 标量 → 整体替换
+  - 目标文件不存在则报错（patches 是补丁性质，不负责创建文件；app init 应该先创建）
+  - patches 下非 `.json` 文件会被跳过（预留给将来其它 patch 类型）
+- 不做用户改动保护（本期约定：`upgrade/templates/` 下的文件路径由平台拥有，用户不应手改）。
+
+## 跟 `miaoda skills sync` 的区别
+
+| 链路 | 源 | 内容 | 目标 |
+|---|---|---|---|
+| `miaoda skills sync` | NPM 包 `@lark-apaas/coding-steering` | agent skills（`.md`） | `<app>/.agent/skills/steering/<stack>/` |
+| `miaoda app upgrade`  | 本仓 `upgrade/templates/<stack>/` | 启动脚本、package.json 字段等 | `<app>/` 项目根 |
+
+两者独立调用，互不依赖。

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

@@ -0,0 +1,4 @@
+#!/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

@@ -0,0 +1,83 @@
+#!/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 已就绪');
+}
+
+console.log('[dev-local] (2/4) miaoda skills sync...');
+try {
+  execSync('npx -y @lark-apaas/miaoda-cli@latest skills sync', { 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

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

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

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// FULLSTACK_PRECOMMIT_V1
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+const SEP = '  ' + '─'.repeat(36);
+
+function failAndExit(step, body) {
+  process.stderr.write('\n✗ pre-commit failed: ' + step + '\n');
+  process.stderr.write(SEP + '\n');
+  if (body && body.length > 0) {
+    process.stderr.write(body.replace(/\s+$/, '') + '\n');
+  }
+  process.stderr.write(SEP + '\n');
+  process.stderr.write('  bypass: git commit --no-verify\n');
+  process.exit(1);
+}
+
+function runLint() {
+  const cwd = process.cwd();
+  const res = spawnSync('npm', ['run', 'lint'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: process.env,
+  });
+  if (res.error) {
+    failAndExit('lint', String(res.error.message || res.error));
+  }
+  if (res.status !== 0) {
+    const stdout = res.stdout ? res.stdout.toString() : '';
+    const stderr = res.stderr ? res.stderr.toString() : '';
+    failAndExit('lint', stdout + '\n' + stderr);
+  }
+}
+
+runLint();

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

@@ -0,0 +1,4 @@
+#!/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/.gitignore.append

@@ -0,0 +1,8 @@
+
+# ==========================================
+# fullstack-cli managed files
+# ==========================================
+# scripts/ directory is auto-generated
+# DO NOT modify manually
+scripts/
+

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

@@ -0,0 +1,16 @@
+run = ["npm", "run", "dev"] # 默认 spark-cli dev
+hidden = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]
+lint = ["npm", "run", "lint"]
+test = ["npm", "run", "test"]
+genDbSchema = ["npm", "run", "gen:db-schema"]
+genOpenApiClient = ["npm", "run", "gen:openapi"]
+
+[deployment]
+build = ["npm", "run", "build"]
+run = ["npm", "run", "start"]
+
+[files]
+[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"]

package/upgrade/templates/nestjs-react-fullstack/templates/drizzle.config.ts

@@ -0,0 +1,55 @@
+import { defineConfig, Config } from 'drizzle-kit';
+require('dotenv').config();
+
+const outputDir = process.env.__DRIZZLE_OUT_DIR__ || './tmp/.introspect';
+const schemaPath = process.env.__DRIZZLE_SCHEMA_PATH__ || './server/database/schema.ts';
+
+const parsedUrl = new URL(process.env.SUDA_DATABASE_URL || '');
+
+const envSchemaFilter = process.env.DRIZZLE_SCHEMA_FILTER;
+const urlSchemaFilter = parsedUrl.searchParams.get('schema');
+
+const schemaFilter = (envSchemaFilter ?? urlSchemaFilter ?? '')
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+parsedUrl.searchParams.delete('schema'); // 移除schema参数，避免 drizzle-kit 解析错误
+
+// 默认排除的系统对象（PostgreSQL 扩展和系统视图）
+// 这些对象在 drizzle-kit introspect 时可能导致无效的 JS 代码生成
+const SYSTEM_OBJECTS_EXCLUSIONS = [
+  '!spatial_ref_sys',       // PostGIS 空间参考系统表
+  '!geography_columns',     // PostGIS 地理列视图
+  '!geometry_columns',      // PostGIS 几何列视图
+  '!raster_columns',        // PostGIS 栅格列视图
+  '!raster_overviews',      // PostGIS 栅格概览视图
+  '!pg_stat_statements',    // pg_stat_statements 扩展
+  '!pg_stat_statements_info', // pg_stat_statements 扩展
+  '!part_config',           // pg_partman 分区配置表
+  '!part_config_sub',       // pg_partman 子分区配置表
+  '!table_privs',           // 系统权限视图
+];
+
+const envTablesFilter = process.env.DRIZZLE_TABLES_FILTER;
+const userTablesFilter = (envTablesFilter ?? '*')
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+// 合并用户过滤器和系统对象排除
+// 用户可以通过设置 DRIZZLE_TABLES_FILTER 来覆盖（如果需要包含某些系统对象）
+const tablesFilter = [...userTablesFilter, ...SYSTEM_OBJECTS_EXCLUSIONS];
+
+const config:Config = {
+  schema: schemaPath,
+  out: outputDir,
+  tablesFilter,
+  schemaFilter,
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: parsedUrl.toString(),
+  },
+}
+
+export default defineConfig(config);

package/upgrade/templates/nestjs-react-fullstack/templates/helper/gen-openapi.ts

@@ -0,0 +1,34 @@
+// This file is auto-generated by @lark-apaas/fullstack-cli
+import { NestFactory } from '@nestjs/core';
+import { DevToolsV2Module } from '@lark-apaas/fullstack-nestjs-core';
+
+import { AppModule } from '../server/app.module';
+
+/**
+ * 生成 OpenAPI 文档和客户端 SDK
+ *
+ * 此文件由 @lark-apaas/fullstack-cli 自动派生，请勿手动修改
+ * 每次运行 npm install 时会自动更新
+ */
+async function generateOpenApi() {
+  const app = await NestFactory.create(AppModule, { logger: false });
+  const basePath = process.env.CLIENT_BASE_PATH;
+
+  if (basePath) {
+    app.setGlobalPrefix(basePath);
+  }
+
+  await DevToolsV2Module.mount(app, {
+    basePath,
+    docsPath: '/api_docs',
+    needSetupServer: false,
+    needGenerateClientSdk: true,
+  });
+  
+  process.exit(0); // 主动退出进程，不等待 app 关闭（用户存在场景，未释放 timer 导致 app 卡死问题）
+}
+
+generateOpenApi().catch((err) => {
+  console.error('[OpenAPI] Failed to generate schema', err);
+  process.exitCode = 1;
+});

package/upgrade/templates/nestjs-react-fullstack/templates/nest-cli.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "server",
+  "compilerOptions": {
+    "deleteOutDir": false,
+    "tsConfigPath": "tsconfig.node.json",
+    "assets": [
+      {
+        "include": "capabilities/**/*.json",
+        "outDir": "dist/server",
+        "watchAssets": true
+      }
+    ],
+    "plugins": [
+      {
+        "name": "@nestjs/swagger",
+        "options": {
+          "introspectComments": true,
+          "classValidatorShim": true
+        }
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# This file is auto-generated by @lark-apaas/fullstack-cli
+set -euo pipefail
+
+ROOT_DIR="$(pwd)"
+DIST_DIR="$ROOT_DIR/dist"
+
+# 记录总开始时间
+TOTAL_START=$(node -e "console.log(Date.now())")
+
+# 打印耗时的辅助函数
+print_time() {
+  local start=$1
+  local end=$(node -e "console.log(Date.now())")
+  local elapsed=$((end - start))
+  local seconds=$((elapsed / 1000))
+  local ms=$((elapsed % 1000))
+  echo "   ⏱️  耗时: ${seconds}.$(printf "%03d" $ms)s"
+}
+
+# ==================== 步骤 0 ====================
+echo "🗑️  [0/6] 安装插件"
+STEP_START=$(node -e "console.log(Date.now())")
+npx fullstack-cli action-plugin init
+print_time $STEP_START
+echo ""
+
+# ==================== 步骤 1 ====================
+echo "📝 [1/6] 更新 openapi 代码"
+STEP_START=$(node -e "console.log(Date.now())")
+npm run gen:openapi
+print_time $STEP_START
+echo ""
+
+# ==================== 步骤 2 ====================
+echo "🗑️  [2/6] 清理 dist 目录"
+STEP_START=$(node -e "console.log(Date.now())")
+rm -rf "$ROOT_DIR/dist"
+print_time $STEP_START
+echo ""
+
+# ==================== 步骤 3 ====================
+echo "🗺️  [3/6] 生成路由定义"
+STEP_START=$(node -e "console.log(Date.now())")
+
+# 在 client/server 构建之前生成到 dist/，供 DefinePlugin 注入前端 bundle
+# 注意：nest-cli.json 中 deleteOutDir 必须为 false（模板默认值），否则 nest build 会清掉 dist/
+echo "   ├─ 生成 API 路由定义..."
+npx generate-api-routes --server-dir ./server --out-dir ./dist > /tmp/gen-api-routes.log 2>&1 &
+API_ROUTES_PID=$!
+
+echo "   ├─ 生成页面路由定义..."
+npx generate-page-routes --app-path ./client/src/app.tsx --out-dir ./dist > /tmp/gen-page-routes.log 2>&1 &
+PAGE_ROUTES_PID=$!
+
+API_ROUTES_EXIT=0
+PAGE_ROUTES_EXIT=0
+
+wait $API_ROUTES_PID || API_ROUTES_EXIT=$?
+wait $PAGE_ROUTES_PID || PAGE_ROUTES_EXIT=$?
+
+if [ $API_ROUTES_EXIT -ne 0 ]; then
+  echo "   ⚠️  API 路由生成失败（不影响构建）"
+  cat /tmp/gen-api-routes.log
+else
+  echo "   ✅ API 路由生成完成"
+fi
+
+if [ $PAGE_ROUTES_EXIT -ne 0 ]; then
+  echo "   ⚠️  页面路由生成失败（不影响构建）"
+  cat /tmp/gen-page-routes.log
+else
+  echo "   ✅ 页面路由生成完成"
+fi
+print_time $STEP_START
+echo ""
+
+# ==================== 步骤 4 ====================
+echo "🔨 [4/6] 并行构建 server 和 client"
+STEP_START=$(node -e "console.log(Date.now())")
+
+# 给 server/client 构建子进程预留 8GB heap，缓解 vite build transform 阶段 OOM
+# （典型错误：Reached heap limit Allocation failed）。
+# 仅在外部未设置 NODE_OPTIONS 时注入，允许 CI / 用户通过外部环境变量完全覆盖
+BUILD_NODE_OPTIONS="${NODE_OPTIONS:---max-old-space-size=8192}"
+
+# 根据 only_frontend_change 决定是否构建 server
+if [[ "${only_frontend_change:-false}" == "true" ]]; then
+  echo "🔨 [4/6] 仅构建 client (only_frontend_change=true)"
+
+  echo "   ├─ 启动 client 构建..."
+  NODE_OPTIONS="$BUILD_NODE_OPTIONS" npm run build:client > /tmp/build-client.log 2>&1
+  CLIENT_EXIT=$?
+
+  if [ $CLIENT_EXIT -ne 0 ]; then
+    echo "   ❌ Client 构建失败"
+    cat /tmp/build-client.log
+    exit 1
+  fi
+
+  echo "   ✅ Client 构建完成"
+else
+  echo "🔨 [4/6] 并行构建 server 和 client"
+
+  # 并行构建
+  echo "   ├─ 启动 server 构建..."
+  NODE_OPTIONS="$BUILD_NODE_OPTIONS" npm run build:server > /tmp/build-server.log 2>&1 &
+  SERVER_PID=$!
+
+  echo "   ├─ 启动 client 构建..."
+  NODE_OPTIONS="$BUILD_NODE_OPTIONS" npm run build:client > /tmp/build-client.log 2>&1 &
+  CLIENT_PID=$!
+
+  # 等待两个构建完成
+  SERVER_EXIT=0
+  CLIENT_EXIT=0
+
+  wait $SERVER_PID || SERVER_EXIT=$?
+  wait $CLIENT_PID || CLIENT_EXIT=$?
+
+  # 检查构建结果
+  if [ $SERVER_EXIT -ne 0 ]; then
+    echo "   ❌ Server 构建失败"
+    cat /tmp/build-server.log
+    exit 1
+  fi
+
+  if [ $CLIENT_EXIT -ne 0 ]; then
+    echo "   ❌ Client 构建失败"
+    cat /tmp/build-client.log
+    exit 1
+  fi
+
+  echo "   ✅ Server 构建完成"
+  echo "   ✅ Client 构建完成"
+fi
+
+print_time $STEP_START
+echo ""
+
+# ==================== 步骤 5 ====================
+echo "📦 [5/6] 准备产物"
+STEP_START=$(node -e "console.log(Date.now())")
+
+# 移动 client 下的 HTML 文件到 dist/dist/client，保证 views 路径在 dev/prod 下一致
+# 使用 mv 而非 cp：HTML 不能上传到公网 CDN，移走后 dist/client 中不再包含 HTML
+if [ -d "$DIST_DIR/client" ]; then
+  mkdir -p "$DIST_DIR/dist/client"
+  find "$DIST_DIR/client" -maxdepth 1 -name "*.html" -exec mv {} "$DIST_DIR/dist/client/" \;
+fi
+
+# server 相关产物准备（only_frontend_change=true 时跳过）
+if [[ "${only_frontend_change:-false}" == "true" ]]; then
+  echo "   [skip] 跳过 run.sh/.env 复制 (only_frontend_change=true)"
+else
+  # 拷贝 run.sh 到 dist/（prod 从 dist/ 启动，确保 cwd 一致性）
+  cp "$ROOT_DIR/scripts/run.sh" "$DIST_DIR/"
+
+  # 拷贝 .env 文件（如果存在）
+  if [ -f "$ROOT_DIR/.env" ]; then
+    cp "$ROOT_DIR/.env" "$DIST_DIR/"
+  fi
+fi
+
+# 清理无用文件
+rm -rf "$DIST_DIR/scripts"
+rm -rf "$DIST_DIR/tsconfig.node.tsbuildinfo"
+
+print_time $STEP_START
+echo ""
+
+# ==================== 步骤 6 ====================
+echo "✂️  [6/6] 智能依赖裁剪"
+STEP_START=$(node -e "console.log(Date.now())")
+
+# 智能依赖裁剪（仅全量构建时执行，纯前端场景不打包 server，无需裁剪）
+if [[ "${only_frontend_change:-false}" == "true" ]]; then
+  echo "✂️  [6/6] 跳过智能依赖裁剪 (only_frontend_change=true)"
+else
+  echo "✂️  [6/6] 智能依赖裁剪"
+
+  # 分析实际依赖、复制并裁剪 node_modules、生成精简的 package.json
+  node "$ROOT_DIR/scripts/prune-smart.js"
+fi
+
+print_time $STEP_START
+echo ""
+
+# 总耗时
+echo "构建完成"
+print_time $TOTAL_START
+
+# 输出产物信息
+DIST_SIZE=$(du -sh "$DIST_DIR" | cut -f1)
+if [[ "${only_frontend_change:-false}" == "true" ]]; then
+  echo ""
+  echo "📊 构建产物统计:"
+  echo "   产物大小:        $DIST_SIZE"
+  echo ""
+else
+  NODE_MODULES_SIZE=$(du -sh "$DIST_DIR/node_modules" | cut -f1)
+  echo ""
+  echo "📊 构建产物统计:"
+  echo "   产物大小:        $DIST_SIZE"
+  echo "   node_modules: $NODE_MODULES_SIZE"
+  echo ""
+fi

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

@@ -0,0 +1,111 @@
+#!/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
+console.log('[dev-local] (2/4) miaoda skills sync...');
+try {
+  execSync('npx -y @lark-apaas/miaoda-cli@latest skills sync', { 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);
+});