weifuwu 0.64.0 → 0.64.1

package/README.md

@@ -44,7 +44,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 | 认证 / 消息 / 队列 | **随包内置、互相咬合** | 自选 + 自缝 | 自选 + 自缝 |
 | 部署 | 一个 Node 进程 + PG + Redis | 各组件自理 | 平台绑定 |
 
-> 定位不是「替代某个框架」，而是**包换包**：用 weifuwu 一个依赖替换你原本要缝合的整套栈。心智模型有借鉴（两阶段组件接近 React、中间件接近 Express），但每一层都是自研的确定性实现——组件模型见[核心概念](#核心概念)，与 antd/Element Plus/shadcn 的对应见 `design/components-map.md`。
+> 定位不是「替代某个框架」，而是**包换包**：用 weifuwu 一个依赖替换你原本要缝合的整套栈。心智模型有借鉴（两阶段组件接近 React、中间件接近 Express），但每一层都是自研的确定性实现——组件模型见[核心概念](#核心概念)，与 antd/Element Plus/shadcn 的对应见 [docs/components-map.md](docs/components-map.md)。
 
 ### 从这里开始
 
@@ -495,6 +495,7 @@ README 只保留入门内容（设计理念 / 快速开始 / 核心概念 / 模
 | [docs/examples.md](docs/examples.md) | 组合场景示例：登录表单 / 数据列表 + 搜索 / 消息提示 |
 | [docs/environment.md](docs/environment.md) | 环境变量与开发命令 |
 | [docs/mobile.md](docs/mobile.md) | 移动端开发指南：断点 / 44px 命中区 / usePopup / 手势 / safe-area |
+| [docs/components-map.md](docs/components-map.md) | 组件速查：weifuwu ↔ antd / Element Plus / shadcn 对应 + 迁移路径 |
 | [design/](design/) | 设计与计划文档（组件地图 / AI 协议契约 / 移动端指南 / 数据库客户端计划 / 设计系统 / 各阶段计划） |
 
 > `docs/` 用户文档随 npm 包发布（`files: ['dist/', 'README.md', 'docs/']`）——`node_modules/weifuwu/docs` 可离线查阅；`design/` 设计/计划文档仅仓库内。

package/docs/components-map.md

@@ -0,0 +1,153 @@
+# weifuwu/components 组件速查（对应 antd / Element Plus / shadcn-ui）
+
+> **开发者迁移速查**：从 antd / Element Plus / shadcn-ui 迁到 weifuwu，按功能找到对应组件。
+> 左侧是 **weifuwu 组件**（已提供），右侧是对应的三库组件 + 差异备注。
+> 真实未实现清单（仅 4 项）：见文末「weifuwu 尚未实现」。
+
+## 通用基础
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 按钮 | `<Button variant size loading block>` | Button | Button | Button | 命名基本一致；weifuwu `variant`=primary/secondary/ghost/danger |
+| 图标 | `<Icon name>`（自研 30+ stroke SVG） | Icon | Icon | lucide-react | weifuwu 零依赖、currentColor、1em 随字号；组件内部统一走 Icon |
+| 文本排版 | `<Title/Text/Paragraph>` | Typography | Typography | — | 语义标签 + 语义色 `-text` 变体 + mark/code/删除线 |
+| 分割线 | `<Divider>`（horizontal/vertical/带文字） | Divider | Divider | Separator | 等价 |
+| 头像 | `<Avatar name src color size>` | Avatar | Avatar | Avatar | weifuwu 支持名字哈希色 + 指定色 |
+| 头像组 | `<AvatarGroup items max size>` | Avatar.Group | 手动组合 | 手动组合 | weifuwu 独立组件，`max` 溢出显示 +N |
+| 标签/标签组 | `<Label>`（required 星号）/ `<TagsInput>`（回车/逗号/去重） | Form.Item 标签 / Select tags | — | Label | Label 独立组件 |
+
+## 导航
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 菜单/侧栏 | `<Menu items group activeKey onSelect>`（方向键导航） | Menu | Menu | NavigationMenu / Sidebar | 分组 group 已支持；**子菜单/折叠未实现** |
+| 面包屑 | `<Breadcrumb items>` | Breadcrumb | Breadcrumb | Breadcrumb | 等价 |
+| 标签页 | `<Tabs items active onChange>`（方向键 + 移动端横向滚动） | Tabs | Tabs | Tabs | 等价 |
+| 分页 | `<Pagination total page onChange>`（页码折叠 + 移动端 44px） | Pagination | Pagination | Pagination | 等价 |
+| 步骤条 | `<Steps items current>` | Steps | Steps | — | 等价 |
+| 下拉菜单 | `<Dropdown items>`（danger variant） | Dropdown | Dropdown | DropdownMenu | 等价（usePopup：外部点击/Escape 关闭） |
+| 水平菜单栏 | `<Menubar menus>`（←→↓ 键盘 + 触屏） | Menu 水平 | Menu | Menubar | 等价 |
+| 页面标题 | `<PageHeader title sub>` | PageHeader（v5 移除） | PageHeader | — | weifuwu 保留独立组件 |
+| 回到顶部 | `<BackTop threshold>` | FloatButton / BackTop | Backtop | — | 滚动超阈值显示 |
+| 固定定位 | `<Affix offsetTop>` | Affix | Affix | — | useScrollPosition 实现 |
+| 锚点 | 未实现 | Anchor | Anchor | — | 待补 |
+
+## 表单
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 输入框 | `<Input label error hint variant>` | Input | Input | Input | weifuwu 自带 label/error/hint 包装（antd 需 Form.Item）；`variant="borderless"` 内联编辑 |
+| 文本域 | `<Textarea rows showCount maxLength>` | Input.TextArea | Input textarea | Textarea | weifuwu 独立组件 + 字数统计 |
+| 选择器 | `<Select options searchable multiple>` | Select | Select | Select / Combobox | **searchable + 键盘 ↑↓ + multiple 已实现**（近 Combobox） |
+| 复选框 | `<Checkbox checked label>` | Checkbox | Checkbox | Checkbox | 等价 |
+| 复选组 | `<CheckboxGroup options value>` | Checkbox.Group | Checkbox 组 | — | 数组受控 + 栅格列数 |
+| 单选 | `<RadioGroup options value>` | Radio.Group | Radio | RadioGroup | 等价 |
+| 开关 | `<Switch checked>` | Switch | Switch | Switch | 等价 |
+| 滑块 | `<Slider min max step>` | Slider | Slider | Slider | 等价 |
+| 数字输入 | `<InputNumber min max step precision>`（增减按钮+clamp） | InputNumber | InputNumber | — | 等价 |
+| 密码输入 | `<PasswordInput>`（眼睛切换） | Input.Password | Input show-password | — | weifuwu 独立组件 |
+| 日期选择 | `<DatePicker mode="date\|datetime\|time\|range">`（四合一） | DatePicker / TimePicker / RangePicker | DatePicker / DateTimePicker / TimePicker | Calendar + DatePicker 组合 | **一个组件覆盖三库四个**；移动端 range 自动堆叠 |
+| 评分 | `<Rate value>`（键盘方向键） | Rate | Rate | — | allowClear/readOnly |
+| 验证码 | `<PinInput length>`（粘贴/回退/自动聚焦） | — | — | InputOTP | 等价 |
+| 颜色选择 | `<ColorPicker value>`（预设色板 + hex） | ColorPicker | ColorPicker | — | Popover 弹层 |
+| 标签输入 | `<TagsInput value onChange>`（回车/逗号/去重） | Select mode="tags" | 手动组合 | — | weifuwu 独立组件 |
+| 搜索框 | `<SearchInput>` | Input.Search | Input search | — | weifuwu 独立组件 |
+| 分段控件 | `<SegmentedControl options value>` | Segmented | — | ToggleGroup 近似 | weifuwu 独立组件 |
+| 切换按钮 | `<Toggle>/<ToggleGroup>`（single/multiple） | — | — | ToggleGroup | shadcn 对齐 |
+| 表单 | `<Form>` + `<Field label error>`（校验规则） | Form + Form.Item | Form + Form.Item | Form | weifuwu Field 轻量（无 Provider 样板） |
+| 文件上传 | `<FileUpload drag multiple accept maxSize>` | Upload | Upload | — | 拖拽已支持；文件列表/预览/进度待增强 |
+
+## 数据展示
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 表格 | `<Table columns data sortable onSort>` | Table | Table | Table | 列排序 + **行选择/筛选/列宽已实现**；虚拟表格待补 |
+| 卡片 | `<Card clickable hover padding>` | Card | Card | Card | clickable/hover 抬升/active 选中态 |
+| 标签 | `<Tag variant closable>` | Tag | Tag | Badge（variant） | closable 已支持 |
+| 徽标 | `<Badge variant dot>`（8px 状态点） | Badge | Badge | Badge | `dot` = 状态点 |
+| 列表 | `<List items renderItem empty>` | List | 手动 v-for | — | 通用列表 |
+| 时间线 | `<Timeline items status>` | Timeline | Timeline | — | 节点状态色 + 图标 |
+| 描述列表 | `<Descriptions items column bordered>`（dl/dt/dd 语义） | Descriptions | Descriptions | — | 等价 |
+| 统计卡片 | `<StatCard label value trend animate>` | Statistic | Statistic | — | 卡片形态 + 点击 + 动画 |
+| 图片 | `<Img src fallback lazy preview>` | Image | Image | — | **preview 点击放大已实现** |
+| 图表 | `<Chart type data>`（自研零依赖） | — | — | Chart（recharts 包装） | 自研 line/bar/pie，无运行时依赖 |
+| 骨架屏 | `<Skeleton variant count>` | Skeleton | Skeleton | Skeleton | 等价 |
+| 空状态 | `<EmptyState icon text hint>` | Empty | Empty | — | icon 用 emoji/Icon + 操作区 |
+| 结果页 | `<Result status title desc extra>` | Result | Result | — | 等价（success/error/warning/info） |
+| 搜索高亮 | `<Highlight text query>`（`<mark>` 分词） | — | — | — | weifuwu 独有（配 SearchInput/Table） |
+| 树 | `<Tree data checkable checkedKeys>` | Tree | Tree | — | 勾选父子联动 + indeterminate |
+| 级联 | `<Cascader options value>` | Cascader | Cascader | — | 多列面板逐级推进 |
+| 穿梭框 | `<Transfer data targetKeys>` | Transfer | Transfer | — | 双列表 + 移动；移动端自动堆叠 |
+| 月历 | `<Calendar month year events>` | Calendar | Calendar | — | 事件点 + 月切换 |
+| 虚拟列表 | `<VirtualList height itemHeight>` | — | — | — | spacer + 可见窗口，200 条只渲染 ~12 |
+
+## 反馈
+
+| 功能 | weifuwu | antd | Element Plus | shadcn-ui | 差异说明 |
+|------|---------|------|-------------|-----------|---------|
+| 提示条 | `<Alert variant closable>` | Alert | Alert | Alert | 等价 |
+| 模态框 | `<Modal open title onClose width>` | Modal | Dialog | Dialog | `open/onClose`（antd v5 同）；焦点 trap + 归还；移动端 bottom-sheet |
+| 确认框 | `<Confirm>` + `await confirm()` 命令式 | Popconfirm / Modal.confirm | Popconfirm / MessageBox | AlertDialog | 声明式 + 命令式双模式 |
+| 抽屉 | `<Drawer position="left\|right\|top\|bottom">` | Drawer | Drawer | Sheet / Drawer | **四方向覆盖 shadcn Sheet + Drawer**；移动端全宽 |
+| 气泡 | `<Popover position>`（视口夹紧） | Popover | Popover | Popover | 等价（usePopup：外部点击/Escape/tap 降级） |
+| 悬浮提示 | `<Tooltip content position>`（string） | Tooltip | Tooltip | Tooltip | usePopup：桌面 hover / 触屏 tap |
+| 悬停卡 | `<HoverCard content>`（富内容 + 延迟） | — | — | HoverCard | shadcn 对齐；触屏 tap |
+| 右键菜单 | `<ContextMenu items>` | Dropdown context | — | ContextMenu | 桌面右键 + **触屏长按**双通道 |
+| 消息 | `<Toast>` + `toast()` 命令式 | message | Message | Sonner | 命令式 `toast('已保存','success')` |
+| 通知 | `<Notification>` + `notification.success()` | notification | Notification | — | 队列式通知 |
+| 加载 | `<Loading>` | Spin | Loading | — | 等价 |
+| 进度条 | `<ProgressBar value>` | Progress | Progress | Progress | 等价（线性） |
+| 折叠 | `<Collapse items active>`（异步 loading + extra） | Collapse | Collapse | Collapse | 行内折叠（区别于 Accordion） |
+| 手风琴 | `<Accordion items>` | Collapse accordion | Collapse accordion | Accordion | 单开折叠 |
+| 复制按钮 | `<CopyButton value>`（clipboard + 降级 + 成功态） | — | — | — | Chat/CodeBlock 证据驱动 |
+| 水印 | `<Watermark text>`（canvas 平铺 + overlay） | Watermark | — | — | 自研 |
+| 二维码 | `<QRCode value>`（Reed-Solomon + 8 掩码） | QRCode | QRCode | — | **自研编码零依赖** |
+| 轮播 | `<Carousel autoplay>`（箭头/圆点/循环 + 触摸） | Carousel | Carousel | — | 触摸滑动 + 触屏命中区 |
+| 分割面板 | `<Resizable defaultSize>`（拖拽 + 键盘 + clamp） | Splitter | — | Resizable | 指针 + 方向键 |
+| 回到顶部按钮 | `<BackTop>` | FloatButton.BackTop | Backtop | — | 滚动监听 |
+
+## AI / 特色（三库无，weifuwu 独有）
+
+| 组件 | 说明 |
+|------|------|
+| `<AiChat>` | 完整 AI 对话界面（流式 token/工具卡/审批卡/自动滚动），配 `ctx.ui.useChat()`；移动端 `raiseOnKeyboard` |
+| `<Markdown content>` | 零依赖安全子集 parser（无 raw HTML 注入，VNode 渲染天然转义） |
+| `<CodeBlock code lang>` | 代码块 + 语言标签 + 复制按钮 |
+| `<MessageBubble role status>` | 聊天气泡（独立复用，AiChat 抽取） |
+| `<ToolCallCard>` | AI 工具调用状态机（running/ok/error） |
+| `<ApprovalCard>` | HITL 人工审批卡片（pending/approved/rejected/timeout） |
+| `<Editor>` | 富文本编辑器（contentEditable + 工具栏/表格/图片，零依赖） |
+| `<ThemeSwitch>` | 明暗主题切换（CSS 变量驱动，配 `data-theme`） |
+| `<InView>` | 交叉观察（进入视口触发，可做无限滚动） |
+| `<AspectRatio>` | 宽高比容器（内容填满） |
+| `<CopyButton>` | 复制（clipboard + execCommand 降级 + 成功状态机） |
+
+## 快速迁移路径（三库 → weifuwu）
+
+```tsx
+// antd / shadcn 开发者
+<Modal open={show} onClose={f}>…</Modal>          // antd v5 同命名，直接迁移
+<Select options={opts} value={v} onChange={f} />   // 同命名
+<Button variant="primary">保存</Button>            // antd type="primary" → variant
+
+// Element Plus 开发者（v-model 模板语法 → value/onChange）
+<Input :value="v" @input="f" />                    // → <Input value={v} onInput={f} />
+<ElDialog :visible="s" @close="f" />               // → <Modal open={s} onClose={f} />
+<ElMessage>成功</ElMessage>                        // → toast('成功','success')
+
+// shadcn 开发者（原子组合 → 成品）
+<Dialog><DialogTrigger/>…</Dialog>                 // → <Modal open onClose> 一体组件
+<Sheet><SheetTrigger/>…</Sheet>                    // → <Drawer position="bottom">
+<Badge variant="secondary">x</Badge>               // → <Tag variant="secondary">x</Tag>
+```
+
+## weifuwu 尚未实现（三库有）→ 待补清单
+
+仅 4 项：
+
+- **Anchor**（锚点导航，三库均有）
+- **Menu 子菜单/折叠**（分组 group 已支持，子级/折叠待补）
+- **FileUpload 增强**（拖拽已支持；文件列表/预览/进度待补）
+- **VirtualTable**（VirtualList 已有，表格虚拟化待补）
+
+> 难度阶梯（L1-L6）与验证的 client 能力点：见 `design/components-cdd.md`；三库 → weifuwu 覆盖矩阵：见 `design/components-migration.md`。

package/docs/components.md

@@ -4,7 +4,7 @@
 
 92 个 HTML 原语组件。每个是 `(_init, ctx) => (props) => VNode`（两阶段组件，与前端框架同一模型），引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
 
-> **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`design/components-map.md`](../design/components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
+> **组件速查（weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例）**：见 [`docs/components-map.md`](components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -163,6 +163,350 @@ props 变化 ──────────────────────
 | `局部刷新` | `ctx.ui.render()` 或 `$.x = val` |
 | `跨组件刷新` | `ctx.ui.selfId('name')` + `render(['name'])` |
 
+## 通用约定（所有组件一致）
+
+### 受控模式
+
+| 组件类型 | 受控 prop | 必须配回调 |
+|----------|-----------|-----------|
+| 开关/勾选（Checkbox/Switch/RadioGroup） | `checked` | `onChange` |
+| 输入（Input/Select/DatePicker/Textarea） | `value` | `onChange` / `onInput` |
+| 标签页/折叠（Tabs/Collapse） | `active` | `onChange` |
+| 弹层（Modal/Drawer/Dropdown/Popover） | `open` | `onClose` / `onOpenChange` |
+| 树/级联/穿梭（Tree/Cascader/Transfer） | `checkedKeys`/`value`/`targetKeys` | `onChange` |
+| 月历（Calendar） | `month`/`year` | `onMonthChange` |
+
+**规则**：传受控 props 而不传回调时，交互**静默失效**——组件 `console.warn` 明确提示（Collapse/Tree/Calendar/Cascader/Dropdown 已有防护）。非受控（不传受控 props）即可直接点击。
+
+### size 变体
+
+- `sm` / `md` / `lg`（Button/Avatar/Input 族）。未提供 size 的组件使用默认尺寸（CSS `--wf-control-pad-*` 驱动）。
+- 触屏（coarse pointer）自动 44px 命中区，不受 size 影响。
+
+### 事件命名
+
+| 语义 | 命名 |
+|------|------|
+| 值变化（受控） | `onChange` |
+| 原生输入 | `onInput` |
+| 列表选中 | `onSelect` |
+| 弹层开关 | `onOpenChange`（弹层）/ `onClose`（对话框） |
+| 表格排序 | `onSort` |
+
+### 命令式 API（无需组件）
+
+`confirm()` / `toast()` / `notification.success()`——组件内 `ctx.confirm?.('确定？')` 直接可用（中间件注入）。
+
+## 关键组件 Props 参考
+> 从组件 TS 类型自动提取（`src/components/*/*.ts` 的 `interface XxxProps`）。
+> 完整 props 以 TS 类型为准——`tsc` 编译期校验；此处为速查。受控约定：传受控 props 必须配回调（缺回调运行期 warn）。
+
+### Button（表单/通用）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | — |
+| `size` | `'sm' \| 'md' \| 'lg'` | — |
+| `block` | `boolean` | — |
+| `loading` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `type` | `'button' \| 'submit'` | — |
+| `title` | `string` | — |
+| `class` | `string` | 透传原生 class（覆盖默认 wf-btn 组合） |
+| `onClick` | `(e: MouseEvent) => void` | — |
+| `children` | `any` | — |
+
+### Input（表单核心）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `name` | `string` | — |
+| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'url' \| 'date' \| 'tel' \| 'time' \| 'color'` | — |
+| `value` | `string` | — |
+| `placeholder` | `string` | — |
+| `required` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `variant` | `'default' \| 'borderless'` | 边框变体：borderless 用于可编辑标题/内联编辑（hover/focus 才显边框） |
+| `onInput` | `(e: Event) => void` | — |
+| `onChange` | `(e: Event) => void` | — |
+| `min` | `string \| number` | 原生 input 属性透传（type=number 时 min/max/step 等） |
+| `max` | `string \| number` | — |
+| `step` | `string \| number` | — |
+| `key` | `string]: any` | — |
+
+### Textarea（表单核心）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `value` | `string` | — |
+| `placeholder` | `string` | — |
+| `required` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `rows` | `number` | — |
+| `maxLength` | `number` | 最大字符数（同时限制输入） |
+| `showCount` | `boolean` | 显示字数统计（右下角；配合受控 value 实时更新） |
+| `onInput` | `(e: Event) => void` | — |
+
+### Select（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `value` | `string \| string[]` | — |
+| `options` | `SelectOption[]` | — |
+| `placeholder` | `string` | — |
+| `required` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `onChange` | `(value: string \| string[]) => void` | — |
+| `children` | `any` | — |
+| `searchable` | `boolean` | 启用搜索过滤 |
+| `multiple` | `boolean` | 多选模式（searchable 下生效；value/onChange 为数组） |
+| `onSearch` | `(keyword: string) => SelectOption[] \| Promise<SelectOption[]>` | 异步搜索回调，返回值作为新选项列表 |
+
+### Checkbox（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `checked` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `onChange` | `(checked: boolean) => void` | — |
+
+### Switch（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `checked` | `boolean` | — |
+| `disabled` | `boolean` | — |
+| `onChange` | `(checked: boolean) => void` | — |
+
+### RadioGroup（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | — |
+| `value` | `string` | — |
+| `options` | `RadioOption[]` | — |
+| `inline` | `boolean` | — |
+| `onChange` | `(value: string) => void` | — |
+
+### DatePicker（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `mode` | `DatePickerMode` | — |
+| `value` | `string` | — |
+| `onChange` | `(value: string) => void` | — |
+| `placeholder` | `string` | — |
+| `disabled` | `boolean` | — |
+
+### Form（表单增强）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `onSubmit` | `(values: Record<string, any>) => void \| Promise<void>` | 提交回调，接收字段名→值的对象 |
+| `validation` | `Record<string, ValidationRule[]>` | 验证规则：字段名 → 规则数组 |
+| `onError` | `(errors: Record<string, string>) => void` | 验证失败时回调，接收字段名→错误消息的对象 |
+| `children` | `any` | — |
+
+### Field（表单增强）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `required` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `children` | `any` | — |
+
+### Table（数据展示）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `data` | `any[]` | — |
+| `columns` | `TableColumn[]` | — |
+| `onRowClick` | `(row: any, index: number) => void` | — |
+| `sortKey` | `string` | 当前排序列的 key |
+| `sortOrder` | `'asc' \| 'desc'` | 当前排序方向 |
+| `onSort` | `(key: string, order: 'asc' \| 'desc') => void` | 排序变化回调 |
+| `rowSelection` | `TableRowSelection` | 行选择（受控） |
+| `emptyText` | `string` | 数据为空时显示的文本 |
+| `minWidth` | `string` | 表格最小宽度（窄屏横向滚动，如 '720px'） |
+| `loading` | `boolean` | 加载中：保留表头，渲染骨架行 |
+| `loadingRows` | `number` | 骨架行数，默认 3 |
+
+### Modal（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `open` | `boolean` | — |
+| `title` | `string` | — |
+| `onClose` | `() => void` | — |
+| `children` | `any` | — |
+| `footer` | `any` | — |
+| `width` | `string` | 自定义宽度，如 '500px'、'80%'，默认 400px |
+| `closable` | `boolean` | 是否显示关闭按钮，默认 true |
+| `maskClosable` | `boolean` | 点击遮罩是否关闭，默认 true（危险确认应设 false） |
+
+### Drawer（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `open` | `boolean` | — |
+| `title` | `string` | — |
+| `position` | `DrawerPosition` | — |
+| `onClose` | `() => void` | — |
+| `children` | `any` | — |
+| `footer` | `any` | — |
+
+### Confirm（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `open` | `boolean` | — |
+| `title` | `string` | — |
+| `message` | `any` | 提示内容（文本或任意 VNode） |
+| `confirmText` | `string` | — |
+| `cancelText` | `string` | — |
+| `variant` | `'primary' \| 'danger'` | — |
+| `width` | `string` | 对话框宽度，如 '500px'、'80%'，默认 Modal 的 400px |
+| `maskClosable` | `boolean` | 遮罩点击是否取消（默认 false：危险操作防误触；显式传 true 可恢复） |
+| `onConfirm` | `() => void` | — |
+| `onCancel` | `() => void` | — |
+
+### Toast（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `toasts` | `ToastItem[]` | — |
+| `onRemove` | `(id: string) => void` | — |
+| `position` | `ToastPosition` | 容器位置，默认 top-right |
+| `duration` | `number` | 全局默认自动消失时间（ms），0 = 不自动消失，默认 0 |
+| `max` | `number` | 最大显示条数，超出时移除最早条目，默认 0 = 不限制 |
+
+### Tooltip（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `content` | `string` | — |
+| `position` | `TooltipPosition` | — |
+| `children` | `any` | — |
+| `disabled` | `boolean` | — |
+
+### Popover（数据反馈）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `content` | `any` | — |
+| `trigger` | `'click' \| 'hover'` | — |
+| `position` | `PopoverPosition` | — |
+| `open` | `boolean` | — |
+| `onOpenChange` | `(open: boolean) => void` | — |
+| `disabled` | `boolean` | — |
+| `children` | `any` | — |
+
+### Dropdown（导航组件）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `trigger` | `any` | — |
+| `items` | `DropdownItem[]` | — |
+| `open` | `boolean` | — |
+| `onOpenChange` | `(open: boolean) => void` | 关闭回调（面板内 Escape / 外部点击） |
+
+### Tabs（导航组件）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `items` | `TabItem[]` | — |
+| `active` | `string` | — |
+| `onChange` | `(key: string) => void` | — |
+
+### Pagination（导航组件）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `total` | `number` | — |
+| `page` | `number` | — |
+| `pageSize` | `number` | — |
+| `onChange` | `(page: number) => void` | — |
+
+### Tree（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `data` | `TreeNode[]` | — |
+| `selectedKeys` | `string[]` | 受控选中 keys |
+| `onSelect` | `(keys: string[]) => void` | — |
+| `expandedKeys` | `string[]` | 受控展开 keys |
+| `onExpand` | `(keys: string[]) => void` | — |
+| `checkable` | `boolean` | 勾选模式（父子联动，antd 非 strict 语义） |
+| `checkedKeys` | `string[]` | — |
+| `onCheck` | `(keys: string[]) => void` | — |
+| `className` | `string` | — |
+
+### Cascader（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `options` | `CascaderOption[]` | — |
+| `value` | `string[]` | 选中路径（数组，如 ['zj','hz','xh']） |
+| `onChange` | `(value: string[]) => void` | — |
+| `placeholder` | `string` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `label` | `string` | — |
+
+### Transfer（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `data` | `TransferItem[]` | — |
+| `targetKeys` | `string[]` | 目标侧已选 keys |
+| `onChange` | `(targetKeys: string[]) => void` | — |
+| `titles` | `[string, string]` | — |
+| `size` | `'sm' \| 'md' \| 'lg'` | — |
+| `disabled` | `boolean` | — |
+
+### Carousel（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `children` | `any[]` | — |
+| `autoplay` | `boolean` | 自动播放 |
+| `interval` | `number` | 自动播放间隔（ms），默认 3000 |
+| `showArrows` | `boolean` | — |
+| `showDots` | `boolean` | — |
+| `loop` | `boolean` | 循环播放（尾 → 头），默认 true |
+| `className` | `string` | — |
+
+### Calendar（新增批次）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `events` | `CalendarEvent[]` | — |
+| `month` | `number` | 受控年月：month 0-11，year 四位数 |
+| `year` | `number` | — |
+| `onMonthChange` | `(month: number, year: number) => void` | — |
+| `onSelectDate` | `(date: string) => void` | — |
+| `selectedDate` | `string` | — |
+
+### AiChat（AI 交互）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `chat` | `UseChatHandle` | ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） |
+| `maxHeight` | `string` | 消息列表最大高度（默认 '70vh'） |
+| `labels` | `Partial<AiChatLabels>` | 界面文案覆盖 |
+| `renderMessage` | `(msg: UiMessage) => any` | 自定义气泡渲染逃生舱（默认纯文本） |
+| `renderToolArgs` | `(args: Record<string, unknown>) => any` | 工具参数渲染（透传 ToolCallCard） |
+| `raiseOnKeyboard` | `boolean` | 键盘弹起时输入区 fixed 抬升（全屏 chat 布局用；内联卡片默认 false——原生聚焦滚动已够） |
+
+### FileUpload（表单增强）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `accept` | `string` | — |
+| `multiple` | `boolean` | — |
+| `maxSize` | `number` | — |
+| `disabled` | `boolean` | — |
+| `error` | `string` | — |
+| `hint` | `string` | — |
+| `value` | `File[]` | — |
+| `onChange` | `(files: File[]) => void` | — |
+| `children` | `any` | — |
+
+### Slider（表单选择）
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `label` | `string` | — |
+| `value` | `number \| string` | — |
+| `min` | `number` | — |
+| `max` | `number` | — |
+| `step` | `number` | — |
+| `onChange` | `(value: number) => void` | — |
+
 ## 组件列表
 
 ### 表单核心

package/docs/environment.md

@@ -2,26 +2,50 @@
 
 > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
 
-| 变量 | 用途 | 模块 |
-|------|------|------|
-| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres()` |
-| `REDIS_URL` | Redis 连接字符串 | `redis()` |
+## 环境变量
+
+| 变量 | 用途 | 模块 | 默认 |
+|------|------|------|------|
+| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgres()` | —（必填） |
+| `REDIS_URL` | Redis 连接字符串 | `redis()` | `redis://localhost:6379` |
+| `AUTH_SECRET` | userSystem HMAC 签名密钥（≥16 字符） | `userSystem()` | 可传 `options.secret` |
+| `DEEPSEEK_API_KEY` | LLM 对话 provider API key | `ai()` | — |
+| `DEEPSEEK_BASE_URL` | LLM 对话 provider 端点 | `ai()` | `https://api.deepseek.com/v1` |
+| `DEEPSEEK_MODEL` | 默认对话模型 | `ai()` | `deepseek-v4-flash` |
+| `DASHSCOPE_API_KEY` | embedding 向量化 provider key | `ai({ embedding })` | — |
+| `DASHSCOPE_BASE_URL` | embedding provider 端点 | `ai({ embedding })` | — |
+| `DASHSCOPE_EMBEDDING_MODEL` | embedding 模型名 | `ai({ embedding })` | — |
+| `RESEND_API_KEY` | 邮件 adapter `resend` | `email()` | 可用 `options.resend` |
+| `SMTP_HOST` | 邮件 adapter `smtp` | `email()` | `localhost` |
+| `SMTP_PORT` | SMTP 端口 | `email()` | `3025` |
+
+> 均可通过中间件 options 显式传入（`postgres({ url })` / `userSystem({ secret })` / `ai({ provider })`），环境变量为默认来源。
 
 ---
 
-# 开发命令
+## 开发命令
 
 ```bash
 npm run build       # 构建 dist/
 npm run typecheck   # TypeScript 类型检查
-npm test            # 运行 node --test
-node scripts/release.mjs <version>   # 发布
+npm test            # 运行 node --test（含 docker 真库测试）
+node scripts/release.mjs <version>   # 构建 + 发布 + git tag
 ```
 
 ```bash
-# 测试前启动依赖服务
+# 测试前启动依赖服务（postgres / redis / smtp）
 docker compose up -d
 ```
 
 ---
 
+## 应用示例启动
+
+```bash
+# 组件 cheatsheet（零依赖）
+cd apps/components-demo && node server.ts
+
+# 全栈 SaaS 示例（多租户 AI 平台）
+cd apps/agent-platform && npm run seed && npm run dev
+# 凭据：admin@demo.com / admin123
+```

package/docs/frontend.md

@@ -153,6 +153,8 @@ ctx.ui.render(['name'])
 | `render()` | `render(ids?: string[])` | 同步强制渲染；无参 = 当前组件，传参 = 指定组件列表 |
 | `dirty()` | `dirty(ids?: string[])` | 异步渲染（微任务批处理合并）；`$` 内部就是调它 |
 | `selfId()` | `selfId(name: string)` | 注册组件自定义 ID，配合 `render(['id'])` 跨组件精准刷新 |
+| `useChat()` | `useChat({ url, approveUrl?, body? })` | AI 对话会话：消息/流式/工具/审批，与 `$` 同容器（AiChat 配套） |
+| `useAsync()` | `useAsync(fetcher)` | 异步取数：`data/loading/error` 响应式 + `reload()` |
 | `useMedia()` | `useMedia(query, cb)` | 响应式媒体查询，断点变化时自动回调 |
 | `useBreakpoint()` | `useBreakpoint(cb \| bps, cb?)` | 命名断点 mobile/tablet/desktop |
 | `usePopupPosition()` | `usePopupPosition(opts)` | 弹层坐标跟随：scroll/resize 时自动重算 fixed 坐标 |
@@ -412,6 +414,54 @@ ctx.ui.render(['stats'])        // 同步刷新
 - **同名冲突直接抛错**，每个自定义 ID 必须全局唯一
 - 配合 `selfId` 注册的组件在跨组件场景下无需把刷新逻辑层层传 props
 
+#### `ctx.ui.useChat(options)` — AI 对话会话（AiChat 配套）
+
+会话语义的流式 AI 状态容器：消息累积 / 工具调用内嵌 / HITL 审批 / stop / retry，协议对页面完全透明（wf: 协议见 `design/ai-contract.md`）。返回的 handle 与 `ctx.ui.$()` **同一个 $**（页面状态与会话状态共处一容器）：
+
+```tsx
+// mount 阶段（服务端 `ai()` 中间件 + `AiChat` 组件配套）
+const $ = ctx.ui.useChat({
+  url: '/api/chat',          // POST 端点（返回 wf: SSE 流）
+  approveUrl: '/api/approve', // HITL 审批上行（缺省时 approve() 只清卡片）
+  body: (messages) => ({ messages, mode: 'agent' }),  // 定制请求体
+  onEvent: (name, data) => { console.log('x:' + name, data) },  // x:* 透传
+})
+
+return (props) =>
+  h('div', {},
+    h(AiChat, { chat: $ }),        // 标准对话界面：流式 token/工具卡/审批卡/自动滚动
+    $.streaming ? '生成中…' : '',  // 会话状态与页面状态同容器
+  )
+```
+
+**状态（`$` 上）**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `$.messages` | `UiMessage[]` | 消息列表（`{ id, role, content, status, toolCalls?, approval?, usage?, error? }`） |
+| `$.input` | `string` | 输入框值（双向绑定） |
+| `$.streaming` | `boolean` | 是否正在流式生成 |
+| `$.error` | `WfError \| null` | 最近错误（code + message） |
+| `$.usage` | `WfUsage \| null` | token 用量（prompt/completion/total） |
+| `$.step` | `WfStep \| null` | 最近 agent 步骤指示（思考/工具），done/error 时清空 |
+
+**操作（`$` 上的方法）**：`$.send()`（发送当前输入）/ `$.stop()`（中止）/ `$.retry()`（截断到最后一条 user 重生成）/ `$.clear()`（清空）/ `$.approve(decision, note?)`（响应审批）/ `$.dispose()`（卸载时释放流）。
+
+**共享 $ 的子组件**（如 `<AiChat chat={$}>`）：父组件 dirty 不驱动子组件（三态 skip），子组件 mount 阶段 `chat.__watch?.(() => ctx.ui.dirty())` 自订阅（AiChat 已内置）。
+
+#### `ctx.ui.useAsync(fetcher)` — 异步取数
+
+`data/loading/error` 响应式 + `reload()` 重跑；数据就绪自动渲染当前组件。
+
+```tsx
+const list = ctx.ui.useAsync(() => ctx.api.get<User[]>('/users'))
+
+return () => list.loading ? h(Loading) : list.data?.map(u => h('div', {}, u.name))
+```
+
+- `list.data` / `list.loading` / `list.error` 赋值自动 dirty 当前组件
+- `list.reload()` 重跑；组件卸载后旧 Promise resolve 不再触发渲染（idRegistry 查无此组件，安全忽略）
+
 #### CSS 层响应式（不碰 JS）
 
 配合 `weifuwu/layout` 的断点变体，纯 CSS 实现布局方向切换：

package/package.json

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