diff --git a/docs/design/topic7-interaction-dashboard-proposal.md b/docs/design/topic7-interaction-dashboard-proposal.md new file mode 100644 index 0000000..bb36791 --- /dev/null +++ b/docs/design/topic7-interaction-dashboard-proposal.md @@ -0,0 +1,425 @@ +# 课题7+9:AI Native 人机交互 + Dashboard 设计方案 + +**版本**: v1.0 +**作者**: 庞统(副军师)🐦 +**日期**: 2026-05-15 +**评审**: 待司马懿评审 +**状态**: 待评审 + +--- + +## Part A:AI Native 人机交互(课题7) + +### 1. 设计目标 + +定义 moziplus 中人与 AI Agent 的交互范式——不是给 AI 团队做 ERP 界面,而是让 AI 主动、精准、不扰民地和用户协作。 + +### 2. 核心洞察 + +> **传统模式**:用户主动查 Dashboard、主动问进度、主动分配任务。 +> **AI Native 模式**:AI 主动推送关键信息,用户只在需要决策时轻触确认。 + +参考六种 AI Native 交互范式(调研报告 §3.2): + +| # | 范式 | 代表 | moziplus 适用度 | +|---|------|------|----------------| +| 1 | REPL 对话 | Claude Code CLI | ⭐⭐⭐ WebChat 已有 | +| 2 | Canvas/Artifacts | ChatGPT Canvas | ⭐⭐⭐⭐ 产出物交互 | +| 3 | 沉浸式观察 | Devin | ⭐⭐⭐ 长任务监控 | +| 4 | Command Palette | Raycast | ⭐⭐⭐⭐ 快捷操作 | +| 5 | Contextual Inline | Cursor | ⭐⭐ 不适用(非IDE) | +| 6 | Event-Driven Notification | Linear | ⭐⭐⭐⭐⭐ 核心模式 | + +**结论**:moziplus 的核心交互范式是 **Event-Driven Notification + 轻触确认**,辅助以 WebChat 深度对话和 Dashboard 全局观察。 + +### 3. 设计决策 + +#### D7-1:四种交互模式 + +| 模式 | 触发方式 | 用户注意力 | AI 主动性 | 适用场景 | +|------|---------|-----------|----------|---------| +| **沉浸观察** (Dashboard) | 用户主动打开 | 高 | 低 | 全局监控、任务详情 | +| **轻触确认** (Approval) | AI 主动推送 | 中 | 高 | 方案审批、风控告警 | +| **即时对话** (WebChat) | 双向触发 | 中高 | 中 | 复杂指令、探索性需求 | +| **被动通知** (Notify) | AI 主动推送 | 低 | 高 | 任务完成、阶段转换 | + +> **参考实践**: +> - **Cursor**:4 种交互粒度(Tab/Cmd+K/Cmd+L/Cmd+I),从被动到主动覆盖所有场景 +> - **Devin**:沉浸式观察,用户只在关键节点介入 +> - **Linear**:精准通知,不噪音 + +#### D7-2:推送级别分级 + +| 推送级别 | 示例 | 默认行为 | 用户可配置 | +|---------|------|---------|----------| +| 🔴 **必须确认** | 方案审批、风控告警、预算超限 | 始终推送 + 阻塞等待 | ✗ 不可关闭 | +| 🟡 **重要进展** | 任务完成、阶段转换、产出交付 | 默认推送 | 可降级为摘要 | +| 🟢 **一般信息** | Agent 启动、中间步骤、心跳正常 | 默认不推送 | 可开启 | +| 🔵 **定时摘要** | 每日工作汇总、Token 消耗报告 | 默认开启 | 频率可调 | + +**推送频率控制**: +- 任务执行中:每 5 分钟一次进展摘要(不是每步都推) +- 任务完成/阻塞/异常:立即推送 +- 正常心跳:不推送,只在 Dashboard 上更新 + +> **参考实践**: +> - **Linear**:关键变更推送 + 精准通知,不噪音 +> - **课题4 D4-5**:审批式/通知式/中断式三种确认模式,按 risk_level 动态决定 + +#### D7-3:推送渠道 + +| 渠道 | 推送级别 | 交互深度 | 延迟 | +|------|---------|---------|------| +| **WebChat** | 🔴🟡 | 深(可对话) | 实时 | +| **Dashboard 通知** | 🟡🟢 | 浅(点击查看) | 实时 | +| **Signal/Telegram** | 🟡🔵 | 极浅(只读) | 实时 | +| **邮件** | 🔵 | 极浅(只读) | 批量 | + +**当前落地**:WebChat(主) + Signal(辅)。Dashboard 通知随 M2 前端一起上线。 + +#### D7-4:用户决策点设计 + +用户不是全程驾驶,而是在关键节点参与: + +``` +用户参与密度: +Phase 1 需求探索 ──── 高(苏格拉底对话) +Phase 2 动态规划 ──── 中(方案确认,可跳过 simple 任务) +Phase 3 自主执行 ──── 低(只收通知,不干预) +Phase 4 验收汇报 ──── 中(审查产出,确认交付) +``` + +**具体决策点**: + +| 决策点 | 触发条件 | 交互模式 | 超时兜底 | +|--------|---------|---------|---------| +| 需求确认 | 庞统完成需求结构化后 | 即时对话 | 30min 后提醒 | +| 方案审批 | complex 任务规划完成后 | 轻触确认 | 1h 后庞统自行判断(risk_level=high 除外) | +| 风控告警 | 关羽触发风控规则 | 必须确认 | 阻塞直到用户回应 | +| 产出验收 | 任务全部完成后 | 沉浸观察 | 24h 自动确认(risk_level=low) | +| 异常升级 | Agent 无法自主解决 | 即时对话 | 不超时(等用户) | + +> **参考实践**: +> - **v2.0 PRD**:人的参与密度从高到低 +> - **GSD discuss phase**:必须确认步骤 +> - **课题4 D4-5**:三种确认模式 + +#### D7-5:Agent 主动汇报规范 + +Agent 不是沉默执行器——在关键节点主动向用户汇报: + +| 汇报时机 | 谁汇报 | 内容 | 渠道 | +|---------|--------|------|------| +| 任务开始 | 庞统 | "已创建任务 T-006,5个节点,预估30分钟" | WebChat | +| 阶段转换 | 庞统 | "T-006 编码完成,进入审查阶段" | 通知 | +| 遇到阻塞 | 执行者 | "发现 XXX 问题,建议 YYY 方案" | 即时对话 | +| 任务完成 | 庞统 | "T-006 完成!年化收益15.3%,最大回撤8.2%" | WebChat + 通知 | +| 定时摘要 | 庞统 | "今日完成 3 个任务,Token 消耗 ¥12.5" | 通知/邮件 | + +**汇报格式**(简洁、可操作): +``` +✅ T-006 双均线策略 — 完成 + 执行:张飞→司马懿→赵云 + 产出:策略代码 + 回测报告 + 关键指标:年化15.3% / 回撤8.2% / 夏普1.8 + [查看详情] [查看产出] +``` + +#### D7-6:多 Agent 协作可视化 + +用户观察多 Agent 协作过程的三层视图(调研报告 §4.4): + +| 层次 | 展示什么 | 类比 | 用户操作 | +|------|---------|------|---------| +| **全局层** | DAG 拓扑 + 节点状态 | GitHub Actions | 点击节点 | +| **任务层** | 管道进度 + Agent 头像 | Edict MiniPipe | 审批/暂停 | +| **Agent 层** | 当前操作 + 产出物预览 | Devin 工作屏 | 评论/指导 | + +--- + +## Part B:AI Native Dashboard 设计(课题9) + +### 4. 设计目标 + +Dashboard 不是监控面板,是**人 Agent 协作界面**——用户在这里观察、确认、指导 AI 团队的工作。 + +### 5. 设计决策 + +#### D9-1:Dashboard 定位 + +> **参考实践**: +> - **Hermes Kanban**:Dashboard 是协作界面,不是展示墙。Comment Thread 是人 Agent 讨论的最佳实践 +> - **Edict**:看板 + 管道 + 操作按钮 + 皇帝发言 = 完整协作 +> - **Linear**:极简 + 键盘优先,不信息过载 + +**三不做**: +1. ❌ 不做第二个 Grafana(纯监控面板) +2. ❌ 不做第二个 Slack(闲聊频道) +3. ❌ 不做第二个 Jira(重到没人用) + +**定位**:轻量协作界面——展示关键状态 + 快速操作入口 + 深入查看能力。 + +#### D9-2:三层信息架构 + +``` +L1: 一眼看到(顶部栏,永远可见) +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ 全局健康 │ │ 活跃任务 │ │ 待审批 │ │ Token │ +│ 🟢 正常 │ │ 3 │ │ 1 ⚠️ │ │ ¥12.5 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ + +L2: 任务看板(主体区域) +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ T-003 策略回测│ │ T-004 数据采集│ │ T-005 风控 │ +│ ⚙️ 执行中 │ │ 📋 规划中 │ │ ✅ 完成 │ +│ ████░░ 张飞 │ │ ░░░░░░ 赵云 │ │ █████ 赵云 │ +│ 3/5 节点完成 │ │ 等待审批 │ │ 产出已交付 │ +└─────────────┘ └─────────────┘ └─────────────┘ + +L3: 任务详情(点击卡片展开) +- 管道进度:规划→审查→执行→交付 +- 产出物:代码 diff / Markdown / 图表 +- 评论线程:Agent 和用户的讨论 +- 操作历史:所有状态变更记录 +``` + +#### D9-3:页面结构 + +**延续 v1.0 的 Tab 结构**,但大幅精简为 5 个核心页面: + +| 页面 | 展示内容 | 核心交互 | 优先级 | +|------|---------|---------|--------| +| **任务看板** | 活跃任务卡片 + 管道进度 | 审批/暂停/取消、点击查看详情 | P1 | +| **全局监控** | DAG 拓扑 + Agent 状态 + 心跳 | 点击节点/Agent、Token 统计 | P1 | +| **产出档案** | 已完成任务 + 产出物 | 预览/下载/复制 | P2 | +| **系统配置** | 模型/技能/Guardrail 配置 | 编辑/保存 | P2 | +| **AI Briefing** | 今日摘要 + 待处理 + 风险预警 | 一键操作 | P3 | + +**砍掉的 v1.0 页面**(合并或降级): +- "将军总览" → 合并到全局监控的 Agent 状态面板 +- "军议大厅" → 合并到任务详情的评论线程(黑板 comment 已支持) +- "奏折阁" → 合并到产出档案 +- "会话监控" → 合并到全局监控 +- "编排调度" → 合并到任务看板(DAG 拓扑) + +> **理由**:5 个页面覆盖所有场景。v1.0 的 10 Tab 有冗余(编排调度 vs 任务看板、奏折阁 vs 产出档案)。参考 Linear 的极简哲学——少即是多。 + +#### D9-4:任务看板设计 + +**任务卡片**(L2 主体): + +``` +┌─────────────────────────────────────┐ +│ T-006 双均线交叉策略 │ +│ 📋 规划中 ─── 🟡 risk: standard │ +│ │ +│ MiniPipe: █████░░░░░░ 2/5 节点 │ +│ 张飞 🟢 编码中 → 司马懿 ⏳ 等待审查 │ +│ │ +│ 预估 30min | 已用 15min | Token ¥2.3 │ +│ │ +│ [⏸暂停] [📋详情] [💬评论] │ +└─────────────────────────────────────┘ +``` + +**卡片上的操作按钮**(按任务状态动态显示): + +| 状态 | 可用操作 | 说明 | +|------|---------|------| +| pending | 取消、编辑 | 规划前可改 | +| planned | 审批、驳回 | 等用户确认方案 | +| executing | 暂停、查看详情 | 执行中可暂停 | +| reviewing | 查看详情 | 审查中只观察 | +| completed | 查看产出、重新执行 | 完成后可复查 | +| failed | 重试、取消、查看详情 | 失败后可重试 | + +> **参考实践**: +> - **Edict TaskModal**:叫停/恢复/取消统一入口 +> - **Hermes Kanban**:7 状态完整状态机 + 按钮动态显示 +> - **课题3 §9.7**:状态机守卫(ACTION_GUARDS),前端按钮与后端对齐 + +#### D9-5:全局监控设计 + +**DAG 拓扑视图**: + +``` + T-006 双均线策略 + ┌──────┐ ┌──────┐ ┌──────┐ + │ 赵云 │────→│ 张飞 │────→│ 司马懿│ + │ 数据 │ ✅ │ 编码 │ ⚙️ │ 审查 │ ⏳ + └──────┘ └──────┘ └──────┘ + │ + ▼ + ┌──────┐ + │ 关羽 │ + │ 风控 │ ⏳ + └──────┘ +``` + +- 颜色:✅ 完成(绿) / ⚙️ 执行中(蓝动画) / ⏳ 等待(灰) / ❌ 失败(红) +- 点击节点 → 滑出该节点的详情面板 +- 连线 = depends_on 依赖关系 + +**Agent 状态面板**: + +``` +┌────────────────────────────────────┐ +│ 张飞 翼德 🟢 │ +│ 当前: T-006 节点2 编码中 │ +│ 心跳: 30s前 | Session: 45min │ +│ 今日: 完成 2 任务 | Token ¥5.2 │ +└────────────────────────────────────┘ +``` + +> **参考实践**: +> - **GitHub Actions**:DAG 拓扑 + 点击节点看日志 +> - **Hermes Kanban**:心跳可视化 + 僵尸检测 +> - **课题2 §4.5**:续杯与心跳机制 + +#### D9-6:AI Briefing(AI 晨报) + +> **参考实践**: +> - **v2.0 PRD Phase 4**:主动汇报,不等人查 +> - **superpowers**:每次 session 开始时自动 summary + +位置:Dashboard 首页顶部卡片。 + +**内容**(AI 自动生成,不是固定模板): + +``` +┌─────────────────────────────────────────┐ +│ 🌅 今日简报 — 2026-05-16 │ +│ │ +│ 📊 活跃任务: 3 | 待审批: 1 | 今日完成: 2 │ +│ │ +│ ⚠️ 需要你处理: │ +│ • T-006 方案审批(等待 2h) │ +│ │ +│ 📈 今日进展: │ +│ • T-004 数据采集完成(赵云) │ +│ • T-005 风控检查通过(关羽) │ +│ │ +│ 💰 Token 消耗: ¥12.5 / 今日预算 ¥50 │ +│ │ +│ [审批 T-006] [查看全部] │ +└─────────────────────────────────────────┘ +``` + +**生成时机**: +- 用户打开 Dashboard 时自动刷新 +- 每日定时推送(可配置) +- 关键事件后更新 + +#### D9-7:Command Palette(⌘K) + +> **参考实践**: +> - **Raycast**:全局快捷键 + 模糊搜索 + 即用即走 +> - **cmdk(shadcn/ui)**:成熟的 React command palette 组件 + +**支持的命令**: + +| 类别 | 示例 | +|------|------| +| 任务操作 | "暂停任务 3" "查看 T-006 详情" "创建新任务" | +| 状态查询 | "张飞在干什么" "Token 用了多少" "有多少待审批" | +| 导航 | "打开产出档案" "跳转到 T-005" | +| 配置 | "切换模型" "查看技能列表" | + +**实现**:Phase 2,使用 cmdk 组件。 + +#### D9-8:评论线程 + +> **参考实践**: +> - **Hermes Kanban**:per-task comment thread,人和 Agent 都可评论 +> - **黑板 comment 机制**(课题1 §5.2):已设计结构化 comment + @mention + +每个任务有独立评论线程,展示在 L3 任务详情中: + +``` +┌─────────────────────────────────────────┐ +│ 💬 T-006 讨论线程 │ +│ │ +│ [庞统] 任务已创建,5个节点,预估30min │ +│ [张飞] ## Handoff: 编码完成 ✅ │ +│ 产出: strategy.py │ +│ [司马懿] 🔍 发现2个问题... │ +│ verdict: needs_revision │ +│ [张飞] REJECT: 问题1已修复,问题2不同意 │ +│ [你] → 输入评论... │ +└─────────────────────────────────────────┘ +``` + +**用户可以直接在评论线程中发言**,发言会被 Agent 看到(通过黑板 comment + inbox 通知)。 + +#### D9-9:技术方案 + +| 方面 | 方案 | 理由 | +|------|------|------| +| **前端框架** | React 18 + Vite + Zustand + Tailwind | 延续 v1.0 + Edict 已验证 | +| **实时通信** | M2: HTTP 轮询(5s) → M3: WebSocket | 渐进升级,延续 v1.0 策略 | +| **DAG 可视化** | React Flow | GitHub Actions 式 DAG,成熟方案 | +| **Command Palette** | cmdk(shadcn/ui) | 成熟的 command palette 组件 | +| **图表** | Recharts | 轻量级,已有使用经验 | +| **后端 API** | FastAPI + SQLite(黑板数据库) | 延续 v1.0 技术栈 | +| **UI 风格** | 深色主题(延续 Edict CSS 变量体系) | 已有完整设计系统 | + +> **注意**:v1.0 前端源码在 `~/.sanguo_projects/sanguo_moziplus/dashboard/`(React + Vite + TypeScript),可直接在此基础上重构。 + +#### D9-10:API 设计 + +Dashboard 后端 API 直接读取黑板数据库: + +| 端点 | 方法 | 用途 | +|------|------|------| +| `/api/tasks` | GET | 任务列表(支持 state/agent 过滤) | +| `/api/tasks/{id}` | GET | 任务详情(含 comments、reviews) | +| `/api/tasks/{id}/action` | POST | 操作(pause/resume/cancel/approve/reject) | +| `/api/agents` | GET | Agent 状态列表 | +| `/api/stats` | GET | 全局统计(活跃/完成/Token) | +| `/api/briefing` | GET | AI Briefing 内容 | +| `/api/comments/{task_id}` | GET/POST | 评论线程读写 | +| `/ws/events` | WebSocket | 实时事件推送(M3) | + +**关键设计**: +- 所有数据来自黑板数据库(单一数据源) +- Dashboard 不维护独立状态,是黑板数据的只读视图 + 操作入口 +- 操作端点(approve/reject)直接调用 Daemon API + +--- + +## 6. 和现有设计的对齐检查 + +| 已有设计 | 课题7+9 补充 | 一致性 | +|---------|-------------|--------| +| §4.2 Tick+Inbox 事件驱动 | D7-2 推送级别 → inbox 事件驱动通知 | ✅ Inbox 是推送机制的基础 | +| §5.1 Agent spawn 流程 | D7-5 主动汇报 → spawn 后庞统通知用户 | ✅ 庞统作为协调者汇报 | +| §3.4 原子操作 | D9-10 API action 端点 → 调用原子操作 | ✅ Dashboard 操作走黑板原子操作 | +| §3.5 评论线程 | D9-8 Dashboard 评论 → 黑板 comment | ✅ 单一数据源 | +| §9.7 状态机守卫 | D9-4 卡片按钮 → ACTION_GUARDS 对齐 | ✅ 前后端一致 | +| §4.5 续杯与心跳 | D9-5 Agent 心跳状态 → Dashboard 展示 | ✅ 心跳数据可视化 | +| v1.0 10 Tab 设计 | D9-3 精简为 5 页 | ✅ 合并冗余,保留核心 | +| Edict Dashboard | D9-2 三层信息 + D9-4 卡片 + D9-5 DAG | ✅ 直接复用模式 | + +## 7. Phase 落地规划 + +| Phase | 人机交互 | Dashboard | +|-------|---------|-----------| +| **Phase 1** | WebChat 推送(已有)+ 🔴必须确认 | 无前端(CLI + WebChat 够用) | +| **Phase 2** | 🟡通知 + 🟢信息 + ⌘K | 任务看板 + 全局监控 + 评论线程 | +| **Phase 3** | 🔵定时摘要 + AI Briefing | 产出档案 + 系统配置 + WebSocket | +| **Phase 4** | Canvas 产出物交互 | 全功能 + 优化 | + +## 8. 遗留 TODO + +| # | 待解决事项 | 归属 | 说明 | +|---|----------|------|------| +| T7-1 | 推送级别配置 UI | Phase 2 | 用户可调推送偏好 | +| T7-2 | 超时兜底机制实现 | Phase 2 | 审批超时后的自动处理 | +| T7-3 | WebChat 推送格式标准化 | Phase 1 | 庞统汇报消息的统一模板 | +| T9-1 | React Flow DAG 组件实现 | Phase 2 | DAG 拓扑可视化 | +| T9-2 | cmdk Command Palette 集成 | Phase 2 | ⌘K 快捷操作 | +| T9-3 | AI Briefing 内容生成逻辑 | Phase 3 | 读取黑板数据自动生成摘要 | +| T9-4 | Dashboard 评论 → 黑板 comment 联动 | Phase 2 | 用户在 Dashboard 评论 → 写入黑板 | +| T9-5 | WebSocket 实时推送 | Phase 3 | 替代轮询 | +| T9-6 | v1.0 前端重构方案 | Phase 2 | 10 Tab → 5 页面的迁移计划 | +| T9-7 | 产出物预览(Canvas) | Phase 4 | 代码 diff / Markdown / 图表渲染 |