Hermes Agent · 中文源码精读教程

本文集文档发布于灏天文库

第 9 章 · 02 CLI 本地化与 MCP server

第 9 章 · 02 CLI 本地化与 MCP server

本节摘要：本节补齐中文生态的最后两块。其一，CLI 17 种语言本地化——locales/ 下 af/ar/de/en/es/fr/ga/hu/it/ja/ko/pt/ru/tr/uk/zh-hant/zh 共 17 份 YAML，zh.yaml（443 行）覆盖审批选项、模型切换、网关提示等全部静态文案；agent/i18n.py 负责键查找与参数插值。其二，hermes CLI 子命令概览——hermes_cli/main.py 的 _BUILTIN_SUBCOMMANDS 内置清单涵盖 model/tools/gateway/setup/doctor/claw/profile/mcp/plugins/dashboard/kanban/cron/skills/memory 等数十个子命令，且用清单短路插件发现以省 500ms 启动时间。其三，主菜 mcp_serve.py（1060 行）：hermes mcp serve 把 Hermes 反向暴露为一个 MCP server——Claude Code/Cursor/Codex 等任何 MCP 客户端可以把"整个 Hermes 的消息面"当工具用：conversations_list、messages_read、messages_send、events_poll、permissions_respond 等 10+1 个工具，EventBridge 后台线程轮询会话库推送实时事件。

内容来源：原项目源码 locales/zh.yaml、agent/i18n.py、hermes_cli/main.py（_BUILTIN_SUBCOMMANDS 段）、mcp_serve.py，以及 website/docs/user-guide/cli.md。

⚠️ 注意：本地化只覆盖静态 UI 文案（按钮、提示、状态行），不包括模型输出与技能文档——后者由模型与技能自身决定语言。zh.yaml 以 en.yaml 为 source of truth，键必须同步；贡献翻译时先对照 en.yaml 键集。

学习目标

阅读完本节，你应当能够：

  1. 说出 locales 的文件组织与 zh.yaml 的覆盖范围。
  2. 列举至少 10 个常用 hermes 子命令及其职责。
  3. 解释 _BUILTIN_SUBCOMMANDS 清单为什么能省启动时间。
  4. 写出 mcp_serve 暴露的工具清单（9+1 个）。
  5. 讲清 EventBridge 的 baseline 机制为什么必要。

一、17 语言本地化：静态文案全覆盖

locales/ 目录 17 份 YAML，命名即 BCP-47 风格语言码。zh.yaml 的开头就是中文用户每天会看到的审批界面：

locales/zh.yaml:
approval:
  dangerous_header: "⚠️  危险命令： {description}"
  choose_long:     "      [o]仅此一次  |  [s]本次会话  |  [a]永久允许  |  [d]拒绝"
  prompt_long:     "      选择 [o/s/a/D]: "
  timeout:         "      ⏱ 超时 — 已拒绝命令"
  blocklist_message: "此命令位于无条件拦截列表中，无法被批准。"
​

组织方式是按表面分组：approval（审批）、gateway（网关）、gateway.model（模型切换子树——"已切换模型为 {model}""上下文：{tokens} tokens""提示词缓存：已启用"）。占位符用 {param} 花括号插值，由 agent/i18n.py 在查找时填充；每个键在 en.yaml 有唯一权威定义，其余语言保持键同步。这份目录的价值在细节：审批四选项的中文化措辞（"仅此一次/本次会话/永久允许/拒绝"）直接决定中文用户对第 3 章审批安全模型的理解成本——安全机制的可用性是本地化的一部分。

二、hermes 命令大家族：子命令概览

hermes_cli/main.py:11921 的 _BUILTIN_SUBCOMMANDS 是 argparse 无需插件发现就能识别的内置子命令清单：

main.py:11921  _BUILTIN_SUBCOMMANDS = frozenset(
11922      {
11923          "acp", "approvals", "auth", "backup", "bundles", "checkpoints",
11924          "claw", "completion", "computer-use", "config", "console", "cron",
11925          "curator", "dashboard", "serve", "debug", "doctor", "dump", ...,
11927          "gateway", "hooks", "import", "import-agent", "insights", "gui",
11928          "desktop", "kanban", "login", "logout", "logs", "lsp", "mcp",
11929          "memory", "migrate", "moa", ..., "model", "monitoring", "pairing",
...
11934          "send", "sessions", "setup", "skills", "slack", "status", "sync",
11935          "tools", "uninstall", "update", "webhook", "worktree", "chat", ...
​

按功能分簇认识最有效率。生命周期：setup（交互式向导，配平台配模型配凭据）、doctor（诊断环境）、update/migrate/uninstall/backup。运行面：chat（默认交互）、gateway（run/setup/status 管第 7 章的网关）、dashboard（起 9119 端口 Web 面板）、gui/desktop（桌面端）、console。模型与配置：model（切换/列表/搜索，接第 9.1 节的 37 provider）、profile（多 profile 管理，接 profile 路由）、config、tools（工具集开关）、plugins（插件市场与装卸）。协作与数据：kanban（第 8 章看板的 CLI 面）、cron、moa、skills、memory/memory-graph/learning（外循环的观察窗）、sessions/send（会话管理与跨平台发消息）、insights/curator。迁移：claw（claw migrate/import-agent——从 OpenClaw/Claude Code 系导入配置，第 1 章谱系论的落地件）。MCP：mcp serve——下一节主菜。

这份清单的存在本身是个性能故事：插件发现要急切 import 一堆捆绑模块（google.cloud.pubsub_v1、aiohttp、grpc……），普通 hermes chat 白等 500ms+；清单让"用户敲的命令不在内置集"时才触发发现（main.py:11912-11915 注释），代价只是插件命令不出现在顶层 --help——一笔划算的交易。

图：CLI 布局

三、mcp_serve：Hermes 作为 MCP server

第 3 章讲过 Hermes 作为 MCP 客户端消费外部服务器；mcp_serve.py 把方向反过来——Hermes 自己成为 MCP server。模块头一句话定位：

mcp_serve.py:1  """Hermes MCP Server — expose messaging conversations as MCP tools.
3
4  Starts a stdio MCP server that lets any MCP client (Claude Code, Cursor,
5  Codex, etc.) list conversations, read message history, send messages, poll
6  for live events, and manage approval requests across all connected platforms.
​

用法极简：MCP 客户端配置里挂 "command": "hermes", "args": ["mcp", "serve"]。工具面 9+1 个（对齐 OpenClaw 的 9 工具桥接面再加一个 Hermes 特有）：conversations_list（跨平台列会话，可按平台过滤/按名搜索）、conversation_get、messages_read（读历史，只回 user/assistant 轮）、attachments_fetch、events_poll/events_wait（实时事件）、messages_send（向任意平台会话发消息）、permissions_list_open/permissions_respond（列出并裁决待审批请求）、channels_list（频道目录）。注册方式是装饰器（mcp_serve.py:644 起）：

mcp_serve.py:644      @mcp.tool()
645      def conversations_list(
646          platform: Optional[str] = None,
647          limit: int = 50,
648          search: Optional[str] = None,
649      ) -> str:
650          """List active messaging conversations across connected platforms."""
​

docstring 即工具描述、函数签名即输入 schema——与 mcp 2.0 的 MCPServer 面对齐（import 带 try/except，兼容 SDK 版本更名）。数据源全部复用现有设施：会话索引读 ~/.hermes/sessions/（SQLite 优先、JSON 回退）、频道目录读 channel_directory.json、发送经网关适配器——MCP 面只是第 7 章网关的又一层皮。

实时性由 EventBridge（mcp_serve.py:335）提供：后台线程每秒轮询会话库把新消息/审批事件排队；events_wait 可阻塞等待。启动时的 _establish_baseline（mcp_serve.py:469）先记下当前最大事件水位再开始监听——否则客户端一连接就会收到历史消息的雪崩。审批响应 permissions_respond 让另一个 agent 可以替你批准/拒绝 Hermes 的危险命令请求——信任边界完全交给使用者划定。

战略意义值得点透：这让 Hermes 在多 agent 世界里可被组合——Claude Code 里的编程 agent 可以把"发微信问老板确认"当作一次工具调用，Hermes 负责跨平台投递、审批把关（approval 回流到 permissions_respond）、结果回流。Hermes 从"一个 agent"变成"生态里的一个器官"，这与它把 133 个工具开放给模型是同一个开放哲学的两次应用。

💡 循环要点：本地化与 MCP server 看似两件小事，实则是同一命题——降低进入内循环的门槛。zh.yaml 把安全审批翻译成母语直觉，砍掉的是中文用户的信任成本；mcp_serve 把 Hermes 的社交器官输出为标准协议，砍掉的是异构 agent 的组合成本。门槛每降一分，会话量与经验沉淀就多一分——生态层的每一处友好，最终都兑换成外循环的燃料。

本节要点回顾

  1. 17 语言：locales 按语言码一份 YAML；zh.yaml 443 行覆盖审批/网关/模型切换等静态文案，花括号插值，en.yaml 为权威键集；审批措辞是安全可用性的一部分。
  2. 子命令家族：内置清单数十个（model/tools/gateway/setup/doctor/claw/profile/mcp/plugins/dashboard/kanban/cron/skills/memory/sessions/send……），按生命周期/运行面/模型配置/协作数据/迁移/MCP 分簇记忆。
  3. 性能技巧：_BUILTIN_SUBCOMMANDS 短路插件发现省 500ms+，代价仅是插件命令不在顶层帮助。
  4. mcp_serve 9+1 工具：会话列举/读取/发送、附件、事件轮询等待、审批列出与裁决、频道目录；stdio 传输，docstring 即描述、签名即 schema。
  5. EventBridge：后台轮询 + baseline 水位防历史雪崩；permissions_respond 允许外部 agent 参与审批（信任边界自定）。
  6. 组合哲学：Hermes 既消费 MCP（第 3 章）又提供 MCP（本节）——在多 agent 生态中既是工具使用者又是可被使用的器官。

下一章进入收官：batch_runner 与 trajectory_compressor 把双循环跑出的轨迹压成训练数据，evals 度量能力，供应链安全守住底线，最后概览 UI 三件套并回望全书。

作者与出处
原作者： 灏天文库
整理： 灏天文库整理
本站整理收录，版权归原作者/开源协议所有；欢迎通过原文链接访问源仓库。
发布者: 作者: 灏天文库 转发
评论区 (0)
U
0/500