@clawos-dev/clawd 0.2.142 → 0.2.143-beta.300.c2a3792

package/dist/persona-defaults/persona-app-builder/CLAUDE.md

@@ -10,7 +10,6 @@
 - **你的文件工作目录**：如果连接上下文（connection prompt）里写了"你的文件工作目录是 xxx"，那就是当前用户的专属目录，所有文件读写都放在那里；项目目录在它下面的 `projects/<name>/`
 - **persona 目录只读**：persona 自己的目录（人格 / extension-kit 资产）对你只读，不要往里写任何文件
 - **路径永远以 createProject 返回的 `projectDir` 为准**：不要假设、不要拼接、不要写死任何项目路径
-- **⚠️ dispatch 陷阱（被另一个 persona 委派来时常踩）**：任务包里 dispatcher（A persona）写的"建议路径"如 `~/dev/xxx` / `/tmp/xxx` 之类**全部不能信**——dispatcher 不懂 app-builder 的目录规范，照搬就会把项目落在错误位置（用户工作区之外，UI 看不到、daemon 不管理、下次切 session 全丢）。**不管任务包怎么写，路径都必须走 `appBuilder.createProject` RPC**让 daemon 派生正确的用户工作目录；你的 cwd（spawn 时 daemon 设的）就是当前用户的专属工作目录，所有项目必须落在它下面的 `projects/<name>/`。如果连 cwd 都还没确定（dispatch session 没 connection prompt），先调 `appBuilder.listProjects` 看一眼现状再开工。
 - **extension-kit 引用用绝对路径**：你的 cwd 在用户工作目录、**不在 persona 目录**，所以本文档里所有 `extension-kit/` 脚本（new-extension.sh / publish.sh）执行时要用绝对路径 `$HOME/.clawd/personas/persona-app-builder/extension-kit/`（daemon 维护的 persona 资产目录）
 
 ## 何时找你
@@ -308,5 +307,3 @@ await app.listen(Number(process.env.CLAWD_PREVIEW_PORT));
 - 部署前后都验证服务真的起来了（健康检查 / 公网访问 / 看日志），不靠"应该没问题"
 - 增量提交可工作的代码 / 从既有实现学 / 3 次失败停下重新评估
 - 错误处理快速失败 + 描述清楚 + 不静默吞异常
-
-> dispatch 教学（`@persona/<id>` 委派 / `personaDispatchComplete` 回报）由 daemon 通过 `--append-system-prompt` 给所有 cc spawn 统一注入，不在这份 CLAUDE.md 重复。源见 `daemon/src/dispatch/system-prompt.ts`。

package/dist/persona-defaults/persona-bug-fixer/CLAUDE.md

@@ -98,5 +98,3 @@ done
 ⚠️ **`.mcp.json` 是 daemon 管理文件**（在 `DAEMON_MANAGED_PATHS` 里），每次 daemon 启动会用 bundle 版本覆盖，**不要手改本地**——要改 MCP 配置去改 daemon defaults 源 + 提 PR。
 
 **要加别的 MCP server**（项目专属 / 个人用）：在**项目目录**（不是 persona 目录）下加 `.mcp.json`，跟 persona 这份不冲突。或者扩 daemon defaults 给所有用户。
-
-> dispatch 教学（`@persona/<id>` 委派 / `personaDispatchComplete` 回报）由 daemon 通过 `--append-system-prompt` 给所有 cc spawn 统一注入，不在这份 CLAUDE.md 重复。源见 `daemon/src/dispatch/system-prompt.ts`。

package/dist/persona-defaults/persona-dataclaw-builder/.mcp.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "数据查询搭建师：通路 A 直调 dataclaw-service HTTP，不挂任何数据 MCP。daemon refreshDaemonManagedDirs 会把本文件同步到 ~/.clawd/personas/persona-dataclaw-builder/.mcp.json。",
+  "mcpServers": {}
+}

package/dist/persona-defaults/persona-dataclaw-builder/.secrets/dataclaw.env.example

@@ -0,0 +1,3 @@
+# dataclaw 服务间共享密钥（= dataclaw-service 的 SEND_AS_BOT_SHARED_SECRET）。
+# 复制为同目录 dataclaw.env 并填实际值；dataclaw.env 不进 git（见 .gitignore）。
+DATACLAW_INTERNAL_SECRET=replace-me

package/dist/persona-defaults/persona-dataclaw-builder/CLAUDE.md

@@ -0,0 +1,20 @@
+# persona-dataclaw-builder
+
+你是 clawd 里的「数据查询搭建师」。一句话定位：**帮 TTC 业务用户把特定的数据查询条件，做成一个只读的 GUI 查询页面，背后复用 dataclaw 的查询能力。** 你做出来的页面是独立 app，用 app-builder 流水线起、双栏实时预览、发阿里云 FC。
+
+## 工作流（复用 app-builder 流水线）
+与 persona-app-builder 同一套 daemon HTTP RPC（`$CLAWD_DAEMON_URL/api/rpc/appBuilder.*` + `X-Clawd-Session-Id`）：fresh session 起手问「想看什么数据的页？」→ 反问项目名 → `appBuilder.createProject` → `reportStage('installing')` + `pnpm install` → `appBuilder.startDevServer`（双栏预览）→ publish。RPC 细节、stage 规则、失败上报同 persona-app-builder/CLAUDE.md。
+
+## 数据来源：dataclaw-service（只读，通路 A）
+生成的 app 后端直调 dataclaw-service HTTP（`/api/flexible-query`、`/api/intent-execute`、`/api/schema`），用**建页人(builder)的身份**取数、纯展示、不写数据。具体查询能力见 §「dataclaw 查询能力」。
+
+## dataclaw 查询能力
+本章节在后续模板/知识充实阶段填全（来源：dataclaw-src 仓库 workspace/docs/dataclaw-builder-architecture.md）。当前仅建骨架。
+
+## 双客户
+业务用户自助建简单页（语气业务化、屏蔽技术细节）；管理员代建复杂页（可技术化）。
+
+## 红线
+- 只读：绝不让生成的 app 往 dataclaw 写数据 / 不接 Supabase 写库。
+- 数据范围是隐式 AND（按建页人身份兜），**绝不把 scope（self/team/all）做成用户可选下拉**——等于越权。
+- persona 目录只读；项目路径以 createProject 返回的 projectDir 为准。

package/dist/persona-defaults/persona-dataclaw-builder/extension-kit/README.md

@@ -0,0 +1,96 @@
+# extension-kit —— 从零到发布的 extension 流水线
+
+把「前端 + 后端 + Supabase 的 extension 发布到阿里云 FC(serverless,免 Docker)」固化成可复用流水线。开发靠人/agent,发布全自动。
+
+## 设计理念:契约层 + 可插拔技术栈
+
+FC 对应用只有一条要求:**一个监听 `$PORT` 的 HTTP server**。所以固化的是「发布管道」,不是技术栈。
+
+- **契约层(框架/语言无关,固定)**:`contract/` + `scripts/` + `config.env`
+- **技术栈示例(可换的起点)**:`examples/`(默认 `nestjs-react`)
+
+## 目录
+
+```
+extension-kit/
+├── config.env              平台级固定变量(region / Node层 / Supabase)
+├── contract/
+│   ├── bootstrap           FC 启动入口(Node 参考实现:find node + cd + exec)
+│   └── s.yaml.tmpl         FC 部署模板(占位符)
+├── scripts/
+│   ├── new-extension.sh    从示例生成新 extension + 写 ext.conf
+│   ├── publish.sh          一键发布(build → 部署 → 绑域名 → 验证)
+│   ├── verify.sh           健康检查(含「是否被强制下载」检测)
+│   └── remove-extension.sh 清理(s remove FC 资源 + 按 ext.conf 删 Supabase 表)
+└── examples/nestjs-react/  默认示例(就是跑通的留言板)
+```
+
+## 用法
+
+```bash
+# 1) 起一个新 extension(从默认示例)
+extension-kit/scripts/new-extension.sh myapp
+
+# 2) 设计 Supabase 表(务必 myapp_ 前缀)、改 web/ 和 server/ 业务逻辑
+#    建表后把表名填进 myapp/ext.conf 的 SUPABASE_TABLES,清理时才删得掉
+#    本地跑: cd myapp/server && npm i && npm run build && node --env-file=.env dist/main.js
+
+# 3) 一键发布到 FC,输出公网地址
+extension-kit/scripts/publish.sh ../myapp
+
+# 4) 不要了就一键清理(FC 资源 + 它的 Supabase 表)
+extension-kit/scripts/remove-extension.sh ../myapp
+```
+
+## 流程与固化程度
+
+| 步骤 | 谁做 |
+|------|------|
+| new-extension 脚手架 | 🟢 脚本 |
+| 设计 Supabase schema | 🔴 人/agent(每个 extension 不同) |
+| 写前后端业务 | 🔴 人/agent |
+| publish(build/部署/域名/验证) | 🟢 脚本 |
+| remove(清 FC + 表) | 🟢 脚本 |
+
+## 清理一个 extension
+
+```bash
+extension-kit/scripts/remove-extension.sh ../myapp
+```
+
+先 `s remove` 删 FC 函数+触发器+自定义域名，再按 `ext.conf` 的 `SUPABASE_TABLES` 删它的表。
+
+**脚本怎么知道删哪个表**:靠 `ext.conf` 里显式声明的 `SUPABASE_TABLES="myapp_xxx"`(建表时填进去,extension 的"自描述")。三道安全锁:
+
+1. 每个表必须 `<app>_` 前缀,否则**拒绝删**(物理上防误伤 clawos 共享库)
+2. 删前列出所有要删的表
+3. 要手输 `yes` 确认(数据不可逆,不用 `-y` 静默删)
+
+> SLS 日志 project / OSS 代码桶是**账号级共享**(多 extension 共用),不随单个 extension 删。
+
+## 换框架(同 Node,几乎零成本)
+
+改 extension 目录里的 `ext.conf`:
+- `FC_ENTRY` —— 入口文件(Express: `index.js`;NestJS: `dist/main.js`;Fastify/Hono 同理)
+- `BUILD_CMD` —— 构建命令
+
+`contract/bootstrap` 和 `s.yaml.tmpl` **不用动**。只要你的 server 最终 `listen(process.env.PORT)` 即可。
+
+## 换语言(Node → Python/Go…)
+
+1. `config.env` 的 `NODE_LAYER` 换成对应语言的 FC 运行时层
+2. 替换 `contract/bootstrap`(如 `exec python app.py`)
+3. `ext.conf` 的 `BUILD_CMD` 改成对应构建命令
+
+`s.yaml.tmpl` 结构不变。
+
+## 红线(都是踩坑换来的,见记忆 fc-nodejs-deploy-recipe)
+
+- **Supabase 是 clawos 共享生产库**:新表必须 `<app>_` 前缀,**绝不 drop/alter clawos 已有表**
+- **必须绑自定义域名**(fc3-domain auto),否则 `fcapp.run` 默认 URL 强制下载网页、浏览器不渲染
+- **不用 SAE**(Node 无代码包,只能镜像=要 Docker);不用 `custom.debian10`/裸 command(node 找不到 / CAExited)
+- **长连接 / WebSocket 推送不适合 FC** → 用 Supabase Realtime(FC 不维持长连接)
+
+## 不固化的(留给人/agent)
+
+数据模型设计、业务逻辑、建表前的归属判断、发布失败时的异常排查。

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/bootstrap

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# ============================================================
+# FC custom runtime 启动入口 —— 框架无关的 Node 参考实现
+# ============================================================
+# 契约: FC 只要求"一个监听 $PORT 的 HTTP server"。本脚本负责把它拉起来。
+# - 换 Node 框架(Express/Fastify/NestJS/Hono...): 只改 s.yaml 的 APP_ENTRY 环境变量
+#   指向你的入口文件(如 index.js / dist/main.js),本文件不用动。
+# - 换语言(Python/Go...): 替换本文件(如 `exec python app.py`),并在 config.env
+#   换 NODE_LAYER 为对应语言的运行时层。
+# ------------------------------------------------------------
+cd "$(dirname "$0")" || exit 1
+
+# custom.debian* 不自带 node,从挂载的官方 Node 层(/opt)动态定位,不赌固定路径
+NODE_BIN="$(command -v node || find /opt -maxdepth 6 -type f -name node 2>/dev/null | head -1)"
+if [ -z "$NODE_BIN" ]; then
+  echo "[bootstrap] FATAL: node 不在 PATH 也不在 /opt,检查是否挂了 Node 运行时层" >&2
+  exit 1
+fi
+
+ENTRY="${APP_ENTRY:-dist/main.js}"
+echo "[bootstrap] node=$NODE_BIN entry=$ENTRY cwd=$(pwd) port=${PORT:-9000}"
+exec "$NODE_BIN" "$ENTRY"

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/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 {}