摘要终端界面虽然高效但不是所有开发者都喜欢黑屏白字。cc-haha 的桌面端基于 Tauri 2 和 React 构建将 AI 编程助手的能力封装到一个现代化的图形界面中。本文深入解析三层架构设计、WebSocket 实时通信、12 个 Zustand Store 的状态管理以及从开发到打包的完整流程。一、为什么需要桌面端CLI 终端界面TUI虽然轻量高效但存在明显的用户体验瓶颈历史会话浏览困难终端里翻找昨天的对话很麻烦代码 Diff 展示受限终端里的 diff 不如图形界面直观权限确认打断心流弹出的终端对话框容易让人手忙脚乱多项目切换不友好每次切换都要重新 cd 到项目目录cc-haha 的桌面端把会话管理、代码 Diff、权限确认、提供商配置、定时任务和 IM 适配器集中到一个图形化工作台里。CLI TUI 模式适合: 终端爱好者适合: 快速任务适合: 低资源环境Desktop GUI 模式适合: 日常开发适合: 多项目管理适合: 可视化需求适合: 非技术用户二、三层架构设计桌面端不是简单的套壳网页而是一个完整的三层架构应用渲染错误:Mermaid 渲染失败: Parse error on line 26: ... --|ws://127.0.0.1:{port}| S2 S1 -- -----------------------^ Expecting SQE, DOUBLECIRCLEEND, PE, -), STADIUMEND, SUBROUTINEEND, PIPE, CYLINDEREND, DIAMOND_STOP, TAGEND, TRAPEND, INVTRAPEND, UNICODE_TEXT, TEXT, TAGSTART, got DIAMOND_START2.1 第一层Tauri 主进程Rust职责窗口管理、Sidecar 进程编排、原生 API 桥接。核心文件desktop/src-tauri/src/lib.rs只暴露两个 CommandCommand说明get_server_url前端获取 Server Sidecar 的 HTTP 地址restart_adapters_sidecar热重启 Adapter Sidecar启动流程Adapter SidecarWebViewServer SidecarTauri 主进程Adapter SidecarWebViewServer SidecarTauri 主进程绑定 127.0.0.1:0获取 OS 随机端口TCP 探活轮询150ms 间隔 10s 超时注入 ADAPTER_SERVER_URLreserve_local_port()start_server_sidecar(port)wait_for_server()加载 React 应用GET /health200 OKstart_adapters_sidecar()2.2 第二层Server SidecarBun职责HTTP REST API WebSocket 网关 会话管理 协议代理。src/server/ ├── index.ts # 入口 ├── server.ts # HTTP 服务器 (Bun.serve) ├── router.ts # 路由注册 ├── sessionManager.ts # 会话管理器 ├── api/ # REST 路由层 (14 个模块) ├── services/ # 业务服务层 (14 个模块) ├── ws/ # WebSocket 处理 ├── proxy/ # API 协议代理转换 ├── middleware/ # auth、cors、errorHandler └── config/ # Provider 预设2.3 第三层CLI 子进程职责AI 对话核心、工具执行、Agent 编排。Server 为每个 Session spawn 一个 CLI 子进程通过stdin/stdout JSON 通信。三、状态管理12 个 Zustand Store桌面端使用 Zustand 按领域拆分为 12 个 Store18%14%10%10%10%8%8%8%5%5%2%2%Zustand Store 分布chatStoresessionStoresettingsStoreproviderStoreuiStoretabStoretaskStoreteamStoreagentStoreskillStoreadapterStorecliTaskStore3.1 核心 Store 详解Store核心状态持久化chatStoreper-session 消息、流式状态、权限请求Server JSONLsessionStore会话列表、activeSessionId、项目筛选Server JSONLtabStore标签页顺序localStoragesettingsStore权限模式、当前模型、effort、语言Server APIproviderStoreProvider 列表、activeIdServer APItaskStore定时任务、运行记录Server API3.2 chatStore 的多会话隔离设计// 关键设计RecordsessionId, StateinterfaceChatState{sessions:Recordstring,SessionChatactiveSessionId:string|null}interfaceSessionChat{messages:Message[]isStreaming:booleanpendingPermissions:PermissionRequest[]tokenStats:TokenStats}这种设计确保切换标签页时各会话的状态完全隔离不会出现消息串台。3.3 数据流用户操作 → Component → Store → API/WebSocket → Server → Store → Component 重渲染四、WebSocket 实时通信4.1 协议设计客户端 → 服务端user_messagepermission_responseset_permission_modestop_generationping服务端 → 客户端connectedcontent_start/deltathinkingtool_use_completepermission_requestmessage_completeerror4.2 连接管理// WebSocket 管理器核心逻辑classWebSocketManager{privatews:WebSocket|nullnullprivatereconnectCount0privatemessageQueue:Message[][]connect(sessionId:string){this.wsnewWebSocket(ws://127.0.0.1:${port}/ws/${sessionId})this.ws.onopen(){this.reconnectCount0this.flushQueue()this.startHeartbeat()}this.ws.onclose(){constdelayMath.min(1000*2**this.reconnectCount,30000)setTimeout(()this.connect(sessionId),delay)this.reconnectCount}}send(message:Message){if(this.ws?.readyStateWebSocket.OPEN){this.ws.send(JSON.stringify(message))}else{this.messageQueue.push(message)// 离线缓冲}}}五、HTTP API 一览5.1 会话管理方法端点说明GET/api/sessions列表支持 project/limit/offset 筛选POST/api/sessions创建GET/api/sessions/:id/messages历史消息DELETE/api/sessions/:id删除5.2 模型与提供商方法端点说明GET/PUT/api/models/current当前模型GET/api/models可用模型列表CRUD/api/providers提供商管理POST/api/providers/:id/test测试连接5.3 其他方法端点说明CRUD/api/scheduled-tasks定时任务GET/api/teamsAgent 团队GET/PUT/api/adaptersIM 适配器配置GET/health健康检查六、协议代理层Server 内置代理层统一不同 AI 提供商的 API 格式格式典型提供商anthropicAnthropic、OpenRouter、MiniMaxopenai_chatOpenAI、DeepSeek、Ollama、通义千问openai_responsesOpenAI Responses API每个 Provider 配置 4 个模型槽位main、haiku、sonnet、opus前端按槽位名调用代理层自动映射为实际模型名。七、开发到打包的完整流程7.1 开发环境启动# 终端 1启动 Server SidecarSERVER_PORT3456bun run src/server/index.ts# 终端 2启动桌面前端cddesktopbun run dev--host127.0.0.1--port2024# 浏览器打开openhttp://127.0.0.1:20247.2 构建 Sidecarcddesktop bun run build:sidecars# 输出到 desktop/src-tauri/binaries/# 包含claude-sidecar-server# claude-sidecar-cli# claude-sidecar-adapters7.3 Tauri 打包cddesktop/src-tauricargotauri build# 输出# - macOS: desktop/src-tauri/target/release/bundle/# - Windows: desktop/src-tauri/target/release/bundle/7.4 平台差异处理// desktop/src-tauri/src/lib.rs 中的平台差异#[cfg(target_os macos)]fnsetup_window(app:mutApp){// macOS: overlay titlebar 自定义菜单set_overlay_titlebar(true);setup_macos_menu();}#[cfg(target_os windows)]fnsetup_window(app:mutApp){// Windows: 隐藏原生标题栏前端自定义渲染window.set_decorations(false);// 前端渲染 TitleBar WindowControls}八、前端技术栈技术版本职责React18UI 框架Zustand5状态管理Vite6构建工具Tailwind CSS4样式Shiki4代码高亮Mermaid11图表渲染marked DOMPurify-Markdown 渲染react-diff-viewer4Diff 展示总结cc-haha 的桌面端是一个现代化的跨平台桌面应用三层架构Tauri 主进程 → Server Sidecar → CLI 子进程层层隔离12 个 Zustand Store按领域拆分chatStore 采用RecordsessionId, State实现多会话隔离WebSocket 实时通信支持自动重连、心跳保活、消息队列缓冲协议代理层统一 anthropic/openai_chat/openai_responses 三种格式Sidecar 模式Server 和 Adapter 作为独立进程确保稳定性开发建议修改前端代码后不需要重启 ServerVite HMR 自动刷新测试 IM 适配器时建议新建 session 并选择真实存在的工作目录如果 3456 端口被占用先lsof -iTCP:3456找到旧进程并 kill参考资料cc-haha 桌面端快速上手cc-haha 桌面端架构设计Tauri 2 官方文档Zustand 状态管理Bun.serve HTTP/WebSocket从终端到图形界面cc-haha 的桌面端不是对 CLI 的替代而是对使用场景的补充。喜欢终端的继续用 TUI需要可视化管理的打开桌面端——选择权在用户手中。