@lark-apaas/coding-template-nestjs-react-fullstack 0.1.40-alpha.20260915093425 → 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.20260915093425",
+  "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.20260914151757",
+        "@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.20260914151758",
+        "@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.20260914151758",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/coding-preset-vite-react/-/coding-preset-vite-react-1.0.23-alpha.20260914151758.tgz",
-      "integrity": "sha512-zxG4MdxaJ31mf4BFuBbGa/6uBK2XcNNCNN+whVfMRe1S5Zj4ibs9WDa1mgOtyuHZJ/9hdQK67CVyp5yQ7/ssbw==",
+      "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.20260914151757",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-nestjs-core/-/fullstack-nestjs-core-1.1.62-alpha.20260914151757.tgz",
-      "integrity": "sha512-1o32Arg42ACa/+jq8MyFHNvjKAL0QJQmR6/bj7HF8QtbDCEYp/Ahm0LgYPVz9QXQn0cOWUE4zh0qwns4l/n6Yw==",
+      "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.20260914151759",
+        "@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.20260914151759",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/nestjs-mcp/-/nestjs-mcp-0.1.1-alpha.20260914151759.tgz",
-      "integrity": "sha512-omVHjHSxhzuZKePXr8cu7AsqqvAYEV9YC8twMhD/DcazAxLPx9Ea4l7OtvZikv15qV2SHF80UJEeu903HE0Cew==",
+      "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,17 +18,19 @@
     "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": "concurrently -n \"server,client\" -c \"blue,green\" \"npm run type:check:server\" \"npm run type:check:client\"",
+    "type:check": "node ./scripts/lint.js --typecheck",
     "type:check:client": "tsc --noEmit --project tsconfig.app.json",
     "type:check:server": "tsc --noEmit --project tsconfig.node.json",
     "lint": "node ./scripts/lint.js",
     "precommit": "node scripts/hooks/run-precommit.js",
-    "upgrade": "npx -y @lark-apaas/fullstack-cli sync --disable-gen-openapi"
+    "upgrade": "npx -y @lark-apaas/fullstack-cli sync --disable-gen-openapi",
+    "type:check:mcp-ui": "node ./scripts/lint.js --typecheck-mcp-ui",
+    "eslint:mcp-ui": "node ./scripts/lint.js --eslint-mcp-ui"
   },
   "dependencies": {
-    "@lark-apaas/fullstack-nestjs-core": "1.1.62-alpha.20260914151757",
+    "@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",
@@ -53,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.20260914151758",
+    "@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

package/template/scripts/lint.js

@@ -18,19 +18,31 @@ function runCommand(command, args) {
       shell: false,
     });
 
-    child.on('close', (code) => resolve(code || 0));
+    child.on('close', (code) => resolve(code ?? 1));
     child.on('error', () => resolve(1));
   });
 }
 
+// 串行依次执行每个任务，全部跑完后再聚合退出码：
+// 降低并发资源占用、让各任务输出按顺序清晰可读，同时保留“一次暴露所有 lint 问题”的行为。
+async function runTasksSerially(taskSpecs) {
+  let exitCode = 0;
+  for (const [command, args] of taskSpecs) {
+    const code = await runCommand(command, args);
+    if (code !== 0) {
+      exitCode = 1;
+    }
+  }
+  return exitCode;
+}
+
 function normalizeProjectFile(filePath) {
   const absolutePath = path.isAbsolute(filePath)
     ? filePath
     : path.resolve(cwd, filePath);
 
   if (!fs.existsSync(absolutePath)) {
-    console.warn(`[lint] Skip missing file: ${filePath}`);
-    return null;
+    console.log(`[lint] Deleted file: ${filePath}; checking affected projects`);
   }
 
   const relativePath = path.relative(cwd, absolutePath);
@@ -94,17 +106,92 @@ function canRunStylelint() {
   return STYLELINT_CONFIG_FILES.some(file => fs.existsSync(path.join(cwd, file)));
 }
 
+const UI_DIR = 'server/mcp/ui';
+const UI_TYPECHECK = 'node ./scripts/lint.js --typecheck';
+
+function isUiFile(file) {
+  return file.startsWith(`${UI_DIR}/`);
+}
+
+function uiSourceFiles() {
+  const files = [];
+  function visit(relative) {
+    const absolute = path.join(cwd, relative);
+    if (!fs.existsSync(absolute)) return;
+    if (fs.lstatSync(absolute).isSymbolicLink()) {
+      throw new Error(`MCP UI 检查不支持符号链接: ${relative}`);
+    }
+    for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+      if (['node_modules', 'dist', '.git'].includes(entry.name)) continue;
+      const file = `${relative}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw new Error(`MCP UI 检查不支持符号链接: ${file}`);
+      if (entry.isDirectory()) visit(file);
+      else if (isEslintTarget(file) && !/\.d\.(?:ts|mts|cts)$/.test(file)) files.push(file);
+    }
+  }
+  visit(UI_DIR);
+  return files.sort();
+}
+
+function uiTasks({ types = true, eslint = true } = {}) {
+  const sources = uiSourceFiles();
+  if (!sources.length) return [];
+  const tasks = [];
+  if (types) {
+    const config = `${UI_DIR}/tsconfig.json`;
+    if (!fs.existsSync(path.join(cwd, config))) {
+      throw new Error(`MCP UI 缺少 ${config}，请按 mcp-guide 补齐独立浏览器 TypeScript 配置。`);
+    }
+    const ts = require('typescript');
+    const parsed = ts.getParsedCommandLineOfConfigFile(path.join(cwd, config), {}, {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: d => { throw new Error(ts.flattenDiagnosticMessageText(d.messageText, '\n')); },
+    });
+    if (!parsed || parsed.errors.length) throw new Error(`MCP UI TypeScript 配置无效: ${config}`);
+    const included = new Set(parsed.fileNames.map(file => path.resolve(file)));
+    const missing = sources.filter(file => !included.has(path.resolve(cwd, file)));
+    if (missing.length) throw new Error(`MCP UI TypeScript 配置未覆盖源码: ${missing.join(', ')}；请检查 include/exclude，JS 源码需开启 allowJs。`);
+    tasks.push([getBinName('npx'), ['--no-install', 'tsc', '--noEmit', '-p', config]]);
+  }
+  if (eslint) {
+    const config = ['eslint.mcp-ui.config.js', 'eslint.mcp-ui.config.cjs', 'eslint.mcp-ui.config.mjs']
+      .find(file => fs.existsSync(path.join(cwd, file)));
+    if (!config) throw new Error('MCP UI 缺少独立 ESLint 配置，请按 mcp-guide 创建 eslint.mcp-ui.config.cjs。');
+    tasks.push([getBinName('npx'), ['--no-install', 'eslint', '--config', config, '--quiet', '--max-warnings', '0', ...sources]]);
+  }
+  return tasks;
+}
+
+function packageScripts() {
+  return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).scripts || {};
+}
+
+async function runTypeCheck() {
+  const scripts = packageScripts();
+  const tasks = ['type:check:server', 'type:check:client'].map(name => {
+    if (!scripts[name]) throw new Error(`缺少 scripts.${name}，请保留应用原有类型检查命令。`);
+    return [getBinName('npm'), ['run', name]];
+  });
+  tasks.push(...uiTasks({ eslint: false }));
+  process.exit(await runTasksSerially(tasks));
+}
+
 async function runDefaultLint() {
-  const commands = ['npm run eslint', 'npm run type:check'];
+  const taskSpecs = [
+    [getBinName('npm'), ['run', 'eslint']],
+    [getBinName('npm'), ['run', 'type:check']],
+  ];
+
+  // Customized type:check remains untouched; ensure full lint still checks UI.
+  taskSpecs.push(...uiTasks({ types: packageScripts()['type:check'] !== UI_TYPECHECK }));
 
   if (canRunStylelint()) {
-    commands.push('npm run stylelint');
+    taskSpecs.push([getBinName('npm'), ['run', 'stylelint']]);
   } else {
     console.warn('[lint] Skip stylelint: missing scripts.stylelint or stylelint config');
   }
 
-  const code = await runCommand(getBinName('npx'), ['concurrently', ...commands]);
-  process.exit(code);
+  process.exit(await runTasksSerially(taskSpecs));
 }
 
 async function runSelectiveLint(inputFiles) {
@@ -117,15 +204,20 @@ async function runSelectiveLint(inputFiles) {
     process.exit(0);
   }
 
-  const eslintFiles = normalizedFiles.filter(isEslintTarget);
-  const stylelintFiles = normalizedFiles.filter(isStylelintTarget);
+  const eslintFiles = normalizedFiles.filter(file => fs.existsSync(path.join(cwd, file)) && isEslintTarget(file) && !isUiFile(file) && !file.startsWith('eslint.mcp-ui.config.'));
+  const stylelintFiles = normalizedFiles.filter(file => fs.existsSync(path.join(cwd, file)) && isStylelintTarget(file));
   const typeCheckFiles = normalizedFiles.filter(isTypeCheckTarget);
 
   const clientTypeFiles = [];
   const serverTypeFiles = [];
+  const rootConfigChanged = normalizedFiles.some(file => /^tsconfig(?:\.[^/]*)?\.json$/.test(file));
+  if (rootConfigChanged) { clientTypeFiles.push('config'); serverTypeFiles.push('config'); }
+  let checkUi = rootConfigChanged || normalizedFiles.some(file => isUiFile(file) || file.startsWith('shared/') || file.startsWith('eslint.mcp-ui.config.'));
 
   for (const filePath of typeCheckFiles) {
-    if (filePath.startsWith('client/')) {
+    if (isUiFile(filePath)) {
+      checkUi = true;
+    } else if (filePath.startsWith('client/')) {
       clientTypeFiles.push(filePath);
     } else if (filePath.startsWith('server/')) {
       serverTypeFiles.push(filePath);
@@ -135,36 +227,46 @@ async function runSelectiveLint(inputFiles) {
     }
   }
 
-  const tasks = [];
+  const taskSpecs = [];
 
   if (eslintFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npx'), ['eslint', '--quiet', ...eslintFiles]));
+    taskSpecs.push([getBinName('npx'), ['eslint', '--quiet', ...eslintFiles]]);
   }
 
   if (stylelintFiles.length > 0 && !canRunStylelint()) {
     console.warn('[lint] Skip stylelint: missing scripts.stylelint or stylelint config');
   } else if (stylelintFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npx'), ['stylelint', '--quiet', ...stylelintFiles]));
+    taskSpecs.push([getBinName('npx'), ['stylelint', '--quiet', ...stylelintFiles]]);
   }
 
   if (clientTypeFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npm'), ['run', 'type:check:client']));
+    taskSpecs.push([getBinName('npm'), ['run', 'type:check:client']]);
   }
 
   if (serverTypeFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npm'), ['run', 'type:check:server']));
+    taskSpecs.push([getBinName('npm'), ['run', 'type:check:server']]);
   }
 
-  if (tasks.length === 0) {
+  if (checkUi) taskSpecs.push(...uiTasks());
+
+  if (taskSpecs.length === 0) {
     console.log('[lint] No supported files matched for lint');
     process.exit(0);
   }
 
-  const results = await Promise.all(tasks);
-  process.exit(results.some(code => code !== 0) ? 1 : 0);
+  process.exit(await runTasksSerially(taskSpecs));
 }
 
 async function main() {
+  const args = process.argv.slice(2);
+  const modes = ['--typecheck', '--typecheck-mcp-ui', '--eslint-mcp-ui'];
+  if (args.length && !(args[0] === '--files' && args.length > 1) && !(args.length === 1 && modes.includes(args[0]))) {
+    throw new Error('用法: lint.js [--files <paths...> | --typecheck | --typecheck-mcp-ui | --eslint-mcp-ui]');
+  }
+  if (args[0] === '--files' && args.slice(1).some(arg => arg.startsWith('--'))) throw new Error('--files 不可与其他检查模式混用');
+  if (args.includes('--typecheck')) return runTypeCheck();
+  if (args.includes('--typecheck-mcp-ui')) return process.exit(await runTasksSerially(uiTasks({ eslint: false })));
+  if (args.includes('--eslint-mcp-ui')) return process.exit(await runTasksSerially(uiTasks({ types: false })));
   const files = parseFilesArg(process.argv.slice(2));
   if (files === null) {
     await runDefaultLint();