weifuwu 0.87.0 → 0.89.0

package/content/guides/production.md

@@ -1,37 +0,0 @@
-# 生产级案例（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

@@ -1,60 +0,0 @@
-# 人类质量标准（交付前验收清单）
-
-> 用途：开发完成、交付给人类用户前，逐项自查。每一项失败都必须是**拒绝交付**的理由。
-> 素材来源：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/content/guides/realtime-guide.md

@@ -1,296 +0,0 @@
-# 实时能力指南（ws/sse）
-
-> 从 docs/realtime.md 迁移（content/ 文档库——随 npm 包发布，与框架版本同步）。
-> 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
-
-# 实时与渲染 — scheduler / ui / graphql / WebSocket（weifuwu）
-
-## scheduler — 计划任务（即时/延时/cron）
-
-> 依赖 `queue`（触发后入队执行）。三类任务：即时（queue.add 已有）、延时（`ctx.schedule`）、定时（`ctx.cron`）。
-
-```ts
-import { redis, queue, scheduler } from 'weifuwu'
-
-// 模式 A 显式注入：redis 是 scheduler 的第一方消费者（ZSET 延时队列 + HASH cron 注册表
-// 直接命令 redis）——必传，与 queue({ redis }) 对齐；scheduler.close() 不关闭注入的 redis
-const r = redis()                      // ctx.redis（RedisPool）
-const q = queue({ redis: r.redis })    // 入队执行（stream）
-app.use(r)
-app.use(q)
-app.use(scheduler({ redis: r.redis, queue: q }))   // 守护循环走 createConnection() 独立连接
-
-// 延时任务（单次）：delayMs 或指定时间
-await ctx.schedule('email.send', { to, body }, { delayMs: 30_000 })
-await ctx.schedule('report.build', {}, { when: new Date('2026-09-01T00:00:00Z') })
-
-// cron 定时任务（重复）：每分钟触发 → 入队执行
-ctx.cron('* * * * *', 'heartbeat.check', { scope: 'health' })
-// 改需求 = 重新注册（同 name 覆盖更新，旧定义不残留）
-ctx.cron('*/5 * * * *', 'heartbeat.check', { scope: 'health' })
-// 停用 = cancel（删定义 + 清理 pending 触发点）
-await ctx.cancelCron('heartbeat.check')
-
-// 执行端：与 queue 完全一致
-const worker = ctx.queue.worker('email.send', async (job) => { ... })
-```
-
-- **延时**：ZSET（score=触发时间戳）+ 守护循环（独立连接）→ 到期 `ZREM` 原子抢占（多实例不重复）→ `queue.add`
-- **多应用隔离**：`scheduler({ prefix })`——ZSET/HASH 应用级共享，多应用共用 redis 时必须各自 prefix（同应用多实例共享 prefix = 协作消费）
-- **连接所有权**：scheduler 内部用 `redis.createConnection()` 独立守护连接（不占池——对齐 queue worker）；`scheduler.close()` 只关守护连接——**不关闭注入的 redis**（调用方负责 `r.close()`）
-- **cron**：HASH 注册表（**field = name，同 name 重新注册 = 覆盖更新**，改表达式不残留旧定义）+ 滚动生成触发点（`ZADD NX` 幂等）→ 复用延时链路；`nextRunAt` 原子推进
-- **取消**：`ctx.cancelCron(name)` 删定义 + 清理 pending 触发点（停用 cron 必须 cancel——定义无 TTL 会累积）
-- **崩溃恢复**：未消费触发点留在 ZSET，重启后补扫立即触发（at-least-once，幂等由业务保证）
-- **cron 表达式**：5 字段（分 时 日 月 周），支持 `*`/步进/列表/范围；时区 = 服务器本地；非法表达式注册即抛错
-- **裁剪**：❌ cron 秒/年/别名（@daily）/特殊字符（L/W/#）、时区配置、单次任务取消（v2）、分布式锁（原子命令抢占替代）
-- **文档红线**：cron 定义持久化在 HASH——进程重启后守护循环恢复即继续触发（无需重新注册）；**停用必须 `cancelCron`**（定义无 TTL，不取消会永久触发）
-
-## ui — SSR 渲染 + JS/CSS 编译
-
-```ts
-import { ui } from 'weifuwu'
-
-app.use(ui())
-```
-
-| ctx 注入 | 签名 | 说明 |
-|----------|------|------|
-| `ctx.ui.html` | `` (strings, ...values) => Response `` | HTML 模板 (转义防 XSS) |
-| `ctx.ui.html.unsafe(str)` | `(string) => string` | 插入原始 HTML |
-| `ctx.ui.js(entryPath)` | `(string) => Promise<Response>` | esbuild 编译 TSX → JS bundle |
-| `ctx.ui.css(entryPath)` | `(string) => Promise<Response>` | 读取 CSS 文件 → CSS Response（如安装 postcss + @tailwindcss/postcss 则自动编译） |
-| `ctx.ui.ssr(Comp, props?, { data })` | `(Component, props, opts?) => Promise<string>` | 服务端渲染组件 → HTML 片段（async 工厂自动 await；HtmlSafe 内联不二次转义） |
-| `ctx.ui.ssrData(data)` | `(Map) => string` | 序列化 SSR 数据 → `<script>window.__DATA__=...</script>`（`<` 转义防 XSS） |
-
-### ctx.ui.html — HTML 模板
-
-模板插值自动转义（`& < > "` → 实体），防 XSS：
-
-```ts
-app.get('/page', (req, ctx) => ctx.ui.html`
-  <h1>${title}</h1>          <!-- 自动转义 -->
-  <div>${ctx.ui.html.unsafe(richHtml)}</div>  <!-- 不转义 -->
-`)
-```
-
-### ctx.ui.js — 编译 TSX → JS
-
-```ts
-app.get('/app.js', (req, ctx) => ctx.ui.js('./src/main.tsx'))   // 相对路径
-
-app.get('/app.js', (req, ctx) => ctx.ui.js('weifuwu/ui-dom'))   // 或包名（exports map 解析）
-```
-
-使用 esbuild 编译：
-- `bundle: true`, `format: 'esm'`, `platform: 'browser'`
-- `jsx: 'automatic'`, `jsxImportSource: 'weifuwu/ui-dom'`
-- 带 mtime 缓存验证（开发时编辑文件后自动失效）
-
-### ctx.ui.css — CSS 编译
-
-```ts
-app.get('/style.css', (req, ctx) => ctx.ui.css('./src/style.css'))               // 相对路径
-app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))   // 或包名
-```
-
-- 无编译工具时直接返回原始 CSS
-- 检测到已安装 `postcss` + `@tailwindcss/postcss` 时自动编译 Tailwind CSS
-- 支持包名（`weifuwu/layout/style.css`, `weifuwu/components/style.css`）或文件路径
-- 带 mtime 缓存验证（开发时编辑文件后自动失效）
-
-### ctx.ui.ssr — SSR 渲染组件 → HTML
-
-将组件（含 async 组件）在服务端渲染为完整 HTML 片段，数据经 `ctx.data` 预取并序列化进 `window.__DATA__`（客户端 hydration 时同步命中，不重跑请求）：
-
-```ts
-const BlogPage = async (initProps, ctx) => {
-  const post = await ctx.data.get(`/api/posts/${ctx.params.slug}`, fetchPost)
-  return () =>
-    h('article', {},
-      h('h1', {}, post.title),
-      h('div', { innerHTML: post.body }),
-    )
-}
-
-app.get('/blog/:slug', async (req, ctx) => {
-  const data = new Map()
-  const html = await ctx.ui.ssr(BlogPage, {}, { data })   // HtmlSafe：模板内联不二次转义
-  return ctx.ui.html`
-    <!DOCTYPE html>
-    <html><body>
-      <div id="root">${html}</div>
-      ${ctx.ui.ssrData(data)}
-      <script src="/static/app.js"></script>
-    </body></html>
-  `
-})
-```
-
-- 事件处理器/ref 剥离，文本自动转义（XSS），`class`/`style` 对象序列化，`innerHTML` 原样输出
-- Fragment/Portal 子节点就地内联
-- `ctx.ui.ssrData(data)` 输出 `<script>window.__DATA__=...</script>`（JSON `<` 转义防 XSS）
-- 服务端 ctx shim：`$`（dirty no-op）、`ctx.data` 预取去重、`selfId` 请求级隔离
-
-### Hydration — 客户端收养服务端 HTML（事件流形态）
-
-服务端将 vnode 构建为**事件流**（`renderToEvents`）→ `eventsToHtml` 输出完整 HTML + `serializeEvents` 序列化进 `__DATA__`，客户端 `deserializeEvents` + `replay` **收养**（DOM = fold(事件流)——零 DOM 猜测、不重建、无闪跳）：
-
-```ts
-import { createRouter, deserializeEvents, replay } from 'weifuwu/ui-dom'
-
-const root = document.querySelector('#root')!
-replay(deserializeEvents((window as any).__DATA__), root)  // 收养服务端 HTML（同构）
-createRouter(routes, root)                                  // 之后正常交互渲染
-```
-
-- **DOM = fold(事件流)**：初始 DOM + 事件序列 = 任意时刻 DOM——收养即回放（与服务端渲染完全同构）
-- **async 工厂 hydration**：工厂 `ctx.data.get` 从 `__DATA__` 同步命中（不重跑请求）→ 渲染与服务端一致
-- 收养后事件流全量可用（与纯 SPA 无差别）
-- 诚实裁剪：Portal 内容就地收养（不移动到 `#__wf_portal`）；渲染期非确定性（Date/random）会导致 mismatch（dev 警告）
-
-### 路由级 SSR（routes 两端共享）
-
-同一份 RouteDef[] 路由定义，后端构建事件流即自动 SSR，无需手写 handler/模板/序列化：
-
-```tsx
-// routes.ts —— 前后端共用
-import { h } from 'weifuwu/ui-dom'
-
-export const routes = [{ path: '/blog/:slug', render: (params) => h(BlogPage, { slug: params.slug }) }]
-
-// server.ts —— renderToEvents → eventsToHtml + serializeEvents（完整 HTML + __DATA__ + styles）
-import { renderToEvents, eventsToHtml, serializeEvents } from 'weifuwu/ui-dom'
-const events = await renderToEvents(routes[0].render({ slug: 'hello' }))
-const page = eventsToHtml(events)
-
-// client.ts —— deserializeEvents + replay 收养
-replay(deserializeEvents((window as any).__DATA__), root)
-```
-
-- 组件工厂读 `ctx.params`（`/blog/:slug` → `ctx.params.slug`）——两端同源注入
-- SSR（事件流形态）：`renderToEvents` → `eventsToHtml` + `serializeEvents`——styles/title 由页面模板控制
-
-### weifuwu/dev — 服务端直接跑 .tsx
-
-Node 原生 TS 只剥离类型（不支持 JSX）。`weifuwu/dev` 注册 esbuild loader，服务端直接跑 `.tsx`（零构建）：
-
-```json
-{
-  "scripts": {
-    "dev": "node --import weifuwu/dev server.ts",
-    "start": "node --import weifuwu/dev server.ts"
-  }
-}
-```
-
-- 前后端同一 JSX 运行时（`jsxImportSource: weifuwu/ui-dom`）→ 两端 VNode 一致 → hydration 可靠
-- 与 `ctx.ui.js` 前端动态编译同一理念：无构建、无产物、改代码即生效
-
----
-
-## graphql — GraphQL 端点
-
-> **SDL + resolvers 绑定为自研实现**（`makeExecutableSchema`，56 行替代 @graphql-tools/schema）——支持根类型与嵌套类型字段 resolver、默认属性查找。
-
-```ts
-import type { GraphQLHandler } from 'weifuwu'
-
-const handler: GraphQLHandler = async (req, ctx) => ({
-  schema: `
-    type Query {
-      hello: String
-      users: [User]
-    }
-    type User { id: ID, name: String }
-  `,
-  resolvers: {
-    Query: {
-      hello: () => 'world',
-      users: () => [{ id: 1, name: 'Alice' }],
-    },
-  },
-  rootValue: {},
-  context: (req, ctx) => ({ user: ctx.user }),
-  graphiql: true,
-  maxDepth: 10,
-  timeout: 30000,
-})
-
-// 挂载到 /
-app.graphql(handler)
-
-// 或挂载到自定义路径
-app.graphql('/graphql', handler)
-```
-
-| 选项 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `schema` | `string \| GraphQLSchema` | — | SDL 字符串或 Schema 对象 |
-| `resolvers` | `any` | — | 解析器（schema 为字符串时必填）|
-| `rootValue` | `any` | — | 根值 |
-| `context` | `(req, ctx) => object` | — | 上下文工厂 |
-| `graphiql` | `boolean` | — | 启用 GraphiQL IDE |
-| `maxDepth` | `number` | `10` | 查询深度限制（0=关闭）|
-| `timeout` | `number` | `30000` | 执行超时（ms，0=关闭）|
-
-GET 请求支持 query 参数查询；POST 支持 JSON body。启用 `graphiql: true` 时，GET 无 `?query=` 参数返回 GraphiQL IDE 页面。
-
----
-
-## WebSocket
-
-```ts
-app.ws('/chat/:room', {
-  open(ws, ctx) {
-    ws.send(`欢迎加入 ${ctx.params.room} 房间`)
-    ctx.hub?.join(ctx.params.room, ws)
-  },
-  message(ws, ctx, data) {
-    // data: string | Buffer
-    ctx.hub?.send(ctx.params.room, `用户: ${data}`)
-  },
-  close(ws, ctx) {
-    ctx.hub?.leave(ws)
-  },
-  error(ws, ctx, error) {
-    console.error('WS error:', error)
-  },
-})
-```
-
-| 回调 | 参数 | 说明 |
-|------|------|------|
-| `open(ws, ctx)` | `WebSocket`, `Context` | 连接建立 |
-| `message(ws, ctx, data)` | `WebSocket`, `Context`, `string \| Buffer` | 收到消息 |
-| `close(ws, ctx)` | `WebSocket`, `Context` | 连接关闭 |
-| `error(ws, ctx, error)` | `WebSocket`, `Context`, `Error` | 错误 |
-
-### Hub — WebSocket 房间
-
-```ts
-// 注入 hub → ctx.hub
-app.ws('/chat/:room', {
-  open(ws, ctx)  { ctx.hub.join(ctx.params.room, ws) },
-  message(ws, ctx, data) { ctx.hub.send(ctx.params.room, String(data)) },
-  close(ws, ctx) { ctx.hub.leave(ws) },
-})
-
-// 自定义 Hub（Redis 后端）
-import type { Hub } from 'weifuwu'
-const redisHub: Hub = { ... }
-app.wsHub(redisHub)
-```
-
-| Hub 方法 | 说明 |
-|----------|------|
-| `join(key, ws)` | WebSocket 加入房间 |
-| `leave(ws)` | WebSocket 离开所有房间 |
-| `send(key, message)` | 向房间广播消息 |
-| `close()` | 关闭 Hub |
-
-WebSocket 原生 `ws.send()` 发送，`ws.on('message', cb)` WebSocket 接收。
-
-> **实时应用推荐用 `messager()`**（SaaS 地基模块）：协议内置（`connected/subscribe/ping`）+ 持久化 + 跨进程广播 + 点对点，不必自写 Hub/协议——见[消息系统章节](saas-guide.md)。
-
----
-

package/content/guides/render-only.md

@@ -1,44 +0,0 @@
-# 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 错位。
-