From 870e03d88bfd055b6c6ff35f468181e19014b259 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E5=91=98=E9=98=BF=E6=B1=9F=28Relakkes?=
=?UTF-8?q?=29?=
Date: Thu, 16 Apr 2026 10:25:36 +0800
Subject: [PATCH] =?UTF-8?q?docs(desktop):=20=E5=85=A8=E9=9D=A2=E6=9B=B4?=
=?UTF-8?q?=E6=96=B0=E6=A1=8C=E9=9D=A2=E7=AB=AF=E6=96=87=E6=A1=A3=EF=BC=8C?=
=?UTF-8?q?=E6=9B=BF=E6=8D=A2=E7=9C=9F=E5=AE=9E=E6=88=AA=E5=9B=BE=EF=BC=8C?=
=?UTF-8?q?=E4=BF=AE=E5=A4=8D=20DMG=20=E5=B8=83=E5=B1=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 重写 02-architecture.md:修正 Rust 函数签名、补充 AdapterSidecar/Updater 插件、更新目录结构
- 重写 03-features.md:补充 ComputerUse/ToolInspection/ImageGallery 等新组件和页面
- 精简 04-installation.md:仅保留 macOS/Windows,新增 Web UI 模式说明
- 精简 index.md:移除过时配图说明表格
- 删除 8 张 AI 渲染概念图,替换为 9 张真实应用截图
- 新增 desktop/README.md:开发/构建指南 + macOS 常见问题
- 修复 DMG 构建脚本:通过 AppleScript 控制图标布局(App 左/Applications 右)
Co-Authored-By: Claude Opus 4.6 (1M context)
---
desktop/README.md | 30 +
desktop/scripts/build-macos-arm64.sh | 44 +-
docs/desktop/01-quick-start.md | 10 +-
docs/desktop/02-architecture.md | 931 +++++-------------
docs/desktop/03-features.md | 795 +++------------
docs/desktop/04-installation.md | 355 +------
docs/desktop/images/01-desktop-overview.png | Bin 712004 -> 0 bytes
docs/desktop/images/02-tech-stack.png | Bin 787808 -> 0 bytes
docs/desktop/images/03-three-layer-arch.png | Bin 769764 -> 0 bytes
docs/desktop/images/04-websocket-protocol.png | Bin 728041 -> 0 bytes
docs/desktop/images/05-session-lifecycle.png | Bin 464768 -> 0 bytes
docs/desktop/images/06-features-grid.png | Bin 722629 -> 0 bytes
docs/desktop/images/07-adapter-bridge.png | Bin 989139 -> 0 bytes
docs/desktop/images/08-chat-message-flow.png | Bin 155085 -> 0 bytes
docs/desktop/index.md | 130 +--
docs/images/desktop_ui/01_full_ui.png | Bin 0 -> 345258 bytes
.../03_ask_question_and_permission.png | Bin 0 -> 474994 bytes
docs/images/desktop_ui/04_tasktodo_list.png | Bin 0 -> 476070 bytes
docs/images/desktop_ui/05_settings.png | Bin 0 -> 456782 bytes
.../desktop_ui/06_settings_computer_use.png | Bin 0 -> 459070 bytes
docs/images/desktop_ui/07_im.png | Bin 0 -> 446048 bytes
docs/images/desktop_ui/08_scheduled_task.png | Bin 0 -> 431277 bytes
docs/images/desktop_ui/09_file_search.png | Bin 0 -> 443407 bytes
docs/images/desktop_ui/09_slash_command.png | Bin 0 -> 474485 bytes
24 files changed, 530 insertions(+), 1765 deletions(-)
create mode 100644 desktop/README.md
delete mode 100644 docs/desktop/images/01-desktop-overview.png
delete mode 100644 docs/desktop/images/02-tech-stack.png
delete mode 100644 docs/desktop/images/03-three-layer-arch.png
delete mode 100644 docs/desktop/images/04-websocket-protocol.png
delete mode 100644 docs/desktop/images/05-session-lifecycle.png
delete mode 100644 docs/desktop/images/06-features-grid.png
delete mode 100644 docs/desktop/images/07-adapter-bridge.png
delete mode 100644 docs/desktop/images/08-chat-message-flow.png
create mode 100644 docs/images/desktop_ui/01_full_ui.png
create mode 100644 docs/images/desktop_ui/03_ask_question_and_permission.png
create mode 100644 docs/images/desktop_ui/04_tasktodo_list.png
create mode 100644 docs/images/desktop_ui/05_settings.png
create mode 100644 docs/images/desktop_ui/06_settings_computer_use.png
create mode 100644 docs/images/desktop_ui/07_im.png
create mode 100644 docs/images/desktop_ui/08_scheduled_task.png
create mode 100644 docs/images/desktop_ui/09_file_search.png
create mode 100644 docs/images/desktop_ui/09_slash_command.png
diff --git a/desktop/README.md b/desktop/README.md
new file mode 100644
index 00000000..eeb617ba
--- /dev/null
+++ b/desktop/README.md
@@ -0,0 +1,30 @@
+# Claude Code Haha Desktop
+
+基于 Tauri 2 + React 的桌面客户端。
+
+## 开发
+
+```bash
+bun install
+bun run tauri dev
+```
+
+## 构建
+
+```bash
+# macOS (Apple Silicon)
+./scripts/build-macos-arm64.sh
+
+# Windows (x64)
+.\scripts\build-windows-x64.ps1
+```
+
+构建产物位于 `build-artifacts/` 目录。
+
+## 常见问题
+
+### macOS 提示"已损坏,无法打开"
+
+```bash
+xattr -cr /Applications/Claude\ Code\ Haha.app
+```
diff --git a/desktop/scripts/build-macos-arm64.sh b/desktop/scripts/build-macos-arm64.sh
index ee211a25..b4773dfb 100755
--- a/desktop/scripts/build-macos-arm64.sh
+++ b/desktop/scripts/build-macos-arm64.sh
@@ -137,19 +137,59 @@ build_canonical_dmg() {
local app_bundle="$1"
local dmg_output="$2"
local staging_dir
+ local rw_dmg
staging_dir="$(mktemp -d "${TMPDIR:-/tmp}/cc-haha-dmg.XXXXXX")"
+ rw_dmg="$(mktemp "${TMPDIR:-/tmp}/cc-haha-rw.XXXXXX").dmg"
+
cp -R "${app_bundle}" "${staging_dir}/"
ln -s /Applications "${staging_dir}/Applications"
+ # Create a read-write DMG first so we can customize the Finder layout
hdiutil create \
-volname "Claude Code Haha" \
-srcfolder "${staging_dir}" \
-ov \
- -format UDZO \
- "${dmg_output}" >/dev/null
+ -format UDRW \
+ "${rw_dmg}" >/dev/null
rm -rf "${staging_dir}"
+
+ # Mount the read-write DMG and apply Finder layout via AppleScript
+ local dev_name mount_dir
+ dev_name=$(hdiutil attach -readwrite -noverify -noautoopen -nobrowse "${rw_dmg}" \
+ | grep -E '^/dev/' | head -1 | awk '{print $1}')
+ mount_dir=$(hdiutil info | grep -E "${dev_name}" | tail -1 | awk '{$1=$2=""; print}' | xargs)
+
+ # Use AppleScript to set icon positions and window size
+ osascript </dev/null
+ rm -f "${rw_dmg}"
}
if [[ -n "${LATEST_DMG}" ]]; then
diff --git a/docs/desktop/01-quick-start.md b/docs/desktop/01-quick-start.md
index 597c472a..4e46bd94 100644
--- a/docs/desktop/01-quick-start.md
+++ b/docs/desktop/01-quick-start.md
@@ -6,12 +6,12 @@
界面布局 · 对话操作 · 多标签系统 · 权限控制 · 项目管理 · 模型与提供商 · IM 适配器 · 定时任务
-
-
---
## 一、界面布局
+
+
桌面端采用**三栏 + 标签页**的经典 IDE 布局,从左到右分为:
| 区域 | 位置 | 功能 |
@@ -72,6 +72,8 @@
### 斜杠命令
+
+
输入 `/` 触发命令自动补全菜单:
```
@@ -89,6 +91,8 @@
### @ 文件引用
+
+
输入 `@` 触发文件搜索菜单,快速将文件引入对话上下文:
- 支持路径和文件名自动补全
@@ -168,6 +172,8 @@ AI 回复时实时流式展示,支持:
## 四、权限控制
+
+
Claude Code 在执行文件修改、Shell 命令等操作前,会请求你的权限。
### 权限请求对话框
diff --git a/docs/desktop/02-architecture.md b/docs/desktop/02-architecture.md
index 7cbdd096..7e318966 100644
--- a/docs/desktop/02-architecture.md
+++ b/docs/desktop/02-architecture.md
@@ -1,834 +1,379 @@
-# Claude Code 桌面端 — 架构设计
+# 架构设计
-> 从 Tauri 窗口到 CLI 子进程,深入理解桌面端的三层通信架构。
-
-
-技术栈 · 三层架构 · WebSocket 协议 · HTTP API · 状态管理 · 会话生命周期 · 协议转换 · 适配器架构
-
-
-
+> 从 Tauri 窗口到 CLI 子进程,桌面端的三层通信架构。
---
-## 一、技术栈全景
+## 技术栈
-Claude Code 桌面端的技术选型强调**轻量、高性能、跨平台**:
-
-### 前端层
+### 前端
| 技术 | 版本 | 职责 |
|------|------|------|
-| **React** | 18.3.1 | UI 框架,函数式组件 + Hooks |
-| **Zustand** | 5.0.3 | 轻量级状态管理,零样板代码 |
-| **Vite** | 6.0.7 | 构建工具,HMR 热更新 |
-| **Tailwind CSS** | 4.0 | 原子化样式框架 |
-| **Shiki** | 4.0.2 | VS Code 级别代码语法高亮 |
-| **react-diff-viewer** | 4.2.0 | Diff 变更展示 |
-| **marked** | 15.0.7 | Markdown 解析渲染 |
+| React | 18 | UI 框架 |
+| Zustand | 5 | 状态管理 |
+| Vite | 6 | 构建工具 |
+| Tailwind CSS | 4 | 样式 |
+| Shiki | 4 | 代码高亮 |
+| Mermaid | 11 | 图表渲染 |
+| marked + DOMPurify | - | Markdown 渲染 |
+| react-diff-viewer | 4 | Diff 展示 |
+| Lucide React | - | 图标 |
### 桌面层
| 技术 | 版本 | 职责 |
|------|------|------|
-| **Tauri** | 2.x | 跨平台桌面框架(Rust) |
-| **tauri-plugin-shell** | 2.x | Sidecar 进程管理 |
-| **tauri-plugin-dialog** | 2.x | 原生文件选择对话框 |
-| **tauri-plugin-process** | 2.x | 进程生命周期管理 |
+| Tauri | 2 | 跨平台桌面框架 (Rust) |
+| tauri-plugin-shell | 2 | Sidecar 进程管理 |
+| tauri-plugin-dialog | 2 | 原生对话框 |
+| tauri-plugin-process | 2 | 进程生命周期 |
+| tauri-plugin-updater | 2 | 自动更新 |
-### 服务端层
+### 服务端
| 技术 | 职责 |
|------|------|
-| **Bun** | JavaScript/TypeScript 运行时 + 构建工具 |
-| **Bun.serve** | HTTP/WebSocket 服务器 |
-| **Zod** | 请求参数校验 |
+| Bun | 运行时 + 构建工具 |
+| Bun.serve | HTTP/WebSocket 服务器 |
-### 字体系统
+### 字体
-桌面端自托管所有字体,无需 CDN 依赖:
-
-- **Inter** (400-600) — 正文
-- **Manrope** (400-800) — 标题
+- **Inter** — 正文
+- **Manrope** — 标题
- **JetBrains Mono** — 代码
- **Material Symbols Outlined** — 图标
---
-## 二、三层架构
-
-
-
-桌面端采用**三层架构**设计,各层职责明确:
+## 三层架构
```
-┌─────────────────────────────────┐
-│ Tauri 主进程 (Rust) │
-│ ┌───────────────────────────┐ │
-│ │ WebView (React App) │ │ ← 用户看到的界面
-│ │ Port 1420 (开发) / 内置 │ │
-│ └───────────┬───────────────┘ │
-│ │ HTTP + WebSocket │
-│ ┌───────────▼───────────────┐ │
-│ │ Sidecar: claude-server │ │ ← Bun 编译的服务端二进制
-│ │ Port: 动态分配 │ │
-│ └───────────┬───────────────┘ │
-│ │ 子进程 spawn │
-│ ┌───────────▼───────────────┐ │
-│ │ CLI 子进程 (claude-cli) │ │ ← 实际执行 AI 对话和工具调用
-│ │ stdin/stdout 通信 │ │
-│ └───────────────────────────┘ │
-└─────────────────────────────────┘
+┌─────────────────────────────────────┐
+│ Tauri 主进程 (Rust) │
+│ ┌─────────────────────────────┐ │
+│ │ WebView (React App) │ │ ← 用户界面
+│ └───────────┬─────────────────┘ │
+│ │ HTTP + WebSocket │
+│ ┌───────────▼─────────────────┐ │
+│ │ Server Sidecar (Bun) │ │ ← API 服务 + 会话管理
+│ │ Port: 动态分配 │ │
+│ └───────────┬─────────────────┘ │
+│ │ 子进程 spawn │
+│ ┌───────────▼─────────────────┐ │
+│ │ CLI 子进程 │ │ ← AI 对话 + 工具执行
+│ └─────────────────────────────┘ │
+│ │
+│ ┌─────────────────────────────┐ │
+│ │ Adapter Sidecar (可选) │ │ ← Telegram/飞书接入
+│ └─────────────────────────────┘ │
+└─────────────────────────────────────┘
```
### 第一层:Tauri 主进程
-**职责**:窗口管理、进程编排、原生 API 桥接
+**职责**:窗口管理、Sidecar 进程编排、原生 API 桥接
-关键文件:`desktop/src-tauri/src/lib.rs`
+核心文件 `desktop/src-tauri/src/lib.rs`,暴露两个 Tauri Command:
-```rust
-// 核心功能
-fn reserve_local_port() -> u16 // 获取空闲端口
-fn wait_for_server(port) -> bool // 等待服务就绪(超时 10 秒)
-fn start_server_sidecar(port) // 启动 Server 后台进程
-fn stop_server_sidecar() // 停止 Server 后台进程
+| Command | 说明 |
+|---------|------|
+| `get_server_url` | 前端获取 Server Sidecar 的 HTTP 地址 |
+| `restart_adapters_sidecar` | 热重启 Adapter Sidecar(修改配置后生效) |
-// Tauri 命令(暴露给前端调用)
-#[tauri::command]
-fn get_server_url() -> String // 返回 http://127.0.0.1:{port}
-```
+**状态管理**:
-启动流程:
-1. Tauri 主进程启动
-2. 调用 `reserve_local_port()` 获取空闲端口
-3. 启动 `claude-server` sidecar 进程,传入端口号
-4. 调用 `wait_for_server()` 轮询等待服务就绪
-5. WebView 加载 React 应用
-6. 前端调用 `get_server_url` 获取服务地址
+| Struct | 说明 |
+|--------|------|
+| `ServerState` | `Mutex` — 含 server URL 和 Child 进程 handle |
+| `AdapterState` | `Mutex