Agent Orchestrator 的 OMP 适配器:从交互式 TUI 会话到 Chat 模式的完整接入指南
Agent Orchestrator 的 OMP 适配器:从交互式 TUI 会话到 Chat 模式的完整接入指南
Agent Orchestrator(下文简称 AO)将 OMP(Pi Coding Agent)同时以交互式 Terminal UI harness 与结构化 Chat harness 两种形态接入会话系统,并在 session worktree 内直接启动用户自己安装的 omp 二进制。本文以 docs/harnesses/omp.md 为骨架,结合 omp 适配器源码 与测试用例,完整讲解 OMP 的安装解析、版本契约、启动参数、活动追踪、会话恢复与认证探测机制。读完你可以理解 AO 如何在不侵入 OMP 的前提下获得其会话与审批生命周期状态,并能独立排查接入问题。
OMP 适配器的定位与接入形态
OMP 是一个终端优先(terminal-first)的编码 harness。AO 的 OMP 适配器遵循这一特性:它在会话终端窗格中交互式地启动 OMP,而不是通过协议级的 RPC/ACP 集成来控制它。这一点在适配器的包注释中写得很明确:
OMP is a terminal-first coding harness, so AO launches it interactively inside the session terminal pane and keeps protocol-level RPC/ACP integration out of this adapter.
适配器通过 registry.go 中的 omp.New() 注册,实现了 ports.Agent、ports.AgentAuthChecker、ports.AgentBinaryResolver、ports.AgentInterfaceHandoffHistoryProbe 等多个端口,其 Manifest 能力为 CapabilityAgent(omp.go)。
OMP 的两种接入形态:
| 形态 | 说明 | 最低版本 |
|---|---|---|
| Terminal UI 模式 | 在会话终端中以 omp "<prompt>" 启动交互式 TUI,进程保持交互 |
OMP 17.1.0+(活动追踪契约) |
| Chat 模式 | 通过 OMP 原生 omp acp 命令在 AO 的 Chat 界面中运行 |
OMP 15.0.0+ |
安装 OMP 与二进制解析
安装与验证
OMP 需要用户自行通过其上游官方安装器安装,并确保 omp 二进制在 PATH 上。文档给出的常见安装路径:
curl -fsSL https://omp.sh/install | sh
brew install can1357/tap/omp
bun install -g @oh-my-pi/pi-coding-agent
安装完成后验证版本:
omp --version
AO 的二进制解析顺序
AO 通过 binaryutil.BinarySpec 描述 OMP 二进制的查找位置,按 "PATH 优先、固定候选路径兜底" 的顺序迭代(omp.go 中的 ompBinarySpec):
| 平台 | 解析位置 |
|---|---|
| 通用 | PATH 环境变量 |
| Unix | /usr/local/bin/omp、/opt/homebrew/bin/omp |
| Node 托管 | Node 管理的全局 bin 目录、~/.omp/bin/omp |
| Windows | %AppData%\npm\omp.cmd、%AppData%\npm\omp.exe |
解析结果是缓存的:Plugin.ompBinary 在首次成功解析后通过互斥锁保护缓存路径,后续启动与恢复直接复用,避免每次拉取重复探测。若 OMP 未安装,ResolveOMPBinary 返回包装后的 ports.ErrAgentBinaryNotFound。
版本契约:为什么必须升级到 OMP 17.1.0
AO 在安装其活动扩展之前会先校验 OMP 版本,因为追踪契约依赖 OMP 17 的生命周期与审批事件。校验逻辑位于 hooks.go 的 requireActivityContract:
- 以 10 秒超时执行
omp --version; - 用正则
\b(\d+)\.(\d+)\.(\d+)\b解析版本号; - 与
minOMPActivityVersion = "17.1.0"比较,低于该版本则报错activity tracking requires OMP 17.1.0 or newer。
这一点在 omp_test.go 的 TestGetAgentHooksRequiresOMP171LifecycleContract 中有一组清晰的边界用例:16.9.9 与 17.0.0 安装扩展失败,17.1.0 与 18.1.0 成功。换言之,旧版本必须升级,而不是在"不完整或误导性的 Kanban 状态"下继续运行。
启动方式与 AO 模式
OMP 通过 AO 的 Terminal UI 模式暴露。一个新会话的启动命令为:
omp "<prompt>"
当项目 agent 配置了对应字段时,AO 会追加转发:
--model <model>:来自 agent 配置的model字段(适配器通过 GetConfigSpec 报告model配置项,说明为 "Model override passed toomp --model");--append-system-prompt <text>:用于注入 AO 的角色/系统提示词。
appendSystemPrompt 支持内联文本与文件两种来源:若内联提示非空则直接使用,否则读取 SystemPromptFile 内容再传入(omp.go)。另外,启动命令会通过 --extension 显式传入受管扩展路径,使状态追踪不依赖 OMP 的扩展自动发现机制。
GetPromptDeliveryStrategy 返回 PromptDeliveryInCommand,即提示词以命令行参数方式交付(omp_test.go)。测试用例还验证了启动命令的参数拼接细节:
- 仅提示词:
omp add a health check; - 带扩展:
omp --extension <workspace>/.omp/extensions/ao-activity.ts add a health check; - 带系统提示与模型:
omp --append-system-prompt "follow repo rules" --model anthropic/claude-sonnet-4 implement it。
进程在初始提示之后保持交互,用户可以直接在 OMP TUI 中继续工作。
活动追踪:受管扩展与状态映射
扩展安装
AO 在 session worktree 内的 .omp/extensions/ao-activity.ts 安装一个受管扩展(GetAgentHooks),并在每次启动与恢复时通过 --extension 显式传入。安装过程有三个关键保障:
- 不覆盖用户文件:写入前先读取目标路径,若内容不含哨兵字符串
agent-orchestrator: managed omp activity extension,则报错refusing to overwrite non-AO file(测试 TestGetAgentHooksRefusesForeignManagedPath 验证了这一点); - 保留其他扩展:只管理自己的这一个文件;
- 写入 .gitignore:通过
EnsureWorkspaceGitignore将ao-activity.ts加入忽略清单,避免把 AO 生成的扩展提交进仓库。
扩展如何上报状态
扩展通过 spawnSync("ao", ["hooks", "omp", hookName]) 同步调用 AO CLI 的 hook 通道,把 OMP 原生事件转成 AO 可识别的 hook 名。它订阅了 7 个 OMP 事件:
| OMP 事件 | 上报 hook | 映射活动状态 |
|---|---|---|
session_start / session_switch |
session-start |
idle |
before_agent_start |
user-prompt-submit |
active |
tool_approval_requested |
permission-request |
waiting_input |
tool_approval_resolved |
permission-resolved |
active |
agent_end(且 !willContinue) |
stop |
idle |
session_shutdown |
session-end |
exited |
事件到状态的最终映射由 activity.go 的 DeriveActivityState 完成,并有 TestDeriveActivityState 覆盖全部 6 种事件(未知事件返回无信号)。
文档描述的生命周期语义与之一一对应:会话启动与回合完成上报 idle;/new、/resume、/fork 切换会立即刷新原生 resume ID 并上报 idle;提示词提交上报 active;审批请求上报 waiting_input;审批解决上报 active;进程关闭上报 exited。
尽力而为(best-effort)的 hook 传递
Hook 传递是尽力而为的:AO 可执行文件缺失、daemon 不可用或 hook 超时都不会打断 OMP 会话。扩展为每个同步调用设置了 1250ms 的超时(HOOK_TIMEOUT_MS = 1_250),注释说明这是因为 OMP 将 session_shutdown 处理器限制在 2 秒内,同步上报必须明显低于该预算,避免挂起的 hook 拖住 TUI 的关闭流程。扩展源码中对所有异常做了静默捕获,并在注释中强调 "Reporting is best-effort and must never interrupt the OMP session"。hooks 失败场景(ao 缺失、hook 超时)在 hooks_test.go 中有专门测试。
根会话隔离
只有顶层交互式 TUI 扩展会上报活动。扩展通过 isRootSession(ctx) 判断 ctx.hasUI === true,子代理虽然继承扩展路径,但其非 UI 扩展上下文被忽略——这样子代理既不能替换根会话的 resume ID,也不能把仍在运行的根会话标记为 exited。
会话恢复:--resume 与原生会话文件校验
当 AO 在会话元数据中捕获到 OMP 原生 session id 后,恢复命令为:
omp --resume <native-session-id>
恢复流程(GetRestoreCommand):
- 从
session.Metadata[MetadataKeyAgentSessionID]读取原生会话 id;为空则返回ok=false,由会话管理器回退到全新启动; - 组装
omp [--extension ...] [--append-system-prompt ...] [--model ...] --resume <id>; - 先验证会话文件是否存在:
NativeConversationExists在 OMP sessions 目录下递归查找文件名以_<id>.jsonl结尾的常规文件。sessions 目录取自PI_CODING_AGENT_DIR环境变量,未设置时回退到~/.omp/agent/sessions(omp.go); - 会话文件缺失或没有原生 session id 时,回退到新的交互式启动。
对应测试 TestGetRestoreCommandUsesNativeSessionID 验证了带 --resume 的完整命令拼装,TestNativeConversationExistsRequiresPersistedSessionFile 验证了"有文件返回 true、未知 id 返回 false、空白 id 返回 false"三种情形。
认证检查:本地信号探测
OMP 没有非交互式的 auth status 命令——把位置参数传给它会直接启动交互式 agent,因此绝不能用作认证探针。AO 只使用本地信号做检查(auth.go),流程如下:
- 配置目录解析:优先
PI_CODING_AGENT_DIR环境变量,否则~/.omp/agent; - 依次检查两个凭据存储:
<configDir>/agent.db:以只读方式打开 SQLite,统计auth_credentials表中data非空且disabled_cause为 NULL 的启用凭据数,大于 0 即判定authorized;<configDir>/auth.json:解析 JSON 映射,任一 provider 的key非空即判定authorized。
需要强调:这些凭据存储检查是建议性的(advisory)。后续真实模型调用仍可能因为配额、provider 配置或所选模型不可用而失败。文档中列出的检查路径(PI_CODING_AGENT_DIR/auth.json 与 ~/.omp/agent/auth.json)对应 auth.json 分支;源码实现在此基础上还增加了对 SQLite agent.db 的探测,两者都只做本地只读判断,不会触发任何交互流程。
Chat 模式:omp acp
OMP 15.0.0 及以上版本可通过其原生 omp acp 命令在 AO 的 Chat 界面中运行。与 TUI 模式不同,Chat 模式的活动状态直接从结构化的 turn、approval、input 与 controller 事件派生,而不是依赖 TUI 扩展。因此 Chat 会话不经过 .omp/extensions/ao-activity.ts 这条上报链路,也不受 17.1.0 活动契约的约束(Chat 模式的最低门槛是 15.0.0)。
不支持的边界
文档明确列出以下能力不在当前 OMP 适配器支持范围内:
- RPC 模式:
omp --mode rpc; - 现有 OMP 会话的 TUI→Chat 或 Chat→TUI 交接(interface handoff)。
这与适配器"保持协议级 RPC/ACP 集成在适配器之外"的定位一致。结合 docs/harnesses/pi.md 等其他 harness 文档,可以看到 AO 对不同 harness 采用"能原生结构化则结构化、不能则 TUI 化 + 扩展上报"的差异化接入策略。
结语与进一步阅读
OMP 适配器是 AO 多 harness 接入体系的典型样本:以用户的 omp 二进制为执行体,通过受管扩展捕获原生生命周期事件,以 best-effort 方式汇入 AO 的 hook 管道,从而在不打断 TUI 体验的前提下获得可靠的 Kanban/活动状态。若你想深入实现细节,可以继续阅读: