weifuwu 0.78.0 → 0.80.0

package/dist/ui-dom/vdom2/x2html.d.ts

@@ -0,0 +1,23 @@
+/**
+ * vdom2 x2html — vnode → HTML 字符串（SSR）
+ *
+ * 与 renderValue（客户端 DOM）同一**类型遍历**——TO_HTML[classifyKind(v)] 分派：
+ * 每个类型一个渲染实现，SSR/客户端结构同构（数组边界标记/占位注释/属性规则同一单一规则源
+ * transform.ts），hydration 不 mismatch。
+ *
+ * 与客户端的差异（SSR 语义）：
+ * - 组件：现场执行工厂 + renderFn（无预构建——SSR 服务端每次渲染）
+ * - Portal：就地内联子节点（客户端 portal 渲染到 #__wf_portal——SSR 内联保留内容/SEO）
+ * - 事件 props 剥离（hydration 接线）；ref 剥离
+ */
+import type { VNodeChild } from '../vnode.ts';
+import { isFrag, isComp, isPortal, isNative, Fragment, Portal } from '../vnode.ts';
+export declare function escape(s: string): string;
+type HtmlCtx = {
+    _fidPath?: string;
+    [key: string]: any;
+};
+/** vnode → HTML（SSR）——类型分派主入口 */
+export declare function x2html(input: VNodeChild, ctx: HtmlCtx): Promise<string>;
+export { Fragment, Portal };
+export { isFrag, isComp, isPortal, isNative };

package/dist/ui-dom/vnode.d.ts

@@ -1,82 +1,78 @@
 /**
- * weifuwu/ui-dom VNode — 虚拟 DOM 节点
+ * vnode — VNode 强类型判别联合（vdom2 方案——vdom1 退役后唯一类型源）
  *
- * VNode 是纯 JS 对象，不依赖 DOM。组件返回 VNode。
+ * 与全局 vnode.ts（vdom1 JSX 运行时）的关系：
+ * - Fragment/Portal **symbol 复用全局**（全局唯一协议——JSX 编译产物用全局 Fragment，
+ *   vdom2 引擎处理全局 h() 产物必须同 symbol 判别）
+ * - 类型（VNode/VNodeChild/Component）**独立**（vdom2 强类型；vdom1 替换后本文件成唯一类型源）
  *
- * h/jsx 由 esbuild JSX 编译调用：
- *   --jsxImportSource=weifuwu/ui-dom
+ * 访问模式（强类型约束）：
+ *   if (isFrag(vnode)) { vnode._childNodes ... }   // type === Fragment → TS 收窄为 FragVNode
+ *   if (isComp(vnode)) { vnode._render ... }        // type 为函数 → 收窄为 CompVNode
+ *   —— 无散落 cast；字段访问由类型系统强制。
  */
-import type { WfuiContext } from './types.ts';
 export type VNodeType = string | Component<any, any> | typeof Fragment | typeof Portal;
-/**
- * VNode 子节点合法值——组件可返回/渲染的多态内容。
- * 递归联合：string/number/VNode/array/null/boolean 任意组合。
- */
 export type VNodeChild = VNode | string | number | boolean | null | undefined | VNodeChild[];
-export interface VNode {
+export declare const Fragment: unique symbol;
+export declare const Portal: unique symbol;
+/** 通用字段（所有 VNode 共有——构建元数据；渲染前为 null 的显式初始化） */
+interface VNodeBase {
     type: VNodeType;
     props: Record<string, any>;
-    key?: string;
-    el?: Node;
-    /** 子 VNode 缓存（用于 patchValue diff，避免重复执行组件） */
-    _child?: VNode | VNode[] | null;
-    /** 远程 DOM 容器（Portal 等 remote VNode 的 DOM 所在处） */
-    _remoteEl?: HTMLElement | undefined;
-    /** VNode 的 DOM 归属：'local' 在父 DOM 树下，'remote' 在别处 */
-    _placement?: 'local' | 'remote';
-    /** 两阶段组件的 render 函数（mount 返回的函数——强制异步：props 变化时可 await 数据） */
-    _render?: (props: Record<string, unknown>) => Promise<VNode | null>;
-    /** 组件实例 ID（如 '_wf_0'） */
-    _id?: string;
-    /** 自定义组件 ID（ctx.ui.selfId() 注册，跨组件精准刷新） */
-    _customId?: string;
-    /** 组件输出的 DOM 父节点 */
-    _parentNode?: Node;
-    /** 父 vnode 引用（动态挂载补全向上找持有组件） */
-    _parentVNode?: VNode;
-    /** 组件输出的第一个 DOM 节点 */
-    _refNode?: Node | null;
-    /** 阶段 B：children 每位置的首 DOM 节点（规则表 §5 锚点优先——替代 source[i] 下标猜测，
-     *  fragment/数组项多节点展开后相邻项不错位）。renderValue 记录，patchChildren 读取 + 回写 */
-    _childAnchors?: (Node | null)[];
-    /** Fragment 展开后的多个直属 DOM 节点范围（diff 对齐用，见 diff.ts） */
-    _childNodes?: Node[];
-    /** 组件 renderFn 上次执行时的 ctx 版本号（buildVNode 剪枝 + diff 三态 skip 的版本比较——
-     *  bumpCtxVersion 递增后版本不同 → 强制重跑 renderFn，如 i18n 切换语言） */
-    _ctxVersion?: number;
+    /** key（数组项身份——无 key 为 null；显式 null 非可选 undefined） */
+    key: string | null;
+    /** 子 vnode 缓存（buildVNode 构建——patchValue diff 对照用；渲染前 null） */
+    _child: VNode | VNode[] | null;
+    /** 结构父节点（输出范围坐标系——范围定位不需要外部传 parent） */
+    _parentNode: Node | null;
+    /** 输出锚点 = 输出范围**首 DOM 节点**（多节点输出时必须是真实节点而非 DocumentFragment） */
+    _refNode: Node | null;
+    /** 组件实例 ID / 自定义 ID（buildVNode 分配） */
+    _id: string | null;
+    _customId: string | null;
+    /** 父 vnode 引用 */
+    _parentVNode: VNode | null;
+    /** 组件 renderFn 上次执行时的 ctx 版本号（buildVNode 剪枝 + diff 三态 skip） */
+    _ctxVersion: number | null;
 }
-/**
- * 两阶段异步组件（weifuwu 唯一组件形态）：
- *   async (initProps, ctx) => Promise<renderFn>
- * 外层 = mount（一次，可 await 数据），内层 = renderFn（每次 dirty/props 变化——**强制异步**，
- * 可 await 数据；统一异步心智：两阶段都可 await，无「同步组件 vs 异步组件」二元形态）。
- * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
- *
- * renderFn 签名：async (props) => Promise<VNode | null>——同步 renderFn 是类型错误
- * （diff 永不执行 renderFn——渲染器在 buildVNode 阶段 await，同步上下文拿不到 vnode）。
- * 渲染器按「返回值是 Promise」判别（主路径 buildVNode await 全部工厂 + renderFn）。
- */
-export type RenderFn<P> = (props: P) => Promise<VNode | null>;
-export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => Promise<RenderFn<P> | null>;
-export declare const Fragment: unique symbol;
-/** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
-export declare const Portal: unique symbol;
-/** JSX 类型声明 — 使 TypeScript 理解自定义 JSX 运行时 */
+/** 原生元素——type: string；特有：el（元素引用——锚点统一用 _refNode） */
+export interface NativeVNode extends VNodeBase {
+    type: string;
+    el: Node | null;
+}
+/** Fragment——type: typeof Fragment（多节点输出边界 = fragment-start/end 标记——DOM 持久化） */
+export interface FragVNode extends VNodeBase {
+    type: typeof Fragment;
+}
+/** 组件——type: Component；特有：_render（两阶段 renderFn）/ _outputChild（输出引用） */
+export interface CompVNode extends VNodeBase {
+    type: Component;
+    _render: ((props: Record<string, unknown>) => Promise<VNode | null>) | null;
+    /** 输出 vnode 引用（dispose 清 _child/_id/_render 后仍可取输出范围——getOutputRange 递归终点） */
+    _outputChild: VNodeChild | null;
+}
+/** Portal——type: typeof Portal；特有：_remoteEl / _placement（固定 'remote'） */
+export interface PortalVNode extends VNodeBase {
+    type: typeof Portal;
+    _remoteEl: HTMLElement | null;
+    _placement: 'remote';
+}
+/** VNode 判别联合——type 为判别式 */
+export type VNode = NativeVNode | FragVNode | CompVNode | PortalVNode;
+export declare function isNative(v: unknown): v is NativeVNode;
+export declare function isFrag(v: unknown): v is FragVNode;
+export declare function isComp(v: unknown): v is CompVNode;
+export declare function isPortal(v: unknown): v is PortalVNode;
+export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: import('./types.ts').WfuiContext & C) => Promise<((props: P) => Promise<VNode | null>) | null>;
+/** 按类型构造强类型 VNode（每类初始化特有必填字段） */
+export declare function createVNode(type: VNodeType, props: Record<string, any>, key?: string | null): VNode;
+export declare function h(type: VNodeType, props: Record<string, any> | null, ...children: VNodeChild[]): VNode;
 export declare function jsx(type: VNodeType, props: Record<string, any> | null, key?: string | null): VNode;
 export declare const jsxs: typeof jsx;
 export declare function jsxDEV(type: VNodeType, props: Record<string, any> | null, key?: string | null): VNode;
-/** `h`（hyperscript）支持 variadic children: `h('div', {class:'x'}, child1, child2)` */
-export declare function h(type: VNodeType, props: Record<string, any> | null, ...children: VNodeChild[]): VNode;
-export declare function isNative(vnode: VNode): boolean;
-/** 递归文本/数组归一化（children 数组展开——嵌套数组扁平化，DOM 范围对齐）。
- *  栈展开（索引遍历替代 shift/unshift 头部操作——长数组 O(n) 而非 O(n²)）；逆序入栈 + pop 保持原顺序 */
-export declare function normalizeChildren(c: VNodeChild | undefined | null): VNodeChild[];
-export declare function isComponent(vnode: VNode): boolean;
-export declare function isFragment(vnode: VNode): boolean;
-export declare function isPortal(vnode: VNode): boolean;
-/** Portal VNode — 子节点渲染到 document.body#__wf_portal 中 */
+export declare function arrayChildren(c: VNodeChild | undefined | null): VNodeChild[];
 export declare function createPortal(children: VNodeChild, portalKey?: string): VNode;
-/** JSX 类型声明 — ui-dom 是 jsxImportSource（client 壳不再声明） */
+/** JSX 类型声明（jsxImportSource: weifuwu/ui-dom——组件/用户 JSX 编译产物类型） */
 declare global {
     namespace JSX {
         type Element = import('./vnode.ts').VNode | null;
@@ -85,7 +81,8 @@ declare global {
             [tag: string]: any;
         }
         interface IntrinsicAttributes {
-            key?: string | number;
+            key?: string | number | null;
         }
     }
 }
+export {};

package/docs/ai-contract.md

@@ -0,0 +1,418 @@
+# Weifuwu AI Stream Protocol (v1)
+
+> **weifuwu 前后端之间的 LLM/agent 对话协议。** 定义"后端如何把一次对话/一次 agent run 流式地告诉前端，前端如何回传人工决策"。
+>
+> - **协议是 weifuwu 自己的**（`wf:` 命名空间），不依赖任何 provider 的 wire format——前端只见 `wf:` 事件，换模型/换提供商前端零改动。
+> - **实现可换**：后端可以用自研 OpenAI 兼容客户端（`weifuwu/src/ai/`）、raw fetch 或任何库，只要输出 `wf:` 事件即可。协议不绑定实现。
+> - **错误即值**：`wf:error` 是正常协议消息，不是断流异常（对齐自研 DB 客户端 RESP `-ERR` 精神）。
+> - **前端参考实现**（`weifuwu/ui-dom`）：`aiStream()` = 传输解码（POST + SSE 解析 + trace + abort）；`ctx.ui.useChat()` = 会话语义层（消息累积、工具调用内嵌、HITL 审批、stop/retry，协议对页面透明）。
+> - **版本**：本文档为 v1。非破坏性演进（新事件）直接追加；破坏性变更升版本号，两端随 weifuwu 单包原子发布同步升级。
+
+---
+
+## 1. 传输
+
+### 1.1 下行：SSE（`text/event-stream`）
+
+- 一次 `POST` = 一次对话 / 一次 agent run
+- 请求头：`Accept: text/event-stream`；认证与业务参数走 app 的既有中间件（auth / rateLimit 等）
+- 响应头：`Content-Type: text/event-stream`、`Cache-Control: no-cache`、`Connection: keep-alive`
+- 事件格式：`event: <名称>\ndata: <JSON>\n\n`
+
+```
+event: wf:message_start
+data: {"id":"9f3a"}
+
+event: wf:token
+data: {"text":"你好"}
+
+event: wf:done
+data: {"content":"你好，有什么可以帮你？","usage":{"prompt_tokens":512,"completion_tokens":384}}
+```
+
+调试：`curl -N -X POST <url> -d '{"messages":[...]}'` 直接看裸事件。
+
+### 1.2 上行：独立 POST
+
+SSE 单向，人工决策回传走独立 POST（低频、可鉴权、可审计）：
+
+```
+POST /api/ai/approve
+Content-Type: application/json
+
+{"id":"ap_01","decision":"approved","note":"OK"}
+// modified 决策：携带修改后参数（use-chat approve('modified', note, modifiedArgs) 自动带上）
+// {"id":"ap_01","decision":"modified","note":"数量改为 5","modifiedArgs":{"qty":5}}
+```
+
+- 回传载荷形状由协议定义（见 §4.5）；**路由路径是 app 的**（app 知道自己的 run 生命周期）。
+- 回传端点应挂 auth / rateLimit，审批记录带 `ctx.user` 进审计。
+
+### 1.3 生命周期
+
+| 语义 | 规则 |
+|---|---|
+| 请求即会话 | 一次 POST + 一条 SSE 连接 = 一个会话；无连接池、无会话管理 |
+| 断开 = abort | 客户端断开 → `req.signal` → 取消 provider 请求（省 token） |
+| 无 token 超时 | 60s 内无任何事件 → `wf:error { code: 'timeout' }`，随后关闭连接 |
+| 审批超时 | `wf:approval_request.expiresAt` 到期无人批 → 工具以 `tool_result { error: { code: 'timeout' } }` 结束（见 §4.5） |
+
+---
+
+## 2. 事件集总表
+
+| 事件 | 层 | 方向 | 前端处理 | v1 状态 |
+|---|---|---|---|---|
+| `wf:message_start` | 核心 | 下行 | 创建会话/消息 | ✅ 实现 |
+| `wf:token` | 核心 | 下行 | **append** 文本 | ✅ 实现 |
+| `wf:usage` | 核心 | 下行 | 更新 token 计数 | ✅ 实现 |
+| `wf:done` | 核心 | 下行 | 收尾（内容 + usage + 可选 reasoning） | ✅ 实现 |
+| `wf:error` | 核心 | 下行 | 结构化降级（重试/提示） | ✅ 实现 |
+| `wf:tool_call` | 工具 | 下行 | 渲染工具卡片 | ✅ 实现 |
+| `wf:tool_result` | 工具 | 下行 | 卡片 → 结果态 | ✅ 实现 |
+| `wf:tool_progress` | 工具 | 下行 | 卡片 → 进度态 | ✅ 实现 |
+| `wf:step` | agent | 下行 | 步骤可视化 | ✅ 实现（agent 引擎） |
+| `wf:approval_request` | agent | 下行 | 渲染审批卡片（待批态） | ✅ 实现（agent 引擎） |
+| `wf:approval_response` | agent | **上行 POST** | 用户决策回传 | ✅ 实现（ctx.ai.approve） |
+| `x:*` | 自定义 | 双向 | **透传不解释** | ✅ 规则生效 |
+
+**层规则**：只要 chat 的 app 永远不接触工具/agent 事件；前端解码器按层订阅，未订阅的事件跳过不报错。
+
+---
+
+## 3. 核心事件（chat 必需）
+
+### 3.1 `wf:message_start`
+
+```jsonc
+{ "id": "9f3a" }            // 会话/消息 id
+```
+
+- 一条 SSE 流的第一个事件。
+- **`id` 应取 `X-Trace-Id` 请求头**（见 §7 追踪关联），无则后端生成。
+- 前端以 `id` 关联后续所有事件。
+
+### 3.2 `wf:token`
+
+```jsonc
+{ "text": "你好" }          // 增量文本，直接 append
+```
+
+- **纯增量**：前端把 `text` 追加到当前消息尾部，不做 diff/合并。
+- 一个 provider chunk 的 content delta → 一个 `wf:token`（后端不做聚合）。
+
+### 3.3 `wf:usage`
+
+```jsonc
+{ "prompt_tokens": 512, "completion_tokens": 384 }
+```
+
+- provider 返回 usage 时即发（可能出现在流中最后一 chunk，或聚合后一次发）。
+- 前端只更新计数，不改变消息内容。
+
+### 3.4 `wf:done`
+
+```jsonc
+{
+  "content": "你好，有什么可以帮你？",
+  "usage": { "prompt_tokens": 512, "completion_tokens": 384 },
+  "reasoning": "先分析用户意图：……"   // 可选：thinking 模式推理过程（reasoning_content）
+}
+```
+
+- 正常收尾事件：完整内容 + 最终 usage。
+- **`reasoning`（可选，additive）**：thinking 模式（DeepSeek 等）的推理过程，
+  收尾时一次性下发——**v1 不进流式**（`wf:token` 只承载正文增量）；
+  前端以 ReasoningBlock 折叠展示，下一轮回传（`toChatMessages` 带 `reasoning_content`）。
+- 前端标记会话完成（停止打字指示、启用输入框）。
+
+### 3.5 `wf:error`
+
+```jsonc
+{ "code": "rate_limited", "message": "请求过于频繁，请稍后再试" }
+```
+
+- **正常协议消息，连接保持**（除非 code 为致命错误如 `auth_failed`，后端可随后关闭）。
+- 前端按 `code` 分类降级：展示错误、给重试按钮、允许继续会话。
+
+**错误码表（v1 定稿）**：
+
+| code | 含义 | 前端建议 |
+|---|---|---|
+| `auth_failed` | API key 无效/未配置 | 引导配置 |
+| `rate_limited` | provider 限流 | 显示 + 延迟重试 |
+| `context_length` | 上下文超长 | 提示截断/新会话 |
+| `timeout` | 无 token 超时 / 审批超时 | 提示重试 |
+| `provider_error` | provider 返回错误（详情在 message） | 显示 message |
+| `invalid_request` | 请求参数错误 | 修复请求 |
+| `unsupported` | 能力不支持（诚实裁剪，CS-05） | 提示不可用 |
+| `aborted` | 服务端侧主动取消 | 静默 |
+
+---
+
+## 4. 工具事件（chat + tools）
+
+### 4.1 `wf:tool_call`
+
+```jsonc
+{
+  "id": "tc_01",               // 工具调用 id（provider 给 / 后端生成）
+  "name": "query_orders",      // 工具名（app 定义的业务语义，协议不解释）
+  "args": { "userId": "u1" }   // 完整参数
+}
+```
+
+- **后端聚合完成后才发出**：provider 流式 chunk 中 `tool_calls` 的 id 可能只在首个 chunk（DeepSeek 如此），后端负责聚合出完整的 `{ id, name, args }` 再发。前端不接触增量。
+- 并行工具调用 = 连续多条 `wf:tool_call`（各带独立 id），前端可渲染多张卡片。
+- 前端按 `name` 分发渲染（`SearchCard` / `ProgressBar` / …），工具名是 app 的扩展面。
+
+### 4.2 `wf:tool_result`
+
+```jsonc
+{ "id": "tc_01", "ok": true, "output": { "rows": 3 } }
+```
+
+失败形态：
+
+```jsonc
+{ "id": "tc_01", "ok": false, "error": { "code": "rejected", "message": "预算不够" } }
+```
+
+- `error.code`：`rejected`（人工拒绝）/ `timeout`（审批超时）/ `tool_error`（执行异常）/ app 自定义。
+- **`ok: false` 不代表对话结束**——agent 读到 result 后可换方案重试（HITL 核心语义）。
+
+### 4.3 `wf:tool_progress`
+
+```jsonc
+{
+  "toolCallId": "tc_01",
+  "step": 2,
+  "total": 5,
+  "message": "生成第 2 页",
+  "status": "running"          // running | error | done
+}
+```
+
+- 长任务（PPT 生成、委派子 agent、深度搜索）执行期间的进度汇报，前端更新卡片进度条。
+- 秒级任务用此事件；分钟级任务应入队（`ctx.queue`）+ 独立进度通道，见 §9。
+
+### 4.4 工具执行模型
+
+```ts
+// 工具 = 普通对象；run 收到 emit（汇报进度/自定义事件）与 signal（取消）
+tools: [{
+  name: 'generate_ppt',
+  run: async (args, { emit, signal }) => {
+    emit('wf:tool_progress', { step: 1, total: 5, message: '生成大纲' })
+    emit('x:ppt_page_done', { page: 2 })          // 自定义事件
+    return { fileId: 'ppt_01' }                    // → wf:tool_result
+  }
+}]
+```
+
+- `emit` 是工具的执行声道：可发 `wf:tool_progress` 与任意 `x:*` 事件。
+- `signal`：用户取消 → abort → 中断长任务（与 §1.3 生命周期闭环）。
+- 工具名/args 语义是 app 的，协议只定义"调用怎么流动"。
+
+### 4.5 人工审批（HITL，agent 扩展 schema）
+
+**下行** `wf:approval_request`：
+
+```jsonc
+{
+  "id": "ap_01",
+  "toolCallId": "tc_02",
+  "name": "send_email",
+  "args": { "to": "boss@x.com", "subject": "方案" },
+  "reason": "发送前需要确认收件人",
+  "expiresAt": 1735689600000     // 审批超时
+}
+```
+
+发出后**后端挂起该工具执行**，等待上行回传。
+
+**上行** `POST`（`wf:approval_response` 载荷）：
+
+```jsonc
+{
+  "id": "ap_01",
+  "decision": "approved",        // approved | rejected | modified
+  "modifiedArgs": { "to": "me@x.com" },   // 仅 modified
+  "note": "不要群发，只发给我"
+}
+```
+
+**决策语义**：
+
+| decision | 工具行为 | 后续事件 |
+|---|---|---|
+| `approved` | 按原 args 执行 | `wf:tool_result` |
+| `modified` | 按 `modifiedArgs` 执行 | `wf:tool_result` |
+| `rejected` | 不执行 | `wf:tool_result { ok:false, error:{ code:'rejected', message: note } }` → **agent 读 reason 换方案** |
+
+- 审批请求带独立 `id`：并发多卡片各自挂起/恢复；id 一次性（防重放）。
+- 回传端点挂 auth + rateLimit，审批人 `ctx.user` 进审计（app 责任，协议给 id 语义）。
+- 超时：`expiresAt` 到期 → 按 rejected 处理（`error.code: 'timeout'`）。
+
+---
+
+## 5. agent 扩展事件（已实现：src/ai/agent.ts）
+
+### 5.1 `wf:step`
+
+```jsonc
+{ "type": "llm", "content": "正在查询订单…" }
+{ "type": "tool", "toolCallId": "tc_01", "name": "query_orders" }
+```
+
+- 供前端做步骤可视化（思考中/工具执行中/完成）。
+- 由 agent 引擎（`a.agent()`）在每个 LLM 轮次前与每个工具执行前发出。
+
+### 5.2 agent 引擎（`a.agent({ systemPrompt, tools, humanInTheLoop })`）
+
+工具循环：LLM 流式（emit `wf:token`）→ tool_calls → 执行工具 → 结果回喂 → 重复，直到无工具调用或 maxSteps 耗尽。
+
+- 事件序列：`message_start → (step:llm → token* → tool_call → step:tool → [approval_request → approve] → tool_result)* → usage → done`
+- **工具执行上下文**：`run(args, { emit, signal })`——emit `wf:tool_progress` / `x:*` 自定义事件；signal 接收用户取消
+- **HITL 审批**：`humanInTheLoop` 时每个工具执行前挂起等 `ctx.ai.approve()` 响应（见 §4.5）
+- **多轮消息纪律**（真实 DeepSeek 验证）：带 tool_calls 的 assistant 消息必须入上下文；thinking 模式 `reasoning_content` 必须回传（陷阱清单 #4）
+
+### 5.3 子 agent = 工具
+
+多 agent 沟通不新增协议事件：子 agent 通过 `delegate` 工具承载（工具 run 内调 `a.chat()` 或另一个 agent 的循环），其最终输出 = 该工具的 `tool_result`。编排逻辑（委派给谁、何时、如何聚合）是 app 在工具 handler 里的业务。
+
+---
+
+## 6. 扩展机制（协议不是紧身衣）
+
+| 机制 | 规则 |
+|---|---|
+| `x:` 命名空间 | `event: x:any_name`，解码器**透传不解释、不校验、不转换**，前端经 `onEvent` 自处理 |
+| 未知字段透传 | `data` 中未知字段必须原样保留（解码器不得丢弃）——新旧客户端双向兼容 |
+| 未知事件 | 前端**不得抛错**：未订阅的事件跳过（老前端接新后端安全） |
+| 晋升路径 | 2+ app 收敛的 `x:` 事件 → 晋升为 `wf:` 事件 + 协议版本小升 + 前端原语跟进，单包原子发布 |
+
+**规则一句话：`wf:` 是框架的、版本化的、有前端原语覆盖的；其余全是 app 的。**
+
+---
+
+## 7. 追踪关联（trace）
+
+- 前端流式请求应携带 `X-Trace-Id` 请求头（ctx.api 同源生成，一行钩子）。
+- 后端以 `X-Trace-Id` 作为 `wf:message_start.id`（serve.ts 已内置 traceId 机制，接受 `x-trace-id` / `traceparent`，兜底 `randomUUID`，响应头回显）。
+- **工具内发起的后端请求继承同一 traceId** → 整个 agent run（对话 + provider 调用 + 工具内请求）挂在同一 id 下，日志一次搜完。
+
+```
+用户输入 → POST /api/chat (X-Trace-Id: 9f3a)
+        → wf:message_start { id: "9f3a" }
+        → provider 调用（日志带 9f3a）
+        → wf:tool_call query_orders
+          → GET /api/orders（继承 X-Trace-Id: 9f3a）
+        → wf:done
+→ 日志搜 "9f3a" = 整个会话全链路
+```
+
+---
+
+## 8. 共享类型（规范型，`src/ai/types.ts` 据此实现）
+
+```ts
+// ── 事件 ──────────────────────────────────────────────
+
+export interface WfMessageStart { id: string }
+export interface WfToken { text: string }
+export interface WfUsage { prompt_tokens: number; completion_tokens: number; total_tokens?: number }
+export interface WfDone { content: string; usage?: WfUsage; reasoning?: string }
+
+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: string; name: string; args: Record<string, unknown> }
+export interface WfToolResult {
+  id: string
+  ok: boolean
+  output?: unknown
+  error?: { code: string; message: string }   // rejected | timeout | tool_error | app 自定义
+}
+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
+  expiresAt?: number
+}
+export type WfApprovalDecision = 'approved' | 'rejected' | 'modified'
+export interface WfApprovalResponse {
+  id: string
+  decision: WfApprovalDecision
+  modifiedArgs?: Record<string, unknown>
+  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 }
+
+// ── 对话消息（回传 provider 的形状，与 wf: 事件无关）────
+
+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 } }
+```
+
+---
+
+## 9. 诚实裁剪与边界
+
+| 范围 | 状态 |
+|---|---|
+| chat / stream / tools / progress / error 模型 | ✅ v1 实现 |
+| `x:*` 透传、未知事件/字段兼容 | ✅ v1 规则生效 |
+| agent 引擎（`a.agent()`）、`wf:step`、审批事件 | ✅ 已实现 |
+| embeddings | ❌ 不做（DeepSeek 无此 API） |
+| Anthropic/OpenAI 原生协议 | ❌ 不做（OpenAI 兼容已覆盖，baseUrl 可换） |
+| 多 agent 编排 | ❌ 不承诺（子 agent = 工具已覆盖） |
+| 审批持久化 | ❌ 不做（连接断 = 会话亡；持久化等 agent 长任务化 + queue） |
+| 分钟级长任务 | ⚠️ 工具入队即返回（`ctx.queue`），进度走独立通道（WS/SSE 订阅）——app 编排 |
+| 前端通用 HTTP 追踪/时间线面板 | ⏸ 信号（浏览器 DevTools 已覆盖前端部分） |
+
+## 10. 陷阱清单（来自真实实现）
+
+1. **partial chunk / UTF-8 边界**：SSE 解析必须 buffer + `TextDecoder(stream: true)`，`\n` 切行，末段保留到下次。
+2. **`[DONE]` 终止符**：读到即结束，不当作 JSON 解析。
+3. **tool_calls id 只在首个 chunk**（DeepSeek）：后端必须聚合完整 tool_call 再发 `wf:tool_call`；无 id 的后续 chunk 追加到最后一个。
+4. **reasoning_content 必须回传**（thinking 模式）：`ChatMessage.reasoning_content` 随消息往返，否则推理断档。
+5. **SSE 注释行 `:` 与空行**：跳过。
+6. **非 JSON 行**：忽略不抛错。
+7. **usage 可能只在最后一 chunk**（DeepSeek）：聚合后发 `wf:usage`，`wf:done` 再带最终值。
+8. **审批回传 id 一次性**：防重放，用后即焚。

package/docs/components-map.md

@@ -111,6 +111,8 @@
 | 组件 | 说明 |
 |------|------|
 | `<AiChat>` | 完整 AI 对话界面（流式 token/工具卡/审批卡/自动滚动），配 `ctx.ui.useChat()`；移动端 `raiseOnKeyboard` |
+| `<ChatInput>` | 独立聊天输入条（AiChat 抽取）：单行/多行 + streaming 停止 + IME 安全——纯输入层（useChat 组合在消费方） |
+| `<AuthPage>` | 认证页骨架：居中卡片 + logo + 表单插槽 + 错误条 + 提交 loading（登录/注册复用） |
 | `<Markdown content>` | 零依赖安全子集 parser（无 raw HTML 注入，VNode 渲染天然转义） |
 | `<CodeBlock code lang>` | 代码块 + 语言标签 + 复制按钮 |
 | `<MessageBubble role status>` | 聊天气泡（独立复用，AiChat 抽取） |
@@ -129,7 +131,7 @@
 ## 第九批：AI 差异化（109 → 111 组件，2026-08）
 
 > 三库业务组件覆盖 ~100% 后的差异化期——补 AI **输入层 + 推理展示层**。
-> 完整设计/裁剪见 `design/ai-differentiation-plan.md`。
+> 完整设计/裁剪见组件裁剪登记（内部文档，仓库内可查）。
 
 | 组件 | 类型 | 三库等价 | 要点 |
 |------|------|---------|------|
@@ -137,7 +139,7 @@
 | **ReasoningBlock** | 新增 | 三库无 | CoT 推理折叠展示：aria-expanded + 键盘可达 + 流式脉冲 |
 | **AiChat 集成** | 增强 | — | `WfDone.reasoning`（additive，收尾一次性下发）+ use-chat 聚合 + toChatMessages 回传 `reasoning_content`（thinking 模式闭环） |
 
-> 协议变更：`wf:done` 新增可选 `reasoning` 字段（向后兼容），见 `design/ai-contract.md` §3.4。
+> 协议变更：`wf:done` 新增可选 `reasoning` 字段（向后兼容），见 `docs/ai-contract.md` §3.4。
 
 ## 快速迁移路径（三库 → weifuwu）
 
@@ -171,7 +173,7 @@
 | **LogViewer** | 新增 | ANSI 着色 + 虚拟滚动 + follow 自动跟随 + maxLines |
 | **JSONViewer** | 新增 | 递归折叠 + 类型色 + 路径复制 + 懒展开（ToolCallCard 已接入） |
 
-> 三库共识覆盖度 ~100%（剩余均为已声明裁剪项，见 `design/components-roadmap.md` 第六批裁剪清单）。
+> 三库共识覆盖度 ~100%（剩余均为已声明裁剪项，见组件裁剪登记）。
 
 ## 第七批：AI 开发者工具深化（96 → 102 组件）
 
@@ -188,7 +190,7 @@
 
 > AI 开发者工具链成型：AiChat / Command / JSONViewer / LogViewer / DiffView /
 > Pipeline——三库差异化最深的完整工具线。
-> 裁剪声明见 `design/components-roadmap.md` 第七批。
+> 裁剪声明见组件裁剪登记（内部文档）。
 
 ## 第八批：三库并集缺口清零（102 → 113，2026-08）
 
@@ -199,7 +201,7 @@
 |------|------|---------|------|
 | **Layout**（+LayoutHeader/Sider/Content/Footer） | 新增 | antd Layout / EP Container / shadcn Sidebar | 复合子组件双模式；含 Sider → row 布局；Sider 折叠受控/非受控 + trigger |
 | **Popconfirm** | 新增 | antd / EP Popconfirm | 复用 usePopup 基座（弹层组合性）；danger 危险色；确认后自动关闭 |
-| **AutoComplete** | 新增 | antd+EP Autocomplete / shadcn Combobox | 自由输入联想；包含过滤（纯函数）；键盘 ↓↑/Enter/Escape；选中回填 |
+| **AutoComplete** | 新增 | antd+EP Autocomplete / shadcn Combobox | 自由输入联想；包含过滤（纯函数）；键盘 ↓↑/Enter/Escape；选中回填；error 错误态 |
 | **Link** | 新增 | EP Link / antd Typography.Link | 语义色/下划线/disabled/new window/icon |
 | **FloatButton** | 新增 | antd FloatButton（特有） | fixed 定位 + badge + 组展开状态机 |
 | **NavMenu** | 新增 | shadcn NavigationMenu（特有） | 顶部多级 hover 弹出 + 键盘 →/Escape |