| title | 架构总览 |
|---|---|
| nav_title | 架构总览 |
| description | 五层代码怎么分工，一条消息怎么流过它们，以及改动某块功能该从哪篇读起。 |
| order | 0 |
Claude Code Haha 看着是一个桌面应用，实际是五块可以各自独立运行的代码拼起来的。想读源码或者提 PR，先把这五块的边界分清楚，后面每一篇都会落在其中一块里。
desktop/src/ 前端 —— React + Zustand，只画界面，不碰系统能力
desktop/electron/ 桌面壳 —— Electron 主进程，管窗口、更新、终端、原生预览
src/server/ 本地 Server —— Bun.serve 的 REST + WebSocket，桌面端和手机端共用
src/ CLI 内核 —— Agent 循环、工具系统、权限、记忆、Skills
adapters/ IM 接入 —— 每个平台一个独立 sidecar，桥回同一套会话
三条事实值得先记住：
- CLI 内核是唯一执行方。桌面端每开一个会话，Server 就拉起一个 CLI 子进程；前端点的每个按钮最后都变成发给它的一条消息。
- 本地 Server 是唯一入口。桌面端、手机 H5、IM adapter 走的是同一套 REST 与 WebSocket，只是鉴权等级不同。
- Electron 是当前桌面主路径，
desktop/src-tauri/只保留打包资源和历史代码作回滚，不是运行时。
入口层做完初始化后分成两侧：左侧是把一次请求跑完的主链路（终端界面 → 查询引擎 → 工具系统 → 子 Agent），右侧是被主链路调用的横切能力（状态管理、Skills 与插件、MCP / OAuth / 记忆等服务）。桌面端接管了终端界面那一格，其余部分原样复用。
用户输入被解析、组装上下文后发给模型，流式返回里一旦出现工具调用，就先过权限校验再执行，结果回填进上下文继续下一轮，直到模型不再请求工具。桌面端看到的「工具调用卡」「权限询问卡」，就是这条链路上两个节点的可视化。
所有工具在同一个注册中心登记，按能力分成文件、命令、系统、子 Agent、外部集成和通信几类。真正决定安全边界的是下面那条固定管线：任何一次调用都要先过参数校验和权限门，再进沙箱执行。加新工具时，接进注册中心不难，难的是想清楚它落在权限门的哪一侧。
| 你想动的东西 | 从这篇开始 |
|---|---|
| 窗口、托盘、自动更新、内嵌终端、原生预览 | 桌面端架构 |
| REST 接口、WebSocket 事件、鉴权、Provider 代理 | 本地 Server 与 API |
| 不知道某个功能的代码在哪个目录 | 项目结构 |
| 子 Agent 的行为、内置 Agent、Agent Teams | 多 Agent 使用指南 |
| 子 Agent 的生成路径、工具池过滤、后台任务引擎 | 多 Agent 实现原理 |
| Agent 主循环、系统提示词、上下文压缩 | Agent 框架深度解析 |
| Skill 的写法、来源优先级、触发方式 | Skills 使用指南 |
| Skill 的发现、注入、fork 执行 | Skills 实现原理 |
| 记忆存在哪、什么时候写 | 记忆系统使用指南 |
| 记忆的注入、提取、检索、团队同步 | 记忆系统实现原理 |
| 后台自动整合记忆 | AutoDream 记忆整合 |
| 屏幕控制的工具、授权、坐标换算 | Computer Use 架构 |
| IM 消息协议、访问控制、权限中继 | Channel 系统 |
| 提 PR 前要跑哪些检查、发版流程 | 参与贡献与质量门禁 |
| 在终端里跑 CLI、写自动化脚本 | CLI 安装与启动 |