Git Worktree

为什么使用 worktree？

没有 worktree，在同一仓库上运行多个智能体意味着它们共享工作目录。一个智能体的修改会干扰另一个。你无法安全地并行运行任务。

有了 worktree，每个智能体都有自己的目录和分支，可以同时工作而不产生冲突。当智能体完成后，你审查差异、合并分支、归档 worktree。

目录结构

Seawork 在 $SEAWORK_HOME/worktrees/下创建 worktree，按源代码检出路径的短哈希值组织：

~/.seawork/worktrees/
├── 1vnnm9k3/
│   ├── tidy-fox/            # random slug
│   └── bold-owl/            # random slug
└── 4k8q2d1p/
    └── swift-hare/          # random slug

哈希值避免了共享同一目录或远程名称的仓库之间的冲突。Worktree 目录名是随机短语——分支名是独立的，在你第一次在 worktree 中启动智能体时设置。

分支

创建 worktree 时，Seawork 生成一个随机目录名。分支名在你第一次启动智能体时设置——Seawork 自动生成。

这意味着 worktree 目录和分支是独立的。你可以稍后重命名分支而不影响 worktree 路径。

每个 worktree 中的多个智能体

你可以在同一个 worktree 中启动多个智能体。它们共享工作目录和分支，适用于你希望智能体协作完成同一功能或一个智能体移交给另一个的场景。

注意冲突——同时处理同一文件的智能体可能会相互干扰。当智能体有不同职责或按顺序运行时效果最佳。

使用 seawork.json 配置生命周期钩子

Seawork 创建 worktree 时是全新检出。依赖未安装，配置文件未复制。你可以通过在仓库根目录创建 seawork.json 文件来自动化设置：

{
  "worktree": {
    "setup": [
      "npm ci",
      "cp \"$SEAWORK_SOURCE_CHECKOUT_PATH/.env\" \"$SEAWORK_WORKTREE_PATH/.env\""
    ]
  }
}

setup数组包含 worktree 创建后运行的 shell 命令。用它来安装依赖、复制本地配置文件或运行其他初始化操作。

你也可以添加 teardown 数组，用于在 Seawork 归档时删除 worktree 目录之前运行的清理命令：

{
  "worktree": {
    "teardown": [
      "pkill -f \"vite --port $SEAWORK_WORKTREE_PORT\" || true",
      "rm -rf \"$SEAWORK_WORKTREE_PATH/.cache\""
    ]
  }
}

环境变量

设置和清理命令可以访问这些环境变量：

• $SEAWORK_SOURCE_CHECKOUT_PATH ——你的源代码检出路径（原始仓库根目录）
• $SEAWORK_ROOT_PATH ——$SEAWORK_SOURCE_CHECKOUT_PATH
• $SEAWORK_WORKTREE_PATH ——新的 worktree 目录
• $SEAWORK_BRANCH_NAME ——已创建的分支名
• $SEAWORK_WORKTREE_PORT ——存在运行时元数据时的 worktree 端口

使用 $SEAWORK_SOURCE_CHECKOUT_PATH 从源代码检出复制不应纳入 git 的文件（如 .env）到 worktree。

$SEAWORK_WORKTREE_PORT 在 worktree 以端口引导时可用。这使其对于在设置中启动服务和在清理中停止服务都很有用。

清理

清理在归档期间、Seawork 删除 worktree 目录之前运行。用于需要访问 worktree 路径或其分配端口的清理工作。

常见用途包括停止 $SEAWORK_WORKTREE_PORT上的开发服务器、删除生成的文件或注销与该 worktree 绑定的服务。

{
  "worktree": {
    "setup": [
      "npm ci",
      "nohup npm run dev -- --port $SEAWORK_WORKTREE_PORT > \"$SEAWORK_WORKTREE_PATH/dev.log\" 2>&1 &"
    ],
    "teardown": [
      "pkill -f \"npm run dev -- --port $SEAWORK_WORKTREE_PORT\" || true",
      "rm -f \"$SEAWORK_WORKTREE_PATH/dev.log\""
    ]
  }
}

常用模式

Node.js / npm

{
  "worktree": {
    "setup": ["npm ci"]
  }
}

Python / Poetry

{
  "worktree": {
    "setup": ["poetry install"]
  }
}

复制环境文件

{
  "worktree": {
    "setup": [
      "npm ci",
      "cp \"$SEAWORK_SOURCE_CHECKOUT_PATH/.env\" \"$SEAWORK_WORKTREE_PATH/.env\"",
      "cp \"$SEAWORK_SOURCE_CHECKOUT_PATH/.env.local\" \"$SEAWORK_WORKTREE_PATH/.env.local\""
    ]
  }
}

运行数据库迁移

{
  "worktree": {
    "setup": [
      "npm ci",
      "cp \"$SEAWORK_SOURCE_CHECKOUT_PATH/.env\" \"$SEAWORK_WORKTREE_PATH/.env\"",
      "npm run db:migrate"
    ]
  }
}

工作流

典型工作流如下：

1. 创建 worktree——Seawork 创建目录并运行设置
2. 启动智能体——Seawork 创建或分配分支
3. 智能体在隔离环境中工作——修改保留在其 worktree 中
4. 审查差异——与基础分支比较
5. 合并或丢弃——如果批准，合并分支；否则归档
6. 归档 worktree——清理目录和可选的分支

你可以同时在不同 worktree 中运行多个智能体。每个 worktree 有其自己的分支和工作目录。

CLI 参考

在新 worktree 中创建智能体：

seawork run --worktree feature-auth --base main "implement auth"

列出所有 worktree：

seawork worktree ls

归档 worktree（停止智能体，删除目录）：

seawork worktree archive feature-auth

元数据

Seawork 在每个 worktree 的 git 目录中存储元数据以跟踪基础分支。这用于差异操作和确定要合并到哪个分支。

你无需手动管理——Seawork 在创建和归档 worktree 时会处理这些。