# 课题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 处理时检查来源合法性
   ```json
   POST /api/tasks/T-006/action
   { "action": "approve", "source": "dashboard", "reason": "方案可行" }
   ```

2. **乐观锁**：action 请求必须带 `expected_version` 字段，Daemon 校验当前 version 是否匹配，不匹配则拒绝（409 Conflict）
   ```json
   { "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设计方案待用户进一步探讨后结题。