git worktrees

Hermes 代理经常在大型且长期的仓库中使用。当您希望：

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

Git 工作树 (worktrees) 是最安全的方法，它能为每个代理提供独立的检出环境，而无需克隆整个仓库。

本页面展示了如何将工作树与 Hermes 结合使用，从而让每个会话都拥有一个干净、隔离的工作目录。

为什么要将工作树与 Hermes 结合使用？

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

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

如果您在 同一个检出路径 下运行多个代理，它们的修改可能会相互干扰：

• 一个代理可能会删除或重写另一个代理正在使用的文件。
• 很难分辨哪些更改属于哪次实验。

通过工作树，每个代理都能获得：

• 独立的分支和工作目录
• 独立的检查点管理器 (Checkpoint Manager) 历史记录，用于执行 /rollback（回滚）

*另请参阅： 检查点与 /rollback。

快速入门：创建工作树

在包含 .git/ 的主仓库中，为功能分支创建一个新的工作树：

# 进入主仓库根目录
cd /path/to/your/repo

# 在 ../repo-feature 路径下创建一个新分支和工作树
git worktree add ../repo-feature feature/hermes-experiment

这将创建：

1. 一个新目录：../repo-feature
2. 一个在该目录下检出的新分支：feature/hermes-experiment

现在您可以进入(cd)新的工作树并运行 Hermes：

cd ../repo-feature

# 在工作树中启动 Hermes
hermes

Hermes 将：

• 将 ../repo-feature 视为项目根目录。
• 使用该目录进行上下文文件读取、代码编辑和工具调用。
• 使用 独立的检查点历史记录，回滚操作(/rollback)仅限于此工作树范围内。

并行运行多个代理

您可以创建多个工作树，每个工作树对应一个分支：

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 实验使用一个工作树

  • 为每一个重大的变更创建专属的分支/工作树。
  • 这能确保代码差异（diffs）集中，并使 PR 保持短小且易于评审。

• 以实验名称命名分支

  • 例如：feature/hermes-checkpoints-docs、feature/hermes-refactor-tests。

• 频繁提交 (Commit)

  • 对于高层级的阶段性里程碑，使用 git commit。
  • 对于其间由工具驱动的编辑，使用 检查点 (checkpoints) 和 /rollback 作为安全网。

• 使用工作树时避免从裸仓库根目录运行 Hermes

  • 优先选择在工作树目录中运行，以便每个代理都有明确的作用域。

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

Hermes 内置了一个 -w 标志，可以 自动创建一个随用随弃的 Git 工作树 及其专属分支。您不需要手动设置工作树 —— 只需进入仓库并运行：

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

Hermes 将会：

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

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

hermes -w -q "修复第 #123 号问题"

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

总结归纳

• 使用 git worktrees 为每个 Hermes 会话提供干净的独立检出环境。
• 使用 分支 (branches) 来记录实验的高层级历史。
• 使用 检查点 (checkpoints) + /rollback 来恢复每个工作树内的错误操作。

这种组合为您提供了：

• 强有力的保障，确保不同的代理和实验不会相互干扰。
• 快速的迭代周期，能够轻松从错误的编辑中恢复。
• 干净且可评审的拉取请求 (Pull Requests)。