SeaWorkSeaWork
简体中文
下载

Git Worktree

Git worktree 让你可以在同一仓库中拥有多个工作目录。SeaWork 使用它们在隔离分支中运行智能体，无需切换上下文。

为什么使用 worktree？

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

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

目录结构

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

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

哈希值避免了共享同一目录或远程名称的仓库之间的冲突。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 命令。用它来安装依赖、复制本地配置文件或运行其他初始化操作。

重要：设置命令来自所选基础分支上的 seawork.json。如果你选择 main，SeaWork 读取 main 上已提交的文件。其他分支中的本地或未提交更改不会用于该 worktree。

环境变量

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

  • $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 目录之前运行。用于需要访问 worktree 路径或其分配端口的清理工作。

工作流

典型工作流如下：

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

CLI 参考

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