paddock-agent 0.2.0

Multi-agent engineering orchestration framework

Paddock

多 Agent 工程研发编排框架 | Multi-agent engineering orchestration framework

你睡觉的时候，Paddock 在帮你 merge PR。

---

是什么

Paddock 是一个让 AI agent 能够可靠参与真实工程项目的控制平面。它解决的不是"怎么调用 agent"，而是"agent 调用之后怎么不乱、不冲突、不失控、能交付"。

核心能力：

• 多 agent 并发调度：依赖图驱动，自动解锁，路径冲突检测
• Git worktree 隔离：每个任务独立分支，自动 merge，互不干扰
• 结构化工作层次：Goal → Milestone → Phase → Objective，Planner 自动拆解
• Session budget 控制：commit 数 + 时间双维度限制，超时强制终止
• 三层失败恢复：自动重试 → 自动扩展 scope → 人工升级
• 完整可观测性：事件日志、session 日志、Admin dashboard

支持的 agent runtime：Claude Code、OpenAI Codex、Kimi CLI，以及任何接受 prompt 文件的命令行工具。

---

快速开始

环境要求

• Python 3.10+
• Git
• 至少一个 AI agent CLI（如 claude、codex、kimi）

安装

git clone https://github.com/Roganic/paddock.git
cd paddock
pip install -e .

接入一个项目

1. 在项目仓库中创建配置文件

mkdir -p your-project/.paddock
cat > your-project/.paddock/project.yaml << 'EOF'
name: My Project
description: 项目描述
EOF

2. 在 Paddock 中注册项目

cp projects/example.yaml projects/my-project.yaml
# 编辑 my-project.yaml，修改 repo_root、worktrees_root 等路径

3. 初始化数据库并设置 Goal

export PADDOCK_PROJECT=my-project
python scripts/init_db.py
# 在 Admin dashboard 中添加 Goal 和 Milestone

4. 启动 Supervisor

export PADDOCK_PROJECT=my-project
python scripts/supervisor_v2.py --duration-minutes 120

5. 启动 Admin Dashboard（可选）

export PADDOCK_PROJECT=my-project
bash admin/scripts/start.sh
# 访问 http://127.0.0.1:4174

环境变量

变量	说明	默认值
PADDOCK_PROJECT	项目 slug（必填）	无，必须设置
PADDOCK_ROOT	Paddock 根目录	自动检测
PADDOCK_PROXY	agent 子进程使用的代理，如 http://127.0.0.1:7897	不设置代理
PADDOCK_NO_PROXY	代理排除列表	localhost,127.0.0.1,::1
PADDOCK_POLL_SECONDS	Supervisor 轮询间隔（秒）	20
PADDOCK_PLANNER_COOLDOWN	Planner 触发冷却时间（秒）	300
PADDOCK_LOG_LEVEL	日志级别	INFO

---

架构概览

┌─────────────────────────────────────┐
│  Goal          人类设定的长期目标     │
├─────────────────────────────────────┤
│  Milestone     可验证的阶段成果       │
├─────────────────────────────────────┤
│  Phase         里程碑内的工作阶段     │
├─────────────────────────────────────┤
│  Objective     分配给 agent 的任务    │  ← Planner 生成
├─────────────────────────────────────┤
│  Session       单次 agent 执行过程    │  ← Supervisor 调度
├─────────────────────────────────────┤
│  Checkpoint    单次 git commit        │  ← 自动 review & merge
└─────────────────────────────────────┘

Supervisor 每 20 秒运行一次七阶段循环：Harvest → Review → Merge → Unlock → Planner → Apply → Dispatch。

详细架构文档见 docs/PADDOCK_OVERVIEW.md。

---

项目结构

paddock/          核心包（config、db、utils）
scripts/            Supervisor、Planner 等调度脚本
templates/          agent prompt 模板
projects/           项目配置文件（.yaml）
admin/
  backend/          只读 API（FastAPI）
  frontend/         Dashboard（React + Vite）
runtime/            运行时状态（不提交到 git）
tests/              框架自身测试

---

接入新的 Agent

在数据库 agents 表中添加一条记录，或在项目配置中声明：

agents:
  - id: my-agent
    cli_command: my-agent-cli
    command_template: my-agent-cli --prompt {prompt_file} --dir {worktree}
    description: My custom agent

Agent 需要遵守的协议：

1. 读取 {prompt_file} 作为任务描述
2. 在 {worktree} 目录下工作（已是独立 git 分支）
3. 完成后在 stdout 输出 ---SESSION_SUMMARY--- 块（格式见 templates/session-worker.md）

---

示例项目

幻界 2.0：一个 AI 驱动的 TRPG 游戏主持系统，~36,500 行代码，264 个测试，12 个并发 worktree，是 Paddock 的第一个完整验证项目。

---

License

MIT