Hermes Agent 架构深度解析
1. 前言：从一个真实的生产级 AI Agent 中学习架构
1.1. 为什么要写这本书？
1.1.1. 为什么是 Hermes Agent？
1.2. 为什么通过真实代码学习？
1.3. 如何阅读这本书
1.3.1. 推荐阅读路径
1.3.2. 代码引用约定
1.4. 前置知识
1.4.1. Python 编程
1.4.2. LLM API 基础
1.4.3. 异步编程概念
1.5. 章节概览
1.5.1. 第一部分：基础（Part 1）
1.5.2. 核心架构
1.5.3. 平台层
1.5.4. 第二部分：经验与实战（Part 2）
1.5.5. 附录
1.6. 本书的边界
1.7. 致谢
2. 第一部分：基础概念
2.1. 什么是 AI Agent？
2.1.1. 定义
2.1.1.1. 与聊天机器人的区别
2.1.1.2. 与 RAG 管线的区别
2.1.1.3. 一个精确的工作定义
2.2. 基础循环：Observe → Think → Act → Observe
2.3. Agent 架构的演进
2.3.1. ReAct (2022)
2.3.2. Reflexion (2023)
2.3.3. Toolformer (2023)
2.3.4. AutoGPT (2023)
2.4. 为什么要工具、记忆和规划？
2.4.1. 工具：Agent 的手脚
2.4.2. 记忆：Agent 的经验
2.4.3. 规划：Agent 的大脑
2.5. 通用 Agent 架构模式
2.6. Hermes 如何映射到这些概念
3. 核心循环：Agent Loop 的完整生命周期
3.1. 第一节：AIAgent 类的架构
3.1.1. 类概览
3.1.1.1. 属性分组
3.1.1.2. 类图
3.2. 第二节：run_conversation() —— 主循环
3.2.1. 方法签名
3.2.2. 完整的时序图
3.2.2.1. 步骤详解
3.3. 第三节：流式架构
3.3.1. 三种 API 模式
3.3.1.1. 统一的 SimpleNamespace 响应模式
3.3.1.2. 流式数据的累积
3.3.1.3. 流式数据流图
3.3.1.4. 思考泄漏防护（Think Scrubber）
3.3.1.5. 为什么 Hermes 不使用 async/await？
3.4. 第四节：错误分类与恢复
3.4.1. 14 种 FailoverReason
3.4.1.1. 错误分类管道
3.4.1.2. 抖动指数退避
3.4.1.3. 错误恢复的状态机
3.5. 第五节：工具执行引擎
3.5.1. 并行 vs 顺序决策
3.5.1.1. Agent 循环拦截工具
3.5.1.2. 调用链：_invoke_tool → handle_function_call → registry.dispatch
3.5.1.3. 工具名幻觉修复
3.6. 第六节：预算与迭代控制
3.6.1. IterationBudget 的工作原理
3.6.1.1. 父 Agent 与子 Agent 的预算共享
3.6.1.2. 预算耗尽的宽限机制
3.7. 第七节：会话持久化与清理
3.7.1. 循环退出时的处理
3.7.2. 轨迹保存
3.7.3. 资源清理
3.7.3.1. 后台审查线程
3.7.3.2. 插件钩子
3.8. 总结
4. 工具系统：从注册到执行的完整管道
4.1. 1. 工具系统设计哲学
4.1.1. 为什么 Agent 需要工具？
4.1.2. 自注册模式：去中心化的工具管理
4.2. 2. 注册表单例 (ToolRegistry)
4.2.1. 单例模式与线程安全
4.2.2. ToolEntry：使用 __slots__ 优化
4.2.3. 快照机制：线程安全的读取
4.2.4. 注册 API：工具的自声明
4.2.5. 注销 API：动态工具管理
4.2.6. 工具注册流程图
4.3. 3. AST 预扫描发现机制
4.3.1. 问题：导入的成本
4.3.2. AST 扫描的实现
4.3.3. 发现与导入流程
4.4. 4. 工具集系统
4.4.1. 工具集的设计目标
4.4.2. 共享工具列表
4.4.3. 递归解析与循环检测
4.4.4. 工具集解析流程图
4.5. 5. 参数类型强制转换
4.5.1. 问题的根源
4.5.2. 类型强制转换的实现
4.5.3. 值转换逻辑
4.5.4. 数字转换
4.5.5. 布尔转换
4.6. 6. 执行调度
4.6.1. 调度流程总览
4.6.2. Agent Loop 拦截
4.6.3. 钩子系统
4.6.4. 注册表调度
4.6.5. 工具调度流程图
4.7. 7. Agent Loop 拦截
4.7.1. 为什么需要拦截？
4.7.2. 拦截的工作原理
4.7.3. 注册表中的占位符
4.8. 8. 结果持久化与预算
4.8.1. 三层防御策略
4.8.2. 工具级最大结果大小
4.8.3. 结果持久化
4.8.4. 轮次预算
4.9. 9. 工具安全护栏 (Tool Guardrails)
4.9.1. 安全护栏的设计理念
4.9.2. 文件操作安全：file_safety.py
4.9.3. 护栏系统的整体架构
4.10. 10. 写后增量检查 (Post-write Delta Lint)
4.10.1. 问题：写入后的沉默失败
4.10.2. 增量检查的工作原理
4.10.3. 支持的文件类型
4.10.4. 为什么选择进程内检查？
4.10.5. 与调度管道的集成
4.11. 11. 并行执行引擎
4.11.1. 并行执行的好处
4.11.2. 工具分类
4.11.3. 并行决策流程图
4.12. 12. 异步桥接
4.12.1. 为什么需要异步桥接？
4.12.2. 持久化事件循环
4.12.3. _run_async()：统一的桥接
4.13. 扩展工具集
4.13.1. 代码执行工具（PTC）
4.13.2. Mixture-of-Agents 工具
4.13.3. 环境执行后端
4.13.4. 浏览器工具
4.13.5. 其他扩展工具
4.14. 总结
5. 提示工程管线：如何组装一个完美的 System Prompt
5.1. 1. 提示工程的挑战
5.1.1. 为什么 System Prompt 如此重要？
5.1.2. 提示工程的核心矛盾
5.2. 2. 提示组装管线总览
5.2.1. 9 槽位管道概览
5.2.2. 提示组装管线流程图
5.3. 3. Agent 身份层 (SOUL.md)
5.3.1. 身份的定义
5.3.2. 自定义身份：SOUL.md
5.4. 4. 平台适配层
5.4.1. 13 个平台提示
5.4.2. 平台适配的关键考量
5.4.3. 媒体发送机制
5.5. 5. 环境感知层
5.5.1. WSL 检测
5.5.2. 环境检测函数
5.6. 6. 记忆与搜索指导
5.6.1. 记忆指导 (MEMORY_GUIDANCE)
5.6.2. 会话搜索指导 (SESSION_SEARCH_GUIDANCE)
5.6.3. 技能指导 (SKILLS_GUIDANCE)
5.7. 7. 模型特定执行规范
5.7.1. 工具使用强制指导
5.7.2. OpenAI 模型执行指导
5.7.3. Google 模型操作指导
5.7.4. 角色映射
5.8. 8. 技能索引系统
5.8.1. 双层缓存架构
5.8.2. 缓存键的设计
5.8.3. 磁盘快照
5.8.4. 技能条件过滤
5.8.5. 技能索引的输出格式
5.8.6. 技能缓存查找流程图
5.9. 9. 上下文文件优先级
5.9.1. 优先级顺序
5.9.2. .hermes.md 的搜索范围
5.9.3. 内容截断
5.9.4. YAML Frontmatter 处理
5.9.5. 上下文文件解析优先级流程图
5.10. 10. 提示注入防御
5.10.1. 13 种检测模式
5.10.2. Unicode 不可见字符扫描
5.10.3. 扫描与阻止流程
5.11. 11. Anthropic Prompt 缓存
5.11.1. 为什么需要 Prompt 缓存？
5.11.2. system_and_3 策略
5.11.3. 缓存标记的注入
5.11.4. 成本节省分析
5.11.5. Anthropic 缓存策略流程图
5.12. 总结
6. 上下文压缩：当对话超出 Token 限制
6.1. 为什么需要上下文压缩
6.1.1. Token 限制的现实
6.1.2. 成本和延迟的影响
6.1.3. 简单截断 vs. 结构化压缩
6.2. 压缩引擎抽象（ContextEngine ABC）
6.2.1. 设计理念
6.2.2. 核心接口
6.2.3. 可选扩展
6.2.4. 插件选择机制
6.3. 触发条件与阈值设计
6.3.1. 基础阈值：threshold_percent
6.3.2. 反抖动保护（Anti-Thrashing）
6.4. Phase 1: 工具结果修剪（_prune_old_tool_results）
6.4.1. 为什么先修剪工具结果？
6.4.2. Hash 去重
6.4.3. 28 种工具摘要器
6.4.4. 工具参数 JSON 截断
6.4.5. 修剪边界确定
6.5. Phase 2: 边界确定
6.5.1. 三段式分割
6.5.2. 头部保护：protect_first_n=3
6.5.3. 尾部保护：Token 预算而非固定消息数
6.5.4. 边界对齐：避免拆分工具调用组
6.6. Phase 3: LLM 摘要生成
6.6.1. 首次摘要 vs. 迭代更新
6.6.2. 摘要结构模板
6.6.3. 摘要模型的提示词设计
6.6.4. 摘要的 Token 预算
6.6.5. 序列化与截断
6.6.6. 焦点话题（Focus Topic）
6.7. Phase 4: 消息组装
6.7.1. 组装流程
6.7.2. 系统提示注入
6.7.3. 摘要前缀（SUMMARY_PREFIX）
6.7.4. 角色选择与冲突避免
6.8. Phase 5: Tool 对清理
6.8.1. 工具调用的配对约束
6.9. 失败降级和迭代压缩
6.9.1. 摘要生成失败的降级策略
6.9.2. 静态回退上下文标记
6.9.3. 迭代压缩的效果追踪
6.10. 配置参数速查表
6.11. 总结
7. 状态与会话管理：Agent 的记忆系统
7.1. 为什么 Agent 需要持久化
7.1.1. 无状态 Agent 的局限
7.1.2. 持久化的需求层次
7.2. SessionDB 架构概览
7.2.1. 技术选型：为什么是 SQLite？
7.2.2. WAL 模式详解
7.3. 数据库 Schema 详解
7.3.1. Schema 版本管理
7.3.2. sessions 表
7.3.3. 索引设计
7.3.4. messages 表
7.4. FTS5 全文搜索
7.4.1. FTS5 虚拟表结构
7.4.2. 同步触发器
7.4.3. 查询清理器（_sanitize_fts5_query）
7.4.4. CJK 回退机制
7.5. 写入并发控制
7.5.1. 问题：多进程写竞争
7.5.2. 解决方案：BEGIN IMMEDIATE + 随机抖动
7.5.3. WAL 检查点
7.6. 会话生命周期
7.6.1. 创建会话（create_session）
7.6.2. 追加消息（append_message）
7.6.3. 结束会话（end_session）
7.6.4. 重新打开会话（reopen_session）
7.6.5. 确保会话存在（ensure_session）
7.6.6. 删除会话（delete_session）
7.6.7. 修剪旧会话（prune_sessions）
7.7. 会话分支机制
7.7.1. 分支的设计动机
7.7.2. 标题的血脉继承
7.7.3. 标题验证与清理
7.8. Token 计数双模式
7.8.1. 增量模式 vs. 绝对模式
7.8.2. 计费信息
7.9. 消息加载
7.9.1. 两种加载格式
7.9.2. 还原时的反序列化
7.10. 会话列表与富预览
7.10.1. 单查询优化
7.10.2. 子会话过滤
7.11. ID 解析
7.12. Schema 迁移链 v1→v6
7.12.1. 迁移策略
7.12.2. 迁移历史
7.13. 轨迹记录
7.13.1. 轨迹格式
7.13.2. Scratchpad 转换
7.14. 会话 ID 解析
7.15. 导出与备份
7.15.1. 单会话导出
7.15.2. 全量导出
7.15.3. 消息清除
7.16. 配置参数速查表
7.17. 总结
8. 配置管理：分层配置系统
8.1. 配置层级（4 层）
8.2. DEFAULT_CONFIG 结构
8.2.1. 模型与 Provider
8.2.2. Agent 行为
8.2.3. 终端与沙箱
8.2.4. 浏览器
8.2.5. 上下文压缩
8.2.6. 辅助任务配置
8.2.7. 审批系统
8.2.8. 安全配置
8.2.9. 显示与交互
8.2.10. 配置版本控制
8.3. load_config() 深度合并
8.3.1. 深度合并逻辑
8.3.2. 环境变量展开
8.3.3. 配置路径
8.4. 环境变量管理
8.4.1. load_env() 加载
8.4.2. save_env_value() 保存
8.4.3. get_env_value() 查询
8.4.4. 可选环境变量注册表
8.5. Profile 系统
8.5.1. HERMES_HOME 覆盖
8.5.2. 隔离的资源
8.6. 配置迁移
8.6.1. 版本追踪
8.6.2. 迁移流程
8.6.3. 向后兼容处理
8.6.4. Managed 模式
8.6.5. 容器感知
8.7. 国际化（i18n）支持
8.7.1. 支持的语言
8.7.2. 配置方法
8.7.3. i18n 框架实现
8.8. Model Aliases 配置
8.9. 安全与权限
8.9.1. 文件权限
8.9.2. 密钥脱敏
8.9.3. 非 ASCII 凭证检查
8.10. 总结
9. 模型路由：多 Provider 的统一接入层
9.1. 为什么需要多 Provider
9.1.1. 成本多样性
9.1.2. 可用性保障
9.1.3. 能力差异
9.2. Provider 注册表
9.2.1. Provider 注册表：HermesOverlay 与 models.dev
9.2.1.1. HermesOverlay 数据类
9.2.1.2. models.dev 注册表
9.2.1.3. 双数据源合并
9.3. 辅助客户端路由
9.4. 文本/视觉任务的优先级链
9.4.1. 文本任务优先级链
9.4.2. 视觉任务优先级链
9.5. 客户端适配器模式
9.5.1. CodexAuxiliaryClient（Responses -> ChatCompletions）
9.5.2. AnthropicAuxiliaryClient
9.5.3. 异步适配器
9.6. 客户端缓存架构
9.6.1. 缓存设计要点
9.6.2. 异步客户端的事件循环验证
9.6.3. 启动和关闭
9.7. 支付错误自动回退
9.7.1. 支付错误检测
9.7.2. 回退链
9.8. 模型特定策略
9.8.1. 固定温度
9.8.2. Developer 角色处理
9.8.3. Anthropic 兼容 Provider
9.8.4. Opus 4.7+ 采样参数限制
9.9. 上下文长度解析 10 级优先级
9.9.1. 本地服务器类型检测
9.9.2. URL 到 Provider 推断
9.10. Token 估算
9.10.1. estimate_tokens_rough
9.10.2. estimate_request_tokens_rough
9.10.3. 上下文探测阶梯
9.11. models.dev 注册表
9.11.1. 数据解析链
9.11.2. Provider ID 映射
9.11.3. 隐藏模型过滤
9.11.4. Agent 模型过滤
9.12. 错误消息解析
9.12.1. 上下文限制提取
9.12.2. 可用输出 Token 提取
9.13. 客户端适配器
9.13.1. 适配器架构
9.13.2. AnthropicAdapter
9.13.3. BedrockAdapter
9.13.4. GeminiCloudCodeClient
9.14. 总结
10. CLI 与 UI 系统：构建交互式 Agent 界面
10.1. 为什么 Agent 需要精心设计的 UI
10.2. CLI 架构总览
10.2.1. 入口点解析
10.2.2. HermesCLI 类的生命周期
10.3. prompt_toolkit 集成
10.3.1. Layout 布局结构
10.3.2. KeyBindings 键绑定
10.3.3. Completer 补全器
10.3.4. AutoSuggest 自动建议
10.4. 输入路由优先级
10.4.1. 各级别详细说明
10.5. Slash 命令系统
10.5.1. CommandDef 数据类
10.5.2. 命令解析流程
10.5.3. 别名解析机制
10.5.4. Tab 补全实现
10.6. 皮肤/主题引擎
10.6.1. SkinConfig 数据结构
10.6.2. 内置主题
10.6.3. 颜色键系统
10.6.4. 继承机制
10.6.5. prompt_toolkit 样式桥接
10.7. KawaiiSpinner
10.7.1. 9 种动画风格
10.7.2. Kawaii 表情
10.7.3. 线程安全渲染
10.7.4. 环境适配
10.8. 工具预览系统
10.8.1. build_tool_preview()
10.8.2. get_cute_tool_message()
10.8.3. 工具失败检测
10.9. 内联 Diff 系统
10.9.1. LocalEditSnapshot
10.9.2. 皮肤感知的 ANSI 渲染
10.10. 交互模式
10.10.1. Clarify（澄清）
10.10.2. Approval（审批）
10.10.3. Secret（密码输入）
10.11. 状态栏三层自适应
10.11.1. 颜色编码
10.12. Ctrl+C 分级处理
10.13. 扩展 CLI 命令生态
10.13.1. Kanban 看板系统
10.13.2. Curator 内容管理
10.13.3. Voice 语音系统
10.13.4. Hooks 钩子系统
10.13.5. Goals 目标追踪
10.13.6. Onboarding 新手引导
10.13.7. Account Usage 用量追踪
10.13.8. 其他 CLI 改进
10.14. 源码文件索引
11. TUI Gateway：跨进程 JSON-RPC 通信
11.1. 为什么需要 Gateway
11.2. 通信协议
11.2.1. 请求格式
11.2.2. 响应格式
11.2.3. Stdout 保护
11.2.4. 错误码体系
11.3. 双调度架构
11.3.1. 内联处理器（主线程）
11.3.2. 长时处理器（线程池）
11.4. 初始化握手
11.4.1. 信号处理
11.5. prompt.submit 完整流程
11.5.1. 时序分析
11.6. 56 个 RPC 方法分类表
11.6.1. Session（会话管理）— 13 个方法
11.6.2. Prompt（提示处理）— 4 个方法
11.6.3. Media（媒体附件）— 2 个方法
11.6.4. Interaction（交互响应）— 4 个方法
11.6.5. Config（配置管理）— 3 个方法
11.6.6. Completion（补全）— 2 个方法
11.6.7. Command（命令）— 4 个方法
11.6.8. Voice（语音）— 3 个方法
11.6.9. Model & Tools（模型与工具）— 6 个方法
11.6.10. System（系统管理）— 8 个方法
11.6.11. Rollback（快照回滚）— 3 个方法
11.6.12. Advanced（高级功能）— 4 个方法
11.7. 阻塞式提示机制
11.7.1. _block() 函数
11.7.2. 超时处理
11.7.3. _pending 字典结构
11.7.4. 响应路由
11.8. 会话内存管理
11.8.1. _sessions 字典结构
11.8.2. Agent 实例生命周期
11.8.3. 孤儿会话清理
11.9. 乐观并发控制
11.9.1. history_version 机制
11.9.2. busy-state 守卫
11.10. SlashWorker 子进程
11.10.1. 通信协议
11.10.2. 序列号管理
11.10.3. 超时控制
11.10.4. Stderr 尾部追踪
11.10.5. 生命周期管理
11.11. Agent 回调系统
11.11.1. 回调注册
11.11.2. tool_start / tool_complete
11.11.3. tool_progress 回调
11.11.4. thinking / reasoning
11.11.5. clarify 回调
11.12. 消息队列与 busy→false 转换
11.12.1. Drain 机制
11.12.2. 事件顺序保证
11.13. 内存与资源管理
11.13.1. 配置缓存
11.13.2. 会话关闭
11.13.3. 进程退出
11.14. Platform 适配器基类
11.14.1. BasePlatformAdapter 接口
11.14.2. 消息处理流水线
11.14.3. 平台注册与生命周期
11.15. Stream Consumer：Agent 输出流处理
11.15.1. 核心设计
11.15.2. 核心职责
11.16. API Server：HTTP/SSE 接口
11.16.1. X-Hermes-Session-Key：长期记忆作用域
11.16.2. SSE 流式输出
11.17. 源码文件索引
12. MCP 集成：Model Context Protocol 的生产级实现
12.1. MCP 协议概述
12.2. 传输层架构
12.2.1. Stdio 传输
12.2.2. HTTP/StreamableHTTP 传输
12.3. 连接生命周期
12.3.1. MCPServerTask 的核心状态
12.3.2. 连接流程
12.3.3. 重连与指数退避
12.4. 工具注册格式
12.4.1. 命名规范
12.4.2. 工具集（Toolset）
12.4.3. Schema 转换
12.4.4. 工具过滤
12.5. OAuth 2.1 PKCE 认证
12.5.1. 配置方式
12.5.2. HermesTokenStorage
12.5.3. 跨进程令牌重载
12.5.4. 401 去重（Thundering Herd 保护）
12.6. 动态工具发现
12.6.1. 消息处理器
12.6.2. 刷新机制
12.7. 熔断器模式
12.7.1. 工作原理
12.8. Sampling 支持
12.8.1. 配置
12.8.2. 速率限制
12.8.3. 工具循环治理
12.8.4. 消息转换
12.9. 安全机制
12.9.1. 环境变量过滤
12.9.2. 工具描述注入扫描
12.9.3. 工具名称清洗
12.9.4. 凭据脱敏
12.9.5. OSV 恶意软件检查
12.10. 与内置工具的冲突保护
12.10.1. 线程安全架构
12.10.2. 总结
13. 插件系统：可扩展的 Agent 架构
13.1. 为什么需要插件系统
13.2. 插件发现
13.2.1. 用户插件
13.2.2. 项目插件
13.2.3. Pip 入口点插件
13.2.4. 发现流程
13.3. plugin.yaml 格式
13.3.1. 字段说明
13.3.2. 清单解析
13.4. PluginContext API
13.4.1. register_tool
13.4.2. register_hook
13.4.3. register_command
13.4.4. register_cli_command
13.4.5. register_context_engine
13.4.6. register_skill
13.4.7. inject_message
13.4.8. dispatch_tool
13.5. 生命周期钩子
13.5.1. 钩子列表
13.5.2. pre_tool_call：策略执行
13.5.3. pre_llm_call：上下文注入
13.5.4. on_session_start/end：会话生命周期
13.6. Hook 执行机制
13.6.1. 异常隔离
13.6.2. 模块级便捷函数
13.7. 内存提供者插件
13.7.1. Hindsight 的后续改进
13.8. 上下文引擎插件
13.8.1. 插件技能注册
13.8.2. 插件管理的全局单例模式
13.8.3. 插件加载的错误处理
13.9. 运营类插件
13.10. 插件工具合并与命令发现
13.10.1. 总结
14. 技能系统：Agent 的可复用知识单元
14.1. 什么是技能
14.2. 技能来源
14.2.1. 内置技能（Bundled Skills）
14.2.2. Hub 安装技能（Hub-installed Skills）
14.2.3. 用户创建技能（User-created Skills）
14.2.4. 插件提供技能（Plugin-provided Skills）
14.3. SKILL.md 格式
14.3.1. 完整格式
14.3.2. 前置元数据字段详解
14.3.2.1. name 和 description
14.3.2.2. platforms
14.3.2.3. prerequisites 和 required_environment_variables
14.3.2.4. triggers、fallback_for 和 requires_toolsets
14.3.2.5. metadata.hermes
14.3.3. 正文结构
14.4. 技能管理工具
14.4.1. create：创建技能
14.4.2. edit：编辑技能
14.4.3. patch：补丁技能
14.4.4. delete：删除技能
14.4.5. write_file：写入支持文件
14.4.6. remove_file：删除支持文件
14.4.7. 原子写入与回滚
14.5. 技能索引构建
14.5.1. 索引内容
14.5.2. 条件激活
14.5.3. 索引缓存
14.6. 同步机制
14.6.1. 清单格式
14.6.2. 同步策略
14.6.3. 哈希计算
14.6.4. 原子清单写入
14.6.5. 重置功能
14.6.6. 类别描述
14.7. 技能缓存
14.7.1. 内存 LRU 缓存
14.7.2. 磁盘快照缓存
14.7.3. 缓存清除
14.7.4. 技能查找策略
14.7.5. 安全检查
14.7.6. 总结
15. 安全设计：Agent 的攻防考量
15.1. Agent 安全的独特挑战
15.1.1. LLM 作为攻击面
15.1.2. 工具访问的放大效应
15.1.3. 持久上下文的累积风险
15.2. 提示注入防御
15.2.1.
_scan_context_content()
函数
15.2.2. 10 种威胁模式
15.2.3. 不可见 Unicode 字符
15.3. MCP 安全
15.3.1. 工具描述注入扫描
15.3.2. 环境变量过滤
15.3.3. 凭证错误消息净化
15.3.4. 工具名称清洗
15.4. 审批系统
15.4.1. 危险命令检测
15.4.2. 命令规范化
15.4.3. 审批决策流程
15.4.4. Cron 模式特殊处理
15.4.5. 敏感写入目标
15.5. 凭证管理
15.5.1. .env 文件隔离
15.5.2. 凭证来源抑制
15.5.3. 凭证错误消息脱敏
15.5.4. 显式配置门控
15.5.5. 凭证池
15.5.6. Auth Store 锁机制
15.6. 沙箱执行
15.6.1. execute_code 沙箱
15.6.2. 环境变量清理
15.6.3. Docker 沙箱配置
15.6.4. 代码执行模式
15.6.5. 浏览器隔离
15.7. 工具冲突保护
15.7.1. 命名空间前缀
15.7.2. 注册顺序保护
15.7.3. 最小权限原则
15.8. 预执行安全扫描（Tirith）
15.9. 安全设计的权衡
15.9.1. 误报容忍度
15.9.2. 性能影响
15.9.3. 深度防御
15.10. 总结
16. Kanban：多 Profile 协作的任务看板
16.1. 为什么 Agent 需要 Kanban
16.1.1. 单 Agent 的局限
16.1.2. Hermes Kanban 的设计目标
16.1.3. 设计决策：SQLite 而非消息队列
16.2. 架构总览
16.2.1. 三大接入面，一条代码路径
16.2.1.1. 数据模型
16.3. 调度器：核心循环
16.3.1. Tick 循环的五个阶段
16.3.2. Worker Spawn 机制
16.3.3. 失败熔断器
16.4. Worker 生命周期
16.4.1. Kanban 工具集
16.4.2. Worker 的交接上下文
16.4.3. 幻觉门控
16.5. CLI 命令参考
16.5.1. Board 管理
16.5.2. 任务生命周期
16.5.3. Worker 操作
16.5.4. 可观测性
16.6. 诊断引擎
16.6.1. 五条诊断规则
16.7. Dashboard UI
16.7.1. 看板视图
16.7.2. 交互功能
16.7.3. 实时更新
16.7.4. REST API
16.8. 集成点
16.8.1. Gateway 集成
16.8.2. Profile 系统集成
16.8.3. Skills 系统集成
16.8.4. 通知系统集成
16.9. 配置参考
16.10. 协作模式
16.11. 关键源文件
17. 第二部分：从 Hermes 学到的工程智慧
17.1. 从"它如何运转"到"我们能学到什么"
17.2. 论文与生产系统之间的鸿沟
17.3. 第二部分的章节结构
17.3.1. 工程教训：从 12,000 行代码中提炼的模式
17.3.2. 构建你自己的 Agent：从零开始的实践指南
17.3.3. 附录
17.4. 如何使用第二部分
18. 工程教训：从 12,000 行代码中提炼的模式
18.1. 架构模式总结
18.1.1. Strategy Pattern：API 路由
18.1.2. Self-Registration Pattern：工具注册表
18.1.3. Observer Pattern：回调链
18.1.4. Adapter Pattern：API 响应归一化
18.1.5. Circuit Breaker：MCP 断路器
18.1.6. Optimistic Concurrency Control：网关历史版本
18.1.7. Write-Ahead Log：SQLite WAL 模式
18.2. 性能优化策略
18.2.1. 持久化事件循环：避免 asyncio.run() 的陷阱
18.2.2. 三层结果预算系统
18.2.3. Prompt 缓存：system_and_3 策略
18.2.4. 并行工具执行策略
18.2.5. 双层技能缓存
18.3. 错误处理哲学
18.3.1. 11 类错误分类：精确优于泛型重试
18.3.2. 抖动退避：避免重试风暴
18.3.3. 优雅降级
18.4. 可扩展性设计
18.4.1. 插件钩子系统
18.4.2. MCP 动态工具发现
18.4.3. 工具集组合与菱形依赖
18.4.4. 皮肤主题引擎
18.5. 技术债务反思
18.5.1. 12,000 行的上帝类
18.5.2. 分散的提供商特定 Hack
18.5.3. 父子 Agent 间的预算共享
18.5.4. 缓存失效复杂性
18.6. 模式与反模式总结
19. 构建你自己的 Agent：从零开始的实践指南
19.1. 最小可行 Agent：200 行 Python
19.2. 架构选型决策
19.2.1. 单块 vs 微服务
19.2.2. 同步 vs 异步
19.2.3. 数据库：SQLite vs PostgreSQL
19.2.4. 通信协议：JSON-RPC vs gRPC vs REST
19.3. 工具系统设计
19.3.1. 第一步：定义工具注册接口
19.3.2. 第二步：实现自注册模式
19.3.3. 第三步：参数验证与类型强制转换
19.3.4. 第四步：并行执行策略
19.4. 上下文管理策略
19.4.1. 何时压缩
19.4.2. 如何摘要
19.4.3. Token 预算
19.4.4. 缓存策略
19.5. 多 Provider 支持
19.5.1. 适配器模式实现
19.5.2. 客户端缓存考量
19.5.3. 错误恢复跨提供商
19.6. 部署考量
19.6.1. CLI vs Web vs API
19.6.2. 进程隔离：SlashWorker 模式
19.6.3. 会话持久化
19.7. 一个完整的示例架构
19.7.1. 数据流：从用户到 LLM 再回来
19.7.2. 推荐技术栈
19.8. 从原型到生产的路线图
19.9. 最后的话
术语表
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
R
S
T
W
文件索引
核心层
Agent 子系统（agent/）
工具系统（tools/）
执行环境子目录（tools/environments/）
浏览器提供者子目录（tools/browser_providers/）
网关层（gateway/）
内置钩子子目录（gateway/builtin_hooks/）
网关平台适配器（gateway/platforms/）
TUI 网关层（tui_gateway/）
CLI 层（hermes_cli/）
插件系统（plugins/）
文件依赖关系
Hermes Agent 架构深度解析
搜索
请启用 JavaScript 以便使用搜索功能