weifuwu 0.59.0 → 0.60.0

package/README.md

@@ -1,6 +1,6 @@
 # weifuwu
 
-**全栈框架 — 后端 HTTP 路由 + 前端 VDOM 框架 + 纯 CSS 布局系统**
+**一个包的全栈框架** — 后端 HTTP + 前端 VDOM + 组件库 + CSS 设计系统。全自研、零配置、消灭样板。
 
 ```bash
 npm install weifuwu
@@ -17,21 +17,46 @@ npm install weifuwu
 
 ## 设计理念
 
+### 一句话
+
+**weifuwu = 一个包的全栈框架：全自研、零配置、消灭样板。** 下面三条核心哲学与十条技术原则都是这句话的展开——我们不做缝合框架，每一层都自研且可预测。
+
+### 核心哲学
+
+**① 一个包，全栈一体。** 后端、前端、组件、样式装在一个 npm 包里，零配置、零构建、纯 link 可用：服务端 `--import weifuwu/dev` 直接跑 `.tsx`（Node loader + esbuild 同步编译）；浏览器 CDN import map 直接跑；CSS 一条 link 即得完整设计系统。
+
+**② 全自研，诚实裁剪。** VDOM、PG v3 / RESP2 协议、GraphQL schema、OpenAI 兼容流式协议——全部自研而非包装他人。动机不是炫技而是**确定性**：自研客户端输出确定、行为可预测、错误模型统一。配套纪律是诚实裁剪：**不支持的能力明确抛 `ProtocolError('unsupported')`，绝不静默降级或"尽量支持"**（已裁剪清单见 `docs/db-clients-plan.md`）。
+
+**③ 消灭样板。** 框架的每一层都在消灭一类样板代码：
+
+| 样板 | 消灭方式 |
+|---|---|
+| 构建样板 | 动态编译（`ctx.ui.js` / `weifuwu/dev`），改代码即刷即用，零构建步骤 |
+| 样式样板 | 语义原语 + 变量定制，零自定义 CSS 文件（`--wf-brand-500` 改一层值全站跟随） |
+| 数据样板 | `ctx.data.get` 一个 API 覆盖 SSR 预取 / hydration 命中 / SPA fetch，写数据像写同步代码 |
+| 协议样板 | 自研 PG/Redis 客户端消灭双重编码、parseRow 样板、`'EX'` 参数顺序陷阱 |
+
+### 技术原则（哲学的展开）
+
 **零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `esbuild`（TSX→JS 编译）+ `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 作为运行时依赖随 `npm install weifuwu` 自动安装，`ctx.ui.js()` 开箱即用。
 
-**两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook。
+**两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook——**位置即语义**：外层天生只跑一次，没有 hooks 规则、没有依赖数组、没有闭包陷阱（详解见[核心概念](#核心概念)）。
 
-**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch。也支持手动 `ctx.ui.render()` 精确控制渲染时机。无需手动调用 `useState`/`useEffect`。
+**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch；也支持手动 `ctx.ui.render()` 精确控制渲染时机。**组件库手动优先、业务层自动优先**——同一框架内按角色选模式（详见[组件库](#组件库-weifuwucomponents)）。
 
-**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` 等），Handler/组件从 `ctx` 读取。
+**中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` / `ctx.limit` / `ctx.email` / `ctx.queue` / `ctx.ai` 等），Handler/组件从 `ctx` 读取。
 
-**自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
+**async 工厂组件** — `async (ctx) => (initProps, ctx) => (props) => VNode`：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`$`）、render 输出视图。异步只在工厂边界，mount/render 保持同步；数据经闭包注入，写数据像写同步代码。三条纪律见[核心概念 · async 组件](#核心概念)。
+
+**SPA/SSR/Hydration 统一透明** — 同一份路由定义（`routes`）一个组件三场景自动适配：后端 `uiSsr({ routes })` 匹配即自动 SSR（完整 HTML + `__DATA__`），客户端 `router({ routes })` + `RouteView` + `mount(..., { hydrate: true })` 按 URL 同源匹配并收养服务端 HTML（不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
 
-**SSR + 动态编译** — 后端 `ctx.ui.js()` 用 esbuild 实时编译 TSX，开发时改代码即刷即用，零构建步骤。
+**AI 是一等公民** — 自研 OpenAI 兼容协议（`docs/ai-contract.md`）+ 零依赖流式客户端 + agent 工具循环 + HITL 人工审批。后端 `ctx.ai` 一个入口：`chat()` / `stream()` / `agent()` / `approve()`；前端 `ctx.ui.useChat()`（会话语义）+ `AiChat` 组件（标准对话界面）——流式 token / 工具调用卡 / 审批卡开箱即用，协议对页面完全透明，不用 ai-sdk。
 
-**async 工厂组件** — `async (ctx) => (initProps, ctx) => (props) => VNode`：工厂层声明数据（`await ctx.data.get`）、mount 初始化状态（`$`）、render 输出视图。异步只在工厂边界，mount/render 保持同步；数据经闭包注入，写数据像写同步代码。
+**SaaS 地基随包内置** — rateLimit（限流）/ email（邮件）/ userSystem（用户认证）/ queue（可靠队列）以中间件形态随包提供，`app.use(...)` 一行接入（详见文末[SaaS 地基模块](#saas-地基模块ratelimit--email--usersystem--queue)）。
 
-**SPA/SSR/Hydration 统一透明** — 同一份路由定义（`routes`）一个组件形态三场景自动适配：后端 `uiSsr({ routes })` 匹配即自动 SSR（完整 HTML + `__DATA__`），客户端 `router({ routes })` + `RouteView` + `mount(..., { hydrate: true })` 按 URL 同源匹配并收养服务端 HTML（不重建、无闪跳）。`ctx.data.get` 一个 API：SSR 预取 / hydration 命中（不重复请求）/ SPA 触发 fetch。服务端直接用 `.tsx`（`weifuwu/dev` Node loader），前后端同一 JSX 运行时。
+**零自定义 CSS 设计系统** — 一个 CSS 文件 = 双层 Token + 布局原语 + 工具类 + 组件样式。业务页面不写 style.css：组件 + `wf-*` 原语写业务，品牌/组件定制改变量（`--wf-brand-500` / `--wf-btn-radius`），暗色自动（详见[布局系统](#布局系统-weifuwulayout)）。
+
+**自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
 
 ---
 
@@ -211,7 +236,7 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | 资源 | 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` | 44 个 UI 组件（Button, Card, Table, Modal 等） |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 46 个 UI 组件（Button, Card, Table, Modal 等） |
 | 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 115 个主题 Token + 67 个布局原语 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
@@ -234,7 +259,7 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | `weifuwu` | **email** | 邮件发送（Resend/SMTP 自研/自定义适配器）→ `ctx.email` | Router |
 | `weifuwu` | **userSystem** | 用户系统（scrypt 密码哈希 + 混合会话）→ `ctx.user` / `ctx.auth` + `/api/auth/*` | Router, postgres |
 | `weifuwu` | **queue** | 可靠任务队列（Redis Streams，at-least-once + DLQ）→ `ctx.queue` | Router, redis |
-| `weifuwu` | **ai** | LLM 对话（自研 OpenAI 兼容协议 + 自研 SSE 解码，默认 DeepSeek）→ `ctx.ai` + `aiStream` | Router |
+| `weifuwu` | **ai** | LLM 对话（自研 OpenAI 兼容协议 + 自研 SSE 解码，默认 DeepSeek）→ `ctx.ai` + `ctx.ui.useChat` + `AiChat` | Router |
 | `weifuwu/dev` | **dev loader** | Node loader：服务端直接跑 `.ts/.tsx`（`--import weifuwu/dev`） | esbuild |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
 | `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
@@ -243,14 +268,14 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | Router 方法 | **app.graphql()** | GraphQL 端点（支持 GraphiQL），Router 实例方法（无需单独 import） | Router |
 | `weifuwu/client` | **createApp** | 应用引导 + VDOM 渲染引擎 | — |
 | `weifuwu/client` | **router / RouteView** | 前端路由（history/hash 模式） | createApp |
-| `weifuwu/client` | **asyncComponent** | async 工厂组件（形态 C）：工厂层声明数据，mount/render 同步 | — |
+| `weifuwu/client` | **asyncComponent** | async 工厂组件：工厂层声明数据，mount/render 同步（三条纪律见[核心概念](#核心概念)） | — |
 | `weifuwu/client` | **ctx.data** | 数据管道：SSR 预取 / hydration 命中 / SPA fetch（`ctx.data.get`） | createApp |
 | `weifuwu/client` | **api / auth / ws** | HTTP 客户端 / 认证 / WebSocket 中间件 | createApp |
 | `weifuwu/client` | **i18n** | 国际化中间件（运行时切换语言） | createApp |
 | `weifuwu/client` | **ErrorBoundary** | 错误边界组件 | createApp |
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
 | `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
-| `weifuwu/components` | **44 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
+| `weifuwu/components` | **47 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
 | `weifuwu/layout` | **CSS 布局** | 67 个布局原语 + 115 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
@@ -298,6 +323,49 @@ const Counter = (_init, ctx) => {
 | 读取 | handler 读取 ctx | 组件读取 ctx |
 | 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` / `$.x = val` 触发局部 VDOM patch |
 
+### async 组件（三条纪律）
+
+`asyncComponent` 让"拿数据渲染页面"像写同步代码——三层结构：**工厂**（async，只执行一次，声明数据）→ **mount**（初始化 `$`）→ **render**（输出视图）。异步只在工厂边界：
+
+```tsx
+const UserProfile = asyncComponent(async (ctx) => {
+  const user = await ctx.data.get(`/api/user/${ctx.params.id}`)   // ① 工厂层：声明数据
+  return (_init, ctx) => {
+    const $ = ctx.ui.$()
+    $.liked = false                                               // ② mount：客户端状态
+    return (props) =>
+      h('div', {},
+        h('p', {}, user.name),          // 服务端状态（闭包，SSR 进 HTML）
+        h('button', { onClick: () => $.liked = !$.liked }, $.liked ? '❤️' : '🤍'))
+  }
+})
+```
+
+**三条纪律**（不遵守就是隐性 bug）：
+
+| 纪律 | 反例 | 正确 |
+|---|---|---|
+| ① 数据 key 必须含维度 | `ctx.data.get('/api/user')`——`/users/1 → /users/2` 导航命中旧缓存 | `ctx.data.get(\`/api/user/${ctx.params.id}\`)` |
+| ② 会变的数据放 `$` | `const count = data.count`——点击永不更新 | `$.count = data.count`（初始值 seed 自服务端数据） |
+| ③ 初始状态必须确定性 | `$.w = window.innerWidth`——SSR/hydration mismatch | 用服务端数据 seed，交互后再测 |
+
+**常见坑**：
+- 工厂**拿不到 props**——数据维度从 `ctx.params` / `ctx.data` 取
+- 闭包数据是页面加载时的**快照**——路由参数变化靠工厂重跑刷新（key 变 → 缓存 miss → 重新取数）；工厂缓存绑定页面上下文，路由导航/登录登出时自动失效
+- **个性化数据不进 `ctx.data`**——SSR 会把工厂取数结果序列化给所有客户端，会话/用户相关数据留在 `$` + fetch
+
+### 渲染策略：SPA 还是 SSR？
+
+组件与路由的写法**完全一样**，差异只有入口两行：
+
+| | SPA | SSR + Hydration |
+|---|---|---|
+| 适用 | 应用页（后台、工具、Dashboard） | 内容页（博客、营销，需要 SEO/首屏） |
+| 后端 | HTML 外壳 | `uiSsr({ routes })` 一行（自动完整 HTML + `__DATA__`） |
+| 客户端 | `mount('#root', RouteView)` | `mount('#root', RouteView, { hydrate: true })` |
+
+**怎么选**：默认 SPA；需要 SEO 或首屏即内容时用 SSR。两种模式可混合——一个 app 内 `uiSsr` 匹配共享路由，未匹配 `next()` 走普通 handler。
+
 ### Closeable 接口
 
 所有有状态模块（postgres、redis）实现 `close(): Promise<void>`，serve 关闭时自动调用。
@@ -1651,7 +1719,7 @@ const UserProfile: Component = (initProps, ctx) => {
 }
 ```
 
-### asyncComponent 工厂（形态 C）— 同步式数据声明
+### asyncComponent 工厂（async 组件）— 同步式数据声明
 
 `async (ctx) => (initProps, ctx) => (props) => VNode` — 工厂层（async，只执行一次并缓存）声明数据/加载代码，mount/render 保持同步。数据经闭包注入组件，渲染无 loading 分支：
 
@@ -2148,7 +2216,7 @@ import type { RouterOptions } from 'weifuwu/client'
 
 # 组件库 (`weifuwu/components`)
 
-44 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+46 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -2368,6 +2436,7 @@ props 变化 ──────────────────────
 
 | 组件 | 导入名 | 关键 Props | 说明 |
 |-----|--------|-----------|------|
+| AiChat | `AiChat` | `chat`, `maxHeight?`, `labels?`, `renderMessage?`, `renderToolArgs?` | 标准 AI 对话界面：气泡 + 工具卡 + 审批卡 + 自动滚动 + 错误重试（接收 `ctx.ui.useChat()` handle） |
 | ToolCallCard | `ToolCallCard` | `call`, `progress?`, `result?`, `renderArgs?` | 工具调用卡片：running（进度条）/ ok / error 三态（协议 §4） |
 | ApprovalCard | `ApprovalCard` | `request`, `status?`, `onApprove`, `onReject` | 人工审批卡片：待批（允许/拒绝+备注）/ 已批 / 已拒 / 超时（协议 §4.5） |
 
@@ -2403,7 +2472,6 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 ```
 
 也支持相对路径：`ctx.ui.css('./src/style.css')`。
-```
 
 ## 67 个布局原语
 
@@ -2998,6 +3066,22 @@ const handle = aiStream('/api/chat', { messages }, {
 handle.abort()  // 用户停止/组件卸载/导航跳走
 ```
 
+前端对话层（会话语义 + 标准界面，协议对页面透明）：
+
+```tsx
+// ctx.ui.useChat：会话语义（消息累积/工具内嵌/审批/重试），返回页面同一个 $
+const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+// $.messages / $.input / $.streaming / $.error / $.usage / $.step
+// $.send() / $.stop() / $.retry() / $.clear() / $.approve('approved', note?)
+
+// AiChat：标准对话界面（气泡 / 工具卡 / 审批卡 / 自动滚动 / 错误重试）
+return () => <AiChat chat={$} />
+
+// agent 模式消息内嵌：msg.toolCalls（ToolCallCard 直接消费）/ msg.approval（ApprovalCard）
+```
+
+> 分层：`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](./docs/ai-contract.md)）
 - **agent 引擎**：`a.agent({ systemPrompt, tools, humanInTheLoop })` 工具循环（LLM → tool_call → 执行 → 回喂 → 重复）；工具可 `emit` 进度/自定义事件、接收 `signal` 取消；HITL 审批（`ctx.ai.approve` 响应，拒绝≠终止、modified 改参、超时兜底）
 - **零依赖**：自研 OpenAI 兼容客户端（fetch + SSE 解析），默认 DeepSeek，`baseUrl` 可换任意 OpenAI 兼容端点（Ollama/vLLM/Moonshot…）

package/dist/client/index.d.ts

@@ -33,6 +33,8 @@ export { extendCtx } from './types.ts';
 export type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
 export { aiStream } from './ai.ts';
 export type { AiStreamCallbacks, AiStreamOptions, AiStreamHandle } from './ai.ts';
+export { toChatMessages } from './use-chat.ts';
+export type { UiMessage, UiToolCall, UseChatOptions, UseChatState, UseChatHandle, ChatApi } from './use-chat.ts';
 export type { WfStreamEvent, WfMessageStart, WfToken, WfUsage, WfDone, WfError, WfErrorCode, WfToolCall, WfToolResult, WfToolProgress, WfStep, WfApprovalRequest, WfApprovalResponse, WfApprovalDecision, ChatMessage, ChatParams, MessageRole, ToolCall, ToolDefinition, } from '../ai/types.ts';
 export { ErrorBoundary } from './error-boundary.ts';
 export type { ErrorBoundaryProps } from './error-boundary.ts';

package/dist/client/index.js

@@ -838,6 +838,7 @@ async function hydrateVNode(container, vnode, ctx) {
 // src/client/reactive.ts
 function createReactiveState(dirty) {
   const proxyCache = /* @__PURE__ */ new WeakMap();
+  const watchers = /* @__PURE__ */ new Set();
   const reactive = (target) => {
     if (target === null || typeof target !== "object") return target;
     if (proxyCache.has(target)) return proxyCache.get(target);
@@ -847,6 +848,7 @@ function createReactiveState(dirty) {
         if (old === value) return true;
         Reflect.set(target2, key, value);
         dirty();
+        for (const w of watchers) w();
         return true;
       },
       get(target2, key) {
@@ -858,6 +860,7 @@ function createReactiveState(dirty) {
         if (Reflect.has(target2, key)) {
           Reflect.deleteProperty(target2, key);
           dirty();
+          for (const w of watchers) w();
         }
         return true;
       }
@@ -865,7 +868,326 @@ function createReactiveState(dirty) {
     proxyCache.set(target, proxy);
     return proxy;
   };
-  return reactive({});
+  const root = reactive({});
+  Object.defineProperty(root, "__watch", {
+    value: (cb) => {
+      watchers.add(cb);
+      return () => {
+        watchers.delete(cb);
+      };
+    },
+    writable: false,
+    enumerable: false
+  });
+  return root;
+}
+
+// src/client/ai.ts
+var RECORD_LIMIT = 1e3;
+function aiStream(url, body, options) {
+  const controller = new AbortController();
+  const external = options?.signal;
+  if (external) {
+    if (external.aborted) controller.abort();
+    else external.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  const traceId = options?.traceId ?? randomId();
+  const record = options?.record !== false;
+  const events = [];
+  const done = (async () => {
+    let res;
+    try {
+      res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Trace-Id": traceId,
+          Accept: "text/event-stream",
+          ...options?.headers
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (controller.signal.aborted) return;
+      options?.onError?.({ code: "provider_error", message: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    if (!res.ok) {
+      options?.onError?.({
+        code: httpErrorCode(res.status),
+        message: `HTTP ${res.status} ${res.statusText}`
+      });
+      return;
+    }
+    try {
+      for await (const { name, data } of parseWfEvents(res.body)) {
+        if (controller.signal.aborted) return;
+        pushEvent(events, { name, data }, record);
+        dispatch(name, data, options ?? {});
+      }
+    } catch (err) {
+      if (controller.signal.aborted) return;
+      options?.onError?.({ code: "provider_error", message: err instanceof Error ? err.message : String(err) });
+    }
+  })();
+  return {
+    abort: () => controller.abort(),
+    done,
+    traceId,
+    events
+  };
+}
+function dispatch(name, data, o) {
+  switch (name) {
+    case "wf:token":
+      return o.onToken?.(data.text);
+    case "wf:tool_call":
+      return o.onToolCall?.(data);
+    case "wf:tool_result":
+      return o.onToolResult?.(data);
+    case "wf:tool_progress":
+      return o.onToolProgress?.(data);
+    case "wf:step":
+      return o.onStep?.(data);
+    case "wf:approval_request":
+      return o.onApproval?.(data);
+    case "wf:usage":
+      return o.onUsage?.(data);
+    case "wf:done":
+      return o.onDone?.(data);
+    case "wf:error":
+      return o.onError?.(data);
+    default:
+      return o.onEvent?.(name, data);
+  }
+}
+async function* parseWfEvents(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const blocks = buffer.split("\n\n");
+      buffer = blocks.pop() ?? "";
+      for (const block of blocks) {
+        let name = "message";
+        let data = "";
+        for (const line of block.split("\n")) {
+          if (line.startsWith("event: ")) name = line.slice(7);
+          else if (line.startsWith("data: ")) data += line.slice(6);
+        }
+        if (!data) continue;
+        try {
+          yield { name, data: JSON.parse(data) };
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function pushEvent(events, e, record) {
+  if (!record) return;
+  if (events.length >= RECORD_LIMIT) events.shift();
+  events.push(e);
+}
+function httpErrorCode(status) {
+  if (status === 401 || status === 403) return "auth_failed";
+  if (status === 429) return "rate_limited";
+  if (status >= 500) return "provider_error";
+  return "invalid_request";
+}
+function randomId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `trace-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/client/use-chat.ts
+function toChatMessages(msgs) {
+  return msgs.map((m) => ({ role: m.role, content: m.content }));
+}
+function uid() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function createChatSession(state, transport, options) {
+  if (options.initialMessages) {
+    state.messages = structuredClone(options.initialMessages);
+  } else if (state.messages === void 0) state.messages = [];
+  if (state.input === void 0) state.input = "";
+  if (state.streaming === void 0) state.streaming = false;
+  if (state.error === void 0) state.error = null;
+  if (state.usage === void 0) state.usage = null;
+  if (state.step === void 0) state.step = null;
+  let handle = null;
+  function current() {
+    if (!state.streaming) return void 0;
+    const m = state.messages[state.messages.length - 1];
+    return m && m.role === "assistant" && m.status === "streaming" ? m : void 0;
+  }
+  function apply(name, data, onEvent) {
+    const m = current();
+    switch (name) {
+      case "wf:token":
+        if (m) m.content += data.text;
+        break;
+      case "wf:tool_call": {
+        if (m) {
+          if (!m.toolCalls) m.toolCalls = [];
+          m.toolCalls.push({ call: data, status: "running" });
+        }
+        break;
+      }
+      case "wf:tool_progress": {
+        const p = data;
+        const tc = m?.toolCalls?.find((t) => t.call.id === p.toolCallId);
+        if (tc) tc.progress = p;
+        break;
+      }
+      case "wf:tool_result": {
+        const r = data;
+        const tc = m?.toolCalls?.find((t) => t.call.id === r.id);
+        if (tc) {
+          tc.result = r;
+          tc.status = r.ok ? "ok" : "error";
+        }
+        break;
+      }
+      case "wf:approval_request":
+        if (m) m.approval = data;
+        break;
+      case "wf:usage":
+        if (m) m.usage = data;
+        break;
+      case "wf:step":
+        state.step = data;
+        break;
+      case "wf:done":
+        if (m) {
+          m.status = "done";
+          m.approval = void 0;
+        }
+        state.streaming = false;
+        state.step = null;
+        break;
+      case "wf:error":
+        if (m) {
+          m.status = "error";
+          m.error = data;
+          m.approval = void 0;
+        }
+        state.error = data;
+        state.streaming = false;
+        state.step = null;
+        break;
+      default:
+        onEvent?.(name, data);
+        break;
+    }
+  }
+  function startStream() {
+    const body = options.body ? options.body(state.messages) : { messages: toChatMessages(state.messages) };
+    handle = transport(options.url, body, {
+      onToken: (t) => apply("wf:token", { text: t }),
+      onToolCall: (c) => apply("wf:tool_call", c),
+      onToolProgress: (p) => apply("wf:tool_progress", p),
+      onToolResult: (r) => apply("wf:tool_result", r),
+      onApproval: (req) => apply("wf:approval_request", req),
+      onUsage: (u) => apply("wf:usage", u),
+      onStep: (s) => apply("wf:step", s),
+      onDone: (d) => apply("wf:done", d),
+      onError: (e) => apply("wf:error", e),
+      onEvent: (n, d) => apply(n, d, options.onEvent)
+    }, { signal: options.signal, headers: options.headers });
+    state.streaming = true;
+    const m = current();
+    if (m && handle?.traceId) m.id = handle.traceId;
+  }
+  function send() {
+    if (state.streaming) return;
+    const text = String(state.input ?? "").trim();
+    if (!text) return;
+    state.input = "";
+    state.error = null;
+    state.usage = null;
+    state.step = null;
+    state.messages.push(
+      { id: uid(), role: "user", content: text, status: "done" },
+      { id: uid(), role: "assistant", content: "", status: "streaming", toolCalls: [] }
+    );
+    startStream();
+  }
+  function stop() {
+    handle?.abort();
+    state.streaming = false;
+    state.step = null;
+    const m = state.messages[state.messages.length - 1];
+    if (m && m.role === "assistant" && m.status === "streaming") {
+      if (!m.content && (!m.toolCalls || m.toolCalls.length === 0)) {
+        state.messages.pop();
+      } else {
+        m.status = "done";
+      }
+    }
+  }
+  function retry() {
+    if (state.streaming) return;
+    let idx = -1;
+    for (let i = state.messages.length - 1; i >= 0; i--) {
+      if (state.messages[i].role === "user") {
+        idx = i;
+        break;
+      }
+    }
+    if (idx === -1) return;
+    state.messages.splice(idx + 1);
+    state.error = null;
+    state.usage = null;
+    state.step = null;
+    state.messages.push({ id: uid(), role: "assistant", content: "", status: "streaming", toolCalls: [] });
+    startStream();
+  }
+  function clear() {
+    handle?.abort();
+    state.messages = [];
+    state.input = "";
+    state.streaming = false;
+    state.error = null;
+    state.usage = null;
+    state.step = null;
+  }
+  async function approve(decision, note) {
+    const m = state.messages[state.messages.length - 1];
+    const req = m?.role === "assistant" ? m.approval : void 0;
+    if (!req) return;
+    m.approval = void 0;
+    if (!options.approveUrl) return;
+    try {
+      await fetch(options.approveUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...options.headers },
+        body: JSON.stringify({ id: req.id, decision, note }),
+        signal: options.signal
+      });
+    } catch (err) {
+      if (options.signal?.aborted) return;
+      state.error = { code: "provider_error", message: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  function dispose() {
+    handle?.abort();
+    handle = null;
+  }
+  return { send, stop, retry, clear, approve, dispose };
 }
 
 // src/client/app.ts
@@ -1050,6 +1372,31 @@ function createApp() {
           }
           return this._$cache;
         },
+        /**
+         * AI 对话会话（会话语义 + 工具调用内嵌 + HITL 审批）
+         *
+         * 用法（mount 阶段）：
+         *   const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+         *   // 状态：$.messages / $.input / $.streaming / $.error / $.usage / $.step
+         *   // 操作：$.send() / $.stop() / $.retry() / $.clear() / $.approve('approved', note?)
+         *   // agent：msg.toolCalls（ToolCallCard 直接消费） / msg.approval（ApprovalCard）
+         *
+         * 返回组件同一个 $（WeakMap 缓存复用）：chat 状态与页面状态共处一个容器。
+         * 卸载时调用 $.dispose()（或经 ref cleanup）中止流，防泄漏。
+         */
+        useChat: function(options2) {
+          const state = this.$();
+          const api2 = createChatSession(state, aiStream, options2);
+          Object.assign(state, {
+            send: api2.send,
+            stop: api2.stop,
+            retry: api2.retry,
+            clear: api2.clear,
+            approve: api2.approve,
+            dispose: api2.dispose
+          });
+          return state;
+        },
         /**
          * 响应式媒体查询：注册监听，值变化时自动 dirty
          *
@@ -1584,133 +1931,6 @@ function auth(options) {
   };
 }
 
-// src/client/ai.ts
-var RECORD_LIMIT = 1e3;
-function aiStream(url, body, options) {
-  const controller = new AbortController();
-  const external = options?.signal;
-  if (external) {
-    if (external.aborted) controller.abort();
-    else external.addEventListener("abort", () => controller.abort(), { once: true });
-  }
-  const traceId = options?.traceId ?? randomId();
-  const record = options?.record !== false;
-  const events = [];
-  const done = (async () => {
-    let res;
-    try {
-      res = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "X-Trace-Id": traceId,
-          Accept: "text/event-stream",
-          ...options?.headers
-        },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-    } catch (err) {
-      if (controller.signal.aborted) return;
-      options?.onError?.({ code: "provider_error", message: err instanceof Error ? err.message : String(err) });
-      return;
-    }
-    if (!res.ok) {
-      options?.onError?.({
-        code: httpErrorCode(res.status),
-        message: `HTTP ${res.status} ${res.statusText}`
-      });
-      return;
-    }
-    try {
-      for await (const { name, data } of parseWfEvents(res.body)) {
-        if (controller.signal.aborted) return;
-        pushEvent(events, { name, data }, record);
-        dispatch(name, data, options ?? {});
-      }
-    } catch (err) {
-      if (controller.signal.aborted) return;
-      options?.onError?.({ code: "provider_error", message: err instanceof Error ? err.message : String(err) });
-    }
-  })();
-  return {
-    abort: () => controller.abort(),
-    done,
-    traceId,
-    events
-  };
-}
-function dispatch(name, data, o) {
-  switch (name) {
-    case "wf:token":
-      return o.onToken?.(data.text);
-    case "wf:tool_call":
-      return o.onToolCall?.(data);
-    case "wf:tool_result":
-      return o.onToolResult?.(data);
-    case "wf:tool_progress":
-      return o.onToolProgress?.(data);
-    case "wf:step":
-      return o.onStep?.(data);
-    case "wf:approval_request":
-      return o.onApproval?.(data);
-    case "wf:usage":
-      return o.onUsage?.(data);
-    case "wf:done":
-      return o.onDone?.(data);
-    case "wf:error":
-      return o.onError?.(data);
-    default:
-      return o.onEvent?.(name, data);
-  }
-}
-async function* parseWfEvents(stream) {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      const blocks = buffer.split("\n\n");
-      buffer = blocks.pop() ?? "";
-      for (const block of blocks) {
-        let name = "message";
-        let data = "";
-        for (const line of block.split("\n")) {
-          if (line.startsWith("event: ")) name = line.slice(7);
-          else if (line.startsWith("data: ")) data += line.slice(6);
-        }
-        if (!data) continue;
-        try {
-          yield { name, data: JSON.parse(data) };
-        } catch {
-        }
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-function pushEvent(events, e, record) {
-  if (!record) return;
-  if (events.length >= RECORD_LIMIT) events.shift();
-  events.push(e);
-}
-function httpErrorCode(status) {
-  if (status === 401 || status === 403) return "auth_failed";
-  if (status === 429) return "rate_limited";
-  if (status >= 500) return "provider_error";
-  return "invalid_request";
-}
-function randomId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
-  }
-  return `trace-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-}
-
 // src/client/error-boundary.ts
 function ErrorBoundary(props, ctx) {
   let error = null;
@@ -1987,6 +2207,7 @@ export {
   jsxs,
   lockScroll,
   router,
+  toChatMessages,
   trapFocus,
   unlockScroll,
   ws,

package/dist/client/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * weifuwu/client 类型定义
  */
+import type { UseChatHandle, UseChatOptions } from './use-chat.ts';
 /** 弹层位置跟踪配置 — 供 ctx.ui.usePopupPosition 使用 */
 export interface PopupPositionOptions {
     /** 锚定元素 getter（通常是 ref 保存的触发元素） */
@@ -33,6 +34,16 @@ export interface WfuiContext {
         dirty: (ids?: string[]) => void;
         /** 创建响应式状态容器：$.x = val 自动触发 dirty() */
         $: () => Record<string, any>;
+        /**
+         * AI 对话会话：$ 超集（会话语义 + 工具调用内嵌 + HITL 审批）
+         *
+         * ```tsx
+         * const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+         * // $.messages / $.input / $.streaming / $.error / $.usage / $.step
+         * // $.send() / $.stop() / $.retry() / $.clear() / $.approve(decision, note?)
+         * ```
+         */
+        useChat: (options: UseChatOptions) => UseChatHandle;
         /** 弹层位置跟踪：滚动/resize 时自动重算 fixed 坐标 */
         usePopupPosition: (options: PopupPositionOptions) => PopupPosition;
         /** 注册组件实例的自定义语义 ID，同名冲突抛错 */

package/dist/client/use-chat.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ctx.ui.useChat — AI 会话语义层（client）
+ *
+ * 在 aiStream（传输解码）之上加一层「一段对话」的语义：
+ * 消息累积、工具调用内嵌、HITL 审批、错误恢复、stop/retry/clear。
+ *
+ * - 协议透明：消费 wf: 事件（docs/ai-contract.md），页面不需要知道事件名
+ * - 状态即 $：useChat 返回组件同一个响应式 Proxy，赋值自动渲染
+ * - 就地累积：token 经 state.messages[idx] 代理就地 append（O(1)/token，
+ *   不重建数组；配合 key 稳定引用 → VDOM 只 patch 文本节点）
+ * - 工具内嵌：wf:tool_call/progress/result 按 toolCallId/id 聚合到
+ *   消息的 toolCalls[]，ToolCallCard 直接消费（call/progress/result）
+ * - 审批：approval 挂消息，approve() POST approveUrl（协议 §4.5）
+ * - 生命周期：dispose() 中止流（组件 ref cleanup 调用；卸载防泄漏）
+ *
+ * 核心与框架无关：transport 注入（默认 aiStream），node 直接测。
+ */
+import type { AiStreamCallbacks, AiStreamHandle } from './ai.ts';
+import type { ChatMessage, WfApprovalDecision, WfApprovalRequest, WfError, WfStep, WfToolCall, WfToolProgress, WfToolResult, WfUsage } from '../ai/types.ts';
+/** 工具调用显示条目：ToolCallCard 的三个 props 聚合 + 状态机 */
+export interface UiToolCall {
+    call: WfToolCall;
+    progress?: WfToolProgress;
+    result?: WfToolResult;
+    status: 'running' | 'ok' | 'error';
+}
+/** 对话消息（显示模型）：provider 形状 + UI 状态字段 */
+export interface UiMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    status: 'streaming' | 'done' | 'error';
+    usage?: WfUsage;
+    toolCalls?: UiToolCall[];
+    approval?: WfApprovalRequest;
+    error?: WfError;
+}
+/** useChat 会话状态（挂在 $ 上，赋值自动渲染） */
+export interface UseChatState {
+    messages: UiMessage[];
+    input: string;
+    streaming: boolean;
+    error: WfError | null;
+    usage: WfUsage | null;
+    /** 最近 wf:step（思考/工具指示），done/error 时清空 */
+    step: WfStep | null;
+    /** 页面自有状态与 chat 状态共处一个 $（与 ctx.ui.$() 一致） */
+    [key: string]: any;
+}
+/** useChat 操作（挂到 $ 上的方法；调用不触发渲染，内部 set 触发） */
+export interface ChatApi {
+    /** 发送当前输入：追加 user + assistant 占位 → POST url */
+    send: () => void;
+    /** 中止当前流；空占位移除，有内容则标记 done */
+    stop: () => void;
+    /** 截断到最后一条 user 消息并重新生成其回复（错误恢复） */
+    retry: () => void;
+    /** 清空会话并中止 */
+    clear: () => void;
+    /** 响应 HITL 审批（协议 §4.5）：清卡片 + POST approveUrl */
+    approve: (decision: WfApprovalDecision, note?: string) => Promise<void>;
+    /** 中止流并释放（组件卸载时调用） */
+    dispose: () => void;
+    /** 内部：订阅会话状态变更（AiChat 等共享 $ 的子组件用；返回退订）。
+     *  父组件 dirty 只驱动自身重渲染，共享 handle 的子组件需自行订阅。 */
+    __watch?: (cb: () => void) => () => void;
+}
+export type UseChatHandle = UseChatState & ChatApi;
+export interface UseChatOptions {
+    /** POST 端点（返回 wf: SSE 流） */
+    url: string;
+    /** HITL 审批上行端点（协议 §4.5）；缺省时 approve() 只清卡片不请求 */
+    approveUrl?: string;
+    /** 历史会话种子（app 数据注入；hook 不持有持久化） */
+    initialMessages?: UiMessage[];
+    /** 定制请求体（agent 模式携带 tools/mode 等）；缺省 { messages } */
+    body?: (messages: UiMessage[]) => unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** x:* 自定义事件透传（协议 §6） */
+    onEvent?: (name: string, data: unknown) => void;
+}
+/** 传输层（默认 aiStream）：POST + SSE 解析 + abort */
+export type ChatTransport = (url: string, body: unknown, callbacks: AiStreamCallbacks, opts?: {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}) => AiStreamHandle;
+/** UiMessage[] → provider ChatMessage[]（剥离 UI 字段） */
+export declare function toChatMessages(msgs: UiMessage[]): ChatMessage[];
+export declare function createChatSession(state: UseChatState, transport: ChatTransport, options: UseChatOptions): ChatApi;

package/dist/client/vnode.d.ts

@@ -7,7 +7,7 @@
  *   --jsxImportSource=weifuwu/client
  */
 import type { WfuiContext } from './types.ts';
-export type VNodeType = string | Component | AsyncComponent | typeof Fragment | typeof Portal;
+export type VNodeType = string | Component<any, any> | AsyncComponent | typeof Fragment | typeof Portal;
 export interface VNode {
     type: VNodeType;
     props: Record<string, any>;

package/dist/components/AiChat/AiChat.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AiChat — 标准 AI 对话组件（useChat 的标准展示层）
+ *
+ * 组件库第一个领域复合组件：接收 ctx.ui.useChat() 返回的 handle，
+ * 渲染完整对话界面：消息气泡、工具调用卡（ToolCallCard）、HITL 审批卡
+ * （ApprovalCard）、思考/工具状态、usage、错误 + 重试、输入条 + 自动滚动。
+ *
+ * 分工：
+ *   - useChat（hook）= 会话语义 + 协议（数据层）
+ *   - AiChat（组件）= 标准界面（展示层，5 分钟出可交互对话页）
+ *   - 需要完全自定义 UI 的应用直接用 useChat + 自有渲染（hook 保持灵活路径）
+ *
+ * 约定（手动优先）：内部无 $，let + 事件；自动滚动经 ref + scroll 事件。
+ * 文案默认中文（与 ToolCallCard/ApprovalCard 一致），labels 可覆盖。
+ *
+ * ```tsx
+ * const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+ * return () => h(AiChat, { chat: $ })
+ * ```
+ */
+import type { Component } from '../../client/vnode.ts';
+import type { UseChatHandle, UiMessage } from '../../client/use-chat.ts';
+import type { WfError, WfUsage } from '../../ai/types.ts';
+export interface AiChatLabels {
+    send: string;
+    stop: string;
+    retry: string;
+    thinking: string;
+    runningTool: (name?: string) => string;
+    tokens: (u: WfUsage) => string;
+    error: (e: WfError) => string;
+    placeholder: string;
+    empty: string;
+}
+export interface AiChatProps {
+    /** ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） */
+    chat: UseChatHandle;
+    /** 消息列表最大高度（默认 '70vh'） */
+    maxHeight?: string;
+    /** 界面文案覆盖 */
+    labels?: Partial<AiChatLabels>;
+    /** 自定义气泡渲染逃生舱（默认纯文本） */
+    renderMessage?: (msg: UiMessage) => any;
+    /** 工具参数渲染（透传 ToolCallCard） */
+    renderToolArgs?: (args: Record<string, unknown>) => any;
+}
+export declare const AiChat: Component<AiChatProps>;

package/dist/components/index.d.ts

@@ -98,3 +98,5 @@ export { ToolCallCard } from './ToolCallCard/ToolCallCard.ts';
 export type { ToolCallCardProps } from './ToolCallCard/ToolCallCard.ts';
 export { ApprovalCard } from './ApprovalCard/ApprovalCard.ts';
 export type { ApprovalCardProps, ApprovalStatus } from './ApprovalCard/ApprovalCard.ts';
+export { AiChat } from './AiChat/AiChat.ts';
+export type { AiChatProps, AiChatLabels } from './AiChat/AiChat.ts';

package/dist/components/index.js

@@ -3205,8 +3205,130 @@ var ApprovalCard = (_init, ctx) => {
     ]);
   };
 };
+
+// src/components/AiChat/AiChat.ts
+var defaultLabels = {
+  send: "\u53D1\u9001",
+  stop: "\u505C\u6B62",
+  retry: "\u91CD\u8BD5",
+  thinking: "\u{1F914} \u601D\u8003\u4E2D\u2026",
+  runningTool: (name) => name ? `\u2699\uFE0F \u6267\u884C\u5DE5\u5177 ${name}` : "\u2699\uFE0F \u6267\u884C\u5DE5\u5177\u2026",
+  tokens: (u) => `tokens: ${u.prompt_tokens}\u2192${u.completion_tokens}`,
+  error: (e) => `${e.code}: ${e.message}`,
+  placeholder: "\u8F93\u5165\u6D88\u606F\uFF0C\u56DE\u8F66\u53D1\u9001\u2026",
+  empty: "\u8F93\u5165\u6D88\u606F\u5F00\u59CB\u5BF9\u8BDD\u3002"
+};
+var AiChat = (initProps, ctx) => {
+  let listEl;
+  let stickToBottom = true;
+  const unwatch = initProps.chat.__watch?.(() => ctx.ui.dirty());
+  const onScroll = () => {
+    if (!listEl) return;
+    stickToBottom = listEl.scrollHeight - listEl.scrollTop - listEl.clientHeight < 48;
+  };
+  const scrollToBottom = () => {
+    if (listEl) listEl.scrollTop = listEl.scrollHeight;
+  };
+  const listRef = (el) => {
+    if (el && !listEl) {
+      listEl = el;
+      el.addEventListener("scroll", onScroll);
+      queueMicrotask(scrollToBottom);
+    } else if (!el && listEl) {
+      listEl.removeEventListener("scroll", onScroll);
+      listEl = void 0;
+      unwatch?.();
+    }
+  };
+  return (props) => {
+    const { chat } = props;
+    const labels = { ...defaultLabels, ...props.labels };
+    if (stickToBottom) queueMicrotask(scrollToBottom);
+    const msgs = chat.messages ?? [];
+    const nodes = [];
+    if (msgs.length === 0) {
+      nodes.push(h("p", { class: "wf-aichat-empty" }, labels.empty));
+    }
+    for (const m of msgs) {
+      nodes.push(renderMessage(m, props, labels));
+    }
+    if (chat.step) {
+      nodes.push(
+        h(
+          "div",
+          { class: "wf-aichat-status" },
+          chat.step.type === "llm" ? labels.thinking : labels.runningTool(chat.step.name)
+        )
+      );
+    }
+    if (chat.usage) nodes.push(h("div", { class: "wf-aichat-usage" }, labels.tokens(chat.usage)));
+    if (chat.error) nodes.push(h("div", { class: "wf-aichat-error" }, labels.error(chat.error)));
+    return h("div", { class: "wf-aichat" }, [
+      h("div", {
+        class: "wf-aichat-list",
+        style: { maxHeight: props.maxHeight ?? "70vh" },
+        ref: listRef
+      }, nodes),
+      h("div", { class: "wf-aichat-inputbar" }, [
+        h("input", {
+          class: "wf-aichat-input",
+          value: chat.input ?? "",
+          placeholder: labels.placeholder,
+          onInput: (e) => {
+            chat.input = e.target.value;
+          },
+          onKeyDown: (e) => {
+            if (e.key === "Enter") chat.send();
+          }
+        }),
+        chat.streaming ? h("button", {
+          class: "wf-btn wf-btn--primary wf-btn--sm",
+          type: "button",
+          onClick: () => chat.stop()
+        }, labels.stop) : h("button", {
+          class: "wf-btn wf-btn--primary wf-btn--sm",
+          type: "button",
+          onClick: () => chat.send()
+        }, labels.send),
+        !chat.streaming && chat.error ? h("button", {
+          class: "wf-btn wf-btn--danger wf-btn--sm",
+          type: "button",
+          onClick: () => chat.retry()
+        }, labels.retry) : null
+      ])
+    ]);
+  };
+};
+function renderMessage(m, props, _labels) {
+  const nodes = [];
+  if (m.toolCalls?.length) {
+    const cards = m.toolCalls.map((tc, i) => h(ToolCallCard, {
+      key: `${m.id}-tool-${i}`,
+      call: tc.call,
+      progress: tc.progress,
+      result: tc.result,
+      renderArgs: props.renderToolArgs
+    }));
+    nodes.push(h("div", { class: "wf-aichat-tools" }, cards));
+  }
+  if (m.approval) {
+    const card = h(ApprovalCard, {
+      request: m.approval,
+      onApprove: () => props.chat.approve("approved"),
+      onReject: (note) => props.chat.approve("rejected", note ?? "\u7528\u6237\u62D2\u7EDD")
+    });
+    nodes.push(h("div", { class: "wf-aichat-approval" }, card));
+  }
+  nodes.push(h(
+    "div",
+    { class: `wf-aichat-bubble wf-aichat-bubble--${m.role}` },
+    props.renderMessage ? props.renderMessage(m) : m.content || "\u2026"
+  ));
+  return h("div", { key: m.id, class: `wf-aichat-msg wf-aichat-msg--${m.role}` }, nodes);
+}
 export {
   Accordion,
+  AiChat,
   Alert,
   ApprovalCard,
   Avatar,

package/dist/components/style.css

@@ -4445,4 +4445,115 @@ code {
   color: var(--wf-color-text-secondary);
 }
 
+/* weifuwu/components — AiChat（标准 AI 对话界面） */
+
+.wf-aichat {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-sm, 8px);
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-sm, 14px);
+  line-height: var(--wf-line-height);
+  color: var(--wf-color-text);
+}
+
+.wf-aichat-list {
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-sm, 8px);
+  padding: var(--wf-space-sm, 8px);
+  border: 1px solid var(--wf-color-border);
+  border-radius: var(--wf-radius);
+  background: var(--wf-color-bg);
+}
+
+.wf-aichat-empty {
+  margin: var(--wf-space-lg, 16px) 0;
+  text-align: center;
+  color: var(--wf-color-text-secondary);
+  font-size: var(--wf-font-size-sm, 14px);
+}
+
+.wf-aichat-msg {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wf-gap-xs, 4px);
+}
+
+.wf-aichat-tools,
+.wf-aichat-approval {
+  max-width: 100%;
+}
+
+.wf-aichat-bubble {
+  display: inline-block;
+  max-width: 85%;
+  padding: var(--wf-space-sm, 8px) var(--wf-space-md, 12px);
+  border-radius: var(--wf-radius);
+  font-size: var(--wf-font-size-sm, 14px);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.wf-aichat-msg--user {
+  align-items: flex-end;
+}
+
+.wf-aichat-msg--assistant {
+  align-items: flex-start;
+}
+
+.wf-aichat-bubble--user {
+  background: var(--wf-color-primary);
+  color: #fff;
+}
+
+.wf-aichat-bubble--assistant {
+  background: var(--wf-color-bg-tertiary);
+  color: var(--wf-color-text);
+}
+
+.wf-aichat-status {
+  font-size: var(--wf-font-size-xs, 12px);
+  color: var(--wf-color-info);
+}
+
+.wf-aichat-usage {
+  font-size: var(--wf-font-size-xs, 12px);
+  color: var(--wf-color-text-secondary);
+}
+
+.wf-aichat-error {
+  font-size: var(--wf-font-size-xs, 12px);
+  color: var(--wf-color-error);
+  background: var(--wf-color-error-bg);
+  border-radius: var(--wf-radius);
+  padding: var(--wf-space-sm, 8px);
+}
+
+.wf-aichat-inputbar {
+  display: flex;
+  gap: var(--wf-gap-sm, 8px);
+  align-items: center;
+}
+
+.wf-aichat-input {
+  flex: 1;
+  min-width: 0;
+  height: var(--wf-control-height, 36px);
+  padding: var(--wf-control-pad-y, 6px) var(--wf-space-md, 12px);
+  border: 1px solid var(--wf-color-border);
+  border-radius: var(--wf-radius);
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-sm, 14px);
+  color: var(--wf-color-text);
+  background: var(--wf-color-bg);
+}
+
+.wf-aichat-input:focus {
+  outline: none;
+  border-color: var(--wf-color-primary);
+}
+
 }

package/dist/index.js

@@ -1129,7 +1129,7 @@ function rateLimit(options) {
     if (opts.algorithm === "fixed") {
       const count2 = await redisPool.incr(PREFIX + key);
       if (count2 === 1) {
-        await redisPool.expire(PREFIX + key, Math.ceil(windowMs / 1e3));
+        await redisPool.command("PEXPIRE", PREFIX + key, windowMs);
       }
       return {
         allowed: count2 <= max,
@@ -2401,6 +2401,7 @@ function queue(options) {
       const consumer = opts?.consumer ?? `${hostname()}-${process.pid}-${Math.random().toString(36).slice(2, 6)}`;
       const concurrency = opts?.concurrency ?? 1;
       const visibilityTimeout = opts?.visibilityTimeout ?? 3e4;
+      const blockMs = opts?.blockMs ?? 1e3;
       const s = stream(name);
       const dead = deadStream(name);
       const delayed = `${prefix}${name}:delayed`;
@@ -2520,7 +2521,7 @@ function queue(options) {
               "COUNT",
               String(concurrency),
               "BLOCK",
-              "1000",
+              String(blockMs),
               "STREAMS",
               s,
               ">"
@@ -2977,6 +2978,7 @@ var Portal = /* @__PURE__ */ Symbol("Portal");
 // src/client/reactive.ts
 function createReactiveState(dirty) {
   const proxyCache = /* @__PURE__ */ new WeakMap();
+  const watchers = /* @__PURE__ */ new Set();
   const reactive = (target) => {
     if (target === null || typeof target !== "object") return target;
     if (proxyCache.has(target)) return proxyCache.get(target);
@@ -2986,6 +2988,7 @@ function createReactiveState(dirty) {
         if (old === value) return true;
         Reflect.set(target2, key, value);
         dirty();
+        for (const w of watchers) w();
         return true;
       },
       get(target2, key) {
@@ -2997,6 +3000,7 @@ function createReactiveState(dirty) {
         if (Reflect.has(target2, key)) {
           Reflect.deleteProperty(target2, key);
           dirty();
+          for (const w of watchers) w();
         }
         return true;
       }
@@ -3004,7 +3008,18 @@ function createReactiveState(dirty) {
     proxyCache.set(target, proxy);
     return proxy;
   };
-  return reactive({});
+  const root = reactive({});
+  Object.defineProperty(root, "__watch", {
+    value: (cb) => {
+      watchers.add(cb);
+      return () => {
+        watchers.delete(cb);
+      };
+    },
+    writable: false,
+    enumerable: false
+  });
+  return root;
 }
 
 // src/ui/ssr.ts
@@ -3060,7 +3075,28 @@ function createSsrContext(serverCtx, dataStore) {
     useBreakpoint: () => {
     },
     usePopupPosition: () => ({ top: 0, left: 0, refresh: () => {
-    } })
+    } }),
+    // SSR 确定性空态：会话不启动（无事件/无网络），仅保证挂载不崩
+    useChat: () => ({
+      messages: [],
+      input: "",
+      streaming: false,
+      error: null,
+      usage: null,
+      step: null,
+      send: () => {
+      },
+      stop: () => {
+      },
+      retry: () => {
+      },
+      clear: () => {
+      },
+      approve: async () => {
+      },
+      dispose: () => {
+      }
+    })
   };
   const ctx = Object.create(serverCtx ?? {});
   ctx.ui = ui2;

package/dist/queue/index.d.ts

@@ -57,6 +57,10 @@ export interface WorkerOptions {
     visibilityTimeout?: number;
     /** 消费组 consumer 名（多实例自动 hostname-pid，可覆盖） */
     consumer?: string;
+    /** XREADGROUP 阻塞等待时长（ms）。默认 1000。
+     *  越小失败重投延迟越低（重投间隔 = max(visibilityTimeout, blockMs)），
+     *  测试用短值提速；生产保持默认。 */
+    blockMs?: number;
 }
 export interface QueueWorker {
     /** 启动消费循环（阻塞直到 stop） */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {