381 lines
17 KiB
Markdown
381 lines
17 KiB
Markdown
# Design: core/evolution/ 可提取内核
|
||
|
||
**日期** 2026-07-07 · **状态** 提案 · **范围** `core/evolution/` 全部 7 个文件
|
||
|
||
## 1 定位
|
||
|
||
`core/evolution/` 是自进化循环的决策内核——诊断、进化、门控、补丁。它只依赖 Protocol 接口和标准库，可搬到无 adapters 的环境用假实现原样运行。
|
||
|
||
与 `app/harness/` 的分工：core/ 做决策（"候选好不好"），app/ 做编排（"跑推理、写版本、管缓存"）。
|
||
|
||
## 2 模块结构与依赖
|
||
|
||
```text
|
||
core/evolution/
|
||
├── __init__.py
|
||
├── protocols.py # SkillStore, PromptStore, RunLog
|
||
├── types.py # ~18 个 dataclass
|
||
├── gate.py # CE-Gate e-process（算法 #5）
|
||
├── patch.py # 补丁引擎 + 冻结区（算法 #9 局部）
|
||
├── validate.py # 块验证纯决策函数（算法 #7 局部）
|
||
├── diagnose.py # 两阶段诊断管线（算法 #8）
|
||
└── evolve.py # 进化引擎（算法 #9）
|
||
```
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
gate["gate.py\n纯数学"] ~~~ patch["patch.py\n纯文本"]
|
||
types["types.py"] ~~~ protocols["protocols.py"]
|
||
validate["validate.py"] --> gate
|
||
validate --> types
|
||
diagnose["diagnose.py"] --> types & protocols
|
||
diagnose -.->|LLMProvider| CP["core/protocols.py"]
|
||
evolve["evolve.py"] --> types & protocols & patch
|
||
evolve -.->|LLMProvider| CP
|
||
```
|
||
|
||
依赖规则：`core/evolution/` 不 import `app/` 或 `adapters/`。LLM 调用通过已有 `core.protocols.LLMProvider`。
|
||
|
||
## 3 protocols.py
|
||
|
||
三个 Protocol 均**只读**——core/ 返回结果，app/ 负责持久化。
|
||
|
||
```python
|
||
@runtime_checkable
|
||
class SkillStore(Protocol):
|
||
"""版本化技能读取端口。实现方解析 manifest 指针，core/ 不感知版本号。"""
|
||
def read_skill(self, filename: str) -> str: ...
|
||
def list_skill_files(self) -> list[str]: ...
|
||
|
||
@runtime_checkable
|
||
class PromptStore(Protocol):
|
||
"""版本化提示词读取端口。覆盖 system.md 和 tool extract/verify。"""
|
||
def read_prompt(self, filename: str) -> str: ...
|
||
def list_prompt_files(self) -> list[str]: ...
|
||
|
||
@runtime_checkable
|
||
class RunLog(Protocol):
|
||
"""实验日志查询端口。隔离 SQLite，core/ 不写 SQL。"""
|
||
async def get_predictions(
|
||
self, run_id: str, *, question_ids: list[str] | None = None,
|
||
) -> list[dict[str, Any]]: ...
|
||
async def get_traces(
|
||
self, run_id: str, *, question_ids: list[str] | None = None,
|
||
) -> list[dict[str, Any]]: ...
|
||
```
|
||
|
||
固定模板 prompt（诊断/进化用）不走 PromptStore，由调用方加载后以 frozen dataclass 束传入：
|
||
|
||
```python
|
||
@dataclass(frozen=True)
|
||
class DiagnosePrompts:
|
||
defect_vs_lapse: str; reasoning_sub: str
|
||
span_eval_system: str; span_eval_user: str
|
||
missed_nodes: str; skill_adherence: str
|
||
confirmation_bias: str; evidence_sufficiency: str
|
||
|
||
@dataclass(frozen=True)
|
||
class EvolvePrompts:
|
||
evolve_skill: str; evolve_system: str; evolve_tool: str
|
||
evolve_rank: str; consolidate_system: str
|
||
```
|
||
|
||
| 决策 | 理由 |
|
||
|------|------|
|
||
| Protocol 只读 | core/ 纯输入→纯输出，易测试；写入是 app/ 职责 |
|
||
| RunLog 用领域方法 | 避免 SQL 泄入 core/ |
|
||
| SkillStore/PromptStore 同步 | 文件读取量小且快，无需 async |
|
||
| 模板束 frozen dataclass | 零 I/O + 类型安全，不增 Protocol |
|
||
|
||
> **ARCHITECTURE.md §3.1 修订说明**：ARCHITECTURE.md 定义的 SkillStore/PromptStore/RunLog 含 write_skill/write_prompt/insert 写方法。本设计有意精简为只读——core/ 返回结果 dataclass，写入由 app/harness/ 编排层执行。写方法保留在 app/ 侧的实现类中，不进 core/ Protocol。此为对 ARCHITECTURE.md 的细化，需同步更新 §3.1。
|
||
|
||
## 4 types.py
|
||
|
||
### 4.1 Gate 决策
|
||
|
||
```python
|
||
@dataclass(frozen=True)
|
||
class GateParams:
|
||
e_confirm: float; e_provisional: float; w_net_min: int
|
||
delta_min: float; lambda_dir: float; e_rollback: float
|
||
|
||
@dataclass(frozen=True)
|
||
class GateVerdict:
|
||
decision: str # accept_confirmed | accept_provisional |
|
||
# reject_directional | reject_futility |
|
||
# reject_inertia | continue
|
||
e_value: float; wald_lambda: float
|
||
delta_hat: float; delta_shrunk: float
|
||
```
|
||
|
||
### 4.2 诊断
|
||
|
||
| 类型 | frozen | 用途 |
|
||
|------|--------|------|
|
||
| `SpanMetrics` | ✓ | 单 span judge 结果（step, tool_name, completeness, hallucination, tags） |
|
||
| `SkillStepAdherence` | ✓ | skill 步骤遵循度 |
|
||
| `QuestionMetrics` | ✓ | Stage 1 单题完整指标（7 规则 + 5 judge 类型：span/missed/adherence/bias/sufficiency） |
|
||
| `ErrorAttribution` | ✓ | D1 归因（error_type + cause_category + lapse_note） |
|
||
| `CaseSample` | ✓ | 案例包单样本 |
|
||
| `SkillCasePack` | ✓ | 按题型（failure_cases + success_cases + lapse_notes） |
|
||
| `SystemCasePack` | ✓ | 跨题型行为（行为模式 ≥ 3 次触发） |
|
||
| `ToolCasePack` | ✓ | 按工具（failure_spans + success_spans） |
|
||
| `DiagnosisResult` | ✓ | 管线最终输出 |
|
||
|
||
### 4.3 进化
|
||
|
||
| 类型 | frozen | 说明 |
|
||
|------|--------|------|
|
||
| `EvolutionRecord` | — | 构建过程 mutable；tool 类的 evolved_content 为 JSON `{"extract":..,"verify":..}` |
|
||
| `RejectedEdit` | ✓ | 黑名单条目；gate 字段全 Optional |
|
||
| `EvolutionResult` | ✓ | 聚合输出（由 app/harness/ 编排层组装，非 core/ 函数返回） |
|
||
|
||
### 4.4 验证辅助
|
||
|
||
```python
|
||
@dataclass(frozen=True)
|
||
class PairResult:
|
||
w: int; l: int
|
||
observed: dict[str, tuple[bool, bool]] # qid → (baseline, candidate)
|
||
|
||
@dataclass(frozen=True)
|
||
class QuadrantClassification:
|
||
improvements: list[str]; regressions: list[str]
|
||
persistent_fails: list[str]; stable_successes: list[str]
|
||
```
|
||
|
||
## 5 gate.py — CE-Gate（算法 #5，纯数学）
|
||
|
||
| 常量 | 值 | 来源 |
|
||
|------|-----|------|
|
||
| `_WALD_WIN` | `ln(1.4) ≈ +0.3365` | θ₁=0.70 → 2×0.70 |
|
||
| `_WALD_LOSS` | `ln(0.6) ≈ -0.5108` | 2×(1-0.70)；loss 步幅 > win（不对称） |
|
||
| `_SHRINK_PSEUDO` | 4 | Agresti-Coull 伪计数 |
|
||
|
||
**compute_e_value(w, l)**：截断 Beta 混合 `E = 2^(W+L+1)·B(W+1,L+1)·I½(L+1,W+1)`。log 空间计算；用对称性 `I½(b,a)` 代替 `1-I½(a,b)` 防灾难性消去。`w<0`/`l<0` → ValueError；`tail≤0` → 0.0；`W=L=0` → 1.0。
|
||
|
||
**gate_decision** 四出口优先级：confirmed(E+δ) → directional(Wald) → futility(best-case) → exhaustion(provisional/inertia) → continue。Wald 从累积 W/L 重算（非增量，避免浮点漂移）。delta_shrunk 仅观测，不进决策。
|
||
|
||
**probation_verdict(w, l)**：双向非对称——confirm 用 `E(w,l) ≥ e_confirm`，rollback 用 `E(l,w) ≥ e_rollback`（参数交换）。e_rollback < e_confirm（回滚比确认更容易）。
|
||
|
||
## 6 patch.py — 补丁引擎（纯文本）
|
||
|
||
**标记常量**：`APPENDIX_START/END`、`MOMENTUM_START/END`（HTML 注释形式）、`*_MAX_CHARS=2000`。
|
||
|
||
**区域解析**：`appendix_region_bounds()` 和 `momentum_region_bounds()` **均严格**——标记不配对（单标记/重复/逆序）抛 ValueError，双缺合法返回 None。宽容语义仅存在于 evolve.py 的包装函数 `_strip_appendix_region`（缺标记 = no-op）和 `_appendix_span`（缺标记 = 空串），不在 patch.py 本身。
|
||
|
||
**apply_patch_with_report(content: str, edits: list[dict], protected_spans: list[str]) -> tuple[str, list[dict]]**：
|
||
- edits 为 `[{"op": str, "target": str, "content": str}, ...]`（松类型 dict，保持 TRM4 格式）
|
||
- report 为 `[{"index": int, "op": str, "status": str, "target": str, "content_preview": str}, ...]`
|
||
- 4 种 op：append（最早非 frontmatter 冻结区前）、insert_after（三结果：成功/降级 append/skip）、replace、delete（均首次出现、count=1）
|
||
- 每条 edit 前重算 `_protected_ranges`（坐标偏移）
|
||
- target 不 strip，payload strip
|
||
- 冻结区坐标半开 `[start, end)`
|
||
|
||
**replace_momentum(content, guidance)**：guidance 含标记字面量 → ValueError（注入防护）。空 guidance 合法（清除旧动量，保留标题行）。
|
||
|
||
## 7 validate.py — 纯决策函数（算法 #7 局部）
|
||
|
||
三个公开函数：`pair_block`（逐题比对 W/L）、`classify_quadrants`（四组各 sorted）、`compute_accuracy`。
|
||
|
||
编排循环（materialize candidate → 双臂推理 → 缓存 → INFRA 护栏 → 块序贯 gate_decision）在 app/harness/。
|
||
|
||
## 8 diagnose.py — 诊断管线（算法 #8）
|
||
|
||
### 公开入口
|
||
|
||
```python
|
||
async def run_diagnosis(
|
||
run_id: str,
|
||
questions: list[GeneratedQuestion],
|
||
tree_data: dict[str, Any], # video_id → 树 JSON
|
||
llm: LLMProvider,
|
||
run_log: RunLog,
|
||
skill_store: SkillStore,
|
||
prompts: DiagnosePrompts,
|
||
*, concurrency: int,
|
||
question_ids: list[str] | None = None,
|
||
task_types: list[str] | None = None,
|
||
only_incorrect: bool = False,
|
||
) -> DiagnosisResult:
|
||
```
|
||
|
||
### 流程
|
||
|
||
```
|
||
Stage 1（asyncio.gather + Semaphore，per-question）:
|
||
7 规则指标（纯函数） + 5 LLM judge（span/missed/adherence/bias/sufficiency）
|
||
→ D1 归因瀑布 → defect/lapse 分类（LLM）
|
||
→ ValueError 降级：规则指标保留，judge 指标 None，degraded=True
|
||
|
||
独立串行 pass:
|
||
reasoning_failure 子分类（仅对 error_type=reasoning_failure 的题）
|
||
|
||
Stage 2（纯逻辑）:
|
||
D2 按工具聚合 → D3 按题型×正误 → D4 skill adherence → D5 跨题型行为
|
||
→ 三类案例包构建
|
||
```
|
||
|
||
### 关键保真规则
|
||
|
||
- 归因瀑布顺序：extraction(`completeness<0.5∨hallucination>0.5`) → search(`missed_nodes`) → reasoning(`evidence_sufficient=True`) → mixed
|
||
- defect_vs_lapse 分类：解析失败降级为 "lapse"（保护性，防错误改正文）
|
||
- single-failure fallback：某题型仅剩 1 个 defect → 降级为 lapse_note
|
||
- lapse_note 空白过滤：strip 后为空则丢弃
|
||
- SystemCasePack 触发：3 种行为模式各需 ≥ 3 次出现
|
||
- merge_system_packs stats 用 `{"per_step": [...]}` 包裹（不数值合并）
|
||
- trigram 相似度是**字符级**，取 **max**（非 mean）
|
||
- `_call_judge` 重试 3 次（仅 ValueError），API 错误直传
|
||
|
||
## 9 evolve.py — 进化引擎（算法 #9）
|
||
|
||
### 公开 API
|
||
|
||
| 函数 | 参数 | 返回 |
|
||
|------|------|------|
|
||
```python
|
||
async def evolve_single_skill(
|
||
llm: LLMProvider, pack: SkillCasePack,
|
||
skill_store: SkillStore, prompts: EvolvePrompts,
|
||
source_version: str, edit_budget: int,
|
||
consolidate_threshold: int, *,
|
||
skill_update_mode: Literal["patch", "rewrite"] = "patch",
|
||
rejected: list[RejectedEdit] | None = None,
|
||
) -> EvolutionRecord: ...
|
||
|
||
async def evolve_system_prompt(
|
||
llm: LLMProvider, pack: SystemCasePack,
|
||
prompt_store: PromptStore, prompts: EvolvePrompts,
|
||
source_version: str, edit_budget: int,
|
||
) -> EvolutionRecord: ...
|
||
|
||
async def evolve_single_tool(
|
||
llm: LLMProvider, pack: ToolCasePack,
|
||
prompt_store: PromptStore, prompts: EvolvePrompts,
|
||
source_version: str, edit_budget: int,
|
||
) -> EvolutionRecord: ...
|
||
|
||
def edit_budget_at(
|
||
global_step: int, total_steps: int,
|
||
start: int, end: int,
|
||
) -> int: ... # 纯数学
|
||
```
|
||
|
||
### Skill 三分支
|
||
|
||
| 分支 | 条件 | 行为 |
|
||
|------|------|------|
|
||
| A: Lapse-only | 无 defect edits + 有 lapse_notes | 合成 `applied_append` report，防循环误判 no-op |
|
||
| B: Rewrite | mode="rewrite" + 有 edits | 整篇重写；失败降级：有 lapse 转 A，否则 no-op |
|
||
| C: Patch | 默认 | rank_clip → apply_patch → validate → 最多 2 轮重试 |
|
||
|
||
所有分支后：有 lapse_notes → appendix 追加（≥ threshold 则 consolidate）
|
||
|
||
### rank_and_clip 三级降级
|
||
|
||
LLM 排序 → `_select_top_edits`（`type(idx) is int` 排除 bool + 范围 + 去重）→ 空则降级原序前 N。
|
||
|
||
### Tool 共享预算池
|
||
|
||
extract+verify edits 合池（`_src` 标记）→ rank_clip → 按标记拆回。evolved_content 存 `json.dumps({"extract":..,"verify":..})`。
|
||
|
||
### 冻结区配置
|
||
|
||
| 目标 | 冻结区 |
|
||
|------|--------|
|
||
| Skill | frontmatter + appendix + momentum |
|
||
| System | 3 个 `##` section（能力边界/输出格式/视频树结构）+ appendix |
|
||
| Tool | 输出格式 section + appendix |
|
||
|
||
### 验证规则
|
||
|
||
| 检查 | Skill | System | Tool |
|
||
|------|-------|--------|------|
|
||
| Frontmatter 三字段 | ✓ | — | — |
|
||
| 冻结 section 值相等 | — | ✓ | ✓ |
|
||
| 长度比 [0.3, 2.0]（去冻结区后） | ✓ | ✓ | ✓ per file |
|
||
| 代码块闭合 | ✓ | ✓ | — |
|
||
|
||
### consolidate_appendix 四守卫
|
||
|
||
G1(`<2`直返) → G2(结果非空且≤输入) → G3(any Exception返原文) → G4(**调用方**：`≥`拒绝等长)
|
||
|
||
## 10 共享工具函数
|
||
|
||
**`resolve_skill_file(skills_dir, task_type) -> str`**（core/evolution/ 内部工具函数）：
|
||
|
||
`resolve_skill_file(skill_store: SkillStore, task_type: str) -> str`
|
||
|
||
`task_type.lower().replace(' ', '-') + ".md"`，若文件不在 `skill_store.list_skill_files()` 中则回退 `"default-strategy.md"`。diagnose（加载 skill 内容做 adherence 判定）和 evolve（定位进化目标文件）共用此约定。接受 `SkillStore`（非 `Path`），保持 core/ 不依赖文件系统。
|
||
|
||
## 11 TRM4 → TRM5 变更总表
|
||
|
||
| 项 | TRM4 | TRM5 | 理由 |
|
||
|----|------|------|------|
|
||
| 并发 | `ThreadPoolExecutor` | `asyncio.gather + Semaphore` | TRM5 async-first |
|
||
| LLM | `LLMClient.from_env()` 每线程构造 | 共享 `LLMProvider` 注入 | Protocol 化 |
|
||
| DB | `HarnessLog` + raw SQL | `RunLog` Protocol | 隔离实现 |
|
||
| 文件 | `Path.read_text` 直读 | `SkillStore` / `PromptStore` | 可提取性 |
|
||
| 模板 | `_PROJECT_ROOT / "prompts"` 硬编码 | `DiagnosePrompts` / `EvolvePrompts` 束传入 | 零路径依赖 |
|
||
| 输出 | 写 JSON + DB + advance_version | 纯返回 dataclass，app/ 持久化 | 无副作用 |
|
||
| response 访问 | `response.choices[0].message.content` | `LLMResponse.content` | 已有统一类型 |
|
||
| validate 编排 | 在 core/ | 在 app/harness/ | Clean Architecture |
|
||
| run_evolution 编排 | 在 evolve.py | 在 app/harness/ | 版本管理属 app/ |
|
||
|
||
## 12 迁移保真约束
|
||
|
||
本节列出 TRM4 中影响正确性的实现细节，实现时必须逐条比对。
|
||
|
||
### 12.1 JSON 解析策略差异
|
||
|
||
| 模块 | 函数 | 策略 | 失败行为 |
|
||
|------|------|------|---------|
|
||
| metrics.py | `extract_json_from_response` | 三级：fenced code block → 最外层 `{...}` → `json_repair` | 全失败抛 ValueError |
|
||
| metrics.py | `_call_judge` | 包裹上述，max_retries=2（共 3 次），仅 ValueError 重试 | API 错误直传 |
|
||
| evolve.py | `_parse_llm_json` | 两级：fenced code block → 原文 `json.loads` | 失败返回 None（不抛） |
|
||
| metrics.py | `_parse_json_object` | 两级：`json.loads` → `json_repair` | 失败返回 None |
|
||
|
||
所有解析器均拒绝非 dict 结果（list/str → 视为失败）。
|
||
|
||
### 12.2 关键常量
|
||
|
||
| 常量 | 值 | 位置 | 说明 |
|
||
|------|-----|------|------|
|
||
| `_INFRA_STOP_REASONS` | `frozenset({"error", "parse_error"})` | diagnose | INFRA 排除集 |
|
||
| `_SPAN_EVAL_TOOLS` | `{"view_node", "search_similar", "observe_frame"}` | metrics | span judge + all_tool_outputs 范围 |
|
||
| `_MIN_PATTERN_COUNT` | 3 | diagnose | SystemCasePack 触发阈值 |
|
||
| `_TOOL_TARGET_FILES` | view_node→4 文件, search_similar→2, observe_frame→2 | diagnose | 工具→prompt 文件映射 |
|
||
| truncation | thought[:100], tool_output[:200] (metrics); 不截断 (diagnose) | metrics/diagnose | `_format_trace_text` 两版本不同！ |
|
||
| case_sample truncation | tool_output[:500] | evolve | `_format_case_samples` |
|
||
|
||
### 12.3 案例包选择规则
|
||
|
||
| 包 | failure 选择 | success 选择 |
|
||
|----|-------------|-------------|
|
||
| Skill | 按 error_type 分组，各取 severity top-2 | `max(2, len(failures)//2)`；acc≤0.3 按 budget 升序，否则按 (-adherence, budget) |
|
||
| System | 3 种行为模式（early_submit/high_conf_wrong/confirmation_bias）各取 top-2 | correct + calibrated + no_bias + 0.3≤budget≤0.8，按 abs(budget-0.5) |
|
||
| Tool | 低 completeness top-2 + 高 hallucination top-2，去重，总数≤4 | completeness≥0.9 且 hallucination==0.0 |
|
||
|
||
### 12.4 validate 编排守卫（app/harness/ 侧，非 core/）
|
||
|
||
- `gate_run_prefix` 必须含 `"_gate_"` 子串（防泄漏标记）
|
||
- `ladder_items` 空 → ValueError
|
||
- INFRA guard：累计两臂 error，分母≥10 且 error_rate > `gate_guard_err` → RuntimeError
|
||
- 基线缓存补齐后 `assert all(v is not None)`
|
||
|
||
### 12.5 evolve 重试与退火
|
||
|
||
- `_run_patch_evolution_loop`：`range(2)` 两轮，三种失败反馈（JSON/target 未匹配/验证错误）
|
||
- `edit_budget_at`：`assert start >= end`；`total_steps ≤ 1` 返 start；Python `round`（banker's rounding）
|
||
- `rewrite_from_suggestions`：重写不得长于原文；只捕 `ValueError/KeyError/TypeError/AttributeError`
|
||
|
||
### 12.6 范围说明
|
||
|
||
`momentum.py` 按 ARCHITECTURE.md §2.3 归属 `app/harness/`（非 core/evolution/），不在本设计范围内。其 LLM 调用、四类常量（IMPROVED/REGRESSED/PERSISTENT_FAIL/STABLE_SUCCESS）、`_format_comparison_pairs` 放在 try 外的设计意图、解析失败返回 `prev_guidance` 等规则将在 Design B（app/harness/）中覆盖。
|
||
|
||
## 13 被拒方案
|
||
|
||
**方案 A（validate Protocol 回调）**：给 validate 造 `InferenceRunner` Protocol 让编排留 core/。拒绝理由：leaky abstraction，Protocol 签名暴露 workspace/skills_dir 等外层概念，形式反转实质耦合。
|
||
|
||
**方案 B（同步 + ThreadPoolExecutor）**：保持 TRM4 同步。拒绝理由：TRM5 LLMProvider.chat() 已是 async，同步调用需 asyncio.run() 嵌套或线程桥接，增加复杂度。
|