第 15 章：源码地图与学习路线

目标：把前 14 章压缩成可执行的源码索引。遇到具体功能时，可以从这里快速找到入口、事实源、客户端投影和测试。

1. 顶层目录地图

orca/
├── src/
│   ├── main/          Electron main、资源服务、runtime
│   ├── renderer/src/  React UI、Zustand、xterm view
│   ├── preload/       renderer ↔ Electron typed bridge
│   ├── shared/        跨进程类型、schema、协议、身份
│   ├── cli/           orca CLI specs、handlers、transport
│   └── relay/         SSH 远端 PTY/Git/文件服务
├── mobile/            Expo / React Native 客户端
├── config/            构建、检查、发布脚本
├── tests/e2e/         Electron Playwright E2E
├── tools/             repro 与 benchmark
├── docs/              设计记录与兼容政策
├── skill-guides/      随应用分发的完整 skill 文档
└── skill-stubs/       渐进披露入口

2. 十个必须先读的文件

顺序	文件	阅读目标
1	package.json	目标、依赖、构建与测试面
2	src/shared/types.ts	Repo/Worktree/Tab/PersistedState
3	src/main/index.ts	composition root
4	src/main/ipc/register-core-handlers.ts	本机能力目录
5	src/preload/index.ts	renderer 权限面
6	src/renderer/src/store/index.ts	客户端状态切片
7	src/main/runtime/orca-runtime.ts	公共主机语义
8	src/main/providers/pty-provider-contract.ts	PTY 抽象
9	src/shared/runtime-types.ts	RPC/移动投影
10	src/main/persistence.ts	磁盘状态与迁移

不要试图一次读完这些大文件；先找本教程提到的类型和 public method，再沿 call site 扩展。

3. 按问题找代码

“为什么 workspace 没出现？”

1. renderer store/slices/worktrees.ts；
2. main ipc/worktrees.ts；
3. Git git/worktree.ts；
4. remote owner providers/ssh-git-provider.ts 或 runtime worktree RPC；
5. metadata persistence.ts；
6. sidebar components/sidebar/WorktreeList.tsx。

“终端为什么丢画面/卡住？”

1. renderer terminal-pane/pty-connection.ts；
2. output scheduler lib/pane-manager/pane-terminal-output-scheduler.ts；
3. main ipc/pty.ts；
4. runtime orca-runtime.ts 中 onPtyData / snapshot；
5. provider contract 与具体 provider；
6. docs/terminal-main-owned-state.md。

“Agent 状态为什么不对？”

1. shared/agent-status-types.ts；
2. main/agent-hooks/server.ts；
3. shared/agent-hook-listener.ts；
4. provider hook service；
5. renderer store/slices/agent-status.ts；
6. pane authority / freshness scheduler。

“SSH 重连后数据错乱？”

1. ssh/ssh-connection.ts；
2. ssh/ssh-relay-session.ts；
3. connection generation；
4. multiplexer/frame decoder；
5. renderer direct-ssh recovery ledger；
6. host-stamped store admission。

“移动端和桌面 tab 不一致？”

1. shared/runtime-types.ts 的 session snapshot；
2. runtime listMobileSessionTabs 与 publication；
3. renderer runtime/web-session-tabs-sync.ts；
4. mobile src/session；
5. client selection projection；
6. close reason / host retirement revision。

4. 主流程索引

启动桌面

main/index.ts
 -> startup/*
 -> persistence.Store
 -> OrcaRuntimeService
 -> createMainWindow
 -> registerCoreHandlers
 -> renderer/App.tsx hydration
 -> sync-runtime-graph

创建 Agent worktree

New workspace UI / CLI
 -> worktree slice / runtime client
 -> worktrees:create / worktree RPC
 -> git/worktree.addWorktree
 -> Store WorktreeMeta + lineage
 -> tabs/terminals slice
 -> pty spawn
 -> TUI_AGENT_CONFIG prompt delivery
 -> hook status

恢复 terminal

persisted workspace session
 -> stable pane identity normalization
 -> renderer pane mount
 -> provider spawn(sessionId) / attach
 -> snapshot + provider sequence
 -> xterm replay guard
 -> live chunk reconciliation
 -> runtime graph publication

远程 Agent 唯一执行

client createAgentSession(operationId, metadata)
 -> capability negotiation
 -> host claim fingerprint
 -> authoritative provider listing
 -> create or adopt
 -> canonical surface handoff
 -> durable host tab/terminal publication

5. 各领域的“事实源”速查

领域	事实源	客户端缓存/投影
Repo 设置	main Store / host partition	repo slice
Git worktree	执行 host 的 Git	worktree slice + meta fallback
PTY liveness	provider + incarnation	terminal slice / pane connection
终端画面	runtime/provider model	xterm view
Agent 状态	hook server / runtime	agent-status slice
Browser guest	BrowserManager	browser slice
Orchestration	SQLite home DB	Agent rows / CLI output
Mobile tab	host session publication	per-device projected selection
Plugin consent	main Store/service	settings UI

6. 测试入口索引

想验证	优先搜索
race / generation	同名 .test.ts + deferred
Electron UI	tests/e2e/*.spec.ts
真实 runtime	config/scripts/*repro*.mjs
SSH	ssh-docker scripts/tests
terminal 性能	terminal-perf, tools/terminal-*
startup/idle	tools/benchmarks
schema parity	*parity*.test.ts
old Git	Git compatibility matrix

7. 阅读大型文件的方法

以 35,000 行级的 orca-runtime.ts 为例：

1. 先 rg '^ (async )?[a-zA-Z].*\(' 建 public/private method 索引；
2. 搜索一个领域名，如 registerPty；
3. 记录它读写的 Map/Store；
4. 找调用者和 event listener；
5. 看紧邻测试中构造了哪些 race；
6. 最后读 surrounding comments 的 “Why”。

不要从第一行顺读到最后一行。大型 runtime 文件更像多个状态机共用一个资源所有者。

8. 关键术语表

术语	精确定义
Workspace	worktree 或 folder 的统一工作上下文
WorktreeMeta	Orca 对 Git worktree 的产品元数据
Pane Key	tabId:stableLeafId 逻辑 pane 身份
PTY ID	provider 可路由终端进程 id
Incarnation	同一 PTY ID 背后的物理进程代次
Terminal Handle	runtime 客户端地址，runtime-scoped
Graph Epoch	renderer 窗口图的一代发布
Publication Epoch	session tabs 主机发布世代
Host Revision	host-owned terminal membership 修订
Operation ID	一次副作用调用的重试身份
Claim	一个逻辑 Agent 会话的唯一执行身份
Authority	对某一资源事实拥有最终裁决权的一层

9. 从 Orca 可以复用的设计模式

Host-owned resource, client-owned presentation

适合终端、浏览器、远程文件等“UI 会消失但资源必须继续”的产品。

Unknown is a state

适合网络控制的副作用资源。不要把 timeout 自动解释为 not-created/dead。

Identity tuple + generation

资源地址之外，再加 host scope、generation、incarnation，抵御重连迟到事件。

Snapshot + sequence reconciliation

适合“需要全量恢复，同时实时流不能停”的场景。

Capability probe + narrow fallback

适合多版本 host、CLI、Git 或 relay；比只看版本号可靠。

Revision-fenced persistence

适合客户端可编辑 presentation、主机拥有成员关系的共享状态。

10. 继续深入的练习

1. 画出 TerminalPane mount 到 LocalPtyProvider.spawn 的完整调用图；
2. 找出一个 SSH connection generation 在 main 和 renderer 的所有 admission 点；
3. 追踪 Codex hook 从安装配置到 AgentStatusEntry；
4. 模拟 PTY 在 spawn response 前 exit，列出每层保存的证据；
5. 比较 automation new-worktree run 与 orchestration worker start；
6. 找到 stale renderer session write 被 host revision rebase 的位置；
7. 从 CLI terminal read 追到 runtime headless emulator snapshot。

11. 全书结论

Orca 最值得学习的不是某个 UI 或 provider，而是一套一致的所有权语言：

• 工作目录属于执行 host；
• PTY 属于 provider；
• 终端模型属于 host，xterm 是 view；
• Agent 状态属于 hook authority；
• 会话恢复先证明唯一 owner；
• 客户端发送意图，不能凭旧 snapshot 创造资源事实；
• 任何网络不确定副作用都需要 operation、claim 或 revision 保护。

一旦抓住这条主线，数千个文件就不再是平铺的复杂度，而是围绕工作空间、终端和远程控制三个核心资源展开的防线。