# ACPX Teams Monitor — UI 设计文档 V2

> 日期: 2026-04-12
> 状态: 已确认
> 前置文档: 2026-04-11-frontend-dashboard-design.md

## 1. 设计决策汇总

| 决策 | 选择 |
|------|------|
| 页面结构 | 三栏布局：左侧团队列表 + 中间看板 + 右侧消息 |
| 团队切换 | 左侧边栏列表（非下拉），点击切换 |
| 视图模式 | 按成员分列 + 按任务状态分列，Tab 切换 |
| 配色 | 浅色模式（Light），类似 Trello |
| 卡片密度 | 自适应：默认紧凑，可单独展开或批量展开 |
| 消息位置 | 右侧边栏（类似 Slack 线程），可折叠 |
| 交互 | 纯只读，不做任何写操作 |
| 数据刷新 | 准实时轮询（5-10s） |

## 2. 页面架构

```
┌──────────────────────────────────────────────────────────────┐
│  ACPX Teams Monitor              [🔄 Refresh]               │  ← 顶部导航栏
├────────┬────────────────────────────────────┬────────────────┤
│        │ 5 Members │ 8 Tasks │ 2 Blocked   │                │
│ Teams  ├────────────────────────────────────┤  Messages (15) │
│        │ [Members] [Tasks]                  │                │
│ ● Alpha│                                    │  @Sarah → "…"  │
│   Beta │ ┌────┐ ┌────┐ ┌────┐ ┌────┐      │  @David → "…"  │
│   Gamma│ │col1│ │col2│ │col3│ │col4│      │  @Emily → "…"  │
│   Delta│ │card│ │card│ │card│ │card│      │  ...           │
│        │ │card│ │card│ │    │ │    │      │                │
│        │ └────┘ └────┘ └────┘ └────┘      │                │
│        │ ← 主区域：Trello 看板 →           │                │
└────────┴────────────────────────────────────┴────────────────┘
  ~15%              ~55%                          ~30%
```

### 2.1 顶部导航栏
- Logo "ACPX Teams Monitor"
- 手动刷新按钮
- 轮询状态指示（上次刷新时间）

### 2.2 左侧团队边栏（~15%）
- 团队列表，纵向排列
- 每个条目显示：
  - 状态指示灯：🟢 有在线成员 / ⚪ 全部离线 / 🟡 有阻塞任务
  - 团队名称
  - 在线数/总成员数
- 当前选中团队高亮背景色
- 数据来源：遍历所有团队调用 `team_status`

### 2.3 中间主区域（~55%）

#### 2.3.1 摘要统计条
水平排列的统计徽章，展示当前选中团队的关键数字：
- 成员数（Members）
- 在线数（Online）
- 任务数（Tasks）
- 阻塞数（Blocked）— 红色高亮
- 未读消息数（Unread）

#### 2.3.2 视图切换 Tab
两个 Tab 按钮：
- **Members** — 按成员分列视图
- **Tasks** — 按任务状态分列视图

#### 2.3.3 Members 视图（按成员分列）
- 每列代表一个团队成员
- 列头信息：
  - 成员名称
  - 状态点：🟢 running / 🟡 idle / 🔴 dead / ⚫ no-session
  - agent_type 标签（如 claude、codex、gemini）
  - model 名称（如 claude-opus-4-6）
- 列内内容：
  - 该成员 own 的任务卡片（自适应密度）
  - 无任务时显示 "(no tasks)"

#### 2.3.4 Tasks 视图（按任务状态分列）
- 列分类：Pending / In Progress / Completed
- 列头：状态名 + 计数徽章
- 卡片内容：任务标题 + owner + 阻塞关系标记

#### 2.3.5 自适应任务卡片

**紧凑模式（默认）：**
- 任务标题（粗体）
- 状态色点
- Owner 名称（灰色小字）
- 展开箭头

**展开模式：**
- 任务标题（粗体）
- 描述摘要（2 行）
- 状态徽章（彩色 pill）
- Owner 名称
- active_form 文本（当前在做什么）
- 依赖关系：Blocked by #X / Blocks #Y
- 自定义 metadata（如有）
- 创建时间

**操作：**
- 单卡展开/收起：点击卡片上的箭头
- 批量展开/收起：Expand All / Collapse All 按钮

### 2.4 右侧消息边栏（~30%）
- 标题：Messages + 总数 + 未读数徽章
- 消息列表按时间倒序
- 每条消息显示：
  - 发送者颜色点 + 名称
  - 消息内容预览
  - 相对时间（2m ago, 5m ago）
  - 已读/未读状态（未读蓝色高亮）
  - 消息类型图标：
    - 💬 普通文本
    - 📋 task_assignment
    - ⏹ shutdown_request
    - 🌙 idle_notification
- 可折叠（点击标题或拖拽边缘）
- 滚动加载更多历史消息
- 数据来源：`read_inbox`（team-lead 收件箱） + `check_teammate` 的 pending_from

## 3. 数据映射

### 3.1 MCP 调用与区域对应

| 页面区域 | MCP 工具 | 调用参数 |
|---------|---------|---------|
| 左侧团队列表 | `team_status(team_name)` | 遍历所有团队 |
| 摘要统计条 | `team_status` + `task_list` | 当前团队 |
| Members 视图列头 | `team_status(team_name)` | 当前团队 |
| Members 视图列头详情 | `read_config(team_name)` | 获取 agent_type, model, color |
| 任务卡片 | `task_list(team_name)` | 当前团队所有任务 |
| 任务卡片展开 | `task_get(team_name, task_id)` | 单个任务详情 |
| 消息边栏 | `check_teammate(team_name, agent_name, include_messages=True)` | 遍历当前团队成员 |

### 3.2 数据模型映射

| 数据字段 | 来源 | UI 展示位置 |
|---------|------|-----------|
| team.name | read_config | 左侧边栏团队名 |
| team.description | read_config | 左侧边栏 tooltip |
| member.name | team_status | Members 视图列头 |
| member.agent_status | team_status | 状态色点 |
| member.agent_type | read_config | Members 视图列头标签 |
| member.model | read_config | Members 视图列头 |
| member.color | read_config | 消息边栏发送者色点 |
| task.subject | task_list | 卡片标题 |
| task.description | task_get | 卡片展开描述 |
| task.status | task_list | 卡片状态徽章 / Tasks 视图分列 |
| task.owner | task_list | 卡片 owner / Members 视图分列 |
| task.blocks / blocked_by | task_list | 卡片依赖标记 |
| task.active_form | task_list | 卡片展开"当前在做" |
| task.metadata | task_get | 卡片展开自定义字段 |
| message.from | check_teammate | 消息边栏发送者 |
| message.text | check_teammate | 消息边栏内容 |
| message.timestamp | check_teammate | 消息边栏时间 |
| message.read | check_teammate | 消息边栏已读/未读 |
| message.color | check_teammate | 消息边栏色点 |

## 4. 交互规则

### 4.1 只读交互（V1 允许）

| 交互 | 行为 |
|------|------|
| 点击左侧团队 | 切换当前团队，刷新中间+右侧数据 |
| 点击 Members/Tasks Tab | 切换看板视图模式 |
| 点击紧凑卡片展开箭头 | 展开单张卡片显示完整信息 |
| 点击 Expand All / Collapse All | 批量展开/收起所有卡片 |
| 点击刷新按钮 | 手动触发数据刷新 |
| 消息边栏滚动 | 加载更多历史消息 |
| 折叠/展开消息边栏 | 隐藏/显示右侧消息面板 |

### 4.2 禁止操作（V1 明确排除）
- 发消息 / 广播
- 改任务状态 / 改 owner
- 处理队列 / 启停 teammate
- 删除或创建团队
- 修改收件箱

## 5. 数据轮询策略

| 数据 | 轮询间隔 | 说明 |
|------|---------|------|
| 团队列表 + ���态 | 10s | 左侧边栏更新团队在线状态 |
| 当前团队成员状态 | 5s | 成员 running/idle/dead 变化较快 |
| 当前团队任务列表 | 10s | 任务状态变化相对慢 |
| 当前团队消息 | 5s | 消息需要较实时 |

- 切换团队时立即触发全量刷新
- 手动刷新按钮触发全量刷新
- 轮询失败时显示错误提示，不中断展示

## 6. 视觉反馈

- **状态变化**：成员状态变更时，状态点短暂脉冲动画
- **新消息**：新消息到达时，消息边栏标题闪烁 + 未读计数更新
- **加载态**：刷新时卡片区域显示轻量 skeleton 占位
- **异常高亮**：
  - 阻塞任务卡片左边框变红
  - no-session 成员列头变灰
  - 左侧团队有异常时显示黄色警告图标

## 7. 响应式适配

| 断点 | 行为 |
|------|------|
| >1440px | 三栏完整展示 |
| 1024-1440px | 消息边栏可折叠，默认折叠 |
| <1024px | 左侧团队栏折叠为图标，消息栏折叠为底部 Tab |

## 8. 配色方案

| 元素 | 色值 |
|------|------|
| 页面背景 | #F8F9FA |
| 卡片背景 | #FFFFFF |
| 卡片边框 | #E2E8F0 |
| 列背景 | #EBEDF0 |
| 主文字 | #1A202C |
| 次要文字 | #718096 |
| 强调色-绿（running/online/completed） | #34D399 |
| 强调色-琥珀（idle/warning） | #FBBF24 |
| 强调色-红（blocked/dead/error） | #F87171 |
| 强调色-蓝（pending/unread） | #60A5FA |
| 选中高亮 | #EBF4FF |

## 9. 效果图参考

设计过程中生成的效果图（位于项目根目录）：

| 文件 | 说明 |
|------|------|
| `2026-04-12-23-12-00-layout-a-by-member.png` | 按成员分列布局 |
| `2026-04-12-23-12-00-layout-b-by-status.png` | 按任务状态分列布局 |
| `2026-04-12-23-12-00-layout-c-by-type.png` | 按信息类型分列布局 |
| `2026-04-12-23-22-00-card-a-compact.png` | 紧凑型卡片 |
| `2026-04-12-23-22-00-card-b-expanded.png` | 展开型卡片 |
| `2026-04-12-23-22-00-card-c-adaptive.png` | 自适应卡片 |
| `2026-04-12-23-29-00-msg-a-bottom-panel.png` | 消息底部面板 |
| `2026-04-12-23-29-00-msg-b-right-sidebar.png` | 消息右侧边栏 |
| `2026-04-12-23-29-00-msg-c-tab-view.png` | 消息独立 Tab |
