Hermes Agent 源码架构全解剖

00全景架构：一颗 Python 心脏，多张「脸」

先建立整体心智模型。Hermes 与 Claude Code 最大的不同：它不只是一个「终端里的编程助手」，而是一个「跑在任何地方、从任何聊天软件都能召唤」的通用个人 agent。

Hermes 的本质是：一个 Python 类 AIAgent（run_agent.py:393，管理「调模型 → 执行工具 → 再调模型」的循环）+ 一个进程内工具注册表（tools/registry.py:208）+ 一堆可以互换的「外壳」——经典终端 REPL、Node/Ink 图形化 TUI、桌面 App、Telegram/Discord/Slack/WhatsApp/Signal 网关、cron 定时器、MCP server……全部外壳最终都调用同一个入口函数 run_conversation()（agent/conversation_loop.py:518）。

0.1 与 Claude Code 的五个根本差异

01一条消息的一生 ★

这是全文主线。以最常用的经典终端模式（hermes 敲一句话）为例，从按下回车到回复完整出现，共 12 站。每一站都在后面的章节有放大详解。

02启动流程：从 hermes 命令到可交互

Hermes 的入口比 Claude Code 复杂：不仅有交互聊天，还有 40+ 个子命令、TUI 的三段式进程链和首次运行向导。

2.1 入口链与 bootstrap 垫片

唯一的 console_scripts 入口定义在 pyproject.toml:307-308：hermes = "hermes_cli.main:main"。所有入口第一个 import 都是 hermes_bootstrap.py 这个「环境垫片」：Windows 强制 UTF-8 stdio（hermes_bootstrap.py:59-122）、harden_import_path() 把 cwd 从 sys.path 移除防止用户项目里的 utils/ 目录 shadow 掉 Hermes 同名模块（:125-158）、不可变 Docker 镜像下恢复 lazy-install 路径（:161-183）。

main()（hermes_cli/main.py:12686）的启动序列：设进程名 → 清理上次 hermes update 的残留 → Termux 快速路径 → 构建顶层 argparse。子命令 parser 拆在 hermes_cli/subcommands/ 的 39 个模块里，覆盖 chat / model / gateway / cron / skills / mcp / secrets / doctor / desktop / kanban / backup …。dispatch 尾部（main.py:14030-14155）：容器模式转发 → 顶层 --oneshot 拦截 → 裸 hermes 或 --resume 落到 cmd_chat(args)。

2.2 cmd_chat 的三岔口：经典 REPL / TUI / gateway

cmd_chat（main.py:2215）先跑首次运行守卫：没配任何 provider 就问「Run setup now? [Y/n]」进 setup 向导（main.py:2277-2306）。然后 _resolve_use_tui（main.py:2190-2212）决定界面：--cli 强制经典 REPL；--tui 或配置 display.interface: tui 走图形化 TUI；默认经典 REPL。

2.3 配置体系：HERMES_HOME + 两层 YAML + .env

HERMES_HOME 由 hermes_constants.py:55 的 get_hermes_home() 决定：环境变量 HERMES_HOME 优先，否则 ~/.hermes（Windows 用 %LOCALAPPDATA%\hermes）；支持 profiles/<name> 多 profile 隔离（hermes_constants.py:117-149）。配置顶层键覆盖 model / terminal / browser / compression / memory / skills / agent / delegation / display … 约 20 个大段（cli-config.yaml.example）。

对比 Claude Code 的五层 settings：Hermes 没有企业托管层与 flag 层，只有「用户 → 项目回落」两层 YAML + 环境变量覆盖，简单得多；换来的是每处配置读取要各自兜底默认值（cli.py:392-674 的内置默认块）。

2.4 首次运行 setup 向导

hermes setup（hermes_cli/setup.py:2716 run_setup_wizard）：备份旧配置 → 三选一「Quick Setup (Nous Portal) / Full setup / Blank Slate」（setup.py:2888-2896）。全向导由 SETUP_SECTIONS 驱动（setup.py:2622-2629）：model → tts → terminal → gateway → tools → agent 六段。模型段路由到 hermes_cli/model_setup_flows.py 里 14+ 个 provider 专属流程（openrouter:121 / nous:284 / anthropic:2834 / bedrock:2183 / copilot:1564…），Nous Portal 走 device-code OAuth。

会话 ID 形如 20260225_143052_a1b2c3（hermes_state.py:486）；会话消息全部落 SQLite，resume 时经 resolve_resume_session_id 沿「压缩 fork 链」找到真正持有最新消息的后代会话（hermes_state.py:3936-3990，第 7 章解释为什么压缩会 fork 会话）。

03Agentic 主循环：conversation_loop.py

整个产品的心脏。5294 行的 run_conversation() 里是一个 while 循环，每次迭代 = 一次「调模型 + 执行工具」的回合。

3.1 三段式结构：序幕 → 循环 → 收尾

调用关系
外壳（CLI / TUI gateway / 消息网关 / cron / 子agent）
 └─ AIAgent.run_conversation()          [run_agent.py 转发 → agent/conversation_loop.py:518]
     ├─ build_turn_context()            [turn_context.py]  回合序幕：清洗输入、恢复 system prompt、预检压缩、pre_llm_call hook
     ├─ while api_call_count < max_iterations and budget.remaining > 0:   [conversation_loop.py:633]
     │    调模型 → 解析 → 执行工具 → continue
     └─ finalize_turn()                 [turn_finalizer.py:30]  收尾：落盘、诊断、记忆/技能复盘触发

与 Claude Code 的「三层 async generator 流式吐消息」不同，Hermes 的循环是同步函数 + 回调：流式增量、工具进度、思考过程都通过构造 AIAgent 时注入的十几个回调（stream_delta_callback / tool_progress_callback / thinking_callback / clarify_callback…，run_agent.py:441-460）推给外壳。这让同一个循环能同时服务终端、Node TUI、Telegram、cron——外壳只需要换一组回调。

3.2 循环条件：双保险预算

agent/conversation_loop.py:633
while (api_call_count < agent.max_iterations and agent.iteration_budget.remaining > 0) or agent._budget_grace_call:

• max_iterations：每回合 API 调用上限，默认 90（run_agent.py:430）。
• iteration_budget：跨「父 agent + 子 agent」的全局迭代预算（agent/iteration_budget.py:17），子 agent 每个独立 50 次；execute_code 回合会 refund() 不计数。
• grace call：预算耗尽后再给模型「最后一次机会」收个尾（conversation_loop.py:649-659），避免生硬掐断。

3.3 一轮迭代的完整步骤

和 Claude Code 一样，「模型这轮有没有要工具」是唯一的续跑判据——没有计划器，agent 的「自主性」全部来自这个反馈循环。

3.4 System Prompt：三层结构 + 「一次构建、字节稳定」不变量

Hermes 的 system prompt 有一条铁律（agent/system_prompt.py:3-8）：每个会话只构建一次、之后逐字节复用，只有上下文压缩才触发重建——目的是让厂商侧 prompt cache 前缀永远命中。三层结构（system_prompt.py:10-21，组装在 build_system_prompt_parts :113）：

3.5 中断、/steer 与实时转向

• 中断：外壳把 agent._interrupt_requested 置位（终端 ESC、平台新消息均可触发），循环顶检查到即 break，带着部分结果走 finalize（conversation_loop.py:638-643）；正在等模型时则由 _interruptible_streaming_api_call 负责放弃流（run_agent.py:4734）。
• /steer 转向：Hermes 特色——agent 干活时你可以继续打字「改主意」。转向文本进入排队区，在下一次 API 调用组消息之前被排水注入（conversation_loop.py:695-750），模型本轮就能看到，不用等整个任务跑完。
• guardrail 强停：工具护栏（循环检测等）可以返回「controlled halt」，直接把本轮收掉并把原因作为 assistant 消息发给用户（conversation_loop.py:4672-4690）。

另有一个完全绕开默认循环的逃生门：api_mode == "codex_app_server" 时整个回合交给 OpenAI Codex app-server 子进程执行（终端/文件操作都在 Codex 内），Hermes 只做壳（conversation_loop.py:624-631）。

04工具系统

80+ 个工具、按 toolset 分组、文件 import 即自注册。一个工具 = JSON Schema + handler 函数 + 可用性探针 + 结果预算。

4.1 注册表：ToolEntry 与自注册

每个工具文件在模块底部调用 registry.register(...) 完成注册，例如四个文件工具（tools/file_tools.py:2170-2173）：

tools/file_tools.py:2170
registry.register(name="read_file", toolset="file", schema=READ_FILE_SCHEMA,
    handler=_handle_read_file, check_fn=_check_file_reqs, emoji="📖",
    max_result_size_chars=100_000)

ToolEntry（tools/registry.py:78-107）的字段就是工具的全部契约：schema（OpenAI function 格式的 JSON Schema，模型输入的唯一事实源）、handler（同步或异步，异步自动桥接）、check_fn（可用性探针——Docker 装没装、playwright 在不在，结果带 ~30 秒 TTL 缓存 + 抖动抑制，registry.py:110-135 注释）、max_result_size_chars（超限落盘阈值）、dynamic_schema_overrides（运行期改 schema 描述，比如 delegate_task 的描述要反映用户当前的并发上限配置）。注册表带 RLock 和「代数计数器」——MCP 动态刷新会在运行期改注册表，读者按代数做 memoize（registry.py:222-231）。

执行入口 registry.dispatch(name, args)（registry.py:574-600）：一切异常都被捕获成 {"error": "..."} JSON 返回——工具永不抛异常给循环，错误是喂给模型的数据，这一点与 Claude Code 的 <tool_use_error> 设计同构。

4.2 Toolsets：给不同场景发不同的「工具套餐」

toolsets.py:31-66 定义 _HERMES_CORE_TOOLS（CLI 和所有消息平台共用的核心 30 余个工具：web_search/terminal/read_file/patch/browser_*/todo/memory/skills…），toolsets.py:95 起的 TOOLSETS 字典把工具组合成可组装的套餐（web / file / browser / cronjob / computer_use / video_gen…），支持 includes 嵌套复用。哪些 toolset 启用由配置、平台（platform_toolsets）、CLI flag 共同决定，model_tools.py:279 的 get_tool_definitions() 最终算出发给模型的 schema 列表。桌面 GUI 专属工具（project_list 等）刻意不进核心套餐，只由 GUI gateway 启用（toolsets.py:53-59 注释）。

4.3 并发执行：白名单 + 路径不重叠

_execute_tool_calls（run_agent.py:5631）用 _should_parallelize_tool_batch（agent/tool_dispatch_helpers.py:104-147）判定一批调用可否并行，规则保守：

• 只读白名单 _PARALLEL_SAFE_TOOLS（tool_dispatch_helpers.py:45-58）：read_file / search_files / web_search / web_extract / vision_analyze / session_search / skills_list 等 10 个；MCP 工具需 server 显式声明 parallel-safe。
• 路径互斥：read_file / write_file / patch 属「路径作用域工具」，同批目标路径两两不重叠（含子树判断）才可并行（:61,136-141）。
• 绝不并行：clarify（要问用户的交互工具）出现即整批串行（:42）；参数解析失败也退回串行。

并行批走 execute_tool_calls_concurrent（agent/tool_executor.py:306）：最多 8 个 daemon 线程（tool_executor.py:71；用自定义 DaemonThreadPoolExecutor 防止解释器退出时被 atexit 卡住，:642-647），整批默认 420 秒看门狗（:74-75）。串行路径 execute_tool_calls_sequential（:965）逐个跑。两条路径共享同一套前置：越权工具拒绝 → PreToolUse 插件 hook → ToolGuardrails.before_call（:447-460）→ dispatch。

4.4 结果预算：三级防上下文爆炸

4.5 代表性工具逐个拆

05权限与安全模型

三层纵深：硬底线（任何模式不可绕）→ 用户策略（deny/allowlist）→ 审批门（manual/smart/off）。哲学很坦诚：进程内启发式是「辅助」，真正的 OS 级边界只有容器。

5.1 审批模式：manual / smart / off（+ YOLO）

5.2 命令风险分级：四道闸门的顺序

gateway 场景的审批是异步的：agent 线程阻塞等 Telegram 里的 /approve 或 /deny；沉默 ≠ 同意——超时按拒绝处理，且拒绝消息会点名 agent 常见的规避伎俩（换个说法重试、换条命令达成同样效果），防止模型「绕道」（approval.py:2548-2598）。发到聊天软件的命令内容先经 redact_sensitive_text 脱敏（:2538-2543）。

5.3 写保护与路径安全

• 写黑名单（agent/file_safety.py:28-77）：~/.ssh/authorized_keys、.env、/etc/sudoers、~/.aws ~/.kube ~/.gnupg 等敏感路径直接拒写；设 HERMES_WRITE_SAFE_ROOT 后变成「只准写指定目录」的白名单模式（:80-95,134-142）。源码注释坦白：这不是安全边界（同一 OS 用户下 terminal 仍能 cat），只是纵深防御（:184-187）。
• 记忆/技能写审批（tools/write_approval.py:264-273）：可选门，开启后 MEMORY.md 写入在交互终端内联审批，SKILL.md 一律进 staging 目录等人批——「只延迟、不静默丢弃」。
• SSRF 防护（tools/url_safety.py:154-168）：云 metadata 端点（169.254.169.254、Azure IMDS、阿里云 100.100.100.200…）无条件阻断，不受任何开关影响；私网 IP 默认阻断可配置放开。

5.4 供应链与内容威胁

• tirith（tools/tirith_security.py:730-825）：本地 Rust 二进制子进程扫内容级威胁（同形异义 URL、pipe-to-interpreter），退出码即裁决（0 允许/1 阻断/2 警告）；二进制从 GitHub releases 自动下载但必验 SHA-256 + cosign provenance（:293-333）；默认 fail-open + 连续崩溃熔断。
• OSV 恶意包预检（tools/osv_check.py:22-62）：npx/uvx 启动 MCP server 前查 api.osv.dev 的 MAL-* 预警。
• MCP 配置扫描（hermes_cli/mcp_security.py:80-175）：内置 2026 年 6 月「hermes-0day」真实攻击的 IOC 黑名单（攻击者 SSH 公钥/IP），外加网络外泄形（/dev/tcp/、curl 内联脚本）和持久化形（写 authorized_keys/crontab/.bashrc）模式，保存时和 spawn 时都跑。
• Skill 安装门（tools/skills_guard.py:51-61）：信任分级 × 危险等级的策略矩阵——builtin 全放行、trusted 源（openai/anthropics/huggingface）dangerous 阻断、community 源 caution 就阻断；--force 也压不过 dangerous 判定（:704-723）。详见第 9 章。
• 凭据不进沙箱（tools/env_passthrough.py:48-119）：execute_code 和 terminal 子进程默认剥离 secret；skill 可声明需要透传的环境变量，但 Hermes 托管的 provider 凭据在黑名单上、永远不可注册透传（GHSA-rhgp-j443-p4rf 的修复），import 失败时 fail-closed。多 profile 网关另有 contextvar 级 secret scope，未绑定 scope 时读 secret 直接抛异常而不是回落全局环境（agent/secret_scope.py:148-153）。

06模型 / API 层：一颗引擎适配 30+ 厂商

Hermes 的「通用语」是 OpenAI chat.completions 格式；ProviderProfile 声明差异，transports 做翻译，credential_pool 管钥匙。

6.1 ProviderProfile：声明式而非继承式

与其给每个厂商写一个类，Hermes 用一个 dataclass 把「厂商的一切怪癖」declarative 地摆出来（providers/base.py:1-10：「They do NOT own client construction, credential rotation, or streaming. Those stay on AIAgent.」）。关键字段：api_mode（默认 chat_completions）、auth_type（api_key / oauth_device_code / oauth_external / copilot / aws_sdk，base.py:56）、fixed_temperature（哨兵 OMIT_TEMPERATURE = 干脆不发温度，:21）、supports_vision、fallback_models。5 个可覆盖 hook：prepare_messages / build_extra_body / build_api_kwargs_extras / fetch_models / get_hostname（base.py:98-217）。

Profile 本体作为插件放在 plugins/model-providers/<name>/（30+ 个：nous / openrouter / anthropic / gemini / bedrock / vertex / xai / alibaba / zai…），调用 register_provider(...) 注册。Nous 官方端点 https://inference.nousresearch.com/v1（plugins/model-providers/nous/__init__.py:50），OAuth device-code 登录走 hermes portal（hermes_cli/portal_cli.py:28）。

6.2 五种消息方言与适配器

6.3 重试、错误分类与 fallback 链

Hermes 面对的是「30 个厂商 × 各自的报错方言」，所以搞了一个 错误分类器（agent/error_classifier.py:24-72）：把异常归成约 20 类 FailoverReason（auth / billing / rate_limit / upstream_rate_limit / overloaded / context_overflow / content_policy…），每类带四个动作位：retryable / should_compress / should_rotate_credential / should_fallback（:90-93）。主循环的内层重试环按这些动作位行动：

• 退避：jittered_backoff = min(5s × 2^(n-1), 120s) + 50% 抖动（agent/retry_utils.py:28-66）。
• 429 细分：上游过载（OpenRouter 转发的上游 429）→ fallback 换模型；账号级 429 → 轮换凭据；Nous 的 429 还写进跨进程共享文件让其他会话直接跳过调用（agent/nous_rate_guard.py:1-12，防「3 次 SDK 重试 × 3 次 Hermes 重试」的 9 倍放大）。
• fallback 链：try_activate_fallback（agent/chat_completion_helpers.py:1172-1260）沿用户配置的备选链逐个切换 client/model/provider，主 provider 上 60 秒冷却，链耗尽才认输。
• 上下文超限 → 触发压缩后重试（最多 3 次压缩尝试，conversation_loop.py:3339-3607）。
• 一次性恢复守卫：16 个「本回合只许试一次」的修复动作（OAuth 刷新、剥 thinking 签名、缩图、去 multimodal tool 内容…）收进 TurnRetryState dataclass（agent/turn_retry_state.py:32-75），每次 attempt 重建，杜绝无限自我修复循环。

6.4 多凭据池：一个 provider 可以插很多把钥匙

agent/credential_pool.py:508 的 CredentialPool 支持同一 provider 配多个 key/OAuth 账号，4 种轮换策略：fill_first（默认，用坏了才换）/ round_robin / random / least_used（:98-106,1485-1513）。429 的 key 进 1 小时冷却（:114）；选择前还会从磁盘同步其他进程刷新过的 OAuth token（:1384-1394）——因为 CLI、gateway、cron 可能同时在跑。这是 Claude Code 完全没有的一层（它假设单账号）。

6.5 Prompt caching 与计价

对 Claude 系模型自动打 cache_control：唯一布局 system_and_3——4 个断点 = system prompt + 最后 3 条「能承载 marker」的消息（agent/prompt_caching.py:1-7,84-117）；OpenRouter 转发和原生 Anthropic 的 marker 摆放位置不同由 native_anthropic 区分。模型目录用 models.dev 数据库（打包快照 → 磁盘缓存 → 网络 → 每小时后台刷新，agent/models_dev.py:1-18）；计价三源（官方价目 / OpenRouter / 元数据）在 agent/usage_pricing.py:733；Nous 订阅额度从 x-nous-credits-* 响应头解析（agent/credits_tracker.py:1-23）。

6.6 MoA：一次回合多模型合议

/moa 开启 Mixture-of-Agents 模式：每次主模型迭代前，用线程池并发问最多 8 个「参考模型」（可以来自不同厂商），把它们的意见拼进本轮 user 消息，由主模型（aggregator）综合后再决定行动（agent/moa_loop.py:1-7,336,28）。各参考模型按自己的费率单独计价（:291-295）。工具调用与终止仍由主循环掌管——MoA 只是给主模型「开会」。

07上下文·记忆·学习循环

这是 Hermes 的招牌章节：上下文压缩解决「一次会话装不下」，记忆 + 技能 + curator 解决「跨会话越用越懂你」。

7.1 上下文压缩：先廉价裁剪，再 LLM 摘要

压缩引擎可插拔（agent/context_engine.py:32），内置实现 ContextCompressor（agent/context_compressor.py:662）。触发：prompt token ≥ 阈值（有效输入预算 × 50%，:956-958,912-942；比 Claude Code 的 92% 激进得多）。压缩分四相（:2670-2733 算法注释）：

防抖设计：连续两次压缩各省不到 10% 就跳过；摘要 LLM 失败进 600 秒冷却；压缩失败还有确定性静态回退摘要兜底（context_compressor.py:1155-1172,2891-2900）。跨进程用 SQLite compression_locks 表 + 租约防止 CLI 和 gateway 同时压同一会话（agent/conversation_compression.py:75-120）。

7.2 双文件记忆：MEMORY.md 与 USER.md

内置记忆极简却讲究（tools/memory_tool.py）：两个 Markdown 文件在 ~/.hermes/memories/——MEMORY.md（agent 自己的笔记：环境事实、项目约定）与 USER.md（对你的了解），条目用 § 分隔（:16,56-59）。字符上限而非 token（模型无关）：2200 / 1375 字符（:130,804-805），系统提示里带用量表头（MEMORY [63% — 1,400/2,200 chars]，:664-680）逼模型定期整理。模型通过单一 memory 工具 add/replace/remove。关键设计——冻结快照：会话开始时读入注进 system prompt，中途写盘立即持久化但不改提示（保 prompt cache），下个会话才见新版（:11-14,615-626）。

外部记忆走 MemoryProvider 抽象（agent/memory_provider.py:43，Honcho / Hindsight / Mem0 等作为 plugins/memory/ 插件，同时只允许挂一个防 schema 膨胀）：每回合前后台 prefetch(query) 召回、回合后 sync_turn 异步写、压缩丢历史前有 on_pre_compress 抢救洞见（:176-230）。召回内容注入本轮 user 消息而非 system prompt——又是为了缓存。

7.3 自我改进循环：nudge → skill → curator

README 说 Hermes 是「the only agent with a built-in learning loop」，源码里这个循环由四件套构成：

• 回合末复盘触发：finalize_turn 末尾的 memory/skill review 触发器（agent/turn_finalizer.py:9-10），加上系统提示里的 skill nudge 计数器——每隔 N 轮没用 skill_manage 就提醒模型「要不要沉淀点什么」（conversation_loop.py:692-694）。
• agent 自创技能：模型用 skill_manage 工具写 SKILL.md（tools/skill_manager_tool.py:1303-1364）；/learn 命令则构造一段提示让 agent 用现有工具收集素材再写成规范技能（agent/learn_prompt.py:99）。
• curator 后台园丁：agent 闲置 ≥2 小时且距上次运行 ≥7 天时，fork 一个用便宜辅助模型的 AIAgent 审查技能库——按活跃时间戳流转生命周期（30 天标 stale、90 天归档）、合并、修补（agent/curator.py:6,146-157,1480）。严格不变量：只碰 agent 自建技能、只归档从不删除、pinned 豁免（:15-20）。归属由 contextvar 区分：用户让前台 agent 写的技能永不被自动 curate（tools/skill_provenance.py:3-14）。
• 会话全文检索：session_search 工具在 SQLite FTS5 上做跨会话召回（DISCOVERY / SCROLL / BROWSE 三模式），并把 cron 等自动化会话降权防止淹没交互记忆（tools/session_search_tool.py:6-52）。

08UI 层：真 Ink 的 Node TUI + 经典 Python REPL

Hermes 有两套终端界面：老而稳的 prompt_toolkit REPL，和新的 React/Ink TUI。有趣的对照：Claude Code fork 了 Ink，Hermes 直接用 npm 上的 Ink v6，只加了一个薄补丁包。

8.1 ui-tui 技术栈

ui-tui/package.json:19-27 说明一切：ink ^6.8.0（npm 原版，不是 fork）+ react ^19 + nanostores（轻量状态库，替代 Redux）+ 本地补丁包 @hermes/ink（file:./packages/hermes-ink，覆盖 Ink 的部分行为并暴露 FrameEvent）。开发跑 tsx src/entry.tsx，发布用 esbuild 打成 dist/entry.js。入口 ui-tui/src/entry.tsx:1 的 shebang 就带着性能预算：node --max-old-space-size=8192 --expose-gc；开头一段注释专门处理「上个 TUI 被 kill -9 后终端还开着鼠标追踪模式」的惨案（entry.tsx:26-40，resetTerminalModes 挂 exit 兜底）。

8.2 与 Python 的协议：stdio 上的 JSON-RPC 2.0

Node 端 GatewayClient spawn python -m tui_gateway.entry（ui-tui/src/gatewayClient.ts:356），Python 侧的主循环就是逐行读 stdin（tui_gateway/entry.py:357-373）：

tui_gateway/entry.py:357
for raw in sys.stdin:
    # 每行一个 JSON-RPC 2.0 请求
    resp = dispatch(req, transport)      # tui_gateway/server.py:1160 按 method 路由
    if not write_json(resp): break       # 响应写回 stdout

dispatch（tui_gateway/server.py:1160-1180）把慢方法（OAuth device flow 等）丢线程池（_LONG_HANDLERS，:178），快方法同步答。RPC 面有多宽？ui-tui/src/gatewayTypes.ts 里导出了 76 个接口/类型：会话创建/恢复/活跃列表、斜杠命令目录与补全、配置读写、计费卡片、setup 状态……tui_gateway/server.py 高达 13873 行——比引擎的 conversation_loop 还长两倍多，因为 TUI 把设置、计费、模型选择这些原本散在 CLI 各处的功能全部 RPC 化了。agent 的流式输出走同一管道反向推送：AIAgent 的回调（stream_delta / tool_progress / thinking）被 server 序列化成事件行，Node 端渲染。

8.3 经典 REPL 与 Python 侧渲染

不开 TUI 时是纯 Python 界面：prompt_toolkit 管输入（多行、历史、补全、「运行中输入」实现 /steer），agent/display.py（1426 行）管输出——工具调用的单行预览（emoji + 截断参数）、diff 上色（display.py:36-89）、皮肤/工具 emoji 映射（:122-139）、流式「响应盒子」边框绘制（cli.py 内的 ╭─ ⚕ Hermes ─╮ 盒子，cli.py:12180-12186）。hermes_cli/curses_ui.py:1-5 则只是 hermes tools/hermes skills 用的 curses 多选清单组件，不是聊天界面。

8.4 输入回传与中断

• 提交链：TUI 输入框回车（ui-tui/src/app/submissionCore.ts:75 prompt.submit）→ GatewayClient 发 JSON-RPC → server 调 agent.run_conversation(...)（tui_gateway/server.py:8674）→ 事件流回推；经典 REPL 则如第 1 章步骤 2，在本进程线程里直接调。
• 中断：两套外壳殊途同归——把 agent._interrupt_requested 置位 + 掐断当前流式请求（run_agent.py:4734 _interruptible_streaming_api_call 轮询该标志），循环顶检查后带部分结果退出（agent/conversation_loop.py:638-643）。TUI 侧从 ui-tui/src/app/turnController.ts:298 的 session.interrupt 发起，落到 tools/interrupt.py:39-52 的线程级中断信号，让长工具（浏览器、终端）也能响应。
• 运行中打字 = /steer：不打断、不丢弃，排队到下一次 API 调用前注入（第 3 章 3.5）。

09扩展生态：Skills、MCP、Plugins、Hooks、多 Agent

和 Claude Code 一样，所有扩展收敛为「注入对话的文本」或「模型可调用的工具」两种本质；不同的是 Hermes 的 skill 有完整的分发市场、信任分级和 agent 自建通道。

9.1 Skills：渐进披露 + 自建 + 市场

技能 = SKILL.md（YAML frontmatter：name/description/version/platforms/related_skills）+ 可选 references/templates/scripts 子目录，存放于仓库 skills/（内置 18 类）、optional-skills/（按需装）和 ~/.hermes/skills/（用户/agent 自建）。触达模型有两条路，都是显式注入而非暗中触发：

1. 渐进披露：系统提示只放「名字 + 一句话」索引（agent/system_prompt.py:260-289），模型需要时调 skills_list（tier-1 清单）→ skill_view（tier-2 全文 + 支撑文件，tools/skills_tool.py:689,864）。与 Claude Code 的 SkillTool 思路相同。
2. 斜杠直载：/skill-name 把 SKILL.md 全文内联成一条消息，附技能目录路径和配置（agent/skill_commands.py:245-334）；bundle（~/.hermes/skill-bundles/*.yaml）可一次装载一组（agent/skill_bundles.py:1-10）。frontmatter 支持 inline_shell（渲染时执行内嵌 shell）。

分发侧是 Hermes 独有的重头戏：tools/skills_hub.py:424 的 SkillSource 抽象下挂 8 个源——GitHub、skills.sh、ClawHub、Claude marketplace、LobeHub、well-known URL 等，兼容 agentskills.io 开放标准；scripts/build_skills_index.py 定期爬全部源产出静态索引给 hermes skills search 用（免打 API）。装机必过 skills_guard 信任矩阵（第 5 章）+ prompt-injection 扫描 + 不可见 Unicode 检测（tools/skills_guard.py:797-926）。

9.2 MCP：双向——既当 client 又当 server

• Client 侧（tools/mcp_tool.py，5308 行）：stdio / StreamableHTTP / SSE 三种 transport；启动时 asyncio.gather 并行连全部 server（外层 120 秒超时，:4577-4643）；每个远程工具注册为 mcp__<server>__<tool>（:4199）进同一个 registry，与内置工具无差别调度；支持 tools/list_changed 运行期动态刷新（:1570-1725）；OAuth 走 PKCE + 动态客户端注册，token 存 ~/.hermes/mcp-tokens/，后台线程绝不弹浏览器（tools/mcp_oauth.py:132-202）。安全面：stdio 子进程环境变量白名单、远程 URL 校验（禁 file://）、工具描述注入扫描、OSV 恶意包预检。
• Server 侧（mcp_serve.py:52,564-712）：hermes mcp serve 用 FastMCP 把 Hermes 自己暴露成 MCP server——Claude Code / Cursor 可以列 Hermes 的会话、读历史、发消息、回应审批（9+1 个工具，对齐 OpenClaw 桥面）。也就是说你可以在 Claude Code 里把 Hermes 当一个可编程的常驻 agent 使。

9.3 Plugins：四种来源、五种能力

插件 = plugin.yaml + __init__.py::register(ctx)，来源有四：仓库内置 plugins/、~/.hermes/plugins/、配置指定路径、Python entry-point 组 hermes_agent.plugins（hermes_cli/plugins.py:5-20）。ctx 能注册：工具（覆盖内置工具需 operator 显式授权，防第三方插件静默替换 write_file 提权，:451-470）、hook 回调、消息平台适配器、模型 provider，还能借宿主的 LLM 凭据跑推理（ctx.llm，:349）。内置 20 个插件：browser / kanban / memory / spotify / observability / 各消息平台 / 各模型厂商——Hermes 把自己的大量一等功能也实现成插件，狗粮吃得很彻底。

9.4 Hooks：两套总线 + shell 桥

9.5 多 Agent：delegate 之外还有 Kanban Swarm

除第 4 章的 delegate_task（进程内 new AIAgent），Hermes 还有一套进程级多 agent 编排：hermes kanban 维护一个共享 SQLite 看板（~/.hermes/kanban.db），swarm 模式往看板写一个任务图——规划根节点 → 并行 specialist workers → verifier → synthesizer（hermes_cli/kanban_swarm.py:1-14）；LLM 负责把大任务扇出成子任务图并按「花名册」分派（hermes_cli/kanban_decompose.py:1-13）；dispatcher 为每张就绪卡 fire-and-forget 一个独立的 hermes chat 子进程（hermes_cli/kanban_db.py:7811 subprocess.Popen），黑板通信走看板评论。worker 的 kanban 工具只在 HERMES_KANBAN_TASK 环境变量存在时注册，普通会话看不到（tools/kanban_tools.py:1-8）。

9.6 Cron：会思考的定时任务

网关内每 60 秒一次 tick()（文件锁防多进程重叠），到期任务两种执行法：agent job 起完整 AIAgent 跑一个自然语言 prompt（cron 会话禁用 cronjob 工具防套娃）；脚本 job 直接 subprocess 跑、零 token（cron/scheduler.py:2-8,2947-3007,1917-2003,116）。任务存 ~/.hermes/cron/jobs.json，输出按 job 归档为 markdown，投递路由可指到任何平台频道（cron/jobs.py:2-6 · gateway/delivery.py:1-9）。agent 自己通过单一 cronjob 工具增删改查（tools/cronjob_tools.py:1-6）——「每天早上八点给我 Telegram 发日报」一句话就能落地。

10Gateway 与多形态部署：Hermes 最独特的子系统

Claude Code 活在你的终端里；Hermes 被设计成「活在服务器上、从任何聊天软件召唤」。gateway/ 就是那台永动机。

10.1 进程模型：单 asyncio 进程、per-session 缓存 AIAgent

python -m gateway.run（或 hermes gateway start 托管为 systemd/launchd 服务）启动一个 asyncio 事件循环进程（gateway/run.py:20411-20451），GatewayRunner（:2738）拉起所有已配置的平台适配器。agent 就在网关进程内跑：每个会话缓存一个 AIAgent 实例以保住 prompt cache（run.py:2914-2918,16491）。路由键 = "{platform}:{chat_id}"（run.py:3176），会话上下文用 ContextVar 承载（gateway/session_context.py:149）。设 GATEWAY_PROXY_URL 可退化成薄中继，把消息转发给远端 Hermes API server（run.py:16131-16153）。

10.2 平台矩阵：内置 + 插件共 30 余个

平台注册走 PlatformEntry 元数据 + 懒加载（gateway/platform_registry.py:39,187——不能启动就 import 20 个平台 SDK，否则每次 hermes 都慢几秒）。每个 entry 声明依赖探针、所需 env、授权 env、消息长度上限、cron 投递默认频道、进程外投递函数等（Discord 示例见 plugins/platforms/discord/adapter.py:7879-7913）。出站侧还有一个有趣设计：模型可以回 NO_REPLY 静默 token 主动选择「这条不用回」（gateway/response_filters.py:14-19）。

10.3 谁能命令你的 agent：默认拒绝 + 配对码

入站消息先过 _is_user_authorized（gateway/authz_mixin.py:249-495）：默认 deny，按序查系统事件豁免 → relay 上游委托（严格 is True 判断防 mock 提权）→ 群聊 chat allowlist → bot 白名单 → per-platform *_ALLOW_ALL_USERS / *_ALLOWED_USERS env → 配对存储。配对（gateway/pairing.py:5-18）：陌生人私聊 bot 会收到一次性 8 位码（32 字符无歧义字母表、密码学随机、1 小时过期、每平台最多 3 个待批、失败 5 次锁 1 小时），bot 主人在 CLI/dashboard 批准——审批入口入站消息永远够不到，从结构上封死「在 Telegram 里说服 agent 给自己开门」的注入路径。

10.4 常驻进程的自我保养

10.5 桌面端、批处理与训练管线

• Electron 桌面 App（apps/desktop/package.json:9）：React + Electron 壳，不重写 agent——启动时拉起自带的 headless 后端 hermes serve（就是解耦命名的 gateway，apps/desktop/electron/backend-command.cjs:5-12）。首装引导器反而是 Tauri 写的（apps/bootstrap-installer/package.json，Rust src-tauri/），图它体积小。另有 web/（Vite+React 的 dashboard 前端）。
• batch_runner.py：数据集批量跑 agent、multiprocessing 并行、断点续跑、按 ShareGPT 格式存轨迹（batch_runner.py:1-20,325）——Nous 拿它给下一代工具调用模型造训练数据；trajectory_compressor.py 离线把轨迹压到训练 token 预算。mini_swe_runner.py 是 SWE 风格任务 runner（复用 local/docker/modal 执行环境；是否直接对接 SWE-bench 榜单未核实）。

11文件索引速查

按「我想看 X」检索，路径相对仓库根。