weifuwu 0.85.0 → 0.87.0

package/content/guides/production.md

@@ -0,0 +1,37 @@
+# 生产级案例（agent-platform）
+
+> 来源：`apps/agent-platform/`——多租户 AI Agent 平台，weifuwu 中间件全量消费方。
+> 定位：**实战驱动框架开发的生产级参考**——showcase 的教学模板由此提炼，框架能力先在此实战验证。
+
+## 中间件全家桶装配（真实顺序即依赖顺序）
+
+```ts
+import { serve, Router, cors, postgres, redis, ui, userSystem, ai, messager, rateLimit, verifyPassword, email } from 'weifuwu'
+
+const app = new Router()
+app.use(cors())
+app.use(postgres())          // ctx.sql——契约层（引擎实现）
+app.use(redis())             // ctx.redis——独立连接工厂 createConnection()
+app.use(userSystem())        // ctx.user/ctx.auth——登录态
+app.use(ai())                // ctx.ai——chat/stream/agent/approve
+app.use(messager())          // 实时消息
+app.use(rateLimit({ redis: r.redis, windowMs: 60_000, max: 100 }))  // ctx.limit
+app.use(ui())                // ctx.ui——前端
+```
+
+## 架构决策（可复用的模式）
+
+1. **路由按域注册**：`registerAuthRoutes / registerAgentRoutes / ...`——每域一个函数（showcase 模板的 registerXxxApi 同源）
+2. **14 页 SPA**：单一前端入口 + 路由表——见 `src/ui/routes.ts`
+3. **服务层独立**：services/（chat/agent-runner/sandbox）不依赖路由层——可单测
+4. **沙箱隔离**：sandbox/（docker + host 管理）——Agent 执行环境
+5. **商业化能力**：订阅分层/租户管理/邀请/白标/私有化——见 apps/agent-platform/README.md
+
+## 学习路径
+
+1. 先跑起来：`cd apps/agent-platform && node --env-file=.env server.ts`
+2. 读 `src/middleware/ctx.ts`（AppCtx——中间件注入面全貌）
+3. 对照 showcase 教学模板（todo/auth/admin/multi）理解"模板 = 生产架构的简化提炼"
+
+> 纪律：**实战先行、文档跟进**——框架能力变更先在 agent-platform 验证，再沉淀进 showcase 文档。
+

package/content/guides/quality.md

@@ -0,0 +1,60 @@
+# 人类质量标准（交付前验收清单）
+
+> 用途：开发完成、交付给人类用户前，逐项自查。每一项失败都必须是**拒绝交付**的理由。
+> 素材来源：AGENTS.md §8 设计系统纪律 + 组件走查记录（agent-browser 实测沉淀）。
+
+## □ 1. 可访问性（键盘全程可达）
+
+- [ ] Tab 顺序合理；role="button"/tabindex 元素有 Enter/Space 处理
+- [ ] 方向键导航组件（Tabs/DatePicker/Menu）焦点跟随激活项
+- [ ] 弹层（Modal/Drawer/Dropdown/Popover/Tooltip）Escape 关闭
+- [ ] Modal 系焦点 trap + 关闭后焦点归还
+- [ ] 危险操作（Confirm）默认 maskClosable=false（防误触）
+- [ ] aria 语义：aria-expanded/aria-current/aria-label 正确
+
+## □ 2. 响应式（三断点）
+
+- [ ] 375 / 768 / 1280 三断点无横向溢出
+- [ ] 导航正确降级（侧栏 → 顶部条）
+- [ ] 表格窄屏横向滚动（Table minWidth）或卡片化
+- [ ] 弹层视口夹紧（openPopup 自动）
+
+## □ 3. 主题（亮/暗/自动）
+
+- [ ] 全部颜色走 `--wf-color-*` token（无裸色值）
+- [ ] 语义文字色用 `-text` 变体；实心填充文字用 `on-brand`
+- [ ] 对比度 ≥ 4.5:1（文字）；focus-ring 含 primary 线（明暗均可见）
+
+## □ 4. 动效
+
+- [ ] 时长/缓动走 `--wf-dur-*` / `--wf-ease-*`（无硬编码）
+- [ ] 退场类 `--exit` 成对（有 exit 类必须挂上）
+- [ ] reduced-motion 降级（_base.css 自动——勿覆盖）
+
+## □ 5. 状态矩阵
+
+- [ ] loading / error / empty / disabled 四态全覆盖（无缺态渲染）
+- [ ] 提交按钮 loading 防重复提交
+- [ ] 受控组件有回调（无静默不可点）
+
+## □ 6. 性能
+
+- [ ] 首帧预算合理（大数据列表用 VirtualList/VirtualTable/InfiniteScroll）
+- [ ] 无渲染循环（vdom3 防死循环守护不触发）
+- [ ] 事件流无 error:caught（浏览器 console 零错误）
+
+## □ 7. 框架纪律
+
+- [ ] 无裸 `window.`/`document.`/`localStorage`（ctx.browser）
+- [ ] 渲染只发生在 `ctx.ui.render()` 调用处（无隐式触发）
+- [ ] 无 eval/new Function；无 npm 运行时依赖（前端）
+- [ ] 请求路径无同步 I/O（后端）
+
+## 验证手段（agent-browser 走查纪律）
+
+1. 真实点击（CDP）验证交互——`eval click` 绕过命中测试会掩盖问题，两者都测
+2. 查 outerHTML（结构）+ getAttribute('style')（定位/显隐）+ getBoundingClientRect（真实可见性）
+3. `closest('#__wf_portal')` 验证浮层 portal
+4. 每次验证前 reload 清状态（会话残留制造假 bug）
+5. console --level error 抓加载期错误（hook 需在页面加载前）
+

package/{docs/realtime.md → content/guides/realtime-guide.md}

@@ -1,6 +1,9 @@
-# 实时与渲染 — scheduler / ui / graphql / WebSocket（weifuwu）
+# 实时能力指南（ws/sse）
+
+> 从 docs/realtime.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+# 实时与渲染 — scheduler / ui / graphql / WebSocket（weifuwu）
 
 ## scheduler — 计划任务（即时/延时/cron）
 
@@ -287,7 +290,7 @@ app.wsHub(redisHub)
 
 WebSocket 原生 `ws.send()` 发送，`ws.on('message', cb)` WebSocket 接收。
 
-> **实时应用推荐用 `messager()`**（SaaS 地基模块）：协议内置（`connected/subscribe/ping`）+ 持久化 + 跨进程广播 + 点对点，不必自写 Hub/协议——见[消息系统章节](saas.md)。
+> **实时应用推荐用 `messager()`**（SaaS 地基模块）：协议内置（`connected/subscribe/ping`）+ 持久化 + 跨进程广播 + 点对点，不必自写 Hub/协议——见[消息系统章节](saas-guide.md)。
 
 ---
 

package/content/guides/render-only.md

@@ -0,0 +1,44 @@
+# render-only 状态
+
+> 唯一规则：**渲染只发生在 `ctx.ui.render()` 调用处**。状态是普通 JS 对象——
+> 行为可静态推导（代码审查看事件回调里有无 render() 即可验证渲染逻辑）。
+
+## 三通道
+
+| 场景 | 写法 | 触发 |
+|------|------|------|
+| 组件内部状态 | `let count` + 改后 `ctx.ui.render()` | 显式调用 |
+| 跨组件共享 | `createStore(init)` + `ctx.ui.useExternal(store)` | store.set/update/notify 自动 |
+| 跨组件精准刷新 | mount 时 `ctx.ui.selfId('name')` → 任意处 `ctx.ui.render(['name'])` | 显式调用 |
+
+```tsx
+// 内部状态
+const Counter = (_init, ctx) => {
+  let count = 0
+  return (props) => h('button', {
+    onClick: () => { count++; ctx.ui.render() },
+  }, count)
+}
+
+// 共享状态（模块级单例）
+const store = createStore({ user: null })
+const UserBadge = (_init, ctx) => {
+  const s = ctx.ui.useExternal(store)   // 订阅：变化 → 自身重渲染
+  return (props) => h('span', {}, s.state.user?.name ?? '未登录')
+}
+store.set({ user })                      // 任何位置 → 订阅组件自动重渲染
+```
+
+## 不需要渲染的状态
+
+`let el` / `let timerId` 等内部缓存——改后**不**调 render()（参考 AGENTS.md §4.1 表）。
+
+## hooks（事件驱动——非赋值自动）
+
+useMedia/useInView/useChat 等是浏览器事件驱动重渲染——与"赋值自动"本质不同，保留合理。
+
+## 历史教训
+
+v1 的 $ Proxy 在重挂载场景捕获的 selfId 与当前实例错位 → 交互静默失效。
+render-only 根治：render() 闭包绑定组件 id——无 this/selfId 错位。
+

package/{docs/saas.md → content/guides/saas-guide.md}

@@ -1,9 +1,12 @@
+# SaaS 能力指南（auth/limit/email/queue/cron）
+
+> 从 docs/saas.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
+
 # SaaS 地基模块（weifuwu）
 
 五个模块（限流 / 邮件 / 用户系统 / 消息系统 / 队列）+ AI 对话，以中间件形态随包提供，`app.use(...)` 一行接入。
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
-
 四个内建模块组成一个"基本 SaaS 底座"：认证、异步任务、限流、邮件——零新增依赖
 （只依赖已自研的 redis / postgres 客户端与 node 标准库）。
 
@@ -77,7 +80,7 @@ app.post('/secure', (req, ctx) => { ctx.auth.requireAuth(); ... })
 ```
 
 
-> ⚠️ **weifuwu/client 已删除**——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [frontend-ui-dom.md](frontend-ui-dom.md)。
+> ⚠️ **weifuwu/client 已删除**——前端运行时唯一入口为 `weifuwu/ui-dom`，见 [ui-dom 指南](ui-dom-guide.md)。
 - **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/ui-dom` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
 - **防枚举**：登录失败统一 401（不泄露邮箱是否存在）
 - **`ctx.auth` 方法面**：`register` / `login` / `logout` / `requireAuth` / `setPassword(userId, newPwd)` / `createToken(type, payload, { ttlSeconds })`（邮箱验证/密码重置自接）
@@ -147,7 +150,7 @@ import { ai } from 'weifuwu'
 const a = ai()          // DEEPSEEK_API_KEY / BASE_URL / MODEL 自动读 env，默认 deepseek-v4-flash
 app.use(a)              // 注入 ctx.ai（worker/非请求场景也可直接 a.chat()）
 
-// 流式对话：路由一行返回 SSE（wf: 协议，详见 docs/ai-contract.md）
+// 流式对话：路由一行返回 SSE（wf: 协议，详见 [ai-contract](../../docs/ai-contract.md)）
 app.post('/api/chat', async (req, ctx) => {
   const { messages } = await req.json()
   return ctx.ai.stream({ messages }, {
@@ -217,7 +220,7 @@ return () => <AiChat chat={$} />
 
 > 分层：`ctx.ai`（后端协议）→ `aiStream`（传输解码）→ `useChat`（会话语义）→ `AiChat`（标准界面）。要完全自定义 UI 的应用用 useChat + 自有渲染；要 5 分钟出界面用 AiChat。
 
-- **协议**：`wf:` 命名空间（message_start/token/tool_call/tool_progress/usage/done/error + agent 扩展 step/approval_request），SSE 下行 + POST 上行，错误即值、未知事件透传、`x:*` 自定义事件（详见 [docs/ai-contract.md](ai-contract.md)）
+- **协议**：`wf:` 命名空间（message_start/token/tool_call/tool_progress/usage/done/error + agent 扩展 step/approval_request），SSE 下行 + POST 上行，错误即值、未知事件透传、`x:*` 自定义事件（详见 [ai-contract](../../docs/ai-contract.md)）
 - **agent 引擎**：`a.agent({ systemPrompt, tools, humanInTheLoop })` 工具循环（LLM → tool_call → 执行 → 回喂 → 重复）；工具可 `emit` 进度/自定义事件、接收 `signal` 取消；HITL 审批（`ctx.ai.approve` 响应，拒绝≠终止、modified 改参、超时兜底）
 - **emitter 抽象**：`agent.stream(messages, { emit })`——`wf:*` 事件（step/token/tool_result/usage/done）可接任意通道（SSE/WS/回调），协议不焊死在传输层；`agent.runToResult(messages)` 返回结构化结果 `{ content, steps, usage }`（非流式/worker 场景）
 - **embedding**：`ctx.ai.embed(text)` / `embedMany(texts)` 向量化（默认 `DASHSCOPE_API_KEY` + `text-embedding-v4`，compatible-mode 端点）；未配置抛 `AiError('unsupported')`（惰性检查，不静默降级）——知识库/语义检索开箱即用

package/{docs/server.md → content/guides/server-guide.md}

@@ -1,9 +1,12 @@
+# 后端开发指南
+
+> 从 docs/server.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
+
 # 后端 API — HTTP 服务层（weifuwu）
 
 > 以下为完整 API 参考，按需查阅。新手建议先阅读 README 的「核心概念」和「快速开始」。
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
-
 ## Router
 
 Trie 路由，支持 URL 参数、通配符、中间件链、WebSocket、GraphQL。

package/content/guides/start.md

@@ -0,0 +1,41 @@
+# 快速开始
+
+> LLM 路径：本文件是起点。读完后按需打开 content/ 各域。
+
+## 1. 获取文档（三选一，同一份内容）
+
+- 仓库内：`content/index.md`（本文件的上层导航）
+- npm 包：`node_modules/weifuwu/content/index.md`（版本永远匹配装的代码）
+- 文档站：`npx weifuwu docs` → http://localhost:4000
+
+## 2. 选型（30 秒决策）
+
+| 要做什么 | 打开 |
+|---------|------|
+| 用某个组件（Button/Table/Modal…） | `content/components/<id>.md`——API 表 + 纪律 + 示例 |
+| 拼页面布局（容器/间距/导航壳） | `content/layout/*.md`——wf-* 原语族 |
+| 完整页面（后台壳/仪表盘/登录…） | `content/patterns/*.md`——复制即用 |
+| 完整应用（todo/auth/admin/multi） | `content/apps/*.md` + `examples/apps/<id>/`——复制即改 |
+| 后端能力（sql/redis/ws/ai/limit…） | `content/backend/*.md`——装配代码 + 活体端点 |
+| 框架怎么工作（路由/状态/事件流…） | `content/capabilities/*.md` |
+| 交付前质量检查 | `content/guides/quality.md` |
+
+## 3. 取码（新手从最小起步）
+
+- **最小起步**：`examples/hello-world/`（server.ts + routes.tsx + client.ts 三文件——复制目录 → `node server.ts` → http://localhost:3400 即跑）——README「快速开始」的落地版
+- 组件片段：组件文档「用法示例」节复制
+- 完整页面：`examples/patterns/<file>.tsx`（复制文件即得页面）
+- 完整应用：`examples/apps/<id>/` 整个目录（复制 → `node server.ts` 即跑）
+
+## 4. 运行
+
+```bash
+node server.ts   # 或 node --env-file=.env server.ts（需要环境变量时）
+```
+
+## 5. 验证
+
+1. `npx weifuwu docs` 起文档站对照 API
+2. 对照 `content/guides/quality.md` checklist 逐项自查
+3. 交互组件用 agent-browser 真实点击验证（详见组件文档「验证」节）
+

package/{docs → content/guides}/styling.md

@@ -1,6 +1,10 @@
+# 样式体系指南
+
+> 从 docs/styling.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
+
 # 主题配置指南（三档）
 
-> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 > 主题配置按复杂度分三档——**90% 的项目止步于第一档**。
 
 ## 第一档：1 个值换肤（90% 项目）

package/{docs/frontend-ui-dom.md → content/guides/ui-dom-guide.md}

@@ -1,3 +1,8 @@
+# 前端运行时指南（UIRouter/渲染器）
+
+> 从 docs/frontend-ui-dom.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
+> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
+
 # ui-dom — 前端运行时（vdom3 精准事件流引擎）
 
 > **createRouter（路由）+ createRoot（挂载）+ 精准事件流（渲染本体）**，
@@ -59,6 +64,7 @@ let ctx: any = {}
 ctx = await api({ baseURL: '', token: ... })(ctx)
 ctx = auth({ ... })(ctx)
 ctx = v3Toast()(ctx)
+ctx = v3Notification()(ctx)
 createRouter([...], root, { ctx })
 ```
 
@@ -133,7 +139,7 @@ replay(deserializeEvents(data), root)
 - **render-only**：状态是普通对象（`let` + 显式 `render()`）——禁止隐式触发
 - **mount/render 分工**：只依赖稳定引用的回调（ctx/挂载闭包）→ mount 定义（零重绑）；依赖最新 props → render 内定义（重绑是正确性要求）
 - **ref 稳定**：带清理的 ref 定义在 mount 作用域（内联 ref 每次渲染新函数 → ref(null) 反复触发）
-- **浮层 portal**：`ctx.ui.usePopup` + `popup.portal()`（#__wf_portal）——禁止 absolute 相对父容器
+- **浮层**：`ctx.ui.openPopup`（命令式——#__wf_portal 统一容器）——禁止 absolute 相对父容器
 - **浏览器环境**：组件用 `ctx.browser`（禁裸 window/document）——SSR 安全三态
 - **事件 handler**：代理 Map 覆盖——handler 更新零重绑零事件（稳定引用仅为性能建议——结构共享收益前提）
 - **props 不可变（红线——Chat 空 bubble 事故）**：**禁止原地修改 props 引用的对象**（`m.content += text`）——vdom3 剪枝按 props 浅比较判断"未变"→ 复用旧输出 → 渲染不更新。**状态更新必须新建对象**（`$.msgs[i] = { ...m, content: ... }`——引用变 → 剪枝不命中 → 重渲染）。排查"渲染没更新"时看 `__wf_tail` 的 `comp:build` 事件 `reason: 'reuse-skip'`（= 契约：props 引用未变）