源码导航地图
快速定位关键文件，按功能模块分类。
核心循环
| 文件 | 职责 | 行数(约) |
|---|---|---|
run_agent.py | AIAgent 类 — 核心对话循环、工具调度、会话持久化 | 9000+ |
cli.py | HermesCLI 类 — 交互式 CLI、prompt_toolkit 集成 | 3000+ |
model_tools.py | 工具编排层 — schema 收集、函数调用分发、async 桥接 | 1500+ |
toolsets.py | 工具集定义与解析 | 500+ |
Agent 内部 (agent/)
| 文件 | 职责 |
|---|---|
prompt_builder.py | 系统提示词组装 — 10+ 个注入源 |
context_compressor.py | 上下文压缩 — 三区策略 |
context_engine.py | 上下文引擎 — 插件化架构 |
memory_manager.py | 记忆管理器 — 多 Provider 协调 |
memory_provider.py | 记忆 Provider 抽象基类 |
prompt_caching.py | Anthropic Prompt Caching |
display.py | KawaiiSpinner、工具预览格式化 |
model_metadata.py | 模型上下文长度、token 估算 |
models_dev.py | models.dev 注册表集成 |
skill_commands.py | 技能斜杠命令（CLI/Gateway 共享） |
skill_utils.py | 技能工具函数 |
title_generator.py | 对话标题生成 |
trajectory.py | 轨迹保存辅助 |
anthropic_adapter.py | Anthropic 模型适配器 |
gemini_native_adapter.py | Gemini REST API 适配器 |
gemini_cloudcode_adapter.py | Gemini Cloud Code 适配器 |
bedrock_adapter.py | AWS Bedrock 适配器 |
codex_responses_adapter.py | Codex Responses API 适配器 |
transports/ | 传输层抽象（统一响应格式） |
工具系统 (tools/)
| 文件 | 职责 |
|---|---|
registry.py | 中央工具注册中心（无依赖，所有工具文件导入） |
terminal_tool.py | 终端执行 — 6 种后端环境 |
file_tools.py | 文件读写搜索补丁 |
file_operations.py | 文件操作辅助 |
web_tools.py | Web 搜索/提取/爬取 |
browser_tool.py | Browserbase 浏览器自动化 |
delegate_tool.py | 子 Agent 委托派遣 |
mcp_tool.py | MCP 客户端协议集成 |
mcp_oauth.py | MCP OAuth 认证 |
mcp_oauth_manager.py | MCP OAuth 令牌管理 |
code_execution_tool.py | execute_code 沙箱 |
memory_tool.py | 记忆读写工具 |
todo_tool.py | Todo 列表工具 |
clarify_tool.py | 澄清问题工具 |
send_message_tool.py | 消息发送工具 |
skill_manager_tool.py | 技能管理工具 |
skills_tool.py | 技能查看/执行工具 |
skills_hub.py | Skills Hub 集成 |
skills_sync.py | 技能同步 |
skills_guard.py | 技能安全守卫 |
cronjob_tools.py | 定时任务工具 |
tts_tool.py | 文本转语音 |
vision_tools.py | 视觉分析 |
image_generation_tool.py | 图片生成 |
approval.py | 危险命令检测 |
process_registry.py | 后台进程管理 |
environments/ | 终端后端实现（local, docker, modal, ssh, daytona, singularity） |
网关 (gateway/)
| 文件 | 职责 |
|---|---|
run.py | 网关主循环 — 消息路由、斜杠命令、事件分发 |
session.py | SessionStore — 会话持久化 |
config.py | 网关配置 |
delivery.py | 消息投递 |
hooks.py | 网关钩子 |
mirror.py | 跨平台消息镜像 |
pairing.py | DM 配对 |
platforms/base.py | 平台适配器基类 |
platforms/telegram.py | Telegram 适配器 |
platforms/discord.py | Discord 适配器 |
platforms/slack.py | Slack 适配器 |
platforms/whatsapp.py | WhatsApp 适配器 |
platforms/signal.py | Signal 适配器 |
platforms/matrix.py | Matrix 适配器 |
platforms/dingtalk.py | 钉钉适配器 |
platforms/feishu.py | 飞书适配器 |
platforms/wecom.py | 企业微信适配器 |
platforms/weixin.py | 微信适配器 |
platforms/email.py | Email 适配器 |
platforms/sms.py | SMS 适配器 |
TUI (ui-tui/ + tui_gateway/)
| 文件 | 职责 |
|---|---|
ui-tui/src/app.tsx | 主状态机和 UI |
ui-tui/src/gatewayClient.ts | JSON-RPC 客户端 |
ui-tui/src/entry.tsx | TTY 检测 + render() |
tui_gateway/server.py | Python RPC 服务 |
tui_gateway/entry.py | stdio 入口 |
tui_gateway/slash_worker.py | 斜杠命令工作进程 |
CLI 子命令 (hermes_cli/)
| 文件 | 职责 |
|---|---|
main.py | 入口 — 所有 hermes 子命令 |
config.py | DEFAULT_CONFIG、OPTIONAL_ENV_VARS、迁移 |
commands.py | COMMAND_REGISTRY — 斜杠命令定义 |
callbacks.py | 终端回调（clarify、sudo、approval） |
setup.py | 交互式设置向导 |
skin_engine.py | 皮肤/主题引擎 |
skills_config.py | hermes skills 子命令 |
tools_config.py | hermes tools 子命令 |
models.py | 模型目录、Provider 模型列表 |
model_switch.py | /model 切换管线 |
auth.py | Provider 凭证解析 |
配置与基础设施
| 文件 | 职责 |
|---|---|
hermes_state.py | SessionDB — SQLite 会话存储 |
hermes_constants.py | 全局常量、get_hermes_home() |
hermes_logging.py | 日志配置 |
hermes_time.py | 时间工具 |
cron/scheduler.py | Cron 调度器 |
cron/jobs.py | Cron 作业定义 |
按功能查找
"我想了解..."
├── 对话是怎么循环的 → run_agent.py → run_conversation()
├── 工具是怎么注册的 → tools/registry.py → register()
├── 工具是怎么被调用的 → model_tools.py → handle_function_call()
├── 系统提示词怎么组装的 → agent/prompt_builder.py → build_system_prompt()
├── 上下文是怎么压缩的 → agent/context_compressor.py → compress()
├── 记忆是怎么存储的 → agent/memory_manager.py + hermes_state.py
├── 技能是怎么加载的 → agent/skill_commands.py → scan skills/
├── 消息平台怎么对接的 → gateway/platforms/base.py → BasePlatformAdapter
├── 子Agent怎么创建的 → tools/delegate_tool.py → delegate_task()
├── 模型是怎么切换的 → hermes_cli/model_switch.py + agent/transports/
├── 配置怎么管理的 → hermes_cli/config.py → DEFAULT_CONFIG
├── 斜杠命令怎么注册的 → hermes_cli/commands.py → COMMAND_REGISTRY
└── 定时任务怎么执行的 → cron/scheduler.py → tick()