Halaman utama Jelajahi Bantuan
Daftar Masuk
AI-Special-Project-Team
/
agent-management
3
1
Fork 0
Berkas Masalah 0 Permintaan Tarik 0 Wiki
Pohon: d725e474ef
Ranting Tag
agent-managemen...
/
docs
/
reference
/
hermes-agent-upgrade-reference.md

hermes-agent-upgrade-reference.md 14 KB
Riwayat Mentahan

Hermes-Agent 上游升级参考

项目位置：backend/hermes-agent/（第三方仓库 NousResearch/hermes-agent 的本地克隆，已通过父项目 .gitignore 排除） 文档目的：记录一次 hermes-agent 上游升级（git pull）带来的总量数据、关键变更、与本项目的兼容性影响，便于后续评估升级风险、规划适配工作。 评估时点：2026-08-03 评估范围：基线 021ed69141（2026-06-11）→ HEAD f4604f89（2026-08-02）

0. 一句话定位

Hermes-Agent 是 NousResearch/hermes-agent 仓库提供的智能体运行时，本项目（agent-management）通过 backend/hermes-bridge/ 内的 Python Bridge 进程托管它，再由 Java 侧 HermesBridgeClient 通过 SSE 通信完成工作流编排。Bridge 与 hermes-agent 的耦合点主要包括：agent.clarify_callback 钩子、tools.clarify_gateway 模块、tools.file_tools 中的路径解析函数（由 sandbox_patch.py 做 monkey-patch 实现沙箱隔离）。

本次升级的核心影响：上游已原生支持 clarify 永久等待（timeout=None/<=0），本项目对 tools/clarify_gateway.py 的私有 patch 已被覆盖、可废弃。

1. 总量数据

维度 数值
基线 commit 021ed6914162416522462b009de0bec1513c73a1
基线时间 2026-06-11 17:22:22 -0400
基线 subject docs: finish Automation Blueprints terminology rebrand (#44470)
当前 HEAD f4604f89dec8d225d67d7a68065c1b425fd3732a
HEAD 时间 2026-08-02 22:14:27 -0500
HEAD subject Merge pull request #77275 from NousResearch/bb/tab-reload
时间跨度 约 52 天
提交总数 8 936
文件变更 6 620 个
代码变更 +1 055 298 / −359 700 行
涉及 tools/ 的 commit 1 376
涉及 agent/ 的 commit 993

量级说明：约 52 天内涌入近 9000 个 commit、超过 100 万行新增代码，远超普通迭代节奏。这通常意味着上游在此期间合并了一个或多个长期分支（long-running feature branch），或完成了某次大规模重构。docs: finish Automation Blueprints terminology rebrand 这条基线 commit subject 也暗示此前刚刚完成术语统一（"Automation Blueprints" 大概率是新品牌名），本次升级见证了术语落地后的特性爆发期。

2. Commit 类型分布

类型 数量 占比
fix 4 443 49.7%
feat 988 11.0%
Merge PR 764 8.5%
test 610 6.8%
chore 513 5.7%
refactor 275 3.1%
docs 183 2.0%
perf 142 1.6%
fmt 118 1.3%
security 25 0.3%

观察：fix 数量是 feat 的 4.5 倍，说明此阶段上游以密集修复为主，新特性交付与修复并行；security 有 25 条，建议单独过一遍（见第 5 节）。

3. 新增特性（feat）子系统分布

子系统 feat 数 备注
desktop 279 桌面客户端，本轮最大特性波
gateway 53 HTTP/SSE 网关与 clarify 重写
cli 32 命令行
agent 28 AIAgent 核心抽象
relay 27 Hermes Relay 远程协同
skills 21 技能系统
kanban 20 Kanban 任务视图
dashboard 20 仪表盘
voice 17 语音输入
slack 17 Slack 集成
moa 15 Mixture-of-Agents
tui / ui-tui 23 终端 UI
memory 12 记忆系统
cron 12 定时任务
tts 10 文本转语音
tools 10 工具集
compression 10 上下文压缩
mcp 9 Model Context Protocol
photon 8 iMessage 集成
models 8 模型管理
config 8 配置
ci 8 持续集成
secrets 7 密钥处理
providers 7 模型 provider
plugins 7 插件
delegation 7 委托
themes 6 主题

上表按 feat 数倒序排列前 27 个子系统。desktop 一项就占全部 feat 的 28%，是本轮迭代的主战场。

4. 关键变更主题

4.1 Clarify / 用户交互（与本项目强相关）

这是本次升级中对 agent-management 影响最大的主题。

  • 507d479c8c fix(clarify): one canonical timeout across CLI, TUI/desktop, and gateway (#69774)（2026-07-22）
    • 把 CLI / TUI / gateway 三处各自实现的 clarify 超时统一为单一解析器 tools.clarify_gateway.resolve_clarify_timeout(config)。
    • 解析顺序：显式 clarify.timeout（向后兼容）→ agent.clarify_timeout（默认 3600）→ 兜底 3600。
    • 关键：<= 0 与 None 都被视为"永久不超时"，仅靠 1s 切片轮询维持 watchdog 心跳。
    • 本项目影响：backend/hermes-bridge/hermes_bridge.py:403 的 wait_for_response(clarify_id, timeout=None) 直接命中上游新能力，对 tools/clarify_gateway.py 的私有 patch 已可废弃。详见 docs/patches/hermes-agent/README.md。
  • 10b7ab5cb6 feat(clarify): extend multi-select to gateway text fallback and TUI bridge —— 多选 clarify 扩展到 gateway 文本回退路径。
  • fe95194c59 feat(photon): render multiple-choice clarify as a native iMessage poll —— 多选 clarify 在 iMessage 上渲染为原生 poll。
  • c0dd6e1f3f fix(desktop): stop a clarify card swallowing keys it doesn't bind —— 桌面端 clarify 卡片不再吞键盘事件。
  • 251b668f4d fix(desktop): let the composer answer past a clarify card —— composer 可越过 clarify 卡片继续回答。
  • aa40f16d3e fix(gateway): transcribe clarify voice replies —— 转写 clarify 语音回复。
  • aacc15b2c9 fix(clarify): raise default clarify_timeout to 3600s (#32762) —— 默认超时从 60s 提升到 3600s。
  • tools/clarify_gateway.py：单文件 +202/−21，几乎重写。

4.2 Desktop 客户端（279 feat，本轮最大特性波）

近期 merge PR 主线：

  • bb/tab-reload、bb/composer-path-copy、bb/composer-link-open、bb/composer-placeholder —— composer（输入框）多轮打磨。
  • bb/desktop-lockfile-engines、bb/npm-engine-outage —— 桌面运行时引擎隔离与 npm 引擎故障修复。
  • bb/win-update-lock-handoff、ethie/bundled-node-path-windows-layout —— Windows 升级锁交接与打包 Node 路径修复。
  • bb/sqlite-repair-locked —— SQLite 锁修复。
  • bb/kanban-model-picker —— Kanban 视图模型选择器。
  • bb/example-plugin-off-by-default —— 示例插件默认关闭。

与本项目关系：完全独立。本项目通过 Bridge 进程调用 hermes-agent，不使用其桌面应用。升级不影响 Bridge 兼容性。

4.3 网关与 Bridge（gateway 53 feat）

  • HTTP/SSE 网关整体增强。
  • tools/clarify_gateway.py 引入 resolve_clarify_timeout 统一解析器（见 4.1）。
  • gateway 端 notify / resolve_gateway_clarify 等 API 形态有调整。

建议：Bridge 侧调用的 clarify_gateway.register、clarify_gateway.resolve_gateway_clarify、clarify_gateway.clear_session、clarify_gateway.wait_for_response 这四个 API 升级后是否仍保持原签名，需在新版本上跑一次完整 clarify 流程验证（详见第 6 节）。

4.4 Agent 核心（agent 28 feat）

  • AIAgent 抽象更新。
  • 委托（delegation）结构化 stall 元数据 + 子 agent 实时状态：b792bd0529 feat(delegation): structured stall metadata + live per-child status in /agents。
  • 上下文压缩 ceiling 修复：06c7f9b26f fix(agent): clarify compress_context ceiling is pre-commit only。
  • 批量轨迹持久化与池清理：a1ff62a139 fix: context-length fallback logging, batch trajectory durability, pool cleanup。

建议：agent.clarify_callback 钩子签名（hermes_bridge.py:451 用到）若变化会直接破坏 Bridge，需重点验证。

4.5 Relay / Skills / MCP / Plugins

  • Relay（27 feat）：Hermes Relay 远程协同完善；prompts 信任 run.py 线程时间戳（不再自我锚定重推导）。
  • Skills（21 feat）：技能系统持续打磨。
  • MCP（9 feat）：Model Context Protocol 支持。
  • Plugins（7 feat）：示例插件默认关闭。

4.6 性能（perf 142）

  • 9acc4b47f5 perf(state): external-content FTS + tool-row-free trigram index（schema v23）—— 状态索引大重构。
  • 3a69e34702 perf(update): cut redundant network + subprocess work from hermes update —— 升级流程提速。

4.7 安全（security 25）

  • secrets 处理增强：fe8c0f7eef fix(secrets): pass OP_LOAD_DESKTOP_APP_SETTINGS through to the op child env。
  • /private/var 路径收窄：7f4d155159 fix(tools): validate timeout, reject whitespace old_string, narrow /private/var block。
  • Windows 探针防死锁：b9dba7eff5 fix(env-probe): stuck Windows probe can no longer deadlock system-prompt builds (#67999)。
  • Bootstrap 下载超时与 BOM 升级：73b3a8afe3 fix(bootstrap): download timeouts + BOM upgrade for pre-fix cached scripts (#67193 follow-up)。
  • git 不再阻塞内部调用：58708c7066 fix(git): never block internal git calls on credential prompts。

4.8 平台与 Provider

  • photon（8 feat）：iMessage 集成，多选 clarify 渲染为原生 poll。
  • slack（17 feat）、voice（17 feat）、tts（10 feat）。
  • providers / models：xAI active_provider 契约锁定、Groq STT 语言提示等。

5. 兼容性影响评估

风险点 影响层级 评估结论 建议动作
wait_for_response(timeout=None) 语义 Bridge ✅ 上游 PR #69774 已原生支持 私有 patch 废弃
agent.clarify_callback 钩子签名 Bridge ⚠️ 上游 agent 模块 993 commit、28 feat，签名可能有微调 跑一次完整 clarify 流程验证
clarify_gateway.{register, resolve_gateway_clarify, clear_session, wait_for_response} API Bridge ⚠️ 单文件 +202/−21，几乎重写 同上
tools.file_tools._resolve_path_for_task / _resolve_base_dir sandbox_patch.py monkey-patch 目标 ⚠️ tools/ 涉及 1376 个 commit 跑一次文件读写流程验证
agent.coding_context._git_root sandbox_patch.py monkey-patch 目标 ⚠️ 同上 跑一次 git 操作流程验证
桌面 / Kanban / Photon / Slack 等子系统 Bridge ✅ 完全独立 无需动作

6. 升级后建议的回归测试清单

升级 hermes-agent 后，建议按以下清单手动回归（参考 AGENTS.md：复杂网页操作不使用 Playwright，交由人工测试）：

  1. Bridge 启动：拉起 Bridge 进程，确认无 monkey-patch 失败日志。
  2. 基础对话：跑一次不涉及工具调用的智能体对话，验证 AIAgent.run 主路径无回归。
  3. 文件读写：在工作流中触发一次文件读写节点，验证 sandbox_patch.py 的 _resolve_path_for_task / _resolve_base_dir patch 仍生效（路径仍被限制在 workingDir）。
  4. git 操作：触发一次需要 _git_root 的操作，验证 patch 仍指向正确的 workingDir。
  5. Clarify 全流程（关键）：在工作流中触发"智能操作"节点的 clarify（用户提问 → 前端弹窗 → 用户回答 → 继续执行），确认：
    • clarify_gateway.register / wait_for_response(timeout=None) / resolve_gateway_clarify 全链路无异常。
    • Bridge 进程的 agent 线程在用户回答前持续阻塞（无意外超时返回 None）。
    • Java 侧 SSE 连接保持（无提前断开）。
    • 前端断线重连后能恢复 clarify 弹窗状态。
  6. 多 clarify 并发：同一 run 中先后触发两次 clarify，确认 _clarify_ids 集合与 clear_session 清理正常。
  7. 24h 兜底（可选）：构造 clarify 长时间不回答场景（如离线 1 小时），确认 Java 侧 SseEmitter(86_400_000L) 与 setReadTimeout(86_400_000) 未提前超时。

7. 上游基线信息（升级后）

本节内容用于 docs/patches/hermes-agent/README.md 的"上游基线"小节同步更新。

项 值
远程仓库 https://github.com/NousResearch/hermes-agent
子项目本地路径 backend/hermes-agent/
父项目 .gitignore 排除规则 hermes-agent/
当前基线 commit f4604f89dec8d225d67d7a68065c1b425fd3732a
基线 commit subject Merge pull request #77275 from NousResearch/bb/tab-reload
基线时间 2026-08-02 22:14:27 -0500
当前 main 分支跟踪状态 正常跟踪 origin/main（非 detached HEAD）

8. 升级操作回放

本次升级的实际操作记录：

# 在父项目根目录
cd backend/hermes-agent

# 当前工作区有私有 patch（已 apply），先还原
python ../docs/patches/hermes-agent/apply-patches.py --revert

# 拉取上游
git pull --ff-only origin main

# 验证 patch 是否仍需要（--check 显示找不到原始锚点，说明上游已重写该段）
python ../docs/patches/hermes-agent/apply-patches.py --check

# 决策：上游 PR #69774 已原生覆盖能力 → 不再 apply，标记 patch 为废弃

9. 参考链接