# Qwen Code Electron Desktop Architecture > 目标：在现有 Qwen Code CLI、VS Code Companion、Core 能力之上，新增一个 > Electron 桌面端本地 AI 编码助手工作台。本文是产品、架构与验证设计文档， > 不包含代码实现。 ## 背景与参考 当前仓库已经有三类可复用资产： - `packages/core`：模型配置、认证、工具注册与执行、权限、会话录制、 `SessionService`、`ChatRecordingService`、MCP、hooks、subagents、memory 等核心能力。 - `packages/cli`：命令行入口、交互式 UI、非交互 `stream-json`、ACP agent、 slash command、配置加载、认证入口。 - `packages/vscode-ide-companion` 与 `packages/webui`：VS Code WebView 聊天界面、 ACP 子进程连接、权限回调、会话更新转换，以及可复用的 React 消息、 ToolCall、PermissionDrawer、ChatViewer 组件。 参考项目 `~/Documents/cc-haha/desktop` 的核心思想是：桌面壳只负责窗口、 原生能力和本地服务生命周期；复杂业务放进本地 HTTP/WebSocket 服务；服务再 编排 CLI 子进程。外部架构文档 `https://claudecode-haha.relakkesyang.org/desktop/02-architecture.html` 可以访问，和本地实现一致：Tauri 主进程启动 sidecar server，React 前端通过 HTTP/WS 访问 server，server 再管理 CLI 子进程。 Qwen Code 不应照搬这套实现，原因是： - 本方案必须使用 Electron，不使用 Tauri。 - Electron 主进程本身具备 Node 运行时，不需要 Bun-compiled sidecar 才能跑本地服务。 - Qwen Code 已有 ACP agent 和 `@agentclientprotocol/sdk` 集成；桌面端应复用 ACP， 而不是像 `cc-haha` 那样再翻译 `stream-json`。 - Qwen Code 已有 `@qwen-code/webui` 共享 UI，桌面端应复用组件和类型转换逻辑， 而不是从参考项目复制整套 React/store。 - 可以参考现代 AI coding desktop 的工作台思路，但不能复制其他产品的品牌、 名称、图标或具体视觉设计。 ## 产品定位与 MVP 范围 桌面端定位是一个本地 AI 编码助手工作台。用户选择本地项目目录后，可以创建 AI 任务线程，让 AI 阅读代码、解释代码、修改代码、运行命令、查看 diff、 提交 Git 变更，并在一个桌面界面内完成从提需求到审查代码的流程。 P0 MVP 必须覆盖： | 能力 | UI 位置 | 验收标准 | | ------------------- | ----------------------------- | ------------------------------------------------------ | | 项目选择/最近项目 | Welcome、左侧边栏顶部 | 用户能打开本地目录，最近项目保留项目名、路径、分支 | | 项目与线程列表 | 左侧边栏 | 每个项目下能展示多个 thread/task，并支持新建/切换 | | AI 对话线程 | 中间主区域 | 展示用户消息、AI 计划、执行步骤、文件引用、最终总结 | | Composer | 中间底部 | 支持多行输入、发送、附件入口、`@file`、`/command` 入口 | | 任务状态 | 顶部栏、线程标题、消息内 | 显示 Idle/Running/Needs Approval/Done/Error | | 文件读取追踪 | AI 消息内 | AI 读过的文件以 chip/list 形式展示 | | 文件修改审查 | 右侧 Changes 面板 | 修改后必须显示 changed files 和 diff | | 接受/撤销修改 | 右侧 Changes 面板 | 支持按全部、文件、hunk 接受或撤销 | | 集成终端 | 底部抽屉 | 当前项目/线程作用域内运行命令，输出可复制/发送给 AI | | 命令审批 | 对话流或终端上方 | AI 运行命令前暂停，用户可 approve once/session 或 deny | | Git 状态与提交 | 顶部栏、右侧 Summary/Changes | 显示分支、modified/staged 数量，可填写 message commit | | 设置 | 左下角、顶部菜单、命令面板 | 配置模型/API key/权限/主题/编辑器/终端/Git | | Chrome DevTools MCP | 开发/测试模式 | 可以连接 renderer，检查 DOM/console/network/screenshot | | E2E | `packages/desktop` 或集成测试 | P0 用户流程必须有可重复自动化验证 | P1 建议覆盖 Worktree 并行任务、浏览器预览、页面批注、自动化任务、Automation Inbox、slash commands、文件/图片拖拽、浮动小窗、通知、主题设置、默认编辑器和 GitHub PR review context。P2 再考虑 Skills 工作流、MCP/插件设置页、Web Search、 Memories、IDE 同步和 Computer Use。 第一版视觉优先级不是花哨，而是让用户始终清楚看到： ```text AI 正在做什么 AI 读了哪些文件 AI 想运行什么命令 AI 改了哪些代码 用户如何接受或撤销 任务最终是否完成 ``` ## 推荐架构 推荐采用四层结构： ```text ┌──────────────────────────────────────────────────────────────┐ │ Electron Main │ │ - BrowserWindow / Menu / Tray / App lifecycle │ │ - Local DesktopServer host │ │ - Native IPC: dialog, shell, window controls, optional PTY │ │ - ACP child process lifecycle │ └──────────────┬───────────────────────────────┬───────────────┘ │ preload IPC │ spawn stdio ACP ▼ ▼ ┌──────────────────────────────┐ ┌────────────────────────┐ │ Electron Renderer │ │ qwen --acp child │ │ React + Zustand + webui │ │ existing CLI ACP agent │ │ HTTP + WebSocket client │ │ core/tools/auth/session│ └──────────────┬────────────────┘ └────────────────────────┘ │ HTTP/WS 127.0.0.1 random port ▼ ┌──────────────────────────────────────────────────────────────┐ │ DesktopServer (Node module hosted by Electron Main) │ │ - REST API: sessions/settings/models/auth/runtime │ │ - WS API: per-session chat stream and permission routing │ │ - AcpProcessClient: ClientSideConnection to qwen --acp │ │ - Session/update normalization for renderer │ └──────────────────────────────────────────────────────────────┘ ``` MVP 中 `DesktopServer` 作为 Electron main 进程内模块启动，监听 `127.0.0.1:0` 随机端口。这样比 `cc-haha` 少一个 server sidecar 进程，打包和调试 更简单。接口边界仍然按本地 HTTP/WS 设计；如果后续需要更强隔离，可以把 `DesktopServer` 平移到 Electron `utilityProcess`，渲染层和 REST/WS 协议不变。 `qwen --acp` 仍作为独立子进程运行。生产包中通过 Electron 可执行文件加 `ELECTRON_RUN_AS_NODE=1` 启动打包后的 `dist/cli.js`，开发态可以使用系统 Node 或 `tsx` 启动源码。选用 Electron 版本时必须确保内置 Node 满足 Qwen Code 的 `>=20` 运行要求。 ## 为什么首选 ACP `cc-haha` 的 server 通过 `stream-json` 与 CLI 子进程通信，然后自己转换 `content_delta`、`tool_use_complete`、`permission_request` 等事件。Qwen Code 已经有更合适的协议边界： - `packages/cli/src/acp-integration/acpAgent.ts` 暴露 `newSession`、`loadSession`、 `unstable_listSessions`、`prompt`、`cancel`、`setSessionMode`、 `unstable_setSessionModel`、`extMethod(deleteSession/renameSession/getAccountInfo)`。 - `packages/cli/src/acp-integration/session/Session.ts` 直接调用 core 的 `GeminiChat`、`ToolRegistry`、hooks、permission、cron、session recording。 - `packages/vscode-ide-companion/src/services/acpConnection.ts` 和 `packages/channels/base/src/AcpBridge.ts` 已证明 ACP 可以作为外部宿主和 CLI 的边界。 - VS Code 的 `QwenSessionUpdateHandler` 已经处理 `agent_message_chunk`、`agent_thought_chunk`、`tool_call`、 `tool_call_update`、`plan`、`available_commands_update`、usage metadata。 因此桌面端应复用 ACP 子进程能力。`stream-json` 只作为 fallback 或 SDK 兼容路径， 不作为桌面主链路。 ## 包与目录规划 新增 workspace： ```text packages/desktop/ ├── package.json ├── electron.vite.config.ts ├── src/ │ ├── main/ │ │ ├── main.ts │ │ ├── windows/MainWindow.ts │ │ ├── lifecycle/AppLifecycle.ts │ │ ├── ipc/registerIpc.ts │ │ ├── native/dialogs.ts │ │ ├── native/shell.ts │ │ └── terminal/PtyManager.ts # scoped terminal, P0 │ ├── preload/ │ │ └── index.ts # contextBridge whitelist │ ├── server/ │ │ ├── index.ts # startDesktopServer() │ │ ├── http/router.ts │ │ ├── http/auth.ts │ │ ├── ws/SessionSocketHub.ts │ │ ├── acp/AcpProcessClient.ts │ │ ├── acp/AcpEventRouter.ts │ │ ├── acp/permissionBridge.ts │ │ ├── services/projectService.ts │ │ ├── services/sessionService.ts │ │ ├── services/gitService.ts │ │ ├── services/reviewService.ts │ │ ├── services/settingsService.ts │ │ ├── services/runtimeService.ts │ │ ├── services/terminalService.ts │ │ ├── services/artifactService.ts │ │ └── types.ts │ └── renderer/ │ ├── main.tsx │ ├── App.tsx │ ├── api/client.ts │ ├── api/websocket.ts │ ├── stores/projectStore.ts │ ├── stores/chatStore.ts │ ├── stores/sessionStore.ts │ ├── stores/reviewStore.ts │ ├── stores/artifactStore.ts │ ├── stores/settingsStore.ts │ ├── stores/modelStore.ts │ ├── stores/terminalStore.ts │ ├── stores/uiStore.ts │ ├── components/layout/ │ └── pages/ └── assets/ ``` 构建顺序上，`packages/desktop` 应放在 `packages/core`、`packages/cli`、 `packages/webui` 之后。根 `scripts/build.js` 后续增加 desktop build；根 `npm run bundle` 产出的 `dist/cli.js` 和必要 vendor/native 资源作为桌面包资源。 ## 应用布局与页面结构 应用采用信息密度较高的开发者工具风格，深色模式优先，避免营销页和装饰性视觉。 主界面是经典工作台布局： | 区域 | 位置 | 作用 | | ------------- | --------------- | ------------------------------------------------ | | 顶部栏 | 窗口顶部 | 当前项目、Git 分支、任务模式、运行状态、快捷按钮 | | 左侧边栏 | 左侧固定栏 | Projects、Threads、Automations、Skills、Settings | | 中间主区域 | 屏幕中间 | AI 对话线程、计划、执行步骤、审批、用户输入框 | | 右侧审查面板 | 屏幕右侧可折叠 | Changes、Files、Artifacts、Summary 四个 tab | | 底部终端抽屉 | 底部可展开/收起 | 集成终端、命令输出、测试结果 | | 弹窗/命令面板 | 全局浮层 | 新建任务、打开项目、搜索、快捷命令、设置 | 顶部栏从左到右显示当前项目名、当前 Git 分支、任务模式、运行状态，以及打开终端、 打开 diff、打开浏览器预览、命令面板和设置入口。MVP 任务模式先实现 Local， Worktree 作为 P1，Cloud 暂缓。 左侧边栏分成四块： ```text Projects - project-a - project-b Threads - 修复登录报错 - 解释项目结构 - 添加单元测试 Automations - 每天检查 CI 报错 - 每周生成代码变更摘要 Bottom - Skills - Settings - User Account ``` Projects 和 Threads 必须支持搜索、折叠和上下文菜单。MVP 右键/更多菜单至少包括： 重命名线程、归档线程、删除线程、在文件管理器中打开项目、刷新 Git 状态。 中间主区域的每条 AI 消息应能展示： - 可折叠 Plan； - step list，例如 1/4、2/4； - 读取文件 chip，例如 `src/App.tsx`； - 修改文件卡片； - 命令执行摘要； - 错误卡片； - 最终 Summary，列出改了什么、如何验证。 Composer 形态： ```text [ Attach ] [ @file ] [ /command ] [ text input .......... ] [ Send ] ``` 右侧审查面板是核心体验，包含： | Tab | 内容 | | --------- | --------------------------------------------------------------------------- | | Changes | changed files、diff viewer、accept/revert file、accept/revert hunk、comment | | Files | 项目文件树、搜索、复制路径、打开文件、让 AI 解释文件 | | Artifacts | Markdown、HTML、JSON、测试报告、图片等非代码产物预览 | | Summary | 当前任务完成内容、验证方式、建议下一步 | 底部终端抽屉作用域为当前项目或当前线程。MVP 至少支持单终端、命令输出、复制输出、 中止命令、发送输出给 AI；P1 支持 dev/test/git 多终端 tab 和命令历史。 页面和组件清单： ```text pages/ - WelcomePage 首次启动、登录/API Key、打开项目 - WorkspacePage 主工作台 - SettingsPage 设置 - AutomationsPage 自动化任务，P1 - SkillsPage 技能/工作流，P2 components/ - AppTopBar - ProjectSidebar - ThreadList - ChatThread - MessageBubble - Composer - ApprovalDialog - ReviewPanel - DiffViewer - FileTree - ArtifactViewer - TerminalDrawer - SettingsModal - CommandPalette ``` 核心 UI 数据结构建议： ```ts type Project = { id: string; name: string; path: string; gitBranch?: string; lastOpenedAt: number; }; type Thread = { id: string; projectId: string; title: string; mode: 'local' | 'worktree' | 'cloud'; status: 'idle' | 'running' | 'waiting_approval' | 'done' | 'error'; createdAt: number; updatedAt: number; }; type Message = { id: string; threadId: string; role: 'user' | 'assistant' | 'system' | 'tool'; content: string; createdAt: number; metadata?: { files?: string[]; commands?: string[]; artifacts?: string[]; }; }; type FileChange = { id: string; threadId: string; filePath: string; status: 'added' | 'modified' | 'deleted'; diff: string; accepted: boolean; }; type CommandRun = { id: string; threadId: string; command: string; cwd: string; status: 'pending_approval' | 'running' | 'success' | 'failed' | 'denied'; output: string; createdAt: number; }; ``` ## 任务模式与核心用户流程 任务模式： | 模式 | MVP | 说明 | | -------- | --- | ----------------------------------------------------------------- | | Local | 是 | AI 直接在当前项目目录读取和修改文件，所有命令和文件访问受审批控制 | | Worktree | P1 | 每个任务创建独立 Git worktree，避免多个任务互相污染 | | Cloud | 否 | 远程容器或云开发环境，MVP 暂缓 | 新建线程弹窗需要包含 task input、mode、permission policy： ```text New Task Task: [ 帮我修复登录页 bug，并保持改动最小 ] Mode: (*) Local ( ) Worktree ( ) Cloud Permissions: (*) Ask before running commands ( ) Auto-run safe commands ( ) Read-only [ Create Task ] ``` 核心用户流程必须被 E2E 覆盖： 1. 首次使用：打开 app，配置 API key 或登录，选择本地项目目录，扫描项目基本信息， 显示项目概览，创建第一个 AI task。 2. 修复 bug：用户新建 task，AI 读取相关文件，给出计划，请求运行测试，用户批准， AI 修改代码，右侧 Changes 显示 diff，用户添加 inline comment，AI 继续修改， 用户接受修改并 commit。 3. 解释项目结构：用户输入请求，AI 读取 `package.json`、入口文件、路由文件， 中间对话输出结构说明，右侧 Summary 显示关键文件列表。 4. 运行测试并修复失败项：AI 请求执行测试，终端显示失败输出，AI 读取日志并修改， 再次请求运行测试，测试通过后生成总结。 ## Electron Main 主进程职责保持薄： - 创建主窗口，管理 macOS/Windows/Linux 菜单、关闭、重启、深色模式。 - 启动 `DesktopServer`，获得 `serverUrl` 与一次性随机 `serverToken`。 - 通过 preload 暴露 `getServerInfo()`，renderer 再通过 HTTP/WS 连接本地服务。 - 注册安全 IPC：选择目录、打开文件、在系统文件管理器中显示、窗口控制、可选 PTY。 - 管理 `qwen --acp` 子进程生命周期：app 退出时关闭 ACP、清理 pending permission。 - CSP 限制 renderer 只连接 `self`、`http://127.0.0.1:*`、`ws://127.0.0.1:*`。 Preload 只暴露白名单： ```ts window.qwenDesktop = { getServerInfo(): Promise<{ url: string; token: string }>, selectDirectory(): Promise, openPath(path: string): Promise, showItemInFolder(path: string): Promise, window: { minimize(); maximize(); close(); isMaximized() }, terminal?: { spawn(); write(); resize(); kill() }, } ``` Renderer 禁用 Node integration，启用 context isolation。禁止 renderer 直接访问 `fs`、`child_process`、任意 IPC channel。 ## DesktopServer `DesktopServer` 是 Electron main 内部启动的 Node HTTP/WS 服务，绑定 `127.0.0.1` 随机端口。所有 REST 请求要求： - `Authorization: Bearer ` - `Origin` 必须为 app 允许来源或为空 - WebSocket 使用 `ws://127.0.0.1:{port}/ws/{sessionId}?token=...` 核心模块： | 模块 | 职责 | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `AcpProcessClient` | spawn `qwen --acp --channel=Desktop`，建立 `ClientSideConnection`，封装 initialize/auth/session/prompt/cancel/mode/model/extMethod | | `AcpEventRouter` | 将 ACP `sessionUpdate` 按 sessionId 分发到 `SessionSocketHub`，复用 VS Code 的更新转换逻辑 | | `permissionBridge` | 将 ACP `requestPermission` / ask-user-question 转为 WS 请求，等待 renderer 回包，超时默认 cancel | | `SessionSocketHub` | 管理每个 session 的 WS 客户端、心跳、重连、pending 消息、广播 | | `sessionService` | 对 `SessionService` 和 ACP session API 做薄封装，提供列表、历史、创建、恢复、重命名、删除 | | `projectService` | 管理最近项目、项目元数据、Git 分支、当前 workspace 范围校验 | | `gitService` | 读取 status/diff、stage/unstage/revert、commit，禁止默认 push/force push | | `reviewService` | 将 Git diff 转为右侧 Changes 面板数据，支持 file/hunk accept、revert、comment | | `settingsService` | 读写 `~/.qwen/settings.json`，复用 `Storage`、Coding Plan 常量、modelProviders 结构 | | `runtimeService` | 当前 session 的 model、approval mode、auth/account info、available commands/skills | | `terminalService` | 管理 scoped terminal，限制 cwd 到当前项目，输出流推送到 renderer，支持中止和输出摘要 | | `artifactService` | 管理 AI 生成的 Markdown/HTML/JSON/测试报告等产物，提供右侧 Artifacts 预览数据 | REST API MVP： | Method | Path | 说明 | | --------- | ---------------------------------- | -------------------------------------------------------- | | `GET` | `/health` | 本地服务健康检查 | | `GET` | `/api/runtime` | CLI 路径、版本、平台、当前 auth/account 摘要 | | `GET` | `/api/projects` | 最近项目列表，含 name/path/gitBranch/lastOpenedAt | | `POST` | `/api/projects/open` | 选择或注册本地项目目录，刷新 Git 元数据 | | `GET` | `/api/sessions?cwd=&cursor=&size=` | 使用 core `SessionService` 或 ACP list 列出会话 | | `POST` | `/api/sessions` | 创建新 ACP session，body: `{ cwd }` | | `POST` | `/api/sessions/:id/load` | 恢复历史 session，调用 ACP `loadSession` | | `GET` | `/api/sessions/:id/messages` | 从 Qwen JSONL 重建历史消息，供 UI 首屏渲染 | | `PATCH` | `/api/sessions/:id` | rename，优先 ACP `extMethod('renameSession')` | | `DELETE` | `/api/sessions/:id` | delete，优先 ACP `extMethod('deleteSession')` | | `GET` | `/api/sessions/:id/slash-commands` | 返回缓存的 `available_commands_update` | | `GET` | `/api/sessions/:id/summary` | 当前任务摘要、验证结果、下一步建议 | | `GET` | `/api/sessions/:id/artifacts` | 当前任务产生的 artifacts 列表与预览元数据 | | `GET` | `/api/models` | 当前模型和可用模型，来自 ACP `NewSessionResponse.models` | | `PUT` | `/api/sessions/:id/model` | 调用 ACP `unstable_setSessionModel` | | `GET/PUT` | `/api/sessions/:id/mode` | 读取/设置 approval mode | | `GET` | `/api/projects/:id/git/status` | 当前分支、modified/staged/untracked 数量 | | `GET` | `/api/projects/:id/git/diff` | changed files 与 unified diff/hunk 数据 | | `POST` | `/api/projects/:id/git/revert` | 按 all/file/hunk 撤销未提交改动 | | `POST` | `/api/projects/:id/git/stage` | 按 all/file/hunk stage，作为 accept 的实现基础 | | `POST` | `/api/projects/:id/git/commit` | 使用用户确认的 commit message 创建提交 | | `POST` | `/api/terminals` | 创建当前项目/线程作用域的 terminal | | `POST` | `/api/terminals/:id/write` | 写入终端 stdin | | `POST` | `/api/terminals/:id/kill` | 中止终端当前进程或关闭 terminal | | `GET/PUT` | `/api/settings/user` | 读写桌面设置和 `~/.qwen/settings.json` | | `POST` | `/api/auth/:method` | 调用 ACP `authenticate` 或写入 API key 后重连 | WS 协议 MVP： ```ts type ClientMessage = | { type: 'user_message'; content: string; attachments?: AttachmentRef[] } | { type: 'permission_response'; requestId: string; optionId: string } | { type: 'ask_user_question_response'; requestId: string; optionId: string; answers?: Record; } | { type: 'set_permission_mode'; mode: 'plan' | 'default' | 'auto-edit' | 'yolo'; } | { type: 'set_model'; modelId: string } | { type: 'git_review_comment'; filePath: string; line?: number; body: string; } | { type: 'terminal_output_to_prompt'; terminalId: string; range?: OutputRange; } | { type: 'stop_generation' } | { type: 'ping' }; type ServerMessage = | { type: 'connected'; sessionId: string } | { type: 'message_delta'; role: 'assistant' | 'thinking' | 'user'; text: string; } | { type: 'tool_call'; data: ToolCallUpdateData } | { type: 'plan'; entries: PlanEntry[] } | { type: 'permission_request'; requestId: string; request: RequestPermissionRequest; } | { type: 'ask_user_question'; requestId: string; request: AskUserQuestionRequest; } | { type: 'usage'; data: UsageStatsPayload } | { type: 'mode_changed'; mode: string } | { type: 'available_commands'; commands: AvailableCommand[]; skills: string[]; } | { type: 'file_reference'; filePath: string; reason?: string } | { type: 'file_change'; filePath: string; status: 'added' | 'modified' | 'deleted'; } | { type: 'git_status'; branch: string | null; modified: number; staged: number; untracked: number; } | { type: 'terminal_output'; terminalId: string; text: string; stream: 'stdout' | 'stderr'; } | { type: 'terminal_exit'; terminalId: string; exitCode: number | null; signal: string | null; } | { type: 'message_complete'; stopReason?: string } | { type: 'error'; message: string; code: string; retryable?: boolean } | { type: 'pong' }; ``` ## 会话生命周期 1. Renderer 启动后调用 `getServerInfo()`，配置 API base URL 和 token。 2. `projectStore.fetchProjects()` 从 `/api/projects` 拉取最近项目和 Git 元数据。 3. 用户选择项目目录后，`POST /api/projects/open` 注册项目，刷新 branch/status。 4. `sessionStore.fetchSessions()` 按项目从 `/api/sessions?cwd=` 拉取历史线程。 5. 用户新建线程时选择 mode/permissions；MVP mode 为 Local，调用 ACP `newSession({ cwd })`。 6. Server 缓存 session 的 models、modes、commands、skills，并打开 WS。 7. 用户发送消息，WS handler 调用 `acp.prompt({ sessionId, prompt })`。 8. ACP agent 在 CLI 子进程内复用 core：配置、认证、模型、工具、权限、hooks、录制。 9. `sessionUpdate` 流式回到 server，server 归一化后推给 renderer。 10. 工具需要权限时，ACP `requestPermission` 被 server 转为 WS 请求；renderer 展示 `@qwen-code/webui` 的 `PermissionDrawer`，响应后 server resolve ACP promise。 11. AI 修改文件后，renderer 刷新 `/api/projects/:id/git/diff`，右侧 Changes 面板 展示 changed files、diff 和 accept/revert/comment 操作。 12. 用户审查完成后，可以 stage/accept 改动并通过 `/api/projects/:id/git/commit` 创建提交；push 和 PR 不属于 P0 默认操作。 13. 生成结束后，server 发送 `message_complete`，renderer 刷新 usage、session summary、Git status 和 session 列表。 14. App 退出时 main 关闭 WS、停止 server、终止 ACP 子进程和 scoped terminals。 并发约束： - 同一个 session 只允许一个 active prompt；后续消息可排队或提示当前正在生成。 - 不同 session 可以共享同一个 ACP 子进程；如果发现单进程互相影响，再演进为 per-workspace ACP process pool。 - permission request 必须有超时，默认选择 cancel，避免窗口关闭后 ACP 永久挂起。 ## 配置与认证复用 桌面端不维护独立配置格式。用户设置仍写入： - 全局：`~/.qwen/settings.json` - 项目：`/.qwen/settings.json` - runtime output：沿用 `Storage.getRuntimeBaseDir()` 与 `QWEN_RUNTIME_DIR` 复用策略： - 认证真实执行仍通过 `qwen --acp` 的 `authenticate()` 与 `Config.refreshAuth()`。 - API key / Coding Plan 表单复用 VS Code `settingsWriter.ts` 的逻辑，但应抽成 非 VS Code 依赖的共享模块，避免复制两份 JSON 写入规则。 - 模型列表来自 `Config.getAllConfiguredModels()` 经 ACP 返回，桌面不自己推断 provider。 - approval mode 使用 Qwen 的 `plan/default/auto-edit/yolo`，不引入 `cc-haha` 的 `bypassPermissions` 命名。 - 权限持久化仍走 core `PermissionManager` 与 settings 中的 `permissions.allow/ask/deny`。 Settings 页面采用左侧分类 + 右侧表单布局。MVP 分类： | 分类 | MVP 设置项 | | ------------- | -------------------------------------------------------------- | | General | 默认项目目录、默认打开方式、多行输入快捷键、长任务防止睡眠 | | Model | API provider、model、API key、reasoning effort、temperature | | Permissions | 文件访问范围、命令运行策略、网络访问、高危命令确认、审批白名单 | | Git | 默认 branch 命名规则、是否允许 push、commit message 生成规则 | | Terminal | 默认 shell、环境变量、输出最大行数、命令超时 | | Appearance | Light/Dark/System、UI font、code font、font size、accent color | | Notifications | 任务完成、需要审批、自动化任务结果、后台运行通知 | Browser、Integrations、Memories、Advanced 可以先放入口或占位，真实能力进入 P1/P2。 ## 渲染进程与状态管理 Renderer 使用 React + Vite + Zustand。主界面必须是工作台，而不是只有聊天窗口。 UI 不复刻 VS Code WebView，但复用 `@qwen-code/webui` 中适合桌面端的消息、 工具、权限和输入组件： - 消息：`UserMessage`、`AssistantMessage`、`ThinkingMessage`、`WaitingMessage` - 工具：shared ToolCall components、`ToolCallContainer`、`AgentToolCall` - 权限：`PermissionDrawer`、`AskUserQuestionDialog` - 输入：`InputForm`、`CompletionMenu`、`SessionSelector` - 历史只读视图：`ChatViewer` 推荐 stores： | Store | 状态 | | --------------- | ----------------------------------------------------------------------------------------- | | `projectStore` | recent projects、activeProjectId、git branch/status、open/refresh/remove project | | `sessionStore` | thread list、activeSessionId、mode、status、create/load/archive/delete/rename | | `chatStore` | per-thread messages、plan、steps、file refs、tool calls、permission、usage、commands | | `reviewStore` | changed files、selected file、diff hunks、accept/revert/comment、commit draft | | `artifactStore` | generated artifacts、preview selection、test reports、summary data | | `modelStore` | current model、available models、per-session model override | | `settingsStore` | auth/account、approval mode、theme、editor、terminal shell、Git options、desktop settings | | `uiStore` | sidebar collapsed、right panel tab、terminal drawer、command palette、dialogs | | `terminalStore` | scoped terminal tabs、command output、running state、history、output selection | 数据流： ```text Component → Zustand action → REST/WS → DesktopServer → ACP → core/CLI ← Zustand reducer ← WS event ← DesktopServer ← ACP sessionUpdate ``` 首屏建议是 Welcome + Workspace 的组合：首次没有项目时展示登录/API key、Open Project、最近项目；有项目后进入 WorkspacePage。WorkspacePage 必须包含顶部栏、 左侧 Projects/Threads、中心 ChatThread、右侧 ReviewPanel、底部 TerminalDrawer。 ## 命令执行与终端 Agent 的 shell/file/tool 执行不由 Electron 实现，继续由 core 工具系统执行： - ShellTool/Edit/Write/Read/WebFetch/MCP 等工具保持现状。 - Desktop 只负责展示 tool_call、diff、输出、权限确认。 - 这样 CLI、VS Code、Desktop 的安全语义一致。 P0 需要内置 scoped terminal，但它是用户终端，不是 agent 工具系统的替代： - 使用仓库已有 optional dependency `@lydell/node-pty`。 - Electron main 暴露 `terminal:spawn/write/resize/kill` IPC。 - 终端 cwd 默认当前 session workspace。 - 终端支持展开/收起、复制输出、清空显示、中止命令、把选中输出发送给 AI。 - MVP 支持单 terminal；P1 支持 dev server、test、git 多 terminal tab。 - AI 要运行命令时仍走 ACP/core permission flow，并在对话中展示审批卡片； 终端抽屉显示命令输出和测试结果，但不能绕过命令审批。 - 高风险命令如 `rm -rf`、`sudo`、删除大量文件、force push、网络安装依赖等必须 高亮风险，并要求用户明确确认。 ## 与 cc-haha 的差异化适配 | cc-haha 设计 | Qwen Desktop 适配 | | -------------------------------- | ------------------------------------------------------------------- | | Tauri/Rust 主进程 | Electron main，Node 原生能力更强 | | Bun compiled server sidecar | MVP 不需要 server sidecar，main 内启动 Node DesktopServer | | Server spawn 每个 session 的 CLI | 默认一个 ACP 子进程管理多个 Qwen sessions | | stream-json 翻译成 WS 事件 | 复用 ACP `sessionUpdate` 和 requestPermission | | `~/.claude` 会话解析 | 复用 `~/.qwen`、`Storage`、`SessionService`、`ChatRecordingService` | | 独立 React 组件体系 | 复用 `@qwen-code/webui` 和 VS Code 的事件转换经验 | | Tauri commands 做 native bridge | Electron preload + typed IPC 白名单 | ## 安全模型 - 本地 server 只绑定 `127.0.0.1`，使用随机端口和随机 token。 - REST 必须校验 bearer token；WS token 放 query 并在握手时校验。 - Renderer 无 Node integration，preload 只暴露白名单 API。 - 禁止任意命令 IPC；用户命令执行只能通过 Qwen 工具系统或可选 terminal。 - 权限请求必须显示 tool name、kind、input、diff/command/path，并支持 deny。 - 默认 AI 只能访问当前项目目录。跨目录文件读取/修改必须被权限层拦截或显式审批。 - 默认命令策略是 Ask every time。Read-only 和 Auto-approve safe commands 作为 新建线程与设置页可选权限模式。 - 文件修改必须通过右侧 diff 审查面板可见，用户可以接受或撤销；不得把修改结果 只藏在聊天消息里。 - 网络访问由设置控制，MVP 默认保守；远程 URL 访问、安装依赖、push 等动作必须 进入审批流程。 - App 退出、窗口关闭、WS 断开时，pending permission 默认 cancel。 - 外部链接用 `shell.openExternal`，需要 URL scheme allowlist。 - 打包时 CSP 禁止远程 script，允许本地 server connect-src。 - Chrome DevTools Protocol 只在显式开发/测试模式启用，默认生产关闭。启用时 只能绑定 `127.0.0.1`，端口来自 `QWEN_DESKTOP_CDP_PORT` 或专用测试脚本， 不允许监听公网地址。 ## E2E 与 Chrome DevTools MCP 方案 桌面端必须把 E2E 当作 MVP 验收的一部分，而不是只依赖单元测试和 smoke test。 方案分三层： 1. **协议层 E2E**：启动 `DesktopServer` + fake ACP agent，覆盖 REST/WS 协议、 token 校验、session 创建、消息发送、permission request/response、model/mode 切换。此层运行快，适合放在 `packages/desktop` 的 vitest 测试中。 2. **真实 Electron E2E**：使用 Playwright Electron 启动 `packages/desktop`， 注入临时 HOME/QWEN_RUNTIME_DIR/workspace 和 fake ACP CLI，断言首屏不是黑屏、 `Connected` 状态出现、选择目录、新建会话、发送消息、停止生成、权限弹层响应、 settings 保存、模型/模式选择。测试应收集 screenshot、console errors、failed requests 和主进程日志，失败时写入 `.qwen/e2e-tests/electron-desktop/`。 3. **打包后 E2E / smoke**：先 `npm run build && npm run bundle`，再 `npm run package:dir --workspace=packages/desktop`。启动打包目录中的 app，验证 renderer、preload、bundled CLI、`ELECTRON_RUN_AS_NODE=1` ACP 子进程都能工作。 为了让 Codex、Ralph 或人工调试工具能看到真实 Electron renderer，桌面端要提供 Chrome DevTools MCP 可访问入口： - Electron main 在 `app.whenReady()` 之前读取 `QWEN_DESKTOP_CDP_PORT`。存在时调用 `app.commandLine.appendSwitch('remote-debugging-address', '127.0.0.1')` 和 `app.commandLine.appendSwitch('remote-debugging-port', port)`。 - 新增或保留一个开发脚本，例如 `QWEN_DESKTOP_CDP_PORT=9222 npm run start --workspace=packages/desktop`。脚本启动后， chrome-devtools-mcp 连接 `http://127.0.0.1:9222`，选择 `Qwen Code` renderer page。 - E2E harness 启动 app 后读取 CDP endpoint，至少验证： - page URL 是 `file://.../packages/desktop/dist/renderer/index.html` 或 dev-server URL； - DOM 中存在 `Qwen Code`、`Connected`、`Runtime`、`Settings`； - console 没有 uncaught exception； - network 没有 renderer asset 404； - screenshot 不是纯黑或空白。 - Chrome DevTools MCP 用于可视检查和调试，不替代可重复的 Playwright/Vitest E2E。 如果 MCP 能看到问题，必须把复现步骤固化为自动化 E2E 或在 `.qwen/e2e-tests/electron-desktop/` 记录不能自动化的原因。 ## 实施阶段 ### Phase 0: E2E Harness 与可观测性 - 新增/完善 desktop E2E harness，支持 fake ACP、临时 HOME/QWEN_RUNTIME_DIR、 临时 workspace、截图、console/network 诊断。 - 开发/测试模式支持 `QWEN_DESKTOP_CDP_PORT`，chrome-devtools-mcp 能连接 renderer 并检查首屏、console、network。 - 建立 “首屏不是黑屏” E2E：启动 app，断言 `Qwen Code`、`Open Project`、 `Settings`、空项目状态可见。 ### Phase 1: 桌面壳、本地服务与 Welcome - 新增/整理 `packages/desktop` workspace。 - Electron main/preload/renderer 骨架。 - Main 启动 `DesktopServer`，renderer 获取 server URL。 - `/health`、token 校验、窗口菜单、选择目录。 - WelcomePage：API key/login 入口、Open Project、最近项目空状态。 - E2E：首次启动、服务 connected、选择临时项目目录、最近项目持久化。 ### Phase 2: Workspace 三栏布局与项目/线程模型 - AppTopBar、ProjectSidebar、ThreadList、ChatThread、ReviewPanel、 TerminalDrawer、CommandPalette 骨架。 - Project store 和 Thread store；左侧 Projects/Threads 支持搜索、折叠、上下文菜单。 - 顶部栏显示项目名、Git branch、mode、status、terminal/diff/settings 快捷按钮。 - E2E：打开项目后进入 WorkspacePage，创建 Local thread，切换线程，刷新 Git 状态。 ### Phase 3: ACP 会话链路与 AI 对话 - 实现 `AcpProcessClient`，spawn `qwen --acp --channel=Desktop`。 - 实现 session create/load/list/prompt/cancel/mode/model。 - 实现 WS per-session 通道和 `QwenSessionUpdateHandler` 风格的事件转换。 - ChatThread 展示用户消息、AI 消息、Plan、steps、file refs、tool calls、usage。 - E2E：fake ACP 返回计划、文件引用、assistant delta、tool update、final summary。 ### Phase 4: 权限、命令审批与终端抽屉 - 接入 permission request 和 ask-user-question。 - ApprovalDialog 支持 Approve once、Approve for this thread、Deny。 - TerminalDrawer 支持 scoped terminal、命令输出、复制、清空、中止、发送给 AI。 - 高风险命令高亮并二次确认；终端不能绕过 agent 命令审批。 - E2E：命令审批 pending/running/denied/success；终端输出可见并可发送给 AI。 ### Phase 5: Diff Review、文件树、Artifacts 与 Commit - gitService/reviewService 支持 status、diff、accept/revert all/file/hunk、comment。 - Right panel tabs：Changes、Files、Artifacts、Summary。 - DiffViewer 支持文件树、hunk 展示、inline comment、Open in Editor。 - Commit UI：commit message 输入、stage/commit、失败提示；push/PR 留到 P1。 - E2E：fake file change 后 Changes 显示 diff；accept/revert/commit 流程可验证。 ### Phase 6: 设置、认证、模型与打包 - 抽取 VS Code settings writer 的通用部分。 - SettingsPage/SettingsModal 覆盖 General、Model、Permissions、Git、Terminal、 Appearance、Notifications。 - 实现 Coding Plan / OpenAI-compatible provider 配置 UI。 - 打包包含 `dist/cli.js`、vendor ripgrep、native optional deps。 - 生产态使用 `ELECTRON_RUN_AS_NODE=1` 启动 CLI ACP 子进程。 - E2E/smoke：settings 保存后刷新仍保留；打包产物能加载 renderer 并启动 bundled CLI ACP。 ### P1/P2 后续阶段 - P1：Worktree 并行任务、浏览器预览、页面批注、自动化任务、slash commands、 拖拽文件/图片、浮动小窗、通知、主题/编辑器增强、GitHub PR review context。 - P2：Skills 工作流、MCP/插件系统、Web Search、Memories、IDE 同步、Computer Use。 ## 测试计划 单元测试： - `AcpProcessClient`：mock `ClientSideConnection`，覆盖 initialize/new/load/prompt/cancel。 - `AcpEventRouter`：覆盖 message/tool/plan/usage/available_commands 映射。 - `permissionBridge`：覆盖 allow/deny/timeout/window closed。 - `settingsService`：使用临时 `QWEN_RUNTIME_DIR` / HOME，验证 settings JSON 写入。 - renderer stores：连接、发送、streaming、tool update、permission 状态。 集成测试： - 启动 DesktopServer + fake ACP agent，验证 REST/WS 协议。 - 启动真实 `qwen --acp`，用临时 workspace 创建 session，发送简单 prompt。 - 验证 session JSONL 可被 core `SessionService` 读取。 E2E： - `packages/desktop` 增加 Electron E2E harness。优先使用 Playwright Electron； 如果仓库不引入额外 Playwright 依赖，则用 Electron 的 CDP endpoint 配合 chrome-devtools-mcp/DevTools Protocol 做可视与 DOM 断言，但最终仍要沉淀成可重复 的自动化测试。 - 每个用户可见行为切片必须先写 E2E 场景，至少覆盖： - 首次使用：启动 app 后首屏不是黑屏，配置 API key/login 入口可见，选择临时 项目目录后进入 Workspace； - 修复 bug：新建 Local thread，发送“修复登录页点击无反应”，fake ACP 返回计划、 文件读取、命令审批、文件修改，右侧 Changes 显示 diff，用户 comment 后继续修改， 最后 accept 并 commit； - 解释项目结构：fake ACP 读取 `package.json`、入口文件、路由文件，中心消息和 Summary tab 显示关键文件列表； - 运行测试并修复失败项：命令审批 `npm test`，终端显示失败输出，AI 修改文件， 再次请求测试，最终 Summary 标记测试通过； - 权限与安全：permission request 和 ask-user-question 能从 renderer 响应到 fake ACP， denied/timeout 都有清晰 UI 状态； - 设置：settings/auth/model/mode/terminal/theme 保存后刷新仍保留； - 取消生成：会调用 ACP cancel 并更新 UI； - 打包目录启动后 renderer asset、preload、bundled CLI ACP 都可用。 - E2E 运行时必须收集失败诊断：Electron main stderr/stdout、renderer console、 failed network requests、截图、CDP page list、DesktopServer URL/token 状态摘要。 - chrome-devtools-mcp 调试路径必须纳入验收：使用固定本地 CDP 端口启动 app， 通过 MCP 连接 renderer，确认页面 URL、DOM、console/network 状态。发现黑屏或 asset 404 时先修复 Vite base/path，再重跑 E2E。 验收命令后续应接入： ```bash npm run build npm run typecheck npm test --workspace=packages/desktop npm run test:e2e --workspace=packages/desktop npm run package:dir --workspace=packages/desktop npm run smoke:package --workspace=packages/desktop npm run smoke:package --workspace=packages/desktop -- --launch ``` ## 风险与应对 | 风险 | 应对 | | --------------------------------- | ------------------------------------------------------------------------- | | Electron 内置 Node 版本不满足 CLI | 固定 Electron 版本时校验 Node >=20；CI 加 smoke test | | packaged app 无法启动 CLI JS | 生产态使用 `ELECTRON_RUN_AS_NODE=1`；明确资源路径；打包 smoke test | | ACP 单进程多 session 互相影响 | 先复用现有 ACP；若发现阻塞，升级为 per-workspace process pool | | VS Code settings writer 被复制 | 抽成 core/desktop 共用的 settings writer 模块 | | 本地 server 被其他本地进程调用 | 127.0.0.1 + random token + origin 校验 | | native deps 打包遗漏 | 列出 `@lydell/node-pty`、ripgrep、clipboard 等资源清单；打包后 smoke test | | renderer 与 ACP 事件类型漂移 | 复用/抽取 `QwenSessionUpdateHandler` 测试夹具 | | MVP 退化成聊天壳 | 每个切片必须保留工作台布局和右侧审查/底部终端可见验收 | | hunk 级 accept/revert 误伤代码 | 优先使用 Git/index 或结构化 patch API；E2E 覆盖 file/hunk 操作 | | 终端绕过命令审批 | 用户 terminal 和 agent command permission 分离；AI 命令仍走 ACP 审批 | ## 开放问题 - 桌面端是否需要第一版就支持多窗口，还是先单窗口多 tab？ - 单窗口多 tab - 是否把 `AcpProcessClient` 抽成 `packages/acp-client`，供 VS Code、channels、desktop 共用？ - 不需要，先放 desktop 内部 - Desktop settings UI 是只覆盖认证/模型/权限，还是完整暴露 `settings.json`？ - MVP 覆盖 General、Model、Permissions、Git、Terminal、Appearance、Notifications； 不直接暴露完整 JSON 编辑器 - 是否在 MVP 中内置 terminal，还是先专注 chat/workspace？ - MVP 需要 scoped terminal drawer，但它是用户终端，不绕过 agent 命令审批 - 是否需要独立桌面命令 `qwen desktop` 启动 Electron？ - 不需要