sdaduanbilei/cc-haha

Fork 0

mirror of https://github.com/NanmiCoder/cc-haha synced 2026-07-16 13:03:31 +08:00

程序员阿江(Relakkes) 20806f406f chore: update cluade model name

2026-04-18 20:34:56 +08:00

12 KiB

Raw Permalink Blame History

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.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)

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: 基础框架

项目脚手架 + 主题系统
设计系统组件（Dialog, Select, Button）
App Shell 布局（标题栏 + 侧边栏 + 状态栏）
全局状态管理

Phase 2: 核心对话

Code 空状态页
输入区域（文本 + 选择器）
消息列表（用户 + AI 文本）
权限 / 模型选择器
加载状态

Phase 3: 高级渲染

Markdown + 代码高亮
工具调用展示
Diff 展示
权限请求对话框

Phase 4: Agent Teams

Team 状态栏 + 成员标签
Teammate transcript 视图切换
后台任务通知

Phase 5: 定时任务

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/`

12 KiB Raw Permalink Blame History Unescape Escape