Hermes Agent 架構(gòu)設(shè)計(jì)與目錄結(jié)構(gòu)解析
Hermes Agent 架構(gòu)與目錄詳解
1. 總體架構(gòu)
從主執(zhí)行鏈來看,這個(gè)項(xiàng)目可以概括成下面這條主線:
用戶入口 -> hermes / hermes_cli.main -> 選擇 CLI / TUI / Gateway / ACP / Dashboard / 其他子命令 -> 構(gòu)造或恢復(fù) AIAgent -> AIAgent.run_conversation() -> model_tools.get_tool_definitions() -> tools.registry + tools/* -> 模型返回 tool calls / text -> 工具執(zhí)行結(jié)果回灌消息歷史 -> 會(huì)話/記憶/日志/狀態(tài)落盤
關(guān)鍵架構(gòu)分層:
- 入口層
hermeshermes_cli/main.py
- Agent 核心層
run_agent.pyagent/
- 工具層
model_tools.pytoolsets.pytools/
- 狀態(tài)層
hermes_state.py~/.hermes/config.yaml~/.hermes/.env
- 交互層
cli.pyui-tui/tui_gateway/gateway/acp_adapter/hermes_cli/web_server.py
2. 核心執(zhí)行鏈說明
2.1 統(tǒng)一入口
hermes- 只是一個(gè)極薄的啟動(dòng)包裝器。
- 真正入口是
hermes_cli.main:main。
hermes_cli/main.py- 項(xiàng)目總調(diào)度入口。
- 負(fù)責(zé):
- profile 提前注入
- 讀取
.env - 初始化日志
- 構(gòu)建 argparse 子命令樹
- 分發(fā)到
setup / gateway / dashboard / cron / doctor / acp / skills / sessions ...
2.2 Agent 核心
run_agent.py- 項(xiàng)目最重要的核心文件。
- 定義
AIAgent。 - 負(fù)責(zé):
- 系統(tǒng)提示詞拼接
- 工具清單獲取
- 與 LLM 交互
- 處理 tool calls
- 上下文壓縮
- 記憶注入
- 會(huì)話持久化
- 中斷/重試/回退
- 軌跡保存
2.3 工具調(diào)度
model_tools.py- 是工具編排層,不直接實(shí)現(xiàn)工具。
- 負(fù)責(zé):
- 自動(dòng)發(fā)現(xiàn)
tools/*.py - 生成 tool schema
- 過濾不可用工具
- 統(tǒng)一派發(fā)執(zhí)行
- 同步/異步橋接
- 自動(dòng)發(fā)現(xiàn)
tools/registry.py- 工具注冊(cè)中心。
- 每個(gè)工具文件在 import 時(shí)通過
registry.register(...)自注冊(cè)。
toolsets.py- 定義工具集合。
- 例如
web、file、terminal、browser、delegation、hermes-cli、hermes-telegram等。
2.4 多入口交互
cli.py- 傳統(tǒng) CLI 的交互殼。
ui-tui/- React + Ink 的 TUI 前端。
tui_gateway/- TUI 的 Python 后端,負(fù)責(zé)和
AIAgent、會(huì)話、slash 命令交互。
- TUI 的 Python 后端,負(fù)責(zé)和
gateway/- 消息平臺(tái)網(wǎng)關(guān)。
- 一個(gè) Agent 可以掛到多個(gè)聊天平臺(tái)上。
acp_adapter/- 編輯器/ACP 協(xié)議接入。
hermes_cli/web_server.py- 本地 Web Dashboard 后端。
3. 頂層目錄作用
下表覆蓋倉(cāng)庫(kù)頂層主要目錄:
| 目錄 | 作用 |
|---|---|
.github/ | CI、Issue/PR 模板、GitHub 工作流配置。 |
.idea/ | 本地 IDE 配置,不屬于核心業(yè)務(wù)代碼。 |
.plans/ | 內(nèi)部計(jì)劃文檔,偏研發(fā)過程資料。 |
acp_adapter/ | ACP 協(xié)議適配器,給 VS Code / Zed / JetBrains 等編輯器集成使用。 |
acp_registry/ | ACP 相關(guān)元數(shù)據(jù)與圖標(biāo)。 |
agent/ | Agent 內(nèi)部能力模塊,負(fù)責(zé)提示詞、壓縮、記憶、模型元數(shù)據(jù)、顯示等。 |
assets/ | README 或產(chǎn)品展示圖片等靜態(tài)資源。 |
cron/ | 定時(shí)任務(wù)與調(diào)度器。 |
datagen-config-examples/ | 數(shù)據(jù)生成/訓(xùn)練相關(guān)配置樣例。 |
docker/ | Docker 運(yùn)行支持文件。 |
docs/ | 開發(fā)文檔、設(shè)計(jì)文檔、遷移文檔、計(jì)劃文檔。 |
environments/ | RL/訓(xùn)練環(huán)境,不是普通運(yùn)行時(shí) tools/environments/。 |
gateway/ | 消息網(wǎng)關(guān)主系統(tǒng)。 |
hermes_cli/ | CLI 命令、配置、安裝向?qū)?、狀態(tài)管理、dashboard 啟動(dòng)等。 |
nix/ | Nix/NixOS 打包與環(huán)境定義。 |
optional-skills/ | 可選技能庫(kù),按領(lǐng)域拆分。 |
packaging/ | 包管理與發(fā)布支持,當(dāng)前可見 Homebrew 打包。 |
plans/ | 計(jì)劃文檔、實(shí)現(xiàn)方案。 |
plugins/ | 插件機(jī)制相關(guān)內(nèi)容,如 memory provider、dashboard 插件等。 |
scripts/ | 安裝、測(cè)試、發(fā)布、橋接等腳本。 |
skills/ | 內(nèi)置技能庫(kù)。 |
tests/ | pytest 測(cè)試。 |
tinker-atropos/ | RL 訓(xùn)練相關(guān)子模塊。 |
tools/ | Agent 工具實(shí)現(xiàn)層。 |
tui_gateway/ | TUI 的 Python JSON-RPC 后端。 |
ui-tui/ | TUI 前端,React + Ink。 |
web/ | Web Dashboard 前端,Vite + React。 |
website/ | Docusaurus 文檔站,不是運(yùn)行時(shí)產(chǎn)品 UI。 |
4. 根目錄關(guān)鍵文件說明
| 文件 | 作用 |
|---|---|
README.md | 對(duì)外總說明,包含安裝、能力、快速開始。 |
AGENTS.md | 倉(cāng)庫(kù)級(jí)開發(fā)/協(xié)作說明,給 AI 助手和開發(fā)者使用。 |
pyproject.toml | Python 包定義、依賴、extras、腳本入口。 |
package.json | 根 Node 依賴,主要服務(wù)瀏覽器工具。 |
hermes | 輕量啟動(dòng)器。 |
run_agent.py | AIAgent 核心邏輯。 |
model_tools.py | 工具發(fā)現(xiàn)、過濾與統(tǒng)一派發(fā)。 |
toolsets.py | 工具分組定義。 |
cli.py | 傳統(tǒng)交互式 CLI 主邏輯。 |
hermes_state.py | SQLite 會(huì)話數(shù)據(jù)庫(kù)。 |
hermes_constants.py | 統(tǒng)一常量和 HERMES_HOME 路徑邏輯。 |
hermes_logging.py | 集中式日志初始化。 |
batch_runner.py | 批量運(yùn)行 Agent,偏研究/數(shù)據(jù)生成。 |
mcp_serve.py | MCP 相關(guān)服務(wù)入口。 |
mini_swe_runner.py | 更輕量的 SWE/任務(wù)運(yùn)行器。 |
setup-hermes.sh | Unix/WSL/macOS 開發(fā)安裝腳本。 |
requirements.txt | 輔助依賴列表。 |
5.agent/目錄詳解
agent/ 是把原本塞在 run_agent.py 的輔助能力拆出來后的核心模塊集。
關(guān)鍵文件:
| 文件 | 作用 |
|---|---|
prompt_builder.py | 組裝系統(tǒng)提示詞,注入身份、技能、上下文文件、平臺(tái)提示等。 |
context_compressor.py | 長(zhǎng)會(huì)話壓縮器,避免上下文超限。 |
context_engine.py | 上下文引擎抽象層。 |
memory_manager.py | 統(tǒng)一調(diào)度內(nèi)置記憶和外部記憶 provider。 |
memory_provider.py | 記憶 provider 抽象。 |
prompt_caching.py | Anthropic prompt caching 支持。 |
model_metadata.py | 模型上下文長(zhǎng)度、token 估算、模型元數(shù)據(jù)探測(cè)。 |
models_dev.py | provider-aware 模型目錄/上下文支持。 |
smart_model_routing.py | 智能模型路由策略。 |
auxiliary_client.py | 輔助模型調(diào)用,如視覺、摘要等。 |
display.py | CLI 展示、spinner、tool preview。 |
skill_commands.py | 技能相關(guān) slash command 邏輯。 |
skill_utils.py | 技能掃描、frontmatter、索引輔助。 |
trajectory.py | 軌跡保存與轉(zhuǎn)換。 |
usage_pricing.py | 使用量和成本估算。 |
retry_utils.py | API 重試與退避。 |
error_classifier.py | API 錯(cuò)誤分類與回退依據(jù)。 |
credential_pool.py | 多憑證池管理。 |
title_generator.py | 會(huì)話標(biāo)題生成。 |
redact.py | 脫敏。 |
整體作用:
- 讓
AIAgent不至于把所有輔助邏輯都塞在一個(gè)文件里。 - 但目前
run_agent.py仍然非常大,說明拆分還未徹底完成。
6.tools/目錄詳解
tools/ 是項(xiàng)目執(zhí)行能力的真正落地點(diǎn)。
6.1 核心基礎(chǔ)設(shè)施文件
| 文件 | 作用 |
|---|---|
registry.py | 工具注冊(cè)中心。 |
terminal_tool.py | 終端執(zhí)行工具,支持多后端。 |
file_tools.py | 讀寫/搜索/patch 文件。 |
process_registry.py | 后臺(tái)進(jìn)程管理。 |
tool_result_storage.py | 工具結(jié)果落盤與預(yù)算控制。 |
approval.py | 危險(xiǎn)命令檢測(cè)與審批。 |
interrupt.py | 中斷信號(hào)。 |
path_security.py | 路徑安全控制。 |
patch_parser.py | patch 解析。 |
tool_backend_helpers.py | 工具后端選擇與公共邏輯。 |
6.2 主要能力型工具
| 文件 | 作用 |
|---|---|
web_tools.py | Web 搜索/提取/爬取。 |
browser_tool.py | 瀏覽器自動(dòng)化。 |
vision_tools.py | 圖像理解。 |
image_generation_tool.py | 圖片生成。 |
code_execution_tool.py | 在沙箱里執(zhí)行可調(diào)用工具的 Python。 |
delegate_tool.py | 生成子代理執(zhí)行子任務(wù)。 |
mcp_tool.py | 外部 MCP server 工具接入。 |
memory_tool.py | 記憶工具。 |
todo_tool.py | 待辦/計(jì)劃工具。 |
session_search_tool.py | 歷史會(huì)話搜索。 |
send_message_tool.py | 跨平臺(tái)消息發(fā)送。 |
cronjob_tools.py | 定時(shí)任務(wù)管理。 |
tts_tool.py | 文本轉(zhuǎn)語(yǔ)音。 |
transcription_tools.py | 語(yǔ)音轉(zhuǎn)文本。 |
homeassistant_tool.py | Home Assistant 集成。 |
skills_tool.py / skill_manager_tool.py | 技能列表、查看、管理。 |
mixture_of_agents_tool.py | 高級(jí)推理/多代理融合能力。 |
rl_training_tool.py | RL 訓(xùn)練相關(guān)工具。 |
6.3tools/environments/
這是終端后端實(shí)現(xiàn),不要和倉(cāng)庫(kù)根目錄 environments/ 混淆。
| 文件 | 作用 |
|---|---|
local.py | 本地執(zhí)行。 |
docker.py | Docker 環(huán)境。 |
ssh.py | SSH 遠(yuǎn)程環(huán)境。 |
modal.py / managed_modal.py | Modal 云環(huán)境。 |
daytona.py | Daytona 環(huán)境。 |
singularity.py | Singularity 環(huán)境。 |
file_sync.py | 跨環(huán)境文件同步。 |
base.py | 終端后端抽象。 |
7.gateway/目錄詳解
gateway/ 是一個(gè)完整子系統(tǒng),作用是把 Hermes 暴露到聊天平臺(tái)。
關(guān)鍵文件:
| 文件 | 作用 |
|---|---|
run.py | 網(wǎng)關(guān)主循環(huán)與生命周期管理。 |
config.py | 平臺(tái)配置模型。 |
session.py | 平臺(tái)會(huì)話上下文與會(huì)話路由。 |
session_context.py | 會(huì)話變量和上下文注入。 |
delivery.py | 消息投遞路由。 |
status.py | 網(wǎng)關(guān)狀態(tài)。 |
pairing.py | 配對(duì)和權(quán)限控制。 |
hooks.py | 網(wǎng)關(guān)事件鉤子。 |
restart.py | 平滑重啟邏輯。 |
stream_consumer.py | 流式輸出消費(fèi)。 |
channel_directory.py | 平臺(tái)頻道/房間目錄解析。 |
7.1gateway/platforms/
這里是一組平臺(tái)適配器。
代表性文件:
base.py- 平臺(tái)適配器基類。
telegram.py- Telegram 適配。
discord.py- Discord 適配。
slack.py- Slack 適配。
whatsapp.py- WhatsApp 適配。
signal.py- Signal 適配。
matrix.py- Matrix 適配。
email.py- Email 適配。
homeassistant.py- Home Assistant 適配。
webhook.py- Webhook 適配。
api_server.py- OpenAI 兼容 API Server 適配器。
8.hermes_cli/目錄詳解
這是“命令與配置中樞”,偏控制面。
關(guān)鍵文件:
| 文件 | 作用 |
|---|---|
main.py | CLI 統(tǒng)一主入口與命令樹。 |
config.py | 配置默認(rèn)值、遷移、配置文件路徑。 |
setup.py | 交互式安裝向?qū)А?/td> |
commands.py | slash 命令注冊(cè)表。 |
auth.py | Provider 憑證解析。 |
gateway.py | CLI 對(duì)網(wǎng)關(guān)管理命令的包裝。 |
doctor.py | 診斷命令。 |
status.py | 狀態(tài)匯總命令。 |
model_switch.py | 模型切換流程。 |
models.py | 模型目錄。 |
skills_hub.py | 技能 Hub 命令面。 |
skills_config.py | 技能啟用/禁用配置。 |
tools_config.py | 工具啟用/禁用配置。 |
skin_engine.py | 皮膚/主題系統(tǒng)。 |
web_server.py | Web Dashboard 的 FastAPI 服務(wù)。 |
profiles.py | 多 profile 支持。 |
plugins.py | 插件發(fā)現(xiàn)與調(diào)用。 |
memory_setup.py | 記憶后端安裝與配置。 |
logs.py | 日志查看命令。 |
backup.py | 備份與恢復(fù)。 |
9.ui-tui/與tui_gateway/
這兩個(gè)目錄共同組成新的 TUI 體系。
9.1ui-tui/
這是前端界面層,React + Ink。
ui-tui/src/ 主要子目錄:
| 子目錄 | 作用 |
|---|---|
app/ | TUI 主狀態(tài)機(jī)、事件處理、slash 處理。 |
components/ | Ink 組件。 |
domain/ | 領(lǐng)域?qū)ο笈c純邏輯。 |
hooks/ | 輸入、隊(duì)列、補(bǔ)全、歷史等 hooks。 |
lib/ | RPC、消息、文本、OSC52 等工具函數(shù)。 |
protocol/ | 與后端交互協(xié)議輔助。 |
types/ | 類型定義。 |
__tests__/ | TUI 單元測(cè)試。 |
關(guān)鍵文件:
src/entry.tsx- TUI 前端入口。
src/app.tsx- 主 UI 狀態(tài)與組件裝配。
src/gatewayClient.ts- 啟動(dòng) Python 子進(jìn)程并通過 stdio JSON-RPC 通信。
9.2tui_gateway/
這是 TUI 的 Python 后端。
| 文件 | 作用 |
|---|---|
entry.py | stdio JSON-RPC 入口。 |
server.py | 請(qǐng)求處理、session 管理、Agent 調(diào)用。 |
render.py | 可選 ANSI 渲染橋。 |
slash_worker.py | 持久化 slash 命令子進(jìn)程。 |
10.acp_adapter/
作用:
- 把 Hermes 作為 ACP Agent 暴露給編輯器。
- 讓編輯器通過協(xié)議和 Hermes 交互,而不只是啟動(dòng)一個(gè)命令行。
關(guān)鍵文件:
| 文件 | 作用 |
|---|---|
entry.py | ACP 入口。 |
server.py | ACP Agent 服務(wù)器實(shí)現(xiàn)。 |
session.py | ACP 會(huì)話管理。 |
tools.py | ACP 可暴露的工具。 |
permissions.py | 權(quán)限控制。 |
events.py | 事件處理。 |
auth.py | 認(rèn)證。 |
11.cron/
作用:
- 管理定時(shí)任務(wù)定義、調(diào)度與執(zhí)行。
關(guān)鍵文件:
| 文件 | 作用 |
|---|---|
jobs.py | 定時(shí)任務(wù)存取。 |
scheduler.py | 周期性掃描并執(zhí)行 due jobs。 |
12.environments/
這個(gè)目錄是研究/RL 環(huán)境,不是普通用戶日常 CLI 的終端后端。
關(guān)鍵文件:
| 文件 | 作用 |
|---|---|
hermes_base_env.py | RL 環(huán)境基類。 |
agent_loop.py | 面向環(huán)境的 Agent 循環(huán)。 |
tool_context.py | 工具上下文橋接。 |
web_research_env.py | Web Research 環(huán)境。 |
agentic_opd_env.py | 代理型 OPD 環(huán)境。 |
README.md | 訓(xùn)練環(huán)境說明。 |
子目錄:
benchmarks/- benchmark 配置。
hermes_swe_env/- SWE 類環(huán)境。
terminal_test_env/- 終端測(cè)試環(huán)境。
tool_call_parsers/- 工具調(diào)用解析器。
13.skills/、optional-skills/、plugins/
13.1skills/
內(nèi)置技能庫(kù),按領(lǐng)域劃分,例如:
software-development/research/productivity/github/apple/smart-home/creative/data-science/mcp/
每個(gè)技能通常包含:
SKILL.md- 可選
references/ - 可選
scripts/ - 可選
templates/
13.2optional-skills/
可選技能包,說明這些技能不一定默認(rèn)啟用,偏擴(kuò)展或?qū)I(yè)領(lǐng)域。
13.3plugins/
當(dāng)前可見主要是:
memory/- 多種記憶后端 provider。
context_engine/- 上下文引擎插件。
example-dashboard/- dashboard 插件示例。
14.web/與website/的區(qū)別
這兩個(gè)目錄容易混淆。
web/
- 運(yùn)行時(shí) Web Dashboard 前端。
- Vite + React。
- 配合
hermes_cli/web_server.py工作。
website/
- Docusaurus 文檔站。
- 用于發(fā)布官網(wǎng)文檔,不是用戶運(yùn)行時(shí)控制臺(tái)。
15.tests/
tests/ 數(shù)量很多,說明項(xiàng)目工程化程度較高。
特點(diǎn):
- 大量
gateway/測(cè)試,說明消息平臺(tái)是重點(diǎn)能力。 - 有
tui_gateway/、平臺(tái)適配器、API server、session、config、memory、tools 等測(cè)試。 - 倉(cāng)庫(kù)明確要求優(yōu)先用
scripts/run_tests.sh跑測(cè)試,以保持和 CI 一致。
16. 架構(gòu)總結(jié)
這個(gè)項(xiàng)目的目錄結(jié)構(gòu)體現(xiàn)出 3 個(gè)非常鮮明的事實(shí):
- 它不是一個(gè)單體 CLI,而是一個(gè)多入口代理平臺(tái)。
- 其核心價(jià)值不在 UI,而在
AIAgent + Tools + Session + Gateway。 - 它已經(jīng)具備“平臺(tái)型代碼庫(kù)”特征,因此理解時(shí)必須按子系統(tǒng)切分,而不能按單文件線性閱讀。
到此這篇關(guān)于Hermes Agent 架構(gòu)設(shè)計(jì)與目錄結(jié)構(gòu)解析的文章就介紹到這了,更多相關(guān)Hermes Agent 架構(gòu)內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章,希望大家以后多多支持腳本之家!
相關(guān)文章

深度對(duì)比OpenClaw,Claude Code與Hermes Agent的AI Agent記憶系統(tǒng)架構(gòu)設(shè)計(jì)
本文將深入對(duì)比三個(gè)代表性項(xiàng)目的記憶系統(tǒng)設(shè)計(jì),OpenClaw(通用 Agent 框架)、Claude Code(編程 Agent)和 Hermes Agent(自進(jìn)化 Agent),它們分別代表了三種不同的設(shè)計(jì)哲2026-05-30
Hermes Agent 從部署到項(xiàng)目實(shí)戰(zhàn)完整操作指南
本文詳細(xì)介紹了龍蝦桌面助手Hermes 客戶端從安裝到配置,以及常用的場(chǎng)景演示,本文通過圖文并茂的形式給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,2026-07-07
從環(huán)境準(zhǔn)備到網(wǎng)關(guān)啟動(dòng),Hermes Agent的安裝每一步都可能報(bào)錯(cuò),本文將手把手幫你解決WSL2安裝失敗、Node.js版本沖突、API 502錯(cuò)誤等核心問題,讓你少走彎路,快速搞定開發(fā)環(huán)境2026-07-07
Hermes Agent 桌面版安裝部署完全指南:一步步安裝自進(jìn)化Agent智能體
Hermes Agent 是由 Nous Research 開發(fā)的開源自主 AI 智能體(MIT 協(xié)議),這篇文章給大家介紹Hermes Agent 桌面版安裝部署完全指南:一步步安裝自進(jìn)化Agent智能體,感興趣2026-07-02
Ollama 一條推文直接炸了 AI 圈 ——Ollama 0.21 版本原生支持 Hermes Agent,這次 Ollama 直接把門檻砍到了地板上,真一行命令一鍵完成,零基礎(chǔ)小白也能 5 分鐘擁有自己的2026-06-25
Hermes Agent 是當(dāng)前最前沿的開源 AI 智能體框架之一,這篇文章主要介紹了Hermes從裸版到AI Agent天花板配置的相關(guān)資料,文中通過圖文以及代碼介紹的非常詳細(xì),需要的朋友可以2026-06-25
Docker部署Hermes Agent的踩坑與最佳實(shí)踐
本文基于 M5 MacBook Air 32G 上使用 Colima 運(yùn)行 Docker 虛擬機(jī)的實(shí)戰(zhàn)經(jīng)驗(yàn),介紹如何在 Docker 中部署 Hermes Agent,解決數(shù)據(jù)持久化、權(quán)限隔離、工具環(huán)境保留等關(guān)鍵問題2026-06-24
Hermes Agent代碼倉(cāng)庫(kù)打包工具repomix-rs的使用指南
repomix-rs 是一款將整個(gè)代碼庫(kù)打包為 AI 友好單文件的工具,它能同時(shí)適用于 Hermes Agent、Claude、ChatGPT、Gemini 等主流大模型應(yīng)用場(chǎng)景,下面小編就和大家詳細(xì)講講具體如2026-06-15
最近在開源 Agent 圈里,Hermes Agent 的名字反復(fù)出現(xiàn)在各種討論中,有人戲稱它為愛馬仕 Agent,這篇文章將從零開始部署 Hermes Agent 并接入飛書的完整過程做一個(gè)系統(tǒng)梳理2026-06-14
Hermes Agent接入QQ的超詳細(xì)實(shí)戰(zhàn)指南
Hermes Agent 可通過 QQ Bot 官方接口接入,實(shí)現(xiàn)一個(gè)具備記憶、工具調(diào)用與自動(dòng)執(zhí)行能力的智能 QQ 機(jī)器人,通過 Gateway 轉(zhuǎn)換消息協(xié)議,將 QQ 消息接入 Agent 與大模型處理,2026-06-11











