cfdaily
467 lines
17 KiB
Markdown
467 lines
17 KiB
Markdown
# 课题9：Dashboard 前后端完整设计方案
|
||
|
||
**版本**: v2.0（评审修订版）
|
||
**作者**: 庞统（副军师）🐦
|
||
**日期**: 2026-05-17
|
||
**状态**: 待司马懿确认
|
||
**评审记录**: Mail #278（司马懿 P0+P1 评审）→ 已全部修复 → Mail #279（验证通过）
|
||
|
||
---
|
||
|
||
## 一、核心定位
|
||
|
||
### 1.1 Dashboard 不是管理控制台，是 AI 工作可视化窗口
|
||
|
||
| 传统 Dashboard | AI Native Dashboard（v2.0） |
|
||
|---|---|
|
||
| 用户主动操作（点按钮、填表单） | AI 主动展示（推送状态、产出、决策请求） |
|
||
| 用户监控一切 | AI 只在关键点拉人，其余自主 |
|
||
| 表格+表单为主 | 时间线+卡片+对话为主 |
|
||
| 用户是驾驶员 | 用户是乘客，偶尔导航 |
|
||
|
||
### 1.2 参考的优秀实践
|
||
|
||
| 实践 | 借鉴点 |
|
||
|------|--------|
|
||
| **Edict MiniPipe** | 任务卡片上的状态管线可视化 |
|
||
| **Hermes Kanban** | 卡片 + 结果区 + 评论线程 + 事件流 + Nudge 按钮 |
|
||
| **Claude Code App** | 多 Tab 切换详情面板（产出/评审/事件） |
|
||
| **Linear** | 精准通知不噪音；状态流转按钮守卫 |
|
||
| **Devin** | AI 自主执行的观察窗口理念 |
|
||
| **OpenClaw Control Center** | 双入口对等（对话 + Dashboard） |
|
||
|
||
---
|
||
|
||
## 二、数据模型
|
||
|
||
### 2.1 V2Task 类型（对齐后端 tasks 表）
|
||
|
||
前端核心类型，字段完全对齐后端 `src/blackboard/db.py` 的 `tasks` 表：
|
||
|
||
```typescript
|
||
interface V2Task {
|
||
// 基础字段（直接对应 tasks 表列）
|
||
id: string;
|
||
title: string;
|
||
description: string;
|
||
status: TaskStatus; // 8 状态枚举，见 §2.2
|
||
assignee: string | null;
|
||
assigned_by: string | null;
|
||
depends_on: string | null; // 依赖任务 ID
|
||
parent_task: string | null; // 父任务 ID
|
||
priority: number; // 1-10 整数（P0 修复：前端曾用 string，已改 number）
|
||
task_type: string;
|
||
created_at: string;
|
||
updated_at: string;
|
||
claimed_at: string | null;
|
||
completed_at: string | null;
|
||
started_at: string | null;
|
||
deadline: string | null;
|
||
retry_count: number;
|
||
max_retries: number;
|
||
risk_level: 'low' | 'standard' | 'high' | 'critical';
|
||
escalated: number; // 0/1 整数（与后端 INTEGER 一致）
|
||
|
||
// 聚合字段（后端 summary API 或前端多次查询）
|
||
comments_count: number;
|
||
outputs_count: number;
|
||
review_status: 'none' | 'pending' | 'approved' | 'rejected' | 'rebuttal';
|
||
latest_event: string | null;
|
||
project_id: string;
|
||
}
|
||
```
|
||
|
||
### 2.2 状态机（8 状态，对齐后端 VALID_STATUSES）
|
||
|
||
```
|
||
pending ──→ claimed ──→ working ──→ review ──→ done
|
||
│ │ │ │
|
||
│ │ ├→ blocked ├→ failed
|
||
│ │ │ │
|
||
└→ cancelled←┴───────────┴───────────┘
|
||
```
|
||
|
||
**线性管线**（5 步）：`pending → claimed → working → review → done`
|
||
|
||
**旁路状态**：`failed`（标记在 working 位置）、`blocked`（标记在 working 位置）
|
||
|
||
**终态**：`done`、`cancelled`
|
||
|
||
### 2.3 状态流转守卫（对齐后端 VALID_TRANSITIONS）
|
||
|
||
```typescript
|
||
const VALID_TRANSITIONS: Record<string, string[]> = {
|
||
pending: ['claimed', 'cancelled'],
|
||
claimed: ['working', 'pending', 'cancelled'],
|
||
working: ['review', 'blocked', 'failed', 'cancelled'],
|
||
review: ['done', 'pending', 'failed', 'cancelled'],
|
||
blocked: ['pending', 'cancelled'],
|
||
failed: ['pending'],
|
||
done: [],
|
||
cancelled: [],
|
||
};
|
||
```
|
||
|
||
与后端 `src/blackboard/db.py` 的 `VALID_TRANSITIONS` 完全一致。
|
||
|
||
### 2.4 Priority 映射
|
||
|
||
后端 `priority` 是 INTEGER（1-10），前端映射：
|
||
|
||
```typescript
|
||
const PRIORITY_META: Record<number, { color: string; label: string }> = {
|
||
1: { color: '#6b7280', label: '低' },
|
||
2: { color: '#6b7280', label: '低' },
|
||
3: { color: '#3b82f6', label: '中' },
|
||
4: { color: '#3b82f6', label: '中' },
|
||
5: { color: '#f59e0b', label: '高' },
|
||
6: { color: '#f59e0b', label: '高' },
|
||
7: { color: '#ff5270', label: '紧急' },
|
||
8-10: { color: '#ff5270', label: '紧急' },
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 三、前端页面设计
|
||
|
||
### 3.1 页面结构
|
||
|
||
| 页面 | 组件 | 优先级 | 状态 |
|
||
|------|------|--------|------|
|
||
| **📜 任务看板** | EdictBoard | P0 | ✅ Mock UI 已完成，待对接 API |
|
||
| **🔍 任务详情** | TaskModal | P0 | ✅ Mock UI 已完成，待对接 API |
|
||
| **🏛️ 朝堂议政** | CourtDiscussion | P1 | 迁移自 v1.0 |
|
||
| **🔌 编排调度** | MonitorPanel | P1 | 迁移自 v1.0 |
|
||
| **🤺 将军总览** | OfficialPanel | P1 | 迁移自 v1.0 |
|
||
| **🔔 通知中心** | NotificationCenter | P1 | 占位（Header 铃铛） |
|
||
| **📊 AI Briefing** | AIBriefing | P2 | 占位页面 |
|
||
| **⚙️ 系统设置** | SettingsPanel | P1 | 迁移自 v1.0 |
|
||
|
||
### 3.2 任务看板（EdictBoard）
|
||
|
||
#### 顶部统计（4 格）
|
||
|
||
| 格 | 内容 | 数据来源 |
|
||
|---|------|---------|
|
||
| 活跃任务 | working + claimed + review 数 | tasks 表 count |
|
||
| 已完成 | done 数 | tasks 表 count |
|
||
| 失败/阻塞 | failed + blocked 数 | tasks 表 count |
|
||
| 审查中 | review 数 | tasks 表 count |
|
||
|
||
#### 状态管线可视化（5 步线性）
|
||
|
||
```
|
||
📋待认领 → 👤已认领 → ⚔️执行中 → 🔍审查中 → ✅已完成
|
||
```
|
||
|
||
- 管线上游步骤显示 ✓（绿色），当前步骤高亮（蓝色），下游步骤灰显
|
||
- `failed` 状态：在 working 位置显示 ✗（红色）
|
||
- `blocked` 状态：在 working 位置显示 🚧（黄色）
|
||
- `cancelled` 状态：管线全部灰显
|
||
|
||
#### 筛选栏
|
||
|
||
8 个状态筛选按钮（all/pending/claimed/working/review/done/failed/blocked）+ 搜索框。
|
||
|
||
#### 任务卡片
|
||
|
||
每张卡片展示：
|
||
- **状态管线**（5 步 MiniPipe）
|
||
- **ID + 标题**
|
||
- **标签行**：状态标签 + 负责人（agent emoji）+ 优先级 + 升级标记 + 依赖标记
|
||
- **元信息行**：更新时间 + 产出数 + 评论数 + 审查状态图标
|
||
- **最新事件**：单行文本截断
|
||
- **底部**：风险等级 + 重试次数 + 截止时间 + 详情按钮
|
||
|
||
### 3.3 任务详情面板（TaskModal）
|
||
|
||
点击任务卡片弹出 Modal，4 Tab 布局：
|
||
|
||
#### Tab 1: 📋 总览
|
||
|
||
| 区域 | 内容 | 数据来源 |
|
||
|------|------|---------|
|
||
| 需求描述 | task.description | tasks 表 |
|
||
| 状态操作 | 基于 VALID_TRANSITIONS 的操作按钮 | §2.3 守卫 |
|
||
| 任务信息 | 类型/优先级/风险/重试/时间/分配人（8 字段网格） | tasks 表 |
|
||
| 事件时间线 | 逆序事件列表（图标 + 描述 + 时间 + agent） | events 表 |
|
||
| 评论/交接 | handoff/progress/review/rebuttal/debate/observation 6 种类型 | comments 表 |
|
||
| 决策记录 | 决策人 + 决策类型 + 理由 | decisions 表 |
|
||
| Checkpoint | 占位（虚线框 + "v2.7 提供"） | ❌ 后端未实现 |
|
||
|
||
#### Tab 2: 📦 产出
|
||
|
||
产出物列表：agent + 内容 + 类型标签 + 尝试次数 + 时间。数据来源：outputs 表。
|
||
|
||
#### Tab 3: 🔍 审查
|
||
|
||
审查意见：评审人 + verdict（APPROVE/REJECT）+ 置信度 + 风险等级 + 辩论轮次 + 摘要。数据来源：reviews 表。
|
||
|
||
#### Tab 4: 🧠 经验
|
||
|
||
关联经验：标题 + 摘要 + 标签。左侧彩色边框区分 best_practice（绿）/ pitfall（红）/ environment（蓝）。数据来源：experiences 表。
|
||
|
||
### 3.4 通知中心（Header 铃铛）
|
||
|
||
```
|
||
🔔 (3) → 点击展开通知面板
|
||
```
|
||
|
||
- 按 4 级分组（🔴 Critical > 🟡 Warning > 🟢 Info > 🔵 Silent）
|
||
- 每条：时间 + 级别图标 + 内容摘要 + 关联任务链接
|
||
- 🔴 可展开操作按钮
|
||
- 支持标记已读/全部已读
|
||
|
||
**当前状态**：SSE broker 已实现（F17），ticker 未推送事件。前端做铃铛 UI + 占位。
|
||
|
||
### 3.5 AI Briefing
|
||
|
||
日报/周报自动生成。格式：
|
||
|
||
```
|
||
📊 今日战报 (2026-05-17)
|
||
━━━━━━━━━━━━━━━━━━━━
|
||
📋 完成任务：3 个
|
||
🔄 进行中：2 个
|
||
⚠️ 需关注：1 个
|
||
💰 Token 消耗：127K
|
||
🧠 新增经验：2 条
|
||
```
|
||
|
||
**当前状态**：后端未实现。前端做占位页面。
|
||
|
||
---
|
||
|
||
## 四、后端 API 设计
|
||
|
||
### 4.1 已有 API（F5 实现）
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/projects/{pid}/tasks` | GET | 任务列表（支持 status 筛选） |
|
||
| `/api/projects/{pid}/tasks` | POST | 创建任务 |
|
||
| `/api/projects/{pid}/tasks/{tid}` | GET | 单任务基本信息 |
|
||
| `/api/projects/{pid}/tasks/{tid}` | PATCH | 更新任务 |
|
||
| `/api/projects/{pid}/tasks/{tid}/status` | POST | 状态流转 |
|
||
| `/api/projects/{pid}/tasks/{tid}/claim` | POST | 认领任务 |
|
||
| `/api/projects/{pid}/tasks/{tid}/comments` | GET/POST | 评论 CRUD |
|
||
| `/api/projects/{pid}/tasks/{tid}/outputs` | GET/POST | 产出 CRUD |
|
||
| `/api/projects/{pid}/tasks/{tid}/decisions` | GET/POST | 决策 CRUD |
|
||
| `/api/projects/{pid}/tasks/{tid}/observations` | GET/POST | 观察 CRUD |
|
||
| `/api/projects/{pid}/tasks/{tid}/reviews` | GET/POST | 审查 CRUD |
|
||
| `/api/events` | GET (SSE) | SSE 事件流 |
|
||
| `/api/daemon/status` | GET | Daemon 状态 |
|
||
| `/api/projects` | GET/POST | 项目管理 |
|
||
|
||
### 4.2 需新增的 API
|
||
|
||
#### API-1: `GET /api/projects/{pid}/tasks/{tid}?expand=comments,outputs,reviews,events,decisions`
|
||
|
||
**优先级**: P0
|
||
**说明**: 任务详情聚合，一次返回全部关联数据，避免前端多次请求。
|
||
**实现方案**: 在 `blackboard_routes.py` 的 `get_task` 端点增加 `expand` 查询参数。
|
||
|
||
```python
|
||
@router.get("/tasks/{task_id}")
|
||
async def get_task(
|
||
task_id: str,
|
||
expand: str = "", # 逗号分隔: "comments,outputs,reviews,events,decisions"
|
||
db_path: Path = Depends(get_db_path),
|
||
):
|
||
task = queries.get_task(db_path, task_id)
|
||
if not task:
|
||
raise HTTPException(404, "Task not found")
|
||
|
||
result = dict(task)
|
||
|
||
if expand:
|
||
for rel in expand.split(","):
|
||
rel = rel.strip()
|
||
if rel == "comments":
|
||
result["comments"] = queries.list_comments(db_path, task_id)
|
||
elif rel == "outputs":
|
||
result["outputs"] = queries.list_outputs(db_path, task_id)
|
||
elif rel == "reviews":
|
||
result["reviews"] = queries.list_reviews(db_path, task_id)
|
||
# 聚合 review_status
|
||
if result["reviews"]:
|
||
latest = result["reviews"][-1]
|
||
result["review_status"] = "approved" if latest["verdict"] == "APPROVE" else "rejected"
|
||
else:
|
||
result["review_status"] = "none"
|
||
elif rel == "events":
|
||
result["events"] = queries.list_events(db_path, task_id)
|
||
# 聚合 latest_event
|
||
if result["events"]:
|
||
result["latest_event"] = result["events"][-1]["detail"]
|
||
elif rel == "decisions":
|
||
result["decisions"] = queries.list_decisions(db_path, task_id)
|
||
|
||
# 聚合计数
|
||
result["comments_count"] = queries.count_comments(db_path, task_id)
|
||
result["outputs_count"] = queries.count_outputs(db_path, task_id)
|
||
|
||
return result
|
||
```
|
||
|
||
**工作量**: 30min（queries.py 已有基础方法，只需组合）
|
||
|
||
#### API-2: `GET /api/projects/{pid}/tasks/{tid}/events`
|
||
|
||
**优先级**: P0
|
||
**说明**: 任务事件时间线查询。
|
||
**实现方案**: 新增路由端点。
|
||
|
||
```python
|
||
@router.get("/tasks/{task_id}/events")
|
||
async def get_task_events(
|
||
task_id: str,
|
||
limit: int = 50,
|
||
offset: int = 0,
|
||
db_path: Path = Depends(get_db_path),
|
||
):
|
||
return queries.list_events(db_path, task_id, limit=limit, offset=offset)
|
||
```
|
||
|
||
**前置**: `queries.list_events()` 已存在（events 表 CRUD 已实现）。
|
||
**工作量**: 15min
|
||
|
||
#### API-3: `GET /api/projects/{pid}/tasks/{tid}/experiences`
|
||
|
||
**优先级**: P1
|
||
**说明**: 查询与任务关联的经验（通过 task_id 检索 experiences.jsonl）。
|
||
**实现方案**: 新增路由端点 + queries 方法。
|
||
|
||
```python
|
||
@router.get("/tasks/{task_id}/experiences")
|
||
async def get_task_experiences(
|
||
task_id: str,
|
||
project_id: str,
|
||
):
|
||
# 从 experiences.jsonl 读取，过滤 source_task == task_id
|
||
experiences = experience_store.list_by_task(project_id, task_id)
|
||
return experiences
|
||
```
|
||
|
||
**工作量**: 30min（需在 experience_store 增加 `list_by_task` 方法）
|
||
|
||
### 4.3 已有 API 但需增强
|
||
|
||
| 端点 | 增强 | 说明 |
|
||
|------|------|------|
|
||
| `GET /api/projects/{pid}/tasks` | 增加 `counts` 返回 | 任务列表 API 返回各状态计数，供统计卡片使用 |
|
||
| `GET /api/events` (SSE) | ticker 事件推送 | ticker 状态变更时自动通过 SSE 推送（F17 SSEBroker 已实现，只需在 ticker 中调用 publish） |
|
||
|
||
### 4.4 完整路由表
|
||
|
||
```
|
||
/api/projects GET/POST
|
||
/api/projects/{pid} GET/DELETE
|
||
/api/projects/{pid}/tasks GET/POST
|
||
/api/projects/{pid}/tasks/{tid} GET/PATCH/DELETE
|
||
/api/projects/{pid}/tasks/{tid}/status POST
|
||
/api/projects/{pid}/tasks/{tid}/claim POST
|
||
/api/projects/{pid}/tasks/{tid}/comments GET/POST
|
||
/api/projects/{pid}/tasks/{tid}/outputs GET/POST
|
||
/api/projects/{pid}/tasks/{tid}/decisions GET/POST
|
||
/api/projects/{pid}/tasks/{tid}/observations GET/POST
|
||
/api/projects/{pid}/tasks/{tid}/reviews GET/POST
|
||
/api/projects/{pid}/tasks/{tid}/events GET ← 新增 API-2
|
||
/api/projects/{pid}/tasks/{tid}/experiences GET ← 新增 API-3
|
||
/api/events GET (SSE)
|
||
/api/daemon/status GET
|
||
```
|
||
|
||
---
|
||
|
||
## 五、实现方案
|
||
|
||
### 5.1 后端改动清单
|
||
|
||
| # | 改动 | 文件 | 优先级 | 工作量 |
|
||
|---|------|------|--------|--------|
|
||
| B1 | `get_task` 增加 `expand` 参数 | `blackboard_routes.py` + `queries.py` | P0 | 30min |
|
||
| B2 | 新增 `GET /tasks/{tid}/events` 路由 | `blackboard_routes.py` | P0 | 15min |
|
||
| B3 | 新增 `GET /tasks/{tid}/experiences` 路由 | `blackboard_routes.py` + `experience_store.py` | P1 | 30min |
|
||
| B4 | 任务列表 API 返回状态计数 | `blackboard_routes.py` | P1 | 15min |
|
||
| B5 | ticker 状态变更推送 SSE | `ticker.py` | P1 | 1h |
|
||
|
||
### 5.2 前端改动清单
|
||
|
||
| # | 改动 | 文件 | 优先级 | 工作量 |
|
||
|---|------|------|--------|--------|
|
||
| F1 | EdictBoard Mock → 对接真实 API | `EdictBoard.tsx` | P0 | 1h |
|
||
| F2 | TaskModal Mock → 对接真实 API | `TaskModal.tsx` | P0 | 1.5h |
|
||
| F3 | api.ts 补新 API 方法 | `api.ts` | P0 | 30min |
|
||
| F4 | store.ts 补状态字段 | `store.ts` | P0 | 15min |
|
||
| F5 | SSE EventSource 替代轮询 | `App.tsx` + `store.ts` | P1 | 1h |
|
||
| F6 | 通知中心铃铛占位 | `NotificationCenter.tsx` + `App.tsx` | P1 | 30min |
|
||
| F7 | AI Briefing 占位页面 | `AIBriefing.tsx` | P2 | 15min |
|
||
| F8 | 其余 v1.0 Tab 适配 | 各 Panel 组件 | P1 | 2h |
|
||
|
||
### 5.3 执行顺序
|
||
|
||
```
|
||
Phase 1: 后端补 API（B1-B3） ~1.5h
|
||
Phase 2: 前端核心对接（F1-F4） ~3h
|
||
Phase 3: SSE + 通知占位（B5+F5+F6） ~2.5h
|
||
Phase 4: 其余 Tab 适配（F8） ~2h
|
||
Phase 5: 联调 + E2E 验证 ~1h
|
||
总计: ~10h
|
||
```
|
||
|
||
### 5.4 不在本轮范围
|
||
|
||
| 功能 | 原因 | 计划 |
|
||
|------|------|------|
|
||
| Checkpoint（验证/决策/执行） | 后端无数据模型，需新设计 | v2.7 专项 |
|
||
| AI Briefing 生成 | 后端聚合逻辑未设计 | v2.7 专项 |
|
||
| Artifact 文件预览/下载 | 后端无文件存储机制 | v2.7 评估 |
|
||
| 朝堂议政迁移 | 需要 CourtDiscussion 适配 v2.6 API | v2.7 |
|
||
|
||
---
|
||
|
||
## 六、UI 组件文件结构
|
||
|
||
```
|
||
src/frontend/src/
|
||
├── App.tsx # 主布局 + Header + Tab 路由
|
||
├── api.ts # API 层（所有后端调用）
|
||
├── store.ts # Zustand 全局状态
|
||
├── types.ts # V2Task 等类型定义（从 EdictBoard 提取）
|
||
└── components/
|
||
├── EdictBoard.tsx # 任务看板（卡片 + 筛选 + 搜索）
|
||
├── TaskModal.tsx # 任务详情（4 Tab）
|
||
├── NotificationCenter.tsx # 通知铃铛（占位）
|
||
├── CourtDiscussion.tsx # 朝堂议政（迁移自 v1.0）
|
||
├── MonitorPanel.tsx # 编排调度（迁移自 v1.0）
|
||
├── OfficialPanel.tsx # 将军总览（迁移自 v1.0）
|
||
├── ModelConfig.tsx # 模型配置（迁移自 v1.0）
|
||
├── SkillsConfig.tsx # 技能配置（迁移自 v1.0）
|
||
├── SessionsPanel.tsx # 传令巡哨（迁移自 v1.0）
|
||
├── MemorialPanel.tsx # 奏折阁（迁移自 v1.0）
|
||
├── SettingsPanel.tsx # 系统设置（迁移自 v1.0）
|
||
└── GlobalSearch.tsx # 全局搜索
|
||
```
|
||
|
||
---
|
||
|
||
## 七、评审修订记录
|
||
|
||
### 司马懿 Mail #278 评审 → 修复
|
||
|
||
| 项目 | 级别 | 修复内容 |
|
||
|------|------|---------|
|
||
| P0: priority 类型 | 必修 | `string` → `number`（1-10），前端 PRIORITY_META 按整数映射 |
|
||
| P1: 状态管线 | 必修 | 4 步 → 5 步线性 + blocked 旁路，8 状态全覆盖 |
|
||
| P1: VALID_TRANSITIONS | 必修 | 完全对齐后端 `db.py` 的 8×N 映射 |
|
||
| P2: 遗漏字段 | 建议 | V2Task 补 `depends_on`, `parent_task` |
|
||
|
||
### 司马懿 Mail #279 确认
|
||
|
||
> ✅ P0 priority: number
|
||
> ✅ P1 STATUS_ORDER 含 review/blocked
|
||
> ✅ P1 TaskModal 状态映射含 reviewing/blocked/cancelled（17 处引用）
|
||
> 构建产物 12:37 部署在 8083，前端可访问。
|