@clawos-dev/clawd 0.2.142 → 0.2.143-beta.301.814d293

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/config.env

@@ -0,0 +1,20 @@
+# ===== 平台级固定变量(一次配好,所有 extension 共用)=====
+# 阿里云凭证不在这里:从 .secrets/aliyun.env 现读(见 CLAUDE.md)
+
+REGION=cn-hangzhou
+
+# FC 运行时:custom.debian12(纯净) + 官方 Node22 层(自带 node + 原生 WebSocket)
+# 换语言时改这两行 + 换 contract/bootstrap(见 README「换框架/语言」)
+FC_RUNTIME=custom.debian12
+NODE_LAYER=acs:fc:cn-hangzhou:official:layers/Nodejs22/versions/1
+
+# dataclaw-service（通路 A，只读）—— 部署后填实际可达地址
+DATACLAW_SERVICE_URL=
+# TTC 飞书登录门禁（无密钥经纪，只重定向到 TTC）
+TTC_AUTH_BASE=https://app.ttcadvisory.com
+TTC_API_BASE=https://api.ttcadvisory.com
+
+# FC 资源规格(够跑轻量 extension;按需改)
+FC_CPU=0.35
+FC_MEMORY=512
+FC_TIMEOUT=60

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/contract/s.yaml.tmpl

@@ -0,0 +1,59 @@
+# s.yaml 模板 —— publish.sh 用 sed 替换 __占位符__ 后生成实际 s.yaml
+# 框架无关:command 固定走 ./bootstrap,入口由 FC_ENTRY 环境变量决定
+edition: 3.0.0
+name: __APP_NAME__-app
+access: default
+
+vars:
+  region: __REGION__
+
+resources:
+  __APP_NAME__:
+    component: fc3
+    props:
+      region: ${vars.region}
+      functionName: __APP_NAME__
+      description: __APP_NAME__ extension (FC serverless)
+      runtime: __FC_RUNTIME__
+      logConfig: auto
+      layers:
+        - __NODE_LAYER__
+      cpu: __FC_CPU__
+      memorySize: __FC_MEMORY__
+      diskSize: 512
+      timeout: __FC_TIMEOUT__
+      instanceConcurrency: 10
+      code: __CODE_DIR__
+      customRuntimeConfig:
+        command:
+          - ./bootstrap
+        port: 9000
+      environmentVariables:
+        PORT: '9000'
+        APP_ENTRY: __FC_ENTRY__
+        DATACLAW_SERVICE_URL: __DATACLAW_SERVICE_URL__
+        DATACLAW_AS_UNION_ID: __DATACLAW_AS_UNION_ID__
+        DATACLAW_INTERNAL_SECRET: __DATACLAW_INTERNAL_SECRET__
+        TTC_AUTH_BASE: __TTC_AUTH_BASE__
+        TTC_API_BASE: __TTC_API_BASE__
+        APP_BASE_URL: __APP_BASE_URL__
+        SESSION_SECRET: __SESSION_SECRET__
+      triggers:
+        - triggerName: httpTrigger
+          triggerType: http
+          triggerConfig:
+            authType: anonymous
+            methods: [GET, POST, PUT, DELETE, HEAD]
+
+  # 自定义域名:否则 fcapp.run 默认 URL 强制下载网页(防滥用),浏览器无法渲染
+  __APP_NAME__Domain:
+    component: fc3-domain
+    props:
+      region: ${vars.region}
+      domainName: auto
+      protocol: HTTP
+      routeConfig:
+        routes:
+          - path: /*
+            functionName: __APP_NAME__
+            qualifier: LATEST

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/ext.conf

@@ -0,0 +1,5 @@
+CODE_DIR=./server
+FC_ENTRY=dist/main.js
+BUILD_CMD="cd web && pnpm install && pnpm build && cd ../server && pnpm install && pnpm build && mkdir -p dist/public && cp -R ../web/dist/. dist/public/"
+# 建页人 union_id（dataclaw 数据范围按它裁剪）；persona 建页时调 auth.getIdentity 取到后填入。
+DATACLAW_AS_UNION_ID=""

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/.env.example

@@ -0,0 +1,15 @@
+# dataclaw 通路 A（后端直调 dataclaw-service HTTP，只读）
+DATACLAW_SERVICE_URL=http://dataclaw-service:8080
+# 建页人 builder 的 union_id —— 数据范围按此身份在 dataclaw 侧自动裁剪
+DATACLAW_AS_UNION_ID=on_xxxxxxxxxxxxxxxx
+# 服务间共享密钥（与 dataclaw-service 的 internal secret 对齐）；勿提交真实值
+DATACLAW_INTERNAL_SECRET=replace-me
+# 本地起页跳过门禁（仅 dev；上线删或置 0）
+DATACLAW_AUTH_DISABLED=1
+PORT=3000
+
+# TTC 飞书登录门禁（无密钥经纪：重定向到 TTC，不持飞书密钥）
+TTC_AUTH_BASE=https://app.ttcadvisory.com
+TTC_API_BASE=https://api.ttcadvisory.com
+APP_BASE_URL=https://your-app.example.com   # 发布后的公网地址，回调用；HTTPS（cookie secure）
+SESSION_SECRET=replace-with-openssl-rand-hex-32

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/.fcignore

@@ -0,0 +1,7 @@
+src/
+*.map
+.env
+tsconfig.json
+nest-cli.json
+*.log
+.fcignore

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "guestbook-server",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "nest build",
+    "start": "node --env-file=.env dist/main.js",
+    "start:dev": "nest start --watch",
+    "dev": "nest start --watch"
+  },
+  "dependencies": {
+    "@nestjs/common": "^10.4.0",
+    "@nestjs/core": "^10.4.0",
+    "@nestjs/platform-express": "^10.4.0",
+    "cookie-parser": "^1.4.6",
+    "dotenv": "^16.4.5",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.4.0",
+    "@nestjs/schematics": "^10.2.0",
+    "@types/cookie-parser": "^1.4.7",
+    "@types/node": "^22.0.0",
+    "@vitejs/plugin-react": "^4.4.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0"
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/app.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@nestjs/common';
+import { DataclawModule } from './dataclaw/dataclaw.module';
+
+// dataclaw 只读后端 BFF 起手骨架：默认只注册 DataclawModule（schema / query / intent /
+// consultants 四个只读端点，直调 dataclaw-service，身份按建页人 union_id 裁剪）。
+// 业务逻辑由 assistant 按用户需求从零加（添 controller/module 进 imports 即可）。
+//
+// vite middleware / 静态资源 serve 路径仍由 main.ts 处理（dev mount vite，prod express.static），
+// 不需要 ServeStaticModule。
+@Module({
+  imports: [DataclawModule],
+})
+export class AppModule {}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/auth/gate.ts

@@ -0,0 +1,70 @@
+// TTC 飞书登录门禁（无密钥经纪）：Express 中间件 + /auth/login、/auth/callback 处理器。
+// 必须挂在 vite middleware(dev) / express.static(prod) 之前——前端 HTML 不走 Nest 路由，
+// Nest guard 拦不住，所以门禁只能是 Express 层中间件（main.ts 接线在 vite/static 之前）。
+// 门禁只决定"能不能打开页"；数据范围仍由 dataclaw client 固定用建页人 union_id（PR-4 已做），
+// 不用登录者身份查数。
+import { fetchTtcUser } from './ttc-user-info'
+import { makeSession, readSession, makeState, verifyState } from './session'
+
+// req/res/next 用 any：express 不是本 server 包的直接依赖（pnpm 下从 server 根 require.resolve
+// 'express' 失败，main.ts:67 同样用 any），从 'express' import 类型会编译失败。
+type Req = any
+type Res = any
+type Next = (err?: unknown) => void
+
+const SESSION_COOKIE = 'dc_session'
+const STATE_COOKIE = 'dc_oauth_state'
+
+// 子路径部署（clawd dev preview/<port>/，见 main.ts subPath 逻辑）下 redirect 要带同样前缀；
+// prod base=/ 时无前缀，返回 '/auth/login'。
+function loginPath(req: Req): string {
+  const url = String(req.originalUrl || req.url || '')
+  const m = url.match(/^\/(preview\/\d+)\//)
+  return m ? `/${m[1]}/auth/login` : '/auth/login'
+}
+
+// 门禁中间件：放行 /auth/*；DATACLAW_AUTH_DISABLED=1 全放行；否则无有效 session → 302 /auth/login。
+export function authGate(req: Req, res: Res, next: Next) {
+  if (process.env.DATACLAW_AUTH_DISABLED === '1') return next()
+  const p = String(req.path || req.url || '')
+  if (p.includes('/auth/login') || p.includes('/auth/callback')) return next()
+  const sess = readSession(req.cookies?.[SESSION_COOKIE])
+  if (sess) return next()
+  return res.redirect(302, loginPath(req))
+}
+
+export function loginHandler(req: Req, res: Res) {
+  const authBase = process.env.TTC_AUTH_BASE || 'https://app.ttcadvisory.com'
+  const appBase = (process.env.APP_BASE_URL || '').replace(/\/+$/, '')
+  const state = makeState()
+  res.cookie(STATE_COOKIE, state, { httpOnly: true, sameSite: 'lax', secure: true, maxAge: 5 * 60 * 1000 })
+  const url = new URL('/auth/authorize', authBase)
+  url.searchParams.set('callback_url', `${appBase}/auth/callback`)
+  url.searchParams.set('state', state)
+  url.searchParams.set('auto', '1')
+  res.redirect(302, url.toString())
+}
+
+export async function callbackHandler(req: Req, res: Res) {
+  const token = String(req.query?.token || '')
+  const state = String(req.query?.state || '')
+  const cookieState = req.cookies?.[STATE_COOKIE]
+  // CSRF：回调 state 必须等于 cookie 里的、且签名有效未过期
+  if (!token || !state || state !== cookieState || !verifyState(state)) {
+    return res.status(401).send('登录校验失败，请重试')
+  }
+  try {
+    const apiBase = process.env.TTC_API_BASE || 'https://api.ttcadvisory.com'
+    const user = await fetchTtcUser(apiBase, token) // 只验身份；TTC token 验完即丢，不存不用于查数
+    res.clearCookie(STATE_COOKIE)
+    res.cookie(SESSION_COOKIE, makeSession(user.uniqueId, user.name), {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: true,
+      maxAge: 12 * 3600 * 1000,
+    })
+    return res.redirect(302, '/')
+  } catch {
+    return res.status(401).send('飞书身份校验失败')
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/auth/session.ts

@@ -0,0 +1,52 @@
+// HMAC 签名 session + oauth state cookie，用 SESSION_SECRET 签发/校验。
+// FC 多实例无共享内存，所以 state 也走签名 cookie，不能用进程内 Map。
+import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto'
+
+const SECRET = () => process.env.SESSION_SECRET || ''
+
+function sign(payload: string): string {
+  const mac = createHmac('sha256', SECRET()).update(payload).digest('base64url')
+  return `${Buffer.from(payload).toString('base64url')}.${mac}`
+}
+
+function verify(token: string): string | null {
+  const [b64, mac] = (token || '').split('.')
+  if (!b64 || !mac) return null
+  const payload = Buffer.from(b64, 'base64url').toString()
+  const expect = createHmac('sha256', SECRET()).update(payload).digest('base64url')
+  const a = Buffer.from(mac)
+  const b = Buffer.from(expect)
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return null
+  return payload
+}
+
+// session：存 {uid,name,exp}（仅展示/审计，不用于查数——数据范围恒用建页人 union_id）。
+export function makeSession(uid: string, name: string, ttlMs = 12 * 3600 * 1000): string {
+  return sign(JSON.stringify({ uid, name, exp: Date.now() + ttlMs }))
+}
+
+export function readSession(token?: string): { uid: string; name: string } | null {
+  const p = token && verify(token)
+  if (!p) return null
+  try {
+    const o = JSON.parse(p)
+    if (typeof o.exp === 'number' && o.exp > Date.now()) return { uid: o.uid, name: o.name }
+  } catch {}
+  return null
+}
+
+export function makeState(): string {
+  const nonce = randomBytes(16).toString('base64url')
+  return sign(JSON.stringify({ nonce, exp: Date.now() + 5 * 60 * 1000 }))
+}
+
+export function verifyState(token?: string): boolean {
+  const p = token && verify(token)
+  if (!p) return false
+  try {
+    const o = JSON.parse(p)
+    return typeof o.exp === 'number' && o.exp > Date.now()
+  } catch {
+    return false
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/auth/ttc-user-info.ts

@@ -0,0 +1,23 @@
+// 用 TTC JWT 调 user_info 验身份（无密钥经纪：app 不持飞书/TTC 密钥，只用回调 token 验身份）。
+// 精简自 daemon feishu-auth/ttc-client.ts，独立实现、不 import daemon 代码。
+// 接口响应结构：GET /api/user_service/v1/login/user → { code:0, data:{ unique_id, name, union_id, avatar_url } }
+export interface TtcUser {
+  uniqueId: string
+  name: string
+  unionId?: string
+  avatarUrl?: string
+}
+
+export async function fetchTtcUser(apiBase: string, token: string, fetchImpl: typeof fetch = fetch): Promise<TtcUser> {
+  const res = await fetchImpl(`${apiBase}/api/user_service/v1/login/user`, { headers: { Authorization: `Bearer ${token}` } })
+  if (!res.ok) throw new Error(`TTC user_info HTTP ${res.status}`)
+  const body = (await res.json()) as { code?: number; data?: { unique_id?: string; name?: string; union_id?: string; avatar_url?: string } }
+  if (body.code !== 0 || !body.data?.unique_id || !body.data?.name) throw new Error('TTC user_info invalid')
+  const d = body.data
+  return {
+    uniqueId: d.unique_id,
+    name: d.name,
+    ...(d.union_id ? { unionId: d.union_id } : {}),
+    ...(d.avatar_url ? { avatarUrl: d.avatar_url } : {}),
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/dataclaw/dataclaw.client.ts

@@ -0,0 +1,83 @@
+import { Injectable, HttpException, OnModuleInit } from '@nestjs/common'
+import { DataclawConfig, loadDataclawConfig } from './dataclaw.config'
+
+// 端点超时（架构文档 §8.10）：schema / flexible-query 走默认；intent-execute 可能跑 LLM 编排，给 90s。
+const TIMEOUT_MS = { default: 30_000, intent: 90_000 }
+
+@Injectable()
+export class DataclawClient implements OnModuleInit {
+  private cfg!: DataclawConfig
+
+  onModuleInit() {
+    this.cfg = loadDataclawConfig()
+  }
+
+  private async call<T>(
+    method: 'GET' | 'POST',
+    path: string,
+    opts: {
+      query?: Record<string, string | number | undefined>
+      body?: unknown
+      timeout?: number
+    } = {},
+  ): Promise<T> {
+    const url = new URL(this.cfg.baseUrl + path)
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+      if (v !== undefined && v !== '') url.searchParams.set(k, String(v))
+    }
+    const ctrl = new AbortController()
+    const t = setTimeout(() => ctrl.abort(), opts.timeout ?? TIMEOUT_MS.default)
+    try {
+      const res = await fetch(url, {
+        method,
+        signal: ctrl.signal,
+        headers: {
+          'Content-Type': 'application/json',
+          // 身份注入：数据范围按建页人 union_id 在 dataclaw 侧裁剪 + 服务间共享密钥校验。
+          'X-User-UnionId': this.cfg.asUnionId,
+          'X-Internal-Secret': this.cfg.internalSecret,
+        },
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+      })
+      const text = await res.text()
+      let json: any
+      try {
+        json = text ? JSON.parse(text) : {}
+      } catch {
+        throw new HttpException({ ok: false, error: `dataclaw 非 JSON 响应: ${text.slice(0, 200)}` }, 502)
+      }
+      if (!res.ok || json?.ok === false) {
+        // HTTP 非 2xx → 映射上游状态（5xx 归 502）；HTTP 2xx 但应用层 {ok:false} → 502
+        // （别把 200 当错误码抛——对前端是"成功码带错误体"的矛盾态）。
+        const status = res.ok ? 502 : res.status >= 500 ? 502 : res.status || 400
+        throw new HttpException(
+          { ok: false, error: json?.error || `dataclaw ${res.status}`, upstreamStatus: res.status },
+          status,
+        )
+      }
+      return json as T
+    } catch (err: any) {
+      if (err instanceof HttpException) throw err
+      if (err?.name === 'AbortError') throw new HttpException({ ok: false, error: 'dataclaw 请求超时' }, 504)
+      throw new HttpException({ ok: false, error: `dataclaw 连接失败: ${err?.message}` }, 502)
+    } finally {
+      clearTimeout(t)
+    }
+  }
+
+  getSchema(dataset?: string) {
+    return this.call<any>('GET', '/api/schema', { query: { dataset } })
+  }
+
+  flexibleQuery(body: unknown) {
+    return this.call<any>('POST', '/api/flexible-query', { body })
+  }
+
+  intentExecute(body: unknown) {
+    return this.call<any>('POST', '/api/intent-execute', { body, timeout: TIMEOUT_MS.intent })
+  }
+
+  consultants(keyword: string) {
+    return this.call<any>('GET', '/api/consultants', { query: { keyword } })
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/dataclaw/dataclaw.config.ts

@@ -0,0 +1,18 @@
+export interface DataclawConfig {
+  baseUrl: string
+  asUnionId: string
+  internalSecret: string
+}
+
+export function loadDataclawConfig(): DataclawConfig {
+  const baseUrl = (process.env.DATACLAW_SERVICE_URL || '').replace(/\/+$/, '')
+  const asUnionId = process.env.DATACLAW_AS_UNION_ID || ''
+  const internalSecret = process.env.DATACLAW_INTERNAL_SECRET || ''
+  const missing = [
+    !baseUrl && 'DATACLAW_SERVICE_URL',
+    !asUnionId && 'DATACLAW_AS_UNION_ID',
+    !internalSecret && 'DATACLAW_INTERNAL_SECRET',
+  ].filter(Boolean)
+  if (missing.length) throw new Error(`[dataclaw] 缺少必需 env: ${missing.join(', ')}`)
+  return { baseUrl, asUnionId, internalSecret }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/dataclaw/dataclaw.controller.ts

@@ -0,0 +1,30 @@
+import { Body, Controller, Get, Post, Query } from '@nestjs/common'
+import { DataclawClient } from './dataclaw.client'
+
+// app 自己的只读 BFF。main.ts 已 setGlobalPrefix（'api' 或子路径 'preview/<port>/api'），
+// 故这里的路径不带 /api。
+// 登录门禁由 main.ts 的 Express authGate 中间件统一覆盖（含 /api/*），不再用 Nest guard。
+@Controller()
+export class DataclawController {
+  constructor(private readonly dc: DataclawClient) {}
+
+  @Get('schema')
+  schema(@Query('dataset') dataset?: string) {
+    return this.dc.getSchema(dataset)
+  }
+
+  @Post('query')
+  query(@Body() body: unknown) {
+    return this.dc.flexibleQuery(body)
+  }
+
+  @Post('intent')
+  intent(@Body() body: unknown) {
+    return this.dc.intentExecute(body)
+  }
+
+  @Get('consultants')
+  consultants(@Query('keyword') keyword = '') {
+    return this.dc.consultants(keyword)
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/dataclaw/dataclaw.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common'
+import { DataclawClient } from './dataclaw.client'
+import { DataclawController } from './dataclaw.controller'
+
+@Module({
+  controllers: [DataclawController],
+  providers: [DataclawClient],
+})
+export class DataclawModule {}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/main.ts

@@ -0,0 +1,116 @@
+import './polyfill';
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { AppModule } from './app.module';
+import * as path from 'node:path';
+import cookieParser from 'cookie-parser';
+import { authGate, loginHandler, callbackHandler } from './auth/gate';
+
+// app-builder build 模式（spec 2026-06-01 + 2026-06-02 §5.6.4 子路径 fix）：
+//   - dev（通过 clawd 启）：nest 单进程 mount vite middleware，前端 HMR + /api 都从
+//     CLAWD_PREVIEW_PORT 出。所有 URL 走子路径 `/preview/<port>/`，含两层 prefix 处理：
+//       1. vite createServer 传 base=/preview/<port>/，让 vite middleware 识别带前缀的
+//          请求并剥前缀做内部路由 + HTML transform 时给 asset URL 加前缀
+//       2. nest setGlobalPrefix=preview/<port>/api，让 /preview/<port>/api/* 也被 nest 路由匹配
+//     不这样配，daemon preview-proxy 反代过来的请求（含 /preview/<port>/ 前缀）会被 nest 和 vite
+//     都不识别 → 全 404 / 'spa' 兜底返 HTML（API 接不通）
+//   - prod / 脱离 clawd：nest 起来时 express.static serve web/dist，base=/ globalPrefix=api
+//
+// CLAWD_PREVIEW_PORT 由 daemon supervisor 启动时注入；FC_SERVER_PORT / PORT 是 FC 部署 / 本地脱离 clawd 调试的回退。
+async function bootstrap() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
+
+  const isDev = process.env.NODE_ENV !== 'production';
+  const isClawdDev = !!process.env.CLAWD_PREVIEW_PORT;
+  const port =
+    Number(process.env.CLAWD_PREVIEW_PORT) ||
+    Number(process.env.FC_SERVER_PORT) ||
+    Number(process.env.PORT) ||
+    3000;
+
+  // 子路径 prefix：clawd dev 模式下挂 /preview/<port>/，其它（prod / 本地 vite 独跑）走根路径。
+  const subPath = isClawdDev ? `preview/${port}` : '';
+  const apiPrefix = subPath ? `${subPath}/api` : 'api';
+  const viteBase = subPath ? `/${subPath}/` : '/';
+
+  app.setGlobalPrefix(apiPrefix, { exclude: ['/'] });
+
+  // TTC 飞书登录门禁（PR-6）。前端 HTML 由 vite middleware(dev) / express.static(prod) serve、
+  // 不走 Nest 路由，Nest guard 拦不住，所以门禁是 Express 中间件，必须挂在下方 vite middleware
+  // (约:75) / useStaticAssets(约:99) 之前。/api/* 也先经过它（gate 在 vite 守卫和 nest router 之前）。
+  // /auth/login、/auth/callback 直接在 express 层注册，不带 globalPrefix；子路径部署带同样前缀。
+  // fail-loud：门禁启用却没配 SESSION_SECRET，会用空密钥签 cookie（可被伪造）—— 直接拒启动。
+  if (process.env.DATACLAW_AUTH_DISABLED !== '1' && !process.env.SESSION_SECRET) {
+    throw new Error('[auth] 缺 SESSION_SECRET：登录门禁启用时必填（否则 session cookie 可被伪造）。本地调试可设 DATACLAW_AUTH_DISABLED=1 跳过门禁。');
+  }
+  app.use(cookieParser());
+  const httpAdapter = app.getHttpAdapter();
+  const authBasePath = subPath ? `/${subPath}` : '';
+  httpAdapter.get(`${authBasePath}/auth/login`, loginHandler);
+  httpAdapter.get(`${authBasePath}/auth/callback`, callbackHandler);
+  app.use(authGate);
+
+  if (isDev && isClawdDev) {
+    // dev 模式 + 通过 clawd 启的 → mount vite middleware，root=../../web
+    const { createServer: createViteServer } = await import('vite');
+    const viteRoot = path.resolve(__dirname, '..', '..', 'web');
+    // vite 6+ 默认 server.allowedHosts: []（只放 localhost / .localhost / IP）防 DNS rebinding。
+    // frpc tunnel 转发过来的 Host header 是 daemon 当前 subdomain（CLAWD_TUNNEL_HOST 由
+    // daemon supervisor 注入），不在白名单 → vite middleware 直接拒（老板 tunnel URL 404 根因）。
+    // 显式把它加进 allowedHosts。
+    const tunnelHost = process.env.CLAWD_TUNNEL_HOST || '';
+    const allowedHosts = ['localhost', '127.0.0.1', ...(tunnelHost ? [tunnelHost] : [])];
+    const vite = await createViteServer({
+      root: viteRoot,
+      // **显式 inline base**：不依赖 web/vite.config.js 解析路径（middleware mode + ESM 配置
+      // 文件解析有时不可靠）。vite 据此识别带前缀的请求 + transformIndexHtml 注入带前缀的 asset URL。
+      base: viteBase,
+      server: {
+        middlewareMode: true,
+        // HMR WS 复用 nest 的 http.Server —— 跟 HTTP 共享同一个 fd / 同一个端口。
+        // 不设这个 vite 会 fallback standalone 用 24678，多 project 并发会撞。
+        hmr: { server: app.getHttpServer() },
+        allowedHosts,
+      },
+      // appType: 'spa' 让 vite middleware 自己 serve index.html + fallback 路由（base 下任何
+      // 非 vite asset 路径都返 index.html）。
+      appType: 'spa',
+    });
+    // /api/* 守卫：实测 vite 'spa' catch-all 会先吃掉 /api/* 返 HTML，导致 API 拿不到 JSON。
+    // Express middleware 栈顺序：vite.middlewares 这一行加进去时 nest controllers 还没挂
+    // （nest router init 在 app.listen 时），所以 vite 拦截优先于 nest router → 命中 /api 也走 vite。
+    // 守卫：req.url 命中 apiPrefix 时直接 next() 跳过 vite，让 nest router 接管返 JSON。
+    const apiPathPrefix = `/${apiPrefix}/`; // 如 '/preview/6173/api/' 或 '/api/'
+    app.use((req: any, res: any, next: any) => {
+      if (typeof req.url === 'string' && req.url.startsWith(apiPathPrefix)) {
+        return next(); // skip vite，让 nest router 处理 /api/*
+      }
+      return vite.middlewares(req, res, next);
+    });
+    console.log(`[clawd-dev] vite middleware mounted (root=${viteRoot}, base=${viteBase}, apiPrefix=${apiPrefix}, allowedHosts=${allowedHosts.join(',')})`);
+  } else {
+    // prod / 脱离 clawd 跑：直接 serve 前端静态资源。
+    //
+    // 路径解析两条路（覆盖 FC 部署与本地 monorepo 启动两种场景）：
+    //   1. FC（CODE_DIR=./server 只上传 server/，运行时 __dirname=dist/）
+    //      publish.sh BUILD_CMD 末尾会跑 `mkdir -p dist/public && cp -R ../web/dist/. dist/public/`
+    //      把前端打包产物塞进 dist/public，跟着 server 一起上传到 FC。所以 prod 优先用
+    //      __dirname/public 这条 FC 内可达的绝对路径。
+    //   2. 本地 monorepo `node dist/main.js`（极少用，但保留兼容）：__dirname/public 不存在
+    //      时 fallback 到 ../../web/dist（monorepo 相对路径）。
+    //
+    // 历史坑：spec 2026-06-03 前只有路径 2，FC 上 404 整个前端 —— 因为 ../../web/dist 在 FC
+    // 容器里压根不存在（CODE_DIR 只上传了 server/）。dev 时靠 vite middleware 走内存编译没暴露。
+    const fs = await import('node:fs');
+    const fcStaticDir = path.resolve(__dirname, 'public');
+    const monorepoStaticDir = path.resolve(__dirname, '..', '..', 'web', 'dist');
+    const staticDir = fs.existsSync(fcStaticDir) ? fcStaticDir : monorepoStaticDir;
+    app.useStaticAssets(staticDir);
+    console.log(`[prod] serving static from ${staticDir}`);
+  }
+
+  await app.listen(port, '0.0.0.0');
+  console.log(`server listening on :${port} (${isDev ? 'dev' : 'prod'}${isClawdDev ? ' / clawd' : ''})`);
+}
+
+bootstrap();

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/src/polyfill.ts

@@ -0,0 +1,6 @@
+// Dev 模式 .env loader：`nest start --watch` 不会经过 `node --env-file=.env`，
+// server 拿不到 DATACLAW_* env → loadDataclawConfig 会 fail-loud。
+// 这里在 nest bootstrap 之前显式 require dotenv 把 .env 填进 process.env。
+// prod 路径（node --env-file=.env dist/main.js）Node 自带 loader 已经填了，dotenv 看到
+// 已存在的 env 不会覆盖（默认行为），行为对齐。
+require('dotenv/config');

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/server/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2021",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "declaration": false
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "guestbook-web",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.4.0",
+    "vite": "^6.0.0"
+  }
+}

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/examples/nestjs-react/web/src/App.jsx

@@ -0,0 +1,9 @@
+import { useAuthGate } from './auth';
+import PerformanceQueryPage from './pages/PerformanceQueryPage';
+
+export default function App() {
+  const { ready, authed } = useAuthGate();
+  if (!ready) return <div>加载中…</div>;
+  if (!authed) return <div>请先飞书登录</div>;
+  return <PerformanceQueryPage />;
+}