# Spec: experiment-orchestration

## ADDED Requirements

### Requirement: 全因子实验矩阵生成
系统 SHALL 根据实验配置生成全因子实验矩阵：3 模型 × N 级提示词 × 12 commit × 3 次重复（N 为当前启用的提示词级别数），每个单元具有唯一 `run_id`。

#### Scenario: 生成 324 个单元
- **WHEN** 配置 3 模型 × 3 级别 × 12 commit × 3 重复并创建实验
- **THEN** 系统生成恰好 324 个实验单元且各自 `run_id` 唯一

### Requirement: 异步调度执行
系统 SHALL 基于 asyncio 的异步任务队列，按适配层并发额度分批执行实验单元。单次实验为五步流水线：加载样本 diff → 渲染提示词 → 调用模型适配层 → 采集原始结果 → 落库并更新进度。

#### Scenario: 批次执行完毕
- **WHEN** 一批实验单元被调度执行
- **THEN** 全部单元执行完毕（允许重试），进度实时更新

### Requirement: 完整调用记录落库
系统 SHALL 完整记录每次调用：模型标识、策略标识与版本、commit 标识、重复序号、原始输出、token 用量、耗时、调用状态。模型采样参数（温度等）MUST 固定并随 run 记录持久化；每次重复实验 MUST 使用独立 `run_id`；原始输出 MUST 全量留痕。

#### Scenario: 还原历史实验
- **WHEN** 查询任意一次历史实验的数据库记录
- **THEN** 可还原其模型、采样参数、提示词模板及版本、样本与原始输出

### Requirement: 失败重试与隔离
失败调用 SHALL 按指数退避自动重试；超过阈值标记失败并隔离；单个实验单元失败 MUST NOT 中断整体批次。

#### Scenario: 单单元失败不中断批次
- **WHEN** 人为制造 API 限流/超时导致部分单元持续失败
- **THEN** 失败单元重试后被标记失败并隔离，其余单元正常完成

### Requirement: 断点续跑
系统 SHALL 支持断点续跑：批次执行中进程被强杀后重启，能从断点继续，已完成单元 MUST NOT 重复调用模型。

#### Scenario: 强杀后续跑
- **WHEN** 批次执行到一半强杀进程并重启
- **THEN** 系统从断点续跑，已完成单元不重复调用模型

### Requirement: 异常输出处理
模型返回空内容或不合约定结构的内容时，该单元 SHALL 被标记为失败/无效并保留原文，MUST NOT 导致程序崩溃，MUST NOT 做模糊补救式猜测解析。

#### Scenario: 不合约定输出
- **WHEN** 模型返回无法按约定结构解析的内容
- **THEN** 该单元标记失败/无效并保留原文，批次继续