@lark-apaas/coding-templates 0.1.43-alpha.2 → 0.1.43-alpha.21

package/meta.json

@@ -1,10 +1,16 @@
 {
   "templates": [
+    {
+      "name": "vite-react",
+      "dir": "template-vite-react",
+      "description": "Vite + React 19 + shadcn — jsPage 主推（HMR / Inspector / Capability / OpenTel）",
+      "features": ["typescript", "vite", "hmr", "tailwind", "shadcn-ui", "inspector", "capability", "observable"]
+    },
     {
       "name": "html",
       "dir": "template-html",
-      "description": "纯 HTML — 零依赖，原型验证",
-      "features": ["tailwind-cdn", "dark-mode"]
+      "description": "纯 HTML — Vite dev + HMR + Tailwind v4 + Capability / OpenTel",
+      "features": ["vite", "hmr", "tailwind", "capability", "observable"]
     },
     {
       "name": "nextjs-static",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-templates",
-  "version": "0.1.43-alpha.2",
+  "version": "0.1.43-alpha.21",
   "description": "OpenClaw project templates for mclaw CLI",
   "publishConfig": {
     "access": "public"

package/{template-vite-react/.spark-project → template-html/.spark_project}

@@ -7,12 +7,11 @@ build = ["npm", "run", "build"]
 
 [files]
 [files.restrict]
-pathPatterns = ["package.json", ".spark-project", ".spark/meta.json", ".gitignore"]
+pathPatterns = ["package.json", ".spark_project", ".spark/meta.json", ".gitignore"]
 [files.hidden]
 pathPatterns = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]
 
 [sandbox]
 # 临时兼容老沙箱硬编码探测的 3000 / 8001 端口。
-# 这两个端口由 scripts/mock-health.cjs 占位，Vite dev server 实际监听 CLIENT_DEV_PORT(默认 8080)。
-# 沙箱链路切到新协议后，可改回 [8080]，并删掉 mock-health.cjs。
+# 8001 由 vite dev server 真实占据；3000 由 scripts/mock-health.cjs 占位。
 healthCheck = [8001, 3000]

package/template-html/index.html

@@ -1,23 +1,22 @@
 <!doctype html>
 <html lang="zh-CN">
-    <head>
-        <meta charset="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>应用标题</title>
-        <link href="https://lf3-static.bytednsdoc.com/obj/eden-cn/ylcylz_fsph_ryhs/ljhwZthlaukjlkulzlp/feisuda/feisuda.svg" rel="shortcut icon"/>
-        <script src="https://cdn.tailwindcss.com"></script>
-        <script>
-            // 可选：Tailwind 运行时配置
-            tailwind.config = {};
-        </script>
-        <style>
-            /* 必要的自定义样式（如画布容器尺寸、预览区边框等） */
-        </style>
-    </head>
-    <body class="bg-gray-50">
-        <!-- 画布布局容器 -->
-        <main id="canvas" class="mx-auto max-w-7xl p-6">
-            <!-- 页面内容（由 generate_design 生成的 HTML 片段插入此处） -->
-        </main>
-    </body>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>应用标题</title>
+    <link
+      href="https://lf3-static.bytednsdoc.com/obj/eden-cn/ylcylz_fsph_ryhs/ljhwZthlaukjlkulzlp/feisuda/feisuda.svg"
+      rel="shortcut icon"
+    />
+  </head>
+  <body class="bg-gray-50">
+    <!-- 画布布局容器：业务页面内容放这里 -->
+    <main id="canvas" class="mx-auto max-w-7xl p-6">
+      <h1 class="text-2xl font-semibold">Hello HTML 模板</h1>
+      <p class="mt-2 text-gray-600">编辑 <code>index.html</code> 开始你的应用。</p>
+    </main>
+
+    <!-- 入口模块：装载平台 SDK（capability / observable / ...） + 样式 -->
+    <script type="module" src="/src/main.js"></script>
+  </body>
 </html>

package/template-html/package.json

@@ -5,9 +5,24 @@
   "mclaw": {
     "stack": "html",
     "stackVersion": "0.1.0",
-    "features": ["client"]
+    "features": [
+      "client"
+    ]
   },
   "scripts": {
-    "build": "bash scripts/build.sh"
+    "dev": "concurrently -k -n vite,health 'vite --port 8001 --host 0.0.0.0' 'node scripts/mock-health.cjs'",
+    "build": "bash scripts/build.sh",
+    "lint": "echo 'no lint for plain HTML'"
+  },
+  "dependencies": {
+    "@lark-apaas/client-toolkit-lite": "1.1.7-alpha.6",
+    "@lark-apaas/observable-web": "^1.0.6"
+  },
+  "devDependencies": {
+    "@lark-apaas/coding-vite-preset": "1.0.7-alpha.2",
+    "@tailwindcss/vite": "^4.0.0",
+    "concurrently": "^9",
+    "tailwindcss": "^4.0.0",
+    "vite": "^8"
   }
 }

package/template-html/scripts/build.sh

@@ -3,29 +3,41 @@ set -e
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 OUTPUT="$ROOT/dist/output"
+OUTPUT_RESOURCE="$ROOT/dist/output_resource"
 OUTPUT_STATIC="$ROOT/dist/output_static"
-STATIC_PREFIX="${MCLAW_STATIC_PREFIX:-}"
 
-# 清理
+# 映射平台环境变量到 preset 期望的变量名（同 template-vite-react）
+export CLIENT_BASE_PATH="${MCLAW_APP_ID:+/app/$MCLAW_APP_ID}"
+export ASSETS_CDN_PATH="${MCLAW_CDN_DOMAIN:-/}"
+export NODE_ENV="${NODE_ENV:-production}"
+
 rm -rf "$ROOT/dist"
+
+# 1. Vite 构建 → dist/client/
+npx vite build --outDir "$ROOT/dist/client" --emptyOutDir
+
+# 2. HTML → dist/output/
 mkdir -p "$OUTPUT"
+find "$ROOT/dist/client" -maxdepth 1 -name '*.html' -exec cp {} "$OUTPUT/" \;
 
-# 1. 所有 .html 文件按目录结构复制到 dist/output/，并替换 $STATIC$ 为实际静态资源路径
-cd "$ROOT"
-find . -name '*.html' -not -path './dist/*' -not -path './node_modules/*' | while read -r file; do
-  dir=$(dirname "$file")
-  mkdir -p "$OUTPUT/$dir"
-  sed "s|\\\$STATIC\\\$|${STATIC_PREFIX}|g" "$file" > "$OUTPUT/$file"
-done
+# 生成 routes.json（运行态 PageServer 按 type 区分渲染策略）
+echo '{ "version": 1, "type": "html", "fallback": "index.html" }' > "$OUTPUT/routes.json"
 
-# 2. routes.json → dist/output/
-cp "$ROOT/routes.json" "$OUTPUT/routes.json"
+# 3. assets/ → dist/output_resource/（JS/CSS/字体上传到 CDN）
+if [ -d "$ROOT/dist/client/assets" ]; then
+  mkdir -p "$OUTPUT_RESOURCE"
+  cp -r "$ROOT/dist/client/assets" "$OUTPUT_RESOURCE/"
+fi
 
-# 3. static/ → dist/output_static/（如果存在）
-if [ -d "$ROOT/static" ]; then
-  cp -r "$ROOT/static" "$OUTPUT_STATIC"
+# 4. 私有静态资源 → dist/output_static/（排除代码文件）
+if [ -d "$ROOT/shared/static" ]; then
+  mkdir -p "$OUTPUT_STATIC"
+  rsync -a --exclude='*.ts' --exclude='*.tsx' --exclude='*.js' --exclude='*.jsx' "$ROOT/shared/static/" "$OUTPUT_STATIC/"
 fi
 
+rm -rf "$ROOT/dist/client"
+
 echo "Build complete"
-echo "  HTML   → dist/output/"
-[ -d "$OUTPUT_STATIC" ] && echo "  Static → dist/output_static/" || true
+echo "  HTML     → dist/output/"
+[ -d "$OUTPUT_RESOURCE" ] && echo "  Resource → dist/output_resource/" || true
+[ -d "$OUTPUT_STATIC" ] && echo "  Static   → dist/output_static/" || true

package/{template-vite-react → template-html}/scripts/mock-health.cjs

@@ -6,7 +6,7 @@
  * 8001 由 Vite dev server 真正占（预览流量也走 8001），3000 没有任何业务进程，
  * 只能 mock 一个 listener 让健康检查过。
  *
- * 等沙箱链路切到新协议（读 .spark-project [sandbox].healthCheck）后可删除。
+ * 等沙箱链路切到新协议（读 .spark_project [sandbox].healthCheck）后可删除。
  */
 const http = require('node:http');
 

package/template-html/src/main.js

@@ -0,0 +1,38 @@
+// 极薄入口：装平台 SDK。
+// 业务代码写在 index.html 的 <script> 里，或者再 import './your-app.js'。
+
+import './styles.css';
+
+// 1) capability — 调插件能力
+import { capabilityClient } from '@lark-apaas/client-toolkit-lite';
+// 暴露到 window 让 index.html 内联 <script> 也能用
+window.capability = capabilityClient;
+
+// 2) observable — OpenTelemetry traces/logs/metrics
+// lite 里的 initObservable() 绑了 React useEffect，纯 HTML 用不了；inline 一份等效逻辑。
+import { observable, AppEnv } from '@lark-apaas/observable-web';
+try {
+  const appId = window.appId;
+  const isNewPath =
+    typeof window.location !== 'undefined' &&
+    /^\/app\/[^/]/.test(window.location.pathname);
+  observable.start({
+    serviceName: 'app',
+    env: process.env.NODE_ENV === 'development' ? AppEnv.Dev : AppEnv.Prod,
+    collectorUrl: isNewPath
+      ? {
+          log: `/app/${appId}/__runtime__/api/v1/observability/logs/collect`,
+          trace: `/app/${appId}/__runtime__/api/v1/observability/traces/collect`,
+          metric: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
+          time: `/app/${appId}/__runtime__/api/v1/observability/current_server_timestamp`,
+        }
+      : {
+          log: `/spark/app/${appId}/runtime/api/v1/observability/logs/collect`,
+          trace: `/spark/app/${appId}/runtime/api/v1/observability/traces/collect`,
+          metric: `/spark/app/${appId}/runtime/api/v1/observability/metrics/collect`,
+          time: `/spark/api/v1/observability/app/${appId}/current_server_timestamp`,
+        },
+  });
+} catch (error) {
+  console.error('Failed to start WebObservableSdk:', error);
+}

package/template-html/src/styles.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/template-html/vite.config.ts

@@ -0,0 +1,70 @@
+import path from 'path'
+import type { IncomingMessage, ServerResponse } from 'http'
+import { defineConfig } from '@lark-apaas/coding-vite-preset'
+import type { Plugin, ViteDevServer } from 'vite'
+
+/**
+ * dev 模式 base-path normalize 中间件（同 template-vite-react）
+ *
+ * 沙箱预览网关把流量原样转给 vite（保留 /app/:appId 前缀）。但浏览器首次访问的
+ * URL 是 `/app/app_xxx?sso_token=...`（pathname 缺末尾 /）。
+ *
+ * vite 8 的 baseMiddleware 对"缺末尾 /"的请求不再像 vite 5 那样自动 301，
+ * 而是直接返回 404 警告页 "The server is configured with a public base URL..."。
+ *
+ * 这里做 internal rewrite（不发 301，避免跟沙箱网关形成 round-trip 死循环）：
+ * pathname === base 去尾 / → 改写 req.url 加上尾 /，下游继续 strip → SPA fallback。
+ *
+ * 必须 stack.unshift 而非 server.middlewares.use，否则排到内置 baseMiddleware
+ * 之后失效。
+ *
+ * TODO: coding-vite-preset 新版本已含同等逻辑，待依赖普及后可删此 plugin。
+ */
+const baseNormalizePlugin: Plugin = {
+  name: 'base-path-normalize',
+  configureServer(server: ViteDevServer) {
+    const base = (process.env.CLIENT_BASE_PATH || '').replace(/\/+$/, '')
+    if (!base) return
+    const stack = (
+      server.middlewares as unknown as {
+        stack: Array<{ route: string; handle: unknown }>
+      }
+    ).stack
+    if (!Array.isArray(stack)) return
+    stack.unshift({
+      route: '',
+      handle: (req: IncomingMessage, _res: ServerResponse, next: () => void) => {
+        const url = req.url || ''
+        const qIdx = url.indexOf('?')
+        const pathname = qIdx >= 0 ? url.slice(0, qIdx) : url
+        const search = qIdx >= 0 ? url.slice(qIdx) : ''
+        if (pathname === base) {
+          req.url = base + '/' + search
+        }
+        next()
+      },
+    })
+  },
+}
+
+export default defineConfig({
+  // 模板根目录就是 index.html 所在位置（跟 vite-react 不同，没有 client/ 子目录）
+  root: path.resolve(__dirname),
+  resolve: {
+    alias: {
+      '@shared': path.resolve(__dirname, 'shared'),
+    },
+  },
+  build: {
+    // coding-vite-preset 默认把 entry 设为 client/index.html（vite-react 用的布局），
+    // HTML 模板没有 client/ 子目录，override 成根目录的 index.html。
+    rollupOptions: {
+      input: path.resolve(__dirname, 'index.html'),
+    },
+  },
+  // 同步告诉 Vite dev 优化器 entry 在哪，避免"failed to resolve rolldownOptions.input"警告。
+  optimizeDeps: {
+    entries: [path.resolve(__dirname, 'index.html')],
+  },
+  plugins: [baseNormalizePlugin],
+})

package/template-vite-react/.spark_project

@@ -0,0 +1,12 @@
+run = ["npm", "run", "dev"]
+lint = ["npm", "run", "lint"]
+hidden = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]
+
+[deployment]
+build = ["npm", "run", "build"]
+
+[files]
+[files.restrict]
+pathPatterns = ["package.json", ".spark_project", ".spark/meta.json", ".gitignore"]
+[files.hidden]
+pathPatterns = [".config", ".git", "scripts", "node_modules", "dist", ".spark", ".agent", ".agents", "tmp", ".spark_project", ".playwright-cli"]

package/template-vite-react/README.md

@@ -15,7 +15,7 @@
 ## 目录结构
 
 ```
-client/src/
+src/
 ├── index.tsx            # 入口（勿修改）
 ├── app.tsx              # 路由配置（仅在 <Routes> 内增删 <Route>）
 ├── index.css            # 全局样式 + 主题变量
@@ -51,8 +51,8 @@ shared/
 
 | 文件 | 原因 |
 |------|------|
-| `client/src/index.tsx` | Provider 层级 + 样式引入，由模板管理 |
-| `client/src/components/ui/*` | shadcn/ui 内置组件，版本锁定 |
+| `src/index.tsx` | Provider 层级 + 样式引入，由模板管理 |
+| `src/components/ui/*` | shadcn/ui 内置组件，版本锁定 |
 
 ---
 
@@ -60,10 +60,10 @@ shared/
 
 | 内容类型 | 放置位置 |
 |---------|---------|
-| 新页面 | `client/src/pages/<PageName>/PageName.tsx` |
-| 页面专属组件 | `client/src/pages/<PageName>/components/` |
-| 自定义 Hooks | `client/src/hooks/` |
-| 工具函数 | `client/src/lib/` |
+| 新页面 | `src/pages/<PageName>/PageName.tsx` |
+| 页面专属组件 | `src/pages/<PageName>/components/` |
+| 自定义 Hooks | `src/hooks/` |
+| 工具函数 | `src/lib/` |
 | 静态数据文件 | `shared/static/data/` |
 | 静态图片 | `shared/static/images/` |
 
@@ -72,7 +72,7 @@ shared/
 ## 导入路径
 
 ```typescript
-// @/ 别名 → client/src/
+// @/ 别名 → src/
 import { cn } from "@/lib/utils";
 import { useIsMobile } from "@/hooks/use-mobile";
 
@@ -85,14 +85,14 @@ import configData from "@shared/static/config.json";
 
 ## 路由配置
 
-- 新增页面需在 `client/src/app.tsx` 的 `<Routes>` 内注册 `<Route>`
+- 新增页面需在 `src/app.tsx` 的 `<Routes>` 内注册 `<Route>`
 - `BrowserRouter` 已在 `index.tsx` 中配置，`app.tsx` 中**禁止**再包裹 Router
 
 ---
 
 ## 主题变量
 
-主题色定义在 `client/src/index.css`，通过 `:root` CSS 变量 + `@theme inline` 注册到 Tailwind。
+主题色定义在 `src/index.css`，通过 `:root` CSS 变量 + `@theme inline` 注册到 Tailwind。
 
 | 用途 | Tailwind 类 | CSS 变量 |
 |------|------------|----------|

package/template-vite-react/components.json

@@ -5,7 +5,7 @@
   "tsx": true,
   "tailwind": {
     "config": "",
-    "css": "client/src/index.css",
+    "css": "src/index.css",
     "baseColor": "neutral",
     "cssVariables": true,
     "prefix": ""

package/template-vite-react/package.json

@@ -1,20 +1,13 @@
 {
-  "name": "{{projectName}}",
+  "name": "miaoda-vite-react-app",
   "version": "0.1.0",
   "private": true,
-  "mclaw": {
-    "stack": "vite-react",
-    "stackVersion": "0.1.0",
-    "features": [
-      "client"
-    ]
-  },
   "scripts": {
-    "dev": "concurrently -k -n vite,health 'vite --port 8001 --host 0.0.0.0' 'node scripts/mock-health.cjs'",
+    "dev": "node scripts/dev.mjs",
     "build": "bash scripts/build.sh",
     "typecheck": "tsc -p tsconfig.app.json",
     "lint": "concurrently npm:typecheck npm:lint:eslint",
-    "lint:eslint": "eslint client/src"
+    "lint:eslint": "eslint src"
   },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -44,7 +37,7 @@
     "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-toggle-group": "^1.1.10",
     "@radix-ui/react-tooltip": "^1.1.18",
-    "@lark-apaas/client-toolkit-lite": "^1.1.0",
+    "@lark-apaas/client-toolkit-lite": "1.1.7-alpha.23",
     "@formkit/auto-animate": "^0.9.0",
     "@gsap/react": "^2.1.2",
     "framer-motion": "^12.38.0",
@@ -62,6 +55,7 @@
     "react": "^19.2.4",
     "react-day-picker": "^9.14.0",
     "react-dom": "^19.2.4",
+    "react-error-boundary": "^6.0.0",
     "react-hook-form": "^7.72.0",
     "react-resizable-panels": "^4.7.6",
     "react-router-dom": "^7.13.2",
@@ -79,7 +73,7 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@lark-apaas/coding-presets": "^1.0.0",
-    "@lark-apaas/coding-vite-preset": "^1.0.0",
+    "@lark-apaas/coding-vite-preset": "1.0.7-alpha.21",
     "concurrently": "^9",
     "eslint": "^9",
     "eslint-plugin-react-hooks": "^7",

package/template-vite-react/scripts/build.sh

@@ -36,10 +36,22 @@ if [ -d "$ROOT/shared/static" ]; then
   rsync -a --exclude='*.ts' --exclude='*.tsx' --exclude='*.js' --exclude='*.jsx' "$ROOT/shared/static/" "$OUTPUT_STATIC/"
 fi
 
+# 5. capability 配置 → dist/output_capabilities/（老路径优先）
+if [ -d "$ROOT/server/capabilities" ]; then
+  CAPS_SRC="$ROOT/server/capabilities"
+elif [ -d "$ROOT/shared/capabilities" ]; then
+  CAPS_SRC="$ROOT/shared/capabilities"
+fi
+if [ -n "${CAPS_SRC:-}" ]; then
+  mkdir -p "$ROOT/dist/output_capabilities"
+  cp -r "$CAPS_SRC/." "$ROOT/dist/output_capabilities/"
+fi
+
 # 清理中间产物
 rm -rf "$ROOT/dist/client"
 
 echo "Build complete"
-echo "  HTML     → dist/output/"
-[ -d "$OUTPUT_RESOURCE" ] && echo "  Resource → dist/output_resource/" || true
-[ -d "$OUTPUT_STATIC" ] && echo "  Static   → dist/output_static/" || true
+echo "  HTML         → dist/output/"
+[ -d "$OUTPUT_RESOURCE" ] && echo "  Resource     → dist/output_resource/" || true
+[ -d "$OUTPUT_STATIC" ] && echo "  Static       → dist/output_static/" || true
+[ -d "$ROOT/dist/output_capabilities" ] && echo "  Capabilities → dist/output_capabilities/" || true

package/template-vite-react/scripts/dev.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Dev launcher: 启动 vite dev server，把 stdout/stderr 加时间戳前缀
+ * 写到 logs/<name>.std.log + 当前 stdout；负责子进程组管理与端口孤儿清理。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { spawn, execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+process.chdir(ROOT);
+
+const LOG_DIR = process.env.LOG_DIR || 'logs';
+const CLIENT_DEV_PORT = process.env.CLIENT_DEV_PORT || '8001';
+
+fs.mkdirSync(LOG_DIR, { recursive: true });
+
+function timestamp() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+    `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`
+  );
+}
+
+function log(msg) {
+  const line = `[${timestamp()}] [dev] ${msg}\n`;
+  try { process.stdout.write(line); } catch {}
+}
+
+/** 清理端口占用：lsof -ti:<port> | kill -9 */
+function killOrphansByPort(port) {
+  try {
+    const out = execSync(`lsof -ti:${port}`, { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+    if (!out) return [];
+    const pids = out.split('\n').filter(Boolean);
+    for (const pid of pids) {
+      try {
+        process.kill(Number(pid), 'SIGKILL');
+        log(`killed orphan pid=${pid} on :${port}`);
+      } catch {}
+    }
+    return pids;
+  } catch {
+    return [];
+  }
+}
+
+const managed = [];
+
+function startProcess({ name, command, args, logFileName }) {
+  const logFd = logFileName
+    ? fs.openSync(path.join(LOG_DIR, logFileName), 'a')
+    : null;
+
+  const child = spawn(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: false,
+    cwd: ROOT,
+    env: process.env,
+    detached: true,
+  });
+
+  const pipeLines = (stream) => {
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    rl.on('line', (line) => {
+      const msg = `[${timestamp()}] [${name}] ${line}\n`;
+      try { process.stdout.write(msg); } catch {}
+      if (logFd != null) {
+        try { fs.writeSync(logFd, msg); } catch {}
+      }
+    });
+  };
+  pipeLines(child.stdout);
+  pipeLines(child.stderr);
+
+  managed.push({ name, child });
+  return child;
+}
+
+killOrphansByPort(CLIENT_DEV_PORT);
+
+startProcess({
+  name: 'client',
+  command: 'npx',
+  args: ['vite', '--port', CLIENT_DEV_PORT, '--host', '0.0.0.0'],
+  logFileName: 'client.std.log',
+});
+
+let stopping = false;
+function cleanup(signal) {
+  if (stopping) return;
+  stopping = true;
+  log(`cleanup triggered by ${signal}`);
+
+  for (const { child } of managed) {
+    if (!child.pid) continue;
+    try { process.kill(-child.pid, signal || 'SIGTERM'); } catch {}
+  }
+  setTimeout(() => {
+    for (const { child } of managed) {
+      if (!child.pid) continue;
+      try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+    }
+    killOrphansByPort(CLIENT_DEV_PORT);
+    process.exit(0);
+  }, 2000);
+}
+
+process.on('SIGINT', () => cleanup('SIGTERM'));
+process.on('SIGTERM', () => cleanup('SIGTERM'));
+// pkill 杀父 npm 后会收 SIGHUP（controlling tty 关闭）；
+// Node 默认直接退出不跑 handler，注册 handler 触发 cleanup
+process.on('SIGHUP', () => cleanup('SIGTERM'));
+
+Promise.race(
+  managed.map(({ child }) => new Promise((r) => child.on('exit', r))),
+).then(() => cleanup('SIGTERM'));

package/template-vite-react/{client/src → src}/index.tsx

@@ -1,7 +1,8 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { BrowserRouter } from "react-router-dom";
-import { AppContainer } from "@lark-apaas/client-toolkit-lite";
+import { ErrorBoundary } from "react-error-boundary";
+import { AppContainer, ErrorRender } from "@lark-apaas/client-toolkit-lite";
 import App from "./app";
 import "./index.css";
 
@@ -9,7 +10,13 @@ createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <BrowserRouter basename={process.env.CLIENT_BASE_PATH || "/"}>
       <AppContainer>
-        <App />
+        <ErrorBoundary
+          fallbackRender={({ error, resetErrorBoundary }) => (
+            <ErrorRender error={error} resetErrorBoundary={resetErrorBoundary} />
+          )}
+        >
+          <App />
+        </ErrorBoundary>
       </AppContainer>
     </BrowserRouter>
   </StrictMode>,

package/template-vite-react/tsconfig.app.json

@@ -4,10 +4,10 @@
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./client/src/*"],
+      "@/*": ["./src/*"],
       "@shared/*": ["./shared/*"]
     }
   },
-  "include": ["client/src", "shared"],
-  "exclude": ["client/src/components/ui"]
+  "include": ["src", "shared"],
+  "exclude": ["src/components/ui"]
 }

package/template-vite-react/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./client/src/*"],
+      "@/*": ["./src/*"],
       "@shared/*": ["./shared/*"]
     }
   },

package/template-vite-react/vite.config.ts

@@ -1,64 +1,11 @@
 import path from 'path'
-import type { IncomingMessage, ServerResponse } from 'http'
 import { defineConfig } from '@lark-apaas/coding-vite-preset'
-import type { Plugin, ViteDevServer } from 'vite'
-
-/**
- * dev 模式 base-path normalize 中间件
- *
- * 沙箱预览网关把流量原样转给 vite（保留 /app/:appId 前缀）。浏览器首次访问的
- * URL 形如 `/app/app_xxx?sso_token=...`，pathname 缺末尾 /。
- *
- * vite 8 的 baseMiddleware 对"缺末尾 /"的请求不再像 vite 5 那样自动 301，
- * 而是直接返回 404 警告页 "The server is configured with a public base URL..."。
- *
- * 这里做 internal rewrite（不发 301，避免跟沙箱网关形成 round-trip 死循环）：
- * 在 vite 内置 baseMiddleware **之前** unshift 一个中间件，把 req.url 改写
- * 成带尾 /，下游 baseMiddleware 继续 strip base → SPA fallback。
- * 浏览器全程不感知 redirect，地址栏可保留缺尾 / 形态（BrowserRouter basename
- * 处理路由）。
- *
- * 必须 stack.unshift 而非 server.middlewares.use(...)，否则会排到内置
- * baseMiddleware 之后失效。
- *
- * TODO: 这段已同步到 @lark-apaas/coding-vite-preset，待该包发布并被本模板
- * 依赖升级拉到后，可以删除此 plugin。保留是为了让现存沙箱（用着老 preset
- * 的应用）也能立即生效。
- */
-const baseNormalizePlugin: Plugin = {
-  name: 'base-path-normalize',
-  configureServer(server: ViteDevServer) {
-    const base = (process.env.CLIENT_BASE_PATH || '').replace(/\/+$/, '')
-    if (!base) return
-    const stack = (
-      server.middlewares as unknown as {
-        stack: Array<{ route: string; handle: unknown }>
-      }
-    ).stack
-    if (!Array.isArray(stack)) return
-    stack.unshift({
-      route: '',
-      handle: (req: IncomingMessage, _res: ServerResponse, next: () => void) => {
-        const url = req.url || ''
-        const qIdx = url.indexOf('?')
-        const pathname = qIdx >= 0 ? url.slice(0, qIdx) : url
-        const search = qIdx >= 0 ? url.slice(qIdx) : ''
-        if (pathname === base) {
-          req.url = base + '/' + search
-        }
-        next()
-      },
-    })
-  },
-}
 
 export default defineConfig({
-  root: path.resolve(__dirname, 'client'),
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, 'client/src'),
+      '@': path.resolve(__dirname, 'src'),
       '@shared': path.resolve(__dirname, 'shared'),
     },
   },
-  plugins: [baseNormalizePlugin],
 })

package/template-html/_gitignore

@@ -1,2 +0,0 @@
-.DS_Store
-node_modules

package/template-html/routes.json

@@ -1 +0,0 @@
-{ "version": 1, "type": "html", "fallback": "index.html" }