@lark-apaas/coding-template-nestjs-react-fullstack 0.1.40-alpha.20260915110512 → 0.1.40-alpha.20260915170225

package/README.md

@@ -27,6 +27,25 @@ MIAODA_APP_TYPE=3 npx @lark-apaas/miaoda-cli@<latest> app init \
 - `SANDBOX_PUBLIC_URL` —— 沙箱公网域
 - `CLIENT_BASE_PATH=/app/<app_id>/` —— React Router basename + Vite base
 
+## MCP UI 的类型与代码检查
+
+`server/mcp/ui` 是独立浏览器工程，主应用的 TypeScript 和 ESLint 配置排除该目录。
+`npm run lint` 通过现有 `scripts/lint.js` 统一调度检查：
+
+| 命令 | 检查范围 |
+| --- | --- |
+| `npm run type:check` | 服务端、客户端、MCP UI 类型检查 |
+| `npm run type:check:mcp-ui` | 仅 MCP UI 类型检查 |
+| `npm run eslint:mcp-ui` | 仅 MCP UI ESLint 检查 |
+| `npm run lint -- --files <files...>` | 根据改动文件选择检查范围 |
+
+模板不预建 UI 目录。Agent 开发 MCP UI 时，按照 MCP 指南生成
+`server/mcp/ui/tsconfig.json` 和根目录 `eslint.mcp-ui.config.cjs`。
+没有 UI 源码时跳过独立检查；存在源码但配置缺失或未覆盖源码时明确报错。
+
+存量应用通过本地 `miaoda app sync` 或沙箱 `fullstack-cli sync` 更新脚本、迁移已知模板命令，
+并保留现有 TS 排除项。自定义检查命令会保留，开发者需自行接入独立 UI 检查。
+
 ## 包结构
 
 ```
@@ -39,3 +58,30 @@ MIAODA_APP_TYPE=3 npx @lark-apaas/miaoda-cli@<latest> app init \
 `template/` 内以下划线开头的占位文件（`_gitignore` / `_npmrc` / `_env.local`）在 `miaoda app init`
 渲染时会按 RENAME 映射改回正常名（npm pack 会特殊处理 `.gitignore`、且 `.npmrc` 直接放
 在包里会污染用户 `npm install` 行为，所以都要 underscore 前缀）。
+
+## MCP 后端构建标识
+
+`npm run build` 的 `scripts/build.sh` 在服务端、客户端构建、产物准备和依赖裁剪全部成功后，
+用 Node 内置 `crypto.randomUUID()` 生成一次纯文本 UUID（36 字符，无需发布环境变量）。
+同次构建写入下列文件，内容完全相同：
+
+| 构建文件（相对工程根） | 对应运行目录 |
+| --- | --- |
+| `dist/mcp-build-id` | 工程根 |
+| `dist/dist/mcp-build-id` | `dist/`，或整个 `dist/` 复制/解压到的 `dist-server/` |
+| `dist/server/dist/mcp-build-id` | 旧布局 `dist/server/`，或该目录复制/解压到的 `dist-server/` |
+
+SDK 统一读取 `cwd/dist/mcp-build-id`；production 首次读取后缓存。
+复制/部署同一产物必须保留文件，不在启动时重新生成 UUID；再次成功全构建会得到新的 UUID。
+直接运行 `build:server` 不完成交付流程，不能替代 `npm run build`。
+SDK 在文件缺失时不返回 `appRevision`，标准 MCP 仍可用；开发态使用进程单例 UUID，不读构建文件。
+UI/Skill 内容仍由 SDK 计入总 hash，独立修改这些产物不会重写 `backendBuildID`。
+
+`only_frontend_change=true` 跳过服务端构建、依赖裁剪和 UUID 生成。
+构建目录仍按原逻辑清空；平台跳过服务端包上传，所以已部署服务的旧 ID 保持不变。
+`server/mcp/ui`、`server/mcp/skills` 的源码变更应由平台判为全构建；它们不属于 `client/`。
+平台实际根据配置的前端路径前缀匹配变更前后路径，不能把 `server/mcp` 列为前端前缀。
+即使 client build 在本地写出了 `mcp-ui`，纯前端发布也不携带服务端 MCP 产物，**不承诺热更 MCP UI**。
+
+存量应用通过既有 `fullstack-cli sync` 或 `miaoda app sync` 的 `scripts/` 目录覆盖同步获得此脚本，
+同步本身不生成 UUID、不修改已有构建标识，无新增用户 CLI 命令。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-template-nestjs-react-fullstack",
-  "version": "0.1.40-alpha.20260915110512",
+  "version": "0.1.40-alpha.20260915170225",
   "description": "NestJS + React fullstack template for miaoda coding",
   "type": "module",
   "files": [

package/template/eslint.config.js

@@ -9,7 +9,7 @@ module.exports = tseslint.config(
       'node_modules',
       'source_package',
       'client/src/api/gen',
-      // MCP UI 是独立浏览器工程，暂不参与主应用的 ESLint 检查。
+      // MCP UI 使用独立浏览器配置，由 lint.js 使用 eslint.mcp-ui.config.cjs 独立检查。
       'server/mcp/ui/**',
       '**/*.d.ts',
       '**/*.js.map',

package/template/package-lock.json

@@ -8,7 +8,7 @@
       "name": "fullstack-nestjs-template",
       "version": "2.3.0",
       "dependencies": {
-        "@lark-apaas/fullstack-nestjs-core": "1.1.62-alpha.20260915105802",
+        "@lark-apaas/fullstack-nestjs-core": "1.1.62-alpha.20260915164949",
         "@nestjs/axios": "^4.0.1",
         "@nestjs/cache-manager": "^3.1.3",
         "@nestjs/common": "^10.4.20",
@@ -33,7 +33,7 @@
       "devDependencies": {
         "@hookform/resolvers": "^5.2.2",
         "@lark-apaas/client-toolkit": "^1.2.70",
-        "@lark-apaas/coding-preset-vite-react": "1.0.23-alpha.20260915105803",
+        "@lark-apaas/coding-preset-vite-react": "1.0.23-alpha.20260915164951",
         "@lark-apaas/fullstack-presets": "^1.1.0",
         "@nestjs/cli": "^10.4.9",
         "@radix-ui/react-accordion": "^1.2.12",
@@ -1634,9 +1634,9 @@
       "license": "MIT"
     },
     "node_modules/@lark-apaas/coding-preset-vite-react": {
-      "version": "1.0.23-alpha.20260915105803",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/coding-preset-vite-react/-/coding-preset-vite-react-1.0.23-alpha.20260915105803.tgz",
-      "integrity": "sha512-GwUV/4DHWibTx0GrhflevI2kWC+4UqjtHucAwHWJpvD7rd8Q+AdQEIAvYVj5nKZ6QuCc8yQEAMKSwvREDTwcEg==",
+      "version": "1.0.23-alpha.20260915164951",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/coding-preset-vite-react/-/coding-preset-vite-react-1.0.23-alpha.20260915164951.tgz",
+      "integrity": "sha512-5QRc/9rXGp9GYP7ISD9nN99Jt8/NHzro3BnSj3QezaAzBBzH5OMFQOySK3BKFVqvWvnXTNpTiAzt9EioGiVNWQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1697,9 +1697,9 @@
       }
     },
     "node_modules/@lark-apaas/fullstack-nestjs-core": {
-      "version": "1.1.62-alpha.20260915105802",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-nestjs-core/-/fullstack-nestjs-core-1.1.62-alpha.20260915105802.tgz",
-      "integrity": "sha512-7eJM0cJ0jqjhKCslzyl5SX6l7RE0CRCWXWW4I6u5SZN0NDogNcYU11uWjXbscZnqIsLwNiQj+tOnk5iKeSkSYA==",
+      "version": "1.1.62-alpha.20260915164949",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-nestjs-core/-/fullstack-nestjs-core-1.1.62-alpha.20260915164949.tgz",
+      "integrity": "sha512-l5OUcUnbRFWcP8FArwFXkn0kwPDiM4Mu7jSEROGJuHMoOA7DRBZlEfTL9HB6sXXsX92Jo5YJophb2sFCC14KGw==",
       "license": "MIT",
       "dependencies": {
         "@lark-apaas/cache-service": "^0.1.1",
@@ -1712,7 +1712,7 @@
         "@lark-apaas/nestjs-datapaas": "^1.0.21",
         "@lark-apaas/nestjs-http-forwarder": "^0.1.3",
         "@lark-apaas/nestjs-logger": "^1.0.17",
-        "@lark-apaas/nestjs-mcp": "0.1.1-alpha.20260915105801",
+        "@lark-apaas/nestjs-mcp": "0.1.1-alpha.20260915164952",
         "@lark-apaas/nestjs-observable": "^0.0.12",
         "@lark-apaas/nestjs-openapi-devtools": "^1.0.10",
         "@lark-apaas/nestjs-trigger": "^0.0.3",
@@ -1945,9 +1945,9 @@
       }
     },
     "node_modules/@lark-apaas/nestjs-mcp": {
-      "version": "0.1.1-alpha.20260915105801",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-mcp/-/nestjs-mcp-0.1.1-alpha.20260915105801.tgz",
-      "integrity": "sha512-VjW7VlIb24fFktFtzVxySetClX0yD0l5Eixx80LtnsdyKaOKWRW3GCZaVLb0Kn6k5cAao8kF/bImPp55u47Olg==",
+      "version": "0.1.1-alpha.20260915164952",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-mcp/-/nestjs-mcp-0.1.1-alpha.20260915164952.tgz",
+      "integrity": "sha512-TxZ0BAISQKmjLLLjQ2vFsM41J98qSqgg82/MjB950uxm1UgalYbhLe2ok/CdE1SXziO+gvQb3yfZG6avI8muJA==",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/ext-apps": "^1.7.5",

package/template/package.json

@@ -18,7 +18,7 @@
     "build:server": "NODE_ENV=production nest build",
     "build:client": "NODE_ENV=production vite build --config vite.config.ts",
     "start": "NODE_ENV=production node main.js",
-    "eslint": "eslint . --quiet",
+    "eslint": "eslint . --quiet --ignore-pattern \"server/mcp/ui/**\"",
     "stylelint": "stylelint client/src/**/*.css --quiet",
     "type:check": "node ./scripts/lint.js --typecheck",
     "type:check:client": "tsc --noEmit --project tsconfig.app.json",
@@ -30,7 +30,7 @@
     "eslint:mcp-ui": "node ./scripts/lint.js --eslint-mcp-ui"
   },
   "dependencies": {
-    "@lark-apaas/fullstack-nestjs-core": "1.1.62-alpha.20260915105802",
+    "@lark-apaas/fullstack-nestjs-core": "1.1.62-alpha.20260915164949",
     "@nestjs/axios": "^4.0.1",
     "@nestjs/cache-manager": "^3.1.3",
     "@nestjs/common": "^10.4.20",
@@ -55,7 +55,7 @@
   "devDependencies": {
     "@hookform/resolvers": "^5.2.2",
     "@lark-apaas/client-toolkit": "^1.2.70",
-    "@lark-apaas/coding-preset-vite-react": "1.0.23-alpha.20260915105803",
+    "@lark-apaas/coding-preset-vite-react": "1.0.23-alpha.20260915164951",
     "@lark-apaas/fullstack-presets": "^1.1.0",
     "@nestjs/cli": "^10.4.9",
     "@radix-ui/react-accordion": "^1.2.12",

package/template/scripts/build.sh

@@ -43,37 +43,43 @@ echo ""
 echo "🔨 [3/5] 并行构建 server 和 client"
 STEP_START=$(node -e "console.log(Date.now())")
 
-# 并行构建
-echo "   ├─ 启动 server 构建..."
-npm run build:server > /tmp/build-server.log 2>&1 &
-SERVER_PID=$!
-
-echo "   ├─ 启动 client 构建..."
-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
+# server/mcp（含 UI/Skill）变更必须由平台判定为全构建。
+if [[ "${only_frontend_change:-false}" == "true" ]]; then
+  echo "   ├─ 仅构建 client (only_frontend_change=true)"
+  npm run build:client > /tmp/build-client.log 2>&1
+else
+  # 并行构建
+  echo "   ├─ 启动 server 构建..."
+  npm run build:server > /tmp/build-server.log 2>&1 &
+  SERVER_PID=$!
+
+  echo "   ├─ 启动 client 构建..."
+  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
-
-if [ $CLIENT_EXIT -ne 0 ]; then
-  echo "   ❌ Client 构建失败"
-  cat /tmp/build-client.log
-  exit 1
-fi
-
-echo "   ✅ Server 构建完成"
-echo "   ✅ Client 构建完成"
 print_time $STEP_START
 echo ""
 
@@ -81,18 +87,21 @@ echo ""
 echo "📦 [4/5] 准备 server 依赖产物"
 STEP_START=$(node -e "console.log(Date.now())")
 
-mkdir -p "$OUT_DIR/dist/client"
+if [[ "${only_frontend_change:-false}" != "true" ]]; then
+  mkdir -p "$OUT_DIR/dist/client"
 
-# public 先进（server setBaseViewsDir + nestjs-core 中间件同源 serve）
-if [ -d "$ROOT_DIR/client/public" ]; then
-  cp -R "$ROOT_DIR/client/public/." "$OUT_DIR/dist/client/"
-fi
+  # public 先进（server setBaseViewsDir + nestjs-core 中间件同源 serve）
+  if [ -d "$ROOT_DIR/client/public" ]; then
+    cp -R "$ROOT_DIR/client/public/." "$OUT_DIR/dist/client/"
+  fi
+
+  # 构建产物 HTML 随后拷，覆盖 public 里的同名文件（保证入口页是构建版，不被 public 静默覆盖）
+  cp "$ROOT_DIR/dist/client/"*.html "$OUT_DIR/dist/client/" || true
 
-# 构建产物 HTML 随后拷，覆盖 public 里的同名文件（保证入口页是构建版，不被 public 静默覆盖）
-cp "$ROOT_DIR/dist/client/"*.html "$OUT_DIR/dist/client/" || true
+  # 拷贝 run.sh 文件
+  cp "$ROOT_DIR/scripts/run.sh" "$OUT_DIR/"
 
-# 拷贝 run.sh 文件
-cp "$ROOT_DIR/scripts/run.sh" "$OUT_DIR/"
+fi
 
 # 清理无用文件
 rm -rf "$ROOT_DIR/dist/scripts"
@@ -106,7 +115,9 @@ echo "✂️  [5/5] 智能依赖裁剪"
 STEP_START=$(node -e "console.log(Date.now())")
 
 # 分析实际依赖、复制并裁剪 node_modules、生成精简的 package.json
-node "$ROOT_DIR/scripts/prune-smart.js"
+if [[ "${only_frontend_change:-false}" != "true" ]]; then
+  node "$ROOT_DIR/scripts/prune-smart.js"
+fi
 
 print_time $STEP_START
 echo ""
@@ -116,10 +127,37 @@ echo "构建完成"
 print_time $TOTAL_START
 
 # 输出产物信息
-DIST_SIZE=$(du -sh "$OUT_DIR" | cut -f1)
-NODE_MODULES_SIZE=$(du -sh "$OUT_DIR/node_modules" | cut -f1)
+DIST_SIZE=$(du -sh "$ROOT_DIR/dist" | cut -f1)
 echo ""
 echo "📊 构建产物统计:"
 echo "   总大小:        $DIST_SIZE"
-echo "   node_modules: $NODE_MODULES_SIZE"
+if [[ "${only_frontend_change:-false}" != "true" ]]; then
+  NODE_MODULES_SIZE=$(du -sh "$OUT_DIR/node_modules" | cut -f1)
+  echo "   node_modules: $NODE_MODULES_SIZE"
+fi
 echo ""
+
+# 仅成功的全构建生成 backendBuildID；必须在构建、产物准备和依赖裁剪之后。
+# UI/Skill 内容由 SDK 独立计入总 hash；纯前端发布不替换已部署的 backendBuildID。
+if [[ "${only_frontend_change:-false}" != "true" ]]; then
+  node - "$ROOT_DIR/dist" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const dist = process.argv[2];
+// 防止 build:server 空跑成功、却没有可交付的服务端入口。
+if (!fs.statSync(path.join(dist, 'server/main.js')).isFile()) {
+  throw new Error('Missing server build output: dist/server/main.js');
+}
+// runtime cwd 分别为工程根、dist/（或整包解压到 dist-server/）、旧版 dist/server/。
+// 与 MCP UI/Skill 的交付布局一致：复制产物时保留同一个 UUID，不在启动时生成。
+const files = [
+  path.join(dist, 'mcp-build-id'),
+  path.join(dist, 'dist/mcp-build-id'),
+  path.join(dist, 'server/dist/mcp-build-id'),
+];
+for (const file of files) fs.mkdirSync(path.dirname(file), { recursive: true });
+const buildID = randomUUID();
+for (const file of files) fs.writeFileSync(file, buildID, 'utf8');
+NODE
+fi