mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-16 13:03:31 +08:00
411 lines
12 KiB
Markdown
411 lines
12 KiB
Markdown
# Claude Code Desktop App — 产品需求文档 (PRD)
|
||
|
||
## 一、项目概述
|
||
|
||
### 1.1 目标
|
||
|
||
复刻 Claude Code Desktop App 的桌面端 GUI 核心功能。聚焦于 **AI 对话交互**、**会话管理**、**定时任务** 和 **Agent Teams 可视化** 四大模块。
|
||
|
||
### 1.2 复刻技术栈
|
||
|
||
- **前端框架**: React 18 + TypeScript
|
||
- **UI 渲染**: 标准浏览器 DOM（替换 Ink 终端渲染）
|
||
- **桌面容器**: Electron 或 Tauri
|
||
- **样式方案**: TailwindCSS v4
|
||
- **状态管理**: Zustand
|
||
|
||
### 1.3 核心原则
|
||
|
||
- **CLI/UI 数据互通**: UI 读写与 CLI 完全相同的 JSONL/JSON 文件
|
||
- **非侵入性**: 不修改原始 CLI 源代码
|
||
- **聚焦核心**: 只做对话 + 会话 + 定时任务 + Agent Teams，不做 Search/Dispatch/Customize
|
||
|
||
---
|
||
|
||
## 二、页面清单
|
||
|
||
| 编号 | 页面 | 描述 | 优先级 |
|
||
|------|------|------|--------|
|
||
| P1 | 顶部标题栏 | macOS 窗口控件 + Code 标签 | P0 |
|
||
| P2 | 左侧边栏 | New session + Scheduled + 项目选择 + 会话列表 | P0 |
|
||
| P3 | 底部状态栏 | 用户信息 + 仓库信息 | P1 |
|
||
| P4 | Code 空状态页 | 吉祥物 + 输入框 | P0 |
|
||
| P5 | Code 活跃会话页 | 消息列表 + 输入区 + 工具调用 + Agent Teams 面板 | P0 |
|
||
| P6 | 权限模式选择器 | Ask/Auto/Plan/Bypass 下拉菜单 | P0 |
|
||
| P7 | 模型选择器 | 模型列表 + Effort 等级 | P0 |
|
||
| P8 | Scheduled 定时任务页 | 任务列表 + 空状态 | P1 |
|
||
| P9 | 新建定时任务模态框 | 创建定时任务表单 | P1 |
|
||
|
||
**已移除**: Search 搜索页、Dispatch 分发页、Customize 设置页（设置直接在输入框控件里完成）
|
||
|
||
---
|
||
|
||
## 三、功能需求
|
||
|
||
### 3.1 顶部标题栏 (P1)
|
||
|
||
- R-001: macOS 红绿灯按钮（关闭/最小化/全屏）
|
||
- R-002: 前进/后退导航箭头
|
||
- R-003: `Code` 标签居中显示（Chat/Cowork 预留位但暂不实现）
|
||
- R-004: 标题栏可拖拽移动窗口
|
||
|
||
---
|
||
|
||
### 3.2 左侧边栏 (P2)
|
||
|
||
#### 导航菜单
|
||
|
||
- R-005: 显示 `+ New session` 和 `Scheduled` 两个导航项
|
||
- R-006: 点击导航项切换主内容区
|
||
- R-007: 当前选中项高亮
|
||
|
||
#### 项目选择器
|
||
|
||
- R-008: `All projects ▾` 下拉选择器
|
||
- R-009: 可选择特定项目过滤会话列表
|
||
|
||
#### 会话列表
|
||
|
||
- R-010: 按时间分组（Today / Previous 7 Days / Older）
|
||
- R-011: 每项显示会话标题（首条消息摘要 或 自定义标题）
|
||
- R-012: 选中会话高亮，左侧圆点指示
|
||
- R-013: 支持搜索过滤
|
||
- R-014: 右键菜单：重命名、删除
|
||
- R-015: 点击切换到对应会话
|
||
|
||
**数据模型**:
|
||
```typescript
|
||
type Session = {
|
||
id: string // UUID v4
|
||
title: string // 首条消息摘要 或 customTitle
|
||
createdAt: Date
|
||
modifiedAt: Date
|
||
messageCount: number
|
||
projectPath: string // 项目目录（sanitized）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 底部状态栏 (P3)
|
||
|
||
- R-016: 用户头像 + 用户名 + 订阅等级（如 `Max plan`）
|
||
- R-017: Git 仓库名 + 分支名
|
||
- R-018: worktree 复选框
|
||
- R-019: Local / Remote 模式切换
|
||
|
||
---
|
||
|
||
### 3.4 Code 空状态页 (P4)
|
||
|
||
- R-020: 居中显示 Clawd 吉祥物（像素风橙色小动物）
|
||
- R-021: 底部输入框，圆角，placeholder 文本
|
||
- R-022: `+` 按钮（添加附件/上下文）
|
||
- R-023: 权限模式选择器（左下）
|
||
- R-024: 模型选择器（右下）
|
||
- R-025: 麦克风图标（语音输入，右侧）
|
||
|
||
---
|
||
|
||
### 3.5 Code 活跃会话页 (P5) — 核心页面
|
||
|
||
#### 3.5.1 会话标题栏
|
||
|
||
- R-026: 会话标题可点击修改
|
||
- R-027: `▷ Preview ▾` 按钮（右上）
|
||
|
||
#### 3.5.2 消息列表
|
||
|
||
- R-028: 用户消息 — 右对齐暖色气泡
|
||
- R-029: AI 文本 — 左对齐，Markdown 富文本
|
||
- R-030: AI 思考 — 可折叠灰色块
|
||
- R-031: 工具调用 — 可折叠块，显示工具名 + 摘要
|
||
- R-032: 系统消息 — 居中灰色
|
||
- R-033: 折叠区段 — `▸ Initialized your session`，内含子工具列表
|
||
- R-034: 上下文压缩分界线
|
||
- R-035: "N new messages" 跳转提示
|
||
|
||
**消息类型**:
|
||
```typescript
|
||
type MessageType =
|
||
| 'user_text' | 'user_image'
|
||
| 'assistant_text' | 'assistant_thinking' | 'assistant_tool_use'
|
||
| 'user_tool_result' | 'system_text' | 'system_error'
|
||
| 'grouped_tool_use' | 'collapsed_section' | 'compact_boundary'
|
||
```
|
||
|
||
#### 3.5.3 Agent Teams 可视化
|
||
|
||
**功能描述**: 当对话中创建 Agent Teams 时，UI 需要展示每个 Team 成员的实时工作状态，等同于 CLI 终端中用 Shift+Up/Down 切换查看各成员 transcript 的体验。
|
||
|
||
- R-036: 底部 Team 状态栏 — 显示活跃的 Team 名称 + 成员数量
|
||
- R-037: 成员标签列表 — 每个 teammate 显示为可点击的标签（名称 + 颜色标识 + 状态指示）
|
||
- R-038: 点击成员标签 → 切换到该成员的 transcript 视图
|
||
- R-039: 成员 transcript 视图 — 独立的消息列表，展示该 agent 的完整对话
|
||
- R-040: 成员状态指示 — `running`（闪烁点）/ `completed`（绿勾）/ `failed`（红叉）
|
||
- R-041: 返回 Leader 视图按钮
|
||
- R-042: 后台任务通知 — 当 teammate 完成时在 Leader 视图中显示 `<task-notification>` 消息
|
||
|
||
**数据模型**:
|
||
```typescript
|
||
type TeamContext = {
|
||
teamName: string
|
||
isLeader: boolean
|
||
teammates: Record<string, {
|
||
name: string
|
||
agentType?: string
|
||
status: 'running' | 'completed' | 'failed' | 'idle'
|
||
color: AgentColor // red | blue | green | yellow | purple | orange | pink | cyan
|
||
messageCount: number
|
||
}>
|
||
}
|
||
|
||
// 视图状态
|
||
expandedView: 'none' | 'tasks' | 'teammates'
|
||
viewingAgentTaskId?: string // 当前正在查看的 teammate transcript
|
||
```
|
||
|
||
**交互流程**:
|
||
```
|
||
Leader 视图（默认）
|
||
├─ 对话中 AI 调用 TeamCreate → 底部出现 Team 状态栏
|
||
├─ Team 成员开始工作 → 各标签显示 running 状态
|
||
├─ 点击成员标签 → 切换到该成员的 transcript
|
||
│ ├─ 显示该 agent 的独立消息流
|
||
│ ├─ 实时更新（工具调用、文本输出）
|
||
│ └─ 点击 "← Back to Leader" 返回
|
||
├─ 成员完成 → 标签变为 completed + Leader 收到 task-notification
|
||
└─ 所有成员完成 → Leader 综合结果
|
||
```
|
||
|
||
**源码参考**:
|
||
- `src/state/AppStateStore.ts` — `expandedView`, `viewingAgentTaskId`, `teamContext`
|
||
- `src/components/TeammateViewHeader.tsx` — 切换队友视图头部
|
||
- `src/components/CoordinatorAgentStatus.tsx` — 协调者状态面板
|
||
- `src/components/tasks/BackgroundTaskStatus.tsx` — 后台任务状态
|
||
- `src/state/selectors.ts` — `getViewedTeammateTask()`, `getActiveAgentForInput()`
|
||
|
||
#### 3.5.4 工具调用展示
|
||
|
||
- R-043: 单个工具调用 — 可折叠块（工具名 + 参数 + 结果）
|
||
- R-044: Agent 子任务 — `Agent 描述` 格式，带 Agent 颜色标识
|
||
- R-045: Bash 命令 — 命令文本高亮 + 可展开输出
|
||
- R-046: 文件编辑 — Diff 结构化展示（绿色添加/红色删除）
|
||
- R-047: 分组工具调用 — 连续同类工具合并为一组
|
||
|
||
#### 3.5.5 实时状态
|
||
|
||
- R-048: `✦ Crafting...` 闪烁动画 + 动态动词
|
||
- R-049: 计时器 + token 计数
|
||
- R-050: 停止生成按钮
|
||
|
||
#### 3.5.6 底部输入区
|
||
|
||
- R-051: 多行文本输入，自动扩展
|
||
- R-052: `+` 添加附件
|
||
- R-053: 权限模式指示器
|
||
- R-054: 模型选择器
|
||
- R-055: 停止按钮（AI 运行中）
|
||
|
||
---
|
||
|
||
### 3.6 权限模式选择器 (P6)
|
||
|
||
- R-056: 4 个选项的下拉菜单
|
||
- R-057: 每项显示图标 + 名称 + 描述
|
||
- R-058: 选中项 ✓ 标记
|
||
- R-059: 切换即时生效
|
||
|
||
| 选项 | 图标 | 描述 |
|
||
|------|------|------|
|
||
| Ask permissions | ⚙ | Always ask before making changes |
|
||
| Auto accept edits | `</>` | Automatically accept all file edits |
|
||
| Plan mode | 📋 | Create a plan before making changes |
|
||
| Bypass permissions | ⚠ | Accepts all permissions |
|
||
|
||
---
|
||
|
||
### 3.7 模型选择器 (P7)
|
||
|
||
- R-060: 模型列表（上部）+ Effort 等级（下部，分隔线分割）
|
||
- R-061: 模型 — 名称 + 描述 + ✓ 选中
|
||
- R-062: Effort — Low / Medium / High / Max + ✓ 选中
|
||
|
||
| 模型 | 描述 |
|
||
|------|------|
|
||
| Opus 4.7 | Most capable for ambitious work |
|
||
| Opus 4.7 1M | Most capable for ambitious work |
|
||
| Sonnet 4.6 | Most efficient for everyday tasks |
|
||
| Haiku 4.5 | Fastest for quick answers |
|
||
|
||
---
|
||
|
||
### 3.8 Scheduled 定时任务页 (P8)
|
||
|
||
- R-063: 页面标题 `Scheduled tasks`
|
||
- R-064: 空状态：时钟图标 + `No scheduled tasks yet.`
|
||
- R-065: `+ New task` 按钮（右上）
|
||
- R-066: 任务列表：名称 + 描述 + 频率 + 下次执行
|
||
- R-067: 每项支持编辑、删除
|
||
|
||
---
|
||
|
||
### 3.9 新建定时任务模态框 (P9)
|
||
|
||
- R-068: Info 横幅: `Local tasks only run while your computer is awake.`
|
||
- R-069: Name（必填）+ Description（必填）
|
||
- R-070: Prompt 多行输入
|
||
- R-071: Permissions + Model 选择器
|
||
- R-072: Select folder + worktree 复选框
|
||
- R-073: Frequency 下拉 + Time 时间选择
|
||
- R-074: Cancel / Create task 按钮
|
||
|
||
---
|
||
|
||
## 四、交互组件
|
||
|
||
### 4.1 权限请求对话框
|
||
|
||
- R-075: Bash 命令 — 显示命令内容
|
||
- R-076: 文件编辑 — 显示 diff
|
||
- R-077: 文件写入 — 显示路径
|
||
- R-078: 操作按钮：允许 / 拒绝 / 总是允许 / 总是拒绝
|
||
|
||
### 4.2 Markdown 渲染
|
||
|
||
- R-079: 标题、列表、粗体/斜体
|
||
- R-080: 代码块语法高亮
|
||
- R-081: 表格
|
||
- R-082: 文件路径可点击
|
||
|
||
### 4.3 Diff 展示
|
||
|
||
- R-083: 添加行绿色 / 删除行红色
|
||
- R-084: 行号 + 文件路径头部
|
||
- R-085: Word-level diff 高亮
|
||
|
||
### 4.4 通知
|
||
|
||
- R-086: Toast 通知（成功/错误/警告）
|
||
- R-087: 自动消失 + 队列
|
||
|
||
### 4.5 通用对话框
|
||
|
||
- R-088: 标题 + 内容 + 按钮
|
||
- R-089: ESC 关闭
|
||
|
||
---
|
||
|
||
## 五、数据模型
|
||
|
||
### 5.1 全局状态 (AppState)
|
||
|
||
```typescript
|
||
type AppState = {
|
||
// 模型
|
||
mainLoopModel: string | null
|
||
effort: 'low' | 'medium' | 'high' | 'max'
|
||
permissionMode: PermissionMode
|
||
|
||
// 视图
|
||
expandedView: 'none' | 'tasks' | 'teammates'
|
||
viewingAgentTaskId?: string
|
||
|
||
// 任务
|
||
tasks: Record<string, TaskState>
|
||
foregroundedTaskId?: string
|
||
|
||
// 团队
|
||
teamContext?: TeamContext
|
||
|
||
// 通知
|
||
notifications: { current: Notification | null; queue: Notification[] }
|
||
}
|
||
```
|
||
|
||
### 5.2 消息模型
|
||
|
||
```typescript
|
||
type Message = {
|
||
id: string
|
||
role: 'user' | 'assistant' | 'system'
|
||
content: ContentBlock[]
|
||
timestamp: number
|
||
model?: string
|
||
}
|
||
|
||
type ContentBlock =
|
||
| { type: 'text'; text: string }
|
||
| { type: 'image'; source: ImageSource }
|
||
| { type: 'tool_use'; id: string; name: string; input: any }
|
||
| { type: 'tool_result'; tool_use_id: string; content: any }
|
||
| { type: 'thinking'; thinking: string }
|
||
```
|
||
|
||
---
|
||
|
||
## 六、导航模型
|
||
|
||
状态驱动（非 URL 路由）:
|
||
|
||
```
|
||
侧边栏: + New session → Code 空状态
|
||
Scheduled → 定时任务页
|
||
会话列表项 → Code 活跃会话页
|
||
↓
|
||
expandedView = 'teammates' → Agent Teams 面板
|
||
viewingAgentTaskId → 切换到某个 teammate 的 transcript
|
||
```
|
||
|
||
---
|
||
|
||
## 七、实施路线图
|
||
|
||
### Phase 1: 基础框架
|
||
1. 项目脚手架 + 主题系统
|
||
2. 设计系统组件（Dialog, Select, Button）
|
||
3. App Shell 布局（标题栏 + 侧边栏 + 状态栏）
|
||
4. 全局状态管理
|
||
|
||
### Phase 2: 核心对话
|
||
5. Code 空状态页
|
||
6. 输入区域（文本 + 选择器）
|
||
7. 消息列表（用户 + AI 文本）
|
||
8. 权限 / 模型选择器
|
||
9. 加载状态
|
||
|
||
### Phase 3: 高级渲染
|
||
10. Markdown + 代码高亮
|
||
11. 工具调用展示
|
||
12. Diff 展示
|
||
13. 权限请求对话框
|
||
|
||
### Phase 4: Agent Teams
|
||
14. Team 状态栏 + 成员标签
|
||
15. Teammate transcript 视图切换
|
||
16. 后台任务通知
|
||
|
||
### Phase 5: 定时任务
|
||
17. Scheduled 页面 + 新建模态框
|
||
|
||
---
|
||
|
||
## 八、关键源码索引
|
||
|
||
| 功能 | 路径 |
|
||
|------|------|
|
||
| 全局状态 | `src/state/AppStateStore.ts` |
|
||
| 主屏幕 | `src/screens/REPL.tsx` |
|
||
| 布局 | `src/components/FullscreenLayout.tsx` |
|
||
| 输入 | `src/components/PromptInput/PromptInput.tsx` |
|
||
| 消息 | `src/components/Message.tsx`, `src/components/messages/` |
|
||
| 权限类型 | `src/types/permissions.ts` |
|
||
| 模型选择 | `src/components/ModelPicker.tsx` |
|
||
| 主题 | `src/utils/theme.ts` |
|
||
| 定时任务 | `src/utils/cronTasks.ts` |
|
||
| Agent Teams | `src/components/TeammateViewHeader.tsx`, `src/components/CoordinatorAgentStatus.tsx` |
|
||
| 后台任务 | `src/components/tasks/BackgroundTaskStatus.tsx` |
|
||
| Diff | `src/components/StructuredDiff.tsx` |
|
||
| 会话管理 | `src/components/LogSelector.tsx` |
|
||
| 服务端 API | `src/server/` |
|