paddock-agent 0.3.0

Multi-agent engineering orchestration framework

Paddock

多 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 init

2. 注册你的项目

paddock project add ~/code/my-project
# 自动生成 projects/my-project.yaml，推断 repo_root 和 worktrees_root

3. 在 Admin dashboard 设置 Goal

paddock admin start
# 打开 http://127.0.0.1:8100，添加 Goal 和 Milestone

4. 启动 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，直到验收标准满足或预算耗尽。

---

接入新 Agent

在 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。

---

License

MIT © Paddock Contributors