多 Agent 工程研发编排框架 | Multi-agent engineering orchestration framework
你睡觉的时候，Paddock 在帮你 merge PR。
AI 编码助手已经能独立完成复杂编程任务。但在真实工程项目中，"调用一次 agent"远远不够：
- 任务太多：一个功能迭代可能涉及十几个相互依赖的子任务
- 并发风险：多个 agent 同时修改同一个仓库，冲突如何处理？
- 质量控制：agent 完成的工作如何验收？谁来 review？谁来 merge？
- 失控风险：agent 跑偏了怎么办？修改了不该改的文件怎么办？
- 持续性：任务需要跑几个小时甚至过夜，如何保证稳定运转？
Paddock 是解决这些问题的工程控制平面。它不关心"怎么调用 agent"，而是关心"agent 调用之后怎么不乱、不冲突、不失控、能交付"。
核心能力：
- 多 agent 并发调度：依赖图驱动，自动解锁，路径冲突检测
- Git worktree 隔离：每个任务独立分支，自动 merge，互不干扰
- 结构化工作层次：Goal → Milestone → Phase → Objective，Planner 自动拆解
- Session budget 控制：commit 数 + 时间双维度限制，超时强制终止
- 三层失败恢复：自动重试 → 自动扩展 scope → 人工升级
- 完整可观测性：事件日志、session 日志、Admin dashboard
支持的 agent：Claude Code、OpenAI Codex、Kimi CLI，以及任何接受 prompt 文件的命令行工具。
pip install paddock-agent
# 包含 Admin dashboard
pip install 'paddock-agent[admin]'1. 初始化工作空间
mkdir ~/paddock-workspace && cd ~/paddock-workspace
paddock init2. 注册你的项目
paddock project add ~/code/my-project
# 自动生成 projects/my-project.yaml，推断 repo_root 和 worktrees_root3. 在 Admin dashboard 设置 Goal
paddock admin start
# 打开 http://127.0.0.1:8100，添加 Goal 和 Milestone4. 启动 Supervisor
paddock supervisor start就这些。Supervisor 会自动规划、调度 agent、review、merge，你只需要偶尔查看 dashboard。
paddock init [dir] # 初始化工作空间
paddock project add <path> # 注册项目（自动推断配置）
paddock project list # 列出所有项目
paddock supervisor start # 启动调度循环
paddock supervisor start -p my-proj # 只处理指定项目
paddock supervisor status # 查看活跃 session
paddock planner --project my-proj # 手动触发一次规划
paddock admin start # 启动 dashboard（需要 [admin]）
paddock admin start --port 9000 # 指定端口
paddock version # 查看版本┌─────────────────────────────────────┐
│ Goal 人类设定的长期目标 │
├─────────────────────────────────────┤
│ Milestone 可验证的阶段成果 │
├─────────────────────────────────────┤
│ Phase 里程碑内的工作阶段 │
├─────────────────────────────────────┤
│ Objective 分配给 agent 的任务 │ ← Planner 自动生成
├─────────────────────────────────────┤
│ Session 单次 agent 执行过程 │ ← Supervisor 调度
├─────────────────────────────────────┤
│ Checkpoint 单次 git commit │ ← 自动 review & merge
└─────────────────────────────────────┘
Supervisor 每 20 秒运行一次七阶段循环：
Harvest → Review → Merge → Unlock → Planner → Apply → Dispatch
每个 Objective 在独立的 git worktree + 分支上执行，agent 可以在一次 Session 中自主迭代多个 commit，直到验收标准满足或预算耗尽。
在 Admin dashboard 的 Agents 页面添加，或直接编辑数据库。任何接受 prompt 文件的命令行工具都可以接入：
id: my-agent
cli_command: my-agent-cli
command_template: my-agent-cli --prompt {prompt_file} --dir {worktree}Agent 需要遵守的协议：在 stdout 输出结构化的 ---SESSION_SUMMARY--- 块，Supervisor 据此判断成功/失败/重试。详见 templates/session-worker.md。
| 变量 | 说明 | 默认值 |
|---|---|---|
PADDOCK_ROOT |
工作空间目录 | 当前目录 |
PADDOCK_DB |
数据库路径 | runtime/paddock.db |
PADDOCK_PROXY |
agent 子进程代理，如 http://127.0.0.1:7897 |
不设置 |
PADDOCK_POLL_SECONDS |
Supervisor 轮询间隔（秒） | 20 |
PADDOCK_PLANNER_COOLDOWN |
Planner 触发冷却时间（秒） | 300 |
PADDOCK_LOG_LEVEL |
日志级别 | INFO |
| 能力 | Paddock | OpenHands | autoresearch | Slock.ai |
|---|---|---|---|---|
| 多 agent 并发 | ✓ 依赖图调度 | ✗ 顺序 | ✗ 单 agent | ✓ 频道路由 |
| Git worktree 隔离 | ✓ 自动管理 | ✗ | ✗ | ✗ |
| 自动 merge | ✓ | ✗ | ✗ | ✗ |
| 任务依赖图 | ✓ | ✗ | ✗ | ✗ |
| Session budget 控制 | ✓ commit+时间 | ✗ | ✓ 固定时间 | ✗ |
| 三层失败恢复 | ✓ | ✗ | ✓ git revert | ✗ |
| 多项目支持 | ✓ | ✗ | ✗ | ✗ |
| 无人值守过夜 | ✓ | ✗ | ✓ | ✗ |
| 人机实时交互 | ✗ 批处理 | ✓ | ✗ | ✓ |
Paddock 的定位是无人值守的工程交付，不是聊天协作。详细对比见 docs/PADDOCK_OVERVIEW.md。
paddock/ 核心包（config、db、utils、cli）
paddock/admin/ Admin 后端（FastAPI）
paddock/templates/ Agent prompt 模板
scripts/ Supervisor、Planner 调度脚本
projects/ 项目配置示例
tests/ 框架测试
git clone https://github.com/Roganic/paddock.git
cd paddock
pip install -e ".[dev,admin]"
pytest tests/详见 CONTRIBUTING.md。
MIT © Paddock Contributors