docs: add maintenance pool auto-supplement design

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-07-14 10:11:26 -04:00
parent d7d7ce5bdc
commit 89cad891de
4 changed files with 150 additions and 2 deletions
@@ -0,0 +1,131 @@
+---
+id: maintenance-pool
+title: 训练池 Maintenance 正确题自动补入机制
+type: design
+created: 2026-07-14
+status: approved
+---
+
+# 训练池 Maintenance 正确题自动补入机制
+
+## 1. 目标
+
+在 `PerCategoryPoolStrategy` 的池构建阶段，baseline infer 完成后、分层划分前，自动检测每个 task_type 分组的正确/错误比例。若正确题占比低于 `batch_correct_ratio`，从 `test_questions_dir`（VME benchmark）中补入该 task_type 的已验证正确题，使训练集有足够的正确题满足 batch 构建需求。
+
+### 驱动场景
+
+SubPattern 靶向出题（如 AR30）刻意针对 agent 失败模式，agent 在 baseline infer 中大部分答错。`batch_correct_ratio=0.5` 要求 mini-batch 一半正确一半错误，但 train 池正确题不足会导致 batch 构建失败或质量下降。
+
+## 2. 算法
+
+在 `PerCategoryPoolStrategy.build()` 的 Phase 2（按 task_type 分组）和 Phase 3（分层划分）之间插入 Phase 2.5。
+
+### 候选筛选
+
+当前 baseline correctness dict 仅包含训练题（如 AR30），**不包含 benchmark 题**。因此补入候选的正确性判定需要额外查询 DB 中的历史推理记录：
+
+```
+# 从 DB 查询所有 run 中对 benchmark 题的评估结果（取最新一次）
+benchmark_correctness = query_db(
+    "SELECT question_id, prediction, answer FROM predictions
+     WHERE question_id IN (benchmark_qids)
+     ORDER BY timestamp DESC"
+)
+# 每个 question_id 取最新记录判定正确性
+```
+
+若 DB 中无该题的历史记录，该题不作为候选（不假设正确）。
+
+### 补入流程
+
+```
+对每个 task_type 分组:
+    c = 该组正确题数（来自当前 baseline correctness）
+    w = 该组错误题数
+    r = batch_correct_ratio
+
+    if batch_correct_ratio 为 None 或 c / (c + w) >= r:
+        跳过
+
+    k = ceil((r * w - (1 - r) * c) / (1 - r))
+
+    candidates = test_questions_dir 中同 task_type 的题
+               ∩ DB 历史推理中正确的
+               − 已在当前组中的 question_id
+
+    actual = min(k, len(candidates))
+    补入 actual 道：
+      - 构造新 GeneratedQuestion（clone，family="VME_MAINTENANCE"）
+      - correctness[qid] = True
+    合并到该 task_type 分组
+```
+
+### 接口传参
+
+`PerCategoryPoolStrategy.build` 新增 `db_path: Path | None = None` 参数，用于查询历史 benchmark 推理记录。调用方 `build_or_load_pools` 已持有 `db_path`，直接透传。
+
+### 边界情况
+
+| 场景 | 行为 |
+|------|------|
+| 正确率已满足 r | 不补入 |
+| 候选不足（如需 30 道但只有 41 道可用） | 补入全部可用，接受比例不完美 |
+| `batch_correct_ratio` 为 None | 跳过补入 |
+| `test_questions_dir` 为 None | 跳过补入 |
+| DB 中无 benchmark 历史记录 | 无候选，不补入（日志警告） |
+| 补入题与 test 池重复 | 允许 — test 池保持完整不动 |
+| `_split_one_category` 的 floor 造成 ±1 误差 | 接受 — 比例不完美是预期行为 |
+
+## 3. 接口变更
+
+| 组件 | 变更 |
+|------|------|
+| `PoolConfig` | 新增字段 `batch_correct_ratio: float \| None = None` |
+| `_to_pool_config` | 从 `RunConfig.batch_correct_ratio` 映射（`RunConfig` 已有该字段，默认 0.5） |
+| `PerCategoryPoolStrategy.build` | 新增 `db_path` 参数；Phase 2 和 Phase 3 之间插入 Phase 2.5 |
+| `build_or_load_pools` | 透传 `db_path` 给 `strategy.build()` |
+
+### 不变的部分
+
+- `_split_one_category` 不改 — 补入后的分组正常走分层划分
+- test 池加载（Phase 4）不改 — 63 道 VME AR 完整保留
+- `GlobalPoolStrategy` 不改
+- pipeline / runner / batching 不改
+
+## 4. 补入题的标记与追溯
+
+| 字段 | 值 | 说明 |
+|------|-----|------|
+| `family` | `"VME_MAINTENANCE"` | 区分于 `"ACTION_RECOGNITION"` 生成题 |
+| `skill_target` | 保持原题值 | 从 benchmark 原始数据继承 |
+| correctness | `True` | 来源定义：从"已验证正确"池选出 |
+
+## 5. 数据流
+
+```
+baseline infer (30 道 AR30)
+    ↓
+correctness = {qid: True/False}  (如: 5 correct, 25 wrong)
+    ↓
+PerCategoryPoolStrategy.build()
+    Phase 1: 按 task_types 过滤
+    Phase 2: 按 task_type 分组
+    Phase 2.5: ←── 新增 maintenance 补入
+        检查: c=5, w=25, r=0.5 → 需补 k=20
+        从 VME benchmark 加载 AR 正确题 (41 道)
+        排除已有 → 补入 min(20, 41) = 20 道
+        组总量: 50 (25 correct, 25 wrong)
+    Phase 3: _split_one_category (train_ratio=0.667)
+        train: 33 题 (≈17 correct + 16 wrong)
+        val: 17 题 (≈8 correct + 9 wrong)
+    Phase 4: test 池 (63 道 VME AR，完整不动)
+```
+
+## 6. 非功能性需求
+
+| 维度 | 设计 |
+|------|------|
+| 持久化 | 补入题写入 pools.json 冻结，与原生题一视同仁 |
+| 幂等性 | pools.json 存在则直接加载，不重复补入 |
+| 断点续跑 | 不影响 — pools.json 冻结后训练可断点恢复 |
+| 原子性 | 不适用 — 池构建是一次性操作 |
@@ -170,6 +170,11 @@
      "id": "plan:action-recognition-strategy",
      "label": "ActionRecognitionStrategy 特化实现计划 (Plan B)",
      "type": "plan"
+    },
+    {
+      "id": "design:maintenance-pool",
+      "label": "训练池 Maintenance 正确题自动补入机制",
+      "type": "design"
    }
  ],
  "links": [
@@ -312,6 +317,13 @@
      "relation": "implements",
      "evidence": "Plan B implements design §4: ActionRecognitionStrategy with 6 SubPatterns",
      "added": "2026-07-14T10:34:27.079088+00:00"
+    },
+    {
+      "source": "design:maintenance-pool",
+      "target": "design:task-type-strategy",
+      "relation": "extends",
+      "evidence": "maintenance pool supplements the per-category pool strategy to support SubPattern-targeted training",
+      "added": "2026-07-14T14:11:13.527027+00:00"
    }
  ]
 }
@@ -1,8 +1,8 @@
 # Research Wiki 索引

-> 自动生成，更新时间：2026-07-14 10:34 UTC
+> 自动生成，更新时间：2026-07-14 14:11 UTC

-## design (25)
+## design (27)
 - [2026-07-06-core-agent-adapters-llm-design](designs/2026-07-06-core-agent-adapters-llm-design.md) `design:2026-07-06-core-agent-adapters-llm-design`
 - [2026-07-07-app-harness-design](designs/2026-07-07-app-harness-design.md) `design:2026-07-07-app-harness-design`
 - [2026-07-07-core-evolution-design](designs/2026-07-07-core-evolution-design.md) `design:2026-07-07-core-evolution-design`
@@ -25,6 +25,8 @@
 - [建树模块竖切设计：数据结构 + 建树 + 修复 + 迁移](designs/2026-07-07-tree-module-design.md) `design:2026-07-07-tree-module-design`
 - [建树模块竖切设计：数据结构 + 建树 + 修复 + 迁移](designs/tree-module-vertical-slice.md) `design:tree-module-vertical-slice`
 - [搜索 Agent 装配层设计（app/search/）](designs/2026-07-07-search-module-design.md) `design:2026-07-07-search-module-design`
+- [训练池 Maintenance 正确题自动补入机制](designs/2026-07-14-maintenance-pool-design.md) `design:2026-07-14-maintenance-pool-design`
+- [训练池 Maintenance 正确题自动补入机制](designs/maintenance-pool.md) `design:maintenance-pool`
 - [论文主图：Self-Evolving Search Agent 推理训练闭环](designs/paper-main-figure.md) `design:paper-main-figure`
 - [赛题生成工具设计](designs/question-gen-synth.md) `design:question-gen-synth`
 - [赛题生成工具设计（Question Generation Synthesis）](designs/2026-07-09-question-gen-synth-design.md) `design:2026-07-09-question-gen-synth-design`
@@ -79,3 +79,6 @@
 - [2026-07-14 10:34 UTC] 新增 plan: ActionRecognitionStrategy 特化实现计划 (Plan B) (plan:action-recognition-strategy)
 - [2026-07-14 10:34 UTC] 新增边: plan:action-recognition-strategy --implements--> design:task-type-strategy
 - [2026-07-14 10:34 UTC] 重建索引: 66 篇页面
+- [2026-07-14 14:11 UTC] 新增 design: 训练池 Maintenance 正确题自动补入机制 (design:maintenance-pool)
+- [2026-07-14 14:11 UTC] 新增边: design:maintenance-pool --extends--> design:task-type-strategy
+- [2026-07-14 14:11 UTC] 重建索引: 68 篇页面