weifuwu 0.85.0 → 0.87.0

package/content/backend/redis.md

@@ -0,0 +1,26 @@
+# ctx.redis（自研 RESP 协议层） · backend
+
+## 概述
+
+RedisClient 实现 Redis 契约——缓存/计数/发布订阅；演示用 MemoryRedis
+
+## 装配
+
+中间件注入键：`ctx.redis`
+
+## 活体端点
+
+```bash
+curl /api/demo/redis
+```
+
+## 关联组件
+- [Table](../components/table.md)
+
+## 文档素材
+
+来源：`content/guides/data-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/router.md

@@ -0,0 +1,23 @@
+# Router 与请求 · backend
+
+## 概述
+
+Trie 路由 + 路径参数 :id + 通配符 + 方法分发——showcase 自身就是活体证明
+
+## 装配
+
+中间件注入键：`ctx.route`
+
+## 活体端点
+
+```bash
+curl /api/demo/router
+```
+
+## 文档素材
+
+来源：`content/guides/server-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/schedule.md

@@ -0,0 +1,23 @@
+# 定时任务（ctx.schedule/cron） · backend
+
+## 概述
+
+cron 表达式调度——演示：日志计数端点
+
+## 装配
+
+中间件注入键：`ctx.schedule`
+
+## 活体端点
+
+```bash
+curl /api/demo/cron
+```
+
+## 文档素材
+
+来源：`content/guides/saas-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/sql.md

@@ -0,0 +1,27 @@
+# ctx.sql（自研 PG 协议层） · backend
+
+## 概述
+
+PgConnection 实现 Sql 契约——演示用 MemorySql（零 docker），文档说明换 postgres() 一行代码
+
+## 装配
+
+中间件注入键：`ctx.sql`
+
+## 活体端点
+
+```bash
+curl /api/demo/sql
+```
+
+## 关联组件
+- [Form](../components/form.md)
+- [Table](../components/table.md)
+
+## 文档素材
+
+来源：`content/guides/data-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/sse.md

@@ -0,0 +1,26 @@
+# SSE 事件流 · backend
+
+## 概述
+
+Server-Sent Events——服务端推送（流式回复/进度/通知）；wire-fake chat 即活体
+
+## 装配
+
+中间件注入键：`—`
+
+## 活体端点
+
+```bash
+curl /api/chat
+```
+
+## 关联组件
+- [AiChat](../components/aichat.md)
+
+## 文档素材
+
+来源：`content/guides/realtime-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/backend/ws.md

@@ -0,0 +1,26 @@
+# WebSocket · backend
+
+## 概述
+
+app.ws(path, handler)——双向实时（聊天/推送/协作）
+
+## 装配
+
+中间件注入键：`ctx.ws`
+
+## 活体端点
+
+```bash
+curl /ws/echo
+```
+
+## 关联组件
+- [AiChat](../components/aichat.md)
+
+## 文档素材
+
+来源：`content/guides/realtime-guide.md`（迁移至本节——P3）
+
+## 验证
+
+> curl 活体端点断言响应（P2 填充具体断言）

package/content/capabilities/app-node.md

@@ -0,0 +1,21 @@
+# 多应用（registerApp/hApp） · capabilities
+
+## 概述
+
+注册表 + 独立状态 + app:* 边界事件——应用编排
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/registry.ts`
+
+## 平台自证
+
+- multi 应用模板
+
+## 相关纪律
+
+`AGENTS.md §3.3`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/app-node` ——（P1 填充）

package/content/capabilities/data.md

@@ -0,0 +1,21 @@
+# ctx.data 数据管道 · capabilities
+
+## 概述
+
+get/set/has + 并发合并——SSR/hydration/SPA 三场景自动适配
+
+## 框架源码
+
+`src/client/ui-dom/`
+
+## 平台自证
+
+- （P2：示例页）
+
+## 相关纪律
+
+`AGENTS.md §3.4`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/data` ——（P1 填充）

package/content/capabilities/events.md

@@ -0,0 +1,21 @@
+# 事件流（stream） · capabilities
+
+## 概述
+
+DOM↔事件流全链路因果可回放——__wf_tail 实时观测
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/events.ts`
+
+## 平台自证
+
+- __wf_tail 观测面板
+
+## 相关纪律
+
+`AGENTS.md §6`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/events` ——（P1 填充）

package/content/capabilities/hooks.md

@@ -0,0 +1,22 @@
+# hooks 族 · capabilities
+
+## 概述
+
+useMedia/useInView/useChat/usePopup…——事件驱动重渲染
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/`
+
+## 平台自证
+
+- 懒渲染
+- 弹层
+
+## 相关纪律
+
+`AGENTS.md §4.2`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/hooks` ——（P1 填充）

package/content/capabilities/i18n.md

@@ -0,0 +1,21 @@
+# i18n 中间件 · capabilities
+
+## 概述
+
+locale/setLocale/t + 页面级重渲染（demo 专用 AppMiddleware）
+
+## 框架源码
+
+`src/client/ui-dom/i18n.ts`
+
+## 平台自证
+
+- 中英切换
+
+## 相关纪律
+
+`AGENTS.md §4`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/i18n` ——（P1 填充）

package/content/capabilities/popup.md

@@ -0,0 +1,21 @@
+# usePopup 弹窗基座 · capabilities
+
+## 概述
+
+portal + 定位 + 外部点击/Escape + 会话级模态——新弹层一律复用
+
+## 框架源码
+
+`src/client/ui-dom/popup.ts`
+
+## 平台自证
+
+- Drawer/代码抽屉/下拉
+
+## 相关纪律
+
+`AGENTS.md §5.4`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/popup` ——（P1 填充）

package/content/capabilities/render-only.md

@@ -0,0 +1,23 @@
+# render-only 状态 · capabilities
+
+## 概述
+
+只有 ctx.render() 一种触发——状态是普通对象（let/createStore），无 $ Proxy 无隐式触发
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/router.ts`
+
+## 平台自证
+
+- 搜索框
+- 主题切换
+- 应用页内嵌 router
+
+## 相关纪律
+
+`AGENTS.md §4`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/render-only` ——（P1 填充）

package/content/capabilities/router.md

@@ -0,0 +1,22 @@
+# UIRouter 路由 · capabilities
+
+## 概述
+
+pathname 路由 + :param + layout 包裹复用 + 隔离模式（页面内嵌子路由）
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/router.ts`
+
+## 平台自证
+
+- showcase 八域导航
+- app demo 嵌入
+
+## 相关纪律
+
+`AGENTS.md §3.5`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/router` ——（P1 填充）

package/content/capabilities/self-id.md

@@ -0,0 +1,21 @@
+# selfId 精准刷新 · capabilities
+
+## 概述
+
+自定义组件 ID——任意位置 render([id]) 跨组件精准定位
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/`
+
+## 平台自证
+
+- （示例页）
+
+## 相关纪律
+
+`AGENTS.md §4.3`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/self-id` ——（P1 填充）

package/content/capabilities/store.md

@@ -0,0 +1,21 @@
+# createStore + useExternal · capabilities
+
+## 概述
+
+共享状态原语：普通对象 + subscribe/set/update/notify——跨组件通道
+
+## 框架源码
+
+`src/client/ui-dom/store.ts`
+
+## 平台自证
+
+- 主题/语言偏好跨页同步
+
+## 相关纪律
+
+`AGENTS.md §4.5`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/store` ——（P1 填充）

package/content/capabilities/theme.md

@@ -0,0 +1,21 @@
+# 主题系统 · capabilities
+
+## 概述
+
+--wf-* token 双层（亮/暗/自动）+ ThemeSwitch + localStorage 持久化
+
+## 框架源码
+
+`src/layout/_tokens.css`
+
+## 平台自证
+
+- ThemeSwitch 全站
+
+## 相关纪律
+
+`AGENTS.md §8`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/theme` ——（P1 填充）

package/content/capabilities/two-phase.md

@@ -0,0 +1,21 @@
+# 两阶段异步组件 · capabilities
+
+## 概述
+
+mount（工厂，只一次）+ render（每次渲染）——工厂可 await，renderFn 强制异步
+
+## 框架源码
+
+`src/client/ui-dom/vdom3/build.ts`
+
+## 平台自证
+
+- showcase 所有页面
+
+## 相关纪律
+
+`AGENTS.md §3.1`
+
+## 验证
+
+> agent-browser 走查：打开 `/capabilities/two-phase` ——（P1 填充）

package/content/components/accordion.md

@@ -0,0 +1,50 @@
+# Accordion · components
+
+## 概述
+
+折叠面板，支持多个 items
+
+## 典型场景
+
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `items` | `AccordionItem[]` | 否 |  |
+| `active` | `string[]` | 否 | 受控展开 keys |
+| `onChange` | `(keys: string[]) => void` | 否 |  |
+| `multiple` | `boolean` | 否 | true = 多开；默认 false 手风琴互斥（antd 对齐） |
+
+## 用法示例
+
+```tsx
+<Accordion items={[
+  {key:'a',title:'标题',
+    content:<p>内容</p>},
+]} />
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Accordion/Accordion.ts` |
+| 样式 | `src/client/components/Accordion/Accordion.css` |
+| 测试 | `src/client/components/Accordion/Accordion.test.ts` |
+| demo | `apps/showcase/src/demos/DemoAccordion.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/accordion` ——（P1 填充具体步骤）

package/content/components/actionsheet.md

@@ -0,0 +1,46 @@
+# ActionSheet · components
+
+## 概述
+
+动作面板——移动端底部滑出（命令列表 + 取消按钮，usePopup 会话级模态）
+
+## 典型场景
+
+- 浮层交互——弹窗、下拉、气泡、抽屉、命令面板
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `open` | `boolean` | 是 |  |
+| `items` | `ActionSheetItem[]` | 是 |  |
+| `onSelect` | `(key: string) => void` | 否 | 点击项回调（选择后组件自动关闭） |
+| `onClose` | `() => void` | 是 |  |
+| `cancelText` | `string` | 否 | 取消按钮文案（默认「取消」） |
+| `title` | `string` | 否 | 可选标题（面板顶部） |
+
+## 用法示例
+
+> （P1 迁移 CODE 字符串）
+
+## 纪律/坑
+
+> 弹窗纪律（§5.4）：浮层必须 createPortal 渲染（#__wf_portal）——禁 absolute 相对父容器（overflow/transform 裁剪）；统一走 ctx.ui.usePopup
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/ActionSheet/ActionSheet.ts` |
+| 样式 | `src/client/components/ActionSheet/ActionSheet.css` |
+| 测试 | `src/client/components/ActionSheet/ActionSheet.test.ts` |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/overlay/actionsheet` ——（P1 填充具体步骤）

package/content/components/affix.md

@@ -0,0 +1,51 @@
+# Affix · components
+
+## 概述
+
+回到顶部（滚动超 400px 显示）+ 固定导航（距顶 80px 钉住）
+
+## 典型场景
+
+- 页面导航——侧栏、页头、标签页、步骤、分页
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `offsetTop` | `number` | 否 | 距视口顶部偏移，滚动超过该值后固定（px），默认 0 |
+| `target` | `() => HTMLElement \| Window` | 否 | 滚动容器（默认 window） |
+| `children` | `any` | 否 |  |
+| `className` | `string` | 否 |  |
+
+## 用法示例
+
+```tsx
+<BackTop visibilityHeight={400} />
+
+<Affix offsetTop={80}>
+  <nav>固定导航条</nav>
+</Affix>
+```
+
+## 纪律/坑
+
+> 键盘可达（P1）：方向键导航焦点跟随（roving tabindex）；受控 props 配回调
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：（暂无）
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Affix/Affix.ts` |
+| 样式 | `src/client/components/Affix/Affix.css` |
+| 测试 | `src/client/components/Affix/Affix.test.ts` |
+| demo | `apps/showcase/src/demos/DemoAffix.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/navigation/affix` ——（P1 填充具体步骤）

package/content/components/aichat.md

@@ -0,0 +1,57 @@
+# AiChat · components
+
+## 概述
+
+useChat + 标准对话界面：流式 token / 工具卡 / 审批卡 / 自动滚动，协议对页面透明
+
+## 典型场景
+
+- 应用模板：agent-platform（examples/apps/ 完整可跑）
+- AI 对话/工具调用/审批/提示词——agent 场景全链路
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chat` | `UseChatHandle` | 是 | ctx.ui.useChat() 返回的会话 handle（同一 $，状态变化自动重渲染） |
+| `maxHeight` | `string` | 否 | 消息列表最大高度（默认 '70vh'） |
+| `labels` | `Partial<AiChatLabels>` | 否 | 界面文案覆盖 |
+| `renderMessage` | `(msg: UiMessage) => any` | 否 | 自定义气泡渲染逃生舱（默认纯文本） |
+| `renderToolArgs` | `(args: Record<string, unknown>) => any` | 否 | 工具参数渲染（透传 ToolCallCard） |
+| `approveSchema` | `(request: WfApprovalRequest) => JsonSchema \| undefined` | 否 | 审批修改参数：按审批请求返回工具参数 schema（返回 undefined 则审批卡无修改入口； |
+| `raiseOnKeyboard` | `boolean` | 否 | 键盘弹起时输入区 fixed 抬升（全屏 chat 布局用；内联卡片默认 false——原生聚焦滚动已够） |
+
+## 用法示例
+
+```tsx
+const chat = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+return () => <AiChat chat={chat} />
+
+// 状态：chat.messages / chat.input / chat.streaming / chat.error
+// 操作：chat.send() / chat.stop() / chat.retry() / chat.approve(decision)
+// 订阅共享：ctx.ui.useExternal(chat) —— 子组件共享会话状态
+// agent 消息内嵌：msg.toolCalls / msg.approval
+```
+
+## 纪律/坑
+
+> AI 协议纪律：消息流事件驱动（useChat 订阅）——高频 notify 由写者控制频率
+
+## 关系
+
+- ↑ 用于页面模式：（暂无）
+- ↑ 用于应用：[agent-platform](../apps/agent-platform.md)
+- → 后端能力：[ws](../backend/ws.md) · [sse](../backend/sse.md) · [ai](../backend/ai.md)
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/AiChat/AiChat.ts` |
+| 样式 | `src/client/components/AiChat/AiChat.css` |
+| 测试 | `src/client/components/AiChat/AiChat.test.ts` |
+| demo | `apps/showcase/src/demos/DemoAiChat.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/ai/aichat` ——（P1 填充具体步骤）

package/content/components/alert.md

@@ -0,0 +1,52 @@
+# Alert · components
+
+## 概述
+
+信息提示条，4 种 variant + closable
+
+## 典型场景
+
+- 页面模式：focus-task、settings-page（复制即用蓝本——examples/patterns/）
+- 应用模板：auth（examples/apps/ 完整可跑）
+- 操作反馈/结果页/确认——保存成功、删除确认、空态/加载态
+
+## API
+
+| prop | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `variant` | `AlertVariant` | 否 |  |
+| `closable` | `boolean` | 否 |  |
+| `onClose` | `() => void` | 否 |  |
+| `children` | `any` | 否 |  |
+
+## 用法示例
+
+```tsx
+<Alert variant="info">提示</Alert>
+<Alert variant="success">成功</Alert>
+<Alert variant="warning">警告</Alert>
+<Alert variant="error" closable>错误</Alert>
+```
+
+## 纪律/坑
+
+> 退场动画（§8）：exit 类必须挂载（animationend 驱动）+ reduced-motion 降级
+
+## 关系
+
+- ↑ 用于页面模式：[focus-task](../patterns/focus-task.md) · [settings-page](../patterns/settings-page.md)
+- ↑ 用于应用：[auth](../apps/auth.md)
+- → 后端能力：（暂无）
+
+## 文件位置
+
+| 文件 | 路径 |
+|------|------|
+| 源码 | `src/client/components/Alert/Alert.ts` |
+| 样式 | `src/client/components/Alert/Alert.css` |
+| 测试 | `src/client/components/Alert/Alert.test.ts` |
+| demo | `apps/showcase/src/demos/DemoAlert.tsx`（P1 拆分） |
+
+## 验证
+
+> agent-browser 走查：打开 `/components/feedback/alert` ——（P1 填充具体步骤）