weifuwu 0.57.0 → 0.59.0

package/README.md

@@ -211,8 +211,8 @@ 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` | 43 个 UI 组件（Button, Card, Table, Modal 等） |
-| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 91 个主题 Token + 35 个布局原语 |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 44 个 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,6 +234,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/dev` | **dev loader** | Node loader：服务端直接跑 `.ts/.tsx`（`--import weifuwu/dev`） | esbuild |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
 | `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
@@ -249,8 +250,8 @@ 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` | **43 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
-| `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 91 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/components` | **44 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
+| `weifuwu/layout` | **CSS 布局** | 67 个布局原语 + 115 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -2147,11 +2148,11 @@ import type { RouterOptions } from 'weifuwu/client'
 
 # 组件库 (`weifuwu/components`)
 
-43 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
+44 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
-import 'weifuwu/components/style.css'   // 包含 Token + 35 布局原语 + 组件样式，一次性引入
+import 'weifuwu/components/style.css'   // 包含 Token + 67 布局原语 + 组件样式，一次性引入
 ```
 
 ### 使用示例
@@ -2363,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 | 说明 |
@@ -2373,7 +2381,9 @@ props 变化 ──────────────────────
 
 # 布局系统 (`weifuwu/layout`)
 
-纯 CSS 布局原语 + 91 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 布局原语 + 工具类 + 115 个主题 Token。不绑定任何 JS 框架。
+
+> **学习路径与命名规范**：见 [`docs/style-guide.md`](./docs/style-guide.md)——统一语法 `wf-<域>-<名>`、三档学习（组件 → 10 核心原语 → 完整速查）、场景速查、变量定制。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -2395,7 +2405,7 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 也支持相对路径：`ctx.ui.css('./src/style.css')`。
 ```
 
-## 35 个布局原语
+## 67 个布局原语
 
 | 类别 | 原语 | 效果 |
 |------|------|------|
@@ -2432,13 +2442,56 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | | `wf-inline` | display: inline |
 | | `wf-inline-block` | display: inline-block |
 | | `wf-contents` | display: contents |
-
-## 91 个主题 Token
+| **间距** | `wf-p-*` / `wf-px-*` / `wf-py-*`（xs~2xl） | padding：全/水平/垂直，引用 `--wf-space-*` |
+| | `wf-mt-*` / `wf-mb-*` / `wf-my-*`（xs~2xl） | margin：top/bottom/垂直 |
+| | `wf-mx-auto` / `wf-my-auto` | margin: auto 居中 |
+| | `wf-gap-*`（xs~2xl） | 为 flex/grid 原语设置 `--wf-gap` |
+| **尺寸** | `wf-w-full` / `wf-h-full` / `wf-w-auto` | 宽/高 100%、auto |
+| **边框** | `wf-border` / `wf-border-t/b/l/r` | 1px 边框（`--wf-border-width` + `--wf-color-border`） |
+| **面工具** | `wf-bg-secondary/tertiary/brand/success/warning/error/info` | 语义背景色（`--wf-color-*-bg`） |
+| | `wf-pill` | 胶囊圆角（999px，状态徽章/标签/色块） |
+| | `wf-rounded-sm` `wf-rounded` `wf-rounded-md` `wf-rounded-lg` | 圆角工具（`--wf-radius-*`） |
+| **气泡** | `wf-bubble` / `wf-bubble--own` / `wf-bubble--ai` | 聊天气泡（pre-wrap + 折行内建） |
+| **打印** | `wf-print-hidden` / `wf-print-block` | 导出 PDF 时隐藏工具区 / 恢复块级 |
+| **行高** | `wf-leading-tight` `wf-leading-base` `wf-leading-relaxed` | line-height（`--wf-line-height-*`） |
+| **指针** | `wf-pointer` / `wf-not-allowed` | cursor: pointer / not-allowed |
+| **内容排版** | `wf-prose` | 富文本正文（文章/博客/文档，一个类包 h2/p/ul/blockquote/pre…） |
+| **外壳** | `wf-app-shell` | 应用外壳：侧边栏 + 主区 grid（`--wf-sidebar-width`） |
+| | `wf-sidebar` `wf-sidebar-header` `wf-sidebar-body` `wf-sidebar-footer` | 侧边栏：品牌区/导航区/底部用户区，sticky 全高 |
+| | `wf-nav` `wf-nav-group` `wf-nav-item` `wf-nav-icon` | 导航：分组标题 + 链接项（`--active` 激活态） |
+| | `wf-main` | 主内容区（padding + min-width: 0） |
+| | `wf-text-*` 排版工具 | 见下文「排版工具」 |
+
+### 排版工具（`wf-text-*`）
+
+| 工具 | 效果 |
+|------|------|
+| `wf-text-left/center/right` | text-align |
+| `wf-text-xs…5xl` | 字号（`--wf-font-size-*`） |
+| `wf-text-secondary/tertiary/disabled/brand` | 中性色阶 |
+| `wf-text-success/warning/error/info` | 语义色文本（`--wf-color-*`） |
+| `wf-text-medium/semibold/bold` | 字重 |
+| `wf-tracking-normal/wide/wider` | letter-spacing |
+| `wf-uppercase/lowercase/capitalize` | text-transform |
+| `wf-pre-wrap` | white-space: pre-wrap + word-break（聊天气泡/代码） |
+| `wf-break-word` | overflow-wrap + word-break |
+| `wf-text-nowrap` | white-space: nowrap |
+| `wf-truncate` | 单行省略（ellipsis） |
+| `wf-line-clamp-2/3` | 多行截断 |
+
+## 115 个主题 Token
+
+**双层结构**：原始层（Primitive，色值只定义一次，品牌/暗色调校改这里）+ 语义层（Semantic，组件消费）。
 
 ```css
+/* ── 原始层 — 品牌/中性色值 + 暗色值，主题定制改这一层 ── */
+--wf-brand-500 / --wf-brand-600 / --wf-brand-50   /* 品牌主色/悬停/浅底 */
+--wf-slate-900…50 / --wf-white                     /* 中性阶 */
+--wf-dark-*                                        /* 暗色值（暗色模式经间接层引用，零硬编码） */
+
+/* ── 语义层 — 组件消费，暗色/主题切换覆盖这里 ── */
 /* 品牌色 */
 --wf-color-primary / --wf-color-primary-hover / --wf-color-primary-bg
---wf-color-secondary / --wf-color-secondary-bg
 
 /* 语义色 */
 --wf-color-success / --wf-color-success-bg
@@ -2488,6 +2541,9 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 --wf-accent-color / --wf-caret-color
 --wf-opacity-disabled / --wf-opacity-overlay
 --wf-pop-z / --wf-cover-z
+
+/* 应用外壳 */
+--wf-sidebar-width
 ```
 
 ### 暗色模式
@@ -2503,10 +2559,64 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 // 系统为暗色时自动生效；加 data-theme="light" 可强制亮色
 ```
 
+暗色值定义在原始层 `--wf-dark-*`（只写一次），`_dark.css` 两段仅做语义映射——改暗色调校只动原始层，无硬编码色值。
+
 ---
 
 # 样式定制指南
 
+## 组件定制钩子（零覆盖 CSS）
+
+关键组件视觉全部变量化——定制只需设一个变量（默认值 = 现有 token）：
+
+```html
+<style>
+  :root {
+    --wf-brand-500: #7c3aed;      /* 品牌换色：改原始层一个值，全站跟随 */
+    --wf-dark-brand-500: #a78bfa; /* 暗色品牌（可选） */
+    --wf-modal-width: 640px;      /* 组件定制：设一个变量 */
+    --wf-btn-radius: 999px;
+    --wf-field-height: 44px;
+    --wf-card-shadow: 0 8px 24px rgba(0,0,0,.12);
+  }
+</style>
+```
+
+钩子清单：`--wf-btn-*` `--wf-card-*` `--wf-field-*` `--wf-modal-*` `--wf-drawer-width` `--wf-toast-*` `--wf-alert-radius` `--wf-badge-radius` `--wf-tag-radius` `--wf-switch-radius` `--wf-popover-*` `--wf-tooltip-radius` `--wf-dropdown-min-width` `--wf-datepicker-*`。
+
+**覆盖优先级（@layer）**：`@layer tokens, base, layout, utilities, components`——你写的未分层 CSS 天然最高优先级；也可用 `@layer utilities` 精准覆盖我们。
+
+## 零自定义 CSS 模式（推荐）
+
+一个项目只需要引用**一个 CSS 文件**（`weifuwu/components/style.css`，内含 Token + 布局原语 + 组件样式），
+业务代码全部由组件 + `wf-*` 原语承担，**不需要再写 `style.css`**：
+
+```tsx
+// 组件 → 页面功能块；wf-* 原语 → 块之间的空间关系；--wf-* → 业务色值
+<PageHeader title="仪表盘" sub="欢迎回来">
+  <Button variant="primary">+ 新建</Button>
+</PageHeader>
+<div class="wf-row wf-gap-lg">
+  <StatCard label="总用户" value="1,234" trend="up" trendLabel="12%" />
+</div>
+```
+
+主题定制（品牌色/圆角/字体）不需要独立文件——**内联在 HTML 的 `<style>` 里即可**：
+
+```html
+<style>
+  :root {
+    --wf-color-primary: #6366f1;
+    --wf-radius: 8px;
+  }
+</style>
+```
+
+完整的零样式示例：`apps/weifuwu-demo`（一个页面 = 组件 + 原语，无 style.css）。
+
+诚实例外（合理场景，仍可内联 `<style>` 解决）：打印/PDF 导出规则、第三方库宿主样式、
+业务特有的一次性视觉（如色板选择器交互）。
+
 ## 全局主题变量
 
 所有组件引用 `--wf-*` CSS 变量。在根元素覆盖即可定制主题：
@@ -2826,6 +2936,74 @@ await worker.stop()            // 优雅停止
 - **可靠性**：失败 → 延迟重试（间隔 = `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

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[];
+}