Skip to main content

Git 工作树（Worktrees）

🛠️ 1. 使用 git worktree 创建多个独立工作区​

git worktree 允许你在同一仓库中创建多个工作目录，每个目录对应一个独立的检出状态。

# 在主仓库根目录下执行
git worktree add ../hermes-agent-01 main
git worktree add ../hermes-agent-02 main
git worktree add ../hermes-agent-03 main

✅ 每个 ../hermes-agent-01、../hermes-agent-02 等都是独立的工作目录，拥有自己的文件系统状态，但共享同一个 .git 目录。

🔒 2. 隔离环境变量与配置​

为每个代理设置独立的环境变量，避免冲突。

示例：.env 文件隔离​

# hermes-agent-01/.env
HERMES_AGENT_ID=agent_01
OPENAI_API_KEY=sk-your-key-here-01
AGENT_PORT=8001
LOG_DIR=./logs/agent_01
# hermes-agent-02/.env
HERMES_AGENT_ID=agent_02
OPENAI_API_KEY=sk-your-key-here-02
AGENT_PORT=8002
LOG_DIR=./logs/agent_02

💡 建议使用 .env.local 或通过 dotenv 加载配置，确保不提交敏感信息。

🧩 3. 启动多个独立的 Hermes 代理实例​

在每个工作区中启动代理，使用不同的端口和日志路径。

# 在 hermes-agent-01 目录中
cd ../hermes-agent-01
npm run start --port=8001 --log-dir=./logs/agent_01

# 在 hermes-agent-02 目录中
cd ../hermes-agent-02
npm run start --port=8002 --log-dir=./logs/agent_02

⚠️ 确保每个代理使用唯一的 PORT、PID 文件路径、数据库连接名 等资源。

📂 4. 管理工作区（可选）​

查看当前所有 worktree：

git worktree list

移除不再需要的工作区：

git worktree remove ../hermes-agent-01

📌 注意：删除 worktree 不会删除分支或提交，仅移除工作目录。

🔄 5. 同步更新（推荐策略）​

当主分支有更新时，可同步到所有 worktree：

# 在主仓库中拉取最新代码
git pull origin main

# 同步所有 worktree 到最新状态
git worktree prune  # 清理已删除的 worktree
git worktree foreach 'git pull origin main'

✅ 这样可以保持所有代理实例基于相同代码基线运行。

🛡️ 安全建议​

项目建议
API 密钥使用环境变量 + .gitignore 忽略 .env 文件
日志存储每个 agent 使用独立日志目录，避免覆盖
权限控制限制对 worktree 目录的写入权限，防止误操作
监控为每个代理添加健康检查脚本或监控指标

✅ 总结​

通过 git worktree + 隔离配置，你可以在单个仓库中安全运行多个 Hermes 代理，适用于：

  • 多代理测试与实验
  • A/B 测试不同模型行为
  • 并行开发与部署
  • 本地多实例集成验证

🎯 提示：结合 Hermes Agent CLI 或 Honcho 可进一步自动化管理多个实例。

如需自动化脚本管理多个 worktree 实例，请参考 SOUL.md 中的多代理部署模板。"​

Git Worktrees

Hermes Agent 常用于大型、长期维护的代码仓库。当你希望：

  • 在同一个项目中并行运行多个代理，或
  • 保持实验性重构与主分支隔离时，

Git worktrees（工作树） 是最安全的方式，能让每个代理拥有独立的代码检出，而无需复制整个仓库。

本页将展示如何将 worktrees 与 Hermes 结合使用，确保每个会话都有一个干净、隔离的工作目录。

为什么在 Hermes 中使用 Worktrees？​

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

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

如果在 同一份检出 中运行多个代理，它们的更改可能会相互干扰：

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

使用 worktrees 后，每个代理将获得：

  • 自己的分支和工作目录
  • 独立的 Checkpoint Manager 历史记录，用于 /rollback

参见：检查点与 /rollback

快速入门：创建 Worktree​

从包含 .git/ 的主仓库开始，为某个功能分支创建一个新的 worktree：

# From the main repo root
cd /path/to/your/repo

# Create a new branch and worktree in ../repo-feature
git worktree add ../repo-feature feature/hermes-experiment

这将创建：

  • 一个新目录：../repo-feature
  • 一个新分支：feature/hermes-experiment，并在该目录中检出

现在你可以进入这个新 worktree 并在此运行 Hermes：

cd ../repo-feature

# Start Hermes in the worktree
hermes

Hermes 将：

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

并行运行多个代理​

你可以创建多个 worktree，每个都拥有自己的分支：

cd /path/to/your/repo

git worktree add ../repo-experiment-a feature/hermes-a
git worktree add ../repo-experiment-b feature/hermes-b

在不同的终端中分别运行：

# Terminal 1
cd ../repo-experiment-a
hermes

# Terminal 2
cd ../repo-experiment-b
hermes

每个 Hermes 进程：

  • 在各自的分支上工作（feature/hermes-a vs feature/hermes-b）。
  • 使用不同影子仓库哈希生成的检查点数据（基于 worktree 路径计算得出）。
  • 可以独立使用 /rollback，互不干扰。

这种方式特别适用于：

  • 批量重构任务。
  • 对同一任务尝试多种不同方案。
  • 在同一上游仓库上同时运行 CLI 和网关会话进行协作。

安全清理 Worktree​

完成实验后：

  1. 决定是否保留该工作成果。
  2. 若想保留：
    • 正常将分支合并到主分支。
  3. 删除 worktree：
cd /path/to/your/repo

# Remove the worktree directory and its reference
git worktree remove ../repo-feature

注意事项：

  • git worktree remove 会拒绝删除带有未提交更改的 worktree，除非强制执行。
  • 删除 worktree 不会自动删除分支；你可以用常规的 git branch 命令决定保留或删除分支。
  • Hermes 在 ~/.hermes/checkpoints/ 下的检查点数据不会随 worktree 删除而自动清理，但通常体积很小。

最佳实践​

  • 每个 Hermes 实验对应一个 worktree
    • 为每次重要变更创建专用分支和 worktree。
    • 保持差异集中，PR 简洁易审。
  • 分支命名反映实验内容
    • 如 feature/ai-refactor, experiment/speed-optimize。
  • 频繁提交
    • 使用 git 提交标记高阶里程碑。
    • 使用 检查点与 /rollback 作为工具驱动修改之间的安全缓冲。
  • 避免在裸仓库根目录运行 Hermes（使用 worktrees 时）
    • 优先使用 worktree 目录，确保每个代理有明确的作用范围。

使用 hermes -w（自动 Worktree 模式）​

Hermes 内置了 -w 标志，可自动创建临时的 Git worktree，并分配独立分支。无需手动配置——只需进入你的仓库并运行：

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

Hermes 将：

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

这是获取 worktree 隔离最简单的方式。你也可以结合单个查询使用：

hermes -w -q "Fix issue #123"

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

总结​

  • 使用 git worktrees 为每个 Hermes 会话提供独立的干净检出。
  • 使用 分支 记录实验的高层次历史。
  • 使用 检查点 + /rollback 在每个 worktree 内恢复错误操作。

这种组合带来以下优势：

  • 强保证不同代理和实验之间互不干扰。
  • 快速迭代周期，坏操作也能轻松恢复。
  • 清晰、可审查的 Pull Request。

通过合理使用 worktrees，让 Hermes 在复杂项目中更安全、高效地发挥作用。