weifuwu 0.85.0 → 0.87.0

package/content/components/markdown.md

@@ -0,0 +1,51 @@
+# Markdown · components
+
+## 概述
+
+AI 回复渲染：安全子集 parser + 代码块 + 链接白名单
+
+## 典型场景
+
+- 数据展示——列表页、详情页、信息呈现
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `content` | `string` | 是 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Markdown content={"# 标题
+
+**粗体** 与 `code`
+
+- 列表项
+
+[链接](https://weifuwu.dev)"} />
+```
+
+## 纪律/坑
+
+> 三层一致（§6.3）：条件渲染 false 是空洞占位——数组项 key 由业务声明
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Markdown/Markdown.ts` |
+| 样式 | `src/client/components/Markdown/Markdown.css` |
+| 测试 | `src/client/components/Markdown/Markdown.test.ts` |
+| demo | `apps/showcase/src/demos/DemoMarkdown.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/display/markdown` ——（P1 填充具体步骤）

package/content/components/markdowneditor.md

@@ -0,0 +1,47 @@
+# MarkdownEditor · components
+
+## 概述
+
+分屏 Markdown 编辑器——textarea + 实时预览（复用 Markdown parser 零漂移）
+
+## 典型场景
+
+- office 文档/代码/内容编辑——xlsx/pptx/代码/公式/裁剪
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string` | 是 |  |
+| `onChange` | `(value: string) => void` | 否 |  |
+| `placeholder` | `string` | 否 |  |
+| `mode` | `'write' \| 'preview' \| 'split'` | 否 | 初始模式：'write' | 'preview' | 'split'（默认 split） |
+| `rows` | `number` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 内容编辑：textarea value 走 property（attribute 只是 defaultValue）；受控输入纪律
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/MarkdownEditor/MarkdownEditor.ts` |
+| 样式 | `src/client/components/MarkdownEditor/MarkdownEditor.css` |
+| 测试 | `src/client/components/MarkdownEditor/MarkdownEditor.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/editor/markdowneditor` ——（P1 填充具体步骤）

package/content/components/math.md

@@ -0,0 +1,42 @@
+# Math · components
+
+## 概述
+
+轻量公式渲染——自研 LaTeX 子集（上下标/分数/根号/希腊字母——零依赖不引 KaTeX）
+
+## 典型场景
+
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tex` | `string` | 是 | LaTeX 公式（如 'x^2 + \\frac{1}{2}'） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Math/Math.ts` |
+| 样式 | `src/client/components/Math/Math.css` |
+| 测试 | `src/client/components/Math/Math.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/math` ——（P1 填充具体步骤）

package/content/components/mentions-v2.md

@@ -0,0 +1,39 @@
+# Mentions 禁用态 · components
+
+## 概述
+
+disabled 时不可输入（状态矩阵覆盖）
+
+## 典型场景
+
+- 表单输入/搜索/筛选——查询区、编辑表单、设置页
+
+## API
+
+> props 提取降级（接口格式特殊）——见源码：`—`
+
+## 用法示例
+
+```tsx
+<Mentions options={users} disabled rows={2} placeholder="输入 @ 提及成员…" />
+```
+
+## 纪律/坑
+
+> 受控输入纪律（§5.3）：输入期间 value 走内部态（useControlledInput）——依赖回流会重挂 input 丢焦点；IME composition 门控
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| demo | `apps/showcase/src/demos/DemoMentionsDis.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/input/mentions-v2` ——（P1 填充具体步骤）

package/content/components/mentions.md

@@ -0,0 +1,52 @@
+# Mentions · components
+
+## 概述
+
+@提及：composition 抑制 + 过滤插入（antd Mentions）
+
+## 典型场景
+
+- 复杂数据交互——穿梭、树、级联、看板、流水线
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `value` | `string` | 否 |  |
+| `onChange` | `(value: string) => void` | 否 |  |
+| `options` | `MentionsOption[]` | 否 |  |
+| `prefix` | `string` | 否 | 触发字符，默认 '@' |
+| `placeholder` | `string` | 否 |  |
+| `rows` | `number` | 否 |  |
+| `disabled` | `boolean` | 否 |  |
+| `size` | `'sm' \| 'md' \| 'lg'` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Mentions options={[{value:'alice',label:'Alice'}]}
+  value={text} onChange={setText} />
+```
+
+## 纪律/坑
+
+> （该分类暂无通用纪律——组件级事故见源码注释）
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Mentions/Mentions.ts` |
+| 样式 | `src/client/components/Mentions/Mentions.css` |
+| 测试 | `src/client/components/Mentions/Mentions.test.ts` |
+| demo | `apps/showcase/src/demos/DemoMentions.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/advanced/mentions` ——（P1 填充具体步骤）

package/content/components/menu.md

@@ -0,0 +1,56 @@
+# Menu · components
+
+## 概述
+
+侧栏导航：分组 + 图标 + 选中态 + 方向键
+
+## 典型场景
+
+- 应用模板：admin、agent-platform（examples/apps/ 完整可跑）
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `MenuItem[]` | 是 |  |
+| `onSelect` | `(key: string) => void` | 否 |  |
+| `activeKey` | `string` | 否 |  |
+| `className` | `string` | 否 |  |
+| `openKeys` | `string[]` | 否 | 受控展开 key 列表（子菜单） |
+| `onOpenChange` | `(keys: string[]) => void` | 否 |  |
+| `collapsible` | `boolean` | 否 | 可折叠侧栏（宽度收窄 + label 隐藏） |
+| `collapsed` | `boolean` | 否 |  |
+| `onCollapseChange` | `(collapsed: boolean) => void` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Menu items={[
+  { key: 'agents', label: 'Agent 管理', icon: <Icon name="cpu" size={16} />, group: '工作台' },
+  { key: 'settings', label: '设置', icon: <Icon name="settings" size={16} />, group: '系统' },
+]} activeKey="agents" onSelect={k => setActive(k)} />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：[admin](../apps/admin.md) · [agent-platform](../apps/agent-platform.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Menu/Menu.ts` |
+| 样式 | `src/client/components/Menu/Menu.css` |
+| 测试 | `src/client/components/Menu/Menu.test.ts` |
+| demo | `apps/showcase/src/demos/DemoMenu.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/menu` ——（P1 填充具体步骤）

package/content/components/menubar.md

@@ -0,0 +1,44 @@
+# Menubar · components
+
+## 概述
+
+水平菜单栏：←→ 切换 + ↓ 展开（shadcn Menubar）
+
+## 典型场景
+
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `menus` | `MenubarMenu[]` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Menubar menus={[{key:'file',label:'文件',items:[...]}]} />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Menubar/Menubar.ts` |
+| 样式 | `src/client/components/Menubar/Menubar.css` |
+| 测试 | `src/client/components/Menubar/Menubar.test.ts` |
+| demo | `apps/showcase/src/demos/DemoMenubar.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/menubar` ——（P1 填充具体步骤）

package/content/components/messagebubble.md

@@ -0,0 +1,50 @@
+# MessageBubble · components
+
+## 概述
+
+消息气泡：user/assistant + streaming/error 状态 + actions
+
+## 典型场景
+
+- AI 对话/工具调用/审批/提示词——agent 场景全链路
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `content` | `any` | 是 |  |
+| `role` | `MessageBubbleRole` | 是 |  |
+| `status` | `MessageBubbleStatus` | 否 |  |
+| `actions` | `any` | 否 | 气泡尾部操作区（重试/复制按钮等，VNode 或数组） |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<MessageBubble role="user" content="北京天气如何？" />
+<MessageBubble role="assistant" status="streaming" content="…"
+  actions={<Button size="sm">重试</Button>} />
+```
+
+## 纪律/坑
+
+> AI 协议纪律：消息流事件驱动（useChat 订阅）——高频 notify 由写者控制频率
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/MessageBubble/MessageBubble.ts` |
+| 样式 | `src/client/components/MessageBubble/MessageBubble.css` |
+| 测试 | `src/client/components/MessageBubble/MessageBubble.test.ts` |
+| demo | `apps/showcase/src/demos/DemoMessageBubble.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/ai/messagebubble` ——（P1 填充具体步骤）

package/content/components/modal.md

@@ -0,0 +1,59 @@
+# Modal · components
+
+## 概述
+
+自定义宽度 + closable 控制关闭按钮
+
+## 典型场景
+
+- 应用模板：agent-platform（examples/apps/ 完整可跑）
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `open` | `boolean` | 否 |  |
+| `title` | `string` | 否 |  |
+| `onClose` | `() => void` | 否 |  |
+| `children` | `any` | 否 |  |
+| `footer` | `any` | 否 |  |
+| `width` | `string` | 否 | 自定义宽度，如 '500px'、'80%'，默认 400px |
+| `closable` | `boolean` | 否 | 是否显示关闭按钮，默认 true |
+| `maskClosable` | `boolean` | 否 | 点击遮罩是否关闭，默认 true（危险确认应设 false） |
+
+## 用法示例
+
+```tsx
+<Modal open={open}
+  title="标题"
+  width="500px"
+  closable={false}
+  onClose={() => open = false}>
+  <p>内容</p>
+</Modal>
+```
+
+## 纪律/坑
+
+- 退场动画：exit 类必须挂载（animationend 驱动卸载）——reduced-motion 下动画降为 0.01ms 等效瞬时
+- 会话级模态四件套：presence/trapFocus/lockScroll 由 usePopup 统一提供
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：[agent-platform](../apps/agent-platform.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Modal/Modal.ts` |
+| 样式 | `src/client/components/Modal/Modal.css` |
+| 测试 | `src/client/components/Modal/Modal.test.ts` |
+| demo | `apps/showcase/src/demos/DemoModal.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/modal` ——（P1 填充具体步骤）

package/content/components/navmenu.md

@@ -0,0 +1,47 @@
+# NavMenu · components
+
+## 概述
+
+顶部导航：多级 hover 弹出 + 键盘（shadcn NavigationMenu）
+
+## 典型场景
+
+- 应用模板：admin（examples/apps/ 完整可跑）
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `NavMenuItem[]` | 是 |  |
+| `activeKey` | `string` | 否 |  |
+| `onSelect` | `(key: string) => void` | 否 |  |
+
+## 用法示例
+
+```tsx
+<NavMenu items={items} activeKey="home" onSelect={go} />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：[admin](../apps/admin.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/NavMenu/NavMenu.ts` |
+| 样式 | `src/client/components/NavMenu/NavMenu.css` |
+| 测试 | `src/client/components/NavMenu/NavMenu.test.ts` |
+| demo | `apps/showcase/src/demos/DemoNavMenu.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/navmenu` ——（P1 填充具体步骤）

package/content/components/notification.md

@@ -0,0 +1,51 @@
+# Notification · components
+
+## 概述
+
+队列式通知：notification.success/error/warning 命令式（antd 对齐）
+
+## 典型场景
+
+- 操作反馈/结果页/确认——保存成功、删除确认、空态/加载态
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `NotificationItem[]` | 否 |  |
+| `onRemove` | `(id: string) => void` | 否 |  |
+| `position` | `NotificationPosition` | 否 |  |
+| `duration` | `number` | 否 | 全局默认自动关闭时间（ms），默认 4500 |
+| `max` | `number` | 否 | 最大显示条数，超出移除最早，默认 0 = 不限制 |
+
+## 用法示例
+
+```tsx
+notification.success({
+  title: '部署成功',
+  description: 'v0.63.0 已上线',
+})
+```
+
+## 纪律/坑
+
+> 退场动画（§8）：exit 类必须挂载（animationend 驱动）+ reduced-motion 降级
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Notification/Notification.ts` |
+| 样式 | `src/client/components/Notification/Notification.css` |
+| 测试 | `src/client/components/Notification/Notification.test.ts` |
+| demo | `apps/showcase/src/demos/DemoNotification.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/feedback/notification` ——（P1 填充具体步骤）

package/content/components/pageheader.md

@@ -0,0 +1,53 @@
+# PageHeader · components
+
+## 概述
+
+页面标题栏，支持 sub + 右侧操作区 + display 大标题
+
+## 典型场景
+
+- 页面模式：app-shell、dashboard、list-page、detail-page、settings-page（复制即用蓝本——examples/patterns/）
+- 应用模板：todo（examples/apps/ 完整可跑）
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | `string` | 是 |  |
+| `sub` | `string` | 否 |  |
+| `display` | `boolean` | 否 | 顶级页面大标题（display 档 30px），默认 21px |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<PageHeader title="用户管理" sub="管理平台所有用户的账号、角色与权限">
+  <Button size="sm" variant="primary">新建用户</Button>
+  <Button size="sm">导出</Button>
+</PageHeader>
+<PageHeader display title="大标题模式" />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：[app-shell](../patterns/app-shell.md) · [dashboard](../patterns/dashboard.md) · [list-page](../patterns/list-page.md) · [detail-page](../patterns/detail-page.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：[todo](../apps/todo.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/PageHeader/PageHeader.ts` |
+| 样式 | `src/client/components/PageHeader/PageHeader.css` |
+| 测试 | `src/client/components/PageHeader/PageHeader.test.ts` |
+| demo | `apps/showcase/src/demos/DemoPageHeader.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/pageheader` ——（P1 填充具体步骤）

package/content/components/pagination.md

@@ -0,0 +1,49 @@
+# Pagination · components
+
+## 概述
+
+分页器，自动计算页码范围
+
+## 典型场景
+
+- 页面模式：app-shell、list-page（复制即用蓝本——examples/patterns/）
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `total` | `number` | 是 |  |
+| `page` | `number` | 否 |  |
+| `pageSize` | `number` | 否 |  |
+| `onChange` | `(page: number) => void` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Pagination total={200}
+  page={page} onChange={fn} />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：[app-shell](../patterns/app-shell.md) · [list-page](../patterns/list-page.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Pagination/Pagination.ts` |
+| 样式 | `src/client/components/Pagination/Pagination.css` |
+| 测试 | `src/client/components/Pagination/Pagination.test.ts` |
+| demo | `apps/showcase/src/demos/DemoPagination.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/pagination` ——（P1 填充具体步骤）

package/content/components/paragraph.md

@@ -0,0 +1,45 @@
+# Paragraph · components
+
+## 概述
+
+段落排版——Typography 家族
+
+## 典型场景
+
+- 页面模式：docs、landing（复制即用蓝本——examples/patterns/）
+- 基础元素（按钮/图标/文本/卡片/标签）——任意页面的构成单元
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5` | 否 | 1-5，默认 1（h1-h5） |
+| `children` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+| `style` | `Record<string, string>` | 否 |  |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 浏览器纪律（§5.5）：组件能力经 ctx.browser / ctx.ui.useXXX——禁裸 window/document
+
+## 关系
+
+- ↑ 用于页面模式：[docs](../patterns/docs.md) · [landing](../patterns/landing.md)
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Typography/Typography.ts` |
+| 样式 | `src/client/components/Typography/Typography.css` |
+| 测试 | `src/client/components/Typography/Typography.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/core/paragraph` ——（P1 填充具体步骤）