docs(roadmap): 补充 v0.2+ 扩展项与参考项目调研沉淀

2026-06-09 22:32:48 +08:00
parent 0c51bb78a6
commit 63c50e1fc7
2 changed files with 240 additions and 4 deletions
@@ -0,0 +1,180 @@
+# 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）留好接口。**
@@ -1,7 +1,7 @@
 # AG Core Roadmap

 > 定稿日期：2026-05-11
-> 最后更新：2026-06-09（Phase 3 完成）
+> 最后更新：2026-06-09（Phase 4 设计讨论收尾；扩展计划补充 v0.2+ 候选项）

 ## 愿景

@@ -166,13 +166,65 @@ graph BT

 ## 扩展计划（v0.2+）

-> 以下功能在 Phase 0 中已实现基础能力，后续可增量优化。
+> 以下功能在已完成的 phase 中已实现基础能力或在 Phase 4 阶段明确了边界，后续可按维度增量扩展。
+> 设计参考：见 `docs/note-agent-harness-references.md`（OpenClaw / Hermes / OpenHuman / OpenHarness 横向对比）。
+
+### 已有扩展项（沿用）

 | 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
 |-------|---------|------|--------|------|
 | Prompt Optimizer | `prompt` | 提示词自动优化 | P3 | 待实现 |
 | 流式接口优化 | `llm/stream` | 流式响应解析与事件化 | P0 | ✅ 已完成基础实现 |

+### v0.2+ 新增扩展项
+
+> 以下为基于 Phase 4 设计讨论确定的 v0.2+ 候选扩展方向，按维度分组。
+> 标注为"v0.2 待评估"表示在 Phase 4 完成后再决定是否启动。
+
+#### Multi-Agent / 协同
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| Multi-Agent 协同（Swarm） | `agent` | 子 Agent 委派、并行子任务、结果聚合 | P2 | v0.2 待评估 |
+
+#### 技能（Skills）
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| Markdown 技能按需加载 | `agent` / `prompt` | 兼容 `SKILL.md` 格式（Hermes / OpenHarness 风格），按 prompt 上下文动态加载 | P2 | v0.2 待评估 |
+
+#### 记忆（Memory）
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| 多通道检索（hybrid） | `memory/retriever` | 在 TextOverlap 之上叠加向量检索通道 | P2 | v0.2 待评估 |
+| KnowledgeGraph 深度记忆 | `memory` | 实体-关系图、`note-knowledge-graph-design.md` 已记录设计 | P3 | v0.2 待评估 |
+| TokenJuice 智能压缩 | `memory` / `llm/compact` | 借鉴 OpenHuman TokenJuice，对工具结果做语义压缩而非字节截断 | P3 | v0.2 待评估 |
+
+#### 交互层（TUI / Gateway）
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| TUI / 多平台 Gateway | 应用层 | OpenClaw / Hermes 风格的消息平台桥接（Feishu / Telegram / Discord 等） | P3 | v0.2+ 应用层 |
+
+#### 训练基础设施
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| RL 轨迹导出 | `agent` | ShareGPT 格式轨迹、Atropos 集成（Hermes 风格） | P3 | v0.3+ 探索 |
+
+#### 安全治理
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| Human-in-the-loop 审批 | `agent` / `tools/permission` | 高危工具执行前的异步审批回调（OpenHarness `permission_prompt` 模式） | P2 | v0.2 待评估 |
+
+#### 流式 / 实时
+
+| 扩展项 | 所在模块 | 说明 | 优先级 | 状态 |
+|-------|---------|------|--------|------|
+| 流式 `submit_turn` | `agent/session` | Phase 4 v1 只暴露非流式 `submit_turn()`；v0.2 包装 `LlmCycle::submit_stream` 暴露流式入口 | P2 | v0.2 待评估 |
+
 ---

 ## 风险与建议
@@ -181,13 +233,17 @@ graph BT
 2. **并行可能性**：Phase 0 和 Phase 1 可并行开展（无相互依赖），可加速早期交付
 3. **MCP 协议复杂性**：MCP 涉及协议握手、session 管理、长期连接，建议预留充足时间调研协议细节
 4. **Scope 蔓延风险**：当前 specs 只有 1 份文档，建议每个模块上线前都产出对应 spec，避免边实现边设计
+5. **Phase 4 抽象化边界**：AG Core 定位为"支持库"而非"Agent 产品"，Phase 4 需严格控制范围——只暴露 trait + 最小 reference impl，业务循环（多轮 turn 编排、记忆自动回写、Task 拆解策略）留给上层应用，避免与 OpenHarness / Hermes / OpenHuman 等已有 Agent 产品竞争实现细节。详细设计决策见 Phase 4 设计讨论记录（待 `docs/7-agent-runtime.md` 落盘）
+6. **参考项目语言差异**：OpenClaw / Hermes / OpenHarness 均为 Python/TypeScript 实现，OpenHuman 虽是 Rust + Tauri 但定位是桌面应用。借鉴时**只取架构模式**，不照搬具体实现（如 Pydantic 工具校验、SQLite Memory Tree、Node+Python 双进程等）

 ---

 ## 下一步行动

-1. **Phase 4 方案启动**：启动 Agent Runtime 设计（依赖 Phase 0/1/2/3，整合所有模块）
-2. **Phase 3 备用设计就绪**：`docs/note-knowledge-graph-design.md` 记录了 KnowledgeGraph、高级评分、RecallBased 淘汰等设计，Phase 4 可直接参考
+1. **Phase 4 设计讨论收尾**：Phase 4 范围已收窄为「`Agent` trait + `RuntimeBundle` 依赖注入容器 + `AgentSession` 实体/会话分离 + `TaskAgent` 双入口 + 记忆弱引用 + Hook 事件扩展 3 个」。决策记录已固化，待写 `docs/7-agent-runtime.md` 方案文档后启动编码实现
+2. **Phase 4 方案文档**：将 Phase 4 设计决策沉淀为方案文档，沿用 `docs/4-prompt-engineering.md` / `5-tool-system.md` / `6-memory-system.md` 的 6 段式结构，文件名 `docs/7-agent-runtime.md`
+3. **参考项目调研沉淀**：已完成 OpenClaw / Hermes / OpenHuman / OpenHarness 横向调研，结果沉淀至 `docs/note-agent-harness-references.md`，作为 v0.2+ 扩展项的输入
+4. **Phase 3 备用设计就绪**：`docs/note-knowledge-graph-design.md` 记录了 KnowledgeGraph、高级评分、RecallBased 淘汰等设计，v0.2+ 记忆扩展可直接参考

 **已完成阶段**：
 - ✅ Phase 0 Foundation — 全部交付物已完成