342 lines
18 KiB
Markdown
342 lines
18 KiB
Markdown
# 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 冲突 |
|