cc-haha/docs/ui-clone/01-requirements.md

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: 点击切换到对应会话

数据模型:

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" 跳转提示

消息类型:

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> 消息

数据模型:

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.6	Most capable for ambitious work
Opus 4.6 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)

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 消息模型

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/