用途
swarm-workspace 是 swarm 编码工作流的基础设施技能,负责管理每个子智能体的 git worktree 生命周期。它建立在两层文件系统之上,使 swarm 中的多个子智能体能够并行编辑和构建代码而不发生冲突。
两层文件系统
该技能定义了两个路径层级:
/mnt/agents/output/app:共享协调仓库。这是一个普通 git 仓库(没有远程 remote),充当分支创建与合并的枢纽。规则是:不要在此处构建或编辑代码。$HOME/app-<branch>:本地 worktree。这是子智能体进行编辑和构建的快速文件系统位置。每个子智能体使用唯一的路径。
由该布局推导出的关键事实
- 没有远程,没有 push。所有 worktree 共享同一个共享仓库的
.git对象存储,因此任意分支上的提交对主智能体立即可见——主智能体只需在共享仓库内执行git merge <branch>。不存在git push。 node_modules、dist和.env被 gitignore。它们不会通过 git 同步,因此git worktree add不会把它们带入新的 worktree。每个 worktree 获得自己的副本——这正是 setup-local.sh 会复制node_modules(以及可选的.env)的原因。- 永远不要运行
git worktree prune。每个智能体的 worktree 元数据都存放在共享仓库的.git/worktrees/目录中;prune 会破坏同伴的 worktree。 - 每个并行子智能体必须传入唯一的
$HOME/app-<branch>路径——路径冲突会损坏共享的 worktree 元数据。
setup-local.sh —— 单个子智能体的 worktree 设置
调用方式:
[REPO_PATH=<shared-repo>] [NODE_MODULES_SRC=<prebuilt-node_modules>] [ENV_SRC=<.env-file>] \
bash /app/.agents/skills/swarm-workspace/scripts/setup-local.sh <branch> <local-path>
环境变量说明:
REPO_PATH:共享协调仓库,默认/mnt/agents/output/app。NODE_MODULES_SRC:一个预构建的 node_modules 目录,会被复制进 worktree 以实现快速启动;未设置时依赖npm install。ENV_SRC:一个会被复制进 worktree 的.env文件;未设置时使用$REPO_PATH/.env(graft 暂存的 .env),因此后端/数据库/构建类 worktree 会自动继承DATABASE_URL;当该文件不存在时(纯前端场景)此步骤为空操作。
建议将 NODE_MODULES_SRC 指向你所使用技术栈的预构建 node_modules(例如 …/scripts/template/node_modules),这样 worktree 启动时就带有正确的依赖覆盖,随后 npm install 再协调其余部分。
行为:
- 全新创建:执行
git worktree add --force,复制NODE_MODULES_SRC(若设置了ENV_SRC则同时复制.env),然后执行npm install。 - 同一分支重入:复用该 worktree,跳过
npm install,若给出ENV_SRC仍会刷新.env。 - 不同分支重入 / 目录陈旧:干净地重新创建。
--force可容忍已死沙箱遗留的陈旧 worktree 条目。
前置条件
setup-local.sh 假定共享协调仓库已存在于 REPO_PATH。创建该仓库(铺设初始项目并在那里执行 git clone)是负责铺设首个模板的工作流的职责,而非本技能的职责。
适用场景与限制
适用于需要多个子智能体并行编辑、构建同一项目的 swarm 编码工作流,尤其是后端、数据库、构建类任务需要共享 .env 与依赖的场景。限制包括:必须保证每个子智能体使用唯一 worktree 路径;禁止运行 git worktree prune;共享仓库需由外部工作流预先创建;node_modules、dist、.env 不通过 git 同步,需依赖脚本复制。