Git 工作树

Hermes Agent 经常用于大型、长期存在的仓库。当你希望：

• 在同一项目上并行运行多个 agent，或
• 将实验性重构与主分支隔离，

Git 工作树（worktrees） 是最安全的方式，让每个 agent 拥有自己的检出副本，而无需复制整个仓库。

本页介绍如何将工作树与 Hermes 结合使用，使每个会话拥有干净、隔离的工作目录。

为何在 Hermes 中使用工作树？

Hermes 将当前工作目录视为项目根目录：

• CLI：运行 hermes 或 hermes chat 的目录
• 消息网关：由 MESSAGING_CWD 设置的目录

如果在同一个检出中运行多个 agent，它们的变更可能相互干扰：

• 一个 agent 可能删除或重写另一个 agent 正在使用的文件。
• 变得难以理解哪些变更属于哪个实验。

使用工作树后，每个 agent 获得：

• 自己的分支和工作目录
• 自己的检查点管理器历史，用于 /rollback

另请参阅：rollback。

快速开始：创建工作树

从你的主仓库（包含 .git/）中，为特性分支创建一个新的工作树：

# 从主仓库根目录
cd /path/to/your/repo
 
# 创建一个新分支和工作树到 ../repo-feature
git worktree add ../repo-feature feature/hermes-experiment

这会创建：

• 一个新目录：../repo-feature
• 一个新分支：feature/hermes-experiment 已检出到该目录

现在你可以 cd 进入新的工作树并在其中运行 Hermes：

cd ../repo-feature
 
# 在工作树中启动 Hermes
hermes

Hermes 会：

• 将 ../repo-feature 视为项目根目录。
• 使用该目录存放上下文文件、代码编辑和工具。
• 使用独立的检查点历史，作用域限定为此工作树。

并行运行多个 Agent

你可以创建多个工作树，每个都有自己的分支：

cd /path/to/your/repo
 
git worktree add ../repo-experiment-a feature/hermes-a
git worktree add ../repo-experiment-b feature/hermes-b

在单独的终端中：

# 终端 1
cd ../repo-experiment-a
hermes
 
# 终端 2
cd ../repo-experiment-b
hermes

每个 Hermes 进程：

• 在自己的分支上工作（feature/hermes-a vs feature/hermes-b）。
• 在不同的影子仓库哈希下写入检查点（由工作树路径派生）。
• 可以独立使用 /rollback，不影响另一个。

这在以下场景中尤为有用：

• 运行批量重构。
• 对同一任务尝试不同方法。
• 将 CLI + 网关会话配对，针对同一上游仓库。

安全清理工作树

当你完成一个实验后：

1. 决定是保留还是丢弃工作成果。
2. 如果要保留：
   • 像往常一样将分支合并到主分支。
3. 移除工作树：

cd /path/to/your/repo
 
# 移除工作树目录及其引用
git worktree remove ../repo-feature

注意：

• 如果工作树有未提交的变更，git worktree remove 会拒绝移除，除非强制。
• 移除工作树不会自动删除分支；你可以使用正常的 git branch 命令删除或保留分支。
• ~/.hermes/checkpoints/ 下的 Hermes 检查点数据在移除工作树时不会自动清理，但通常非常小。

最佳实践

• 每个 Hermes 实验一个工作树
  • 为每次重大变更创建一个专用的分支/工作树。
  • 这样保持差异集中、PR 小而可审查。
• 以实验名命名分支
  • 例如 feature/hermes-checkpoints-docs、feature/hermes-refactor-tests。
• 频繁提交
  • 使用 Git 提交作为高级里程碑。
  • 使用rollback 作为工具驱动编辑之间的安全网。
• 使用工作树时，避免从裸仓库根目录运行 Hermes
  • 优先使用工作树目录，使每个 agent 有明确的作用域。

使用 hermes -w（自动工作树模式）

Hermes 有一个内置的 -w 标志，可以自动创建一个可丢弃的 Git 工作树，带有自己的分支。你无需手动设置工作树——只需 cd 进入你的仓库并运行：

cd /path/to/your/repo
hermes -w

Hermes 会：

• 在仓库内的 .worktrees/ 下创建一个临时工作树。
• 检出一个隔离的分支（例如 hermes/hermes-<hash>）。
• 在该工作树内运行完整的 CLI 会话。

这是获得工作树隔离的最简单方式。你也可以将其与单次查询结合使用：

hermes -w -q "Fix issue #123"

对于并行 agent，打开多个终端并在每个终端中运行 hermes -w——每次调用都会自动获得自己的工作树和分支。

综合运用

• 使用 Git 工作树让每个 Hermes 会话拥有自己的干净检出。
• 使用分支捕获实验的高级历史。
• 使用检查点 + /rollback 在每个工作树内从错误中恢复。

这种组合为你提供：

• 强有力的保证，不同 agent 和实验不会相互干扰。
• 快速的迭代周期，从不良编辑中轻松恢复。
• 干净、可审查的拉取请求。