Metadata-Version: 2.4
Name: paddock-agent
Version: 0.3.0
Summary: Multi-agent engineering orchestration framework
Author: Paddock Contributors
License: MIT License
        
        Copyright (c) 2026 Paddock Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Roganic/paddock
Project-URL: Repository, https://github.com/Roganic/paddock
Project-URL: Issues, https://github.com/Roganic/paddock/issues
Project-URL: PyPI, https://pypi.org/project/paddock-agent/
Keywords: ai,agent,orchestration,multi-agent,git,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: admin
Requires-Dist: fastapi>=0.115; extra == "admin"
Requires-Dist: uvicorn[standard]>=0.34; extra == "admin"
Requires-Dist: python-multipart>=0.0.9; extra == "admin"
Provides-Extra: dev
Requires-Dist: httpx>=0.28; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25; extra == "dev"
Dynamic: license-file

# Paddock

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

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

[![PyPI](https://img.shields.io/pypi/v/paddock-agent)](https://pypi.org/project/paddock-agent/)
[![Python](https://img.shields.io/pypi/pyversions/paddock-agent)](https://pypi.org/project/paddock-agent/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 是什么

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 文件的命令行工具。

---

## 安装

```bash
pip install paddock-agent

# 包含 Admin dashboard
pip install 'paddock-agent[admin]'
```

---

## 快速开始

**1. 初始化工作空间**

```bash
mkdir ~/paddock-workspace && cd ~/paddock-workspace
paddock init
```

**2. 注册你的项目**

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

**3. 在 Admin dashboard 设置 Goal**

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

**4. 启动 Supervisor**

```bash
paddock supervisor start
```

就这些。Supervisor 会自动规划、调度 agent、review、merge，你只需要偶尔查看 dashboard。

---

## 命令参考

```bash
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 文件的命令行工具都可以接入：

```yaml
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/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](docs/PADDOCK_OVERVIEW.md)。

---

## 项目结构

```
paddock/            核心包（config、db、utils、cli）
paddock/admin/      Admin 后端（FastAPI）
paddock/templates/  Agent prompt 模板
scripts/            Supervisor、Planner 调度脚本
projects/           项目配置示例
tests/              框架测试
```

---

## 开发

```bash
git clone https://github.com/Roganic/paddock.git
cd paddock
pip install -e ".[dev,admin]"
pytest tests/
```

详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

## License

[MIT](LICENSE) © Paddock Contributors
