第 1 章：产品与源码全景
1. 一句话定义
Orca 是一个面向并行 Agent 开发的跨平台 IDE 与运行时控制平面。
它不在内部实现一个统一的大模型循环，而是把 Claude Code、Codex、Gemini、OpenCode、Pi、Droid、Grok 等 CLI Agent 当作可托管进程。Orca 提供的是这些进程缺少的上层能力：
- 每个任务一个 Git worktree 或 folder workspace；
- 可分屏、可恢复、可远程的终端；
- Agent 运行状态、交互问题、通知与会话恢复；
- 源码编辑、diff review、GitHub/GitLab/Linear/Jira；
- 内嵌 Chromium、Design Mode 与 Computer Use；
- SSH、WSL、headless serve 与手机伴侣；
- 自动化调度和多 Agent 编排。
上游把它描述为 “Next-gen IDE for parallel agentic development”，这个描述比“AI 编辑器”更准确：它管理的基本单位不是文件，而是并行执行中的工作空间和 Agent 会话。
2. Orca 与 Pi 的问题域不同
| 维度 | Pi Agent | Orca |
|---|---|---|
| 核心职责 | 实现 Agent Loop | 托管外部 Agent CLI |
| 模型调用 | 自己抽象 provider | 交给各 Agent CLI |
| 工具执行 | 框架内 tool system | Agent 在 PTY 中自行执行 |
| 主要状态 | message / tool / turn | workspace / tab / pane / PTY / session |
| UI | TUI | Electron IDE + mobile |
| 远程能力 | 由运行环境提供 | 内建 SSH relay、runtime RPC |
| 并行方式 | 多实例或 orchestrator | worktree + 多终端 + orchestration |
所以拆解 Orca 时，不能套用“提示词 → LLM → tool call → message”的 Agent 框架模板。更合适的主线是：
3. 七层产品栈
可以把 Orca 理解成七层：
上层看起来是一个 IDE，下层实际上更像一个分布式进程控制系统。
4. 技术栈不是简单的 Electron + React
桌面与 UI
- Electron 43：窗口、主进程、preload 安全桥；
- React 19 + Zustand 5：renderer 与组合状态；
- xterm.js：终端 view；
- Monaco：编辑器；
- TipTap、React Markdown、KaTeX、Mermaid：富文档；
- Tailwind CSS 4 + Radix UI / shadcn：设计系统。
执行与协议
node-pty：本地 PTY；@xterm/headless：main/runtime 终端模型；ssh2+ 自研 relay：远程 Git、PTY 和文件能力；ws+tweetnacl：配对 runtime 的 WebSocket 与加密；- JSON-RPC 风格控制消息 + 二进制 terminal stream；
- SQLite：orchestration 等事务状态。
平台外延
- React Native + Expo：iOS/Android；
- CLI：同一 runtime RPC 的脚本入口；
- Electron headless
serve：没有桌面窗口也能成为执行主机； - 插件 worker：独立子进程与 capability 约束。
依赖全集可从 package.json 和 mobile/package.json 查看。
5. 源码的四个主世界
| 目录 | 角色 | 典型事实 |
|---|---|---|
src/main | Electron main 与主机服务 | PTY、Git、SSH、持久化、窗口、browser guest |
src/renderer/src | 桌面 UI 与客户端状态 | 导航、tab layout、xterm view、editor、review |
src/shared | 跨边界契约 | 类型、schema、身份、协议、兼容规则 |
src/cli | 运行时脚本客户端 | 命令规格、selector、RPC transport |
src/relay | SSH 远端服务 | PTY、Git、文件与通知处理 |
mobile | 手机客户端 | 配对、session tabs、terminal、browser、tasks |
src/shared 不是普通工具目录。它保存多进程必须共同理解的契约，例如 runtime-types.ts、terminal-stream-protocol.ts 和 agent-status-types.ts。
6. 产品能力背后的真实工程问题
6.1 并行不是“多开几个终端”
每个并行任务需要独立分支、文件系统、进程树、tab 布局、状态、来源 Issue、通知和恢复记录。Orca 用 worktree / folder workspace 把它们封装成一个可导航对象。
6.2 终端不是一个 React 组件
终端 view 可以被卸载、节流或崩溃，PTY 仍在持续输出。如果 renderer 是唯一状态源，后台 Agent 的大量输出会造成内存增长，重载后也无法恢复。因此 main/runtime 维护 headless terminal model，renderer 只是低延迟 view。
6.3 Agent CLI 没有统一协议
有的 Agent 接受位置参数，有的用 --prompt，有的只能启动后粘贴；hooks、transcript、resume 参数也完全不同。Orca 将差异收敛在 TUI_AGENT_CONFIG、各 provider hook service 和 transcript parser 中。
6.4 远程调用必须解决“重复启动”
网络超时不代表请求没有执行。一个“创建 Agent 会话”的响应丢失后，如果客户端重试并再次 spawn，就会产生两个并行 Agent。Orca 因此引入 operation id、claim、incarnation、host authority 和 replay fence。
6.5 多客户端同步不是简单覆盖
桌面、CLI 和手机都能关闭 tab、发送输入、切换 active tab。若客户端提交旧 snapshot，不能让已退出的 PTY“复活”。host topology revision 与主机裁决用于阻止 stale writer 改变终端成员关系。
7. Orca 的设计取向
从源码可以总结出五个反复出现的原则。
原则一：资源事实留在资源所在主机
文件、Git、PTY、browser guest 都由执行主机拥有。客户端传意图和 selector，不直接声明“某资源现在存在”。
原则二：身份比位置重要
paneKey、terminal handle、PTY incarnation、runtime id、connection generation 都用于跨重连保持或拒绝身份。路径、标题和数组下标只能做显示或弱匹配。
原则三：未知不等于不存在
SSH 断开时无法证明远程 PTY 已死，因此不能释放会话 claim 并启动替代进程。这是典型的 fail-closed 选择。
原则四：兼容通过能力探测完成
Git 新参数、runtime 新 RPC、relay 新 claim protocol 都有 capability 或窄错误匹配的 fallback，而不是只看版本字符串。
原则五：前台低延迟，后台有边界
终端前台输出尽量立即写入；后台输出、日志、缓存、hook body、plugin message、JSON payload 都有显式容量或时间限制。
8. 一条贯穿全书的示例
假设用户在 GitHub Issue 上点击“创建工作区并用 Codex 开始”：
- renderer 选择 Project/Repo 和执行主机；
- main/runtime 创建 Git worktree 并写入
WorktreeMeta； - renderer 建立 tab group、terminal tab 和稳定 leaf；
- PTY controller 选择 local/daemon/SSH provider；
- 为 Codex 预设 trust、账户 home 与 hook 环境；
- Codex 在 PTY 中启动，初始任务通过 argv 或 composer-ready 路径送达；
- hook server 接收工作/等待/完成事件，绑定到
paneKey； - runtime 将状态投影给桌面和移动端；
- 退出或重启时，workspace session 与 provider session 元数据被保存；
- 恢复时先证明原 PTY/agent session 的所有权，再 attach 或显式新建。
后续章节会逐层展开这 10 步。
9. 源码导航
- 产品说明：
README.md - 主进程入口：
src/main/index.ts - renderer 入口：
src/renderer/src/App.tsx - 总状态类型：
src/shared/types.ts - runtime 控制器：
src/main/runtime/orca-runtime.ts - CLI 入口：
src/cli/index.ts