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.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.2. 第二节：run_conversation() —— 主循环
    • 3.2.1. 方法签名
    • 3.2.2. 完整的时序图
  • 3.3. 第三节：流式架构
    • 3.3.1. 三种 API 模式
  • 3.4. 第四节：错误分类与恢复
    • 3.4.1. 14 种 FailoverReason
  • 3.5. 第五节：工具执行引擎
    • 3.5.1. 并行 vs 顺序决策
  • 3.6. 第六节：预算与迭代控制
    • 3.6.1. IterationBudget 的工作原理
  • 3.7. 第七节：会话持久化与清理
    • 3.7.1. 循环退出时的处理
    • 3.7.2. 轨迹保存
    • 3.7.3. 资源清理
  • 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.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.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.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/）
  • 网关层（gateway/）
  • TUI 网关层（tui_gateway/）
  • CLI 层（hermes_cli/）
  • 插件系统（plugins/）
  • 文件依赖关系