sanguo_moziplus_v2/docs/design/topic7-interaction-dashboard-proposal.md

课题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 验收汇报 ──── 中（审查产出，确认交付）

🔴 级别统一超时策略（适用于所有 🔴必须确认 的决策点）

核心原则：用户不在时，系统宁可暂停也不自动推进高风险操作。

时间段	行为
0-1h	正常等待，无额外动作
1-4h	每 30min 重发提醒（频率可配，通过 WebChat + Signal 双渠道）
4h 后	任务标记 escalated + 暂停（不继续执行，不自动 reject），通知渠道升级
用户回来	手动恢复（approve/reject/cancel），移除 escalated 标记

具体决策点：

决策点	触发条件	交互模式	超时兜底（覆盖上面的通用策略）
需求确认	庞统完成需求结构化后	即时对话	30min 后提醒，4h 后暂停
方案审批	complex 任务规划完成后	轻触确认	同通用策略（含 risk_level=high）
风控告警	关羽触发风控规则	必须确认	同通用策略：4h 后 escalated+暂停，保护资金安全
产出验收	任务全部完成后	沉浸观察	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）

并发与权限保护：

1. 来源标识：action 端点必须带 source 字段（dashboard / daemon / cli），Daemon 处理时检查来源合法性

   POST /api/tasks/T-006/action
   { "action": "approve", "source": "dashboard", "reason": "方案可行" }
   

2. 乐观锁：action 请求必须带 expected_version 字段，Daemon 校验当前 version 是否匹配，不匹配则拒绝（409 Conflict）

   { "action": "approve", "source": "dashboard", "expected_version": 3 }
   

   → Dashboard 前端在读取任务详情时获取 version，提交时带回，防止 Dashboard 和 Daemon 并发冲突。

3. 用户身份：Dashboard 评论的 author 统一为 "user"，与 Agent 的 "pangtong-fujunshi" / "zhangfei-dev" 等区分

关键设计：

• 所有数据来自黑板数据库（单一数据源）
• 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

注意：新版 topic7-9-interaction-dashboard-proposal.md 已完成设计，以下遗留全部由新版覆盖或为开发实现。

#	待解决事项	归属	说明
T7-1	推送级别配置 UI	Phase 2	✅ 新版已设计推送分级，用户偏好配置为开发实现
T7-2	超时兜底机制	Phase 2	✅ 新版已设计超时推送（🟡级别），具体党底在课题3解决
T7-3	WebChat 推送格式标准化	Phase 1	✅ 开发实现
T9-1	React Flow DAG 组件	Phase 2	✅ 开发实现
T9-2	cmdk Command Palette	Phase 2	✅ 开发实现
T9-3	AI Briefing	Phase 3	✅ 新版已设计日报/周报格式
T9-4	Dashboard 评论→黑板	Phase 2	✅ 开发实现
T9-5	WebSocket 实时推送	Phase 3	✅ 新版选 SSE + 降级轮询替代
T9-6	v1.0 前端重构	Phase 2	✅ 新版已设计 5 页面结构
T9-7	产出物预览 Canvas	Phase 4	✅ 开发实现

⏳ 待用户确认：课题7+9设计方案待用户进一步探讨后结题。