Leaf - AI Agent 自进化系统

让 AI Agent 通过自我反思发现问题并提出改进方案的进化系统。

核心理念

• Agent 专注于思考和分析，不直接修改代码
• 进化由问题驱动（用户反馈、错误日志、性能问题）
• 改进通过 Proposal → Review → 专业工具实现 的流程
• 所有进化历史通过 GitHub Issues 追踪

架构

┌─────────────────────────────────────────────────────────────┐
│                    Orchestrator (端口 9000)                  │
│                      协调器 - 控制面                          │
├─────────────────────────────────────────────────────────────┤
│  Sandbox Pool     │  Task Router    │  Proposal Manager     │
│  (沙盒池管理)      │  (任务路由)       │  (提案管理)           │
└────────┬──────────┴────────┬────────┴────────┬──────────────┘
         │                   │                  │
         ▼                   ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  Sandbox A      │ │  Sandbox B      │ │  GitHub Issues  │
│  (gen0)         │ │  (gen1)         │ │  (Proposals)    │
│  ┌───────────┐  │ │  ┌───────────┐  │ └─────────────────┘
│  │ Bootstrap │  │ │  │ Bootstrap │  │
│  │ (固定)     │  │ │  │ (固定)     │  │
│  └─────┬─────┘  │ │  └─────┬─────┘  │
│        │        │ │        │        │
│  ┌─────▼─────┐  │ │  ┌─────▼─────┐  │
│  │deepagents │  │ │  │deepagents │  │
│  │ (基因组)   │  │ │  │ (进化版)   │  │
│  └───────────┘  │ │  └───────────┘  │
└─────────────────┘ └─────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Observatory (前端)                         │
│            React + Vite + Tailwind CSS                       │
│  状态面板 │ 沙盒管理 │ 任务监控 │ 谱系图 │ 提案管理          │
└─────────────────────────────────────────────────────────────┘

目录结构

leaf-next/
├── orchestrator/              # 协调器服务 (Python, aiohttp)
│   ├── server.py             # HTTP API 服务
│   ├── sandbox_manager.py    # Docker 沙盒池管理
│   ├── proposal_manager.py   # 提案生命周期管理
│   ├── models.py             # 数据模型 (Sandbox, Task, Proposal)
│   ├── repositories/         # Repository 层 (DDD 模式)
│   │   ├── interfaces.py    # 抽象接口
│   │   ├── memory.py        # 内存实现
│   │   └── file.py          # 文件持久化实现
│   ├── Dockerfile
│   └── requirements.txt
├── evo_bootstrap/             # 沙盒引导器（固定，不进化）
│   ├── runner.py             # HTTP 服务 + Agent 执行
│   ├── reflector.py          # 反思日志与问题提取
│   ├── proposer.py           # Proposal 生成 + GitHub Issue
│   ├── mutator.py            # Git 变异操作
│   ├── entrypoint.sh         # 容器启动脚本
│   └── Dockerfile
├── observatory/               # 观测台前端 (React + Vite + Tailwind)
│   ├── src/
│   │   ├── api/client.ts    # Orchestrator API 客户端
│   │   ├── components/      # UI 组件
│   │   ├── hooks/           # React Hooks
│   │   └── types/           # TypeScript 类型定义
│   └── package.json
├── libs/deepagents/           # 基因组（进化目标，通过脚本初始化）
├── docs/design/               # 设计文档与 ADR
├── scripts/
│   └── init.sh               # 基因组初始化脚本
├── docker-compose.yml                  # 单沙盒部署
└── docker-compose.orchestrator.yml     # 完整系统部署

快速开始

1. 初始化项目

# 克隆基因组（deepagents）
./scripts/init.sh

2. 配置环境变量

cp .env.example .env
# 编辑 .env 填入:
# - ANTHROPIC_API_KEY
# - GITHUB_TOKEN
# - GITHUB_REPO (如 pandazki/deepagents)

3. 启动系统

# 构建并启动 Orchestrator + 沙盒
docker compose -f docker-compose.orchestrator.yml up -d

4. 启动 Observatory 前端

cd observatory
bun install
bun dev

5. 使用 API

# 查看系统状态
curl http://localhost:9000/status

# 创建沙盒
curl -X POST http://localhost:9000/sandboxes \
  -H "Content-Type: application/json" \
  -d '{"genome_branch": "evo-seed"}'

# 提交任务
curl -X POST http://localhost:9000/tasks \
  -H "Content-Type: application/json" \
  -d '{"task": "分析代码中的性能瓶颈"}'

# 触发反思
curl -X POST http://localhost:9000/sandboxes/{id}/reflect

# 从 GitHub 同步提案
curl -X POST http://localhost:9000/proposals/sync

API 端点

Orchestrator (端口 9000)

端点	方法	说明
/	GET	服务信息与所有端点列表
/status	GET	系统状态（运行时间、沙盒/任务统计）
沙盒管理
/sandboxes	POST	创建沙盒
/sandboxes	GET	列出所有沙盒
/sandboxes/{id}	GET	获取沙盒详情
/sandboxes/{id}	DELETE	终止沙盒
/sandboxes/{id}/reflect	POST	触发沙盒反思
/sandboxes/{id}/logs	GET	获取沙盒容器日志
任务管理
/tasks	POST	创建任务（自动分配沙盒执行）
/tasks	GET	列出任务（支持 ?status= 过滤）
/tasks/{id}	GET	获取任务详情
提案管理
/proposals	GET	列出所有提案（支持 ?status= 过滤）
/proposals/{id}	GET	获取提案详情
/proposals/sync	POST	从 GitHub Issues 同步提案
/proposals/{id}/approve	POST	批准提案
/proposals/{id}/reject	POST	拒绝提案（body: {"reason": "..."})
/proposals/aggregate	GET	聚合相似提案
监控
/metrics	GET	当前系统指标（CPU/内存/磁盘/任务统计）
/metrics/history	GET	指标历史记录
/events	GET	事件日志（支持 ?type= ?source= 过滤）
/lineage	GET	进化谱系图（节点+边）

沙盒 Agent (端口 8080+)

端点	方法	说明
/health	GET	健康检查 + 执行统计
/task	POST	执行任务（自动记录日志）
/feedback	POST	提交用户反馈
/reflect	POST	触发反思分析
/propose	POST	直接提交进化 Proposal
/proposals	GET	查看本地 Proposals
/logs	GET	查看执行日志
/genome	GET	查看基因组文件信息
/mutate	POST	提交变异（仅限 Orchestrator 调用）

数据模型

Sandbox

沙盒实例，对应一个 Docker 容器中运行的 Agent。

字段	类型	说明
id	string	沙盒 ID（sandbox_xxxx）
container_id	string	Docker 容器 ID
genome_branch	string	基因组分支
organism_id	string	有机体 ID
generation	int	代数
status	enum	creating/running/idle/busy/stopped/error
port	int	映射端口

Task

任务，提交给沙盒执行。

字段	类型	说明
id	string	任务 ID（task_xxxx）
content	string	任务内容
sandbox_id	string	执行沙盒 ID
status	enum	pending/running/completed/failed/cancelled
result	string	执行结果
error	string	错误信息

Proposal

进化提案，源自 Agent 反思或 GitHub Issue。

字段	类型	说明
id	string	提案 ID（proposal_xxxx）
title	string	标题
problem_description	string	问题描述
solution_approach	string	解决方案
target_files	list	目标文件及变更说明
risk_level	enum	low/medium/high/critical
status	enum	pending/approved/rejected/implementing/completed/failed
github_issue_number	int	关联的 GitHub Issue 编号

进化流程

执行任务 → 记录日志 → [触发反思] → 分析问题 → 生成 Proposal → GitHub Issue
                                                              ↓
                                              [人类/AI 审核] → 批准
                                                              ↓
                                              [Claude Code] → 实现代码
                                                              ↓
                                              新分支 → 新一代 Agent

技术栈

• Orchestrator: Python 3.11, aiohttp, docker-py, psutil
• Bootstrap: Python 3.11, aiohttp, pyyaml, deepagents + langchain
• Observatory: React 19, Vite 7, Tailwind CSS 4, TypeScript, Lucide Icons
• 基础设施: Docker, GitHub CLI (gh)

设计文档

详细设计请参考 docs/design/ 目录中的 ADR 文档。

相关仓库

• 基因组仓库: pandazki/deepagents (branch: evo-seed)
• 进化提案: Issues

License

MIT