# 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`](https://github.com/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. 升级操作回放

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

```bash
# 在父项目根目录
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. 参考链接

- 上游仓库：https://github.com/NousResearch/hermes-agent
- 关键 PR：[#69774](https://github.com/NousResearch/hermes-agent/pull/69774) fix(clarify): one canonical timeout across CLI, TUI/desktop, and gateway
- 私有 patch 记录：[`docs/patches/hermes-agent/README.md`](../patches/hermes-agent/README.md)
- Bridge 适配层关键文件：
  - [`backend/hermes-bridge/hermes_bridge.py`](../../backend/hermes-bridge/hermes_bridge.py)
  - [`backend/hermes-bridge/sandbox_patch.py`](../../backend/hermes-bridge/sandbox_patch.py)
  - [`backend/src/main/java/com/agent/management/engine/hermes/HermesBridgeClient.java`](../../backend/src/main/java/com/agent/management/engine/hermes/HermesBridgeClient.java)