weifuwu 0.94.0 → 0.95.0

package/dist/level6/apps/agent-platform/docs/archive/MULTI-AGENT-PLAN.md

@@ -0,0 +1,177 @@
+# Agent 协作专项计划（Multi-Agent Collaboration）
+
+> ## ✅ 已归档（2026-12）——M1-M4 全部完成
+>
+> 执行记录：M1 工具定义 + 执行器（TDD 11 测试）→ M2 内置工具自动加入
+> （call_agent 开箱可用）+ 浏览器端到端验收 → M3 深度防环/循环拒绝/租户隔离
+> → M4 子日志落库（department_id 可空）+ 全量 90 绿。提交 `9b8ecc60`。
+> 浏览器实测：A 调 B → call_agent → [数据分析师 的回复] → A 整合转述 →
+> 父子两条 agent_logs（A 4634 / B 2846 tokens）。
+>
+> 保留本文档作为决策与实施记录。
+
+> Wave 6-9 已形成平台底座（模板/版本/配额/审计/留存/可观测性）。
+> 本计划是 P2 最后一个大项：**Agent 之间通过工具化调用协作**。
+> 原则：先 TDD 后实现；诚实裁剪；真实浏览器验收。
+
+---
+
+## 1. 定位与目标
+
+**核心能力**：Agent A 在对话中通过「调用 Agent B」工具，把任务委托给专业 Agent（如「数据分析师」被「开发助手」调用查数据）。
+
+**用户价值**：
+- 专业分工：每个 Agent 单一职责（客服/数据分析/开发），复杂任务由编排 Agent 调度
+- 复用知识库/工具：Agent B 的知识库、文件工具对 Agent A 透明
+- 审批联动：HITL 在子 Agent 上同样生效（父 Agent 等子结果）
+
+**非目标（裁剪）**：
+- 可视化 DAG 编排（拖拽）——需求未验证，先用「工具化调用」探路
+- Agent 之间自由对话（消息路由）——限于「工具调用 + 结果返回」的请求-响应模式
+- 并行多 Agent（fan-out）——先单调用串行，后续按需扩展
+
+---
+
+## 2. 架构设计：Agent 作为工具
+
+### 2.1 模型
+
+```
+用户 → Agent A（编排/客服）
+         └─ 调用工具 call_agent(agent_id, message)
+              ├─ Agent B 的 Tool Loop（复用 agent-runner）
+              ├─ B 的上下文 = A 的 message（+ B 自己的 system_prompt）
+              └─ 结果（B 的最终回复）返回给 A → A 继续
+```
+
+### 2.2 关键设计决策
+
+| 决策 | 选择 | 理由 |
+|---|---|---|
+| 调用方式 | 新工具 `call_agent`（进 Agent 的工具注册表） | 复用现有 Tool Loop——Agent 天然会"思考→调用→整合" |
+| 子 Agent 上下文 | 只传 message（不含父完整对话） | 隔离上下文、防上下文膨胀；子 Agent 自带 system_prompt |
+| 结果格式 | 子 Agent 最终 content（文本） | 简单可读；工具结果对 A 是字符串 |
+| 深度限制 | `max_agent_depth`（默认 2） | 防 A→B→C→A 循环 |
+| 权限 | 只能调用**同租户**的 ai 类型 Agent | 租户隔离 + 只调 AI（不调 user/webhook） |
+| 并发 | 串行（A 等 B 结果） | 单 Agent 工具调用天然串行；并行后续扩展 |
+| 错误处理 | B 失败 → 工具返回错误文本 → A 可重试/换策略 | Tool Loop 已有错误返回语义 |
+
+### 2.3 工具定义（tools/registry.ts 扩展）
+
+```ts
+// builtin.ts 新增：
+{
+  function: {
+    name: 'call_agent',
+    description: '调用同租户的另一个 AI Agent 处理任务（传入其名称或 ID + 任务描述），返回其回复。用于专业分工：把子任务委托给擅长该领域的 Agent。',
+    parameters: {
+      type: 'object',
+      properties: {
+        agent: { type: 'string', description: '目标 Agent 名称或 ID' },
+        message: { type: 'string', description: '委托给该 Agent 的任务描述' },
+      },
+      required: ['agent', 'message'],
+    },
+  },
+}
+```
+
+### 2.4 执行器（agent-runner 扩展）
+
+```
+call_agent 处理器：
+1. 校验：同租户 + ai 类型 + is_active + depth < max_agent_depth
+2. 构造子 Agent 会话：system_prompt（B）+ 用户消息（父传入 message）
+3. 调 runAgent(ctx, B, [message])——复用现有 Tool Loop
+4. 返回 { ok, output: B 的最终 content }（或错误文本）
+```
+
+**复用要点**：子 Agent 的工具（文件/知识库/call_agent）全部可用——**递归协作**（B 也可调 C，深度限制防环）。
+
+---
+
+## 3. 数据模型
+
+### 3.1 无需新表（工具是运行时的）
+
+`call_agent` 是内置工具——Agent 是否可用由 `agents.tools` 决定（启用该工具 = 允许协作）。
+
+**可选优化**（二期）：显式「协作白名单」——`agent_links` 表（from_agent → to_agent 允许列表），防 Agent 被任意调用。一期裁剪（同租户 + ai 类型即可）。
+
+### 3.2 agent_logs 记录
+
+子 Agent 调用在 agent_logs 留痕（steps_count/messages_count）——审计可追踪：
+- 父 Agent 的日志：steps 含 call_agent
+- 子 Agent 的日志：独立一条（含传入 message）
+
+---
+
+## 4. 实现步骤（TDD 先行）
+
+### Step 1: 工具定义 + 注册（红→绿）
+- [ ] 测试：`call_agent` 工具定义存在（name/description/parameters）
+- [ ] 注册进 BUILTIN_TOOL_DEFS（tools/builtin.ts）
+
+### Step 2: 执行器（核心——TDD）
+- [ ] 测试（mock AI）：`call_agent` 处理器调用子 Agent → 返回子回复
+  - 场景 1：A 调 B（B 无工具）→ 返回 B 的 content
+  - 场景 2：B 失败 → 返回错误文本（A 可读）
+  - 场景 3：目标不存在/非 ai 类型/异租户 → 明确错误
+  - 场景 4：深度超限（A→B→C→D）→ 深度错误
+  - 场景 5：B 自己调用 call_agent（递归）→ 深度递增
+- [ ] 实现 `runAgent` 的工具处理器分支（agent-runner.ts）
+
+### Step 3: 前端暴露
+- [ ] AgentDetail「工具」区可选 `call_agent`（已支持 tools 编辑）
+- [ ] 工具卡片显示「调用 Agent X」+ 子结果（Chat 工具卡片已支持展开）
+- [ ] 测试（agent-browser 实测）：建两个 Agent → 聊天让 A 调 B → 子回复显示
+
+### Step 4: 安全与限制
+- [ ] 深度限制（max_agent_depth=2）——防环
+- [ ] 超时：子 Agent 调用超时（父侧兜底）——复用现有 60s 流式超时
+- [ ] 配额联动：子 Agent 调用计入其 token 配额（复用 agent_logs 月度累计）
+
+### Step 5: 测试补强
+- [ ] services.test.ts：call_agent 处理器（mock AI 链）
+- [ ] 浏览器验收：端到端（父 Agent 调子 Agent 返回结果）
+
+---
+
+## 5. 安全边界
+
+| 风险 | 防护 |
+|---|---|
+| 循环调用（A→B→A） | max_agent_depth=2（深度超限工具报错） |
+| 跨租户调用 | 执行器校验 `to_agent.app_id === ctx.appId` |
+| 资源消耗（子 Agent 链） | 深度限制 + 子 Agent 自身配额 + 60s 超时 |
+| 任意 Agent 被调用 | 一期：同租户 ai 类型即可；二期：协作白名单 |
+| 敏感信息泄漏 | 子 Agent 只收 message（不含父完整对话历史） |
+
+---
+
+## 6. 裁剪声明（诚实）
+
+- **不做**：可视化编排、并行 fan-out、Agent 自由对话、跨租户协作
+- **二期候选**：协作白名单（agent_links）、并行调用、子 Agent 结果结构化（JSON schema）
+- **依赖**：现有 Tool Loop（agent-runner）——若工具处理器扩展与沙盒冲突需回归沙盒测试
+
+---
+
+## 7. 验收标准
+
+1. `call_agent` 工具在 Agent 工具列表中可选
+2. A 调 B：A 的回复整合了 B 的结果（文本可见）
+3. B 有自己的 system_prompt/知识库生效（专业化）
+4. 深度循环（A→B→A）被拦截（深度错误）
+5. 异租户/非 ai 目标被拒绝
+6. agent_logs 有父子两条记录（可审计）
+7. services.test.ts + agent-browser 实测通过
+
+## 8. 里程碑
+
+| 阶段 | 内容 | 预计 |
+|---|---|---|
+| M1 | 工具定义 + 执行器（TDD） | 1 天 |
+| M2 | 前端暴露 + 浏览器验收 | 0.5 天 |
+| M3 | 安全/配额/超时补强 | 0.5 天 |
+| M4 | 测试 + 回归 | 0.5 天 |

package/dist/level6/apps/agent-platform/docs/archive/MULTI-ROLE-PLAN.md

@@ -0,0 +1,185 @@
+# agent-platform 多角色审视与优化计划（2026-12）
+
+> ## ✅ 已归档（2026-12）——Wave 6-9 全部完成
+>
+> 执行记录：Wave 6（模板市场/导出/空态/移动适配）→ Wave 7（IA 重构/日志/指标/备份）→
+> Wave 8（骨架屏/深色）→ Wave 9（审计/配额/留存/版本）→ 框架修复（query 丢失 +
+> next(req,ctx)）→ 发布 v0.81.4/0.81.5。8 角色交付全部落地，多 Agent 协作见
+> `MULTI-AGENT-PLAN.md`（活跃计划）。
+>
+> 保留本文档作为决策与交付记录（git 历史可追溯）。
+
+> 从 **老板 / 用户 / 产品经理 / 运营经理 / 视觉设计师 / 计划设计师 / 前端开发者 / 后端开发者**
+> 八个角色视角审视现有功能，输出差异化优化计划（P0 阻断 → P1 高价值 → P2 打磨）。
+
+## 0. 现有功能地图（审视基线）
+
+```
+认证      登录 / 注册（限流）/ 个人设置
+多租户    公司 / 部门 / 成员管理（tenantId 隔离）
+Agent     ai / user / webhook / knowledge_base 四类 + 内置工具 + 角色模板 + 技能（热重载）
+对话      流式 AI + HITL 审批 + 工具卡片 + 消息搜索/编辑/撤回 + Markdown + token 用量 + 重试 + WS 断连提示
+知识库    embedding + pgvector 检索 / 上传 / 重索引
+沙盒      Docker 容器池（心跳/池上限/LRU/网络隔离）+ 工作空间文件浏览器
+Webhook  收发 + 签名验证 + 重试 + 日志
+统计      Dashboard（Agent/消息/漏斗）+ token 成本 + Agent 日志 + 激活漏斗埋点
+```
+
+---
+
+## 1. 老板视角（商业价值 / 成本 / 增长）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 成本 | token 用量统计 | 只展示、无预算/预警 | **P1 成本控制**：agent 级 token 配额/预算 + 超限告警（webhook/通知） |
+| 增长 | 激活漏斗（注册→建Agent→发消息） | 漏斗止于"发消息"，无留存/活跃 | **P1 业务大盘**：DAU/留存/活跃 Agent 数/会话数趋势 |
+| 收入 | 无计费 | 多租户 SaaS 无变现能力 | **P2 计费**：套餐/用量计量/配额（先做配额后做账单） |
+| 竞争 | 平台定位 | 无差异化卖点呈现 | **P2 案例/模板**：成功案例页、一键模板（复用 role-templates） |
+
+**一句话**：先补"成本可控 + 增长可看"，再做"计费变现"。
+
+---
+
+## 2. 用户视角（好用 / 快 / 不出错 / 隐私）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 对话体验 | 流式 + Markdown + 工具卡片 | 长回复定位困难；无对话导出 | **P1 对话导出**（Markdown/文本）+ **回复内锚点/标题目录**（Markdown 长文导航） |
+| 移动端 | 桌面布局 | 14 页 SPA 未适配移动 | **P1 响应式**：关键页（Chat/Approvals）移动优先 |
+| 隐私 | 租户隔离 | 无"对话数据可见性"说明 | **P2 隐私页**：数据存储/隔离/沙盒边界透明化（信任建设） |
+| 操作效率 | 快捷键（Ctrl+Enter 发送） | 无全局快捷入口 | **P2 快捷键**：⌘K 快速跳转（Agent/部门）、Esc 关闭弹层统一 |
+| 容错 | 重试 + 断连提示 | 重试后上下文可能丢失 | **P1 重试保上下文**：重试携带完整历史（验证当前实现） |
+
+**一句话**：对话导出 + 移动适配是用户最直接的获得感。
+
+---
+
+## 3. 产品经理视角（功能完整性 / 用户旅程）
+
+| 旅程阶段 | 现状 | 缺口 | 优化（优先级） |
+|---|---|---|---|
+| 发现 | role-templates 列表 | 无模板市场/筛选/预览沉浸 | **P1 模板市场页**：分类 + 预览（agent/:id/preview 已有 API） |
+| 创建 | NewAgent 表单 | 创建后无引导（知识库/技能/工作空间） | **P1 新手引导**：AgentDetail 空态引导（"先加知识库/再对话"） |
+| 调试 | AgentDetail 编辑 | 无 Prompt 调试台（改系统提示→立即试） | **P2 调试工作台**：右侧系统提示编辑 + 内嵌对话试跑 |
+| 使用 | Chat | 无多 Agent 协作/编排 | **P2 多 Agent**：Agent A 调 Agent B（工具化调用） |
+| 维护 | 无版本 | 系统提示改动不可回滚 | **P2 版本管理**：Agent 配置快照/发布/回滚 |
+| 分析 | token 日志 | 无对话质量评估 | **P2 满意度**：回复点赞/点踩 + 反馈入库 |
+
+**一句话**：模板市场 + 新手引导是激活率关键；版本管理是多租户生产化的必需。
+
+---
+
+## 4. 运营经理视角（增长 / 留存 / 内容 / 数据）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 激活 | 漏斗埋点 | 只记录事件，无运营干预点 | **P1 流失挽回**：漏斗断点触发（建Agent 未完成 → 引导页/提醒） |
+| 留存 | 无 | 无法识别活跃 vs 沉默租户 | **P1 留存报表**：按租户/时段活跃度 + 沉默预警 |
+| 质量 | 无 | 不知道 AI 回复好不好 | **P2 会话质量**：满意度投票 + 失败率/重试率报表 |
+| 内容 | 无公告 | 无法触达用户 | **P2 公告/帮助中心**：运营公告 + 新手引导文档页 |
+| 看板 | Dashboard 基础 | 指标碎片化 | **P2 运营看板**：转化/活跃/质量/成本四维一屏 |
+
+**一句话**：漏斗断点干预 + 留存报表是运营的"方向盘"。
+
+---
+
+## 5. 视觉设计师视角（一致性 / 动效 / 无障碍 / 品牌）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 一致性 | weifuwu 设计系统 | 部分页混用裸 div/emoji | **P1 视觉审计**：全页面组件化替换（图标/间距/语义色对齐设计系统） |
+| 空/错态 | EmptyState 组件 | 各页空态文案/图示不统一 | **P1 空态设计**：统一"图示 + 说明 + 行动按钮"三要素 |
+| 加载 | 无骨架 | 列表/详情页白屏等待 | **P1 骨架屏**：Dashboard/Agents/Chat 列表骨架 |
+| 深色模式 | 无（Settings 无主题） | 设计系统支持但平台未启用 | **P2 深色模式**：全局主题切换（继承 weifuwu ThemeSwitch） |
+| 无障碍 | 组件级支持 | 页面级未系统验证 | **P2 无障碍审计**：键盘可达/焦点环/aria（对照 §8 键盘红线） |
+| 品牌 | 默认 | 无平台品牌定制 | **P2 品牌化**：logo/色板/登录页视觉 |
+
+**一句话**：骨架屏 + 空态统一是"质感"第一步；深色模式是设计系统的自然延伸。
+
+---
+
+## 6. 计划设计师视角（信息架构 / 任务流 / 效率）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 信息架构 | 侧边栏 14 页平铺 | 层级扁平，Agent 相关散落 | **P1 IA 重构**：侧边栏分组（工作台/管理/设置）+ AgentDetail 内 Tab（配置/对话/知识库/日志/工作空间） |
+| 任务流 | 建 Agent 表单 | 创建→配置→测试多步跳转 | **P1 建 Agent 流程**：分步向导（基础→能力→试跑→完成）而非单页表单 |
+| 上下文 | AgentDetail 跳 Chat | 跳转丢失 Agent 上下文 | **P1 上下文保持**：Chat 支持"以某 Agent 身份"入口直达，免二次选择 |
+| 效率 | 审批页独立 | 审批与对话分离 | **P2 审批嵌入**：Chat 内直接审批（当前跳转 Approvals） |
+| 引导 | 无 | 新用户不知从哪开始 | **P1 首页引导**：Dashboard 空态 → "创建第一个 Agent" 显式 CTA |
+
+**一句话**：IA 分组 + 建 Agent 向导直接降低上手门槛。
+
+---
+
+## 7. 前端开发者视角（性能 / 质量 / 可维护 / 测试）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 性能 | 流式渲染 | 大对话列表无虚拟化；知识库大文档渲染卡 | **P1 虚拟列表**：Chat 历史/日志列表虚拟化 |
+| 构建 | 单 bundle | 14 页单入口体积大 | **P2 代码分割**：按路由懒加载 |
+| 类型 | Wave 5 类型化 | 页面状态已类型化 | **P1 补强**：API 响应类型（api.ts 泛型）与实体对齐 |
+| 测试 | 组件测试（框架层） | 平台页面无测试 | **P1 页面测试**：关键页（Login/NewAgent/Chat 审批）DOM 级测试（仿 Editor.dom.test 模式） |
+| 错误处理 | 部分 catch | 无全局错误边界 | **P2 错误边界**：页面级 ErrorBoundary + 友好降级 |
+| 状态管理 | 页面内 $ 对象 | 跨页共享状态（当前租户/主题）重复获取 | **P2 共享状态**：createStore + useExternal 收敛（当前用户/租户） |
+
+**一句话**：虚拟列表 + 页面测试是"稳"的根基；懒加载是"快"的保障。
+
+---
+
+## 8. 后端开发者视角（可靠性 / 安全 / 可扩展 / 可观测）
+
+| 关注点 | 现状 | 问题 | 优化（优先级） |
+|---|---|---|---|
+| 可观测 | 无结构化日志 | 问题排查靠 console | **P1 结构化日志**：请求/AI 调用/沙盒/webhook 关键链路结构化日志 + 请求 id 贯穿 |
+| 监控 | 无指标 | 无错误率/延迟/资源水位 | **P1 指标端点**：/metrics（请求数/错误率/AI 延迟/token/沙盒容器数） |
+| 备份 | 无 | 数据库无备份策略 | **P1 备份**：pg_dump 脚本 + 恢复演练文档 |
+| 安全 | 沙盒隔离/签名/限流 | 密钥硬编码风险（.env） | **P2 密钥管理**：生产密钥注入（环境/密钥服务） |
+| 扩展 | 单实例 | WS 依赖 Redis（已支持）但 AI 调用串行风险 | **P2 水平扩展**：会话亲和 + AI 调用并发限流 |
+| 审计 | agent_logs | 无管理端操作审计 | **P2 审计日志**：登录/Agent 变更/审批操作记录 |
+| 压测 | 无 | 沙盒/AI 并发上限未知 | **P2 压测**：对话/沙盒并发基准（工具：自研 bench 脚本） |
+
+**一句话**：结构化日志 + 指标是"可运维"的门槛；备份是"敢上线"的前提。
+
+---
+
+## 9. 优先级总览与落地路线
+
+| 优先级 | 主题 | 角色共识 | 落地批次 |
+|---|---|---|---|
+| **P0** | 无（现有功能无阻断性缺陷——OPTIMIZE-PLAN 已清） | — | — |
+| **P1-A** | 对话导出 + 虚拟列表 + 移动适配 | 用户/前端 | Wave 6 |
+| **P1-B** | 模板市场 + 新手引导 + 建 Agent 向导 | 产品/计划 | Wave 6 |
+| **P1-C** | IA 重构（侧边栏分组 + AgentDetail Tab） | 计划/视觉 | Wave 7 |
+| **P1-D** | 结构化日志 + 指标 + 备份 | 后端 | Wave 7 |
+| **P1-E** | 骨架屏 + 空态统一 + 页面测试 | 视觉/前端 | Wave 8 |
+| **P2** | 计费/留存报表/深色模式/多 Agent/版本管理/压测/审计 | 全员 | Wave 9+ |
+
+**Wave 6 完成 ✅（2026-12）**：
+1. ✅ 对话导出（Chat.tsx exportChat——Markdown 复制 + toast）
+2. ✅ 模板市场页（Templates.tsx——分类/热门/一键创建→Agent 详情）
+3. ✅ 建 Agent 空态引导（Agents.tsx 双 CTA：从模板开始/自定义）
+4. ✅ 移动适配（Chat header 部门详情小屏隐藏）
+5. 🚧 虚拟列表 Chat 历史——**裁剪**：消息不定高 + 工具卡片/审批/编辑复杂交互，虚拟化收益低风险高（登记）
+
+**Wave 6 发现并规避的框架级问题**（应后续在框架层根治）：
+- **路由页面组件（AppLayout 内）的 rerender（ctx.ui.render / store.set→useExternal）不落地 DOM**
+  ——Templates 首次用「工厂异步 rerender」多次失败（store.state 已更新但渲染空）；
+  改用 **§3.3 工厂层 await 数据**（首次渲染即带数据）绕过。Agents 页侥幸未暴露
+  （/api/agents 响应快于首次渲染）。**建议框架层排查 renderOne 对路由页面组件的 patch**。
+
+**验证标准**：每项按框架纪律——真实浏览器验收（agent-browser）+ DOM 级测试（仿 Editor.dom.test 模式）+ 全量回归。
+
+---
+
+## 10. 多 Agent 协作（P2 专项）
+
+详见 `MULTI-AGENT-PLAN.md`——Agent 作为工具（call_agent）：TDD 实现、
+深度限制防环、租户隔离、父子审计。不做可视化编排/并行 fan-out。
+
+## 10. 裁剪声明（诚实——不做）
+
+- **AI 自研引擎重写**：当前 deepseek/dashscope 直连可用，重写收益低风险高——裁剪
+- **多租户计费全流程**：先配额后账单，避免过早金融化复杂度
+- **Agent 可视化编排**（拖拽 DAG）：需求未验证，先用"多 Agent 工具化调用"探路
+- **移动端 App**：先响应式 Web，原生壳后续按需

package/dist/level6/apps/agent-platform/docs/archive/OPTIMIZE-PLAN.md

@@ -0,0 +1,50 @@
+# 前端交互界面优化计划
+
+## 全部完成 ✅
+
+### Phase 1 — 阻断性问题修复
+- [x] 超时 15 秒 → 60 秒 (deepseek.ts)
+- [x] 捕获 `reasoning_content` 并传递到后续请求 (types.ts + deepseek.ts + agent.ts)
+- [x] 事件系统重构：ai:status / ai:token / ai:tool，完整映射状态机
+- [x] ai:done 过早发送修复：streamAgent 完成后再发 complete
+
+### Phase 2 — 流式动画与状态视觉
+- [x] **Thinking 动画**：跳动 dots（三个点依次上跳回落）
+- [x] **生成闪烁光标**：`span.cursor-blink` 步进闪烁
+- [x] **工具调用卡片**：running 时 pulse-ring 动画，done 显示 ✅
+- [x] **气泡活跃/错误样式**：primary 边框发光，error 红色背景
+
+### Phase 3 — 交互细节
+- [x] **自动聚焦输入框**：onMount + 发送后 refocus
+- [x] **平滑滚动**：CSS smooth + 用户滚动检测（< 80px 视为在底部）
+- [x] **Token 用量标签**：badge-gray 圆角标签
+- [x] **相对时间自动刷新**：timeVersion 每 30s 刷新
+
+### Phase 4 — 错误与重试
+- [x] **错误重试**：AI 回复失败时显示 🔄 重新生成按钮
+- [x] **断连提示**：WS 断开时顶部黄色横幅
+- [x] **发送失败保护**：保留输入内容 + alert 提示
+
+## 实测数据（12 次对话，全部成功）
+
+| 场景 | 状态 |
+|------|------|
+| 纯文本回复 | ✅ 391 chars |
+| 工具调用 + 文本（list_files） | ✅ 441 chars |
+| 工具调用 + 文本（get-current-time） | ✅ 41 chars x 6 |
+| token 用量写入 agent_logs | ✅ φ |
+| 流式超时保护 60s | ✅ |
+
+## 后续建议
+
+- ~~拆分 Chat.tsx~~（已函数化清晰——拆分收益低风险高，裁剪）
+- ~~键盘快捷键~~（已实现：ChatInput 组件级 Ctrl/Cmd+Enter 强制发送；聊天编辑态 Esc 取消编辑——Input 组件透传 onKeyDown 修复，2026-12）
+- ~~多轮对话上下文可视化~~（已实现：每轮消息工具卡片常驻 + 点击展开参数/结果全文，2026-12）
+- ~~消息搜索/过滤~~（已实现：搜索框 + 前滚分页 + @ 补全）
+
+## Wave 5（产品化收尾，2026-12）
+
+- [x] **页面状态类型化**：15 页面 `Record<string, any>` → 类型化状态接口（`ui/lib/types.ts` 共享实体类型）——tsc 编译期暴露 6 处潜在空值/字段错（Agents token_usage、Companies created_at、NewChat member_count、DepartmentDetail Member.id 字段、NewAgent Slider 类型、Chat Ava name）——全部修复
+- [x] **激活漏斗埋点**：events 表（部分唯一索引 first_message 去重）+ POST /api/track（鉴权 + 白名单）+ GET /api/stats/funnel（本租户进度 + 全平台转化）+ 前端 track 工具（Bearer token）+ 注册/建 Agent/发消息埋点 + Dashboard 漏斗卡片
+  - 实测：新注册用户 register_complete 入库 → Dashboard 显示「注册 ✓ / 建 Agent 未完成」；first_message 重复 track 幂等
+  - 踩坑：track 裸 fetch 无 token → protectedRoutes 401 静默失败（已修——localStorage 读 token 带 Bearer）

package/dist/level6/apps/agent-platform/docs/archive/PLAN.md

@@ -0,0 +1,215 @@
+# agent-platform 计划
+
+多租户 AI Agent 平台。自实现 AI 模块（DeepSeek LLM + DashScope Embedding），无第三方 AI 依赖。
+
+---
+
+## 1. 定位
+
+属于 `weifuwu` 框架的用户空间应用。遵循 AGENTS.md 的原则：
+
+> "Domain modules (user system, AI, messaging, knowledge base) are not bundled—they live in user space."
+
+框架本身不做任何改动——`src/` 不动，`package.json` 不动。所有代码在 `apps/agent-platform/` 内自包含。
+
+---
+
+## 2. 依赖
+
+| 类型 | 依赖 | 用途 |
+|------|------|------|
+| 框架 | `weifuwu` | 父项目，通过 tsconfig paths 引用 |
+| 运行时 | 无 | AI 能力全部自实现，HTTP 调用用原生 `fetch` |
+
+**不依赖 `ai` / `@ai-sdk/*`。** 两个供应商只走标准 HTTP REST：
+
+```
+DeepSeek  → POST {baseUrl}/chat/completions
+DashScope → POST {baseUrl}/embeddings
+```
+
+---
+
+## 3. 目录结构
+
+```
+apps/agent-platform/
+├── server.ts                    # 应用入口 + 路由注册（含 /api/stats）
+├── tsconfig.json                # paths 引用父项目 src/
+├── PLAN.md                      # 本文件
+│
+├── src/
+│   ├── ai/                      # AI 核心模块（自实现）
+│   │   ├── types.ts             # 所有类型定义
+│   │   ├── deepseek.ts          # DeepSeek Chat Completions 客户端
+│   │   ├── dashscope.ts         # DashScope Embedding 客户端
+│   │   ├── stream.ts            # SSE 流解析器
+│   │   └── agent.ts             # Tool Loop 引擎 + 全局工具注册表
+│   │
+│   ├── middleware/
+│   │   ├── ai.ts                # ctx.ai 注入（核心中间件）
+│   │   ├── auth.ts              # JWT 认证 + 租户隔离
+│   │   └── tenant.ts            # 从 token 提取 tenant_id
+│   │
+│   ├── db/
+│   │   └── schema.sql           # 完整 DDL（含 agent_logs, webhook_logs）
+│   │
+│   ├── routes/
+│   │   ├── auth.ts              # 登录/注册（scrypt 哈希 + 限流）
+│   │   ├── agents.ts            # CRUD agent（4 种类型 + 内置工具列表 + token 用量统计）
+│   │   ├── departments.ts       # CRUD 部门 + 成员管理
+│   │   ├── messages.ts          # 发送/获取/编辑/撤回/审批
+│   │   ├── companies.ts         # CRUD 公司
+│   │   └── knowledge.ts         # 知识库上传/检索
+│   │
+│   └── services/
+│       ├── agent-runner.ts      # Agent 执行编排（token 统计 + 上下文截断 + 日志记录）
+│       ├── chat.ts              # 消息路由 + AI 自动回复 + HITL 审批推送
+│       ├── webhook.ts           # Webhook 消息收发（签名验证 + 重试 + 日志）
+│       ├── embedding.ts         # 文档分块 + 向量化 + pgvector 检索
+│       ├── password.ts          # scrypt 密码哈希
+│       ├── rate-limit.ts        # 内存滑动窗口限流
+│       └── ws-hub.ts            # WebSocket 房间管理 + Redis Pub/Sub
+│
+├── ui/
+│   ├── main.tsx                 # 前端入口（router + auth + ws）
+│   ├── lib/api.ts               # 自动 token 刷新
+│   ├── components/
+│   │   ├── AppLayout.tsx        # 侧边栏布局 + 认证守卫
+│   │   └── ui.tsx               # PageHeader / TypeBadge / Ava / EmptyState / Loading
+│   ├── pages/
+│   │   ├── Login.tsx
+│   │   ├── Register.tsx
+│   │   ├── Dashboard.tsx        # 多维度统计（agent/消息/token/趋势）
+│   │   ├── Agents.tsx           # 列表 + 模型/用量显示
+│   │   ├── NewAgent.tsx         # 四种类型创建（含 AI 模型/温度/HITL/Token 配置）
+│   │   ├── AgentDetail.tsx      # 完整编辑（AI 配置 + 工具勾选 + 执行历史/Webhook 日志/知识库 QA）
+│   │   ├── Companies.tsx
+│   │   ├── NewCompany.tsx
+│   │   ├── Departments.tsx
+│   │   ├── DepartmentDetail.tsx
+│   │   ├── NewDepartment.tsx
+│   │   ├── NewChat.tsx
+│   │   ├── Chat.tsx             # 消息气泡 + 编辑/撤回 + HITL 审批
+│   │   └── Settings.tsx
+│
+├── test/
+│   ├── ai.test.ts               # AI 核心模块（17 tests）
+│   ├── middleware.test.ts        # 中间件链（17 tests）
+│   ├── services.test.ts         # 服务层（依赖 DB）
+│   └── routes.test.ts           # 路由端点（依赖 DB）
+│
+├── scripts/
+│   └── build.mjs                # esbuild 构建
+│
+├── seed.ts                      # 演示数据初始化
+├── public/
+│   └── index.html
+└── .env.example
+```
+
+---
+
+## 4. 环境变量
+
+```env
+# === 数据库 ===
+DATABASE_URL=postgres://root:123456@localhost:5432/demo
+# REDIS_URL=redis://localhost:6377
+
+# === DeepSeek LLM ===
+DEEPSEEK_API_KEY=sk-xxx                                  # 必需
+DEEPSEEK_BASE_URL=https://api.deepseek.com/v1             # 默认
+DEEPSEEK_MODEL=deepseek-v4-flash                              # 默认
+
+# === DashScope Embedding ===
+DASHSCOPE_API_KEY=sk-xxx                                  # 必需
+DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1  # 默认
+DASHSCOPE_EMBEDDING_MODEL=text-embedding-v4               # 默认
+
+# === JWT ===
+JWT_SECRET=change-this-to-a-random-secret-in-production
+
+# === 模式 ===
+# NODE_ENV=production
+```
+
+---
+
+## 5. Agent 四种类型的实现状态
+
+| 类型 | 后端 | 前端 | 完成度 |
+|------|------|------|--------|
+| **AI Robot** (`ai`) | Tool Loop / Stream / HITL / Token 统计 / 上下文截断 / 执行日志 | 模型选择 / 温度滑块 / max_tokens / HITL 开关 / 工具勾选 / 执行历史面板 | **95%** |
+| **Real User** (`user`) | 注册自动创建 / 消息发送 / 编辑 / 撤回 | 详情显示绑定用户 | **100%** |
+| **Webhook Bot** (`webhook`) | HMAC-SHA256 签名验证 / 指数退避重试 / 调用日志 | URL / Secret / 重试次数配置 + 测试 + 请求日志面板 | **95%** |
+| **Knowledge Base** (`knowledge_base`) | 文档分块 / DashScope Embedding / pgvector 检索 | 文档列表 / 上传 / 删除 / QA 检索测试 | **85%** |
+
+---
+
+## 6. 待办项
+
+### P0 — 当前已实现
+
+- [x] AI Robot: 模型选择 / 温度 / max_tokens / HITL 配置
+- [x] AI Robot: 工具勾选（从内置工具列表选择）
+- [x] AI Robot: 执行历史面板（次数 / token 统计）
+- [x] AI Robot: token 用量统计 + 上下文截断
+- [x] Webhook: Secret / 重试次数配置
+- [x] Webhook: 签名验证（HMAC-SHA256）+ 指数退避重试
+- [x] Webhook: 请求日志记录与展示
+- [x] Dashboard: 按类型 agent 统计 / 消息数 / token 消耗 / 趋势
+- [x] Agent 列表: 显示模型名 / token 用量
+
+### P1 — 当前已实现
+
+- [x] KB: 文件上传（拖拽 + 文件选择 .txt/.md/.csv/.json）
+- [x] KB: 文档展开预览（content + chunks）
+- [x] KB: 批量上传（批量 JSON 粘贴 + 多文件选择）
+- [x] KB: QA 检索测试面板
+
+### P2 — 后续改进
+
+- [x] Agent: 类型特定字段校验（webhook 必填 URL 已由 H5 裁剪为入站无需 URL；KB 空 system_prompt 已支持；user 必须绑定账号校验已有）
+- [x] Agent: 统计面板（按类型已有；活跃度新增——/api/stats active_agents 近 7 天消息排行 + Dashboard「本周活跃 Agent」卡片，2026-12）
+- [x] 统一前端 toast 错误提示（ctx.toast 全页面统一入口——8 页面均已使用）
+
+### P2 — 长期规划
+
+- [ ] Agent 版本管理（prompt 历史）
+- [ ] Agent 模板市场
+- [ ] 自定义工具注册 UI
+- [ ] 多模型供应商切换
+- [ ] Agent 对话导出
+
+---
+
+## 7. Human-in-the-Loop
+
+```
+用户发消息 → 部门
+  ├→ AI Agent 收到（WS push）
+  │   ├→ 自动回复（humanInTheLoop=false）
+  │   └→ 生成 draft + onStepEnd 等待审批（humanInTheLoop=true）
+  │       └→ 管理员确认后发出
+```
+
+`onStepEnd` 中通过 Promise 阻塞实现等待：
+
+```ts
+agent.run(messages, ctx)  // 内部在 onStepEnd 中 await approval
+  ↑                       // 直到外部调用 resolve()
+  └── 审批弹出 ← WS通知管理员 ← 确认 → resolve()
+```
+
+---
+
+## 8. 测试覆盖
+
+| 测试文件 | 测试数 | 覆盖 |
+|----------|--------|------|
+| `test/01-auth.test.ts` | 9 | 注册/登录/me/限流/错误处理 |
+| `test/ai.test.ts` | 17 | SSE / DeepSeek / DashScope / Agent Tool Loop |
+| `test/middleware.test.ts` | 17 | auth / tenant / ai / 链式调用 |
+| `test/services.test.ts` | 16 | agent-runner / chat / webhook / embedding (真实DB) |
+| **总计** | **59** | **全通过（`node --env-file=.env --test --test-concurrency=1 'test/**/*.test.ts'`）** |

package/dist/level6/apps/agent-platform/docs/archive/PM-OPTIMIZE-PLAN.md

@@ -0,0 +1,44 @@
+# PM 优化计划（2026-12）——PM 审视发现缺口
+
+> ## ✅ 已归档（2026-12）——M1-M4 全部实施（提交 `23c39cd5`）
+>
+> 导出文件化（copyText + .md 下载）/ KB 批量上传 / 管理员删任意消息 /
+> Dashboard SVG 折线 / Webhook 出站回调镜像（双向管道闭环）。
+> 浏览器实测出站镜像 + 单测补强（92 全绿）。
+
+> 来源：PM 全流程审视报告（4 类 Agent/15 页/全闭环实测）。
+> 满足度 ~90%，剩余缺口按价值/成本排序实施。
+
+## 缺口 → 计划（按实施顺序）
+
+| # | 缺口 | 优先级 | 方案 | 成本 |
+|---|---|---|---|---|
+| 1 | **对话导出文件化**（当前仅 copyText 剪贴板） | P2 | Chat 导出生成 `.md` 文件下载（Blob）——「导出」按钮升级：复制 + 下载文件 | 小 |
+| 2 | **KB 文档批量上传** | P3 | 上传 input 加 `multiple`——一次选多文件逐个上传 | 小 |
+| 3 | **对话消息管理**（管理员删除任意消息） | P1 | messages 路由：DELETE 权限升级（sender 自己 + 管理员）；UI 消息 hover 显示删除 | 中 |
+| 4 | **Dashboard 可视化**（CSS 柱条 → SVG 图表） | P2 | 自绘 SVG 折线/柱状（零依赖——趋势 + 留存 + 排行） | 中 |
+| 5 | **Webhook 出站回调** | P1 | Agent 加 `webhook_url`（出站端点）+ `post_webhook` 工具（AI 主动推送）；入站应答可配置镜像到出站 | 大 |
+
+## 验收标准
+
+1. Chat「导出」出 .md 文件（含角色/时间/内容）——浏览器下载
+2. KB 上传支持多文件选择
+3. 管理员可删除任意消息；普通用户只能删自己的
+4. Dashboard 趋势/留存 SVG 渲染（无 CSS hack）
+5. Webhook Agent 配置出站 URL → AI 用 post_webhook 推送 → 外部端点收到带签名请求
+
+## 裁剪声明
+
+- Webhook 出站：一期「AI 主动推送」+「入站应答镜像」；不做出站签名强制（URL 私有即可）；
+  推送重试 3 次指数退避（复用入站逻辑）
+- 可视化：自绘 SVG（框架无 Chart 依赖——不引入 npm 包，FS-05）
+- 消息管理：不做撤回他人消息（保留撤回=自己）+ 删除=管理员/自己
+
+## 里程碑
+
+| 阶段 | 内容 |
+|---|---|
+| M1 | 导出文件化 + KB 批量上传（快赢） |
+| M2 | 消息管理（API + UI） |
+| M3 | Dashboard 可视化（SVG） |
+| M4 | Webhook 出站回调（设计 + post_webhook 工具 + 测试） |