阅读指南：先抓住所有权，再读模块
1. 为什么不能照着目录读
Orca 的源码不是一个“小而美”的 SDK，而是一套正在高频演进的桌面产品。当前快照同时包含：
- Electron 主进程、preload 与 React renderer；
- 本地、daemon、WSL、SSH 和配对 runtime 五类执行路径；
- xterm.js、node-pty 与主进程 headless terminal model；
- Git worktree、folder workspace、项目分组和多 provider 任务；
- Agent hook、会话扫描、原生聊天投影和多 Agent 编排；
- CLI、WebSocket RPC、移动端与插件 worker。
如果按 src/main/*、src/renderer/* 的目录顺序读，很快会遇到同一个概念在四个进程里的投影。更有效的方法是反复问四个问题：
- 身份是什么？ 例如
worktreeId、paneKey、ptyId是否属于同一层？ - 谁是事实源？ renderer store、主进程 Store、runtime graph、远端 relay，哪一个有最终决定权？
- 事实怎样跨边界？ IPC、WebSocket RPC、SSH multiplex、文件、hook HTTP，还是 terminal byte stream？
- 失败后如何恢复？ 是否有 generation、incarnation、snapshot、revision、operation id 或 tombstone？
这四个问题贯穿后续 15 章。
2. 推荐阅读路径
第一阶段：建立坐标系
先读第 1～3 章。读完后，你应该能准确解释：
- Orca 为什么是 agent harness / IDE，而不是另一个 Agent SDK；
- Electron main、renderer、runtime、relay 各自拥有哪类资源；
- Project、Repo、Workspace、Worktree、Tab、Leaf、Pane 和 PTY 的关系。
第二阶段：跟一次真实启动
第 4～7 章以“新建 worktree 并启动 Codex”为主线：
NewWorkspace UI
-> Zustand action
-> preload API
-> worktrees:create IPC / runtime RPC
-> git worktree add
-> workspace metadata
-> tab + stable leaf
-> PTY provider spawn
-> startup prompt delivery
-> Agent hook status
-> renderer row / notification / persistence这是整套系统最重要的一条纵向切片。
第三阶段：理解“本地”只是一个特例
第 8 章把前面的主链重新放到 SSH 和 remote runtime 上。这里会看到 Orca 最核心的工程手法：先把本地能力抽象成 provider / controller，再通过协议把相同语义搬到另一台机器上。
第四阶段：看平台如何扩张
第 9～14 章解释浏览器、Git provider、持久化、编排、CLI、移动端、插件和可靠性体系。它们共享一条规律：扩张功能时不让“不可信客户端”抢走主机资源的所有权。
3. 源码基准与统计口径
本文基于本地 orca-main 快照：
| 项目 | 值 |
|---|---|
package.json 版本 | 1.4.163 |
| 分析日期 | 2026-08-01 |
| Node 目标 | 24 |
| 包管理器 | pnpm 10.24 |
| TypeScript / TSX 文件 | 约 9,560 |
| 去除常规 test/spec 后 | 约 5,622 |
文件数量用于说明体量，不作为质量指标。统计命令为：
find src -type f \( -name '*.ts' -o -name '*.tsx' \) | wc -l上游 main 持续变化，因此文档里的源码链接主要用于定位文件，不承诺未来行号稳定。入口是上游的 package.json。
4. 每章的固定结构
拆解方式参考 dg-ai-notes，但针对 Orca 的体量做了调整。每章尽量回答四层问题：
| 层次 | 要回答的问题 |
|---|---|
| 是什么 | 这个子系统解决哪类产品问题？ |
| 怎么做 | 关键类型、文件、状态机与数据流是什么？ |
| 为什么 | 为什么选择这种所有权和兼容策略？ |
| 怎么验证 | 测试、诊断、失败注入和边界条件在哪里？ |
每章末尾都有“源码导航”，可把概念映射回文件。
5. 三个容易误读的地方
5.1 renderer store 很大，但并不拥有一切
Zustand store 是 UI 的组合状态和操作入口，却不能单方面决定 PTY 是否活着、远程主机上是否存在 worktree、Agent 会话是否可恢复。资源事实最终要回到 main/runtime/provider。
5.2 terminal tab 不等于 PTY
Tab 是 UI 容器，leaf 是布局节点，pane key 是稳定逻辑身份，PTY 才是操作系统进程。重启、split、detach、reattach 期间它们可以分别变化。把四者混为一谈，会误解几乎所有恢复代码。
5.3 Agent 状态不是从标题“猜”出来的
终端标题和前台进程只提供辅助证据。Orca 的明确状态来自 Agent hooks，并通过 pane key、launch token、provider session 和 connection scope 进行归属校验。详见第 7 章。
6. 建议的源码实验
只阅读不运行时，可以围绕以下问题做静态追踪：
- 从
src/renderer/src/store/index.ts找到createWorktreeSlice； - 追到 preload 的
worktrees:create调用； - 进入
src/main/ipc/worktrees.ts； - 找出 local / SSH / runtime 三条分支；
- 再追启动 terminal 时生成的
tabId、leafId、paneKey和ptyId。
如果能画出这条链，后续章节会轻松很多。
7. 文档边界
本教程聚焦架构与关键机制，不尝试：
- 逐个解释数千个 React 组件；
- 复述每个 provider 的 UI；
- 记录所有短期实验开关；
- 代替上游用户文档或贡献指南；
- 对未在本地快照中验证的未来实现做保证。
下一章先回答最根本的问题：Orca 到底是什么，以及它为什么必须长成现在这套架构。