weifuwu 0.86.0 → 0.87.0

package/README.md

@@ -1,6 +1,6 @@
 # weifuwu
 
-**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 118 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
+**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 129 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
 
 ```bash
 npm install weifuwu      # 一个依赖，完整应用栈
@@ -28,9 +28,9 @@ npm install weifuwu      # 一个依赖，完整应用栈
 | 层 | 入口 | 能力 |
 |----|------|------|
 | 后端 | `weifuwu` | Trie 路由 / 中间件链 / serve / 自研 PG+Redis / SSR / GraphQL / WebSocket |
-| 前端 | `weifuwu/ui-dom` | **vdom3 精准事件流引擎**——createRouter（路由）+ createRoot（挂载）+ 事件流（渲染本体：`entity:action` 统一命名、DOM = fold、可回放可断言）+ SSR（事件流序列化）；组件=两阶段异步组件 / ctx.params 对齐后端；**weifuwu/components 直接复用**（VNode 契约唯一来源 ui-dom，见 `docs/frontend-ui-dom.md`） |
-| 组件 | `weifuwu/components` | 118 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
-| 样式 | `weifuwu/layout` | 66 布局原语 + 156 工具类 + 177 主题 Token，零自定义 CSS 文件 |
+| 前端 | `weifuwu/ui-dom` | **vdom3 精准事件流引擎**——createRouter（路由）+ createRoot（挂载）+ 事件流（渲染本体：`entity:action` 统一命名、DOM = fold、可回放可断言）+ SSR（事件流序列化）；组件=两阶段异步组件 / ctx.params 对齐后端；**weifuwu/components 直接复用**（VNode 契约唯一来源 ui-dom，见 `content/guides/ui-dom-guide.md`） |
+| 组件 | `weifuwu/components` | 129 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
+| 样式 | `weifuwu/layout` | 66 布局原语 + 157 工具类 + 182 主题 Token，零自定义 CSS 文件 |
 | SaaS 地基 | 随包内置 | rateLimit / email / userSystem / messager / queue / ai → `ctx.*` 一行接入 |
 
 > ⚠️ **注意：前后端都有 `ctx.ui`，但用途完全不同**
@@ -96,7 +96,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **两阶段组件模型** — 组件 = `async (initProps, ctx) => (props) => Promise<VNode>`。外层工厂只执行一次（mount，可 await 数据），内层 renderFn 每次状态/props 变化时执行（强制异步）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
 
-**render-only 确定性渲染** — 渲染唯一触发 `ctx.ui.render()`（闭包绑定组件），状态是普通对象（`let` + `render()`）；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。行为可静态推导，无隐式触发（详见[组件库](docs/components.md)）。
+**render-only 确定性渲染** — 渲染唯一触发 `ctx.ui.render()`（闭包绑定组件），状态是普通对象（`let` + `render()`）；跨组件共享用 `createStore` + `ctx.ui.useExternal()`。行为可静态推导，无隐式触发（详见[组件库](content/guides/components-guide.md)）。
 
 **VDOM 输出透明（写 JSX，看 DOM 即真相）** — VDOM 对用户输入零 magic：条件渲染的 false 在 DOM 里是诊断占位注释（`<!--wf-hole: false-->`），数组项 key 与组件实例 id 直接落 DOM（`data-wf-key` / `data-wf-id`）——devtools 看到的 DOM 就是引擎决策的可读输出；非法输入占位 + warn，不崩溃不静默。转化契约唯一清晰：用户写什么，vnode 就是什么，DOM 就长什么样（规则表为内部开发契约）。
 
@@ -108,15 +108,15 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **AI 是一等公民** — 自研 OpenAI 兼容协议（`docs/ai-contract.md`）+ 零依赖流式客户端 + agent 工具循环 + HITL 人工审批 + embedding 向量化。后端 `ctx.ai` 一个入口：`chat()` / `stream()` / `agent()`（`stream(messages, { emit })` emitter 抽象——事件可接任意通道，`runToResult()` 结构化结果）/ `approve()` / `embed()` / `embedMany()`；前端 `ctx.ui.useChat()`（会话语义）+ `AiChat` 组件（标准对话界面）——流式 token / 工具调用卡 / 审批卡开箱即用，协议对页面完全透明，不用 ai-sdk。
 
-**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见[SaaS 地基模块](docs/saas.md)）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
+**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ messager（消息系统）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见[SaaS 地基模块](content/guides/saas-guide.md)）。互相咬合成协作基础：身份（userSystem）+ 消息（messager）的组合让「谁能跟谁说话、消息如何送达」天然对齐，不再需要第三套权限系统。
 
 **机制与策略分离** — 框架管**机制**（token 怎么签、消息怎么送达、agent 循环怎么跑），开发者管**策略**（谁能建群、租户隔离 SQL、技能注册表）。这是「诚实裁剪」的积极面：**框架不越界，应用层不被绑架**——agent-platform 迁移验证了边界：多租户隔离（`WHERE tenant_id`）、技能编排、聊天产品模型留在应用层，框架守住通用能力（auth / ai / messager / UI / 数据管道）。
 
-**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，主题改一个值（`--wf-brand-seed` 换肤 / `data-preset` 预设 / `--wf-btn-radius` 钩子），暗色自动（详见[布局系统](docs/layout.md)与[主题配置](docs/styling.md)）。
+**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，主题改一个值（`--wf-brand-seed` 换肤 / `data-preset` 预设 / `--wf-btn-radius` 钩子），暗色自动（详见[布局系统](content/guides/layout-guide.md)与[主题配置](content/guides/styling.md)）。
 
 **自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
 
-> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（118 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
+> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（129 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
 
 ---
 
@@ -232,9 +232,9 @@ createRouter(routes, root)                                  // 之后正常交
 ### 30 秒体验（跑现有 demo）
 
 ```bash
-# ① 组件 cheatsheet——118 组件全部可交互预览（零依赖，5 秒起）
-cd apps/components-demo && node server.ts
-# 打开 http://localhost:3000
+# ① showcase——weifuwu 发展引擎：组件/页面/应用/后端/能力/指南 一站式（活体 demo + 文档同源）
+cd apps/showcase && node server.ts
+# 打开 http://localhost:3200（LLM: curl /llms.txt）
 
 # ② 全栈 SaaS 示例——多租户 AI 平台（auth / AI 对话 / 部门聊天 / 知识库 / HITL 审批）
 docker compose up -d postgres redis   # 仓库根目录
@@ -244,6 +244,15 @@ cd apps/agent-platform && npm run seed && npm run dev
 
 > 想**零后端、零构建**最快跑起来？直接跳到下面的「CDN 快速原型」——一个 `.html` 文件即可。
 
+### 📦 安装后离线文档（content/ 随包发布）
+
+```bash
+npm i weifuwu
+npx weifuwu docs    # → http://localhost:4000 本地文档站（组件 API 表/纪律/示例/验证）
+```
+
+`node_modules/weifuwu/content/` 是完整文档库（逐组件文档 + 页面/应用模板 + 后端能力 + 指南 + 选型决策树 + 人类质量标准）——版本永远匹配安装的代码；`examples/` 是可复制源码（页面模式 + 应用模板 todo/auth/admin/multi）。LLM 开发路径：`read node_modules/weifuwu/content/index.md` → 目标 .md → 复制 examples/ 源码。
+
 ---
 
 ## CDN 快速原型（零构建、纯 HTML）
@@ -321,8 +330,8 @@ cd apps/agent-platform && npm run seed && npm run dev
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
 | `weifuwu/ui-dom` | `https://unpkg.com/weifuwu@latest/dist/ui-dom/index.js` | 前端运行时（createRouter, createRoot, h, 事件流, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 118 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 177 个主题 Token + 66 个布局原语 + 156 个工具类 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 129 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 182 个主题 Token + 66 个布局原语 + 157 个工具类 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
 
@@ -363,9 +372,9 @@ cd apps/agent-platform && npm run seed && npm run dev
 | `weifuwu/ui-dom` | **i18n** | 国际化中间件（运行时切换语言） | — |
 | `weifuwu/ui-dom` | **renderToEvents / eventsToHtml / serializeEvents** | 服务端渲染：vnode → 事件流 → HTML + `__DATA__` 序列化（客户端 `replay` 收养） | — |
 | `weifuwu/ui-dom` | **useChat / AiChat 原语** | AI 会话（流式/工具调用/HITL） | — |
-| `weifuwu/ui-dom` | **事件原语** | `usePopup`（统一弹窗能力层）/ `usePresence` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag` / `useDragDrop` / `useAnimationEnd` / `useTween` / `useReducedMotion`（浏览器事件/动画统一入口，见 [docs/mobile.md](docs/mobile.md)） | — |
-| `weifuwu/components` | **113 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/ui-dom |
-| `weifuwu/layout` | **CSS 布局** | 66 个布局原语 + 156 个工具类 + 177 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/ui-dom` | **事件原语** | `usePopup`（统一弹窗能力层）/ `usePresence` / `useInView` / `useScrollPosition` / `useGlobalKey` / `useDrag` / `useDragDrop` / `useAnimationEnd` / `useTween` / `useReducedMotion`（浏览器事件/动画统一入口，见 [content/guides/mobile-guide.md](content/guides/mobile-guide.md)） | — |
+| `weifuwu/components` | **129 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/ui-dom |
+| `weifuwu/layout` | **CSS 布局** | 66 个布局原语 + 157 个工具类 + 182 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -375,23 +384,23 @@ cd apps/agent-platform && npm run seed && npm run dev
 
 | 任务 | 用 | 位置 |
 |------|-----|------|
-| 起 HTTP 服务 + 路由 | `serve(app)` + `new Router()` + `app.get/post/...` | [docs/server.md](docs/server.md) |
-| 渲染页面（SPA / SSR） | `createRouter(routes, root, { ctx })`；SSR = `renderToEvents` → `eventsToHtml` + `replay`（事件流形态） | [docs/frontend-ui-dom.md](docs/frontend-ui-dom.md) · [docs/frontend.md](docs/frontend.md) |
-| 数据持久化 | `postgres()` → `` ctx.sql`SELECT *` `` · `redis()` → `ctx.redis` · **`sql.query`**（Query Language AST 双后端） | [docs/data.md](docs/data.md) |
-| 零数据库开发/测试 | `createMemorySql()` / `MemoryRedis`——契约同真库、替换成本为零 | [docs/data.md](docs/data.md) |
-| 数据管道（SSR 预取/hydration/SPA） | `ctx.data.get(key)` + async 组件 | [docs/frontend.md](docs/frontend.md) |
-| 用户注册/登录/会话/多租户 | `userSystem()` → `ctx.auth` + `/api/auth/*` | [docs/saas.md](docs/saas.md) |
-| 限流防爆破 | `rateLimit()` + `ctx.limit()` | [docs/saas.md](docs/saas.md) |
-| 发邮件 | `email()` → `ctx.email`（Resend/SMTP） | [docs/saas.md](docs/saas.md) |
-| 实时消息/聊天/通知 | `messager()` → `ctx.msg` + `app.ws` | [docs/saas.md](docs/saas.md) |
-| 后台任务/定时 | `queue()` → `ctx.queue` · `scheduler()` → `ctx.schedule/cron` | [docs/saas.md](docs/saas.md) |
-| AI 对话 / Agent / HITL 审批 | `ai()` → `ctx.ai` + `ctx.ui.useChat()` + `AiChat` | [docs/saas.md](docs/saas.md) |
-| GraphQL / WebSocket | `app.graphql(handler)` · `app.ws(path, handler)` | [docs/realtime.md](docs/realtime.md) |
-| 前端 UI 组件 | `weifuwu/components`（113 个：Button/Table/Modal/AiChat/...） | [docs/components.md](docs/components.md) |
-| 布局/主题/暗色 | `weifuwu/layout`（58 原语 + 156 工具类 + 177 Token） | [docs/layout.md](docs/layout.md) |
-| 样式定制（零自定义 CSS） | `--wf-*` 变量覆盖 + 组件定制钩子 | [docs/styling.md](docs/styling.md) |
-| 移动端适配（tap/长按/键盘/弹层） | `usePopup` / `useHoverCapable` / `useLongPress` / `useVisualViewport` | [docs/mobile.md](docs/mobile.md) |
-| 前后端类型安全中间件 | `createMiddleware`（声明注入即类型化） | [docs/server.md](docs/server.md) |
+| 起 HTTP 服务 + 路由 | `serve(app)` + `new Router()` + `app.get/post/...` | [content/guides/server-guide.md](content/guides/server-guide.md) |
+| 渲染页面（SPA / SSR） | `createRouter(routes, root, { ctx })`；SSR = `renderToEvents` → `eventsToHtml` + `replay`（事件流形态） | [content/guides/ui-dom-guide.md](content/guides/ui-dom-guide.md) · [content/guides/frontend.md](content/guides/frontend.md) |
+| 数据持久化 | `postgres()` → `` ctx.sql`SELECT *` `` · `redis()` → `ctx.redis` · **`sql.query`**（Query Language AST 双后端） | [content/guides/data-guide.md](content/guides/data-guide.md) |
+| 零数据库开发/测试 | `createMemorySql()` / `MemoryRedis`——契约同真库、替换成本为零 | [content/guides/data-guide.md](content/guides/data-guide.md) |
+| 数据管道（SSR 预取/hydration/SPA） | `ctx.data.get(key)` + async 组件 | [content/guides/frontend.md](content/guides/frontend.md) |
+| 用户注册/登录/会话/多租户 | `userSystem()` → `ctx.auth` + `/api/auth/*` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
+| 限流防爆破 | `rateLimit()` + `ctx.limit()` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
+| 发邮件 | `email()` → `ctx.email`（Resend/SMTP） | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
+| 实时消息/聊天/通知 | `messager()` → `ctx.msg` + `app.ws` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
+| 后台任务/定时 | `queue()` → `ctx.queue` · `scheduler()` → `ctx.schedule/cron` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
+| AI 对话 / Agent / HITL 审批 | `ai()` → `ctx.ai` + `ctx.ui.useChat()` + `AiChat` | [content/guides/saas-guide.md](content/guides/saas-guide.md) |
+| GraphQL / WebSocket | `app.graphql(handler)` · `app.ws(path, handler)` | [content/guides/realtime-guide.md](content/guides/realtime-guide.md) |
+| 前端 UI 组件 | `weifuwu/components`（129 个：Button/Table/Modal/AiChat/...） | [content/guides/components-guide.md](content/guides/components-guide.md) |
+| 布局/主题/暗色 | `weifuwu/layout`（58 原语 + 157 工具类 + 182 Token） | [content/guides/layout-guide.md](content/guides/layout-guide.md) |
+| 样式定制（零自定义 CSS） | `--wf-*` 变量覆盖 + 组件定制钩子 | [content/guides/styling.md](content/guides/styling.md) |
+| 移动端适配（tap/长按/键盘/弹层） | `usePopup` / `useHoverCapable` / `useLongPress` / `useVisualViewport` | [content/guides/mobile-guide.md](content/guides/mobile-guide.md) |
+| 前后端类型安全中间件 | `createMiddleware`（声明注入即类型化） | [content/guides/server-guide.md](content/guides/server-guide.md) |
 
 ---
 
@@ -505,23 +514,23 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 
 | 文档 | 内容 |
 |------|------|
-| [docs/server.md](docs/server.md) | HTTP 服务层：Router / serve / cors / serveStatic / HttpError / 响应辅助 / parseBody |
-| [docs/data.md](docs/data.md) | 数据层：postgres（PG v3 自研协议）/ redis（RESP2 自研协议）/ Query Language（AST 双后端）/ Memory 实现（零数据库）/ 测试零外部依赖 |
-| [docs/realtime.md](docs/realtime.md) | 实时与渲染：scheduler / ui（SSR + JS/CSS 编译）/ graphql / WebSocket |
-| [docs/saas.md](docs/saas.md) | SaaS 地基：rateLimit / email / userSystem / messager / queue / ai |
+| [content/guides/server-guide.md](content/guides/server-guide.md) | HTTP 服务层：Router / serve / cors / serveStatic / HttpError / 响应辅助 / parseBody |
+| [content/guides/data-guide.md](content/guides/data-guide.md) | 数据层：postgres（PG v3 自研协议）/ redis（RESP2 自研协议）/ Query Language（AST 双后端）/ Memory 实现（零数据库）/ 测试零外部依赖 |
+| [content/guides/realtime-guide.md](content/guides/realtime-guide.md) | 实时与渲染：scheduler / ui（SSR + JS/CSS 编译）/ graphql / WebSocket |
+| [content/guides/saas-guide.md](content/guides/saas-guide.md) | SaaS 地基：rateLimit / email / userSystem / messager / queue / ai |
 | [docs/ai-contract.md](docs/ai-contract.md) | AI Stream Protocol：wf: 事件（SSE 下行 + POST 上行）——流式/工具/审批 |
 
 ### 前端开发者
 
 | 文档 | 内容 |
 |------|------|
-| [docs/frontend.md](docs/frontend.md) | 前端核心：应用引导（createRouter/createRoot——vdom3 事件流）/ 组件模型 / 异步组件 / 状态管理 / 条件与列表 / ref / 类型（weifuwu/client 已并入 ui-dom） |
-| [docs/frontend-ui-dom.md](docs/frontend-ui-dom.md) | **ui-dom**：vdom3 精准事件流引擎（createRouter/createRoot + 事件流）——components 复用 + SSR（事件流形态）（前端唯一运行时） |
-| [docs/frontend-middleware.md](docs/frontend-middleware.md) | 前端中间件：router / api / auth / ws / i18n / ErrorBoundary / confirm / toast / ScrollLock / extendCtx |
-| [docs/components.md](docs/components.md) | 组件库（113 个组件 + 使用示例 + 组件列表） |
-| [docs/layout.md](docs/layout.md) | 布局系统：66 个布局原语 + 156 个工具类 + 177 个主题 Token |
+| [content/guides/frontend.md](content/guides/frontend.md) | 前端核心：应用引导（createRouter/createRoot——vdom3 事件流）/ 组件模型 / 异步组件 / 状态管理 / 条件与列表 / ref / 类型（weifuwu/client 已并入 ui-dom） |
+| [content/guides/ui-dom-guide.md](content/guides/ui-dom-guide.md) | **ui-dom**：vdom3 精准事件流引擎（createRouter/createRoot + 事件流）——components 复用 + SSR（事件流形态）（前端唯一运行时） |
+| [content/guides/middleware.md](content/guides/middleware.md) | 前端中间件：router / api / auth / ws / i18n / ErrorBoundary / confirm / toast / ScrollLock / extendCtx |
+| [content/guides/components-guide.md](content/guides/components-guide.md) | 组件库（129 个组件 + 使用示例 + 组件列表） |
+| [content/guides/layout-guide.md](content/guides/layout-guide.md) | 布局系统：66 个布局原语 + 157 个工具类 + 182 个主题 Token |
 | [docs/style-guide.md](docs/style-guide.md) | 样式学习路径与命名规范：三档学习（组件 → 原语 → 速查）|
-| [docs/styling.md](docs/styling.md) | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
+| [content/guides/styling.md](content/guides/styling.md) | 样式定制指南：零自定义 CSS 模式 / 暗色 / 组件级覆盖 / 作用域主题 |
 
 ### 通用
 
@@ -529,8 +538,10 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 |------|------|
 | [docs/examples.md](docs/examples.md) | 组合场景示例：登录表单 / 数据列表 + 搜索 / 消息提示 |
 | [docs/environment.md](docs/environment.md) | 环境变量与开发命令 |
-| [docs/mobile.md](docs/mobile.md) | 移动端开发指南：断点 / 44px 命中区 / usePopup / 手势 / safe-area |
+| [content/guides/mobile-guide.md](content/guides/mobile-guide.md) | 移动端开发指南：断点 / 44px 命中区 / usePopup / 手势 / safe-area |
 | [docs/components-map.md](docs/components-map.md) | 组件速查：weifuwu ↔ antd / Element Plus / shadcn 对应 + 迁移路径 |
-| [docs/custom-components.md](docs/custom-components.md) | 自定义组件开发指南：usePopup / useControlled / 动画 / AI 组件 / 类型纪律 |
+| [content/guides/custom-component.md](content/guides/custom-component.md) | 自定义组件开发指南：usePopup / useControlled / 动画 / AI 组件 / 类型纪律 |
 
+> **贡献**：见 [CONTRIBUTING.md](CONTRIBUTING.md)——四条路径（文档/测试/demo/组件）+ 质量防线。
+>
 > `docs/` 用户文档随 npm 包发布（`files: ['dist/', 'README.md', 'docs/']`）——`node_modules/weifuwu/docs` 可离线查阅。

package/content/apps/admin.md

@@ -0,0 +1,55 @@
+# 管理后台 · apps
+
+## 概述
+
+AppShell + Dashboard/Table/Form 多页——layout 包裹复用 + 主题。后端：rateLimit + 查询端点。源于 agent-platform 架构提炼。
+
+
+## 用到的页面模式
+- [app-shell](../patterns/app-shell.md)
+
+## 用到的组件
+- [Layout](../components/layout.md)
+- [Menu](../components/menu.md)
+- [NavMenu](../components/navmenu.md)
+- [Table](../components/table.md)
+- [Form](../components/form.md)
+- [ThemeSwitch](../components/themeswitch.md)
+- [StatCard](../components/statcard.md)
+- [Chart](../components/chart.md)
+- [Badge](../components/badge.md)
+- [Avatar](../components/avatar.md)
+- [Tag](../components/tag.md)
+
+## 源码
+
+> `examples/apps/admin/` ——完整可运行（随 npm 包发布）
+
+## 目录结构
+
+| 文件 | 职责 |
+|------|------|
+| `app.tsx` | 前端：AppShell（Layout 骨架 + Menu）+ DashboardPage/OrdersPage + 路由 layout 包裹 |
+| `api.ts` | 后端：registerAdminApi——订单查询 + 种子数据 |
+| `server.ts` | 独立入口（:3302） |
+| `main.tsx` | 独立前端入口 |
+
+## 改造指南（新手从跑起来到改成自己的）
+
+- 1. 换业务数据：api.ts 的 admin_orders 表 + 种子数据 → 自己的业务表（或接真实 postgres）
+- 2. 加页面：app.tsx 路由表加 { path, render, layout: AppShell }——侧栏 Menu items 同步加
+- 3. 改菜单/品牌：AppShell 里 Menu items + 标题文案
+- 4. 表格交互：Table 组件文档（sortable/rowSelection——受控 props 配回调）
+- 5. 参考生产级：apps/agent-platform/（多租户/权限/商业化真实架构）
+
+## 质量标准
+
+- [x] 键盘可达
+- [x] 侧栏折叠
+- [x] 表格排序
+- [x] 亮暗主题
+- [x] loading/empty 态
+
+## 验证
+
+> agent-browser 走查：打开 showcase `/apps/admin`（活体嵌入）——列表/新建/保存/删除全流程 + 控制台零错误

package/content/apps/agent-platform.md

@@ -0,0 +1,35 @@
+# agent-platform（生产级） · apps（生产级）
+
+## 概述
+
+多租户 AI Agent 平台——weifuwu 中间件全量消费方（认证/AI/沙箱/工具链/商业化/私有化）。实战驱动框架开发的生产级参考。
+
+> **生产级参考**：目录独立于 showcase（apps/agent-platform/），此处为展示层纳入——架构文档 + 源码索引 + 启动方式。
+## 用到的页面模式
+- （无）
+
+## 用到的组件
+- [AiChat](../components/aichat.md)
+- [AuthPage](../components/authpage.md)
+- [Table](../components/table.md)
+- [Form](../components/form.md)
+- [Modal](../components/modal.md)
+- [Drawer](../components/drawer.md)
+- [Menu](../components/menu.md)
+- [StatCard](../components/statcard.md)
+- [ThemeSwitch](../components/themeswitch.md)
+
+## 源码
+
+> 源码见 `apps/agent-platform/`（独立仓库结构——不随包）
+
+## 质量标准
+
+- [x] 真实产品
+- [x] 多租户
+- [x] 私有化部署
+- [x] 商业化闭环
+
+## 验证
+
+> 独立部署验证（docker + 真实库）——见 apps/agent-platform/README.md

package/content/apps/auth.md

@@ -0,0 +1,49 @@
+# 登录注册 · apps
+
+## 概述
+
+登录/注册 → 受保护页 → 登出：应用级状态（user store）+ 路由守卫 + ctx.data。后端：认证中间件。
+
+
+## 用到的页面模式
+- （无）
+
+## 用到的组件
+- [Card](../components/card.md)
+- [Form](../components/form.md)
+- [Input](../components/input.md)
+- [PasswordInput](../components/passwordinput.md)
+- [Button](../components/button.md)
+- [Alert](../components/alert.md)
+
+## 源码
+
+> `examples/apps/auth/` ——完整可运行（随 npm 包发布）
+
+## 目录结构
+
+| 文件 | 职责 |
+|------|------|
+| `app.tsx` | 前端：AuthFormPage（登录/注册两用）+ 路由守卫 + authStore |
+| `api.ts` | 后端：registerAuthApi——内存用户表 + token 会话 |
+| `server.ts` | 独立入口（:3301） |
+| `main.tsx` | 独立前端入口 |
+
+## 改造指南（新手从跑起来到改成自己的）
+
+- 1. 换用户存储：api.ts 的 auth_users 表 → 接 userSystem 中间件（见 content/backend/auth.md）
+- 2. 加受保护页：app.tsx 路由表加页面 + 组件内读 authStore.state.user 做守卫（同 DashboardPage 模式）
+- 3. 改会话持久化：app.tsx 的 ctx.browser.storageSet 已处理——key 名 auth:token 可改
+- 4. 加角色权限：守卫处加角色判断（user 表加 role 字段）
+
+## 质量标准
+
+- [x] 键盘可达
+- [x] 表单校验
+- [x] 错误态
+- [x] 会话持久化
+- [x] 零控制台错误
+
+## 验证
+
+> agent-browser 走查：打开 showcase `/apps/auth`（活体嵌入）——列表/新建/保存/删除全流程 + 控制台零错误

package/content/apps/multi.md

@@ -0,0 +1,44 @@
+# 应用编排 · apps
+
+## 概述
+
+父应用嵌子应用：registerApp/hApp + app:* 边界事件——子应用独立状态。后端：ws 广播。
+
+
+## 用到的页面模式
+- （无）
+
+## 用到的组件
+- [Card](../components/card.md)
+- [Button](../components/button.md)
+- [Input](../components/input.md)
+- [Tag](../components/tag.md)
+- [Tabs](../components/tabs.md)
+
+## 源码
+
+> `examples/apps/multi/` ——完整可运行（随 npm 包发布）
+
+## 目录结构
+
+| 文件 | 职责 |
+|------|------|
+| `app.tsx` | 前端：registerApp 注册 2 个子应用 + 父应用工作台（h(App, {appId}) 嵌入） |
+| `server.ts` | 独立入口（:3303——纯前端编排无后端 API） |
+| `main.tsx` | 独立前端入口 |
+
+## 改造指南（新手从跑起来到改成自己的）
+
+- 1. 加子应用：app.tsx 里 registerApp('my-app', (props, ctx) => h(MyComp, {})) + 父树 h(App, { appId: 'my-app' })
+- 2. 子应用传参：h(App, { appId, props: {...} })——app:update 边界事件（见 content/capabilities/app-node.md）
+- 3. 观察边界事件：stream.subscribe 过滤 e.entity === 'app'（工作台已展示）
+
+## 质量标准
+
+- [x] 子应用独立状态
+- [x] 边界事件观测
+- [x] 零控制台错误
+
+## 验证
+
+> agent-browser 走查：打开 showcase `/apps/multi`（活体嵌入）——列表/新建/保存/删除全流程 + 控制台零错误

package/content/apps/todo.md

@@ -0,0 +1,51 @@
+# 任务管理 · apps
+
+## 概述
+
+经典 CRUD 应用：列表/详情/新建——多页路由 + createStore 跨页状态 + 表单受控。后端：MemorySql 持久化。
+
+
+## 用到的页面模式
+- （无）
+
+## 用到的组件
+- [Button](../components/button.md)
+- [Input](../components/input.md)
+- [Checkbox](../components/checkbox.md)
+- [Form](../components/form.md)
+- [Tag](../components/tag.md)
+- [EmptyState](../components/emptystate.md)
+- [PageHeader](../components/pageheader.md)
+
+## 源码
+
+> `examples/apps/todo/` ——完整可运行（随 npm 包发布）
+
+## 目录结构
+
+| 文件 | 职责 |
+|------|------|
+| `app.tsx` | 前端：路由表 + 页面组件（TodoList/TodoNew）+ createStore + hash 桥接 |
+| `api.ts` | 后端：registerTodoApi(app, sql)——CRUD 路由（独立/嵌入共享） |
+| `server.ts` | 独立入口：MemorySql + ui + 前端服务（:3300） |
+| `main.tsx` | 独立前端入口：createTodoApp + hashchange 桥接 |
+
+## 改造指南（新手从跑起来到改成自己的）
+
+- 1. 改数据模型：编辑 api.ts 的 SQL 表结构（todos 表字段）——MemorySql 与 postgres() 同契约，换库只改 server.ts 一行
+- 2. 加页面：app.tsx 的路由表加一行 { path, render } + 新建页面组件（组件写法见 guides/component-model.md）
+- 3. 改交互/状态：页面组件内 let + ctx.render()（render-only——见 guides/render-only.md）
+- 4. 换样式：组件文档「用法示例」+ layout 原语（wf-* 类，零手写 CSS）
+- 5. 接真实后端：server.ts 把 createMemorySql() 换成 postgres()（见 content/backend/sql.md）
+
+## 质量标准
+
+- [x] 键盘可达
+- [x] 375/768 无溢出
+- [x] 亮暗主题
+- [x] loading/error/empty 态
+- [x] 零控制台错误
+
+## 验证
+
+> agent-browser 走查：打开 showcase `/apps/todo`（活体嵌入）——列表/新建/保存/删除全流程 + 控制台零错误

package/content/backend/ai.md

@@ -0,0 +1,28 @@
+# ctx.ai（chat/stream/agent/approve） · backend
+
+## 概述
+
+AI 对话全链路：流式 token / 工具调用 / HITL 审批——wf: 协议对页面透明
+
+## 装配
+
+中间件注入键：`ctx.ai`
+
+## 活体端点
+
+```bash
+curl /api/chat
+```
+
+## 关联组件
+- [AiChat](../components/aichat.md)
+- [ToolCallCard](../components/toolcallcard.md)
+- [ApprovalCard](../components/approvalcard.md)
+
+## 文档素材
+
+来源：`docs/ai-contract.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/auth.md

@@ -0,0 +1,20 @@
+# 认证（ctx.auth/user） · backend
+
+## 概述
+
+登录态/会话/权限——userSystem 集成
+
+## 装配
+
+中间件注入键：`ctx.auth`
+
+## 关联组件
+- [AuthPage](../components/authpage.md)
+
+## 文档素材
+
+来源：`content/guides/saas-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/email.md

@@ -0,0 +1,23 @@
+# 邮件（ctx.email） · backend
+
+## 概述
+
+Mailer 契约——演示用内存捕获回显（mock 输出可读）
+
+## 装配
+
+中间件注入键：`ctx.email`
+
+## 活体端点
+
+```bash
+curl /api/demo/email
+```
+
+## 文档素材
+
+来源：`content/guides/saas-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/graphql.md

@@ -0,0 +1,23 @@
+# GraphQL · backend
+
+## 概述
+
+app.graphql(handler)——SDL + resolvers map 绑定
+
+## 装配
+
+中间件注入键：`—`
+
+## 活体端点
+
+```bash
+curl /api/demo/graphql
+```
+
+## 文档素材
+
+来源：`content/guides/server-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/http.md

@@ -0,0 +1,23 @@
+# HTTP 原语 · backend
+
+## 概述
+
+Request/Response 标准接口 + SSE + CORS + 静态服务
+
+## 装配
+
+中间件注入键：`—`
+
+## 活体端点
+
+```bash
+curl /api/demo/http
+```
+
+## 文档素材
+
+来源：`content/guides/server-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/limit.md

@@ -0,0 +1,23 @@
+# rateLimit（ctx.limit） · backend
+
+## 概述
+
+限流中间件——超额返回 429（演示端点轻阈值）
+
+## 装配
+
+中间件注入键：`ctx.limit`
+
+## 活体端点
+
+```bash
+curl /api/demo/limit
+```
+
+## 文档素材
+
+来源：`content/guides/saas-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/middleware.md

@@ -0,0 +1,17 @@
+# ctx 注入链 · backend
+
+## 概述
+
+中间件面注入 ctx.sql/redis/ui/api/auth/ws/limit/email/queue/cron/ai——装配即依赖注入
+
+## 装配
+
+中间件注入键：`ctx.*`
+
+## 文档素材
+
+来源：`content/guides/middleware.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/queue.md

@@ -0,0 +1,23 @@
+# 任务队列（ctx.queue） · backend
+
+## 概述
+
+QueueClientModule——池命令 + 阻塞 worker（注入 Redis 模式）
+
+## 装配
+
+中间件注入键：`ctx.queue`
+
+## 活体端点
+
+```bash
+curl /api/demo/queue
+```
+
+## 文档素材
+
+来源：`content/guides/saas-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）