Orca 如何托管 Pi 和 OMP

一个任务交给 Pi 实现，另一个任务交给 OMP 复核。两个 Agent 需要独立目录、稳定终端和可审查的 Git 改动。

Orca 把这些操作放进一个桌面工作台：它启动外部 Agent CLI，为每项工作创建 Git worktree，托管 PTY，并把 Diff 上的行级评论送回指定 Agent。

它没有接管 Pi 或 OMP 的模型循环。理解这一点，才能把三套系统的状态分清。

本章同时记录稳定版本和源码审计点：

stable:       v1.4.156
stable SHA:   e6b89208a69436bf856d572c4a17c98a4c1940d2
audited HEAD: 8f5a45401fc65b4052797b43d251d44c9c691769

下面涉及 Adapter、PTY 状态 Hook 与 Experimental Orchestration 的源码链接使用 audited HEAD。它是本次审计快照，不等于稳定发布版的承诺。

三个系统各自保存什么

层次	负责内容	典型状态
Pi Core	模型调用、Agent Loop、工具事件、Session 与 Extension API	message、tool call、session id
OMP	独立 CLI、配置目录、增强工具与定制发行层	`.omp/agent`、OMP session id
Orca	worktree、PTY、终端 Tab、Git Diff、Review、任务派发与通知	worktree id、terminal handle、pane key

pane key 是 Orca 用来定位某个终端窗格的身份键；它把状态事件送回正确的 Tab，不是 Pi/OMP 的 session id。

Orca 的 Agent registry 保存检测命令、启动命令、预期进程名和 Prompt 注入方式，不保存 Agent Loop。查看审计 HEAD 的 Adapter 配置类型。

Pi 与 OMP 是两个独立条目：

Pi 启动 pi，用 ORCA_PI_PREFILL 放入草稿；
OMP 启动 omp，用 ORCA_OMP_PREFILL 放入草稿。

查看 Pi 与 OMP 的注册配置。

因此，Orca 是 CLI Host 与工作台。模型选择、工具调用和推理过程仍发生在被启动的 Agent 内。

一个 Agent 如何被启动

1. 拼出外部命令

Orca 从 Agent registry 读取 pi 或 omp，叠加用户覆盖、CLI 参数和会话选项，生成最终 shell 命令。查看 launch command 的组合逻辑。

2. 创建终端 Tab

Renderer 根据 worktree、运行平台和 Prompt 交付方式创建终端，再把命令交给 PTY Host。Prompt 可以立即提交、等待界面 ready 后提交，也可以只放进输入框供人修改。查看 launch-agent-in-new-tab.ts。

等待 ready 很有必要。全屏终端程序启动期间可能还没有输入框，过早粘贴会把任务文本送进 shell 或首次启动菜单。

3. 安装托管 Extension

Pi 没有 Orca 所需的 settings hook 表面，因此 Orca 把自己的 TypeScript Extension 安装到 Agent 目录，用它上报：

before_agent_start
agent_start
tool_call
tool_execution_start / end
message_end
agent_settled / agent_end

查看 Pi/OMP 状态 handler 的事件表。

Pi 使用 ~/.pi/agent，OMP 使用 ~/.omp/agent。Orca 不会跨 Agent fallback，也只覆盖带管理标记的 Extension 文件，避免替换用户自己的代码。查看目录选择与覆盖保护。

4. 把状态投影回工作台

Extension 把事件连同 pane、tab、worktree 与 session identity 发给本机 Hook 服务。发送失败会被吞掉，不会让 Pi 的任务失败。查看 fail-open 的状态上报。

这意味着 Orca 暂时少一个状态点，不足以证明 Agent 已停止。还要检查终端、Git 改动和任务回执。

Worktree 能隔离什么

Git worktree 允许同一个仓库同时检出多个分支。每个 Agent 得到独立目录和 index，Git 对象库仍由主仓库共享。

Orca 创建新工作树时使用 git worktree add --no-track -b，已有分支则走不同路径；sparse worktree 创建失败时有有界回滚。查看 worktree 创建链。

Worktree 隔离的是 Git 文件状态，不是进程权限。Pi 或 OMP 仍可能读取进程权限允许的其他路径、环境变量与网络资源。涉及敏感仓库时，仍要配置最小权限和执行隔离。

删除也不是简单删目录。Orca 会重验注册与 lock，检查未提交和未跟踪文件，取得 watcher gate，停止属于该 worktree 的 PTY，再执行 git worktree remove。默认使用安全的 git branch -d，保留未合并工作。查看删除顺序。

脏 worktree 普通删除失败，是保护，不是 Bug。

终端恢复不等于任务恢复

Orca daemon 的 Session 持有 PTY 子进程、PID、前台进程、headless terminal emulator、connected clients、shell readiness 和有界输出缓冲。查看 daemon Session。

终端 Host 是状态来源，Renderer 只是 View。界面重新出现时，可以从 snapshot 和增量日志恢复屏幕。查看 terminal main-owned state 设计。

三种状态要分开：

状态	保存者	用途
Agent Session	Pi 或 OMP	恢复消息、工具上下文与 Agent 任务
PTY Process	Orca Host	继续运行外部 CLI
Terminal Snapshot	Orca	恢复用户看到的屏幕与滚屏

重新看到旧文字，只能说明显示状态恢复。Agent 是否还能继续原任务，要核对 Pi/OMP 的 session id 或 transcript。

Diff Review 怎样回到指定 Agent

Orca 使用 Git porcelain v2 读取状态，并处理 staged、unstaged、分支、commit、二进制与 submodule Diff。查看 Git Diff 实现。

行级评论保存 worktree id、文件路径、起止行、正文和 side。发送给 Agent 时转换成确定格式：

File: src/example.ts
Line: 42
User comment: 请为输入为空补一条测试。

查看评论格式化。

发送菜单会列出当前 worktree 中可写的 Agent Pane。只有 Prompt 实际交付后，Note 才会标记已发送。查看 Review Notes 交付逻辑。

离线实验：找出可以并行的 worktree

本仓库不要求安装 Orca。第 11 个 Lab 只检查路径冲突：

cd agent-harness-lab
npm run lab -- 11

四项任务中，Pi 笔记和 OMP 笔记写不同路径，可以并行；两项共同修改 README 的任务进入串行组。

预期观察：

{
  "parallel": ["pi-core-notes", "omp-notes"],
  "sequential": ["shared-index-a", "shared-index-b"],
  "conflicts": [
    {"left": "shared-index-a", "right": "shared-index-b", "path": "README.md"}
  ]
}

这条规则也适用于 Orca：拥有两个 worktree 不代表两个任务天然可合并。共享写路径仍需拆开或串行收口。

在 Orca 中做一次可视实验

先从 Orca 官方下载页安装桌面端，并确保 pi 与 omp 已经能在同一个终端中启动。macOS 也可以使用：

brew install --cask stablyai/orca/orca

打开一个无敏感数据的小仓库，创建两个 worktree：一个选择 Pi，一个选择 OMP。交给它们两条不会冲突的任务：

Pi：只创建 notes/pi.txt，写入 pi-ready。
OMP：只创建 notes/omp.txt，写入 omp-ready。

两个终端安静后，在各自 worktree 的终端执行：

git worktree list --porcelain
git status --short

保存四份观察：

要验证的能力	应保存的证据
Git 隔离	两份 `git status --short`，每份只出现自己的文件
进程托管	Pi 与 OMP Pane 的 PID 或运行状态
Review 回流	Diff 评论送达后的 `File / Line / User comment` 文本
删除保护	worktree 仍脏时的拒绝结果

git worktree list 和 git status 只能证明文件隔离，不能替进程托管与评论送达作证。四项证据都保存后，这次可视实验才通过。下一章再进入 Orca 的 Experimental Orchestration，把 task、dispatch 与人工 Gate 接到这两个 worktree 上。