.. _part2:

第二部分：从 Hermes 学到的工程智慧
========================================

从"它如何运转"到"我们能学到什么"
------------------------------------

在第一部分中，我们花了十四个章节的篇幅，像外科医生解剖标本一样，
一层一层地拆解了 Hermes Agent 的每一个子系统：从核心的
observe-think-act 循环，到工具注册与调度，到上下文压缩，到
会话持久化，到网关 RPC，到多 Profile Kanban 协作，到插件和技能系统。
我们已经看到了每一行关键代码是如何工作的。

但理解一个系统如何运转只是工程学习的起点。

更深层的问题是：**这些设计决策背后的通用原则是什么？**

- 为什么有些模式让系统更健壮，而另一些模式积累了技术债务？
- 如果让你从零开始构建一个 Agent，你应该复制 Hermes 的哪些决策，又应该避免哪些？
- 在研究论文和博客文章中看起来优雅的方案，在 12,000 行生产代码中变成了什么样？

第二部分试图回答这些问题。我们从"描述性分析"转向"规范性总结"——
不再问"Hermes 是怎么做的"，而是问"从 Hermes 的做法中，
我们能提炼出哪些适用于任何 Agent 系统的工程原则"。

.. mermaid::
   :name: part2-learning-path
   :caption: 第二部分学习路径

   flowchart LR
       classDef start fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
       classDef success fill:#dcfce7,stroke:#16a34a,color:#166534
       classDef info fill:#f1f5f9,stroke:#64748b,color:#334155

       A["第一部分<br/>架构分析"] --> B{"抽象与提炼"}
       B --> C["工程教训<br/>模式总结"]
       B --> D["实践指南<br/>构建你自己的 Agent"]
       C --> E["可复用的设计模式"]
       C --> F["性能优化策略"]
       C --> G["错误处理哲学"]
       D --> H["最小可行 Agent"]
       D --> I["架构选型决策"]
       D --> J["完整示例架构"]

       class A start
       class C,D success
       class E,F,G,H,I,J info

论文与生产系统之间的鸿沟
--------------------------

在进入具体章节之前，让我们先直面一个行业内的核心矛盾。

Agent 研究论文描述的世界是干净的：一个 observe-think-act 循环，
若干个定义良好的工具，一个永远不会溢出的上下文窗口。在这个世界里，
模型总是返回格式正确的 JSON，API 永远不会超时，
用户输入永远不会包含恶意的 Unicode 字符。

生产系统的世界则是混乱的。仅以 Hermes 的错误分类器
（``agent/error_classifier.py``）为例：

- HTTP 402 状态码需要区分"账户余额耗尽"和"临时配额限制"，
  因为前者需要立即切换凭证，后者只需要等待重试。
- OpenRouter 将上游提供商的真实错误包裹在 ``metadata.raw``
  的 JSON 嵌套中，需要三层解包才能识别出真正的上下文溢出错误。
- 有些提供商将上下文溢出报告为 400 Bad Request 而非 413，
  而某些提供商的 400 可能是限流伪装的。
- 当没有 HTTP 状态码可用时（比如连接中断），只能通过错误消息
  的模式匹配来推断原因，而同时还要考虑会话规模来排除误报。

这些复杂性不会出现在任何论文中。它们是"将原型变为产品"的过程中
不可避免的摩擦力。Hermes 的代码库是一个极好的学习素材，
因为它完整地保留了这些摩擦力的痕迹——每一次提交都是一个关于
"理想与现实之间差距"的记录。

第二部分的章节结构
--------------------

本部分包含以下章节：

工程教训：从 12,000 行代码中提炼的模式
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

这一章从 Hermes 的架构中提炼出七大类可复用的工程模式：

**架构模式总结** 涵盖了 Strategy Pattern（API 路由）、
Self-Registration Pattern（工具注册表）、Observer Pattern（回调链）、
Adapter Pattern（API 响应归一化）、Circuit Breaker（MCP 断路器）、
Optimistic Concurrency Control（网关历史版本控制）、
Write-Ahead Log（SQLite WAL 模式）等核心设计模式。
每个模式都附有 Hermes 中的具体实现引用和适用场景分析。

**性能优化策略** 分析了 Hermes 中的五项关键性能优化：
持久化事件循环（避免 asyncio.run() 的陷阱）、三层结果预算系统、
Prompt 缓存策略（system_and_3 方案）、并行工具执行策略、
双层技能缓存。每项优化都解释了"为什么这样做"和"不这样做的后果"。

**错误处理哲学** 揭示了 Hermes 的 11 类错误分类体系，
以及抖动退避（jittered backoff）如何避免重试风暴，
还有优雅降级策略如何确保系统在子模块失败时仍然可用。

**可扩展性设计** 分析了插件钩子系统、MCP 动态工具发现、
工具集组合与菱形依赖解析、皮肤主题引擎等扩展机制。

**技术债务反思** 诚实面对 Hermes 的设计缺陷：
12,000 行的单文件上帝类、分散的提供商特定 hack、
父子 Agent 间的预算共享问题、缓存失效的复杂性。

构建你自己的 Agent：从零开始的实践指南
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

这是全书的压轴章节。我们不再分析 Hermes，而是教你如何从零构建
一个生产级 Agent。这一章提供了一个 200 行的最小可行 Agent 实现，
然后基于 Hermes 的经验教训，逐项讨论架构选型、工具系统设计、
上下文管理、多提供商支持和部署考量。

附录
~~~~~~

**术语表** 提供了全书中所有技术术语的中英文对照与定义。

**文件索引** 列出了 Hermes 仓库中所有关键文件的路径、
代码行数、职责和核心类/函数，按架构层次组织。

如何使用第二部分
------------------

**如果你是架构师或技术负责人** ，重点关注工程教训章节的架构模式总结
和技术债务反思。这些内容可以帮助你在设计评审中提出正确的问题。

**如果你是一线开发者** ，重点阅读构建你自己的 Agent 章节。
这一章提供了可以直接使用的代码模板和架构决策框架。

**如果你正在维护一个现有的 Agent 系统** ，工程教训章节中的
错误处理哲学和性能优化策略可能对你最有启发。将 Hermes 的
11 类错误分类方案与你系统的错误处理做对比，
通常能发现改进空间。

.. mermaid::
   :name: part1-to-part2-mapping
   :caption: 第一部分与第二部分的对应关系

   flowchart TB
       classDef start fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
       classDef success fill:#dcfce7,stroke:#16a34a,color:#166534
       classDef warn fill:#fef9c3,stroke:#ca8a04,color:#854d0e

       subgraph P1["第一部分：架构分析"]
           A1["Agent Loop"]
           A2["工具系统"]
           A3["Prompt 管线"]
           A4["上下文压缩"]
           A5["会话与状态"]
           A6["CLI / 网关"]
           A7["插件 / 技能"]
           A8["模型路由"]
           A9["安全 / 配置"]
       end
       subgraph P2["第二部分：经验与实战"]
           B1["架构模式总结"]
           B2["性能优化策略"]
           B3["错误处理哲学"]
           B4["可扩展性设计"]
           B5["技术债务反思"]
           B6["最小可行 Agent"]
           B7["架构选型决策"]
           B8["完整示例架构"]
       end
       A1 --> B1
       A2 --> B1
       A3 --> B2
       A4 --> B2
       A5 --> B3
       A6 --> B4
       A7 --> B4
       A8 --> B3
       A9 --> B5
       B1 --> B6
       B2 --> B7
       B3 --> B8
       B4 --> B8
       B5 --> B7

       class A1,A2,A3,A4,A5,A6,A7,A8,A9 start
       class B6,B7,B8 success
       class B1,B2,B3,B4,B5 warn

一个阅读建议：不要把第二部分当作独立的指南来读。
它的价值在于与第一部分的对照。当你读到"Self-Registration Pattern"
的总结时，回去看看 ``tools/registry.py`` 中 ``_module_registers_tools()``
的 AST 预检查技巧。当你读到"11 类错误分类"的概述时，
对照 ``agent/error_classifier.py`` 中完整的分类管线。
这种来回对照的阅读方式，能让抽象的原则与具体的实现相互印证，
加深理解。

准备好了吗？让我们从 Hermes 的 12,000 行代码中提炼智慧。