Hermes Agent 策略全景图 - 七脉的笔记

Hermes Agent 策略全景图 — Hermes Agent 核心策略全景

1. 智能体分配策略

策略类型	触发条件	关键参数	行为描述
子智能体委派	模型调用 delegate_task 工具	最大并发: 3, 深度: 1层, 迭代上限: 50	ThreadPoolExecutor 并行子 AIAgent，每个独立迭代预算，默认工具集 [terminal, file, web]
后台审阅	每回合结束后自动 spawn	max_iterations: 16, 工具白名单: memory + skills	守护线程中运行，限制工具集，自动拒绝危险命令，审阅记忆和技能状态
策展人 (Curator)	空闲 > 2小时 + 距上次策展 > 7天	过期: 30天未用, 归档: 90天未用, Pinned 技能豁免	定期技能生命周期管理：过期技能标记，归档旧技能，pinned 技能永不过期
Cron 定时任务	调度器每 60s tick，检查到期任务	Agent 迭代上限: 90, 超时: 600s, 禁用工具集: cronjob/messaging/clarify	独立 AIAgent(platform=cron, quiet_mode=True)，禁止发消息和交互澄清

2. 记忆系统策略

策略类型	触发条件	关键参数	行为描述
记忆预取	每回合开始，LLM 调用前	prefetch_all(query, session_id)	查询所有已注册 Provider，检索相关记忆注入 volatile 提示词层
记忆异步预取	每回合结束后	queue_prefetch_all(query)	后台线程为下一回合提前预热预取缓存，非阻塞
记忆回写	每回合结束后	sync_all(user, assistant, messages)	后台单线程工作者序列化写入，保证顺序(Turn N 先于 N+1)，超时 5s drain
外部 Provider 限制	初始化时	仅允许 1 个外部 Provider	防止工具 schema 膨胀和后端冲突，内置文件记忆始终运行
记忆提示注入	构建系统提示词时	MEMORY.md 上限 2200 字符, USER.md 上限 1375 字符	记忆内容注入 volatile 层，StreamingContextScrubber 自动从流式输出中剥离标签
记忆提醒间隔	每 N 回合	nudge_interval: 10 回合	定期提醒 Agent 使用记忆工具记录重要信息
会话切换通知	Session ID 变化时	on_session_switch(reset/rewound)	通知所有 Provider 刷新缓存的会话状态

3. 技能系统策略

策略类型	触发条件	关键参数	行为描述
技能扫描	启动时 / 缓存失效时	目录: ~/.hermes/skills/ + 外部目录	递归查找所有 SKILL.md，解析 frontmatter，按分类索引
技能过滤	扫描时逐个检查	平台匹配 + 环境匹配 + 禁用列表	platforms/frontmatter 限制平台，disabled 列表排除，environment 变量检查
技能条件可见	构建技能索引时	fallback_for_toolsets / requires_toolsets	缺少高级工具集时显示降级技能；需要特定工具集时才显示高级技能
技能索引缓存	每次构建技能提示词	LRU 缓存: 8 条, 磁盘快照: .skills_prompt_snapshot.json	双层缓存：进程 LRU + 磁盘 mtime 校验，命中跳过全量扫描
焦点模式降级	编码姿态下	compact_categories 降级	整个分类只显示技能名称（无描述），保留可召回性，减少 token 消耗
技能提醒间隔	每 N 回合	creation_nudge_interval: 10 回合	定期提醒 Agent 管理技能（创建/更新）
技能查看计数	每次 skill_view 调用	bump_view + bump_use	更新 last_used_at，作为策展人过期/归档判断依据
技能安全扫描	注入上下文前	_scan_for_threats(scope=context)	检测注入攻击模式，威胁文件替换为 [BLOCKED] 占位

4. ReAct 循环策略

策略类型	触发条件	关键参数	行为描述
循环入口	run_conversation 调用后	max_iterations: 90 (主Agent) / 50 (子Agent)	双重预算门控: api_call_count + iteration_budget.remaining，任一耗尽退出
预算宽限调用	双重预算均耗尽时	_budget_grace_call: 一次性	允许最后 1 次 API 调用做摘要/收尾，之后强制退出
工具调用继续	响应包含 tool_calls	—	执行工具 → 结果附加到 messages → continue 循环
文本响应退出	无 tool_calls + 非空 content	—	认为是最终回复，break 退出循环
空响应重试	无 tool_calls + 空 content	最多 3 次空重试，然后 fallback	重试失败后激活 fallback 模型链
长度续写	finish_reason == length	续写重试: 3 次, max_tokens 递增	追加续写提示词，逐步提升输出 token 上限
execute_code 预算退还	execute_code 工具执行后	自动 refund	编程工具的迭代调用不消耗主预算

5. 工具护栏策略

策略类型	触发条件	关键参数	行为描述
精确失败警告	同一工具+参数连续失败	warn: 2次, block: 5次	2 次相同调用失败后附加指导，5 次后阻止执行(hard_stop_enabled 时)
同类工具失败	同一工具(不同参数)连续失败	warn: 3次, halt: 8次	3 次同工具失败警告，8 次后终止整个回合
幂等无进展	只读工具返回相同结果	warn: 2次, block: 5次	检测到循环读取同一内容无进展时警告或阻止
决策动作	护栏检查后	ALLOW / WARN / BLOCK / HALT	ALLOW=正常执行, WARN=执行+附指导, BLOCK=阻止单次执行, HALT=终止整个回合
工具分类	启动时静态分类	17 个幂等工具 / 17 个变更工具	幂等(只读): read_file, search_files, web_search 等; 变更: terminal, write_file, patch 等
并发执行	模型返回多个 tool_calls	ThreadPoolExecutor max_workers: 8	多工具调用并行执行，按原始顺序收集结果
顺序执行	单工具 / 交互式工具	todo, memory, clarify, delegate_task 等	需要 Agent 级状态的工具强制顺序执行

6. 上下文压缩策略

策略类型	触发条件	关键参数	行为描述
压缩触发	prompt_tokens >= 阈值	threshold: 50% 上下文窗口, 最低 64K tokens	达到上下文窗口 50% 时触发压缩(Codex gpt-5.5 自动提升到 85%)
防抖动	连续压缩节省 < 10%	_ineffective_compression_count >= 2	连续 2 次压缩效果差则暂停压缩，直至某次压缩节省超过 10%
头部保护	压缩时	protect_first_n: 3 条消息 + 系统提示词	系统提示词 + 前 3 条消息永不摘要
尾部保护	压缩时	protect_last_n: 20 条, 最低地板: 8 条, Token 预算: 20%	最近消息受保护，确保最后一轮对话和最后可见助手消息在保护范围内
摘要生成	压缩 Phase 3	summary_target_ratio: 20%, 上限 12K tokens, 辅助模型调用	使用辅助 LLM 生成结构化摘要，失败时用静态摘要兜底(8K 字符上限)
迭代摘要	再次压缩时	_previous_summary 保留	已有摘要时进行增量更新，保留历史信息+添加新完成动作
压缩预清理	压缩 Phase 1(无LLM)	结果去重 + 截断大参数 + 移除图片	去重相同工具结果，大参数 JSON 截断(>200字符)，多模态结果移除图片
摘要失败回退	辅助模型不可用	冷却: 600s	无辅助模型时冷却 10 分钟；404/503/超时回退到主模型生成摘要

7. 系统提示词三级架构

层级	包含内容	变更频率	设计目的
Stable	SOUL.md 身份 + 工具指导 + 技能索引 + 环境探测 + 平台提示 + 模型适配指导	会话内几乎不变	最大化上游 Prompt Prefix Cache KV 命中率
Context	调用方 system_message + 上下文文件(AGENTS.md/.cursorrules/SOUL.md)	跨会话变化，会话内稳定	项目级上下文注入，单文件上限 20K 字符(头70%+尾20%)
Volatile	MEMORY.md + USER.md + 外部记忆 Provider 提示 + 时间戳 + Session/Model/Provider	每回合/会话变化	动态内容，时间戳仅精确到日期(非分钟)以保证缓存稳定性

8. 凭证池与容错策略

策略类型	触发条件	关键参数	行为描述
选择策略	每次 API 调用选择凭证	fill_first(默认) / round_robin / random / least_used	fill_first 优先最高优先级可用项; round_robin 轮转; random 随机; least_used 选最少使用
401 处理	认证失败	瞬态冷却: 5分钟, 致命(token_invalidated等): 永久移除	区分瞬态 401(5 分钟冷却)和致命 401(永久 DEAD 状态，24h 后清理审计记录)
429 处理	速率限制	冷却: 1小时, 支持 reset_at 覆盖	标记 EXHAUSTED 状态，冷却后自动恢复；Provider 提供的 reset_at 时间戳优先于默认值
池恢复判断	_pool_may_recover_from_rate_limit	需 entries > 1 且有可用项	单凭证池/全部冷却/Google CLI 账号级配额 → 返回 False → 直接 fallback 模型
Fallback 模型链	主模型持续失败	有序 {provider, model, base_url?, api_key?} 列表	逐个尝试 fallback 条目，同 provider/model 去重，60s 主模型冷却后尝试恢复
内层重试	单次 API 调用失败	max_retries: 3, 退避: 5~120s 抖动指数	每次外层迭代内 3 次重试机会，指数退避 + 抖动
Transport 适配	根据 api_mode 选择	chat_completions(默认) / codex_responses / anthropic_messages / bedrock_converse	策略模式：提供者 API 差异封装为 4 种 Transport 实现自动适配

9. Gateway 会话策略

策略类型	触发条件	关键参数	行为描述
Agent 缓存	每条消息到来时复用	LRU: 128, 空闲 TTL: 3600s (1小时)	避免每次消息重建 OpenAI client 和重载工具，空闲超时自动回收
忙时输入模式	Agent 运行中收到新消息	interrupt(默认) / queue / steer	interrupt: 中断当前，替换消息; queue: 排队等待(上限32); steer: 注入引导文本
自动重置	会话过期	idle: 1440分钟, daily: 凌晨4点	空闲超 24h 或过凌晨 4 点自动重置；有活跃后台进程的会话永不重置
流式投递	Agent 流式输出	edit(默认) / draft / auto / off	渐进式编辑消息展示实时进度，洪水控制自适应退避(3次失败禁用)
消息分块	响应超平台长度限制	安全限制: max(500, MAX_LEN - cursor - 100)	按换行符边界智能分割，添加 (1/2) 分块指示
崩溃恢复	Gateway 重启	120s 内活跃会话标记 resume_pending	崩溃后 120s 内有活动的会话保留 SessionID 和 Transcript，用户自动恢复

10. 工具集体系

工具集名称	包含工具	用途说明
web	web_search, web_extract	网页搜索与内容提取
terminal	terminal, process	终端命令执行与进程管理
file	read_file, write_file, patch, search_files	文件读写与搜索
browser	13 个浏览器工具 + web_search	浏览器自动化，含 web_search 用于查找 URL
skills	skills_list, skill_view, skill_manage	技能管理三件套
memory	memory	跨会话记忆 CRUD
delegation	delegate_task	子智能体委派
cronjob	cronjob	定时任务管理
messaging	send_message	跨平台消息发送
coding (姿态)	34 个工具(文件+终端+web+技能+浏览器+todo+memory+delegate等)	编码姿态自动选择的全栈工具集
safe	web + vision + image_gen	无 terminal，安全沙箱工具集
hermes-webhook	仅 4 个: web_search, web_extract, vision_analyze, clarify	不可信内容场景，刻意限制防止注入攻击

本作品采用知识共享署名 4.0 国际许可协议进行许可

文章评论