文件索引
Hermes Agent 仓库中关键文件的快速参考，按架构层次组织。 仅列出当前主分支上实际存在的文件。
核心层
文件路径 |
职责 |
|---|---|
|
AIAgent 主类、对话循环、流式调用、工具调度、预算控制 |
|
工具发现编排、异步桥接、调用链编排 |
|
工具集定义与组合解析、内置工具集常量 |
|
数据生成场景下的工具集概率分布配置 |
|
通用工具函数（原子 JSON 写入、环境变量判断等） |
|
SQLite 会话存储、FTS5 全文搜索、WAL 模式 |
|
全局常量（路径、URL、默认值）、 |
|
日志配置、session context 注入 |
|
时间格式化工具 |
|
CLI 交互式入口、REPL 循环、命令路由 |
|
批量任务运行器、检查点恢复 |
|
MCP 服务器模式入口 |
|
SWE 基准运行器，使用 Hermes 执行环境输出标准轨迹格式 |
|
RL 训练专用 CLI，扩展超时和专用系统提示词 |
|
轨迹后处理压缩，在保留训练信号的前提下缩减 token 数 |
Agent 子系统（agent/）
文件路径 |
职责 |
|---|---|
|
API 错误分类管线、FailoverReason 枚举 |
|
抖动指数退避算法 |
|
上下文窗口压缩、LLM 摘要生成 |
|
系统提示词构建、身份注入、安全扫描 |
|
Anthropic prompt 缓存控制（system_and_3 策略） |
|
多凭证管理、轮换策略、冷却机制 |
|
上下文引擎抽象层 |
|
技能元数据工具（YAML 解析、平台匹配） |
|
CLI 与网关共享的斜杠命令辅助（技能调用、/plan 等） |
|
Anthropic API 适配器（请求构建、响应归一化） |
|
AWS Bedrock API 适配器 |
|
Google Gemini Cloud Code Assist 适配器，OpenAI 兼容门面 |
|
GitHub Copilot ACP 服务器转发适配器 |
|
辅助任务统一路由（压缩、搜索、视觉等共用后端选择链） |
|
外部记忆提供者管理、单提供者限制 |
|
可插拔记忆提供者抽象基类（内置 + 插件式） |
|
模型元数据查询、Token 估算 |
|
Models.dev 注册表集成，4000+ 模型/109+ 提供者元数据 |
|
便宜/强力模型智能路由（关键词复杂度分析） |
|
API 速率限制追踪（x-ratelimit-* 头解析与展示） |
|
Nous Portal 跨会话速率限制守卫，防止 429 重试放大 |
|
Google Code Assist API 客户端（项目发现、引导、配额） |
|
Google OAuth PKCE 流程（Gemini CLI 认证） |
|
UI 显示辅助（spinner、工具预览） |
|
轨迹存储与格式转换 |
|
API 使用量统计与成本估算 |
|
异步自动生成短会话标题 |
|
上下文引用解析（文件路径、URL 提取与内容加载） |
|
手动压缩命令的用户反馈摘要 |
|
渐进式子目录上下文发现（AGENTS.md、CLAUDE.md 等） |
|
会话洞察引擎（用量统计、成本估算、工具模式分析） |
|
正则式密钥脱敏（日志与工具输出中的 API key/token 遮蔽） |
工具系统（tools/）
文件路径 |
职责 |
|---|---|
|
工具注册中心、自发现机制、schema 查询 |
|
MCP 客户端、动态工具发现、断路器、server 生命周期管理 |
|
子代理委派、预算共享 |
|
工具结果预算配置 |
|
终端命令执行、进程管理、多后端环境接口 |
|
文件读写、搜索、补丁工具 |
|
跨后端统一文件操作（本地/Docker/SSH/Modal/Daytona 等） |
|
8 策略模糊匹配链（处理 LLM 生成代码的空白/缩进差异） |
|
V4A 补丁格式解析器（codex/cline 兼容） |
|
Web 搜索与内容提取 |
|
浏览器自动化主工具 |
|
Camofox 本地反检测浏览器后端（REST API 对接） |
|
Camofox 持久化浏览器 profile 状态管理 |
|
Chrome DevTools Protocol 直通工具（原生对话框、iframe 等） |
|
图像分析工具 |
|
程序化工具调用（PTC）：LLM 写 Python 脚本通过 RPC 调用工具 |
|
Mixture-of-Agents 多模型协作推理 |
|
跨平台消息发送（Telegram/Discord/Slack） |
|
结构化澄清问题（多选/开放题）交互工具 |
|
任务列表管理（分解复杂任务、跟踪进度） |
|
文件操作前的透明快照（影子 git 仓库），支持回滚 |
|
持久化记忆（MEMORY.md/USER.md），跨会话写入不刷新系统提示词 |
|
长期对话回忆（SQLite FTS5 搜索 + 摘要模型） |
|
FAL.ai 图像生成（多模型选择、放大） |
|
文本转语音（7 个提供者：Edge/ElevenLabs/OpenAI/MiniMax/Mistral/Gemini/NeuTTS） |
|
NeuTTS 本地合成辅助进程（独立进程，避免内存常驻） |
|
语音转文字（local faster-whisper/Groq Whisper/OpenAI Whisper） |
|
推送式语音交互模式（录音/播放/STT/TTS） |
|
Home Assistant 智能家居控制（实体列表/状态查询/服务调用） |
|
飞书文档内容读取工具 |
|
飞书文档评论操作（列表/回复/添加） |
|
RL 训练管理工具（Tinker-Atropos 集成、环境发现、WandB 监控） |
|
Nous 托管工具网关通用辅助（供应商透传） |
|
技能列表与查看工具（渐进式披露架构） |
|
技能创建/编辑/删除（程序化记忆管理） |
|
外部技能安全扫描器（静态分析 + 信任等级策略） |
|
技能中心源适配器（GitHub/官方/社区源） |
|
内置技能清单式同步（manifest 追踪、hash 比对） |
|
线程安全的工具中断信号 |
|
危险命令检测、审批提示与会话级许可状态 |
|
Tirith 预执行安全扫描（同形 URL、管道注入等） |
|
SSRF 防护（阻止请求私有/内部网络地址） |
|
网站访问策略（用户管理的 URL 黑名单） |
|
MCP 扩展包恶意软件检查（OSV API 查询） |
|
路径遍历检查辅助（resolve + relative_to 模式） |
|
ANSI 转义序列剥离（防止进入模型上下文） |
|
二进制文件扩展名常量（跳过文本操作） |
|
后台进程注册表（输出缓冲、状态轮询、崩溃恢复） |
|
大输出持久化（写入临时文件、上下文中替换为预览） |
|
工具后端选择共享辅助 |
|
共享调试会话基础设施（统一多工具的 DEBUG_MODE 逻辑） |
|
环境变量透传注册表（沙箱中的技能所需变量放行） |
|
远程终端后端的凭证文件/技能目录挂载注册 |
|
Cron 任务管理工具（压缩式动作接口） |
|
共享 OpenRouter API 异步客户端 |
|
MCP OAuth 2.1 客户端（PKCE 流程、token 持久化） |
|
MCP OAuth 状态中心管理器（跨进程 token 重载、401 去重） |
|
xAI HTTP 集成共享辅助 |
执行环境子目录（tools/environments/）
文件路径 |
职责 |
|---|---|
|
执行环境基类（spawn-per-call 模型、会话快照） |
|
本地执行环境（进程隔离、环境变量净化） |
|
Docker 执行环境（cap-drop ALL、资源限制、可选持久化） |
|
Singularity/Apptainer 容器环境（containall、可写 overlay） |
|
SSH 远程执行环境（ControlMaster 持久连接） |
|
Modal 云执行环境（Sandbox.create + exec） |
|
托管 Modal 环境（通过 tool-gateway） |
|
Modal 传输层共享执行流程 |
|
Daytona 云沙箱环境（持久化沙箱、启停管理） |
|
远程后端文件同步管理器（mtime+size 变更检测、事务同步） |
浏览器提供者子目录（tools/browser_providers/）
文件路径 |
职责 |
|---|---|
|
云浏览器提供者抽象基类 |
|
Browserbase 云浏览器提供者 |
|
Firecrawl 云浏览器提供者 |
|
Browser Use 云浏览器提供者 |
网关层（gateway/）
文件路径 |
职责 |
|---|---|
|
网关主进程、多平台集成与消息路由 |
|
会话管理、PII 脱敏、重置策略 |
|
会话上下文 contextvars（替代 os.environ 防并发污染） |
|
事件钩子系统（生命周期钩子注册与触发） |
|
网关配置定义（GatewayConfig、Platform、SessionResetPolicy） |
|
平台频道/联系人缓存目录（send_message 名称解析） |
|
投递路由（cron 输出与代理响应的目标选择） |
|
按平台显示/详细度配置解析器 |
|
跨平台消息投递镜像记录 |
|
DM 配对系统（一次性码审批流程、OWASP 安全特性） |
|
网关重启常量与 drain 超时解析 |
|
网关运行状态检测（PID 文件） |
|
Telegram 贴纸描述缓存（vision 工具结果复用） |
|
网关流式消费器（同步回调 → 异步平台消息编辑） |
内置钩子子目录（gateway/builtin_hooks/）
文件路径 |
职责 |
|---|---|
|
启动钩子：网关启动时执行 ~/.hermes/BOOT.md |
网关平台适配器（gateway/platforms/）
文件路径 |
职责 |
|---|---|
|
平台适配器基类（所有平台继承此类） |
|
平台共享辅助（去重、批量聚合、markdown 剥离、线程追踪） |
|
OpenAI 兼容 API 服务器（Chat Completions/Responses API/SSE 流） |
|
Telegram 适配器（python-telegram-bot） |
|
Telegram 网络辅助（主机名保留回退传输） |
|
Discord 适配器（discord.py） |
|
Slack 适配器（slack-bolt + Socket Mode） |
|
Signal 适配器（signal-cli daemon HTTP + SSE） |
|
WhatsApp 适配器（Business API / web 自动化多后端） |
|
Email 适配器（IMAP 接收 + SMTP 发送） |
|
SMS 适配器（Twilio REST API + webhook） |
|
通用 Webhook 适配器（GitHub/GitLab/JIRA/Stripe 等） |
|
飞书/Lark 适配器（WebSocket + Webhook、媒体缓存、去重） |
|
飞书文档评论事件处理 |
|
飞书文档评论访问控制规则（3 级解析） |
|
微信个人号适配器（iLink Bot API 长轮询） |
|
企业微信适配器（AI Bot WebSocket 网关） |
|
企业微信回调模式适配器（自建应用加密 XML 回调） |
|
企业微信 BizMsgCrypt AES-CBC 加解密 |
|
钉钉适配器（Stream Mode + 会话 webhook） |
|
Home Assistant 平台适配器（WebSocket 事件监听 + 通知） |
|
BlueBubbles iMessage 适配器（REST + webhook） |
|
Matrix 适配器（mautrix SDK，可选 E2EE） |
|
Mattermost 适配器（REST API + WebSocket） |
|
QQ Bot 适配器（官方 v2 WebSocket + REST API） |
|
QQ Bot 包级常量 |
|
QQ Bot AES-256-GCM 凭证解密 |
|
QQ Bot 扫码配置引导（QR 码生成与轮询） |
|
QQ Bot 共享工具（User-Agent、HTTP 辅助、配置转换） |
TUI 网关层（tui_gateway/）
文件路径 |
职责 |
|---|---|
|
TUI JSON-RPC 服务器、会话管理、乐观并发控制 |
|
持久化斜杠命令工作进程（stdin/stdout JSON-RPC） |
|
TUI 网关入口、异步 RPC 分发循环 |
|
流式响应渲染、消息格式化 |
CLI 层（hermes_cli/）
文件路径 |
职责 |
|---|---|
|
CLI 主入口、HermesCLI 类、argparse 分发 |
|
斜杠命令定义与自动补全（COMMAND_REGISTRY 中枢） |
|
YAML 配置加载与合并 |
|
认证管理、OAuth 流程、凭证搜索顺序 |
|
凭证池 auth 子命令 |
|
GitHub Copilot OAuth 设备码流程与 token 管理 |
|
钉钉设备流授权（QR 码扫描 + AppKey 获取） |
|
插件发现与加载 |
|
|
|
皮肤/主题引擎（YAML 驱动） |
|
Agent 回调函数（流式、工具进度） |
|
交互式设置向导（模型/终端/Agent/平台/工具） |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Hermes 卸载器（完全卸载 / 保留数据） |
|
多 profile 管理（隔离的 HERMES_HOME 实例） |
|
模型目录与验证辅助 |
|
提供者身份权威源（models.dev + Hermes overlays + 用户配置） |
|
运行时提供者解析（CLI/网关/cron 共享） |
|
按提供者的模型名归一化（slash/dot/hyphen 格式差异） |
|
模型切换管线（CLI 与网关 /model 共享） |
|
Codex 模型发现（API、本地缓存、配置） |
|
Nous 订阅托管工具能力辅助 |
|
平台注册表（平台元数据唯一真相源） |
|
技能配置（按平台/全局启用/禁用） |
|
技能中心 CLI 统一接口（hermes skills + /skills） |
|
工具配置（hermes tools 交互式启用/禁用） |
|
MCP 服务器管理 CLI（add/remove/list/test） |
|
记忆提供者配置向导 |
|
.env 文件加载辅助（凭证 ASCII 清洗） |
|
默认 SOUL.md 模板 |
|
欢迎横幅、ASCII art、技能摘要、更新检查 |
|
会话启动随机提示 |
|
ANSI 颜色工具（NO_COLOR 支持） |
|
共享 CLI 输出辅助（print_info/success/warning/error） |
|
Shell 补全脚本生成（bash/zsh/fish） |
|
curses 多选 UI 组件（工具/技能配置交互） |
|
剪贴板图片提取（macOS/Windows/Linux/WSL2） |
|
OpenClaw 迁移命令（hermes claw migrate） |
|
Web UI 服务器（FastAPI + Vite/React 前端） |
插件系统（plugins/）
文件路径 |
职责 |
|---|---|
|
上下文引擎插件发现（扫描子目录实现 ContextEngine ABC） |
|
记忆插件注册入口 |
|
Honcho 记忆提供者（client + session + CLI） |
|
Hindsight 记忆提供者 |
|
Holographic 记忆提供者（holographic + retrieval + store） |
|
Mem0 记忆提供者 |
|
ByteRover 记忆提供者 |
|
OpenViking 记忆提供者 |
|
RetainDB 记忆提供者 |
|
SuperMemory 记忆提供者 |
|
示例仪表盘插件（plugin_api） |
文件依赖关系
以下 Mermaid 图展示了关键文件之间的导入依赖关系：
flowchart TD
classDef start fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
classDef success fill:#dcfce7,stroke:#16a34a,color:#166534
classDef warn fill:#fef9c3,stroke:#ca8a04,color:#854d0e
classDef fail fill:#fee2e2,stroke:#dc2626,color:#991b1b
classDef info fill:#f1f5f9,stroke:#64748b,color:#334155
subgraph ENTRY["入口层"]
CLI["cli.py"]
GW["gateway/run.py"]
TUI["tui_gateway/server.py"]
end
subgraph CORE["核心层"]
RA["run_agent.py"]
HS["hermes_state.py"]
TS["toolsets.py"]
end
subgraph AGENT["agent/ 子系统"]
EC["agent/error_classifier.py"]
CC["agent/context_compressor.py"]
PB["agent/prompt_builder.py"]
PC["agent/prompt_caching.py"]
RU["agent/retry_utils.py"]
CP["agent/credential_pool.py"]
SMR["agent/smart_model_routing.py"]
AUX["agent/auxiliary_client.py"]
SU["agent/skill_utils.py"]
SRD["agent/subdirectory_hints.py"]
end
subgraph TOOLSYS["tools/ 工具系统"]
MT["model_tools.py"]
TR["tools/registry.py"]
TOOLS["tools/*.py"]
MCP["tools/mcp_tool.py"]
TTS["tools/transcription_tools.py"]
VIS["tools/vision_tools.py"]
end
subgraph GATEWAY["gateway/ 网关"]
GH["gateway/hooks.py"]
GS["gateway/session.py"]
GSC["gateway/session_context.py"]
end
CLI --> RA
GW --> RA
TUI --> RA
RA --> MT
RA --> EC
RA --> CC
RA --> PB
RA --> PC
RA --> RU
RA --> CP
RA --> SMR
RA --> AUX
MT --> TR
MT --> TS
TR --> TOOLS
MT --> MCP
PB --> SU
PB --> SRD
RA --> HS
GW --> GH
GW --> GS
GW --> GSC
AUX --> TTS
AUX --> VIS
class CLI,GW,TUI start
class RA,HS,TS success
class MT,TR,TOOLS,MCP,TTS,VIS warn
class EC,CC,PB,PC,RU,CP,SMR,AUX,SU,SRD info
class GH,GS,GSC fail
关键文件导入依赖关系
这个依赖图展示了 Hermes 的分层架构：CLI/网关层依赖核心层（run_agent.py），
核心层依赖子系统层（agent/ 包和 tools/ 包），子系统层之间保持松耦合。