Hermes-Agent 源码架构分析报告

1. 项目总览

核心模块：agent / hermes_cli / plugins / gateway / tools / acp_adapter / tui_gateway / providers / cron

2. 模块详细分析

2.1 agent/ — 核心智能体模块（134 文件，~82,905 行）

项目心脏，负责完整的 AI 智能体对话循环。

2.1.1 对话引擎

2.1.2 系统提示与上下文

2.1.3 模型适配层

2.1.4 工具调度与安全

2.1.5 多模态能力

2.1.6 其他重要模块

2.2 hermes_cli/ — CLI 命令行模块（192 文件，~149,809 行）

终端交互界面的完整实现，是项目代码量最大的模块。

2.3 plugins/ — 插件系统（173 文件，~99,830 行）

通过目录结构实现的可插拔扩展体系。

2.3.1 模型提供方插件（29 个）

anthropic / openai-codex / deepseek / gemini / bedrock / azure-foundry / openrouter / xai / copilot / copilot-acp / custom / alibaba / alibaba-coding-plan / arcee / gmi / huggingface / kilocode / kimi-coding / minimax / nous / novita / nvidia / ollama-cloud / opencode-zen / qwen-oauth / stepfun / xiaomi / zai

2.3.2 其他插件类型

2.4 gateway/ — 网关/平台适配（65 文件，~71,234 行）

消息平台集成的核心，实现统一网关接入多个异构消息平台。

2.5 tools/ — 工具系统（106 文件，~84,715 行）

智能体可调用的全部工具实现。

2.6 acp_adapter/ — ACP 适配器（11 文件，~5,291 行）

Agent Client Protocol 适配器，实现编辑器集成（VS Code / Zed / JetBrains）。

2.7 tui_gateway/ — TUI 网关（10 文件，~15,508 行）

Terminal UI 网关，为桌面 GUI 客户端提供 JSON-RPC 服务。

2.8 其他模块

providers/（2 文件，~426 行）

cron/（9 文件，~6,322 行）

3. 关键架构特征

3.1 多入口统一内核

项目有 4 个独立运行入口，共享同一个 AIAgent 核心：

3.2 声明式工具系统

• tools/registry.py：所有工具在模块导入时自注册
• toolsets.py：工具按功能分组为 30+ 工具集，支持组合复用
• model_tools.py：轻量调度层，负责发现→过滤→分发

3.3 可插拔提供方体系

• providers/base.py：ProviderProfile 声明式基类
• 双层发现机制：内置 + 用户自定义，后者覆盖前者
• 通过 api_mode 字段自动路由到对应传输层

3.4 上下文引擎抽象

• agent/context_engine.py：定义 ContextEngine 抽象接口
• 第三方可通过 plugins/context_engine/ 替换压缩策略
• 生命周期：on_session_start → update_from_response → should_compress → compress → on_session_end

3.5 多传输协议支持

3.6 消息平台统一适配

• gateway/platforms/base.py：平台基类定义统一接口
• gateway/platform_registry.py：平台注册中心
• 20+ 消息平台共享核心工具集，平台差异通过额外工具集体现

3.7 安全纵深防御

• agent/tool_guardrails.py：工具调用护栏
• tools/approval.py / write_approval.py：文件写入/危险操作审批流
• tools/path_security.py：路径安全检查
• tools/tirith_security.py / threat_patterns.py：威胁模式检测
• agent/redact.py / secret_scope.py：敏感信息脱敏与作用域控制

3.8 多智能体协作

• agent/moa_loop.py：Mixture-of-Agents（参考模型汇聚后聚合）
• tools/delegate_tool.py / async_delegation.py：子智能体委派
• tools/kanban_tools.py / hermes_cli/kanban_*.py：看板多智能体协调系统

3.9 延迟优化策略

• 懒加载：大量 from X import Y 放在函数内部，避免冷启动开销
• AIAgent 代理模式：延迟导入
• 自注册发现：工具和提供方在模块导入时自注册

4. 模块间依赖关系

4.1 逐层调用逻辑

对话引擎链：cli.py → run_agent.py → agent/conversation_loop.py → model_tools.py → tools/registry.py

用户输入经 cli.py 解析后，run_agent.py 构造 AIAgent 实例并调用 run_conversation()。conversation_loop 在主循环中调用 model_tools.py 获取可用工具列表（通过 registry.py 查询），将工具 schema 随消息一起发送给 LLM。LLM 返回 tool_calls 后，conversation_loop 再次通过 model_tools → registry → 具体 tool handler 执行。

工具调度链：model_tools.py ← toolsets.py ← tools/registry.py

model_tools 是轻量调度层，向 toolsets.py 查询当前启用的工具集名称，再从 registry.py 按名称获取工具 schema 和 handler。三层各司其职：model_tools 管接口、toolsets 管分组、registry 管注册。

Gateway 消息链：gateway/run.py → gateway/platforms/* → run_agent.py

平台适配器收到消息后，通过 gateway/run.py 的 handle_message() 查找或创建会话，获取 AIAgent 实例，最终调用 run_agent.py 的 run_conversation()。所有平台共享同一个对话入口，差异仅在平台适配层处理。

TUI 链：tui_gateway/server.py → run_agent.py

桌面 GUI 通过 WebSocket 发送 JSON-RPC 请求，server.py 解析后直接调用 run_agent.py，并注册 stream_callback 回调，将流式事件推回 GUI。

ACP 链：acp_adapter/server.py → run_agent.py

编辑器通过 stdio JSON-RPC 发送请求，acp_adapter 映射工具权限后调用 run_agent.py，执行结果通过 stream_event 流式推回编辑器。

插件发现链：providers/init.py → plugins/model-providers/*

providers/init.py 懒加载扫描 plugins/model-providers/ 目录，每个提供方的 init.py 通过 register_provider() 自注册。用户自定义插件(~/.hermes/plugins/)覆盖同名内置插件。

4.2 链间协同：所有路径汇聚到 conversation_loop

4 条独立入口链（CLI / TUI / Gateway / ACP）最终都经过 run_agent.py 调用同一个 conversation_loop。这意味着无论消息从哪个平台进入，核心对话逻辑（系统提示组装 → LLM 调用 → 工具执行 → 重试/压缩）完全一致。平台差异仅在：

4.3 依赖关系类型说明

5. 各模块核心作用与场景调用时序

5.1 agent/ — 对话引擎：一次用户请求的完整旅程

核心作用：接收用户消息，调用 LLM 生成回复，执行工具调用，管理上下文窗口，直至产出最终响应。

场景：用户说"帮我搜索最新的AI论文并总结"

5.1.1 边界条件与默认策略

💡 提示

以下数值均为源码默认值，可通过 config.yaml 或启动参数覆盖

工具护栏策略：

5.2 plugins/ — 插件系统：无缝切换模型提供方

5.2.1 边界条件与默认策略

核心作用：声明式提供方注册与发现，让一条命令行参数就能切换底层模型后端。

场景：从 Claude 切换到 DeepSeek

双层发现机制：

5.3 gateway/ — 网关：一条飞书消息的处理旅程

核心作用：将20+异构消息平台统一适配为标准消息流，投递到同一个 AIAgent 内核。

场景：用户在飞书群里@机器人"帮我查一下明天日程"

5.3.1 边界条件与默认策略

5.4 tools/ — 工具系统：注册、发现、执行

5.4.1 边界条件与默认策略

核心作用：所有工具自注册到中央注册表，运行时按工具集过滤后暴露给LLM，LLM选择调用后由执行器统一执行。

场景：LLM决定执行一段Python代码

工具集组合复用示例：

5.5 acp_adapter/ — 编辑器集成：VS Code中的AI编程助手

核心作用：实现 ACP (Agent Client Protocol)，让编辑器通过 JSON-RPC 与 Hermes 交互。

场景：开发者在VS Code中选中代码，点击"Explain"

5.5.1 边界条件与默认策略

ACP 额外约束：ACP 通过 stdio 传输 JSON-RPC，工具权限由 acp_adapter 映射，不允许终端类工具。

5.6 tui_gateway/ — 桌面GUI：实时交互体验

核心作用：实现 TUI (Terminal/Text UI) 网关，让桌面 GUI 客户端通过 WebSocket JSON-RPC 与 Hermes 交互，提供实时流式输出、审批确认、斜杠命令等交互体验。

场景：用户在桌面终端 UI 中输入自然语言，TUI 通过 WebSocket 推送流式响应，用户可中断、切换模型、审批危险操作。

💡 提示

5.6.1 边界条件与默认策略

TUI 网关与 ACP/CLI/Gateway 共享核心对话循环，通用边界条件同 5.1.1 节。TUI 额外约束：

6. 多Agent场景深度解析

6.1 三种多Agent模式

Hermes 支持三种多智能体协作模式，覆盖从简单到复杂的不同场景：

6.2 Delegate 模式详解

核心机制：父Agent通过 delegate_task 工具创建子Agent，子Agent在隔离上下文中执行任务，结果回传给父Agent。

关键约束：

两种角色：

场景：用户说"重构这三个模块并写单元测试"

子Agent创建流程：

凭证继承优先级：

6.2.1 Delegate 边界条件与容错

🔴 提示

子Agent上下文完全隔离：禁止读取共享记忆、禁止与用户交互、禁止委派子任务

6.3 MoA（Mixture-of-Agents）模式详解

核心机制：多个参考模型独立回答同一问题，聚合器模型综合所有参考答案生成最终回复。

场景：用户问"这个架构方案有什么风险？"，需要多视角分析

MoA循环5步骤：

6.3.1 MoA 边界条件与容错

6.4 Kanban（看板协调）模式详解

Kanban 是 Hermes 中最复杂的多 Agent 协调模式，基于 SQLite 看板数据库实现跨进程的任务分配、状态跟踪和故障恢复。

6.4.1 Kanban Agent 生命周期

一次完整的 Kanban 任务生命周期：

1. 创建：用户通过 /kanban create 命令或 API 创建任务。初始状态为 running（立即分配）或 blocked（等待依赖）。每个任务写入 tasks 表，同时创建一条 task_runs 记录。

2. 分解：主 Agent 调用 /kanban decompose 将大任务拆分为子任务。子任务自动建立父子关系（task_links 表），子任务状态受父任务约束——若父任务 blocked，子任务自动设为 blocked。

3. 分发：dispatch_once() 在每个 tick 内：扫描 ready 状态任务 → 调用 spawn_fn 启动 Worker 进程 → 原子切换 ready → running 并写入 claim_lock + claim_expires。

4. 执行：Worker 进程持有 claim_lock，定期心跳更新 claim_expires。每条 task_runs 记录追踪独立执行的 PID、心跳、运行时长。

5. 完成/失败：Worker 调用 complete_task()（running|ready|blocked → done）或 block_task()（running|ready → blocked）。失败时根据退出码标记 crashed/timed_out/failed。

6.4.2 状态回退机制

Kanban 支持以下回退路径：

6.4.3 多 Agent 竞态处理

Kanban 在三个层面防止竞态：

1. 数据库层：SQLite WAL 模式提供单写者串行化。task_runs 表的 claim_lock 字段实现 CAS（Compare-And-Swap），两个 Worker 同时 claim 同一任务时，只有先写入 claim_lock 的成功。

2. 进程间锁：_dispatch_tick_lock() 基于文件锁实现跨进程互斥。同一个 kanban.db 不会有两个 dispatcher 并发 tick——孤儿 dispatcher 获取锁失败时返回 skipped_locked=True，不执行任何写操作。

3. 声明式约束：claim_task() 内部执行 ready → running 转换时，SQL WHERE 子句同时检查状态和 claim_lock 为空，确保原子性。索引 idx_tasks_assignee_status 加速同时查分配者和状态的场景。

6.4.4 三种模式对比

6.4.5 Kanban 边界条件

7. A2A 协议与 A2UI 协议说明

7.1 当前实现的Agent间通信机制

Hermes 目前没有实现标准化的 A2A 协议，但通过以下机制实现了Agent间通信：

7.2 Relay 中继：当前最接近 A2A 的机制

gateway/relay/ 是当前最接近 Agent-to-Agent 通信的机制，实现了跨进程的Agent协作。

核心设计：

Relay通信流程：

7.2.1 Relay 边界条件与容错

CapabilityDescriptor 字段：

7.3 A2A 协议设计建议（面向未来）

基于当前 Hermes 的架构，建议的 A2A 协议设计：

A2A 消息类型建议：

7.4 A2UI 协议：当前实现与设计建议

当前 UI 交互机制：

A2UI 事件类型：

Hermes 当前没有实现标准化 A2UI 协议，UI交互通过各入口的传输层直接处理（WebSocket JSON-RPC / stdio JSON-RPC / 平台SDK），不涉及Agent层协议设计。

7.5 三层协议边界总结

7.6 场景对照：不同协议在不同场景下的使用