docs: app/harness/ design — 14-module training loop orchestration layer

2026-07-07 11:28:29 -04:00
parent 4e241aa581
commit eba4344a4b
1 changed files with 341 additions and 0 deletions
@@ -0,0 +1,341 @@
+# Design: app/harness/ 训练循环编排层
+
+**日期** 2026-07-07 · **状态** 提案 · **范围** `app/harness/` 全部 14 个文件
+
+## 1 定位
+
+`app/harness/` 是自进化闭环的编排层，对标 PyTorch Trainer。它组合 `core/evolution/`（决策内核）+ `core/agent/`（AgentLoop 推理引擎）+ `adapters/`（LLM/VLM/telemetry），实现训练循环三级嵌套、块序贯验证、快慢双速进化、checkpoint/resume。
+
+与 `core/evolution/` 的分工：core/ 做决策（"候选好不好"），app/ 做编排（"跑推理、写版本、管缓存、落观测"）。
+
+### 1.1 算法保真
+
+| # | 算法 | 保真要求 |
+|---|------|---------|
+| 6 | 信息阶梯 | 冷启动 2:1 交错 + probe 探针、γ-EMA 更新、warm p̂(1-p̂) 排序、防泄露铁律 |
+| 10 | mini-batch | FFD + round-robin + 正确率混合、确定性（seed） |
+| 13 | 训练循环编排 | 三级嵌套 epoch→step→per-skill、快慢双速、checkpoint/resume、early stop、probation |
+
+## 2 模块结构与依赖
+
+```text
+app/harness/
+├── __init__.py          # 公开 API
+├── config.py            # RunConfig frozen dataclass + 四层校验 + YAML 加载
+├── log.py               # HarnessLog SQLite 薄包装 + RunLog Protocol 实现
+├── store.py             # Store 版本操作 + Seed 管理（稳定基础设施）
+├── workspace.py         # Workspace 生命周期 + manifest + SkillStore/PromptStore 实现
+├── inference.py          # async run_inference（并发推理编排）
+├── pools.py             # 三池切分（test→validation→diagnosis）
+├── batching.py           # FFD + round-robin mini-batch (#10)
+├── gate_ladder.py        # 信息阶梯 + BaselineCache (#6)
+├── validate.py           # 块序贯验证编排（唯一独立子编排器）
+├── momentum.py           # 慢更新动量生成
+├── checkpoint.py         # TrainState 序列化/反序列化 + 原子写
+├── observation.py        # 五张观测表 + step/epoch 报告（合并 metric_log + loop_report）
+└── runner.py             # 瘦编排器：训练循环 + 慢更新十步序 (#13)
+```
+
+```mermaid
+flowchart TD
+    runner["runner.py\n瘦编排器 #13"]
+    runner --> inference["inference.py\nasync 推理"]
+    runner --> validate["validate.py\n块序贯验证"]
+    runner --> momentum["momentum.py\n慢更新动量"]
+    runner --> batching["batching.py\nFFD mini-batch #10"]
+    runner --> pools["pools.py\n三池切分"]
+    runner --> gate_ladder["gate_ladder.py\n信息阶梯 #6"]
+    runner --> checkpoint["checkpoint.py\n状态序列化"]
+    runner --> observation["observation.py\n五表+报告"]
+    runner --> workspace["workspace.py\nmanifest+Protocol"]
+    runner --> config["config.py\nRunConfig"]
+    validate --> inference
+    validate --> gate_ladder
+    momentum --> inference
+    workspace --> store["store.py\n版本+Seed"]
+    inference --> log["log.py\nSQLite+RunLog"]
+    observation --> log
+
+    runner -.->|LLMProvider| core_p["core/protocols.py"]
+    runner -.->|evolve/diagnose| core_e["core/evolution/"]
+    runner -.->|AgentLoop| core_a["core/agent/"]
+```
+
+依赖规则：`app/harness/` → `core/evolution/` + `core/agent/` + `core/protocols`。模块间扁平无环。
+
+## 3 config.py
+
+RunConfig frozen dataclass，47 字段，四层校验，YAML + CLI 加载。
+
+- `frozen=True` 保证运行中不可变
+- 四层校验：`_validate` → `_validate_edit_budget` + `_validate_minibatch` + `_validate_gate`
+- `val_size >= eval_min_per_class × _VIDEO_MME_TASK_TYPE_COUNT(11)`
+- `min_class_per_batch < batch_size`（严格小于）
+- `gate_lambda_dir < 0`（方向拒绝阈值语义）
+- `load_config(yaml_path, cli_overrides)`：合并优先级 CLI args > .env > YAML（CLAUDE.md §4.5）。工程配置（API 密钥、LLM 超时等少变/敏感项）走 .env / pydantic-settings；科研实验配置（gate 阈值、batch 大小等会扫动的参数）走 YAML。RunConfig 统一归口。
+
+与 TRM4 差异：`--resume`/`--fresh` 互斥校验移到 runner（workspace 初始化逻辑在 runner）。新增 .env 层合并（TRM4 仅 CLI > YAML）。
+
+## 4 log.py
+
+HarnessLog SQLite 薄包装 + RunLogImpl（RunLog Protocol 实现）。
+
+**HarnessLog** 与 TRM4 一致：WAL 模式 + threading.Lock 线程安全；`INSERT OR IGNORE` 幂等；query 也持锁（共享连接下并发 SELECT + INSERT 会损坏游标状态）。
+
+**RunLogImpl** 新增，实现 `core/evolution/protocols.py::RunLog`：
+
+- 只读端口（core/ Protocol 定义为只读）
+- 用独立 sqlite3.connect 做 SELECT，不经 HarnessLog 生命周期（不触发 _runs INSERT）
+- `asyncio.to_thread` 包装同步 SQL（避免 aiosqlite 新依赖）
+
+## 5 store.py
+
+Store 版本操作（`advance_version`、`next_version`、`list_versions`、`_write_meta`、`_parse_version`）+ Seed 管理（`init_seed`、`read_seed`、`promote_to_seed`、`extract_run_db`）。
+
+- `list_versions` 只接受 `v\d+` 格式并按**数字值**排序（非字典序），保证 v10 排在 v2 后面。`next_version` 依赖此排序取 latest+1。
+
+- `extract_run_db` 用原始 CREATE 语句重建表（保留 PRIMARY KEY 约束）
+- `promote_to_seed` 强校验 eval run 版本与 --version 一致且非 NULL
+- 临时 db 用 finally 清理
+
+与 workspace.py 分离理由：Store 是跨实验共享的稳定基础设施（变更理由不同、稳定性更高），依赖方向单向（workspace → store）。
+
+## 6 workspace.py
+
+Workspace 生命周期 + manifest 读写 + SkillStore/PromptStore Protocol 实现。
+
+- `ResolvedPaths(frozen=True)`：skills_dir/prompts_dir 解析到 workspace（非 store）
+- `init_workspace_from_seed` 创建前校验 questions ref 存在（fail-fast：归档旧 ws 后才发现缺失则旧 ws 已毁）
+- `record_run` 幂等（同 run_id 不重复追加 history，run 目录和 per-video wiki 目录用 `exist_ok=True` 创建）
+- `update_best`/`read_best`：best 指针独立于 current（可指向已存储但非 current 的版本）
+
+**Protocol 实现**：
+
+| 类 | Protocol | 实现 |
+|---|---------|------|
+| `VersionedSkillStore` | `core/evolution/protocols::SkillStore` | `Path.read_text` + `Path.glob("*.md")` |
+| `VersionedPromptStore` | `core/evolution/protocols::PromptStore` | 同构 |
+
+各 ~15 行。构造参数为 Path（由 resolve_paths 提供）。accept 推进版本后 runner 重建实例。
+
+## 7 inference.py
+
+async run_inference：全异步 + 依赖注入。
+
+### 关键签名
+
+```
+async def run_inference(
+    questions, *, llm, tool_dispatch_fn, log, run_id, concurrency, max_steps, skill_mode, plugins
+) -> InferenceResult
+```
+
+- `asyncio.Semaphore(concurrency)` + `asyncio.gather` 控制并发（替代 ThreadPoolExecutor）
+- LLM/VLM/OCR/Embedding 均由调用方构造注入（inference 不感知具体实现）
+- `run_id: str` 必传（不再可选），空串 → ValueError
+- `_aggregate_results` 从内存聚合（不再 SELECT predictions 表）
+
+### 保留的防御性设计
+
+- 悲观默认值：单题 record 初始 `stop_reason="error"`，成功后覆盖
+- prediction 必落库：`log.insert` 在 try/except 之后（无论成败）
+- `_to_text_field`：非 str 的 evidence/reasoning JSON 序列化入库
+- 5 张表 schema 保留（predictions/traces/validation_flags/anchor_check/observe_frame_health）
+
+## 8 pools.py
+
+三池切分，与 TRM4 1:1 迁移。
+
+- 切分顺序 test→validation→diagnosis（progressive exclusion）
+- test 池自然分布（correct_ratio=None）
+- `build_or_load_pools`：pools.json 存在即冻结复用
+- 旧格式拒绝（无 test 键 → ValueError）
+
+## 9 batching.py — 算法保真 #10
+
+FFD + round-robin + 正确率混合，与 TRM4 1:1 迁移。
+
+- 先小类后大类装箱（小类 first-fit-decreasing 整组不拆、大类全局指针 round-robin 散布）
+- `_validate_params` 防御性自校验（min_class_per_batch < batch_size）
+- `correctness.get(qid) is False` 精确匹配（排除 None/未知题）
+- 只有有错题的题型参与混合
+- 全部确定性（seed 控制 shuffle、题型按名称排序）
+
+## 10 gate_ladder.py — 算法保真 #6
+
+信息阶梯 + BaselineCache，与 TRM4 1:1 迁移。
+
+- 冷启动 p̂ = Beta(1,1) 平滑（错=1/3, 对=2/3），2:1 交错 + probe 探针
+- warm 排序 p̂(1-p̂) 信息量降序，剔除 [p_low, p_high] 外零信息题
+- entries 保持存储序（warm 排序在 ladder_for 取用时做）
+- GatePools 原子写（.tmp + os.replace）
+- 指纹不一致 → RuntimeError（不静默重建）
+- BaselineCache 四维内容寻址（task_type, skill_hash, prompts_version, qid）
+- BaselineCache "先盘后存"（磁盘成功后才更新内存，无分裂窗口）
+- 防泄露铁律：gate 内 rollout（run_id 含 `_gate_`）永不回流 p̂
+
+## 11 validate.py
+
+块序贯验证编排（唯一独立子编排器），async 化。
+
+### 关键类型
+
+| 类型 | 说明 |
+|------|------|
+| `InferenceRunConfig` | 推理配置三元组（concurrency, max_steps, skill_mode） |
+| `ValidationOutcome` | 三态动作 + e-process 证据 + 已观测题逐题对错（candidate_correctness 只含已观测题） |
+| `Probation` | 在途试用账本（anchor_skills_version + correctness_snapshot + pending_edits） |
+
+### 核心函数
+
+`async validate_skill_local(...)` → ValidationOutcome：接收 LLMProvider + ToolDispatchFn + HarnessLog 注入。
+
+内部流程：
+1. `materialize_candidate_skill`（workspace `.cand_tmp/`，唯一命名，finally 清理）
+2. 按 gate_block 切块
+3. 每块：`_resolve_baseline_block`（缓存优先，miss 才 await run_inference）→ `_run_candidate_block`（全块 await）→ INFRA 护栏（跨块累计，分母≥10）→ `pair_block`（core/evolution）→ `gate_decision`（core/evolution）
+4. 最后一块判定即终态（无循环外补判）
+
+- `gate_run_prefix` 必须含 `_gate_`（防泄露过滤依赖此标记，入口校验）
+- 只有终态题的证据行才携带 stop_reason
+- **块级屏障**：每块必须严格顺序执行（基线补齐 → 候选跑完 → INFRA 累计 → pair → gate_decision），不得跨块流式判定或部分观测提前进入 gate。async 化不改变此顺序约束。
+
+## 12 momentum.py
+
+慢更新动量生成，async 化。
+
+- 四类常量单一真源（IMPROVED/REGRESSED/PERSISTENT_FAIL/STABLE_SUCCESS）
+- 展示顺序 REGRESSED 优先（伤害信号最高）
+- `_format_comparison_pairs` 在 try 外（KeyError 不被 ValueError 吞）
+- 解析失败保留 prev_guidance（保守回退）；基础设施异常不捕
+
+导出：`run_slow_momentum`（async）、四类常量、`_format_comparison_pairs`、`_categorize_pair`。编排逻辑（采样、两版 rollout、版本推进）在 runner。
+
+## 13 checkpoint.py
+
+_TrainState 序列化/反序列化 + 原子写 + 配置指纹。
+
+**不持久化**：gate_pools/baseline_cache（各自文件自持久化，resume 按指纹重载）、best_*（从 manifest best 指针读）、global_step（存 progress 块，由 train 单独赋值）。
+
+**完整持久化字段集**（serialize_state 输出，缺一不可）：correctness, eval_prev_acc, eval_prev_run_id, baseline_skills_version, baseline_prompts_version, steps_since_best_improved, epoch_start_skills, changed_task_types_this_epoch (set→sorted list), rejected_buffer, system_packs, tool_packs, probations, gate_cooldown, gate_epoch_observed。
+
+**嵌套 dataclass 复活规则**：SystemCasePack 含 CaseSample 列表（需 `CaseSample(**d)` 逐个重建）；Probation 含 RejectedEdit 列表 pending_edits（先重建 RejectedEdit 再构造 Probation）；ToolCasePack 字段均为标量/dict，`Cls(**d)` 直接构造。
+
+- 反序列化 `d[...]` 不用 `.get` 兜底（缺键 = checkpoint 损坏 → 硬失败）
+- 结构性键变化拒绝 resume，决策性键仅告警
+- 原子写（.tmp + os.replace）
+
+## 14 observation.py
+
+五张观测表 + step/epoch 报告（合并 metric_log + loop_report）。
+
+### 五表
+
+| 表 | 用途 |
+|---|------|
+| dual_metric_eval | epoch 末 hard+soft+mixed 双轨度量 |
+| shadow_gate | mixed 影子 best 候选 |
+| holdout_eval | 四向 held-out 在 test 池的度量 |
+| quadrant_pair | fast gate 后逐题四象限 |
+| gate_evidence | CE-Gate 逐题可回放审计 |
+
+- 所有 write 函数幂等建表
+- 所有 read 函数用独立只读连接（不经 HarnessLog 生命周期）
+- soft/mixed 为 None → 存 NULL（绝不存 0）
+
+### 报告
+
+- `write_step_report`：per (epoch, step, task_type)，skipped/cooldown 路径 gate 字段传 None
+- `write_epoch_report`：system_tool_action + momentum_updated_task_types + best_val_acc
+
+## 15 runner.py — 算法保真 #13
+
+瘦编排器（~400 行），class Runner 作为 DI 容器 + 顶层控制流。
+
+### Runner 类
+
+```python
+class Runner:
+    def __init__(self, config, *, llm, evolve_llm, vlm, telemetry): ...
+    async def train(self, pools) -> None: ...
+    async def infer(...) -> InferenceResult: ...
+    async def eval(version) -> InferenceResult: ...
+    async def diagnose(run_id) -> DiagnosisResult: ...
+    def promote(version, eval_run_id, name) -> None: ...
+```
+
+`self` 只持注入依赖 + _paths。_TrainState 是 train() 内局部变量，显式传参。
+
+### Runner 编排职责补充
+
+以下职责由 Runner 承担（不在 inference/validate 等子模块内）：
+
+- **record_run**：每次调用 run_inference 前，Runner 调 `workspace.record_run(workspace_dir, run_id)` 负责 manifest history 追加和 `runs/<run_id>/wiki` 目录创建。inference.py 不感知 workspace。
+- **eval 版本回填**：`eval()` 跑完后显式 `UPDATE _runs SET skills_version=?, prompts_version=?, questions_ref=?`（promote 依赖此行读版本对建种子）。
+- **run_diagnosis 参数组装**：Runner 负责加载 tree_data（从 TreeEnvironment）、DiagnosePrompts bundle（从根 prompts/ 目录读取诊断 prompt 文件）、questions 列表，组装后传给 `core.evolution.run_diagnosis`。diagnose 模式的完整参数契约：`run_id, questions, tree_data, llm, run_log, skill_store, prompts: DiagnosePrompts, concurrency`。
+
+### _TrainState
+
+19 个可变字段（TRM4 为 20 个，移除 evolve_client——由 Runner.self._evolve_llm 持有）。
+
+关键设计：correctness 增量更新；epoch_start_skills 按文件名索引；gate_epoch_observed 必须持久化并 resume 恢复（阶梯排序开关，丢失会回退冷启动序）；probations 每题型至多一个。
+
+### train() 三级嵌套
+
+epoch → step → per-skill。resume 用 saved_batches 恢复 batch 划分。新 epoch 清空累加器。每 step 后落 "in_epoch" checkpoint，epoch 末落 "epoch_done"。early stop 在慢更新后判。训练收尾 deliver_best + final_test_eval。
+
+### _run_step
+
+rollout → correctness 增量 → diagnose → 累加 slow packs → gate_batch_skills → 冷却递减。
+
+### _gate_batch_skills
+
+按 task_type 排序处理：cooldown 跳过 → evolve → 无改动跳过 → 排除案例包题构造 ladder → validate_skill_local → accept/reject/probation。
+
+accept 关键语义：开账快照在合并前拍取；promote → update_manifest → refresh paths；correctness 二轨合并；清黑名单；probation 分岔（default-strategy.md 不开账）。
+
+reject 黑名单防污染：`_rejected_summary` 只记录 apply_report 中 status 为 applied 的 edit（与 edits 同位对齐筛选），未 applied 的 edit 从未写进候选正文、从未被 gate 验证过，进黑名单会污染"已验证无效"语义。0 applied 时生成防御性文案。
+
+rollback：文件级 revert（读锚版本内容 → promote 新版本），不整体回退 manifest。
+
+### _slow_update_cycle 十步序
+
+```
+1. 捕获版本快照 → 全 val 重跑 R
+2. soft score + dual_metric 落库
+3. R 逐题对错无条件回写
+4. probation 结算（回滚者覆盖 step 3）
+5. best argmax（严格大于）
+6. momentum（不可变新版本，按 skill 文件分组）
+7. system/tool 慢更新（edit_budget_end）
+8. R2 闭环（R2 发生在 momentum 推进 skills 后，其版本对为 (r2_skills_version, new_prompts_version)，绝不沿用 R 的 eval_skills_version。退步 revert prompts；保留则回写 R2 + best argmax 绑定 R2 版本对 + eval_prev ← R2）
+9. 三态标签 + epoch_report + 四向 held-out
+10. gate 阶梯刷新（精确三源：step rollout GLOB `{base}_e{epoch}_s*` 排除 `*_gate_*` + slow R 精确 run_id + kept R2 的 extra_run_ids；reverted R2/shadow/held-out 观测绝不吸收——防泄露同族原则）
+```
+
+### 辅助函数
+
+`resume_plan`、`_guard_infra_failures`、`_apply_batch_correctness`、`_should_early_stop` 等提取为模块级函数（不依赖 self，显式参数，独立可测）。
+
+## 16 与 core/evolution/ 的接缝
+
+| app/harness/ 消费 | core/evolution/ 提供 | 交互模式 |
+|-------------------|---------------------|---------|
+| validate.py | gate_decision, pair_block, classify_quadrants | 纯函数，返回 GateVerdict/PairResult/QuadrantClassification |
+| runner._gate_batch_skills | evolve_single_skill, edit_budget_at, resolve_skill_file | 纯函数/异步，返回 EvolutionRecord |
+| runner._slow_update_cycle | evolve_system_prompt, evolve_single_tool, run_diagnosis | 异步，需 LLMProvider + RunLog + SkillStore |
+| runner._settle_probations | probation_verdict | 纯函数 |
+| momentum | replace_momentum, momentum_inner | 纯函数，文本操作 |
+| checkpoint | types.* (dataclass 序列化) | dataclasses.asdict / Cls(**d) |
+
+**类型导入约定**：app/harness/ 从 `core.evolution.types` 直接导入 dataclass（GateParams, GateVerdict, PairResult, QuadrantClassification, DiagnosisResult, EvolutionRecord, RejectedEdit, SkillCasePack, SystemCasePack, ToolCasePack, EvolvePrompts, DiagnosePrompts）。`core/evolution/__init__.py` 当前只导出函数；types 作为子模块公开 API 的一部分，直接 import 合法（不违反依赖方向）。实现阶段需在 `__init__.py` 补导出这些类型。
+
+## 17 rejected approaches
+
+| 方案 | 拒绝理由 |
+|------|---------|
+| 保持 Runner 单体 God Class（2273 行） | 违反 SRP，测试困难，阅读困难 |
+| 分层编排（runner → slow_update.py 二级编排） | 慢更新与训练循环变更理由相同，拆分增加间接性但不解耦 |
+| 纯函数替代 class Runner | 训练循环有状态（_TrainState 16 字段），参数爆炸比类更差 |
+| workspace.py 单文件 | Store 与 Workspace 变更理由不同、稳定性不同（SRP + SDP） |
+| 混合同步/异步（run_inference 内 asyncio.run） | 与外层 async runner 冲突 |