weifuwu 0.56.1 → 0.58.0

package/README.md

@@ -230,6 +230,11 @@ createApp().use(router({ routes })).mount('#root', RouteView, { hydrate: true })
 | `weifuwu` | **redis** | Redis 客户端（自研 RESP2 协议）→ `ctx.redis` | Router, REDIS_URL |
 | `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
 | `weifuwu` | **uiSsr** | 路由级 SSR：匹配 routes → 自动完整 HTML + `__DATA__` + bundle | Router, ui |
+| `weifuwu` | **rateLimit** | 限流中间件（fixed/sliding，redis 多实例原子）→ `ctx.limit` | Router, redis |
+| `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/dev` | **dev loader** | Node loader：服务端直接跑 `.ts/.tsx`（`--import weifuwu/dev`） | esbuild |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
 | `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
@@ -1019,6 +1024,8 @@ app.get('/secure', () => {
 
 ## 响应辅助函数
 
+> 以下为完整 API 参考，按需查阅。四个 SaaS 地基模块（rateLimit / email / userSystem / queue）见文末「SaaS 地基模块」章节。
+
 消除 `Response.json(...)` 重复模式：
 
 ```ts
@@ -2357,6 +2364,13 @@ props 变化 ──────────────────────
 |-----|--------|-----------|------|
 | Divider | `Divider` | `orientation`, `plain` | 分割线（水平/垂直/带文字） |
 
+### AI 交互原语（wf: 协议配套）
+
+| 组件 | 导入名 | 关键 Props | 说明 |
+|-----|--------|-----------|------|
+| ToolCallCard | `ToolCallCard` | `call`, `progress?`, `result?`, `renderArgs?` | 工具调用卡片：running（进度条）/ ok / error 三态（协议 §4） |
+| ApprovalCard | `ApprovalCard` | `request`, `status?`, `onApprove`, `onReject` | 人工审批卡片：待批（允许/拒绝+备注）/ 已批 / 已拒 / 超时（协议 §4.5） |
+
 ### 全局工具
 
 | 组件 | 导入名 | 关键 Props | 说明 |
@@ -2722,3 +2736,192 @@ node scripts/release.mjs <version>   # 发布
 # 测试前启动依赖服务
 docker compose up -d
 ```
+
+---
+
+# SaaS 地基模块（rateLimit / email / userSystem / queue）
+
+四个内建模块组成一个"基本 SaaS 底座"：认证、异步任务、限流、邮件——零新增依赖
+（只依赖已自研的 redis / postgres 客户端与 node 标准库）。
+
+## rateLimit — 限流
+
+```ts
+import { rateLimit } from 'weifuwu'
+
+app.use(redis())                                        // 依赖 ctx.redis
+app.use(rateLimit({ windowMs: 60_000, max: 100 }))      // 全局限流（默认固定窗口）
+
+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 }))
+```
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `windowMs` | `60000` | 时间窗口 |
+| `max` | `100` | 窗口内最大请求 |
+| `key` | X-Forwarded-For | 限流键（生产环境配置反向代理注入） |
+| `algorithm` | `fixed` | `fixed`（INCR+EXPIRE，原子）\| `sliding`（ZSET，仅 redis） |
+| `store` | `redis` | `redis`（多实例一致）\| `memory`（仅单实例/开发） |
+
+- 响应自动带 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` / `Retry-After`
+- 多实例共享计数：计数在 redis，水平扩展天然一致
+
+## email — 邮件发送
+
+```ts
+import { email } from 'weifuwu'
+
+app.use(email({ from: 'no-reply@your.app', adapter: 'resend', resend: { apiKey: process.env.RESEND_API_KEY } }))
+// 或 adapter: 'smtp' + smtp: { host, port, user, pass }（自研 SMTP 客户端，零依赖）
+
+app.post('/api/notify', async (req, ctx) => {
+  await ctx.email.send({ to: 'user@x.com', subject: '通知', html: '<h1>hi</h1>' })
+})
+```
+
+- 适配器：`resend`（默认，一个 POST）/ `smtp`（自研 node:net + node:tls：EHLO/STARTTLS/AUTH PLAIN/DATA/dot-stuffing，非 ASCII subject 自动 RFC2047 编码）/ 自定义函数
+- 裁剪：附件、退信/送达率（服务商职责）、批量营销不支持
+
+## userSystem — 用户系统
+
+```ts
+import { userSystem } from 'weifuwu'
+
+const db = postgres()
+await db.migrate()
+const users = userSystem({ sql: db.sql, secret: process.env.AUTH_SECRET })
+await users.migrate()          // 幂等建表（users + sessions）
+app.use(db)
+app.use(users)                 // 注入 ctx.user / ctx.auth
+users.routes(app)              // POST /api/auth/register|login|logout|refresh + GET /api/auth/me
+
+app.get('/me', (req, ctx) => ok(ctx.user))        // 已注入
+app.post('/secure', (req, ctx) => { ctx.auth.requireAuth(); ... })
+```
+
+- **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/client` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
+- **防枚举**：登录失败统一 401（不泄露邮箱是否存在）
+- **`ctx.auth` 方法面**：`register` / `login` / `logout` / `requireAuth` / `setPassword(userId, newPwd)` / `createToken(type, payload, { ttlSeconds })`（邮箱验证/密码重置自接）
+- **裁剪**：OAuth、邮箱验证邮件（给底层 API 自接）、多因素、RBAC 权限引擎（只留 `role` 字段）、多租户语义（tenant-ready：`tenant` 字段 + token claim 已预留）
+
+## queue — 可靠任务队列
+
+```ts
+import { queue } from 'weifuwu'
+
+const q = queue()              // 默认 REDIS_URL
+app.use(q)                     // 注入 ctx.queue
+
+app.post('/api/generate', async (req, ctx) => {
+  await ctx.queue.add('llm.batch', { prompt: '...' }, { attempts: 3 })
+  return new Response(null, { status: 202 })  // 立即 202，任务后台执行
+})
+
+// 消费者（独立进程或同进程均可，多开安全）
+const worker = q.worker('llm.batch', async (job) => {
+  await runLLM(job.data)       // 失败自动重试 → 用尽进 DLQ（q:llm.batch:dead）
+}, { concurrency: 5, visibilityTimeout: 30_000 })
+await worker.start()
+await worker.stop()            // 优雅停止
+```
+
+- **语义**：at-least-once（handler 可能重复执行——幂等由业务保证）；Redis Streams 消费组，多 worker 实例不重复消费
+- **可靠性**：失败 → 延迟重试（间隔 = `visibilityTimeout`，ZSET 延迟队列）→ attempts 用尽 → DLQ；worker 崩溃 → pending 由其他实例 `XAUTOCLAIM` 接管
+- 裁剪：延迟调度（除重试外）、cron、优先级、指数退避、速率限制不支持
+
+## ai — LLM 对话（自研协议 + 零依赖客户端）
+
+```ts
+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）
+app.post('/api/chat', async (req, ctx) => {
+  const { messages } = await req.json()
+  return ctx.ai.stream({ messages }, {
+    signal: req.signal,                                    // 断开即取消 provider 请求
+    traceId: req.headers.get('x-trace-id') ?? undefined,   // 追踪关联（协议 §7）
+  })
+})
+
+// 非流式（worker/后台）：
+const res = await a.chat({ messages: [{ role: 'user', content: 'hi' }] })
+
+// agent 引擎：工具循环 + 人工审批（HITL）
+const agent = a.agent({
+  systemPrompt: '你是助手。查询天气时调用 query_weather 工具。',
+  tools: [{
+    name: 'query_weather',
+    description: '查询城市天气',
+    parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+    run: async (args, { emit }) => {
+      emit('wf:tool_progress', { toolCallId: 'x', step: 1, total: 2, message: '查询中…', status: 'running' })
+      return { city: args.city, temp: 25 }
+    },
+  }],
+  humanInTheLoop: true,   // 每个工具执行前等人工审批
+})
+
+app.post('/api/agent', async (req, ctx) => {
+  const { messages } = await req.json()
+  return agent.run(messages, { signal: req.signal, traceId: req.headers.get('x-trace-id') ?? undefined })
+})
+
+// HITL 审批响应（前端点"允许/拒绝" → POST 到这里）
+app.post('/api/approve', async (req, ctx) => {
+  ctx.ai.approve(await req.json())   // { id, decision, modifiedArgs?, note? }
+  return new Response(null, { status: 200 })
+})
+```
+
+前端解码（`weifuwu/client`）：
+
+```ts
+import { aiStream } from 'weifuwu/client'
+
+const handle = aiStream('/api/chat', { messages }, {
+  onToken: (text) => { /* 增量 append 到消息 */ },
+  onToolCall: (call) => { /* 渲染工具卡片 */ },
+  onDone: () => { /* 收尾 */ },
+  onError: (e) => { /* 按 e.code 降级 */ },
+  onEvent: (name, data) => { /* x:* 自定义事件透传 */ },
+})
+handle.abort()  // 用户停止/组件卸载/导航跳走
+```
+
+- **协议**：`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…）
+- **追踪**：前端自动生成 `X-Trace-Id` → 后端以之作为 `message_start.id` → 工具内请求继承同一 traceId，整个 agent run 一次搜完
+- **裁剪**：embeddings、Anthropic 原生协议、审批持久化（连接断=会话亡）暂不支持；多 agent 编排不承诺（子 agent = 工具已支持）
+
+## 组合示例：注册 → 验证邮件 → 欢迎任务 → 登录防爆破
+
+```ts
+app.use(redis())
+app.use(rateLimit({ key: (req) => `login:${req.ip}`, max: 5, windowMs: 60_000 }))  // 防爆破
+app.use(email({ from: 'no-reply@x.com', adapter: 'resend', resend: { apiKey } }))
+app.use(db)
+app.use(users)
+users.routes(app)
+
+// 注册：限流守卫 → 用户系统 → 验证邮件 → 欢迎任务入队
+app.post('/api/auth/register', async (req, ctx) => {
+  await ctx.limit(`register:${req.ip}`, { max: 10, windowMs: 60_000 })
+  const result = await ctx.auth.register(await req.json())
+  const token = ctx.auth.createToken('verify', { sub: result.user.id }, { ttlSeconds: 86400 })
+  await ctx.email.send({ to: result.user.email, subject: '验证邮箱', html: `...?token=${token}` })
+  await ctx.queue.add('welcome.flow', { userId: result.user.id })
+  return created(result)
+})
+
+const worker = q.worker('welcome.flow', async (job) => { /* 欢迎流程 */ })
+await worker.start()
+```

package/dist/ai/agent.d.ts

@@ -0,0 +1,50 @@
+/**
+ * weifuwu AI — agent 工具循环引擎（协议 §5，agent 扩展实现）
+ *
+ * 循环：LLM 流式（emit wf:token）→ tool_calls → 执行工具 → 结果回喂 → 重复
+ *
+ * - 工具执行期间可 emit（wf:tool_progress / x:* 自定义）与接收 signal（取消）
+ * - HITL 审批（协议 §4.5）：humanInTheLoop 时每个工具执行前挂起等待
+ *   ctx.ai.approve() 响应（或超时按拒绝处理）——拒绝 ≠ 终止，agent 换方案
+ * - 事件序列：message_start → (step:llm → token* → tool_call → step:tool
+ *   → [approval_request → approve] → tool_result)* → usage → done
+ *
+ * 子 agent = 工具：委派工具的 run 内部调另一个 createAgent().run()（异步），
+ * 其最终输出即 tool_result——多 agent 沟通不新增协议事件（协议 §5.2）。
+ */
+import { type WfEmitter } from './sse.ts';
+import type { AiClient } from './client.ts';
+import type { ChatMessage } from './types.ts';
+export interface ToolContext {
+    /** 工具执行声道：emit('wf:tool_progress', ...) 或 emit('x:*', ...) */
+    emit: WfEmitter;
+    /** 用户取消 → abort（长任务应响应此 signal） */
+    signal?: AbortSignal;
+}
+export interface AgentTool {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    /** args 来自 LLM（JSON），未类型化——工具内部自行收窄 */
+    run: (args: Record<string, unknown>, tool: ToolContext) => unknown;
+}
+export interface AgentConfig {
+    model?: string;
+    systemPrompt: string;
+    tools: AgentTool[];
+    /** 默认 10 */
+    maxSteps?: number;
+    /** 每个工具执行前要求人工审批（协议 §4.5） */
+    humanInTheLoop?: boolean;
+    /** 审批超时（默认 5 分钟），到期按拒绝处理 */
+    approvalTimeoutMs?: number;
+}
+export interface AgentRunOptions {
+    signal?: AbortSignal;
+    traceId?: string;
+}
+export interface AgentRunner {
+    /** 运行 agent → SSE Response（wf: 协议事件流），路由直接 return */
+    run: (messages: ChatMessage[], options?: AgentRunOptions) => Response;
+}
+export declare function createAgent(client: AiClient, config: AgentConfig): AgentRunner;

package/dist/ai/client.d.ts

@@ -0,0 +1,104 @@
+/**
+ * weifuwu AI — OpenAI 兼容客户端（自研，零依赖）
+ *
+ * 协议（docs/ai-contract.md）的后端参考实现：把 provider 的
+ * chat/completions 流归一化成 wf: 事件。
+ *
+ * - 零依赖：fetch + 自研 SSE 解析
+ * - 默认 DeepSeek（baseUrl 可换 → 任意 OpenAI 兼容端点：Ollama/vLLM/Moonshot…）
+ * - 错误映射：provider HTTP 状态/错误体 → WfErrorCode（错误即值）
+ * - tool_calls 聚合：id 只在首 chunk（DeepSeek），后端聚合成完整 wf:tool_call
+ * - abort：外部 signal + 客户端断开 → 取消 provider 请求
+ *
+ * 诚实裁剪（CS-05）：embeddings 不做（DeepSeek 无此 API）、
+ * reasoning 事件不进 v1 协议（reasoning_content 仅随消息往返）。
+ */
+import { type WfEmitter } from './sse.ts';
+import type { ChatMessage, ChatParams, ToolCall, WfApprovalResponse, WfErrorCode } from './types.ts';
+export interface ChatChunk {
+    id: string;
+    model: string;
+    choices: {
+        index: number;
+        delta: {
+            role?: string;
+            content?: string;
+            reasoning_content?: string;
+            tool_calls?: ToolCall[];
+        };
+        finish_reason: 'stop' | 'length' | 'tool_calls' | null;
+    }[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface ChatResponse {
+    id: string;
+    model: string;
+    choices: {
+        index: number;
+        message: ChatMessage;
+        finish_reason: 'stop' | 'length' | 'tool_calls' | null;
+    }[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/** 协议错误：chat() 非流式场景抛出，stream() 场景编码为 wf:error 事件 */
+export declare class AiError extends Error {
+    code: WfErrorCode;
+    constructor(code: WfErrorCode, message: string);
+}
+export interface AiClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    defaultModel: string;
+}
+/** 单轮 LLM 流式调用的聚合结果（agent 循环用） */
+export interface StreamFinishResult {
+    content: string;
+    /** DeepSeek thinking 模式：必须随 assistant 消息回传（协议陷阱清单 #4） */
+    reasoning_content?: string;
+    toolCalls: ToolCall[];
+    usage?: ChatResponse['usage'];
+}
+export interface AiClient {
+    /** 非流式对话（worker/后台场景） */
+    chat(params: ChatParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatResponse>;
+    /** 流式对话 → SSE Response（协议 §1.1），路由直接 return */
+    stream(params: ChatParams, options?: {
+        signal?: AbortSignal;
+        traceId?: string;
+    }): Response;
+    /** 低层：app 完全控制事件序列（自定义 x:* 事件、HITL 等） */
+    sse(run: (emit: WfEmitter) => Promise<void> | void, options?: {
+        signal?: AbortSignal;
+    }): Response;
+    /** 内部：单轮 LLM 流式 → emit 事件 + onFinish 聚合结果（agent 引擎用） */
+    streamStep(params: ChatParams, opts: {
+        emit: WfEmitter;
+        signal?: AbortSignal;
+        onFinish?: (r: StreamFinishResult) => void;
+        emitUsage?: boolean;
+    }): Promise<void>;
+    /** 响应一个挂起的 HITL 审批（协议 §4.5，app 的 POST /approve 路由调用） */
+    approve(response: WfApprovalResponse): boolean;
+    /** 内部：agent 循环挂起等待审批 */
+    waitApproval(req: {
+        id: string;
+        toolCallId: string;
+        name: string;
+        args: Record<string, unknown>;
+    }, emit: WfEmitter, timeoutMs?: number): Promise<WfApprovalResponse>;
+}
+export declare function createAiClient(opts: AiClientOptions): AiClient;
+/** 审批默认超时：5 分钟 */
+export declare const DEFAULT_APPROVAL_TIMEOUT: number;
+/** 工具参数可能是 JSON 字符串；解析失败给空对象（不抛错） */
+export declare function safeParseArgs(raw: string): Record<string, unknown>;

package/dist/ai/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * weifuwu AI — 中间件工厂（queue 式混合：模块即中间件，也独立可用）
+ *
+ * ```ts
+ * import { ai } from 'weifuwu'
+ *
+ * const a = ai()                    // DEEPSEEK_API_KEY / BASE_URL / MODEL 自动读 env
+ * app.use(a)                        // → ctx.ai.chat / ctx.ai.stream / ctx.ai.sse
+ *
+ * app.post('/api/chat', async (req, ctx) => {
+ *   const { messages } = await req.json()
+ *   return ctx.ai.stream({ messages }, {
+ *     signal: req.signal,
+ *     traceId: req.headers.get('x-trace-id') ?? undefined,   // 追踪关联（协议 §7）
+ *   })
+ * })
+ *
+ * // worker / 非请求场景：同一个实例直接调用
+ * q.worker('llm.batch', async (job) => {
+ *   await a.chat({ messages: job.data.messages })
+ * })
+ * ```
+ *
+ * 配置优先级：显式参数 > env > 默认值。
+ *   apiKey:      DEEPSEEK_API_KEY
+ *   baseUrl:     DEEPSEEK_BASE_URL      → 'https://api.deepseek.com/v1'
+ *   defaultModel: DEEPSEEK_MODEL        → 'deepseek-v4-flash'
+ */
+import type { Context, Middleware } from '../types.ts';
+import { type AiClient, type AiClientOptions } from './client.ts';
+import { type AgentConfig, type AgentRunner } from './agent.ts';
+export interface AiOptions extends Partial<AiClientOptions> {
+}
+export interface AiInjected {
+    ai: AiClient;
+}
+/** 模块 = 中间件 + 客户端（queue 式混合：app.use(a) + worker 直接 a.chat()） */
+export interface AiClientModule extends Middleware<Context, Context & AiInjected>, AiClient {
+    /** agent 引擎（工具循环 + HITL 审批） */
+    agent: (config: AgentConfig) => AgentRunner;
+    close: () => Promise<void>;
+}
+declare module '../types.ts' {
+    interface Context {
+        /** 注入模块本身（含 agent / approve），worker 场景直接 a.chat() */
+        ai?: AiClientModule;
+    }
+}
+export declare function ai(options?: AiOptions): AiClientModule;
+export type { WfStreamEvent, WfMessageStart, WfToken, WfUsage, WfDone, WfError, WfErrorCode, WfToolCall, WfToolResult, WfToolProgress, WfStep, WfApprovalRequest, WfApprovalResponse, WfApprovalDecision, ChatMessage, ChatParams, MessageRole, ToolCall, ToolDefinition, } from './types.ts';
+export type { WfEmitter } from './sse.ts';
+export { AiError } from './client.ts';
+export type { AiClient, ChatResponse } from './client.ts';
+export type { AgentConfig, AgentTool, AgentRunner, ToolContext } from './agent.ts';

package/dist/ai/sse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * weifuwu AI — SSE 编码器
+ *
+ * 把 `wf:` 事件流编码成 text/event-stream Response（协议 §1.1）。
+ * 与 docs/ai-contract.md 对应。
+ *
+ * - 错误即值：run 内部抛错 → 编码为 wf:error 事件，而非断流
+ * - abort：客户端断开（cancel）→ onAbort 回调（用于取消 provider 请求）
+ */
+export type WfEmitter = (name: string, data: unknown) => void;
+export interface SseResponseOptions {
+    /** 客户端断开回调（取消上游请求） */
+    onAbort?: () => void;
+}
+/**
+ * 构造 SSE Response。run 收到 emit，负责输出完整事件序列。
+ *
+ * ```ts
+ * return sseResponse(async (emit) => {
+ *   emit('wf:message_start', { id })
+ *   emit('wf:token', { text: '你好' })
+ *   emit('wf:done', { content })
+ * })
+ * ```
+ */
+export declare function sseResponse(run: (emit: WfEmitter) => Promise<void> | void, options?: SseResponseOptions): Response;

package/dist/ai/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * weifuwu AI 协议共享类型 —— 与 docs/ai-contract.md 规范一一对应
+ *
+ * 纯类型，零运行时成本。两端同源：
+ *   - 后端：从 weifuwu 主包导入（src/index.ts re-export）
+ *   - 前端：从 weifuwu/client 导入（src/client/index.ts re-export）
+ *
+ * 修改本文件 = 修改协议，需同步更新 docs/ai-contract.md。
+ */
+export interface WfMessageStart {
+    id: string;
+}
+export interface WfToken {
+    /** 增量文本，前端直接 append */
+    text: string;
+}
+export interface WfUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens?: number;
+}
+export interface WfDone {
+    content: string;
+    usage?: WfUsage;
+}
+export type WfErrorCode = 'auth_failed' | 'rate_limited' | 'context_length' | 'timeout' | 'provider_error' | 'invalid_request' | 'unsupported' | 'aborted';
+export interface WfError {
+    code: WfErrorCode;
+    message: string;
+}
+export interface WfToolCall {
+    /** 工具调用 id（provider 给 / 后端生成），聚合完成后才发 */
+    id: string;
+    /** 工具名（app 定义的业务语义，协议不解释） */
+    name: string;
+    /** 完整参数 */
+    args: Record<string, unknown>;
+}
+export interface WfToolResult {
+    id: string;
+    ok: boolean;
+    output?: unknown;
+    /** ok:false 时：rejected（人工拒绝）/ timeout（审批超时）/ tool_error / app 自定义 */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface WfToolProgress {
+    toolCallId: string;
+    step: number;
+    total: number;
+    message?: string;
+    status: 'running' | 'error' | 'done';
+}
+export interface WfStep {
+    type: 'llm' | 'tool';
+    content?: string;
+    toolCallId?: string;
+    name?: string;
+}
+export interface WfApprovalRequest {
+    id: string;
+    toolCallId: string;
+    name: string;
+    args: Record<string, unknown>;
+    reason?: string;
+    /** 审批超时；到期按 rejected 处理（error.code: 'timeout'） */
+    expiresAt?: number;
+}
+export type WfApprovalDecision = 'approved' | 'rejected' | 'modified';
+/** 上行 POST 载荷（非 SSE 事件） */
+export interface WfApprovalResponse {
+    id: string;
+    decision: WfApprovalDecision;
+    /** 仅 modified：按修改后的参数执行 */
+    modifiedArgs?: Record<string, unknown>;
+    /** 进 agent 上下文 */
+    note?: string;
+}
+/** 所有框架事件联合类型（前端 switch 收窄用） */
+export type WfStreamEvent = {
+    name: 'wf:message_start';
+    data: WfMessageStart;
+} | {
+    name: 'wf:token';
+    data: WfToken;
+} | {
+    name: 'wf:usage';
+    data: WfUsage;
+} | {
+    name: 'wf:done';
+    data: WfDone;
+} | {
+    name: 'wf:error';
+    data: WfError;
+} | {
+    name: 'wf:tool_call';
+    data: WfToolCall;
+} | {
+    name: 'wf:tool_result';
+    data: WfToolResult;
+} | {
+    name: 'wf:tool_progress';
+    data: WfToolProgress;
+} | {
+    name: 'wf:step';
+    data: WfStep;
+} | {
+    name: 'wf:approval_request';
+    data: WfApprovalRequest;
+};
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface ChatMessage {
+    role: MessageRole;
+    content: string;
+    /** DeepSeek thinking mode：前一轮的 reasoning_content 必须回传 */
+    reasoning_content?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+    name?: string;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ChatParams {
+    model?: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    tools?: ToolDefinition[];
+    tool_choice?: 'auto' | 'none' | 'required';
+    stop?: string[];
+}

package/dist/client/ai.d.ts

@@ -0,0 +1,59 @@
+/**
+ * weifuwu/client AI 解码器 — 消费 wf: 协议（docs/ai-contract.md）
+ *
+ * 协议的前端参考实现：POST → 解析 SSE → 按事件名分发回调。
+ *
+ * - 零依赖：fetch + ReadableStream + 自研 SSE 解析
+ * - 未知事件透传不抛错（协议 §6）：x:* 走 onEvent，未订阅的跳过
+ * - 事件录制（副产品）：record 开启时记录完整事件序列，可导出为测试 fixture
+ * - trace 桥（协议 §7）：默认自动生成 X-Trace-Id 并随请求发送，
+ *   后端以之作为 wf:message_start.id → 整个 agent run 一次搜完
+ * - abort：handle.abort() 或外部 signal → 取消请求 → 后端断开 → provider 取消
+ */
+import type { WfApprovalRequest, WfDone, WfError, WfStreamEvent, WfToolCall, WfToolProgress, WfToolResult, WfUsage } from '../ai/types.ts';
+export interface AiStreamCallbacks {
+    /** wf:token — 增量文本，直接 append */
+    onToken?: (text: string) => void;
+    /** wf:tool_call — 完整工具调用（后端已聚合） */
+    onToolCall?: (call: WfToolCall) => void;
+    /** wf:tool_result — ok:false 不代表会话结束 */
+    onToolResult?: (result: WfToolResult) => void;
+    /** wf:tool_progress — 长任务进度 */
+    onToolProgress?: (p: WfToolProgress) => void;
+    /** wf:step — 步骤可视化（agent 扩展） */
+    onStep?: (s: {
+        type: 'llm' | 'tool';
+        content?: string;
+        toolCallId?: string;
+        name?: string;
+    }) => void;
+    /** wf:approval_request — 渲染审批卡片 */
+    onApproval?: (req: WfApprovalRequest) => void;
+    /** wf:usage — token 计数 */
+    onUsage?: (u: WfUsage) => void;
+    /** wf:done — 收尾 */
+    onDone?: (d: WfDone) => void;
+    /** wf:error — 错误即值，结构化降级 */
+    onError?: (e: WfError) => void;
+    /** x:* 自定义事件透传兜底（协议 §6：框架不解释） */
+    onEvent?: (name: string, data: unknown) => void;
+}
+export interface AiStreamOptions extends AiStreamCallbacks {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    /** 显式指定 traceId；默认自动生成（协议 §7） */
+    traceId?: string;
+    /** 录制事件序列（调试/导出 fixture），默认开启，环形上限 1000 */
+    record?: boolean;
+}
+export interface AiStreamHandle {
+    /** 取消请求（用户停止/组件卸载/导航跳走时调用） */
+    abort: () => void;
+    /** 流结束（正常 done / error / abort 都 resolve） */
+    done: Promise<void>;
+    /** 本次请求使用的 traceId（自动生成的也能拿到） */
+    traceId: string;
+    /** 录制的事件序列（record: true 时） */
+    events: WfStreamEvent[];
+}
+export declare function aiStream(url: string, body: unknown, options?: AiStreamOptions): AiStreamHandle;

package/dist/client/index.d.ts

@@ -31,6 +31,9 @@ export { ApiError } from './middleware/api.ts';
 export type { AuthClient, AuthOptions, AuthInjected } from './middleware/auth.ts';
 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 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';
 export { i18n } from './i18n.ts';