# Per-Category Pool Strategy 设计

> **状态**: 已批准  
> **日期**: 2026-07-12  
> **关联**: [app-harness-design](2026-07-07-app-harness-design.md)、[question-gen-v2-design](2026-07-11-question-gen-v2-design.md)

## 1. 动机

v2 题目生成管线为 12 个 task_type 各生成 30 题（共 360 题）。需要支持：

| 需求 | 说明 |
|------|------|
| 按类增量 baseline | 类别生成完成后立即可跑 baseline inference，无需等全量完成 |
| Per-category 分层划分 | 每类 30 题按 correctness 2:1 分为 20 train / 10 val |
| 按类训练 | `--task-types` 控制训练作用域，快速验证单类别效果 |
| 外部 test 池 | test 用 Video-MME 900 道真题中同类题目，不从生成题中抽取 |
| 全局训练兼容 | 全类别联合训练时 system/tool 慢进化看全量 val 信号 |

## 2. 方案选型

| 方案 | 描述 | 取舍 |
|------|------|------|
| A. 最小改动 | 在 `build_pools` 内加 if 分支 | 改动小但两条路径耦合 |
| B. 替换为纯 per-category | 删除全局模式 | 简洁但丢失 Video-MME 900 题训练能力 |
| **C. Pool 工厂模式** ✓ | `PoolStrategy` Protocol + 具体策略 | 符合 Clean Architecture DIP/OCP；策略可独立测试替换 |

**选择 C**：池分割是真正易变的接缝（已有两种策略，未来可扩展），满足 CLAUDE.md 抽象引入条件。

## 3. 核心抽象

### 3.1 PoolStrategy Protocol

```python
# app/ports.py 新增（应用层端口，非 core 层——因为返回值 Pools 定义在 app/harness/）

class PoolStrategy(Protocol):
    """池构建策略端口。"""

    def build(
        self,
        questions: list[GeneratedQuestion],
        correctness: dict[str, bool],
        config: PoolConfig,
    ) -> Pools: ...

    def build_incremental(
        self,
        new_task_types: list[str],
        questions: list[GeneratedQuestion],
        correctness: dict[str, bool],
        config: PoolConfig,
    ) -> dict[str, dict[str, list[str]]]:
        """增量构建新类别的 train/val 划分。

        返回 {task_type: {"train": [qid, ...], "val": [qid, ...]}}。
        仅 PerCategoryPoolStrategy 有实质实现；GlobalPoolStrategy
        不支持增量，调用时抛出 NotImplementedError。
        """
        ...
```

> **层级决策**：`PoolStrategy` 放在 `app/ports.py` 而非 `core/protocols.py`，因为返回类型 `Pools` 定义在 `app/harness/pools.py`。若放入 core 会导致 core → app 的逆向依赖，违反 Clean Architecture 四层分层。
>
> **注**：`PoolConfig` 的两组字段（Global 系列 / PerCategory 系列）由两个策略各取所需，未使用的字段被忽略。这避免了为每个策略定义专属 config 子类的过度抽象。

### 3.2 PoolConfig

```python
# core/types.py 新增

@dataclass(frozen=True)
class PoolConfig:
    task_types: tuple[str, ...] | None  # None = 全部类别
    seed: int                           # 随机种子
    baseline_run_id: str                # 基线 run 标识（用于读 correctness、写入 pools 指纹）
    # GlobalStrategy 使用
    diag_size: int
    diag_correct_ratio: float
    val_size: int
    val_correct_ratio: float
    test_size: int
    eval_min_per_class: int
    # PerCategoryStrategy 使用
    train_ratio: float                  # train/(train+val)，默认 2/3
    test_questions_dir: Path | None     # 外部 test 题源路径（与 RunConfig.test_questions 对应）
```

### 3.3 两个具体策略

**GlobalPoolStrategy**：封装现有 `build_pools` 逻辑，test → val → diag 全局三分。

**PerCategoryPoolStrategy**：

```
对每个 task_type (共 N 题，目标 train=20, val=10):
    correct 题 (Nc 个) → shuffle(seed)
        train_correct = floor(Nc * 20/N)    # 按总量 20/10 比例分配
        val_correct   = Nc - train_correct
    wrong 题 (Nw 个)   → shuffle(seed)
        train_wrong   = 20 - train_correct  # 确保 train 总量恰好 20
        val_wrong     = Nw - train_wrong
    assert train_correct + train_wrong == 20
    assert val_correct + val_wrong == 10

diagnosis = 所有选中类别的 train 合并
validation = 所有选中类别的 val 合并
test = load_benchmark(test_questions_dir) 按 task_types 过滤
```

**边界场景处理**：

| 场景 | 行为 |
|------|------|
| 某类别全部 correct（0 wrong） | 退化为非分层 random 20/10，记录 WARNING |
| 某类别全部 wrong（0 correct） | 同上，退化为非分层 random 20/10 |
| 某类别 correctness 不完整（部分 qid 无 baseline） | fail-fast，列出缺失 qid |
| Video-MME 中某 task_type 无题 | test 池该类别为空，记录 WARNING |

## 4. RunConfig 变更

| 新增字段 | 类型 | 默认值 | 归属 |
|---------|------|--------|------|
| `task_types` | `tuple[str, ...] \| None` | `None` | CLI 临时覆盖 |
| `pool_split_mode` | `Literal["global", "per_category"]` | `"global"` | 科研 YAML |
| `train_ratio` | `float` | `0.667` | 科研 YAML |
| `test_questions` | `str` | `"benchmarks/Video-MME"` | 科研 YAML |

`default.yaml` 新增：

```yaml
harness:
  pool_split_mode: global
  train_ratio: 0.667
  test_questions: "benchmarks/Video-MME"
```

## 5. 增量 Baseline Inference

### 5.1 流程

```bash
# 类别 A、B 完成 → 跑 baseline
python main.py harness --mode infer \
    --run-id baseline_v2 --questions generated-v2-360 \
    --task-types "Object Recognition" "Scene Understanding"

# 类别 C 完成 → 追加到同一 run_id
python main.py harness --mode infer \
    --run-id baseline_v2 --questions generated-v2-360 \
    --task-types "Action Reasoning"

# promote 为 seed
python main.py harness --mode promote \
    --run-id baseline_v2 --seed baseline_v2_seed

# 按类训练
python main.py harness --mode train --fresh \
    --seed baseline_v2_seed --run-id train_obj_recog_01 \
    --task-types "Object Recognition" --pool-split-mode per_category
```

### 5.2 增量写入规则

| 表 | 唯一键 | 同 run_id 多次 infer 行为 |
|---|--------|-------------------------|
| `_runs` | `run_id` | upsert：更新 `updated_at`，保留原始 `created_at` |
| `predictions` | `(run_id, question_id)` | INSERT；主键冲突报错（防重复推理） |
| `traces` | `trace_id` | 正常 INSERT（UUID 天然唯一） |

**重跑同类别**：若需重新推理某类别，先 DELETE 该类别的 predictions（`WHERE run_id=? AND question_id IN (?)`），再重新 infer。

**promote 读取规则**：`promote_to_seed` 读取指定 `run_id` 下全部 predictions，不区分追加批次。promote 前应确保所有目标类别均已完成 baseline。

## 6. 池冻结格式

### 6.1 per_category 格式

```json
{
    "split_mode": "per_category",
    "train_ratio": 0.667,
    "baseline_run_id": "baseline_v2",
    "categories": {
        "Object Recognition": {
            "train": ["qid_1", "qid_2", "..."],
            "val": ["qid_21", "..."]
        }
    },
    "test_source": "benchmarks/Video-MME",
    "questions": [...]
}
```

### 6.2 增量更新

```python
def build_or_load_pools(
    config: RunConfig,
    strategy: PoolStrategy,
    db_path: Path,
) -> Pools:
    """构建或加载三池。

    参数:
        config: 运行配置（含 task_types, pool_split_mode, baseline_run_id 等）。
        strategy: 池构建策略实例。
        db_path: harness.db 路径（用于读取 baseline correctness）。

    流程:
        1. 若 pools.json 存在 → 加载
           a. 若 config.task_types 中有类别不在已冻结的 categories → 增量构建并追加
           b. 若 pools.json 的 seed/train_ratio/baseline_run_id 与当前 config 不一致 → 报错
        2. 若不存在 → 从 DB 加载 correctness → strategy.build() → 冻结
        3. 按 config.task_types 从 categories 中组装 Pools 返回
    """
```

**冻结一致性校验**：加载已有 pools.json 时，若 `split_mode`、`seed`、`train_ratio`、`baseline_run_id` 与当前 config 不一致，直接报错并提示删除 pools.json 重建。已冻结类别的划分不可变，新类别可追加。

### 6.3 向后兼容

旧格式 `pools.json`（无 `split_mode` 字段）自动识别为 global 模式。

## 7. task_types 作用域贯穿

策略在池构建阶段完成所有过滤，下游无需感知 task_types：

| 阶段 | 行为 |
|------|------|
| 池构建 | strategy 只处理指定类别 |
| mini-batch | 消费 scoped 后的 diagnosis 池，无改动 |
| per-skill gate | 池中只有指定类别的题，自然 scoped |
| 慢进化 | 用 scoped 后的 val 池评估，照常进化 |
| held-out eval | test 池已是 Video-MME 同类题 |

## 8. main.py train 接线

```python
# composition root 伪代码
elif config.mode == "train":
    strategy = (PerCategoryPoolStrategy()
                if config.pool_split_mode == "per_category"
                else GlobalPoolStrategy())
    pools = build_or_load_pools(config, strategy)
    await runner.train(pools)
```

## 9. 文件改动地图

| 文件 | 改动类型 | 内容 |
|------|---------|------|
| `app/ports.py` | 新增 | `PoolStrategy` Protocol（应用层端口，避免 core → app 逆向依赖） |
| `core/types.py` | 新增 | `PoolConfig` dataclass |
| `app/harness/pools.py` | 重构 | `GlobalPoolStrategy` + `PerCategoryPoolStrategy` + 增量逻辑 |
| `app/harness/config.py` | 修改 | RunConfig 新增 4 字段 + 校验；`pool_split_mode` 用 Literal 类型 |
| `config/default.yaml` | 修改 | 3 个新配置项 |
| `main.py` | 修改 | `task_types` 纳入 `cli_overrides` + RunConfig；train 接线；strategy 组装 |
| `app/harness/log.py` | 微调 | `_runs` 表 `INSERT OR IGNORE` 改为 `ON CONFLICT DO UPDATE`（增量 infer 更新时间戳） |
| `tests/unit/test_pools.py` | 新增 | 两种策略单元测试 |
| `tests/integration/test_pool_strategy.py` | 新增 | 端到端集成测试 |

### 不改动

- `app/harness/batching.py` — 消费 scoped 池，无需感知策略
- `core/evolution/` — 进化引擎与池来源解耦
- `app/harness/inference.py` — 推理逻辑不变
- `app/question_gen/` — 题目生成与池构建解耦