weifuwu 0.61.1 → 0.62.0

package/README.md

@@ -62,7 +62,7 @@ npm install weifuwu
 
 **自研数据层** — `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（48 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
+> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（61 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
 
 ---
 
@@ -164,7 +164,7 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 
 - 访问页面：SPA 客户端渲染；SSR 页面内容直接进 HTML（`curl /` 可见，SEO）
 - 改组件刷新即生效，无需构建步骤
-- 完整可运行示例见 `apps/demo`（博客页 = SSR + Hydration，SPA 页 = 纯客户端）
+- 完整可运行示例见 `apps/components-demo`（组件 cheatsheet）与 `apps/agent-platform`（全栈 SaaS 应用）
 
 > 想**零后端、零构建**最快跑起来？直接跳到下面的「CDN 快速原型」。
 
@@ -235,14 +235,14 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 </html>
 ```
 
-将此 HTML 保存到本地用浏览器打开即可运行。完整的 CDN 示例见 [`apps/html/test.html`](./apps/html/test.html)。
+将此 HTML 保存到本地用浏览器打开即可运行。
 
 ### CDN 资源地址说明
 
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
 | `weifuwu/client` | `https://unpkg.com/weifuwu@latest/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 48 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 61 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
 | `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 141 个主题 Token + 67 个布局原语 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
@@ -266,6 +266,7 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | `weifuwu` | **userSystem** | 用户系统（scrypt 密码哈希 + 混合会话 + 多租户感知）→ `ctx.user` / `ctx.auth` / `ctx.tenantId` + `/api/auth/*` | Router, postgres |
 | `weifuwu` | **messager** | 消息系统（会话/消息持久化 + WS 实时投递 + Redis 跨进程广播）→ `ctx.msg` + `/api/messages/*` | Router, postgres, (redis) |
 | `weifuwu` | **queue** | 可靠任务队列（Redis Streams，at-least-once + DLQ）→ `ctx.queue` | Router, redis |
+| `weifuwu` | **scheduler** | 计划任务（延时 `ctx.schedule` + cron `ctx.cron`/`ctx.cancelCron`，触发后入队） | Router, redis, queue |
 | `weifuwu` | **ai** | LLM 对话（自研 OpenAI 兼容协议 + 自研 SSE 解码，默认 DeepSeek）→ `ctx.ai` + embedding + `ctx.ui.useChat` + `AiChat` | Router |
 | `weifuwu/dev` | **dev loader** | Node loader：服务端直接跑 `.ts/.tsx`（`--import weifuwu/dev`） | esbuild |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
@@ -282,7 +283,7 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | `weifuwu/client` | **ErrorBoundary** | 错误边界组件 | createApp |
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
 | `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
-| `weifuwu/components` | **48 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
+| `weifuwu/components` | **61 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
 | `weifuwu/layout` | **CSS 布局** | 67 个布局原语 + 141 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
@@ -551,7 +552,7 @@ await server.stop(2000)  // 超时毫秒
 | `hostname` | `string` | `'0.0.0.0'` | 监听地址 |
 | `signal` | `AbortSignal` | — | 通过信号停止 |
 | `maxBodySize` | `number` | `10MB` | 请求体上限（0=无限） |
-| `timeout` | `number` | `30000` | Socket 超时（ms） |
+| `timeout` | `number` | `120000` | Socket 超时（ms，2 分钟，适配 LLM 生成等长任务） |
 | `keepAliveTimeout` | `number` | `5000` | Keep-Alive 超时 |
 | `headersTimeout` | `number` | `6000` | 请求头超时 |
 | `shutdown` | `boolean` | `true` | 自动注册 SIGTERM/SIGINT |
@@ -669,7 +670,9 @@ app.post('/transfer', async (req, ctx) => {
 | **int8（超出安全范围）** | **`string`**（防静默丢精度，金额/ID 关键） |
 | float / numeric | `number` |
 | boolean | `boolean` |
-| text / varchar / uuid / date | `string` |
+| text / varchar / uuid | `string` |
+| **timestamptz** | **`Date`**（带时区，ISO 解析无本地时区魔法） |
+| timestamp / date / interval | `string`（无时区语义——转 Date 按本地时区解析即时区魔法，诚实裁剪不转） |
 | NULL | `null` |
 
 ### 类型层（查询泛型 + schema 写前校验）
@@ -699,9 +702,28 @@ await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → Validati
 | `ctx.sql.transaction(fn)` | 事务（回调收到 `{ query }`） |
 | `ctx.sql.register(table, schema)` | 注册表结构（写前校验） |
 | `ctx.sql.insert(table, row)` | schema 校验 + 参数化插入 |
+| `ctx.sql.insertMany(table, rows[], { batchSize? })` | **批量插入**：多行 VALUES 单次往返（默认 500/批；所有行键必须一致） |
+| `ctx.sql.update(table, set, where, { returning? })` | **参数化 UPDATE**：SET/WHERE 全部参数化，返回 `affectedRows` |
+| `ctx.sql.delete(table, where)` | **参数化 DELETE**：WHERE 必填（防全表误删），返回 `affectedRows` |
 | `ctx.sql\`...\` 内嵌片段` | 条件 SQL 片段（嵌套过滤，参数自动重编号） |
 | `ctx.sql.close()` | 关闭连接池 |
 
+### 影响行数（affectedRows）
+
+`INSERT / UPDATE / DELETE / MERGE` 的返回行数组带**非枚举** `affectedRows` 属性（不干扰 `deepEqual`/`JSON.stringify`）：
+
+```ts
+const r = await ctx.sql`UPDATE messages SET read = true WHERE id = ${id}`
+if (r.affectedRows === 0) return new Response('not found', { status: 404 })
+```
+
+```ts
+// 批量插入：100 行 1 次往返
+await ctx.sql.insertMany('agent_logs', logs, { batchSize: 500 })
+// 语义化更新/删除：WHERE 全参数化 + 返回影响行数
+await ctx.sql.update('users', { role: 'admin' }, { id: userId })
+await ctx.sql.delete('messages', { id: msgId })
+
 ### 条件片段（嵌套过滤）
 
 ```ts
@@ -721,7 +743,8 @@ const rows = await ctx.sql`
 | `max`（或 `poolSize`） | `number` | `10` | 连接池大小 |
 | `acquireTimeoutMs` | `number` | `30000` | 池全忙时 acquire 超时（防饿死，0=无限） |
 | `statementTimeoutMs`（或 `statementTimeout`） | `number` | `0` | 语句超时（慢查询保护，0=禁用） |
-| `onQuery` | `(sql, durationMs, rowCount) => void` | — | 查询观测钩子（慢查询日志/审计） |
+| `idleTimeoutMs` | `number` | `0` | 空闲连接回收（超时未用关闭，容量收缩后自动重建；0=禁用） |
+| `onQuery` | `(sql, durationMs, rowCount, traceId?) => void` | — | 查询观测钩子；第 4 参数为请求级 traceId（`x-trace-id` 头经 ALS 传播） |
 
 ### 幂等迁移（内置）
 
@@ -816,6 +839,12 @@ await ctx.redis.set('user', 1)         // 实际写入 'api:user'
 | `cache(key, fn, ttl)` | 缓存读-算-写（null 不缓存防穿透） |
 | `publish(channel, msg)` | Pub-Sub 发布 |
 | `createSubscriber()` | 独立订阅连接（`subscribe`/`psubscribe` 回调式） |
+| `hset / hget / hgetall / hdel` | hash 字段读写（`hgetall` → `Record`，缺失 `{}`） |
+| `lpush / rpush / lpop / rpop / lrange` | list 队列操作（`lrange` 支持负数区间） |
+| `sadd / srem / smembers` | set 成员操作（`sadd` 重复不加） |
+| `zadd / zrange` | zset 有序集（score 升序） |
+| `mget / mset / exists / setnx / incrby` | 批量读写 / 存在性 / 原子设值（锁基础）/ 增量 |
+| `pipeline()` | 管道：批量命令一次往返（池级，key 自动加前缀） |
 | `command(name, ...args)` | 底层命令透传 |
 | `close()` | 关闭连接池 |
 
@@ -824,11 +853,50 @@ await ctx.redis.set('user', 1)         // 实际写入 'api:user'
 | `url` | `string` | `REDIS_URL` 环境变量 | 连接字符串 |
 | `poolSize` | `number` | `5` | 连接池大小 |
 | `keyPrefix` | `string` | `''` | 所有 key 自动加前缀（多应用隔离） |
+| `commandTimeoutMs` | `number` | `0` | 命令超时（阻塞命令 resolve(null)；防挂起。0=禁用） |
+| `socketTimeoutMs` | `number` | `0` | socket 响应超时（僵尸连接自愈：pending 有命令且超时无数据 → 主动断开重连。0=禁用） |
+
+> **连接健康**：断线自动剔除死连接并重建（池不萎缩）；`CLIENT KILL`/网络抖动后服务自愈，命令不命中死连接。
 
 > **裁剪声明**：集群（MOVED 路由）/ 哨兵 / 自动管道不支持（standalone 优先）。
 
 ---
 
+## scheduler — 计划任务（即时/延时/cron）
+
+> 依赖 `queue`（触发后入队执行）。三类任务：即时（queue.add 已有）、延时（`ctx.schedule`）、定时（`ctx.cron`）。
+
+```ts
+import { queue, scheduler } from 'weifuwu'
+
+const q = queue()
+app.use(q)
+app.use(scheduler({ queue: q }))       // 依赖 ctx.queue（触发后入队）
+
+// 延时任务（单次）：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 = 协作消费）
+- **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
@@ -1095,7 +1163,8 @@ app.get('/secure', () => {
 | API | 说明 |
 |-----|------|
 | `new HttpError(msg, status)` | 创建 HTTP 错误，name = 'HttpError' |
-| `DEFAULT_MAX_BODY` | `10 * 1024 * 1024` (10MB) |
+
+> 请求体上限常量 `DEFAULT_MAX_BODY`（10MB）见上方 serve 选项表 `maxBodySize`。
 
 ---
 
@@ -1991,7 +2060,7 @@ createApp()
     locale: 'zh-CN',
     messages: {
       'title': '仪表盘',
-      'welcome': '欢迎, {name}',
+      'welcome': '欢迎光临',
     },
   }))
   .mount('#root', App)
@@ -2226,7 +2295,7 @@ import type { RouterOptions } from 'weifuwu/client'
 
 # 组件库 (`weifuwu/components`)
 
-46 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+61 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -2273,35 +2342,35 @@ import 'weifuwu/components/style.css'   // 包含 Token + 67 布局原语 + 组
 <Alert variant="warning" closable>注意：磁盘空间不足</Alert>
 
 // ├─ 标签 / 徽标 / 头像
-<Badge count={5}>消息</Badge>
-<Badge variant="success">通过</Badge>
-<Tag variant="blue" closable onClose={() => {}}>标签</Tag>
+<Badge variant="primary">消息</Badge>
+<Badge variant="success" dot>通过</Badge>
+<Tag variant="primary" closable onClose={() => {}}>标签</Tag>
 <Avatar name="张三" size="lg" />
 
 // ├─ 卡片 / 统计卡片
-<Card title="卡片标题" extra={<a href="#">更多</a>}>卡片内容</Card>
-<StatCard title="总用户" value="1,234" trend={12.5} variant="primary" />
+<Card variant="outlined" padding="md">卡片内容</Card>
+<StatCard label="总用户" value="1,234" trend="up" trendLabel="12%" />
 
 // ├─ 标签页 / 下拉菜单
-<Tabs items={[{ key: 'a', label: '标签A' }, { key: 'b', label: '标签B' }]} activeKey="a" onChange={setTab} />
-<Dropdown items={[{ label: '编辑', onClick: () => {} }, { label: '删除', danger: true }]}>操作</Dropdown>
+<Tabs items={[{ key: 'a', label: '标签A' }, { key: 'b', label: '标签B' }]} active="a" onChange={setTab} />
+<Dropdown items={[{ label: '编辑', onClick: () => {} }, { label: '删除', variant: 'danger' }]}>操作</Dropdown>
 
 // ├─ 分页 / 步骤条
 <Pagination total={100} page={1} pageSize={10} onChange={setPage} />
-<Steps items={[{ title: '第一步' }, { title: '第二步' }]} current={1} />
+<Steps items={[{ key: 's1', label: '第一步' }, { key: 's2', label: '第二步' }]} current={1} />
 
 // ├─ 滑块 / 进度条
 <Slider min={0} max={100} value={50} onChange={setValue} />
-<ProgressBar value={75} variant="success" label="75%" />
+<ProgressBar value={75} label="75%" />
 
 // ├─ 面包屑 / 分割线
 <Breadcrumb items={[{ label: '首页' }, { label: '用户管理' }]} />
 <Divider />
-<Divider orientation="left">分割文字</Divider>
+<Divider>分割文字</Divider>
 
 // ├─ 加载 / 空状态 / 骨架屏
 <Loading text="加载中..." />
-<EmptyState title="暂无数据" description="请先创建一条记录" action={<Button>新建</Button>} />
+<EmptyState text="暂无数据" hint="请先创建一条记录"><Button>新建</Button></EmptyState>
 <Skeleton variant="text" lines={3} />
 <Skeleton variant="table" lines={5} cols={4} />
 <Skeleton variant="avatar" />
@@ -2366,42 +2435,53 @@ props 变化 ──────────────────────
 |-----|--------|-----------|------|
 | Button | `Button` | `variant`, `size`, `loading`, `disabled`, `block`, `type` | 按钮 |
 | Input | `Input` | `label`, `name`, `type`, `value`, `placeholder`, `required`, `disabled`, `error`, `hint`, `onInput`, `onChange` | 输入框 |
-| Textarea | `Textarea` | `rows`, `resize`, `maxLength`, `error` | 文本域 |
+| Textarea | `Textarea` | `rows`, `maxLength`, `showCount`, `error` | 文本域 |
 | Select | `Select` | `options: SelectOption[]`, `placeholder`, `searchable` | 下拉选择 |
 
 ### 表单选择
 
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
-| Checkbox | `Checkbox` | `checked`, `label`, `indeterminate` | 复选框 |
-| Switch | `Switch` | `checked`, `size` | 开关 |
+| Checkbox | `Checkbox` | `checked`, `label`, `onChange` | 复选框 |
+| Switch | `Switch` | `checked`, `label`, `onChange` | 开关 |
 | RadioGroup | `RadioGroup` | `options: RadioOption[]`, `value`, `name` | 单选组 |
-| Slider | `Slider` | `min`, `max`, `step`, `value`, `range` | 滑块 |
+| Slider | `Slider` | `min`, `max`, `step`, `value`, `onChange` | 滑块 |
 
 ### 表单增强
 
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
 | Form | `Form` | `onSubmit`, `validation` | 表单容器 |
-| Field | `Field` | `label`, `error`, `required`, `help` | 字段包装 |
-| FileUpload | `FileUpload` | `accept`, `multiple`, `maxSize`, `onFiles` | 文件上传 |
-| SearchInput | `SearchInput` | `value`, `placeholder`, `onSearch`, `loading` | 搜索框 |
+| Field | `Field` | `label`, `error`, `required`, `hint` | 字段包装 |
+| FileUpload | `FileUpload` | `accept`, `multiple`, `maxSize`, `onChange` | 文件上传 |
+| SearchInput | `SearchInput` | `value`, `placeholder`, `onInput`, `onClear` | 搜索框 |
 | SegmentedControl | `SegmentedControl` | `options: SegmentedOption[]`, `value`, `onChange`, `size` | 分段选择器 |
-| ProgressBar | `ProgressBar` | `value`, `max`, `variant`, `size`, `label` | 进度条 |
+| ProgressBar | `ProgressBar` | `value`, `max`, `label`, `showValue` | 进度条 |
+| InputNumber | `InputNumber` | `value`, `min`, `max`, `step`, `precision`, `onChange` | 数字输入（增减按钮） |
+| PasswordInput | `PasswordInput` | `value`, `onInput`, `autoComplete` | 密码输入（可见性切换） |
+| TagsInput | `TagsInput` | `value: string[]`, `maxTags`, `allowDuplicates` | 标签输入（中文输入法感知） |
 
 ### 数据展示
 
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
-| Table | `Table` | `columns: TableColumn[]`, `data`, `loading`, `sortable`, `selectable` | 表格 |
-| Card | `Card` | `title`, `extra`, `shadow`, `padding` | 卡片 |
-| Badge | `Badge` | `variant: BadgeVariant`, `count`, `dot`, `max` | 徽标 |
-| Tag | `Tag` | `variant`, `closable`, `onClose` | 标签 |
-| Avatar | `Avatar` | `src`, `name`, `size`, `shape` | 头像 |
-| Icon | `Icon` | `name: IconName`, `size`, `color`, `strokeWidth` | 图标（内置 100+ 图标，stroke 风格） |
-| StatCard | `StatCard` | `title`, `value`, `trend`, `icon`, `variant` | 统计卡片 |
-| PageHeader | `PageHeader` | `title`, `subtitle`, `actions`, `onBack`, `breadcrumb` | 页面标题 |
-| Img | `Img` | `src`, `alt`, `fallback`, `lazy`, `fit` | 图片（含 fallback） |
+| Table | `Table` | `columns: TableColumn[]`, `data`, `loading`, `sortKey`, `sortOrder`, `onSort`, `onRowClick` | 表格 |
+| Card | `Card` | `variant`, `outlined`, `padding`, `clickable`, `hover`, `active`, `onClick` | 卡片 |
+| Badge | `Badge` | `variant: BadgeVariant`, `dot` | 徽标 |
+| Tag | `Tag` | `variant: 'default'\|'primary'\|'success'\|'danger'`, `closable`, `onClose` | 标签 |
+| Avatar | `Avatar` | `src`, `name`, `size`, `color` | 头像 |
+| AvatarGroup | `AvatarGroup` | `items`, `max`, `size` | 头像组（堆叠 + 溢出 +N） |
+| Timeline | `Timeline` | `items: TimelineItem[]`, `mode`, `reverse` | 时间线（执行日志/历史） |
+| Descriptions | `Descriptions` | `items: DescriptionItem[]`, `column`, `bordered` | 描述列表（详情页字段） |
+| Markdown | `Markdown` | `content` | AI 回复渲染（安全子集 parser） |
+| CodeBlock | `CodeBlock` | `code`, `lang`, `title` | 代码块（语言标签 + 复制） |
+| Highlight | `Highlight` | `text`, `query: string \| string[]` | 搜索词高亮（mark） |
+| List | `List` | `items`, `renderItem`, `divided`, `header/footer/empty` | 通用列表 |
+| Result | `Result` | `status`, `title`, `desc`, `extra` | 结果页（成功/失败/警告/信息） |
+| Icon | `Icon` | `name: IconName`, `size` | 图标（内置 25 个 stroke 图标，currentColor 随字号） |
+| StatCard | `StatCard` | `label`, `value`, `trend: 'up'\|'down'`, `trendLabel`, `icon`, `animate` | 统计卡片 |
+| PageHeader | `PageHeader` | `title`, `sub`, `display` | 页面标题（actions 放 children） |
+| Img | `Img` | `src`, `alt`, `fallback`, `loading`, `width`, `height` | 图片（含 fallback） |
 | InView | `InView` | `once`, `threshold`, `rootMargin`, `placeholder`, `onEnter` | 进入视窗后懒加载内容 |
 
 ### 数据反馈
@@ -2410,13 +2490,13 @@ props 变化 ──────────────────────
 |-----|--------|-----------|------|
 | Modal | `Modal` | `open`, `title`, `onClose`, `width`, `footer`, `closable` | 模态框 |
 | Confirm | `Confirm` | `open`, `message`, `confirmText`, `cancelText`, `variant`, `onConfirm`, `onCancel` | 确认对话框（同 `ctx.confirm()` 命令式） |
-| Drawer | `Drawer` | `open`, `title`, `onClose`, `position: DrawerPosition`, `width` | 抽屉 |
+| Drawer | `Drawer` | `open`, `title`, `position: DrawerPosition`, `onClose`, `footer` | 抽屉 |
 | Tooltip | `Tooltip` | `content`, `position: TooltipPosition`, `disabled` | 工具提示（hover/focus 触发） |
 | Popover | `Popover` | `content`, `position: PopoverPosition`, `trigger`, `open`, `onOpenChange`, `disabled` | 弹出层 |
-| Toast | `Toast` | `items: ToastItem[]`, `position`, `max` | 消息提示 |
-| Alert | `Alert` | `variant: AlertVariant`, `title`, `closable`, `icon` | 警告提示 |
-| Loading | `Loading` | `size`, `text`, `fullscreen` | 加载中 |
-| EmptyState | `EmptyState` | `title`, `description`, `action`, `icon` | 空状态 |
+| Toast | `Toast` | `toasts: ToastItem[]`, `position`, `max`, `onRemove` | 消息提示 |
+| Alert | `Alert` | `variant: AlertVariant`, `closable`, `onClose` | 警告提示（内容放 children） |
+| Loading | `Loading` | `text` | 加载中 |
+| EmptyState | `EmptyState` | `icon`, `text`, `hint` | 空状态（操作放 children） |
 | Skeleton | `Skeleton` | `variant: SkeletonVariant`, `lines`, `cols`, `width`, `height` | 骨架屏 |
 
 ### 导航组件
@@ -2424,11 +2504,12 @@ props 变化 ──────────────────────
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
 | Breadcrumb | `Breadcrumb` | `items: BreadcrumbItem[]` | 面包屑 |
-| Tabs | `Tabs` | `items: TabItem[]`, `activeKey`, `onChange`, `type` | 标签页 |
-| Dropdown | `Dropdown` | `trigger`, `items: DropdownItem[]`, `open` | 下拉菜单 |
+| Menu | `Menu` | `items: MenuItem[]`, `activeKey`, `onSelect` | 侧栏导航（分组 + 图标 + 方向键） |
+| Tabs | `Tabs` | `items: TabItem[]`, `active`, `onChange` | 标签页 |
+| Dropdown | `Dropdown` | `trigger`, `items: DropdownItem[]`, `open`, `onOpenChange` | 下拉菜单 |
 | Pagination | `Pagination` | `total`, `page`, `pageSize`, `onChange` | 分页 |
-| Steps | `Steps` | `items: StepItem[]`, `current`, `direction`, `size` | 步骤条 |
-| Accordion | `Accordion` | `items: AccordionItem[]`, `multiple`, `defaultActive` | 手风琴 |
+| Steps | `Steps` | `items: StepItem[]`（`{ key, label }`）, `current`, `active` | 步骤条 |
+| Accordion | `Accordion` | `items: AccordionItem[]`, `multiple` | 手风琴 |
 
 ### 图表
 
@@ -2442,13 +2523,14 @@ props 变化 ──────────────────────
 
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
-| Divider | `Divider` | `orientation`, `plain` | 分割线（水平/垂直/带文字） |
+| Divider | `Divider` | `vertical` | 分割线（水平带文字放 children，`vertical` 垂直） |
 
 ### AI 交互原语（wf: 协议配套）
 
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
 | AiChat | `AiChat` | `chat`, `maxHeight?`, `labels?`, `renderMessage?`, `renderToolArgs?` | 标准 AI 对话界面：气泡 + 工具卡 + 审批卡 + 自动滚动 + 错误重试（接收 `ctx.ui.useChat()` handle） |
+| MessageBubble | `MessageBubble` | `content`, `role`, `status`, `actions` | 独立消息气泡（业务聊天页复用） |
 | ToolCallCard | `ToolCallCard` | `call`, `progress?`, `result?`, `renderArgs?` | 工具调用卡片：running（进度条）/ ok / error 三态（协议 §4） |
 | ApprovalCard | `ApprovalCard` | `request`, `status?`, `onApprove`, `onReject` | 人工审批卡片：待批（允许/拒绝+备注）/ 已批 / 已拒 / 超时（协议 §4.5） |
 
@@ -2708,7 +2790,7 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 </style>
 ```
 
-完整的零样式示例：`apps/weifuwu-demo`（一个页面 = 组件 + 原语，无 style.css）。
+完整的零样式示例：`apps/components-demo`（组件 + 原语即插即用，无手写样式）。
 
 诚实例外（合理场景，仍可内联 `<style>` 解决）：打印/PDF 导出规则、第三方库宿主样式、
 业务特有的一次性视觉（如色板选择器交互）。
@@ -2799,7 +2881,7 @@ const LoginPage = (_init, ctx) => {
 
   return (props) =>
     h('div', { class: 'wf-stack', style: { maxWidth: 400, margin: '40px auto' } },
-      h(Card, { shadow: 'md' },
+      h(Card, { padding: 'lg' },
         h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
           h('h2', {}, '登录'),
           h(Form, {
@@ -2847,7 +2929,7 @@ const UserList = (_init, ctx) => {
 
     return h('div', { class: 'wf-stack', style: { gap: 'var(--wf-space-md)' } },
       h('div', { class: 'wf-row', style: { justifyContent: 'space-between', alignItems: 'center' } },
-        h(SearchInput, { placeholder: '搜索用户...', value: $.keyword, onSearch: (v: string) => { $.keyword = v } }),
+        h(SearchInput, { placeholder: '搜索用户...', value: $.keyword, onInput: (e: Event) => { $.keyword = (e.target as HTMLInputElement).value } }),
         h(Button, { variant: 'primary' }, '新建用户'),
       ),
       h(Table, {
@@ -2956,8 +3038,16 @@ app.get('/api/search', async (req, ctx) => {
   await ctx.limit('search', { max: 30, windowMs: 60_000 })  // 手动限流，超限抛 429
 })
 
-// 登录防爆破（配合 userSystem）：组合键 ip:email
-app.use(rateLimit({ key: (req) => `login:${req.ip}:${req.email}`, max: 5, windowMs: 15 * 60_000 }))
+// 登录/注册防爆破：ctx.limit 默认按 IP 维度（每 IP 独立计数）
+app.post('/api/auth/register', async (req, ctx) => {
+  await ctx.limit('register', { max: 5, windowMs: 60_000 }) // 每 IP 每分钟 5 次
+})
+
+// 系统级总量限制：scope: 'global' 全局共享维度
+await ctx.limit('total-jobs', { max: 1000, windowMs: 60_000, scope: 'global' })
+
+// 登录防爆破（配合 userSystem）：组合键 ip:email（key 接收标准 Request，取头拿 IP）
+app.use(rateLimit({ key: (req) => `login:${req.headers.get('x-forwarded-for')}:${req.headers.get('x-user-email')}`, max: 5, windowMs: 15 * 60_000 }))
 ```
 
 | 选项 | 默认 | 说明 |
@@ -3023,7 +3113,7 @@ await msg.migrate()            // 幂等建表（conversations + members + messa
 app.use(db)
 app.use(msg)                   // 注入 ctx.msg
 msg.routes(app)                // /api/messages/*（会话/历史/发消息/已读）
-app.ws('/ws', ctx.msg.handler())   // 标准 WS 协议内置
+app.ws('/ws', msg.handler())        // 标准 WS 协议内置
 
 // 业务代码：持久化 + 鉴权 + 广播 + 未读 + 历史，一次调用
 const conv = await ctx.msg.createConversation(ctx.user.id, { type: 'group', memberIds: ['u2'] })
@@ -3034,7 +3124,8 @@ ctx.msg.sendTo('u2', { type: 'mention' })       // 用户维度点对点
 
 - **数据模型**：`_weifuwu_conversations` / `_weifuwu_conversation_members` / `_weifuwu_messages`（`sender_type + sender_id` 不 FK users——user/agent/system 消息天然可存）；direct 会话同对用户唯一、历史游标分页、未读数（`last_read_at`）、编辑/删除软删
 - **实时协议内置**：`handler()` 提供 `connected / subscribe→subscribed / unsubscribe / ping→pong`——前端 `ctx.ws.send({ type: 'subscribe', room })` 直接可用，两端协议由框架定义
-- **跨进程**：`redis` 选项 → Redis pub/sub 广播（psubscribe 模式），多实例部署天然一致；无 redis 优雅降级单进程
+- **跨进程**：`redis` 选项 → Redis pub/sub 广播（psubscribe 模式），多实例部署天然一致；无 redis 优雅降级单进程。
+  **环回去重**：`broadcast` = 本地直发 + Redis publish，本实例的 subscriber 会收到自己 publish 的消息——publish 携带实例唯一标识 `_pid`（`wf:{pid}:{seq}`），订阅回调跳过自己的环回，保证每个事件恰好投递一次（防 token 级事件重复/乱序）
 - **与 userSystem 咬合**：`sendTo(ctx.user.id)` 按身份路由、`createConversation(ctx.user.id)` 创建者即身份、成员校验自动对齐——身份是消息的路由，消息是身份的交互
 - **裁剪**：已读回执状态机（只做未读数）、附件存储、全文搜索、消息确认/重试（可靠投递用 queue）、移动端推送
 
@@ -3153,7 +3244,7 @@ return () => <AiChat chat={$} />
 
 ```ts
 app.use(redis())
-app.use(rateLimit({ key: (req) => `login:${req.ip}`, max: 5, windowMs: 60_000 }))  // 防爆破
+app.use(rateLimit({ key: (req) => `login:${req.headers.get('x-forwarded-for')}`, max: 5, windowMs: 60_000 }))  // 防爆破
 app.use(email({ from: 'no-reply@x.com', adapter: 'resend', resend: { apiKey } }))
 app.use(db)
 app.use(users)

package/dist/client/diff.d.ts

@@ -11,5 +11,17 @@ export declare function patchValue(parent: Node, oldNode: Node | null, oldInput:
 export declare function patchProps(el: Element, oldProps: any, newProps: any): void;
 /** 为无 key 的子节点自动分配位置 key，确保 keyed diff 正确性 */
 export declare function ensureKeys(oldChildren: any[], newChildren: any[]): void;
+/**
+ * 将 children 映射到它们实际产生的 DOM 节点（每个 child 一个 Node[]）。
+ *
+ * 1 VNode ≠ 1 DOM 节点：Fragment 展开成多个直属节点（_childNodes），
+ * null/boolean/Portal 产生 0 个。explicitNodes 提供限定范围（Fragment 子项
+ * 用其自身 _childNodes），否则从 source（parent.childNodes 或给定快照）按计数游标分配。
+ */
+export declare function mapChildDomNodes(source: Node[], children: any[]): (Node[] | null)[];
 export declare function normalize(children: any): any[];
-export declare function patchKeyedChildren(parent: Node, oldChildren: any[], newChildren: any[], ctx: WfuiContext): void;
+/**
+ * keyed 子节点 diff。返回每个 new child 的 DOM 节点范围（newNodes，可为空）。
+ * oldNodes：old children → 实际 DOM 节点（mapChildDomNodes 结果）。
+ */
+export declare function patchKeyedChildren(parent: Node, oldChildren: any[], newChildren: any[], ctx: WfuiContext, oldNodes?: (Node[] | null)[], rangeStart?: Node | null): (Node[] | null)[];