Metadata-Version: 2.4
Name: paddock-agent
Version: 0.2.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"
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。

---

## 是什么

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`）

### 安装

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

### 接入一个项目

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

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

**2. 在 Paddock 中注册项目**

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

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

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

**4. 启动 Supervisor**

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

**5. 启动 Admin Dashboard（可选）**

```bash
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](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` 表中添加一条记录，或在项目配置中声明：

```yaml
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](templates/session-worker.md)）

---

## 示例项目

[幻界 2.0](docs/PADDOCK_OVERVIEW.md#六示例项目幻界-20)：一个 AI 驱动的 TRPG 游戏主持系统，~36,500 行代码，264 个测试，12 个并发 worktree，是 Paddock 的第一个完整验证项目。

---

## License

[MIT](LICENSE)
