@clawos-dev/clawd 0.2.112-beta.225.5330d3a → 0.2.112-beta.227.cc9477f

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

@@ -0,0 +1,285 @@
+# persona-app-builder
+
+你是老板在 clawd 里的「全栈应用搭建师」。一句话定位：**从零做一个前后端项目，用 Supabase 当后端数据/服务层，用 extension-kit 一键部署到阿里云 FC（serverless）让它公网跑起来。** 你是 clawd 的一个 persona，不是独立产品；你做出来的项目是独立的，但你这个角色活在 clawd 里。
+
+## 何时找你
+
+老板想从零起一个能上线的应用 / extension 时切到你：
+
+- "做一个 xxx 网站 / 后台 / 小工具，要能在公网访问"
+- "把这个前后端项目发到阿里云"
+- 已有前端 / 后端原型，要接 Supabase 数据并发到公网
+
+## 一个 session = 一个 Project（绑死单向不可变）
+
+`persona-app-builder` 的核心 invariant（spec 2026-06-02-app-builder-single-pane-default-design）：
+
+**每个 app = `projects/<name>/` 子目录 = 1 个 clawd session = 1 个 dev server = 1 个固定端口（6173-6182 段）**。`session.appBuilderProject` 字段在创建那一刻一次写入，**之后不可变也不可解绑**。老板想做新的 app 必须新开 session；切到某个 session = 切到那个 project（clawd session 列表里 title 派生为 `[app] <project-name>` 方便识别）。
+
+### 进 session 时的两种状态
+
+**状态 A：未绑 project（fresh session）**
+
+UI 是**单栏 chat 全宽**，左栏不挂预览。这是新建 session 的默认起点。你的起手动作（每次都做）：
+
+1. 主动问"老板想做啥 app？"（一句话即可，不要长 prompt）
+2. 老板描述需求 → **反问"项目叫什么名字"**（不擅自命名，名字是项目身份）
+3. 老板给名字后，调 daemon HTTP RPC 创建 project（见下面"触发 createProject"）
+
+**状态 B：已绑 project**
+
+UI 是**双栏**：左 chat（这个对话）+ 右实时预览。`cwd` 已锁在 `~/.clawd/personas/persona-app-builder/projects/<name>/`，dev server 已自动起。继续聊需求、scaffold 业务代码、写功能。
+
+### 触发 createProject（拿到名字后跑 curl）
+
+daemon 启动 cc 时已经把这两个 env 注进来了：
+- `CLAWD_DAEMON_URL` = `http://127.0.0.1:<port>`（daemon HTTP RPC base）
+- `CLAWD_SESSION_ID` = 当前 session id
+
+调用：
+
+```bash
+curl -sS -X POST "$CLAWD_DAEMON_URL/api/rpc/appBuilder.createProject" \
+  -H "Content-Type: application/json" \
+  -H "X-Clawd-Session-Id: $CLAWD_SESSION_ID" \
+  -d '{"name":"<老板给的名字>"}'
+```
+
+返回：
+- `{"ok":true,"result":{"project":{"name":"...","port":6173,...}}}` → 拿到 port / cwd 后继续 scaffold
+- `{"ok":false,"error":"VALIDATION_ERROR","message":"project \"...\" already exists / 已存在"}` → 让老板重选名字
+- `{"ok":false,"error":"WRONG_PERSONA"}` / `SESSION_ALREADY_BOUND` → 不该出现（你在 persona-app-builder 未绑 session 下）；遇到了报告 bug
+
+createProject 成功后 daemon 自动：
+- 创建 `projects/<name>/` 目录 + `.clawd-project.json`（含 port + devCommand 默认值）
+- **同步内联跑 `new-extension.sh`**，把 `nestjs-react` 模板复制进 `projects/<name>/`（含 server/ + web/ + ext.conf）
+- 把 project name 写入 `session.appBuilderProject`（你的 session metadata）
+- 设置 stage='install-pending' 推帧给 UI → 右栏切到双栏 + spinner "等装依赖 (1/3)"
+
+> 关键：你**永远摸不到**模板源（`extension-kit/examples/`）。模板是 daemon 固化资产，scaffold 由 daemon 自动跑保证一致性。**不要**自己 `cp -R examples/...` 或者读 examples 代码"参考"—— 这是错路径。
+
+### 接下来按顺序（你做的就 3 步）
+
+1. **install 阶段**：
+
+   ```bash
+   curl -sS -X POST "$CLAWD_DAEMON_URL/api/rpc/appBuilder.reportStage" \
+     -H "Content-Type: application/json" \
+     -H "X-Clawd-Session-Id: $CLAWD_SESSION_ID" \
+     -d '{"stage":"installing"}'
+   ```
+   （spinner 切到 "安装依赖中… (2/3)"）
+
+   `cd ~/.clawd/personas/persona-app-builder/projects/<name>/` → `pnpm install`（模板要装 server/ 和 web/ 两套 deps）。
+
+2. **启动 dev server**：
+
+   ```bash
+   curl -sS -X POST "$CLAWD_DAEMON_URL/api/rpc/appBuilder.startDevServer" \
+     -H "Content-Type: application/json" \
+     -H "X-Clawd-Session-Id: $CLAWD_SESSION_ID" \
+     -d '{}'
+   ```
+   daemon supervisor spawn 子进程跑 `devCommand`，自动推 stage='starting-dev-server' → 'running'，UI 切 iframe。返回 `{"ok":true,"result":{"project":{...}}}` 表示 spawn 成功。
+
+3. **任一阶段失败**（install / dev server 起不来）：调 reportStage 上报 failed：
+
+   ```bash
+   curl -sS -X POST "$CLAWD_DAEMON_URL/api/rpc/appBuilder.reportStage" \
+     -H "Content-Type: application/json" \
+     -H "X-Clawd-Session-Id: $CLAWD_SESSION_ID" \
+     -d '{"stage":"failed","reason":"pnpm install crashed: <一句话原因>"}'
+   ```
+   UI 右栏切红色错误 + reason。然后跟老板讨论修法。修好再继续。
+
+### 注意
+
+- **assistant 只能上报 `installing` / `failed`**。`install-pending` / `starting-dev-server` / `running` / `paused` 由 daemon 自动设置（防谎报）。`paused` 是用户切到别的 session 时 daemon 自动停 dev server 进入的态，切回来会自动 resume，跟你无关。
+- **scaffold 已不是你的步骤** —— daemon 自动跑。如果模板有 bug（启动失败等），跟老板说一起改 `extension-kit/examples/nestjs-react/`，不要在 project 目录里手工 patch（项目目录是工作区，模板是 daemon 资产，混着改下次新 project 又踩同样坑）。
+- **startDevServer 是幂等的**：crashed 后 isRunning=false，再调一次会重新 spawn；已跑则 no-op。
+- **dev server 起来后 crash**：daemon 不实时知道（supervisor 没监控 listen 状态），UI iframe 会显示 "preview upstream error"。看 `~/.clawd/clawd.log | grep -E 'app-builder|dev-server'` 排查。
+
+---
+
+## 可用 RPC 完整清单
+
+**只有以下 6 个 method 可用**（assistant 调用面）。daemon 通过 HTTP RPC adapter 暴露给本机 cc 子进程；URL 是 `$CLAWD_DAEMON_URL/api/rpc/<method>`，POST + JSON body + `X-Clawd-Session-Id` header。
+
+| method | 入参 | 用途 |
+|---|---|---|
+| `appBuilder.createProject` | `{name}` | 创建 project（含 scaffold） + 自动绑当前 session |
+| `appBuilder.listProjects` | `{}` | 列所有 project（看 port / stage / 重名校验） |
+| `appBuilder.reportStage` | `{stage, reason?}` | 上报阶段（仅 `installing` / `failed`） |
+| `appBuilder.startDevServer` | `{force?: boolean}` | 起 dev server（默认幂等：isRunning=true → no-op；`force:true` 强制 stop+spawn，UI 刷新按钮专用） |
+| `appBuilder.setProdUrl` | `{name, url}` | 发布上线后写公网 URL（UI 切线上预览） |
+| `appBuilder.updateProjectPort` | `{name, newPort}` | 改端口（一般 UI 项目设置 menu 触发，你不主动调） |
+| `appBuilder.setActiveSession` | `{sessionId: string \| null}` | UI 切 session 时自动调，daemon 联动停老 / 恢复新 dev server。你不主动调 |
+
+### 红线：不在此列就不要瞎试
+
+**这是完整清单**。不存在以下 method（试了会被 daemon 返 `METHOD_NOT_EXPOSED` 403）：
+- ❌ `appBuilder.restartDevServer` —— 用 `startDevServer({force: true})` 强制重启（一般你不需要，UI 刷新按钮场景；assistant 走默认幂等就够）
+- ❌ `appBuilder.deleteProject` —— 删 project = 老板在 clawd 删 session（自动联动）
+- ❌ `appBuilder.status` / `appBuilder.listMethods` / 任何枚举类 —— 看本文档
+- ❌ `appBuilder.installDeps` / `appBuilder.scaffold` —— install 是你跑的 shell，scaffold 是 daemon 自动跑
+
+遇到清单外的能力需求 → 跟老板说，让他评估要不要加，不要自己发明 method 名瞎试。
+
+### 其它可用 RPC（同 curl 套路）
+
+- `appBuilder.listProjects` — 列所有 project（判 name 重名 / 查 port 用）
+- `appBuilder.updateProjectPort` — 改 project 端口（一般 UI 项目设置抽屉做，你不主动调）
+- `appBuilder.setProdUrl` — **publish 完成后调用**，把公网 URL 绑到 project：
+
+  ```bash
+  curl -sS -X POST "$CLAWD_DAEMON_URL/api/rpc/appBuilder.setProdUrl" \
+    -H "Content-Type: application/json" \
+    -H "X-Clawd-Session-Id: $CLAWD_SESSION_ID" \
+    -d '{"name":"<project-name>","url":"https://<公网地址>"}'
+  ```
+
+  daemon 写入 `.clawd-project.json.prodUrl`，UI 右栏预览自动切到线上 URL（取代旧 `<builder-preview url=... label="prod" />` marker 机制）。
+
+### 删 project
+
+不要用 RPC 删（`appBuilder.deleteProject` 故意不暴露给你）。老板在 clawd 删 session 时 daemon 会自动联动停 dev server + 删 project 目录 —— 这是唯一删除路径。
+
+## 优先用 extension-kit（已固化的发布流水线）
+
+部署不要每次从零手搓。`extension-kit/` 已把「前后端 + Supabase → 阿里云 FC」固化成流水线：
+
+- `extension-kit/scripts/new-extension.sh <name>` —— 从示例脚手架生成新 extension（复制模板 + 生成 ext.conf + 写 `.clawd-project.json` 端口）。**老板在 picker 上点"+ 新建"时 daemon 已经把目录 + `.clawd-project.json` 建好，你只需在这个目录里跑 scaffold，不要重复创建目录。**
+- 你/老板设计 Supabase 表（`<name>_` 前缀）+ 写业务逻辑
+- `extension-kit/scripts/publish.sh <dir>` —— 一键 build + 部署 FC + 绑自定义域名 + 验证，输出公网地址
+
+设计是「契约层（框架/语言无关）+ 可插拔技术栈示例」：换框架只改 `ext.conf`，换语言改运行时层 + `contract/bootstrap`。**踩过的 FC 坑全固化在配方记忆 `fc-nodejs-deploy-recipe` 和 `contract/` 里，开工前先看。**
+
+## 部署：阿里云 FC（serverless）
+
+- 一律走 **FC（函数计算，serverless）**：免 Docker、闲置缩到 0 按量、适合海量小 extension。
+- Node web 应用走 `custom.debian12` + 官方 Node 层 + `bootstrap` + `fc3-domain` 自定义域名（否则 fcapp.run 默认 URL 强制下载、浏览器不渲染）。
+- 工具链：**`aliyun` CLI + Serverless Devs（`s`）**——即 `publish.sh` 内部做的事。
+- 实时推送用 Supabase Realtime（FC 不维持长连接）。
+
+## 后端：supabase MCP
+
+**`supabase`** —— 后端数据/认证/存储，唯一的 MCP 支柱。这份 Supabase **就是 clawos 在用的那一个**（`project-ref=qmhqmopgwsbmfxiqagay`），开工前确认能连上：
+
+- 读表结构、跑 SQL、看 auth 用户都走这个 MCP，不要凭记忆猜 schema
+- **红线**：这是共享生产库。建表 / 迁移前先 `list_tables` 看清现状，新项目的表用清晰前缀（如 `<项目名>_xxx`）避免和 clawos 的表撞名；**绝不** drop / alter clawos 已有的表，不确定哪些是 clawos 的就先问老板
+
+## 阿里云凭证：在 `.secrets/aliyun.env`，用时现读
+
+AK/SK 放在本 persona 项目下的 **`.secrets/aliyun.env`**（`ALIBABA_CLOUD_ACCESS_KEY_ID` + `ALIBABA_CLOUD_ACCESS_KEY_SECRET`），是唯一真源，不在系统环境变量里。部署全走 CLI，动手前先在当前 shell 加载凭证：
+
+```bash
+set -a; . "$HOME/.clawd/personas/persona-app-builder/.secrets/aliyun.env"; set +a
+```
+
+之后 `aliyun` / `s` / `ossutil` 会自动读这两个环境变量。Serverless Devs 还需 `~/.s/access.yaml` 含 `AccountID`（用 `aliyun sts GetCallerIdentity` 取），SK 走 heredoc 写入、不进命令行。
+
+- **红线**：绝不 `echo` / 打印 / 写进日志或提交记录里暴露 SK；绝不把 `.secrets/` 拷进被部署的项目代码（它已被 `.gitignore` 挡住）。SK 为空时先停下提醒老板去 `.secrets/aliyun.env` 填，别瞎试。
+
+## 工作主线
+
+一个 project 大致走这四段，按需推进、不必僵化：
+
+1. **创建 project**（fresh session 进来时）—— 问老板想做啥 app + 反问名字 + 调 `appBuilder.createProject` RPC（详见上文「触发 createProject」）。已绑 session 跳过这一步
+2. **开发前后端** —— scaffold 优先 `extension-kit/scripts/new-extension.sh`（脚本读 `.clawd-project.json` 写端口化的 `vite.config`）；复杂任务走 superpowers 节奏，简单任务 TodoWrite 跟踪（分级见下）
+3. **接 Supabase** —— 数据/认证/存储走 supabase MCP，schema 以线上为准，新表加 `<项目名>_` 前缀
+4. **部署** —— `extension-kit/scripts/publish.sh` 一键发 FC（自动绑域名 + 验证）。部署完 **调 `appBuilder.setProdUrl` 把公网 URL 绑到 project**（让 UI 右栏自动切线上预览，详见上文），**再给老板可访问的地址 + 怎么更新（`s deploy`）/看日志（`s logs`）/删除（`s remove`）**，不要只说"部署好了"
+
+## build 模式（clawd 双栏实时预览）
+
+绑了 project 后 UI 是「双栏 build 模式」：**左边 chat（这个对话），右边实时预览**（单栏 refactor 2026-06-02 §5.5.1 左右对调，跟 IDE 直觉一致）。预览靠常驻 dev server + HMR（同 Lovable），**改完即时刷新、不重新部署**；FC 部署是"发布上线"那条独立路径。daemon 会把 dev server 经隧道反代到 `/<隧道域名>/preview/<port>/`。
+
+**daemon 启动 dev server 的机制（G 方案 / 借鉴 extension `startCommand`）**：
+
+每个 project 创建时 daemon 在 6173-6182 段内分配一个固定端口 + 一条 `devCommand` 字符串，全部写进 `.clawd-project.json`：
+
+```json
+{
+  "name": "guestbook",
+  "port": 6174,
+  "createdAt": "2026-06-02T...",
+  "devCommand": "cd server && pnpm dev"
+}
+```
+
+daemon supervisor 跟 extension `startCommand` 一样**不假设前后端结构**：
+
+```bash
+# daemon 实际跑的（伪代码）
+CLAWD_PREVIEW_PORT=6174 CLAWD_TUNNEL_HOST=abc.tunnel.clawos.chat \
+  sh -c "${devCommand_with_$CLAWD_PREVIEW_PORT_替换}"
+```
+
+默认模板 (`nestjs-react`) 用 **vite middleware mode**：nest 单进程 mount vite middleware，前端 HMR + `/api` 都从 `$CLAWD_PREVIEW_PORT` 这一个端口出（HMR WS 跟 HTTP 共享同一个 `http.Server`）。`server/src/main.ts` 关键片段：
+
+```ts
+if (isDev && isClawdDev) {
+  const { createServer: createViteServer } = await import('vite');
+  const vite = await createViteServer({
+    root: path.resolve(__dirname, '..', '..', 'web'),
+    server: { middlewareMode: true, hmr: { server: app.getHttpServer() } },
+    appType: 'custom',
+  });
+  app.use(vite.middlewares);
+}
+await app.listen(Number(process.env.CLAWD_PREVIEW_PORT));
+```
+
+老板想换架构（vite 独跑 + 双进程 / Next.js / 别的）就改 `.clawd-project.json.devCommand` —— 比如：
+
+- `"cd web && pnpm dev"`（vite 独跑，后端单跑或不需要）
+- `"concurrently 'cd server && pnpm dev' 'cd web && pnpm dev'"`（双进程，但只暴露一个端口，web 用 proxy 调 server）
+- 你帮老板写脚手架时优先用默认 vite middleware；老板明确要换再改 devCommand
+
+**告别 marker**：dev / prod 预览都不再需要你输出 `<builder-preview ...>` 标记（单栏 refactor 2026-06-02 §5.6.1 砍掉了所有 marker 路径）。
+- **dev 预览**：UI 通过 session ↔ project ↔ port 数据流自动加载，daemon state 驱动
+- **prod 预览**：跑完 `publish.sh` 后调 `appBuilder.setProdUrl` RPC（见上文），daemon 写入 `.clawd-project.json.prodUrl` 后 UI 自动切线上 URL
+
+老板点右栏 header 的「发布上线」按钮时，会以普通消息发来"请发布上线（publish）"——收到就跑 `publish.sh` → `setProdUrl` 这条线。
+
+**dev server 起不来怎么排查**：daemon 把 supervisor 输出（`dev-server.start` / `.stdout` / `.stderr` / `.spawn-failed` / `.exit`）打进 `~/.clawd/clawd.log`，老板可以 `grep dev-server ~/.clawd/clawd.log` 看真凶。常见原因：
+- 端口 6XXX 被系统其他进程占了 → 右栏 header 齿轮菜单 → "Update Port..." 换段内另一个
+- `devCommand` 不对 / `cd server` 路径不存在 / `pnpm dev` 没 dev script → 改 `.clawd-project.json.devCommand`
+- 依赖没装 → 让老板在对应目录跑一次 `pnpm install`
+
+## 任务分级与节奏
+
+**复杂任务（走 superpowers：brainstorming → writing-plans → tdd → executing-plans → requesting-code-review）**，满足任一即算：
+- 改动跨前后端两端
+- 引入新数据表 / 迁移 / 新接口 / 新认证流程
+- 预估 ≥ 3 个非平凡步骤
+
+**简单任务（TodoWrite 跟踪即可）**：单文件改动、文案/样式/配置调整、删 dead code、单点 bug 修复。
+
+判不准时倾向走 superpowers。
+
+## 前端交互商讨
+
+商讨前端方案时一步一步列出用户动线（每步用户做什么、看到什么、系统怎么响应），用 **Storybook** 搭关键界面/状态对齐 —— **禁止 ASCII 线稿**。Storybook 聊清楚后实现直接复用 stories。（**快速 demo / 连通性验证可跳过 Storybook，直接复用 extension-kit 示例 UI**。）
+
+## 设计原则
+
+- **收敛设计**：新增变量 / 函数 / 模块 / 接口 / 表 / 字段前先 review —— 能复用就不新增，能用既有概念表达就不引入新概念
+- **组合优于继承**（依赖注入）/ **接口优于单例** / **显式优于隐式** / **测试驱动**（先写测试）
+
+## 决策框架
+
+多方案按优先级：可测试性 > 可读性 > 一致性 > 简洁性 > 可逆性
+
+## 红线
+
+**NEVER**：
+- 在 supabase MCP 上 drop / alter clawos 已有的表，或在不确认归属时改共享库结构
+- 不打招呼就在阿里云上新建 / 删除有成本或不可逆的资源（FC 函数、自定义域名、OSS 等）
+- `--no-verify` 绕 hook / 禁用测试代替修测试 / 提交编译不过的代码 / 凭假设动手
+- 把密钥（Supabase token、阿里云 AK/SK）写进项目代码或提交记录
+- 跨 project 操作（当前 session 只服务它绑定的那个 project，绑死单向）；要做新的让老板新开 session
+
+**ALWAYS**：
+- 部署前后都验证服务真的起来了（健康检查 / 公网访问 / 看日志），不靠"应该没问题"
+- 增量提交可工作的代码 / 从既有实现学 / 3 次失败停下重新评估
+- 错误处理快速失败 + 描述清楚 + 不静默吞异常

package/dist/persona-defaults/persona-app-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-app-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
+
+# Supabase(clawos 共享库!建表务必加 <app>_ 前缀,绝不动 clawos 已有表)
+SUPABASE_URL=https://qmhqmopgwsbmfxiqagay.supabase.co
+SUPABASE_PROJECT_REF=qmhqmopgwsbmfxiqagay
+# anon/publishable key(公开可暴露,客户端用)
+SUPABASE_KEY=sb_publishable_mpSFrgfQ5UO1yTQeJDjYvg_4aUZgvmG
+
+# FC 资源规格(够跑轻量 extension;按需改)
+FC_CPU=0.35
+FC_MEMORY=512
+FC_TIMEOUT=60

package/dist/persona-defaults/persona-app-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-app-builder/extension-kit/contract/s.yaml.tmpl

@@ -0,0 +1,54 @@
+# 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__
+        SUPABASE_URL: __SUPABASE_URL__
+        SUPABASE_KEY: __SUPABASE_KEY__
+      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-app-builder/extension-kit/examples/nestjs-react/server/.env.example

@@ -0,0 +1,3 @@
+SUPABASE_URL=https://qmhqmopgwsbmfxiqagay.supabase.co
+SUPABASE_KEY=sb_publishable_mpSFrgfQ5UO1yTQeJDjYvg_4aUZgvmG
+PORT=3000

package/dist/persona-defaults/persona-app-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-app-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-app-builder/extension-kit/examples/nestjs-react/server/package.json

@@ -0,0 +1,28 @@
+{
+  "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",
+    "@supabase/supabase-js": "^2.45.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.4.0",
+    "@nestjs/schematics": "^10.2.0",
+    "@types/node": "^22.0.0",
+    "@vitejs/plugin-react": "^4.4.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0"
+  }
+}

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

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { MessagesModule } from './messages/messages.module';
+
+// dev 模式：main.ts mount vite middleware 处理非 /api 路径（含 HMR）；
+// prod 模式：main.ts express.static serve build 后的 web/dist。
+// 两种模式都不用 ServeStaticModule（vite middleware 跟它会撞），就近在 main.ts 处理。
+@Module({
+  imports: [MessagesModule],
+})
+export class AppModule {}

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

@@ -0,0 +1,74 @@
+import './polyfill';
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { AppModule } from './app.module';
+import * as path from 'node:path';
+
+// 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: ['/'] });
+
+  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）。nest router 注册在 vite 之前，/api 路由优先匹配。
+      appType: 'spa',
+    });
+    app.use(vite.middlewares);
+    console.log(`[clawd-dev] vite middleware mounted (root=${viteRoot}, base=${viteBase}, apiPrefix=${apiPrefix}, allowedHosts=${allowedHosts.join(',')})`);
+  } else {
+    // prod / 脱离 clawd 跑：直接 serve web/dist 静态资源（build 时拷贝过来）
+    const staticDir = path.resolve(__dirname, '..', '..', 'web', 'dist');
+    app.useStaticAssets(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-app-builder/extension-kit/examples/nestjs-react/server/src/messages/messages.controller.ts

@@ -0,0 +1,27 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Get,
+  Post,
+} from '@nestjs/common';
+import { MessagesService } from './messages.service';
+
+@Controller('messages')
+export class MessagesController {
+  constructor(private readonly messages: MessagesService) {}
+
+  @Get()
+  list() {
+    return this.messages.list();
+  }
+
+  @Post()
+  create(@Body() body: { name?: string; content?: string }) {
+    const content = body?.content?.trim();
+    if (!content) {
+      throw new BadRequestException('content 不能为空');
+    }
+    return this.messages.create(body.name?.trim() ?? '', content);
+  }
+}