Meta-Harness 核心 7 设计

1统一的 Executor 契约

整个 meta-harness 的基石 —— 一个抽象接口,归一化所有异构后端。

class Executor:
    async def run_turn(
        messages: list[Message],   # 异构 JSON dict,带 "role"
        tools: list[ToolSpec],     # JSON-Schema 工具定义
        system_prompt: str,
        config: ExecutorConfig,
    ) -> AsyncIterator[ExecutorEvent]

无论底层是 Claude SDK、codex CLI 还是 OpenAI Agents:

• 输入统一归一化成 (messages, tools, system_prompt, config)
• 输出统一归一化成一条 ExecutorEvent 事件流

2归一化的事件词汇表

后端再异构,都得把原生对象翻译成这套固定事件 —— 所有 harness 必须"说同一种话"。

3能力声明(协商差异,不抹平)

后端能力天差地别,用一组布尔标志让上层据此决定控制流。

supports_streaming()               # 是否流式
handles_tools_internally()         # 自己跑工具循环?(Claude SDK=True)
supports_live_message_queue()      # 能否回合中途插话
supports_tool_boundary_interrupt() # 能否在工具边界打断
max_context_tokens()               # 上下文窗口

4子进程隔离 — 每对话一个 harness 进程

工程上最硬核的一条。契约:一个对话 = 一个 harness 子进程,独立 Unix socket,懒启动。

父进程 ──spawn──> python -m omnigent.runtime.harnesses._runner
                   --harness codex --socket conv-<id>.sock --parent-pid N
                 子进程内:import 模块 → create_app() → uvicorn 绑 UDS
父进程 ──httpx over UDS──> 子进程

为什么不在进程内跑?

• 状态隔离:每对话独立 executor / SDK client,互不串
• 崩溃隔离:一个 harness 崩了只死一个对话
• 干净回收:进程退出即彻底清理,无内存泄漏
• native CLI 1:1 对应:每个终端 TUI session 配一个子进程

配套生命周期管理

父死子死:prctl(PDEATHSIG) + 看门狗线程每秒探活 空闲 30min 回收 reaper 启动孤儿清扫:lsof 找占 socket 的 pid → SIGTERM → SIGKILL /model 改模型 → 检测 env 变化 → 重启子进程

5ExecutorAdapter — 把任意 Executor 包成统一 REST 服务

所有 harness 的 create_app() 长一个样,只有 executor_factory 不同。

def create_app() -> FastAPI:
    adapter = ExecutorAdapter(executor_factory=_build_xxx_executor)
    return adapter.build()     # 四种 harness 只有 factory 不同

Adapter 暴露统一 REST 协议(单个 POST /v1/sessions/{id}/events 端点,用 type 区分): message / interrupt / tool_result / approval / policy_verdict。 它把 HTTP 请求翻成 run_turn() 调用,再把 ExecutorEvent 翻成 SSE 事件。

关键桥接 — 装在 executor 上的 3 个稳定回调(所有 harness 共用)

executor._tool_executor       = self._stable_tool_executor       # 工具分发桥
executor._policy_evaluator    = self._stable_policy_evaluator    # 策略往返桥
executor._elicitation_handler = self._stable_elicitation_handler # 审批回调

这三个桥就是横切能力(设计 7)接入每个 harness 的入口。

6native vs sdk 两种 harness 形态

同一个抽象下两种截然不同的接入方式 —— 这是 Omnigent 一个很聪明的设计。

7横切统一层 — 工具 / 策略 / 多 agent / 成本

抽象不只在接口:这些能力在 server / runner 端统一注入,与底层框架无关,对所有 harness 一致生效。