create-fullstack-scaffold 0.4.25 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fullstack-scaffold",
-  "version": "0.4.25",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "create-fullstack-scaffold": "dist/cli/index.js"
@@ -30,10 +30,7 @@
     "template/public"
   ],
   "workspaces": [
-    "template",
-    "packages/core",
-    "packages/infrastructure",
-    "packages/domain-plugin"
+    "template"
   ],
   "publishConfig": {
     "access": "public"
@@ -104,10 +101,12 @@
     "turbo:test": "turbo test",
     "turbo:lint": "turbo lint",
     "turbo:typecheck": "turbo typecheck",
-    "turbo:all": "turbo lint typecheck test build"
+    "turbo:all": "turbo lint typecheck test build",
+    "hooks:sync": "node scripts/sync-agent-hooks.mjs",
+    "hooks:check": "node scripts/sync-agent-hooks.mjs --check"
   },
   "dependencies": {
-    "@hono/node-server": "^1.14.4",
+    "@hono/node-server": "^1.19.15",
     "@hono/zod-openapi": "1.2.2",
     "@hono/zod-validator": "0.7.6",
     "@inquirer/prompts": "^8.4.2",
@@ -117,7 +116,7 @@
     "dotenv": "^16.5.0",
     "drizzle-orm": "^0.45.1",
     "fs-extra": "^11.3.5",
-    "hono": "4.12.16",
+    "hono": "4.12.34",
     "jsonwebtoken": "^9.0.3",
     "lucide-react": "^0.576.0",
     "ora": "^9.4.0",
@@ -125,8 +124,8 @@
     "pino-pretty": "^13.0.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "react-router-dom": "^7.13.1",
-    "ws": "^8.18.3",
+    "react-router-dom": "^7.18.3",
+    "ws": "^8.21.3",
     "tsx": "^4.21.0",
     "zod": "^4.4.3",
     "zustand": "^5.0.2"
@@ -183,9 +182,7 @@
       "eslint --fix",
       "eslint --max-warnings=0 --no-warn-ignored"
     ],
-    "*.{json,md,css}": [
-      "prettier --write"
-    ]
+    "*.{json,md,css}": "prettier --write"
   },
   "engines": {
     "node": ">=18.0.0"

package/template/eslint-rules/__tests__/no-merged-api-type-export.test.ts

@@ -0,0 +1,96 @@
+/**
+ * @framework-baseline bd40e51c9ebe57ab
+ */
+
+import { RuleTester } from 'eslint'
+import tseslint from 'typescript-eslint'
+import { noMergedApiTypeExport } from '../no-merged-api-type-export.js'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslint.parser,
+    ecmaVersion: 2022,
+    sourceType: 'module',
+  },
+})
+
+ruleTester.run('no-merged-api-type-export', noMergedApiTypeExport, {
+  valid: [
+    {
+      // 运行时链式挂载是合法的 —— 约束的是"类型出口"，不是运行时
+      filename: 'src/server/route-registry.ts',
+      code: `
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+export const clientApiRoutes = new OpenAPIHono()
+  .route('/api', moduleA)
+  .route('/api', moduleB)
+  .route('/api', moduleC)
+`,
+    },
+    {
+      // 模块级类型导出（深度 = 1 个模块）是推荐做法
+      filename: 'src/server/module-todos/routes/todos-routes.ts',
+      code: `
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+export const apiRoutes = new OpenAPIHono()
+  .openapi(listRoute, handler)
+
+export type TodosApiType = typeof apiRoutes
+`,
+    },
+    {
+      // typeof 引用的变量没有链式 .route —— 不是 merge 结果
+      filename: 'src/server/module-chat/routes/chat-routes.ts',
+      code: `
+export const chatRoutes = new OpenAPIHono()
+
+export type ChatApiType = typeof chatRoutes
+`,
+    },
+  ],
+  invalid: [
+    {
+      // 出口 1: export type = typeof <链式 merge 实例>
+      filename: 'src/server/route-registry.ts',
+      code: `
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+export const clientApiRoutes = new OpenAPIHono()
+  .route('/api', moduleA)
+  .route('/api', moduleB)
+
+export type ClientApiRoutes = typeof clientApiRoutes
+`,
+      errors: [{ messageId: 'noMergedTypeExport', data: { name: 'clientApiRoutes' } }],
+    },
+    {
+      // 出口 2: ReturnType<typeof createApp> —— app 工厂内部链式 merge
+      filename: 'src/server/app.ts',
+      code: `
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+export function createApp() {
+  return new OpenAPIHono()
+    .route('/', clientApiRoutes)
+    .route('/', adminApiRoutes)
+}
+
+export type AppType = ReturnType<typeof createApp>
+`,
+      errors: [{ messageId: 'noReturnTypeOfAppFactory', data: { name: 'createApp' } }],
+    },
+    {
+      // 出口 3: ReturnType<typeof hc<MegaType>>> —— 测试客户端的 mega 实例化
+      filename: 'src/server/test-utils/test-client.ts',
+      code: `
+import { hc } from 'hono/client'
+import type { AppType } from '@server/index'
+
+export type TestClient = ReturnType<typeof hc<AppType>>
+`,
+      errors: [{ messageId: 'noReturnTypeOfHcInstantiation' }],
+    },
+  ],
+})

package/template/eslint-rules/no-cross-module-service-import.js

@@ -1,3 +1,7 @@
+/**
+ * @framework-baseline ae78703ba6753ec3
+ */
+
 /**
  * @fileoverview Prevent cross-module service internal imports
  * @author create-biomimic-app

package/template/eslint-rules/no-merged-api-type-export.js

@@ -0,0 +1,190 @@
+/**
+ * @framework-baseline c934bac96702cb89
+ */
+
+/**
+ * 禁止导出链式 merge 后的巨型 app 类型（TS2589 的根源治理）
+ *
+ * 背景：route-registry 把 N 个模块 .route() 链式合并，Hono 的类型系统在每一环
+ * 都携带前面所有环的完整累积。把这种 merge 结果导出为类型（typeof / ReturnType）
+ * 并被 hc<T> 实例化时，TypeScript 需要深度展开整个链条，超过 instantiationDepth
+ * 100 就报 TS2589。历史上曾用 typescript+5.9.3.patch 把上限改到 1000 来绕过，
+ * 代价是编译变慢、编辑器不稳定（该 patch 已被 no-ts-patch validator 禁止）。
+ *
+ * 正确模式：每个模块导出自己的窄类型（深度 = 1），客户端按模块实例化 hc。
+ * 运行时链式挂载（.route()）本身合法——本规则只封"类型出口"，不碰运行时。
+ *
+ * 检测三种出口形态：
+ * 1. export type X = typeof <初始化含 ≥2 个 .route() 的变量>
+ * 2. export type X = ReturnType<typeof <函数体内含 ≥2 个 .route() 的函数>>
+ * 3. export type X = ReturnType<typeof hc<MegaType>>>（测试客户端的 mega 实例化）
+ */
+
+/** @param {import('eslint').Rule.RuleContext} context */
+function create(context) {
+  const sourceCode = context.sourceCode || context.getSourceCode()
+
+  // 变量名 → 初始化子树内 .route() 调用 ≥2 次的声明
+  const chainedVars = new Map()
+  // 函数名 → 函数体子树内 .route() 调用 ≥2 次的声明
+  const appFactories = new Map()
+  // 待分析的 type alias（在 Program:exit 统一判定，避免依赖源码顺序）
+  const typeAliases = []
+
+  /**
+   * 统计子树内 .route() 调用次数（不依赖链根，嵌套闭包内的也算）
+   * @param {import('eslint').Rule.Node} node
+   */
+  function countRouteCalls(node) {
+    if (!node || typeof node.type !== 'string') return 0
+    let count = 0
+    if (
+      node.type === 'CallExpression' &&
+      node.callee &&
+      node.callee.type === 'MemberExpression' &&
+      node.callee.property &&
+      node.callee.property.type === 'Identifier' &&
+      node.callee.property.name === 'route'
+    ) {
+      count++
+    }
+    const keys = sourceCode.visitorKeys[node.type] || []
+    for (const key of keys) {
+      const child = node[key]
+      if (Array.isArray(child)) {
+        for (const c of child) count += countRouteCalls(c)
+      } else if (child && typeof child.type === 'string') {
+        count += countRouteCalls(child)
+      }
+    }
+    return count
+  }
+
+  return {
+    VariableDeclarator(node) {
+      if (!node.init || !node.id || node.id.type !== 'Identifier') return
+      if (countRouteCalls(node.init) >= 2) {
+        chainedVars.set(node.id.name, node)
+      }
+    },
+
+    FunctionDeclaration(node) {
+      if (!node.id || !node.body) return
+      if (countRouteCalls(node.body) >= 2) {
+        appFactories.set(node.id.name, node)
+      }
+    },
+
+    TSTypeAliasDeclaration(node) {
+      typeAliases.push(node)
+    },
+
+    'Program:exit'() {
+      for (const alias of typeAliases) {
+        // 只约束导出的类型别名（规则名与语义都是 "export"）
+        const isExported = alias.parent && alias.parent.type === 'ExportNamedDeclaration'
+
+        // typeAnnotation 直接就是类型节点（TSTypeQuery / TSTypeReference），没有中间包装
+        const typeRef = alias.typeAnnotation
+
+        // 形态 1: typeof <chainedVar>
+        if (typeRef && typeRef.type === 'TSTypeQuery') {
+          const exprName = typeRef.exprName
+          if (
+            isExported &&
+            exprName &&
+            exprName.type === 'Identifier' &&
+            chainedVars.has(exprName.name)
+          ) {
+            context.report({
+              node: alias,
+              messageId: 'noMergedTypeExport',
+              data: { name: exprName.name },
+            })
+          }
+        }
+
+        // 形态 2/3: ReturnType<...>
+        if (
+          typeRef &&
+          typeRef.type === 'TSTypeReference' &&
+          typeRef.typeName &&
+          typeRef.typeName.type === 'Identifier' &&
+          typeRef.typeName.name === 'ReturnType' &&
+          typeRef.typeArguments &&
+          typeRef.typeArguments.params &&
+          typeRef.typeArguments.params.length > 0
+        ) {
+          const arg = typeRef.typeArguments.params[0]
+
+          // 形态 3: typeof hc<AppType> —— instantiation expression
+          if (
+            isExported &&
+            arg.type === 'TSTypeQuery' &&
+            arg.typeArguments &&
+            arg.exprName &&
+            arg.exprName.type === 'Identifier' &&
+            arg.exprName.name === 'hc'
+          ) {
+            context.report({
+              node: alias,
+              messageId: 'noReturnTypeOfHcInstantiation',
+            })
+            continue
+          }
+
+          // 形态 2: typeof createApp
+          if (
+            isExported &&
+            arg.type === 'TSTypeQuery' &&
+            arg.exprName &&
+            arg.exprName.type === 'Identifier' &&
+            appFactories.has(arg.exprName.name)
+          ) {
+            context.report({
+              node: alias,
+              messageId: 'noReturnTypeOfAppFactory',
+              data: { name: arg.exprName.name },
+            })
+          }
+        }
+      }
+    },
+  }
+}
+
+export const noMergedApiTypeExport = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        '禁止导出链式 merge 后的巨型 app 类型（typeof / ReturnType），防止 TS2589 类型爆炸',
+      recommended: true,
+    },
+    messages: {
+      noMergedTypeExport:
+        '禁止导出 `typeof {{{name}}}`：它的初始化链式合并了多个模块（≥2 个 .route()），' +
+        '导出此类型会让 hc<T> 深度实例化整条链，触发 TS2589。\n\n' +
+        '// ❌ 错误\n' +
+        'export type ClientApiRoutes = typeof clientApiRoutes  // 11 个模块的 merge\n\n' +
+        '// ✅ 正确 —— 每个模块导出自己的窄类型\n' +
+        'export type TodosApiType = typeof apiRoutes            // 模块 routes 文件里\n' +
+        'export const todosClient = hc<TodosApiType>("/api")    // 客户端按模块实例化',
+      noReturnTypeOfAppFactory:
+        '禁止导出 `ReturnType<typeof {{{name}}}>`：该工厂函数内部链式合并了多个模块（≥2 个 .route()），' +
+        '此类型会把整条 merge 链暴露给类型系统，触发 TS2589。\n\n' +
+        '// ❌ 错误\n' +
+        'export type AppType = ReturnType<typeof createApp>\n\n' +
+        '// ✅ 正确 —— 运行时类型用 Hono<AppBindings>，RPC 类型按模块拆分',
+      noReturnTypeOfHcInstantiation:
+        '禁止导出 `ReturnType<typeof hc<MegaType>>>`：用 merge 后的巨型类型实例化 hc ' +
+        '正是 TS2589 的直接触发点（深度展开整条类型链）。\n\n' +
+        '// ❌ 错误\n' +
+        'export type TestClient = ReturnType<typeof hc<AppType>>\n\n' +
+        '// ✅ 正确 —— 按模块组装的门面，每个属性是独立的窄客户端类型\n' +
+        'export type TestClient = { api: { todos: TodosClient; chat: ChatClient } }',
+    },
+    schema: [],
+  },
+  create,
+}

package/template/eslint.config.js

@@ -39,6 +39,7 @@ import { noDeepRelativeImports } from './eslint-rules/no-deep-relative-imports.j
 import { noCrossModuleServiceImport } from './eslint-rules/no-cross-module-service-import.js'
 import { noDisableTypeSafeClient } from './eslint-rules/no-disable-type-safe-client.js'
 import { routeLocation } from './eslint-rules/route-location.js'
+import { noMergedApiTypeExport } from './eslint-rules/no-merged-api-type-export.js'
 
 const localRules = {
   rules: {
@@ -77,6 +78,7 @@ const localRules = {
     'no-cross-module-service-import': noCrossModuleServiceImport,
     'no-disable-type-safe-client': noDisableTypeSafeClient,
     'route-location': routeLocation,
+    'no-merged-api-type-export': noMergedApiTypeExport,
   },
 }
 
@@ -127,6 +129,7 @@ export default tseslint.config(
       'local-rules/no-cross-module-service-import': 'error',
       'local-rules/route-location': 'error',
       'local-rules/limit-type-complexity': ['warn', { maxRouteChainLength: 15 }],
+      'local-rules/no-merged-api-type-export': 'error',
     },
   },
   {

package/template/package.json

@@ -1,7 +1,7 @@
 {
   "name": "biomimic-todo-app",
   "private": true,
-  "version": "0.1.1",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "biomimic": "./dist/cli/index.js"
@@ -67,11 +67,13 @@
     "ai:context": "node --import tsx/esm lint-scripts/ai-context-generator.ts",
     "postinstall": "node -e \"process.exit(require('fs').existsSync('node_modules/hono')?0:1)\" && patch-package || true",
     "prepare": "husky",
-    "typecheck:full": "tsc --noEmit && eslint . --max-warnings=0"
+    "typecheck:full": "tsc --noEmit && eslint . --max-warnings=0",
+    "hooks:sync": "node scripts/sync-agent-hooks.mjs",
+    "hooks:check": "node scripts/sync-agent-hooks.mjs --check"
   },
   "dependencies": {
     "@dyyz1993/xcli-core": "^0.7.4",
-    "@hono/node-server": "^1.14.4",
+    "@hono/node-server": "^1.19.15",
     "@hono/zod-openapi": "1.2.2",
     "@hono/zod-validator": "0.7.6",
     "@ant-design/icons": "^5.6.1",
@@ -81,7 +83,7 @@
     "dayjs": "^1.11.13",
     "dotenv": "^16.5.0",
     "drizzle-orm": "^0.45.1",
-    "hono": "4.12.16",
+    "hono": "4.12.34",
     "jsonwebtoken": "^9.0.3",
     "lucide-react": "^0.576.0",
     "pino": "^9.7.0",
@@ -89,8 +91,8 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-helmet-async": "^3.0.0",
-    "react-router-dom": "^7.13.1",
-    "ws": "^8.18.3",
+    "react-router-dom": "^7.18.3",
+    "ws": "^8.21.3",
     "zod": "^4.4.3",
     "i18next": "^24.2.3",
     "react-i18next": "^15.5.3",
@@ -105,6 +107,7 @@
     "@playwright/test": "^1.60.0",
     "@prerenderer/renderer-jsdom": "^1.1.9",
     "@prerenderer/renderer-puppeteer": "^1.2.4",
+    "puppeteer": "^24.43.1",
     "@prerenderer/rollup-plugin": "^0.3.12",
     "@tailwindcss/postcss": "^4.2.1",
     "@testing-library/dom": "^10.4.1",

package/template/scripts/sync-agent-hooks.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * agent hooks 同步工具（规范源：仓库 .zcode/hooks/no-no-verify.mjs）
+ *
+ * 用法：
+ *   node scripts/sync-agent-hooks.mjs            # 探测环境并报告状态
+ *   node scripts/sync-agent-hooks.mjs --global   # 同步安装到各 agent 全局配置
+ *   node scripts/sync-agent-hooks.mjs --check    # 漂移检查（CI / validate:all 用）
+ *
+ * 两层模型：
+ *   工作区级（.zcode/config.json 随仓库走）——修改后 git pull 即生效，无需本工具
+ *   全局级（~/.zcode、~/.codex）——开发者机器私有，用 --global 显式同步；
+ *           修改规范源后需重跑 --global（--check 会提示过期）
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.resolve(__dirname, '..')
+const CANONICAL = path.join(ROOT, '.zcode/hooks/no-no-verify.mjs')
+
+const args = process.argv.slice(2)
+const MODE = args.includes('--check') ? 'check' : args.includes('--global') ? 'global' : 'status'
+
+// ---------- 环境探测 ----------
+
+function detectAgents() {
+  const home = homedir()
+  return {
+    zcode: {
+      installed: existsSync(path.join(home, '.zcode')),
+      globalConfig: path.join(home, '.zcode/cli/config.json'),
+      globalHooksDir: path.join(home, '.zcode/cli/hooks'),
+    },
+    codex: {
+      installed: existsSync(path.join(home, '.codex')),
+      configToml: path.join(home, '.codex/config.toml'),
+      hooksDir: path.join(home, '.codex/hooks'),
+    },
+    claude: { installed: existsSync(path.join(home, '.claude')) },
+    cursor: { installed: existsSync(path.join(home, '.cursor')) },
+  }
+}
+
+// ---------- ZCode 全局（幂等注册） ----------
+
+function syncZCodeGlobal(agents, apply) {
+  const target = path.join(agents.zcode.globalHooksDir, 'no-no-verify.mjs')
+  const cmd = `node ${JSON.stringify(target).replace(/"/g, '')}`
+  const cfgPath = agents.zcode.globalConfig
+  if (!existsSync(cfgPath)) return { status: 'skip', detail: `未找到 ${cfgPath}` }
+
+  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'))
+  cfg.hooks ??= {}
+  cfg.hooks.enabled = true
+  cfg.hooks.events ??= {}
+  const list = (cfg.hooks.events.PreToolUse ??= [])
+  const command = `node ${target}`
+  const exists = list.some(g => (g.hooks || []).some(h => /no-verify/.test(h.command || '')))
+
+  // 无条件幂等归一：清掉所有 no-verify 家族条目（含旧 block-no-verify 命名），
+  // 再注册规范条目 —— 重复执行结果一致，也不会新旧双轨
+  for (const g of list) {
+    g.hooks = (g.hooks || []).filter(h => !/no-verify/.test(h.command || ''))
+  }
+  list.push({ matcher: 'Bash', hooks: [{ type: 'command', command, enabled: true, timeoutMs: 5000 }] })
+  const changed = true
+  const installedUpToDate = existsSync(target) && readFileSync(target, 'utf8') === readFileSync(CANONICAL, 'utf8')
+
+  if (MODE === 'check') {
+    // 未安装（如 CI runner / 新同事）不是漂移；只有"存在但过期"才是
+    if (!existsSync(target)) return { status: 'missing', detail: '本机未安装全局钩子（可选：npm run hooks:sync -- --global）' }
+    if (!installedUpToDate) return { status: 'drift', detail: '全局脚本与规范源不一致，运行 npm run hooks:sync -- --global' }
+    return { status: 'ok', detail: '已安装且为最新' }
+  }
+  if (MODE === 'global' && apply) {
+    if (!installedUpToDate) {
+      mkdirSync(agents.zcode.globalHooksDir, { recursive: true })
+      copyFileSync(CANONICAL, target)
+    }
+    if (changed || !installedUpToDate) writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
+    return { status: 'ok', detail: `已同步 → ${target}` }
+  }
+  return { status: exists ? 'ok' : 'missing', detail: exists ? '已注册' : '未注册' }
+}
+
+// ---------- Codex 全局（TOML 幂等追加） ----------
+
+const CODEX_BLOCK = (scriptPath) => `# >>> scaffold agent-hooks（npm run hooks:sync 管理，勿手改） >>>
+[[hooks.PreToolUse]]
+matcher = "^Bash$"
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "node ${scriptPath}"
+timeout = 5
+statusMessage = "Checking for forbidden --no-verify"
+# <<< scaffold agent-hooks <<<`
+
+function syncCodexGlobal(agents, apply) {
+  if (!agents.codex.installed || !existsSync(agents.codex.configToml)) {
+    return { status: 'skip', detail: '未检测到 Codex' }
+  }
+  const target = path.join(agents.codex.hooksDir, 'no-no-verify.mjs')
+  const toml = readFileSync(agents.codex.configToml, 'utf8')
+  const hasBlock = toml.includes('scaffold agent-hooks')
+
+  if (MODE === 'check') {
+    if (!hasBlock && !existsSync(target)) {
+      return { status: 'missing', detail: '本机未检测到 Codex 钩子（可选：npm run hooks:sync -- --global）' }
+    }
+    const upToDate = hasBlock && existsSync(target) && readFileSync(target, 'utf8') === readFileSync(CANONICAL, 'utf8')
+    if (!upToDate) return { status: 'drift', detail: 'Codex 全局钩子过期，运行 npm run hooks:sync -- --global' }
+    return { status: 'ok', detail: '已安装且为最新' }
+  }
+  if (MODE === 'global' && apply) {
+    mkdirSync(agents.codex.hooksDir, { recursive: true })
+    copyFileSync(CANONICAL, target)
+    if (!hasBlock) {
+      writeFileSync(agents.codex.configToml, toml.trimEnd() + '\n\n' + CODEX_BLOCK(target) + '\n')
+    }
+    return {
+      status: 'ok',
+      detail: `已同步 → ${target}（config.toml 若有 trust-hash 机制需在 Codex 内重新信任）`,
+    }
+  }
+  return { status: hasBlock ? 'ok' : 'missing', detail: hasBlock ? '已注册' : '未注册（--global 安装）' }
+}
+
+// ---------- root ↔ template 副本对账 ----------
+
+function checkTemplateMirror() {
+  const pairs = [
+    ['.zcode/hooks/no-no-verify.mjs', '.zcode/hooks/no-no-verify.mjs'],
+    ['.zcode/config.json', '.zcode/config.json'],
+    ['scripts/sync-agent-hooks.mjs', 'scripts/sync-agent-hooks.mjs'],
+  ]
+  const issues = []
+  for (const [rootRel, tplRel] of pairs) {
+    const a = path.join(ROOT, rootRel)
+    const b = path.join(ROOT, 'template', tplRel)
+    if (!existsSync(a) || !existsSync(b)) {
+      issues.push(`缺失：${rootRel} ↔ template/${tplRel}`)
+    } else if (readFileSync(a, 'utf8') !== readFileSync(b, 'utf8')) {
+      issues.push(`内容漂移：${rootRel} ↔ template/${tplRel}`)
+    }
+  }
+  return issues
+}
+
+// ---------- 主流程 ----------
+
+const agents = detectAgents()
+const results = []
+
+if (MODE === 'check' || MODE === 'status') {
+  const mirrorIssues = checkTemplateMirror()
+  results.push({ agent: 'root↔template', r: mirrorIssues.length ? { status: 'drift', detail: mirrorIssues.join('; ') } : { status: 'ok', detail: '镜像一致' } })
+}
+results.push({ agent: 'ZCode 全局', r: syncZCodeGlobal(agents, MODE === 'global') })
+results.push({ agent: 'Codex 全局', r: syncCodexGlobal(agents, MODE === 'global') })
+
+if (MODE === 'status') {
+  console.log('🔍 Agent 环境探测：')
+  for (const [name, a] of Object.entries(agents)) console.log(`  ${a.installed ? '✓' : '–'} ${name}`)
+  console.log('\n🪝 钩子状态（工作区级 .zcode/ 随仓库自动生效）：')
+}
+for (const { agent, r } of results) {
+  const icon = r.status === 'ok' ? '✓' : r.status === 'drift' ? '❌' : r.status === 'missing' ? '⚠️' : '–'
+  console.log(`  ${icon} ${agent}：${r.detail}`)
+}
+
+if (MODE === 'global') console.log('\n✅ 全局同步完成。工作区钩子（.zcode/）无需本工具，随 git 自动生效。')
+
+if (MODE === 'check') {
+  // 退出码只由 root↔template 镜像决定；全局级是开发者机器私有（缺失/过期仅提示），
+  // 否则无 ~/.zcode 的 CI runner 或新同事会被误伤
+  const mirrorDrift = results.find(x => x.agent === 'root↔template' && x.r.status === 'drift')
+  if (mirrorDrift) {
+    console.error('\n❌ hooks 镜像漂移（root ↔ template），请同步副本后重试')
+    process.exit(1)
+  }
+  if (results.some(({ r }) => r.status === 'drift')) {
+    console.log('\n⚠️ 全局钩子过期：运行 npm run hooks:sync -- --global 更新本机配置')
+  }
+}

package/template/src/admin/components/__tests__/StatsCard.test.tsx

@@ -27,7 +27,7 @@ describe('StatsCard', () => {
     render(<StatsCard title="Users" value={100} trend={{ value: 12, isUp: true }} />)
 
     expect(screen.getByText('12%')).toBeInTheDocument()
-    expect(screen.getByText('vs last month')).toBeInTheDocument()
+    expect(screen.getByText('较上月')).toBeInTheDocument()
   })
 
   it('should render downward trend', () => {
@@ -39,6 +39,6 @@ describe('StatsCard', () => {
   it('should not render trend section when trend is undefined', () => {
     render(<StatsCard title="Users" value={100} />)
 
-    expect(screen.queryByText('vs last month')).not.toBeInTheDocument()
+    expect(screen.queryByText('较上月')).not.toBeInTheDocument()
   })
 })

package/template/src/admin/pages/ContentPage.tsx

@@ -47,7 +47,7 @@ export const ContentPage: React.FC = () => {
       const response = await apiClient.api.contents.$get({ query: {} })
       const result = await response.json()
       if (result.success) {
-        setContents(result.data)
+        setContents(result.data.contents)
       } else {
         message.error(t('content.loadFailed'))
       }

package/template/src/admin/pages/DisputesPage.tsx

@@ -48,7 +48,7 @@ export const DisputesPage: React.FC = () => {
       const response = await apiClient.api.disputes.$get({ query: {} })
       const result = await response.json()
       if (result.success) {
-        setDisputes(result.data)
+        setDisputes(result.data.disputes)
       } else {
         message.error(result.error || t('disputes.loadFailed'))
       }

package/template/src/admin/pages/OrdersPage.tsx

@@ -45,7 +45,7 @@ export const OrdersPage: React.FC = () => {
       })
       const result = await response.json()
       if (result.success) {
-        setOrders(result.data)
+        setOrders(result.data.orders)
       } else {
         message.error(result.error || t('orders.loadFailed'))
       }