eval_agent/design_draft/EVAL_SERVICE_INTEGRATION.md

# Eval Service 集成到 ShinkaEvolve

## ✅ 集成完成

Eval Service 已成功集成到 ShinkaEvolve，支持异步评估模式。

## 🎯 修改内容（最小化）

### 1. 数据结构扩展

```python
# EvolutionConfig - 新增 3 个字段
class EvolutionConfig:
    eval_service_url: Optional[str] = None  # 已存在
    use_eval_service: bool = False  # 新增：是否使用 eval service 做评估
    evaluator_module: Optional[str] = None  # 新增：evaluator 模块路径
    evaluator_function: str = "main"  # 新增：evaluator 函数名

# RunningJob - 新增 1 个字段
class RunningJob:
    use_eval_service: bool = False  # 新增：标记是否使用 eval service
```

### 2. 核心方法修改

**`_submit_new_job()`** - 选择提交方式：
```python
if self.eval_service_url and self.evo_config.use_eval_service:
    job_id = self._submit_to_eval_service(exec_fname, results_dir, current_gen)
else:
    job_id = self.scheduler.submit_async(exec_fname, results_dir)
```

**`_check_completed_jobs()`** - 选择检查方式：
```python
if job.use_eval_service:
    is_complete = self._check_eval_service_status(job.job_id)
else:
    is_running = self.scheduler.check_job_status(job)
```

**`_process_completed_job()`** - 选择结果获取方式：
```python
if job.use_eval_service:
    results = self._get_eval_service_results(job.job_id, job.results_dir)
else:
    results = self.scheduler.get_job_results(job.job_id, job.results_dir)
```

### 3. 新增辅助方法（3个）

- `_submit_to_eval_service()` - 提交评估到 eval service
- `_check_eval_service_status()` - 检查 eval service 任务状态
- `_get_eval_service_results()` - 获取 eval service 结果

**总计**: ~60 行新增代码

## 📊 使用方式

### 方式 1：传统模式（默认）

```python
evo_config = EvolutionConfig(
    # ... 其他配置 ...
    eval_service_url=None,  # 或者不设置
)
```

**行为**：
- 使用 scheduler 执行评估（旧方式）
- 完全不受影响

### 方式 2：通知模式（已有）

```python
evo_config = EvolutionConfig(
    # ... 其他配置 ...
    eval_service_url="http://localhost:8765",
    use_eval_service=False,  # 默认值
)
```

**行为**：
- 使用 scheduler 执行评估
- 完成后通知 eval service（触发 Agent）

### 方式 3：评估模式（新）

```python
evo_config = EvolutionConfig(
    # ... 其他配置 ...
    eval_service_url="http://localhost:8765",
    use_eval_service=True,  # 启用 eval service 评估
    evaluator_module="examples.circle_packing.evaluate_ori",
    evaluator_function="main",
)
```

**行为**：
- 提交到 eval service 执行评估（异步）
- Eval service 运行 primary + auxiliary evaluators
- 自动集成所有 metrics
- 可能触发 Agent 分析

## 🚀 快速开始

### 1. 启动 Eval Service

```bash
python eval_agent/ev2_service_standalone.py \
    --results-dir /path/to/experiment \
    --primary-evaluator examples/circle_packing/evaluate_ori.py \
    --port 8765
```

### 2. 运行 ShinkaEvolve

```bash
python examples/circle_packing/run_with_eval_service.py
```

或者修改现有脚本：

```python
from shinka.core import EvolutionRunner, EvolutionConfig

evo_config = EvolutionConfig(
    # ... 基础配置 ...
    
    # 启用 eval service 评估
    eval_service_url="http://localhost:8765",
    use_eval_service=True,
    evaluator_module="examples.circle_packing.evaluate_ori",
    evaluator_function="main",
)

runner = EvolutionRunner(evo_config, job_config, db_config)
runner.run()
```

## 📊 数据流

```
ShinkaEvolve:
  1. 生成代码 → gen_1/main.py
  2. POST /api/v1/notify/generation_complete
     (立即返回 job_id)
  3. 继续生成 gen_2（不等待 gen_1 完成）
  4. 轮询 gen_1 状态...
  5. gen_1 完成 → 获取 metrics → 添加到 DB
  6. 继续进化...

Eval Service（后台）:
  1. 接收请求，启动后台任务
  2. 运行 primary evaluator
  3. 运行 auxiliary evaluators
  4. 保存 metrics.json
  5. 决定是否触发 Agent
```

## ✅ 优势

1. **最小修改**：只修改了 ~60 行核心代码
2. **完全兼容**：旧代码不受任何影响
3. **渐进式**：可以逐步迁移到新模式
4. **并发优化**：利用现有的并发机制
5. **自动集成**：primary + auxiliary metrics 自动整合

## 🧪 测试

```bash
# 1. 启动 eval service
python eval_agent/ev2_service_standalone.py \
    --results-dir /tmp/test \
    --primary-evaluator examples/circle_packing/evaluate_ori.py

# 2. 运行测试
python test_eval_service_unified.py

# 3. 运行集成示例
python examples/circle_packing/run_with_eval_service.py
```

## 📝 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `eval_service_url` | str | None | Eval Service URL |
| `use_eval_service` | bool | False | 是否使用 eval service 做评估 |
| `evaluator_module` | str | None | Evaluator 模块路径 |
| `evaluator_function` | str | "main" | Evaluator 函数名 |

## 🔧 代码统计

- **修改文件**: `shinka/core/runner.py`
- **新增配置**: 3 个字段
- **新增方法**: 3 个辅助方法
- **修改方法**: 3 个核心方法
- **新增代码**: ~60 行
- **linter 错误**: 0

## 🎯 下一步

现在可以：

1. ✅ 使用传统模式（不受影响）
2. ✅ 使用通知模式（触发 Agent）
3. ✅ 使用评估模式（完整集成）

选择最适合你的模式，逐步迁移！

---

**实施日期**: 2026-02-03  
**修改者**: AI Assistant  
**状态**: ✅ 完成并测试