1flowbase · Git 工作空间与多 Agent 并发开发手册

多 Agent 并发开发最容易出问题的地方，不是模型不够聪明，而是多个执行者共享了同一个工作目录、同一组端口、同一个开发数据库和同一份未提交状态。

一旦这样做，问题会很快变得混乱：

Agent A 正在改前端页面。
Agent B 同时改同一个 DTO。
Agent C 重启了 dev server。
主工作区还有半截未提交代码。

最后失败的可能不是某个功能，而是整个开发现场。

更稳的做法是：把并发单位从“同一个目录里的多个 Agent”改成“多个隔离的 Git 工作空间”。每个 Agent 有自己的目录、分支、端口、数据库和日志。最后只把验证过的改动合回主工作区。

这篇手册讲的是这个工作流。

核心原则

一个任务
  -> 一个 Git worktree
  -> 一个 Agent
  -> 一套本地端口
  -> 一个开发数据库
  -> 一个可独立验证的提交

不要让多个 Agent 同时在同一个工作目录里开发。共享目录适合人类临时协作，不适合自动化 Agent 并发执行。

多 Agent 并发的目标也不是让所有任务同时开跑，而是把互不冲突的任务隔离出去，让每个任务可以独立失败、独立回滚、独立验收。

Git 工作空间是什么

这里的 Git 工作空间指 git worktree 创建出来的多个 working tree。

同一个 repository 可以同时有多个目录：

~/git/1flowbase
  -> 主工作区，日常验收、合并、发版

~/git/1flowbase-latest
  -> beta / latest 开发空间

~/git/1flowbase-agent-ui
  -> 某个前端 Agent 的临时任务空间

~/git/1flowbase-agent-api
  -> 某个后端 Agent 的临时任务空间

它们共享同一个 Git 仓库对象库，但每个目录都有自己的工作区文件、分支和未提交状态。

这比复制整个项目目录更好：

不会复制一堆 .git 历史。
可以清楚看到每个工作空间对应哪个分支。
删除临时空间时可以用 Git 正常清理。
主工作区不会被半成品改动污染。

什么时候适合多 Agent 并发

适合并发的任务通常满足两个条件：

文件重叠少
验收入口清楚

适合并发：

一个 Agent 改前端页面，另一个 Agent 改独立脚本。
一个 Agent 修文档，另一个 Agent 补后端测试。
多个 Agent 分别调查不同失败日志，最后由主工作区统一修。
一个 Agent 做方案研究，另一个 Agent 做局部实现。

不适合直接并发：

多个 Agent 同时改同一个 DTO、migration 或状态机。
一个任务还没确定接口 contract，另一个任务已经开始消费它。
多个 Agent 都需要重启同一套本地服务。
多个任务都在改共享壳层、全局路由、权限模型或数据库 schema。

如果任务会碰同一条关键路径，先拆清楚边界，再并发。

每个工作空间都要隔离端口

多工作空间最常见的冲突是端口。

比如主工作区已经在跑：

frontend      3100
api-server    7800
plugin-runner 7801

另一个工作空间如果也用这些端口，就会出现：

服务启动失败。
Agent 重启了别的工作区服务。
浏览器打开的是旧工作区页面。
API proxy 打到了错误后端。

更稳的做法是：每个工作空间用自己的端口段。

示例：

main workspace
  frontend      3100
  api-server    7800
  plugin-runner 7801

latest workspace
  frontend      3200
  api-server    7900
  plugin-runner 7901

agent-ui workspace
  frontend      3300
  api-server    8000
  plugin-runner 8001

在 1flowbase 里，开发端口可以直接放到当前工作空间的 api/apps/api-server/.env：

API_SERVER_ADDR=0.0.0.0:7900
PLUGIN_RUNNER_ADDR=0.0.0.0:7901
VITE_DEV_SERVER_PORT=3200
VITE_API_PROXY_TARGET=http://127.0.0.1:7900

这样 dev-up、api-server、plugin-runner 和 Vite dev server 使用的是同一份工作空间配置。

关键点是：不要为了每个工作空间再发明一套配置文件。优先复用项目已有 .env，让本地环境差异留在不提交的配置里。

每个工作空间都要隔离数据库

端口隔离只解决“服务打到哪里”。数据库也要隔离。

如果两个工作空间共用同一个开发库，一个 Agent 跑 migration、reset、seed 或测试 schema，另一个 Agent 的运行状态就可能被破坏。

推荐命名：

1flowbase
1flowbase_latest
1flowbase_agent_ui
1flowbase_agent_api

在对应工作空间的 .env 里写：

API_DATABASE_URL=postgres://postgres:1flowbase@127.0.0.1:35432/1flowbase_latest

创建数据库：

createdb -h 127.0.0.1 -p 35432 -U postgres 1flowbase_latest

如果使用 Docker 里的 Postgres，也可以进入容器执行：

docker exec -it docker-db-1 createdb -U postgres 1flowbase_agent_ui

实际数据库名保持项目约定即可。重点不是名字，而是一个工作空间一个库。

多 Agent 分工方式

不要给 Agent 一个模糊目标，比如：

你去优化一下前端。

这会导致 Agent 自己扩大范围。更好的任务描述是：

你在 ../1flowbase-agent-ui 工作空间处理设置页布局问题。
范围只包括 web/app 的 settings 页面和相关测试。
不要改后端 DTO，不要改 migration。
验收方式是运行目标测试，并给出截图或日志。

每个 Agent 至少要拿到这几件事：

工作空间路径。
当前分支。
允许修改的目录。
明确不允许碰的目录。
启动端口。
数据库名。
验收命令。
完成后交付什么。

推荐任务卡片：

任务：修复 settings provider 表单布局
工作空间：~/git/1flowbase-agent-ui
分支：codex/settings-provider-layout
范围：web/app/src/features/settings/**
禁止：api/**、migrations/**
端口：frontend 3300, api 8000, plugin-runner 8001
数据库：1flowbase_agent_ui
验收：目标 vitest + 页面截图
交付：commit hash + 验证命令 + 未验证范围

主工作区负责最终验收

临时工作空间可以开发，但最终验收最好回到主工作区。

推荐流程：

Agent workspace
  -> 实现
  -> 定向测试
  -> commit

Main workspace
  -> fetch / merge / cherry-pick
  -> 解决冲突
  -> 跑关键验收
  -> push

这样做的好处是，主工作区永远是最终事实来源。临时空间只负责把局部任务做完整，不负责决定全局合并状态。

如果多个 Agent 都提交了结果，不要让它们互相合并。由主工作区按顺序吸收：

git fetch origin
git merge codex/settings-provider-layout
git merge codex/api-reset-root-fix

或选择性吸收：

git cherry-pick <commit>

哪个方式更好取决于团队习惯。关键是合并动作集中在一个地方发生。

冲突处理规则

多 Agent 并发一定会遇到冲突。冲突本身不是问题，冲突处理不透明才是问题。

建议规则：

谁合并，谁解释冲突。
谁改 contract，谁补消费方验证。
谁改 migration，谁负责数据库状态说明。
谁改共享 UI 壳层，谁负责关键页面 smoke。

不要让 Agent 为了“自动解决冲突”删除用户改动、回退别人的提交，或强行重写历史。

危险操作要默认禁止：

git reset --hard
git checkout -- .
git clean -fd
git push --force

这些命令不是不能用，而是不能在不确认影响范围时用。多 Agent 环境里，破坏现场比修 bug 更贵。

服务启动规则

每个工作空间只管理自己的服务：

node scripts/node/dev-up.js status
node scripts/node/dev-up.js restart --skip-docker
node scripts/node/dev-up.js stop --skip-docker

建议：

Docker 中间件通常只需要一套。
frontend / api-server / plugin-runner 按工作空间分别启动。
每个工作空间的日志写到自己的 tmp/logs/。
发现端口冲突，先看 dev-up status，不要直接杀进程。

如果一个 Agent 只改文档或纯脚本，不要让它启动完整服务。启动服务也要变成任务授权的一部分。

验收要分层

不要要求每个临时工作空间都跑全量门禁。那会浪费时间，也会让多个 Rust / Node 构建互相抢资源。

更实际的分层：

Agent 工作空间
  -> 定向测试
  -> 局部 lint / typecheck
  -> 必要页面截图或接口 smoke

主工作区
  -> 合并后关键回归
  -> 与当前变更相关的门禁

CI / beta
  -> 全量测试
  -> 重型后端门禁
  -> 安全扫描

这样每个 Agent 只证明自己的任务没有明显问题，主工作区负责证明多个任务合在一起仍然成立。

一个好的 Agent 交付说明

Agent 完成任务后，不应该只说“已完成”。它应该给出可验证信息：

完成内容：
- 调整 settings provider 表单布局。
- 保持 API DTO 字段不变。

修改文件：
- web/app/src/features/settings/...

验证：
- pnpm --filter @1flowbase/web test settings-provider
- node scripts/node/dev-up.js status

未验证：
- 未跑全量 frontend build，留给主工作区或 CI。

提交：
- abc1234 fix(settings): adjust provider form layout

多 Agent 环境里，交付说明是合并者的地图。

常见失败模式

两个工作空间用了同一个端口

表现：

打开页面不是刚改的版本。
API 请求打到另一个工作空间。
dev-up restart 停掉了别的服务。

处理：

node scripts/node/dev-up.js status

确认 .env 里的 VITE_DEV_SERVER_PORT、API_SERVER_ADDR、PLUGIN_RUNNER_ADDR 是否属于当前工作空间。

两个工作空间用了同一个数据库

表现：

migration checksum 报错。
root 密码 reset 行为互相影响。
测试数据突然消失或状态异常。

处理：

给当前工作空间单独建库。
更新 API_DATABASE_URL。
不要在不确认的情况下自动 drop 共享库。

Agent 改了不属于自己的文件

表现：

diff 里出现无关目录。
合并冲突扩大。
验收范围说不清。

处理：

git diff --stat
git diff --name-only

只保留任务范围内改动。无关改动不要顺手提交。

主工作区不干净就开始合并

表现：

分不清哪些改动来自 Agent。
冲突解决时误覆盖本地工作。

处理：

合并前先：

git status

主工作区有未提交改动时，先提交、暂存或明确保留策略，再合并 Agent 结果。

最小检查清单

开工前：

[ ] 任务能独立开发
[ ] 已创建单独 worktree
[ ] 分支名清楚
[ ] .env 端口不冲突
[ ] 数据库不共享
[ ] Agent 知道允许修改范围
[ ] Agent 知道验收命令

提交前：

[ ] git diff 只包含任务相关文件
[ ] 定向测试已跑
[ ] 服务状态可解释
[ ] 没有提交本地 .env、日志、tmp 产物
[ ] commit message 能说明任务

合并前：

[ ] 主工作区状态干净
[ ] 已读 Agent 交付说明
[ ] 冲突由合并者解释
[ ] 合并后跑关键验收
[ ] 只推送当前目标分支

这个工作流真正解决什么

多 Agent 并发不是把同一个任务切给更多模型，而是把开发现场拆成多个可控隔间。

没有工作空间隔离：
  Agent 之间互相踩端口、踩数据库、踩未提交代码。

有工作空间隔离：
  每个 Agent 都有自己的目录、服务、数据库和提交。
  主工作区只吸收已经解释清楚的结果。

当任务数量变多时，真正稀缺的不是 Agent 数量，而是可控的合并面、可复现的验证证据，以及不会被半成品污染的主工作区。

这篇手册覆盖的搜索词

如果你在搜索下面这些问题，这篇手册就是对应场景：

git worktree 多工作区开发
多 agent 并发开发
AI agent 并行 coding 工作流
Claude Code 多工作区
Codex 多工作区
git workspace development
agent worktree workflow
local dev port isolation
development database isolation

Git 工作空间与多 Agent 并发开发手册