# Agent Harness 参考项目调研笔记 > 调研日期：2026-06-09 > 用途：为 AG Core Phase 4（Agent Runtime）及后续 v0.2+ 扩展提供设计参考。 > 关联：`docs/roadmap.md` Phase 4 / 扩展计划（v0.2+）小节。 本笔记调研了 4 个 2026 年公开的 AI Agent 项目，对比其核心架构与 AG Core 已完成模块的交集，作为 Phase 4 设计与未来扩展的输入。 > **重要事实**：4 个项目**均非 Rust 写的**（OpenHuman 虽是 Rust + Tauri，但定位是 desktop 应用）。其价值不在"抄代码"，而在参考**经过生产验证的 Agent Harness 架构模式**。AG Core 处于"core 库"层，是这些项目"最底层依赖"的角色。 --- ## 1. 项目概览 | 项目 | 类型 | 语言 | GitHub | Stars（调研时） | 定位 | |------|------|------|--------|--------------|------| | **OpenClaw** | Gateway 网关 | TypeScript / Node 24 | `openclaw/openclaw` | — | 自托管消息平台 ↔ AI Agent 桥接 | | **Hermes Agent** | 自主学习智能体 | Python 3.11 | `NousResearch/hermes-agent` | — | 随使用成长的个人数字员工 | | **OpenHuman** | 桌面助手 | Rust + Tauri | `tinyhumansai/openhuman` | 2.3k+ | 记忆驱动的跨工具私人助理 | | **OpenHarness** | Agent Harness 框架 | Python | `HKUDS/OpenHarness` | 12.2k+ | 对标 Claude Code 的轻量级基础设施 | ## 2. 核心架构对照 | 维度 | OpenClaw | Hermes Agent | OpenHuman | OpenHarness | |------|----------|--------------|-----------|-------------| | **Agent Loop 形态** | 外部 Pi 二进制进程 | 内置 while 循环 | 内置循环 | 70 行 `run_query` | | **记忆模型** | 跨平台 session | MEMORY.md + 技能库 | Memory Tree（SQLite 分层摘要） | MEMORY.md + Auto-Compaction | | **工具机制** | MCP + 插件 | 40+ 内置技能 + 自动技能生成 | 118+ 集成 + Native Toolbelt | 43 工具 + BaseTool Pydantic | | **多 Agent** | 消息平台多 gateway | 并行子 Agent + RPC | Agent Coordination | Swarm 子代理委派 | | **权限/治理** | `allowFrom` + 提及规则 | 容器加固 + Cron 审批 | 本地优先 + 隐私 | 三级权限 + 钩子 | | **规划/任务** | 无显式规划 | 自然语言驱动 | 无显式 | 隐式（LLM 自我规划） | | **持久化** | 外部进程状态 | `~/.hermes/` 目录 | `~/.openhuman/` SQLite | MEMORY.md + state | | **Hook 体系** | 渠道适配器 | cron + 自定义钩子 | 集成触发 | PreToolUse / PostToolUse | | **干运行模式** | ❌ | ❌ | ❌ | ✅ `--dry-run` | | **流式 TUI** | ✅ 控制 UI | ✅ 完整 TUI | ✅ 桌面应用 | ✅ React/Ink | ## 3. 共同分层（5 层架构） 4 个项目都能切成这 5 层，**OpenHarness 的分层最清晰**： ``` ┌─────────────────────────────────────────────────────────────┐ │ L4 扩展层 多 Agent / 渠道网关 / 插件 / 任务调度 │ ├─────────────────────────────────────────────────────────────┤ │ L3 治理层 权限 / Hook / 审批 / 安全策略 │ ├─────────────────────────────────────────────────────────────┤ │ L2 知识层 提示词工厂 / 技能库 / 持久记忆 / 摘要 │ ├─────────────────────────────────────────────────────────────┤ │ L1 执行层 Agent Loop / 工具注册 / 流式事件 / 重试 │ ├─────────────────────────────────────────────────────────────┤ │ L0 模型层 LLM Provider / Provider Registry / 鉴权 │ └─────────────────────────────────────────────────────────────┘ ``` **关键观察**： - 4 个项目都假定 L0/L1 是"基础设施"，不在 core 层重新发明 - AG Core 在 Phase 0-3 已完成 L0 / L1 / L2（部分） / L3（部分） - Phase 4 处于 L1 与 L2 的衔接处 - L4（Multi-Agent / Gateway）属于应用层，应由上层 crate / 二进制承担 ## 4. AG Core 已具备的对应能力 对照 5 层架构，AG Core 已就绪情况： | 层 | AG Core 对应 | 完成状态 | 文档 | |----|------------|---------|------| | **L0 模型层** | `llm::provider` + `llm::ProviderRegistry` | ✅ Phase 0 | `docs/2-llm-call-lifecycle.md` | | **L1 执行层** | `llm::cycle` + `llm::stream` + `tools::ToolRegistry` | ✅ Phase 0/2 | `docs/5-tool-system.md` | | **L2 知识层** | `prompt` + `memory::store/conversation/knowledge/retriever` | ✅ Phase 1/3 | `docs/4-prompt-engineering.md` / `docs/6-memory-system.md` | | **L3 治理层** | `llm::hooks` + `tools::PermissionChecker` | ✅ Phase 0/2 | `docs/3-phase0-remaining.md` | | **L1→L2 衔接（Agent Runtime）** | — | ❌ **Phase 4 待实现** | — | ## 5. 借鉴到 Phase 4 的核心模式 ### 5.1 OpenHarness 风格：显式依赖注入容器 ```rust // 核心思想：所有运行时依赖打包成一个对象，沿调用链显式传递 pub struct RuntimeBundle { pub provider: Arc, pub tool_registry: Arc, pub hook_executor: Arc, // ... 可选：memory_store / retriever } ``` **好处**：测试时可注入 mock bundle；支持同时跑多 session；依赖关系显式可追踪。 **AG Core 决策**：采纳，命名为 `agent::RuntimeBundle`（详见 Phase 4 设计决策记录）。 ### 5.2 Hermes 风格：实体与会话解耦 ```rust pub trait Agent: Send + Sync { /* 角色定义，不绑定 session */ } pub struct AgentSession { /* 绑定 session_id + bundle + 状态 */ } ``` **好处**：同一 `Agent` 可被多个 `AgentSession` 复用（多用户、多会话）；session 状态（cost、turn index）独立追踪。 **AG Core 决策**：采纳，详见 Phase 4 §接口签名草案。 ### 5.3 OpenHarness 风格：Agent Loop 的极简本质 OpenHarness 的 `run_query` 核心只有 70 行，本质是一个 `while` 循环 + 一个 `if not tool_uses: return` 的判断。 **AG Core 现状**：`llm::cycle::submit_with_tools()` 已经在 Phase 2 末实现了这个循环，Phase 4 不应重新实现。 **AG Core 决策**：Phase 4 只在 `AgentSession::submit_turn()` 提供 30 行的 reference impl，组装 `LlmCycle` 并暴露其能力，业务循环留给上层。 ### 5.4 OpenHuman 风格：分层摘要记忆树 OpenHuman 的 Memory Tree 创新点： - 多源数据（Gmail / Slack / GitHub 等）→ 规范化 Markdown → ≤3k token chunks → 打分 → 折叠成 per-source / per-topic / per-day 摘要树 - 存储在本地 SQLite - Auto-fetch 每 20 分钟拉取新数据 **AG Core 现状**：`memory::KnowledgeStore` 已是 LLM Wiki 风格的抽象层。Phase 4 v1 不引入 SQLite 实现（属于 L4 应用层）。 **AG Core 决策**：v0.2+ 考虑 `note-knowledge-graph-design.md` 已记录的 KnowledgeGraph / RecallBased 淘汰等深度记忆能力。 ## 6. 反模式（不要照搬） | 反模式 | 出现项目 | 不要照搬的理由 | |--------|---------|--------------| | 双进程架构（Node UI + Python 后端） | OpenClaw | 应用层架构，core 库不涉及 | | SQLite 持久化细节 | OpenHuman | 属于 L4 应用层具体实现 | | Pydantic 工具校验 | OpenHarness | Python 生态强项；Rust 已有 `serde_json::Value` + JSON Schema，足够 | | 43 工具内置 | OpenHarness | 应用层选型，core 库应保持"零内置工具" | | 单进程内多平台消息网关 | OpenClaw / Hermes | 属于 L4 应用层 | ## 7. 与 AG Core 现有模块的接口对齐 下表列出 4 个项目中被 AG Core **已经覆盖**或**即将在 Phase 4 覆盖**的能力，避免重复造轮子： | 4 项目中的能力 | AG Core 对应 | 状态 | |--------------|-------------|------| | 工具注册表 | `tools::ToolRegistry` | ✅ Phase 2 已实现 | | 权限检查 | `tools::PermissionChecker` | ✅ Phase 2 已实现 | | 生命周期钩子 | `llm::HookExecutor` | ✅ Phase 0 已实现，Phase 4 扩展 3 个事件 | | 自动 tool 循环 | `llm::cycle::submit_with_tools()` | ✅ Phase 2 末已实现 | | Auto-Compaction | `llm::compact` | ✅ Phase 0 已实现 | | 对话记忆 | `memory::ConversationMemory` | ✅ Phase 3 已实现 | | 知识库 | `memory::KnowledgeStore` | ✅ Phase 3 已实现 | | 关键词检索 | `memory::MemoryRetriever` | ✅ Phase 3 已实现 | | 提示词模板 | `prompt::PromptTemplate` + `PromptComposer` | ✅ Phase 1 已实现 | | 用量追踪 | `llm::cycle::usage::CostTracker` | ✅ Phase 0 已实现 | | **显式依赖注入容器** | — | ⏳ **Phase 4 新增 `RuntimeBundle`** | | **Agent ↔ Session 分离** | — | ⏳ **Phase 4 新增 `Agent` + `AgentSession`** | | **任务规划** | — | ⏳ **Phase 4 新增 `TaskAgent` + `Plan`** | | **结构化 Plan 解析** | — | ⏳ **Phase 4 新增 `PlanParser` trait** | ## 8. v0.2+ 扩展项与参考项目的对应 `docs/roadmap.md` 扩展计划（v0.2+）表中的项，在 4 个项目中的对应实现： | 扩展项 | OpenClaw | Hermes | OpenHuman | OpenHarness | |--------|----------|--------|-----------|-------------| | Multi-Agent / Swarm | ❌ | ✅ 并行子 Agent | ✅ Agent Coordination | ✅ Swarm | | Markdown 技能 | ❌ | ✅ SKILL.md | ❌ | ✅ prompts/*.md | | 多通道检索（vector + keyword） | ❌ | ❌ | ✅ Memory Tree | ❌ | | KnowledgeGraph | ❌ | ❌ | ✅ Memory Graph | ❌ | | TokenJuice 智能压缩 | ❌ | ✅ 轨迹压缩 | ✅ TokenJuice | ✅ Auto-Compaction | | TUI / Gateway | ✅ 控制 UI | ✅ 完整 TUI | ✅ 桌面应用 | ✅ React/Ink | | 训练 / RL 轨迹 | ❌ | ✅ Atropos | ❌ | ❌ | | 人类审批（Human-in-the-loop） | ❌ | ✅ Cron 审批 | ❌ | ✅ 权限弹窗 | ## 9. 参考资源 - **OpenClaw 文档**： - **Hermes Agent 官网**： - **Hermes Agent GitHub**： - **OpenHuman GitHub**： - **OpenHuman 中文站**： - **OpenHarness GitHub**： - **OpenHarness 深度学习笔记**： ## 10. 一句话总结 > **4 个项目都不在 L0/L1 重新发明轮子——它们都假定基础设施已就绪。AG Core 在 Phase 0-3 已经把这 4 层全做完了。Phase 4 的核心价值是把它们"装配起来"，同时为未来 v0.2+ 的 L4 扩展（Multi-Agent / Skills / TUI）留好接口。**