Omnigent 架构分析报告（CodeGraph 源码知识图谱）

基于 CodeGraph 对仓库的完整索引（2,942 个文件）生成。所有符号引用、调用关系、 blast-radius（爆炸半径）数据均来自 CodeGraph 的 SQLite 知识图谱，非人工推断。

生成日期：2026-07-22

配套架构图：omnigent-architecture.svg

一、项目定位

Omnigent 是一个"多 Harness 编码 Agent 编排平台"——核心价值不是再造一个 AI Agent， 而是做编码智能体的统一控制平面 (Control Plane)：把 20+ 种编码 Agent抽象成统一的 Harness 适配器，在统一的 Server / 会话 / 权限 / 工具 / 策略框架下调度执行。

可以理解为 "编码 Agent 的 Kubernetes"：

• Server 是控制面
• Host/Runner 是数据面
• AgentSpec 是工作负载（声明式、可打包、可缓存）
• Harness 是运行时（Executor + Harness 两层适配）

二、规模与技术栈

单仓库 monorepo，CodeGraph 索引覆盖率 2,942 文件。

三、整体架构（分层）

┌─────────────────────────────────────────────────────────┐
│  客户端层  Web SPA · Electron · iOS(Swift) · Android(KT)  │
└──────────────────────────┬──────────────────────────────┘
                           │ HTTP / SSE / WebSocket
┌──────────────────────────▼──────────────────────────────┐
│  omnigent/server  (FastAPI + uvicorn 控制平面)            │
│   routes/ · auth · presence                              │
│   accounts · permission · policy                         │
└──────────────────────────┬──────────────────────────────┘
                           │ WebSocket Tunnel (runner 注册)
┌──────────────────────────▼──────────────────────────────┐
│  omnigent/runner + host  (数据面 / 守护进程)              │
│   transports/ws_tunnel · connect · local_server          │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│  omnigent/runtime  (执行编排核心)                         │
│   AgentCache · workflow · policies · prompt · caps        │
│   harnesses/_executor_adapter (HarnessApp 适配层)         │
├───────────────────────────────────────────────────────────┤
│  omnigent/inner  (20+ Harness 实现：_executor + _harness) │
│   claude · codex · cursor · copilot · antigravity · pi    │
│   goose · hermes · qwen · kimi · kiro · opencode · acp    │
│   claude_sdk · openai_agents_sdk · databricks             │
│   (+ 各 *_native TUI 变体)                                 │
├───────────────────────────────────────────────────────────┤
│  omnigent/tools  (工具体系) + omnigent/spec (AgentSpec)    │
│  omnigent/sandbox (bwrap/seatbelt/jobobject/seccomp)      │
│  omnigent/stores (9 个 SQLAlchemy 持久化)                  │
└─────────────────────────────────────────────────────────┘

👆 点击图片查看全屏大图

四、核心子系统解析

1. Harness 双层适配器体系（最关键的抽象）

omnigent/inner/ 里每个编码 Agent 都有 executor + harness 两个文件，共 20+ 对。 CodeGraph 探查发现的核心基类：

• Executor (omnigent/inner/executor.py) —— 把外部 Agent 的协议事件流翻译成统一的 ExecutorEvent（TextChunk / ReasoningChunk / ToolCall / ExecutorError…）。 ExecutorEvent 有 29 处消费，是全平台事件总线的事实标准。
• ExecutorAdapter (omnigent/runtime/harnesses/_executor_adapter.py) —— 把 Executor 适配成 HarnessApp，被 68 处 harness 文件继承。这是整个 Harness 体系的胶水层。

两种执行模式并存：

• "inner" 模式（claude_sdk_executor、codex_executor、openai_agents_sdk_executor…） —— 进程内/SDK 调用，Omnigent 直接驱动 LLM 循环和工具。
• "native" 模式（claude_native、cursor_native、pi_native…）—— 包装外部 TUI 进程， 通过 bridge / forwarder / hook 反向注入 Omnigent 的工具、策略、状态。

Harness 清单（omnigent/inner/）：claude · claude_sdk · claude_native · codex · codex_native · cursor · cursor_native · copilot · antigravity · antigravity_native · pi · pi_native · goose · goose_native · hermes · hermes_native · qwen · qwen_native · kimi · kimi_native · kiro_native · opencode_native · acp · openai_agents_sdk · databricks。

2. AgentSpec —— 声明式工作负载定义

Agent 是可打包、可缓存、可上传的制品：

• 定义在 YAML（omnigent/spec/），含 llm/model、tools、policies、子 Agent。
• 打包成 .tar.gz 存入 ArtifactStore（唯一真相源）。
• AgentCache (omnigent/runtime/agent_cache.py) 是两级缓存（内存 Spec + 磁盘解压目录）， 提供 load / replace(热更新) / evict。
• 安全细节：expand_env 默认 False——防止租户 Agent 的 ${VAR} 泄露 Server 进程环境里的 密钥到 spec 控制的 MCP/LLM 连接。只有 operator 模板 agent（session_id is None）才显式传 True。

3. 工具体系（多种工具来源）

omnigent/tools/ + omnigent/inner/tools.py 定义了工具类型层级：

FunctionTool · MCPTool · AgentTool · SelfAgentTool · InheritedTool · SkillTool · HandoffTool

SDK 侧 @tool 装饰器（sdks/python-client/omnigent_client/tools/_decorator.py）从函数签名 + Google 风格 docstring 自动推导 JSON Schema，挂载 TOOL_MARKER_ATTR 让框架扫描注册。后台工具走 sys_call_async（inbox 模式），而非标注 sync/async。

工具来源分层：builtins/（内置）· client_specified/（客户端指定）· local.py / local_callable.py（本地）· mcp.py（MCP 服务）。

4. Store 持久化（9 个 SQLAlchemy Store）

omnigent/stores/ 下全部插件化、SQLAlchemy 后端：

agent / conversation / comment / file / policy / permission / scheduled_task / host / account + artifact_store（文件系统）。

Server 启动时（omnigent/cli.py:server，行 3224）逐个实例化并注入 init_runtime()， 工作流代码通过 getter 访问——典型的依赖注入全局化模式。

5. 控制平面：Server + Host/Runner 隧道

• Server (omnigent/server/app.py:create_app) 是 FastAPI 应用，提供 routes、SSE 会话流 （session_stream）、WebSocket runner 隧道。优雅关停专门覆写了 uvicorn.Server.shutdown， 在 graceful window 之前 drain SSE 订阅者。
• Host/Runner (omnigent/host/、omnigent/runner/)：omnigent host <url> 把本机注册成 执行节点，通过 WebSocket tunnel 反连 Server；本地模式下 ensure_local_omnigent_server() 自动起一个本地 Server 并注册到 ~/.omnigent/local_server.pid，多个进程复用同一台机器的 Server。
• 三种认证姿态（omnigent/server/auth.py:resolve_auth_source）：本地单用户（loopback 默认）/ header 代理注入 / accounts 账号体系（含 OIDC）。loopback 绑定自动开启 single-user， fail-closed 的是非 loopback 部署。

6. 治理与安全

• Policies 引擎 (omnigent/runtime/policies/ + omnigent/policies/)：每轮 turn 可注入策略 评估，能读写 context.model 等。policy_modules 可配置加载自定义策略。
• 沙箱 (omnigent/sandbox/ + omnigent/inner/*_sandbox.py)：Linux 用 bwrap、macOS 用 seatbelt、Windows 用 JobObject、外加 seccomp 和 egress 出站代理——四平台执行隔离。
• 凭证代理 (omnigent/inner/credential_proxy.py + omnigent/server/accounts_*)：runner 用 Databricks OAuth 鉴权，凭证不落到 Agent spec。

五、值得注意的工程实践

1. 多端深度一致：深链接 omnigent://host/c/<id> 在 iOS(Swift DeepLink)、 Electron(deepLink.js)、Web 三端各自实现同一解析规则，连 http/https 推断（loopback→http） 都保持一致——有专门的 designs/desktop-deep-link.md。
2. 详尽的崩溃 UX：omnigent/cli.py:main（行 1582）第一件事是装 install_crash_handler， 把原始 traceback 换成品牌化崩溃页 + 一键预填 GitHub issue。还有 always-on CLI 诊断日志。
3. 部署矩阵：Docker（deploy/docker/entrypoint.py 是所有容器平台的统一入口）、Modal、 Railway、Render——Modal 部署刻意跑同一个 entrypoint 子进程，保持"所有平台走同一条代码路径"。
4. 设计文档驱动：designs/ 下 16+ 份设计文档（CUJ 分析、harness 能力 seam、可观测性、 发布自动化…），代码注释频繁指向设计文档而非 PR 号——与 CLAUDE.md 里 "注释描述场景不引用 PR 号"的规范一致。

六、潜在关注点（基于 CodeGraph 的 ⚠️ blast-radius 标记）

CodeGraph 的 blast-radius 分析标记了若干"无测试覆盖"的高扇入符号，值得优先补测试：

其中 ConversationStore 有 25 处调用方却无覆盖测试，是测试债务里风险最高的一项—— 任何改动的影响面都很广，且没有自动化回归保护。

七、关键调用路径索引（CodeGraph 检索锚点）

八、总结

这是一个工程化程度极高的 Agent 编排基础设施项目：它不追求单一 Agent 的能力，而是解决 "如何用一套统一的 Server/会话/权限/工具/策略/沙箱框架，安全地调度 20+ 异构编码智能体" 这个企业级问题。架构分层清晰（控制面/数据面/编排层/Harness 层），但 inner/ 下 Harness 实现 的体量（40+ 文件）是最大的复杂度集中点——每个外部 Agent 的协议漂移都会在这里产生维护成本。

优势：Harness 抽象统一（ExecutorEvent + ExecutorAdapter）、安全模型完善（沙箱+凭证代理+ 三姿态认证）、多端一致、部署矩阵成熟。

风险：ConversationStore 等核心 Store 缺测试覆盖；inner/ Harness 数量持续膨胀带来的 长期维护成本。