From 63c50e1fc7e125e6e0efc580e74a447e5544df2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Tue, 9 Jun 2026 22:32:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20=E8=A1=A5=E5=85=85=20v0.2+=20?= =?UTF-8?q?=E6=89=A9=E5=B1=95=E9=A1=B9=E4=B8=8E=E5=8F=82=E8=80=83=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E8=B0=83=E7=A0=94=E6=B2=89=E6=B7=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/note-agent-harness-references.md | 180 ++++++++++++++++++++++++++ docs/roadmap.md | 64 ++++++++- 2 files changed, 240 insertions(+), 4 deletions(-) create mode 100644 docs/note-agent-harness-references.md diff --git a/docs/note-agent-harness-references.md b/docs/note-agent-harness-references.md new file mode 100644 index 0000000..0ea1775 --- /dev/null +++ b/docs/note-agent-harness-references.md @@ -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, + 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）留好接口。** diff --git a/docs/roadmap.md b/docs/roadmap.md index 506f762..0254d17 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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 — 全部交付物已完成