SuperAPI AI 工具集

swarm-workspace

编程与开发

查看项目

更新于 11-06 16:22

技能介绍

用途

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 同步,需依赖脚本复制。