File size: 6,905 Bytes
eeeb2b6 96f34e3 eeeb2b6 9685a3e eeeb2b6 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | # 桌面 HTTP/WebSocket 服务器
## 概述
Codev 桌面服务器是一个同进程 HTTP + WebSocket 服务器，基于 **Bun.serve()** 运行，为 Tauri 桌面应用提供全套 API 接口。服务器与 CLI 子进程通过 SDK WebSocket Bridge 通信，桌面 UI 通过客户端 WebSocket 与服务器交互。
- **入口文件**: `src/server/server.ts`
- **运行时**: Bun (JavaScript/TypeScript 运行时)
- **默认端口**: 3456
- **架构**: 单进程，HTTP + WebSocket 共存
## 路由系统
路由定义在 `src/server/router.ts`。所有 API 请求统一由 `handleApiRequest()` 函数处理，根据 URL 路径第二段（resource）分发到对应的 API handler。
当前支持约 **28 个 API 资源路径**，每个 handler 部署在 `src/server/api/` 目录下独立的文件中。
## API 端点
### 会话管理
| 路径 | 描述 |
|------|------|
| `/api/sessions` | 会话 CRUD — 创建、读取、更新、删除会话 |
| `/api/sessions/:id/chat/*` | 会话内的对话操作（由 conversations handler 处理） |
对应文件: `api/sessions.ts`
### 对话管理
| 路径 | 描述 |
|------|------|
| `/api/conversations` | 对话 CRUD — 会话消息的读写管理 |
对应文件: `api/conversations.ts`
### 模型配置
| 路径 | 描述 |
|------|------|
| `/api/models` | 获取可用模型列表 |
| `/api/models/current` | 获取/切换当前选中的模型 |
| `/api/effort` | 获取/设置 Effort 等级（low / medium / high / max） |
对应文件: `api/models.ts`
### 设置与权限
| 路径 | 描述 |
|------|------|
| `/api/settings` | 应用设置读写 |
| `/api/permissions` | 权限配置（由 settings handler 处理） |
对应文件: `api/settings.ts`
### MCP
| 路径 | 描述 |
|------|------|
| `/api/mcp` | MCP 服务器管理 — 连接配置与状态 |
对应文件: `api/mcp.ts`
### 插件与技能
| 路径 | 描述 |
|------|------|
| `/api/plugins` | 插件管理 — 安装、卸载、更新、启用/禁用 |
| `/api/skills` | 技能管理 |
对应文件: `api/plugins.ts`, `api/skills.ts`
### 诊断
| 路径 | 描述 |
|------|------|
| `/api/doctor` | 环境诊断 — 检查系统配置是否正常 |
| `/api/diagnostics` | 诊断事件记录与查询 |
对应文件: `api/doctor.ts`, `api/diagnostics.ts`
### 好友系统
| 路径 | 描述 |
|------|------|
| `/api/friend` | VRM 虚拟形象前端路由（由 Tauri 桌面应用调用），包含 TTS/STT、SSE、偏好设置等 |
路由定义在单独模块中（非 router.ts 直接管理），对应文件: `api/friend.ts`
### 文件与工作区
| 路径 | 描述 |
|------|------|
| `/api/filesystem` | 文件系统访问操作 |
| `/api/workspaces` | Git 工作区管理（会话工作区创建、差异查看等） |
对应文件: `api/filesystem.ts`（filesystem 由专用路由函数处理）
### 其他端点
| 路径 | 描述 |
|------|------|
| `/api/scheduled-tasks` | 定时任务管理 |
| `/api/search` | 搜索 |
| `/api/agents` / `/api/tasks` | Agent 任务管理 |
| `/api/status` | 服务器状态查询 |
| `/api/teams` | 团队配置 |
| `/api/providers` | Provider 提供商配置 |
| `/api/adapters` | 适配器管理 |
| `/api/computer-use` | [Computer Use 功能控制](computer-use.md) — 环境检测、Python venv 安装、桌面控制 |
| `/api/haha-oauth` | haha 自定义 OAuth 认证 |
| `/api/haha-openai-oauth` | haha OpenAI OAuth 认证 |
| `/api/h5-access` | H5 访问策略 |
| `/api/activity-stats` | 活动统计 |
| `/api/open-targets` | OpenTarget 管理 |
| `/api/memory` | 记忆管理 |
| `/api/desktop-ui` | 桌面 UI 偏好 |
| `/api/cli-auth` | CLI 认证 |
| `/api/cli-proxy` | CLI 代理 |
## WebSocket
**文件**: `ws/handler.ts` (约 68KB)
WebSocket 连接处理器管理完整的连接生命周期：
- **会话管理**: 创建、启动、停止、清理会话
- **消息路由**: 将用户消息通过 CLI 子进程（stream-json 模式）处理
- **命令处理**: 解析和处理斜杠命令（slash command）
- **权限控制**: Computer Use 审批、运行时覆盖
- **自动标题**: 追踪用户消息计数，自动生成对话标题
- **会话预热**: 预启动空闲会话以加快响应
- **断线重连**: 客户端断线后保持会话 5 分钟，支持重连
- **消息转换**: CLI stdout 消息转换为 ServerMessage 并转发到 WebSocket
消息协议定义在 `ws/events.ts`，包含 `ClientMessage` 和 `ServerMessage` 类型。
## 服务层
所有后端服务部署在 `src/server/services/` 目录下：
### conversationService.ts
CLI 子进程管理器。每个桌面会话拥有一个 CLI 子进程，子进程通过 SDK WebSocket Bridge 与桌面服务器通信。
### sessionService.ts
会话 CRUD 操作封装。读写 CLI 持久化在 `~/.claude/projects/{path}/{sessionId}.jsonl` 的会话数据，确保桌面应用与 CLI 数据完全互通。使用 SQLite 间接管理会话索引。
### providerService.ts
多 Provider 配置管理。基于预设（Preset）系统，支持 OpenCode 兼容配置。存储位置: `~/.claude/cc-haha/providers.json`，活跃 Provider 的环境变量写入 `~/.claude/cc-haha/settings.json`（与原始 Claude Code 的 `~/.claude/settings.json` 隔离）。
### workspaceService.ts
Git 工作区管理。支持差异查看、文件历史快照、会话工作区初始化等功能。
### pluginService.ts
插件管理系统。支持安装、卸载、更新、启用/禁用插件，管理 MCP 服务器集成与 LSP 服务器集成。
### cronScheduler.ts
Cron 任务调度引擎。定期检查所有定时任务，在匹配 cron 表达式时通过 CLI 子进程执行任务，执行历史持久化到 `~/.claude/scheduled_tasks_log.json`。
### desktopCliLauncherService.ts
桌面 CLI 启动器。负责安装和管理 `claude-haha` CLI 命令，维护 PATH 环境变量。
### 其他服务
- `diagnosticsService.ts` / `doctorService.ts`: 系统诊断
- `searchService.ts`: 搜索服务
- `titleService.ts`: 对话标题自动生成
- `taskService.ts`: 任务管理
- `teamService.ts` / `teamWatcher.ts`: 团队协作
- `notificationService.ts`: 桌面通知
- `networkSettings.ts`: 网络代理设置
- `managedSettingsService.ts`: 托管设置
- `h5AccessService.ts`: H5 访问策略
- `computerUseApprovalService.ts`: Computer Use 审批
- `mcpHostPreflight.ts`: MCP 预检
- `attributionHeaderPolicy.ts`: 归因头策略
- `agentService.ts`: Agent 服务
- `adapterService.ts`: 适配器服务
- `openaiOfficialProvider.ts`: OpenAI 官方提供商
- `hahaOAuthService.ts` / `hahaOpenAIOAuthService.ts`: OAuth 认证
- `repositoryLaunchService.ts`: 仓库启动（Git worktree 集成）
- `filesystemAccessRoots.ts`: 文件系统访问根目录
- `recoverableJsonFile.ts`: 可恢复 JSON 文件读写
- `persistentStorageMigrations.ts`: 持久化存储迁移
- `providerRuntimeEnv.ts`: Provider 运行时环境
|