weifuwu 0.85.0 → 0.87.0

package/content/components/tree.md

@@ -0,0 +1,59 @@
+# Tree · components
+
+## 概述
+
+树形：递归模型 + 勾选父子联动 + indeterminate（antd/EP Tree）
+
+## 典型场景
+
+- 复杂数据交互——穿梭、树、级联、看板、流水线
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `TreeNode[]` | 否 |  |
+| `selectedKeys` | `string[]` | 否 | 受控选中 keys |
+| `onSelect` | `(keys: string[]) => void` | 否 |  |
+| `expandedKeys` | `string[]` | 否 | 受控展开 keys |
+| `onExpand` | `(keys: string[]) => void` | 否 |  |
+| `checkable` | `boolean` | 否 | 勾选模式（父子联动，antd 非 strict 语义） |
+| `expandOnClick` | `boolean` | 否 | 点击有子节点的行 = 展开/折叠（不触发选中）——TreeSelect 场景（点行展开比点箭头直观） |
+| `checkedKeys` | `string[]` | 否 |  |
+| `onCheck` | `(keys: string[]) => void` | 否 |  |
+| `searchValue` | `string` | 否 | 搜索过滤（label 含 searchValue 的节点 + 祖先；自动展开匹配路径 + 高亮） |
+| `virtual` | `boolean` | 否 | 虚拟滚动（大数据树——固定行高 28px，只渲染可见窗口） |
+| `height` | `number` | 否 | 虚拟滚动视口高度（px） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Tree data={treeData} checkable
+  checkedKeys={keys} onCheck={setKeys} />
+```
+
+## 纪律/坑
+
+- 受控纪律：selectedKeys/checkedKeys/expandedKeys 必须配回调（缺回调 console.warn）
+- 小尺寸 button 固定 min/max-height（§5.6）：checkbox 14x36 竖条事故
+- 虚拟模式（virtual）键盘导航限于可见窗口（VirtualList 无 scrollTo——裁剪登记）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Tree/Tree.ts` |
+| 样式 | `src/client/components/Tree/Tree.css` |
+| 测试 | `src/client/components/Tree/Tree.test.ts` |
+| demo | `apps/showcase/src/demos/DemoToggleTree.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/advanced/tree` ——（P1 填充具体步骤）

package/content/components/treeselect.md

@@ -0,0 +1,54 @@
+# TreeSelect · components
+
+## 概述
+
+树形选择：单选/多选（父子联动）+ 选中 label 回显 + 受控纪律
+
+## 典型场景
+
+- 复杂数据交互——穿梭、树、级联、看板、流水线
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `options` | `TreeNode[]` | 是 | 树选项（复用 TreeNode 结构） |
+| `value` | `string \| string[]` | 否 | 受控：单选 string / 多选 string[] |
+| `onChange` | `(value: any) => void` | 否 | 受控回调：单选 key / 多选 keys[] |
+| `multiple` | `boolean` | 否 | 多选（checkable 父子联动语义） |
+| `placeholder` | `string` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `error` | `string` | 否 |  |
+| `virtual` | `boolean` | 否 | 虚拟滚动（大数据树——透传 Tree；固定行高 28） |
+| `height` | `number` | 否 | 虚拟滚动视口高度（px） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<TreeSelect options={options} value={value} onChange={setValue} />
+```
+
+## 纪律/坑
+
+- 弹窗纪律（§5.4）：曾遗漏 portal——absolute 在父容器 overflow/transform 下裁剪/错位——统一 usePopup
+- 选项量小场景搜索过滤已裁剪（components-cuts.md 永久裁剪）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/TreeSelect/TreeSelect.ts` |
+| 样式 | `src/client/components/TreeSelect/TreeSelect.css` |
+| 测试 | `src/client/components/TreeSelect/TreeSelect.test.ts` |
+| demo | `apps/showcase/src/demos/DemoTreeSelect.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/advanced/treeselect` ——（P1 填充具体步骤）

package/content/components/typography.md

@@ -0,0 +1,51 @@
+# Typography · components
+
+## 概述
+
+Title/Text/Paragraph：语义标签 + 语义色 -text 变体 + mark/code/删除线
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5` | 否 | 1-5，默认 1（h1-h5） |
+| `children` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `style` | `Record<string, string>` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Title level={1}>标题</Title>
+<Text type="secondary">次要</Text>
+<Text type="danger">危险</Text>
+<Text code>code</Text>
+<Paragraph ellipsis>长文本</Paragraph>
+```
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Typography/Typography.ts` |
+| 样式 | `src/client/components/Typography/Typography.css` |
+| 测试 | `src/client/components/Typography/Typography.test.ts` |
+| demo | `apps/showcase/src/demos/DemoTypography.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/typography` ——（P1 填充具体步骤）

package/content/components/videoplayer.md

@@ -0,0 +1,52 @@
+# VideoPlayer · components
+
+## 概述
+
+视频播放器——原生 video 封装（controls/封面/宽高比/事件——零依赖）
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `src` | `string` | 是 |  |
+| `poster` | `string` | 否 |  |
+| `aspect` | `number` | 否 | 宽高比（默认 16/9） |
+| `controls` | `boolean` | 否 |  |
+| `autoPlay` | `boolean` | 否 |  |
+| `loop` | `boolean` | 否 |  |
+| `muted` | `boolean` | 否 |  |
+| `onPlay` | `() => void` | 否 | 事件回调 |
+| `onPause` | `() => void` | 否 |  |
+| `onEnded` | `() => void` | 否 |  |
+| `onError` | `(err: Error) => void` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/VideoPlayer/VideoPlayer.ts` |
+| 样式 | `src/client/components/VideoPlayer/VideoPlayer.css` |
+| 测试 | `src/client/components/VideoPlayer/VideoPlayer.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/videoplayer` ——（P1 填充具体步骤）

package/content/components/virtuallist.md

@@ -0,0 +1,52 @@
+# VirtualList · components
+
+## 概述
+
+虚拟列表：spacer + 可见窗口，200 条只渲染 ~12 个 DOM
+
+## 典型场景
+
+- 大数据列表/表格/树——千级+数据量的性能场景
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `any[]` | 否 |  |
+| `height` | `number` | 否 | 视口高度（px） |
+| `itemHeight` | `number` | 否 | 固定 item 高度（px）——虚拟滚动的基础 |
+| `renderItem` | `(item: any, index: number) => any` | 否 |  |
+| `overscan` | `number` | 否 | 可见区外额外渲染数量 |
+| `keyBy` | `(item: any, index: number) => string \| number` | 否 |  |
+| `emptyText` | `string` | 否 | 空数据占位（F2 状态矩阵——容器类基线） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<VirtualList height={400} itemHeight={36}
+  items={rows} renderItem={renderRow} />
+```
+
+## 纪律/坑
+
+> 大数据渲染：固定行高 + 窗口化（VirtualList）——动态高度裁剪登记
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/VirtualList/VirtualList.ts` |
+| 样式 | `src/client/components/VirtualList/VirtualList.css` |
+| 测试 | `src/client/components/VirtualList/VirtualList.test.ts` |
+| demo | `apps/showcase/src/demos/DemoVirtualList.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/virtual/virtuallist` ——（P1 填充具体步骤）

package/content/components/virtualtable-v2.md

@@ -0,0 +1,39 @@
+# VirtualTable 大数据 · components
+
+## 概述
+
+10 万行虚拟滚动（只渲染可见窗口——性能展示）
+
+## 典型场景
+
+- 大数据列表/表格/树——千级+数据量的性能场景
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<VirtualTable height={280} data={100000行大数据} columns={[{key:'id',label:'ID'}]} />
+```
+
+## 纪律/坑
+
+> 大数据渲染：固定行高 + 窗口化（VirtualList）——动态高度裁剪登记
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoVirtualTableBig.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/virtual/virtualtable-v2` ——（P1 填充具体步骤）

package/content/components/virtualtable.md

@@ -0,0 +1,55 @@
+# VirtualTable · components
+
+## 概述
+
+虚拟表格：10k 行固定表头 + 可见窗口渲染 + 排序
+
+## 典型场景
+
+- 大数据列表/表格/树——千级+数据量的性能场景
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `columns` | `TableColumn[]` | 是 |  |
+| `data` | `any[]` | 否 |  |
+| `height` | `number` | 否 | 视口高度（px），默认 400 |
+| `rowHeight` | `number` | 否 | 行高（px），默认 40 |
+| `overscan` | `number` | 否 | 可见区外额外渲染行数 |
+| `sortKey` | `string` | 否 | 当前排序列 key |
+| `sortOrder` | `'asc' \| 'desc'` | 否 | 当前排序方向 |
+| `onSort` | `(key: string, order: 'asc' \| 'desc') => void` | 否 | 排序变化回调 |
+| `emptyText` | `string` | 否 | 数据为空时显示的文本 |
+| `onRowClick` | `(row: any, index: number) => void` | 否 | 行点击 |
+| `className` | `string` | 否 | 行 key 字段名，默认 'id'；无该字段回退到索引 |
+
+## 用法示例
+
+```tsx
+<VirtualTable columns={cols} data={rows} height={320}
+  sortKey={sortKey} sortOrder={sortOrder} onSort={handleSort} />
+```
+
+## 纪律/坑
+
+> 大数据渲染：固定行高 + 窗口化（VirtualList）——动态高度裁剪登记
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/VirtualTable/VirtualTable.ts` |
+| 样式 | `src/client/components/VirtualTable/VirtualTable.css` |
+| 测试 | `src/client/components/VirtualTable/VirtualTable.test.ts` |
+| demo | `apps/showcase/src/demos/DemoVirtualTable.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/virtual/virtualtable` ——（P1 填充具体步骤）

package/content/components/watermark.md

@@ -0,0 +1,53 @@
+# Watermark · components
+
+## 概述
+
+水印：canvas 平铺绘制 + overlay（antd Watermark）
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `text` | `string` | 否 | 水印文字 |
+| `fontSize` | `number` | 否 |  |
+| `color` | `string` | 否 | 文字颜色（默认继承） |
+| `opacity` | `number` | 否 | 透明度 0-1，默认 0.15 |
+| `rotate` | `number` | 否 | 旋转角度（度），默认 -25 |
+| `gap` | `number` | 否 | 平铺间距（px），默认 100 |
+| `children` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Watermark text="内部资料">
+  <div>内容</div>
+</Watermark>
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Watermark/Watermark.ts` |
+| 样式 | `src/client/components/Watermark/Watermark.css` |
+| 测试 | `src/client/components/Watermark/Watermark.test.ts` |
+| demo | `apps/showcase/src/demos/DemoWatermark.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/watermark` ——（P1 填充具体步骤）

package/content/components/wave.md

@@ -0,0 +1,43 @@
+# Wave · components
+
+## 概述
+
+点击水波纹动效——包装任意可点击元素（纯 CSS，reduced-motion 自动降级）
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `children` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `color` | `string` | 否 | 波纹颜色（默认 currentColor 12% 透明） |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Wave/Wave.ts` |
+| 样式 | `src/client/components/Wave/Wave.css` |
+| 测试 | `src/client/components/Wave/Wave.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/wave` ——（P1 填充具体步骤）

package/content/guides/ai-chat-family.md

@@ -0,0 +1,24 @@
+# AI 会话家族 · components
+
+> AI 会话场景组件族（07 命名治理：**不合并**——每个组件独立深度使用，统一归 ai 分类）。
+> 组合方式：`useChat()` handle 是粘合剂——会话状态 + 流式事件。
+
+| 组件 | 职责 | 组合 |
+|------|------|------|
+| AiChat | 标准对话界面（气泡+工具卡+审批卡+自动滚动） | 接收 useChat handle——最常用 |
+| ChatInput | 独立聊天输入条（IME/多行/流式停止） | AiChat 内部抽取；业务自拼对话页时用 |
+| MessageBubble | 单条消息气泡（role/status/actions） | 自拼对话页 |
+| SessionList | 会话管理列表（分组/重命名/删除/搜索） | 侧栏 |
+| ReasoningBlock | CoT 推理折叠展示 | AiChat renderMessage 内 |
+| ToolCallCard | 工具调用三态卡片 | AiChat 内嵌 |
+| CitationCard | RAG 引用来源展示 | AiChat renderMessage 内 |
+| ApprovalCard | HITL 人工审批（允许/拒绝/修改参数） | AiChat 内嵌；agent 审批流 |
+| PromptTemplate | 提示词模板编辑器（变量插入+预览） | 构建 agent 配置页 |
+
+## 组合示例
+
+```tsx
+// 最小对话页 = ChatInput + MessageBubble + SessionList（业务布局自控）
+// 标准对话 = AiChat（开箱即用）
+// Agent 配置 = PromptTemplate（系统提示词）+ JsonSchemaForm（工具参数）
+```

package/content/guides/choose.md

@@ -0,0 +1,67 @@
+# 选型决策树
+
+> 核心原则：**先查框架再动手**——weifuwu 已提供的能力绝不重复造轮子。
+> 检查顺序：components → layout 原语 → patterns → apps → capabilities。
+
+## 决策树
+
+```
+要做一个界面元素？
+├─ 已有组件（Button/Input/Table/Modal/Tabs/Tree…135 个）
+│   └─ → content/components/<id>.md 查 API + 纪律，直接使用
+├─ 是布局结构（容器/间距/对齐/导航壳/响应式显隐）
+│   └─ → content/layout/*.md 用 wf-* 原语（零手写 CSS）
+│       ├─ 页面骨架 → wf-app-shell / wf-stack / wf-container
+│       ├─ 间距/排版 → wf-gap-* / wf-text-* / wf-p-* 工具
+│       └─ 响应式 → wf-hidden@lg / wf-flex@lg 断点变体
+└─ 是完整页面/应用
+    ├─ 单页结构（后台壳/仪表盘/落地页/移动端）→ content/patterns/*.md 复制
+    ├─ 多页应用（路由 + 状态 + 后端）→ content/apps/*.md 复制模板改
+    │   ├─ 任务管理 → todo
+    │   ├─ 登录/权限 → auth
+    │   ├─ 管理后台 → admin
+    │   └─ 应用编排 → multi
+    └─ 生产级参考 → apps/agent-platform/（真实产品架构）
+```
+
+## 取码（选定后怎么拿源码）
+
+| 选型结果 | 取码路径 |
+|---------|---------|
+| 组件片段 | 组件文档「用法示例」节复制（或 `examples/` 无独立文件——直接按 API 写） |
+| 页面模式 | `examples/patterns/<file>.tsx` 复制文件 |
+| 应用模板 | `examples/apps/<id>/` 整个目录复制（app.tsx + api.ts + server.ts + main.tsx） |
+
+`examples/` 随 npm 包发布——`node_modules/weifuwu/examples/` 可离线取码。
+
+## 组件 vs 原语（最常见混淆）
+
+| 场景 | 用组件 | 用原语 |
+|------|--------|--------|
+| 布局容器/间距/显隐 | ❌ | ✅ wf-stack/wf-grid/wf-gap-* |
+| 导航结构（侧栏/菜单项） | ❌ | ✅ wf-nav/wf-nav-item（或 Menu 组件） |
+| 可交互元素（按钮/输入/选择） | ✅ 组件 | ❌ |
+| 弹层（下拉/弹窗/tooltip） | ✅ 组件（openPopup 命令式） | ❌ |
+| 纯视觉容器（卡片面/分隔） | 两者皆可 | ✅ wf-surface/wf-border |
+
+## 近义组件选型（名字相近/功能重叠——一句话决策）
+
+```
+列表类：List（<500 条）→ VirtualList / VirtualTable（>500 条）
+选择类：固定选项 → Select；自由输入联想 → AutoComplete；纯搜索 → SearchInput
+编辑类：轻量 md → Editor；代码 → CodeEditor；分屏预览 → MarkdownEditor
+树形类：展示/勾选 → Tree；下拉选择 → TreeSelect；路径级联 → Cascader
+折叠类：多开 → Collapse；单开（互斥）→ Accordion
+通知类：轻反馈 → Toast；持久通知 → Notification
+主题类：pressed 语义 → ToggleGroup；选中态样式 → SegmentedControl
+图片类：展示 → Img；裁剪 → ImageCropper；头像 → Avatar
+Office 文档：预览/编辑 → FilePreview；xlsx → FilePreview.Sheet；pptx → FilePreview.Slide
+```
+
+## 关键纪律（选型时就要知道）
+
+1. **浮层必须组件 + openPopup**：dropdown/select/datepicker/menubar/cascader/mentions/contextmenu/tooltip/popover/hovercard/modal/drawer/toast/notification/confirm/tour/command——这些已有组件，直接复用；新弹层组件必须 `ctx.ui.openPopup`（anchor 必传）
+2. **受控组件配回调**：传 active/value/checkedKeys 等受控 props 必须同时传 onChange——缺回调 = 静默不可点
+3. **列表 key 纪律**：有内部状态的组件列表 + 动态增删重排 → 显式 key；纯元素列表 → 无 key（位置身份）
+4. **浏览器能力走 ctx.browser**：禁裸 window/document/localStorage/matchMedia
+

package/content/guides/component-model.md

@@ -0,0 +1,32 @@
+# 两阶段组件模型
+
+```tsx
+const MyComp: Component = async (initProps, ctx) => {   // ── mount（只一次）
+  let count = initProps.initial ?? 0                    // 状态初始化/订阅/定时器
+  return async (props) => {                             // ── render（每次渲染）
+    return h('button', { onClick: () => { count++; ctx.ui.render() } }, count)
+  }
+}
+```
+
+## 职责表
+
+| 阶段 | 职责 | 可访问 | 事件函数 |
+|------|------|--------|---------|
+| mount | 初始化状态/订阅/定时器/稳定引用回调 | initProps、ctx、mount let、稳定 handle | 只依赖稳定引用 → mount 定义（零重绑） |
+| render | 读最新 props/派生数据/输出视图 | 最新 props、mount 闭包、ctx | 依赖最新 props → render 内定义（重绑是正确性要求） |
+| ref | DOM 持有/第三方初始化/清理 | el 或 null | **必须 mount 作用域定义**（内联 ref 每渲染新函数 → ref(null) 反复触发） |
+
+## 铁律
+
+1. **renderFn 强制异步**（`async (props) => Promise<VNode>`）——两阶段都可 await
+2. **渲染只发生在 render() 调用处**——状态是普通对象（let/createStore），无 $ Proxy
+3. **工厂按实例执行**——数据必须走 ctx.data（自带缓存+并发合并）
+4. mount 捕获的 initProps 不得用于渲染（必须用渲染期 props）
+5. 初始状态必须确定性（禁 window.innerWidth 之类直接初始化 → SSR mismatch）
+
+## 相关
+
+- 状态存放：`let` + render()（内部）/ createStore + useExternal（共享）
+- 完整纪律：AGENTS.md §3/§4
+