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

```rust
// 核心思想：所有运行时依赖打包成一个对象，沿调用链显式传递
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 风格：实体与会话解耦

```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 文档**：<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）留好接口。**