Skip to content

PRD.md

Latest commit

 

History

History
344 lines (276 loc) · 10.7 KB

PRD.md

File metadata and controls

344 lines (276 loc) · 10.7 KB

Claude Code 可视化系统 - 产品需求文档 (PRD)

1. 产品概述

1.1 产品定位

一个用于可视化展示 Claude Code 团队协作状态的 Web 系统，帮助用户直观了解团队结构、任务进展和会话活动。

1.2 产品目标

  • 透明化: 让团队协作状态可视化、透明化
  • 实时监控: 实时展示团队运行状态和任务进度
  • 易于导航: 提供清晰的层级结构和导航体验
  • 数据完整: 完整展示 .claude 目录中的所有核心数据

2. 目标用户

用户类型 使用场景 核心需求
团队经理 查看团队整体状态 全局视图、任务分配概览
团队成员 查看个人任务和协作者 任务详情、依赖关系
项目观察者 了解项目进展 进度展示、历史记录

3. 核心功能模块

3.1 模块架构

┌─────────────────────────────────────────────────┐
│              导航栏 (Navigation)                 │
├─────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────────────┐  │
│  │ 团队列表 │  │ 任务看板 │  │ 详情面板        │  │
│  │ (Teams) │  │ (Tasks) │  │ (Detail Panel)  │  │
│  └─────────┘  └─────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────┤
│              状态栏 (Status Bar)                 │
└─────────────────────────────────────────────────┘

3.2 功能清单

F1: 团队可视化 (Team Visualization)

功能点 描述 优先级
F1.1 团队卡片展示 (名称、描述、创建时间) Must-have
F1.2 成员列表展示 (头像/名称、角色、状态) Must-have
F1.3 团队状态指示器 (活跃/非活跃) Must-have
F1.4 团队详情展开面板 Should-have
F1.5 团队创建时间格式化显示 Could-have

F2: 任务可视化 (Task Visualization)

功能点 描述 优先级
F2.1 任务卡片展示 (主题、描述、状态) Must-have
F2.2 任务状态标签 (pending/in_progress/completed/deleted) Must-have
F2.3 任务所有者展示 Must-have
F2.4 任务依赖关系可视化 (blocks/blockedBy) Should-have
F2.5 任务筛选 (按状态/所有者) Should-have
F2.6 任务排序 (按 ID/状态) Could-have

F3: 导航与交互

功能点 描述 优先级
F3.1 侧边栏导航 (Teams/Tasks/History/Memory) Must-have
F3.2 点击查看详情 Must-have
F3.3 搜索功能 Should-have
F3.4 面包屑导航 Could-have

F4: 数据展示

功能点 描述 优先级
F4.1 .claude 目录结构树 Should-have
F4.2 配置文件内容查看 Should-have
F4.3 历史记录浏览 Could-have
F4.4 记忆文件查看 Could-have

4. 数据模型

4.1 Team (团队)

interface Team {
  name: string;
  description: string;
  createdAt: string;
  leadAgentId: string;
  leadSessionId: string;
  members: Member[];
}

interface Member {
  agentId: string;
  name: string;
  agentType: string;
  model: string;
  prompt: string;
  color: string;
  tmuxPaneId?: string;
  isActive: boolean;
}

4.2 Task (任务)

interface Task {
  id: string;
  subject: string;
  description: string;
  activeForm: string;
  owner?: string;
  status: 'pending' | 'in_progress' | 'completed' | 'deleted';
  blocks: string[];
  blockedBy: string[];
}

4.3 目录结构 (Directory Structure)

interface DirectoryNode {
  name: string;
  type: 'file' | 'directory';
  path: string;
  children?: DirectoryNode[];
  content?: string; // 文件内容
}

5. 交互设计要点

5.1 状态颜色映射

状态 颜色
pending 灰色 (gray)
in_progress 蓝色 (blue)
completed 绿色 (green)
deleted 红色 (red)

5.2 团队成员颜色

  • 使用配置中的 color 字段
  • 未指定时使用默认色板

5.3 响应式设计

  • 桌面端：三栏布局 (导航 + 主内容 + 详情)
  • 平板端：两栏布局 (导航可折叠)
  • 移动端：单栏布局 (抽屉式导航)

5.4 视觉风格 (v1.2 更新)

  • 主题: 暗色系主题 (深色背景 + 半透明白色)
  • 主色调: 蓝色 (#4a9eff) 用于高亮和选择状态
  • 状态色: 黄 (pending) / 蓝 (in_progress) / 绿 (completed)
  • 字体: 系统默认字体

5.5 筛选器交互设计 (v1.2 更新)

┌─────────────────────────────────────────┐
│  任务列表                                 │
├─────────────────────────────────────────┤
│  [状态筛选 ▼]  [负责人 ▼]  [🔍 搜索]     │
│   □ 待处理                               │
│   □ 进行中                               │
│   □ 已完成                               │
│   [清除筛选]                             │
└─────────────────────────────────────────┘
  • 下拉多选框设计
  • 支持组合筛选
  • 筛选条件以标签形式展示
  • 一键清除筛选

5.6 依赖关系可视化设计 (v1.2 更新)

  • 实现方式: SVG 或 Canvas 连线图
  • 箭头颜色: 红色 (阻塞) / 橙色 (被阻塞)
  • 交互: 鼠标悬停高亮相关任务
  • 图例: 显示箭头含义说明

5.7 搜索功能设计 (v1.2 更新)

  • 位置: 导航栏全局搜索框
  • 范围: 团队名称、任务主题、成员名称
  • 展示: 搜索结果分类显示
  • 高亮: 匹配关键词高亮
  • 快捷键: Ctrl+K 聚焦搜索框
  • 匹配: 支持模糊匹配

5.8 优化项设计规范 (v1.2 更新)

优化项 规范
统一配色方案 使用 CSS 设计令牌 (Design Tokens) 管理颜色
过渡动画 卡片展开/收起、状态切换添加缓动动画
加载状态指示 数据加载时显示骨架屏 (Skeleton Screen)
空状态设计 无数据时显示友好提示 + 插画

6. 技术建议

6.1 技术栈推荐

层级 推荐方案
框架 React / Vue 3
状态管理 Zustand / Pinia
样式 Tailwind CSS
图表 自研或 Recharts
构建 Vite

6.2 数据获取

  • 团队数据：读取 /Users/gmy/.claude/teams/*.json
  • 任务数据：读取 /Users/gmy/.claude/tasks/<team-name>/*.json
  • 配置数据：读取 /Users/gmy/.claude/config.json

6.3 实时更新

  • 建议实现文件监听机制 (chokidar)
  • 或提供手动刷新按钮

7. 迭代计划

Phase 1 - MVP (核心功能)

  • 基础项目结构和构建系统
  • 团队列表展示 (F1.1, F1.2)
  • 任务列表展示 (F2.1, F2.2, F2.3)
  • 基础导航 (F3.1, F3.2)

Phase 2 - 增强功能

  • 任务依赖关系可视化 (F2.4)
  • 任务筛选功能 (F2.5)
  • 团队详情面板 (F1.4)
  • 目录结构树 (F4.1)

Phase 3 - 完善体验

  • 搜索功能 (F3.3)
  • 配置文件查看 (F4.2)
  • 历史记录浏览 (F4.3)
  • 响应式优化

8. 成功指标

指标 目标值
页面加载时间 < 2s
数据刷新延迟 < 1s
用户操作响应 < 100ms
支持的团队数量 无限制
支持的任务数量 无限制

9. 风险与依赖

风险 影响 缓解措施
数据格式变更 高 增加版本检测和兼容性处理
大文件加载 中 实现分页和懒加载
跨平台路径差异 中 使用 path 模块处理路径

10. 附录

10.1 术语表

  • Team: Claude Code 团队配置
  • Task: 团队任务项
  • Agent: 团队成员 (子代理)
  • Session: 会话实例

10.2 参考文档

  • .claude 目录结构分析 (需求研究员提供)
  • Claude Code 官方文档

11. 实现状态 (2026-03-02 更新)

11.1 已完成功能 (Phase 1 - MVP ✅)

功能 实现状态 说明
基础项目结构 ✅ 完成 Vue 3 + Vite 前端 + Express 后端
团队列表展示 (F1.1) ✅ 完成 GET /api/teams
成员列表展示 (F1.2) ✅ 完成 状态/模型/prompt/颜色
团队状态指示器 (F1.3) ✅ 完成 isActive 状态
任务卡片展示 (F2.1) ✅ 完成 GET /api/tasks
任务状态标签 (F2.2) ✅ 完成 pending/in_progress/completed
任务所有者展示 (F2.3) ✅ 完成 owner 字段
自动刷新 ✅ 完成 每 5 秒自动更新
系统概览面板 ✅ 完成 统计数据展示

11.2 待实现功能 (Backlog)

优先级 功能 说明
P1 任务筛选功能 (F2.5) 按状态/所有者筛选
P1 任务依赖关系可视化 (F2.4) blocks/blockedBy 图形展示
P2 搜索功能 (F3.3) 团队/任务搜索
P2 目录结构树 (F4.1) .claude 目录浏览
P3 历史记录浏览 (F4.3) history.jsonl 查看

11.3 技术栈 (实际)

层级 技术
前端框架 Vue 3
构建工具 Vite
后端框架 Express
实时更新 文件监听 (chokidar)

11.4 运行地址

11.5 新增功能 (v1.3 更新)

Session 关联展示 - 2026-03-02 上线

功能 实现 状态
Session 关联 API /api/session-team-mapping ✅
Session ID 展示 团队详情区块 ✅
Session 状态指示 空闲/单个团队/多团队 ✅
关联团队列表 多团队关联展示 ✅

产品价值:

  • 追踪 Session 使用情况 - 了解每个 Session 的负载
  • 识别多团队关联 - 快速定位共享 Session 的团队
  • 调试 Session 问题 - 查看空闲或异常 Session

文档版本: 1.3 (已更新 Session 关联功能) 创建日期: 2026-03-02 更新日期: 2026-03-02 文档作者: 产品经理 审核状态: ✅ 已通过