agcore/docs/note-agent-harness-references.md

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 风格：显式依赖注入容器

// 核心思想：所有运行时依赖打包成一个对象，沿调用链显式传递
pub struct RuntimeBundle {
    pub provider: Arc<dyn LlmProvider>,
    pub tool_registry: Arc<ToolRegistry>,
    pub hook_executor: Arc<HookExecutor>,
    // ... 可选：memory_store / retriever
}

好处：测试时可注入 mock bundle；支持同时跑多 session；依赖关系显式可追踪。

AG Core 决策：采纳，命名为 agent::RuntimeBundle（详见 Phase 4 设计决策记录）。

5.2 Hermes 风格：实体与会话解耦

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 文档：https://docs.openclaw.ai/zh-CN
• Hermes Agent 官网：https://hermes-agent.org/zh/
• Hermes Agent GitHub：https://github.com/NousResearch/hermes-agent
• OpenHuman GitHub：https://github.com/tinyhumansai/openhuman
• OpenHuman 中文站：https://openhumanai.cn/docs/
• OpenHarness GitHub：https://github.com/HKUDS/OpenHarness
• OpenHarness 深度学习笔记：https://www.joyehuang.me/blog/20260410---openharnessphase1/post

10. 一句话总结

4 个项目都不在 L0/L1 重新发明轮子——它们都假定基础设施已就绪。AG Core 在 Phase 0-3 已经把这 4 层全做完了。Phase 4 的核心价值是把它们"装配起来"，同时为未来 v0.2+ 的 L4 扩展（Multi-Agent / Skills / TUI）留好接口。