Hermes Agent 源码解析（二）：入口与 CLI —— 从 `hermes` 命令到交互式 REPL

Hermes Agent 源码解析（二）：入口与 CLI —— 从 hermes 命令到交互式 REPL

如果你正在做一个自己的 CLI 工具，Hermes 的启动链路里有很多值得借鉴的设计——尤其是它的配置三层合并和技能注入缓存优化。

启动链路

1. hermes shell 脚本

仓库根目录的 hermes 是一个 shell 脚本（而非 Python 文件）。它负责：

• 定位项目根目录下的 .venv
• 设置 PYTHONPATH
• 给 cli.py 传递命令行参数

2. hermes_bootstrap.py —— Windows 兼容层

这个文件只有 129 行，但设计精妙：

# 在 Windows 上设置 PYTHONUTF8=1 和 PYTHONIOENCODING=utf-8
# 修复 cp1252 编码下 print("café") 的 UnicodeEncodeError
# 同时对子进程（execute_code sandbox、delegation children）生效

它的设计原则是：POSIX 上什么都不做，因为 99% 的 Linux/macOS 已经是 UTF-8 默认环境。

3. cli.py 的 HermesCLI 类

CLI 入口在 cli.py，行数 ~14,442。核心结构：

HermesCLI.__init__()
├── Rich 渲染 Banner（ASCII art 标题）
├── 加载配置 load_cli_config()
├── 初始化皮肤引擎
└── 扫描技能目录

HermesCLI.run()
├── 启动输入循环
├── prompt_toolkit 管理输入区域
├── KawaiiSpinner 管理 API 调用动画
└── process_command() 处理斜杠命令

配置加载链路

load_cli_config()
├── 硬编码 DEFAULT_CONFIG（hermes_cli/config.py）
├── 读取 ~/.hermes/config.yaml（用户设置）
├── 读取 ~/.hermes/.env（仅 API 密钥）
├── deep-merge 三层合并
└── 返回完整配置字典

斜杠命令注册中心

所有斜杠命令集中定义在 hermes_cli/commands.py 的 COMMAND_REGISTRY 列表中：

CommandDef("mycommand", "描述文字", "Session", aliases=("mc",), args_hint="[arg]"),

每个 CommandDef 包含：

• name — 规范名（无斜杠）
• description — 描述
• category — 分类（Session / Configuration / Tools & Skills / Info / Exit）
• aliases — 别名元组
• cli_only / gateway_only — 平台限制

设计亮点：这个注册中心是单点事实来源（Single Source of Truth）。所有下游消费者自动派生：

消费者	自动生成内容
CLI	process_command() 派发
Gateway	GATEWAY_KNOWN_COMMANDS frozenset
微信	BotCommand 菜单列表
Slack	/hermes 子命令路由
自动补全	SlashCommandCompleter 的候选项

这意味着添加一个新命令只需要在 COMMAND_REGISTRY 加一行，再在 process_command() 加一个 handler。

Skills 注入策略

技能文件的加载不嵌入 system prompt，而是以 user message 注入：

# agent/skill_commands.py
# 扫描 ~/.hermes/skills/，注入为 user message
# 这样不破坏 prompt cache 的稳定性

这是一个非常重要的缓存优化 —— system prompt 变了会清空 API 侧的 prefix cache，而 user message 变化不影响。

Skin 皮肤引擎

hermes_cli/skin_engine.py 提供纯数据驱动的视觉定制：

# 皮肤是纯 YAML 数据，无需改代码
# 内置 4 个皮肤：default（金色）、ares（深红）、mono（灰度）、slate（冷蓝）
# 用户可在 ~/.hermes/skins/ 放自定义 .yaml

皮肤控制：Banner 颜色、Spinner 表情/动词、工具输出前缀、品牌名称、提示符符号等。

下一篇进入最核心的部分 —— AIAgent 类的 run_conversation() 主循环。