第 10 章 · 02 UI 三件套与全书回顾

第 10 章 · 02 UI 三件套与全书回顾

本节摘要：全书最后一节，先补齐「脸面」。UI 三件套：其一 cli.py（21663 行）——prompt_toolkit + rich 构筑的主交互 UI，hermes chat 的默认体验，斜杠命令、审批对话、/moa、/review 全在此；其二 ui-tui/——React + Ink 的 TypeScript TUI（hermes --tui），TypeScript 只管屏幕，Python 经 tui_gateway/ 的 stdio JSON-RPC 管会话、工具与模型；其三 apps/desktop/——Electron + React 桌面版，外加 web/ 的 React Dashboard（hermes dashboard，9119 端口）。四张脸共享同一个后端，因为网关与会话层从不关心调用者是谁。随后沿双循环主线完成全书十章回顾，提炼 Hermes 四点核心哲学（双循环自我改进/器官化/中文生态原生/工程纪律），并给出下一步学习建议。

内容来源：原项目源码 cli.py、ui-tui/README.md、tui_gateway/、apps/desktop/、web/README.md；并回顾全书十章脉络。

⚠️ 注意：cli.py 约 2.17 万行是仓库最大的单文件，本节只讲它在 UI 版图中的定位，不逐段精读。另外 hermes dashboard 服务的是构建产物（hermes_cli/web_dist/），改 web/src 后需 npm run build 才会生效；开发时用 web --no-open + Vite 热更新。

学习目标

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

1. 说出 UI 三件套各自的技术栈、入口命令与职责边界。
2. 解释 ui-tui 的「TypeScript 管屏幕、Python 管一切」分工与 JSON-RPC 传输。
3. 用一段话概括十章中每一章的核心机制。
4. 复述 Hermes 四点核心哲学并各举一个源码证据。
5. 为自己选定下一步动手方向。

一、UI 三件套：同一颗大脑的三张脸

其一，cli.py——21663 行的旗舰终端 UI。hermes chat 默认进入：prompt_toolkit 提供输入编辑与补全，rich 提供富文本渲染（进度条、表格、markdown）。第 3 章的审批对话（o/s/a/D 四选项）、第 8 章的 /moa 与 /review 派遣单、kanban 的 SIGTERM 优雅退出、子代理树的 /agents 视图，全部落在这个文件。它也是 _BUILTIN_SUBCOMMANDS（第 9 章）的分发中枢——hermes 后面跟的一切子命令从这里路由。

其二，ui-tui + tui_gateway——TypeScript 与 Python 的楚河汉界。README 开篇一句话定纲："React + Ink terminal UI for Hermes. TypeScript owns the screen. Python owns sessions, tools, model calls, and most command logic"。入口 src/entry.tsx 检测 TTY 后启动 GatewayClient，后者 spawn python -m tui_gateway.entry；传输是 stdio 上的换行分隔 JSON-RPC——请求/响应/事件走 stdout，Python 的 stderr 被收进内存环形缓冲仅作诊断（绝不上屏）。解释器解析链（HERMES_PYTHON → PYTHON → venv → python3）保证各种安装形态都能找到正确的 Python。这个架构的深意：TUI 想多花哨就多花哨，会话与工具的事实源永远在 Python 侧——UI 崩了重启，状态无损。

其三，apps/desktop + web——图形化的两端。desktop 是 Electron + React 桌面应用（e2e 测试、DESIGN.md 设计规范俱全）；web 是 Vite + React 19 + Tailwind v4 的浏览器 Dashboard，管配置、API key 与活跃会话监控，由 hermes dashboard 服务构建产物、FastAPI 后端挂在 9119。第 7 章的 dash-admin 系列截图（频道/配对/MCP/技能中枢/curator 运维）全部来自这里——管理员视图也是网关的一个消费者，与 Telegram 消息无异。

三件套能共存的理由在全书反复出现过：网关与会话层面对的是 MessageEvent 与 session key，不是终端帧——UI 只是又一个平台。TUI、桌面、浏览器与微信消息享受同等的会话连续性、审批安全与外循环沉淀。

💡 循环要点：UI 三件套是「平台抽象」哲学的最后一次胜利——当核心循环不关心调用者，脸面就可以任意添加。这也反向解释了为什么 cli.py 能膨胀到 2.1 万行：它承载的是旗舰体验的全部交互细节，而这些细节从不泄漏进核心循环。

二、全书十章双循环回顾

我们沿双循环走完全程。合卷回望：

第 1 章 Hermes 全貌与双循环架构：认识了这个 Nous Research 出品、MIT 协议的自我改进 agent——生产约 97 万行 Python + 58 万行 TypeScript、183 万行的巨兽。核心心法就位：内循环（会话循环：消息→prompt→LLM→工具→循环）+ 外循环（技能创建→curator 策展→使用中改进→learning_graph 沉淀→记忆反哺）。与 OpenClaw/Claude Code 的谱系经 hermes claw migrate 相连。

第 2 章 内循环 Agent Loop 全解剖：run_agent.py（9215 行）的 AIAgent，约 60 个构造参数；同步 while 循环 + 可中断 API 调用；三种 API 模式收敛（chat_completions/codex_responses/anthropic_messages 统一到 OpenAI 消息格式）——多协议世界的单心脏；消息交替规则与迭代预算的地基。

第 3 章 行动器官工具系统：133 个工具一工具一文件，中央 registry 与 schema 收集（model_tools.py）；28 个 toolset 分组与平台预设（toolsets.py）；危险命令审批（o/s/a/D）、路径安全与威胁模式；代表工具精读（terminal、五后端 browser、computer_use、delegate）。

第 4 章 外循环★技能自我改进（全书灵魂）：SKILL.md 开放标准（agentskills.io），82 内置 + 117 可选技能；curator 生命周期（创建→评审→启用→退役）；skill_ledger/usage/provenance 记账；使用中自改进；learning_graph 学习图谱。Hermes 区别于「能调工具的 agent」的全部灵魂在此——用得越多越强不是口号，是有账本、有图谱、有退役机制的工程系统。

第 5 章 记忆器官：有界策展式记忆（MEMORY.md 2200 字符/USER.md 1375 字符的硬边界）；8 种可插拔记忆 provider 横向对比；FTS5 会话搜索与 native/fts5_cjk 中文分词 C 扩展——中文世界的一块基石。

第 6 章 上下文工程：prompt caching 神圣不可侵犯的设计铁律——组装顺序稳定换来缓存命中，省钱又提速；上下文压缩（context_engine/compressor）与 micro-compaction 微压缩；token 估算。压缩不是省钱技巧，是长任务的生存条件。

第 7 章 社交器官 34 平台网关：单进程 asyncio 撑起 34 平台（11.4 万行 gateway/）；Platform 枚举 + 注册表 + 能力位的三层抽象；微信/飞书/钉钉/QQ/企微/元宝六大国内平台原生接入；跨平台会话连续性与语音转写。

第 8 章 协作器官多 Agent：delegate_task 委派与 SubagentLifecycleService 生命周期（HMAC 句柄防伪）；迭代预算体系（父 500/子 50）与 spawn 深度/并发上限的组合防线；/review 验证引擎；kanban 多 Agent 工作队列（九态看板、认领锁租约、崩溃恢复、swarm 拓扑）与 MoA。

第 9 章 中文生态与模型 provider：37 个 provider 插件，国内七家（deepseek/kimi/minimax/qwen/xiaomi/zai-GLM/alibaba）原生支持且 quirk 修到位（reasoning_content 回显陷阱、GLM thinking 静默失效）；5 种适配器正交组合；profile 路由；CLI 17 语言本地化；mcp_serve 把 Hermes 反向输出为 MCP server。

第 10 章 研究管线与工程纪律：batch_runner 批量轨迹生成；trajectory_compressor 的「保护首尾/压缩中间/摘要替换」把会话变训练数据；evals 三基准度量真实能力；供应链安全三件套（精确锁版/OSV/supply-chain-audit）与 30 个 CI——进化的燃料与免疫系统。

十章的因果链清晰可见：第 2 章的心脏需要第 3 章的手脚；第 4、5 章让经验跨越会话沉淀；第 6 章让长任务在有限上下文里活下来；第 7 章把一切送到人眼前（含中文国民级 IM）；第 8 章把一个变一群；第 9 章接通全球与国产的粮草；第 10 章把轨迹炼成更强的模型再灌回心脏，并用工程纪律守住全部成果。没有一章是孤岛。

三、Hermes 核心哲学四点

1. 双循环：自我改进，用得越多越强。内循环跑会话，外循环改行为——技能从经验创建、被 curator 策展、在使用中迭代、沉淀进 learning_graph 与跨会话记忆。证据：skill_ledger 的 usage/provenance 记账、curator 的完整生命周期状态机、第 10 章的轨迹管线把循环产出接回训练。多数 agent 框架止步于「会用的工具越多越强」，Hermes 追求的是「用过的经验变成资产」。
2. 器官化：各司其职，正交组合。工具（133 个）、记忆（8 provider）、技能（199 个）、网关（34 平台）、协作（subagent/kanban/MoA）、模型（37 provider）各自成器官，经统一的注册表与抽象面（BasePlatformAdapter 能力位、ProviderProfile quirk 钩子、toolset 分组）与心脏连接。加一个平台、一个厂商、一个工具，核心循环零改动——这是 183 万行不塌方的结构原因。
3. 中文生态原生，而非事后翻译。微信 iLink/飞书/钉钉/QQ/企微/元宝适配器、deepseek/kimi/qwen/GLM/minimax 的 quink 级修正、FTS5 中文分词 C 扩展、17 语言本地化里的 zh.yaml——从入口到模型到检索到界面，中文用户拿到的是一等公民体验，全栈国产路径可完整走通。
4. 工程纪律：巨兽的免疫与可审计。直接依赖精确锁版 ==X.Y.Z 且注释挂 CVE 编号；OSV 周扫 + 窄口径 supply-chain-audit；约 86 万行测试与 30 个 CI 工作流；预算/深度/并发三重防失控；连「失败提示措辞会毒化后续轮次」这种 prompt 级细节都有 issue 编号可溯。自我改进的系统必须先做到不可被投毒、不可被自己拖垮。

四、下一步：把书合上，把手放上

按投入产出排序的四个方向：

1. 改一个技能：挑自己业务里一个真实重复流程，按第 4 章的 SKILL.md 格式写出来，装进 ~/.hermes/skills/，观察 curator 如何评审启用、usage 如何记账——这是验证你理解外循环的最短路径。
2. 接一个平台：按第 7 章跑 hermes gateway setup，把 agent 接进飞书或钉钉（企业开发者权限最易得），配 deliver=feishu 的 cron 任务体验跨平台投递；有余力再读一个适配器（推荐 dingtalk，Stream 模式最简洁）。
3. 配一条国产链路：deepseek 或 zai-GLM 的 key + profile 路由，让不同聊天窗口用不同模型；对照第 9 章读 profile 的 build_api_kwargs_extras，理解 quirk 修正如何落到请求体。
4. 跑一次研究管线：用 batch_runner 对一个小数据集批量生成轨迹，再用 trajectory_compressor 压缩并读 metrics 报表——亲眼看到「会话→训练数据」的出口，双循环才算真正闭合。

agent 框架会继续演化，协议会来回摇摆，但 Hermes 留给读者的判断力不会过时：把改进做成有账本的系统，把差异锁进边界的抽象，把生态当一等公民，把纪律当生存条件。愿你的 agent 步步收敛、技能日增、账单可控、循环不息。全书完。

本节要点回顾

1. UI 三件套：cli.py（21663 行，prompt_toolkit+rich，旗舰终端 UI 与子命令中枢）；ui-tui（React+Ink 管屏幕）+ tui_gateway（Python 管会话/工具/模型，stdio JSON-RPC，stderr 只进诊断环）；apps/desktop（Electron+React）与 web Dashboard（9119，FastAPI 后端）。
2. 架构要义：UI 是「又一个平台」——网关面对 MessageEvent 而非终端帧，故脸面可任意添加而核心零改动；TUI 崩溃重启状态无损，因为事实源在 Python 侧。
3. 十章主线：双循环架构(1)→内循环三种 API 收敛(2)→133 工具与审批(3)→★外循环技能自我改进(4)→有界记忆+FTS5 中文(5)→caching 铁律+micro-compaction(6)→34 平台含微信飞书钉钉(7)→subagent/kanban/MoA(8)→37 provider 中文生态(9)→轨迹管线+供应链(10)；第 10 章把循环产出接回训练，全书闭环。
4. 四点哲学：双循环（经验变资产）、器官化（183 万行不塌方的结构）、中文生态原生（入口到检索到模型全链路一等公民）、工程纪律（精确锁版+86 万行测试+30 CI 的免疫系统）。
5. 下一步四方向：改一个技能（验外循环）→接一个平台（验网关）→配一条国产链路（验生态）→跑一次研究管线（闭合双循环）。