从单 Agent 到 AWF 集群：在 Docker 中编排并行 AI 编码 Agent 工作空间
场景入口
想象这个场景：你的团队刚拿到一个大型代码重构任务——拆分单体应用、重写核心模块、迁移老旧的 TypeScript 代码到新架构。你让 Claude Code 处理模块 A，让 Codex 处理模块 B，想同时跑两个 Agent 加速进度。结果呢？两个 Agent 在同一个文件系统上相互覆盖修改、共享的 node_modules 被打乱、Docker 网络冲突、一个 PR 刚通过测试却发现基分支已经被另一个任务的改动弄脏了。
这个场景不是个例——任何在实际项目中尝试并行运行 AI 编码 Agent 的开发者都遇到过这类问题。并行 Agent 的最大瓶颈从来不是 AI 的能力，而是工作空间的隔离与管理。
对比：有 AWF 和没有 AWF
| 场景 | 没有 AWF | 有 AWF |
|---|---|---|
| 同时运行 3 个 Agent | 文件冲突、node_modules 被破坏 | 每个 Agent 独立 Docker 工作空间 |
| 多项目并行 | 手动切换分支、容易忘记同步 | Git worktree 隔离 + 自动基分支同步 |
| PR 审查反馈 | 手动处理评论、容易遗漏 | 自动监控 PR 评论、Agent 自动修复 |
| CI 失败 | 需要手动干预 | 自动修复 + 重试 + 合并门禁 |
| 多个工具生态 | 每个 Agent 需要单独配置 | 统一 Profile 驱动、6 种 Agent 适配器 |
| 工作区清理 | 手动删除、占用资源 | 成功后自动销毁、失败保留供排查 |
安装与启动
AWF（Agent Workspace Fabric，GitHub）是一个开源的 Python 工具（Apache-2.0 许可），通过 Docker 为每个 AI 编码 Agent 创建隔离的工作空间。
pipx install agent-workspace-fabric uv tool install agent-workspace-fabric awf setup awf start awf service status --format pretty
启动后，本地 API、Worker、数据库和 Web 控制台会在 http://127.0.0.1:3000 上运行。
项目接入
awf init /path/to/your/project --write-profile --yes awf smoke run --project /path/to/your/project --mocked-local --format pretty
接入后，AWF 会自动检测项目类型（Python、Node、Next.js、Go、Java、Rust 等），生成对应的 Profile 配置。
核心特性详解
1. 完整的 Agent 生命周期管理
AWF 把一次 Agent 编码任务转化为一个可观测、可追踪、可恢复的 16 步生命周期：
- 创建 Workspace 数据库记录
- 从目标分支创建隔离的 Git worktree
- 解析 Workspace Profile
- 生成并启动独立的 Docker Compose 栈
- 执行 Profile 预置阶段（安装依赖等）
- 可选 AWF 自身的 Plan → Execute → Compare 循环
- 在工作容器中执行选定的编码 Agent
- 执行 Profile 验证阶段
- 提交、推送并创建 PR
- 监控 PR 直到合并、关闭或失败
- 通过再次调用 Agent 处理 Reviewer 评论
- 修复 CI 失败
- 必要时同步基分支到 PR 分支
- 初始 Review 宽限期
- 所有门禁通过后自动合并
- 成功的工作空间自动销毁，失败的工作空间保留以供排查
每一步都有对应的 REST API、CLI 和 MCP 接口，方便集成到现有工作流。
2. 多平台 Agent 适配
AWF 支持 6 种编码 Agent 适配器，统一通过中央模型/努力度映射表管理：
- Codex CLI — OpenAI 官方 CLI
- Claude Code — Anthropic 编码工具
- Cursor — AI 原生 IDE
- Gemini CLI — Google 编码工具
- OpenCode — 开源编码 Agent
- Grok — xAI 编码工具
每种 Agent 运行在自己的 Docker 容器中，互不干扰。
3. 智能 PR 监控
AWF 的 PR Monitor 功能会自动跟踪已创建的 PR：
- 自动检测新的 Reviewer 评论，调用原 Agent 修复
- 自动修复 CI 失败（当日志可用时）
- 初始 Review 宽限期：给 Reviewer 一段时间再自动合并
- 所有门禁通过后才自动合并
- 支持 Feature PR（自动合并）和 Release/Sync PR（保留到人工合并）
4. 供应链安全门禁
Workspace Profile 可以声明 security.supply_chain 规则，对以下行为发出警告或阻止：
- 未固定版本的依赖安装
- 远程脚本执行
- 意外的包注册表源
- 不在管辖路径内的锁文件编辑
发现项会附带恢复指南，让 Operator 和 PR Monitor 能区分策略阻止与普通测试失败。
使用场景
场景一：并行重构三个模块
awf workspace create --profile ./profiles/auth-module.yaml --task "Auth 模块重写" --agent claude awf workspace create --profile ./profiles/payment-module.yaml --task "支付模块拆分" --agent codex awf workspace create --profile ./profiles/notification-module.yaml --task "通知模块迁移" --agent gemini awf workspace list --format table
每个 Agent 在自己的 Docker 容器中独立工作，共享同一个 Git 仓库但隔离的文件系统，三个 PR 最终通过同一个合并队列管控。
场景二：处理 PR 审查反馈
awf workspace inspect --id ws-42 --format pretty awf pr monitor adopt --pr https://github.com/org/repo/pull/42
AWF 自动接管该 PR 的监控，当 Reviewer 留下评论时，自动调用原 Agent 修复并根据需要推新提交。
架构说明
AWF 的核心是一个 FastAPI REST API（单一 /v1 命名空间），暴露给三种客户端表面：
- REST API — 编程访问
- Typer CLI — 终端操作
- MCP Server — 集成到 Claude Code/Codex 等工具
数据层使用 SQLAlchemy，存储 Workspace、操作和事件的完整状态。Docker Compose 栈在每个 Workspace 的生命周期内动态生成和销毁。
横向对比
| 特性 | AWF | 手动 Docker | Makefile + tmux |
|---|---|---|---|
| 隔离性 | 每 Agent 独立 Docker | 需手动管理 | 共享文件系统 |
| PR 监控 | 自动 | 无 | 无 |
| Agent 适配 | 6 种原生适配 | 需手动配置 | 需手动配置 |
| 自动合并 | 支持 + 门禁 | 无 | 无 |
| CI 修复 | 自动 | 无 | 无 |
| Web 控制台 | 内置 | 无 | 无 |
| MCP 集成 | 原生 | 无 | 无 |
| 供应链安全 | Profile 规则 | 无 | 无 |
注意事项
- 当前为 Alpha 版本，适合本地评估和自用，尚未支持多节点调度和云部署
- 需要本地 Docker 运行环境
- PR 自动化需要
gh（GitHub）或对应的 Forge 认证 - 首次接入项目需要确认 Docker 资源足够（并行 Agent 会占用相应 CPU/内存）
- 建议先用
awf smoke run --mocked-local验证 Profile 配置正确性
总结
AWF 解决的核心问题不是「Agent 能不能写代码」，而是「多个 Agent 能不能安全地并行工作」。对于已经引入 AI 编码工具的团队，当从单 Agent 过渡到多 Agent 协作时，AWF 提供的隔离工作空间、自动化生命周期和 PR 监控能力是现阶段最完整的开源方案之一。