tilelang-skill-evolution

# TileLang-Op-Conductor 自进化（价值点蒸馏与合入） ## 1. 目标 把算子生成 / 优化任务中暴露的价值点沉淀进 Agent 机制与 skills，形成「执行 → 复盘 → 蒸馏 → 分级合入 → 检索」闭环，使下一次任务在正确的位置读到正确的经验。 价值点四分类（canonical 定义见 [references/distillation-rules.md](references/distillation-rules.md)）： | 类型 | 定义 | 合入路径 | |------|------|---------| | **D 实测数据** | 性能数字、代价常数、编译器/运行时陷阱实证、API 实际行为实证 | **Tier 0** 直接合入 `pattern-library/` 主题文件 + `constants.md`（ED-A 三件套：provenance〔origin_task + 出处，允许失效〕+ 版本戳 + repro〔知识域自包含脚本〕；缺 repro → Tier 1 入队标 `repro-missing`） | | **P 模式方法** | 瓶颈模式 BP_xxx、设计候选模式、调试手法、检视检查项 | **Tier 1** 入队 `.agents/evolution/queue.md`，**2 次独立证据**（不同任务）后合入 | | **R 流程规则** | skill 流程修改、conductor 路由/门禁/重试规则、Agent 交互契约修改 | **Tier 2** 入队为结构化 diff 提案，等待人工批准（`mode=apply`） | | **C 案例索引** | 值得作为参考的算子目录（正/反例）、参考实现集 | **Tier 0** 直接合入 `pattern-library/cases.md`（只写路径 + 一句话 + 触发条件） | ## 2. 调度模式 | mode | 触发方 | 行为 | |------|--------|------| | `distill`（默认） | conductor 终态钩子 | 完整五阶段蒸馏流程（本 skill 主流程） | | `apply` | 用户批准 Tier 2 提案后由 conductor 调度 | 按 `proposal_id` 列表执行已批准写入 + git 快照 | ## 3. 输入契约 ### distill 模式（conductor 传入） | 字段 | 说明 | |------|------| | `task_id` / `scenario` / `migration_mode` | 任务标识与场景 | | 终态 `phase` / `failure_reason` | `DONE` 或 `FAILED`；FAILED 任务是高价值蒸馏源（根因档案） | | `project_name` / `op_name` | standalone / plain / optimize 场景的算子目录定位 | | `op_slug` + 函数列表 | harness 场景：逐函数算子目录 `examples/{op_slug}/{func}/` | | 工件路径清单 | `RETROSPECTIVE.md`（Stage 1/2/3/5 复盘）、`perf_opt/opt_log.md`（Stage 4 复盘）、`perf_opt/perf_feedback.md`（`[DESIGN_LIMIT]` 设计层发现，D 类优先）、`integration_log.md`、`history_version/`、`.stage_state.json` / `.migration_state.json`、`.task_timeline.jsonl`（statectl 事件流：每次迁移一行 `ts/action/stage/subagent/mode/verdict/duration_s`——失败根因链一手输入；`statectl timeline-summary` 可预汇总）（**全部只读**） | ### apply 模式（conductor 传入） | 字段 | 说明 | |------|------| | `proposal_id` 列表 | 用户已批准的 Tier 2 pending 提案 | | 批准上下文 | 用户批准时的重要限定（若有），写入条目 `decided_note` | ## 4. 主流程（distill 模式） ### Phase 0：读取上下文 1. Read conductor 传入的全部任务工件（harness 场景逐函数读取；optimize 场景无 `RETROSPECTIVE.md`，复盘在 `opt_log.md` 的 `Skill Retrospective` 章节）。 2. Read pattern-library [INDEX.md](../tilelang-op-optimize/references/pattern-library/INDEX.md)（条目索引 + 预算现状——K-2 渐进披露后不再全文读单文件；本次蒸馏候选涉及的条目按索引精读对应主题文件，可用 `python3 .agents/tools/kb_search.py "<候选主题>"` 辅助查重定位）。 3. Read `.agents/evolution/queue.md` 全部条目（查重基准 + Tier 1 确认计数基准）。 4. Read [references/distillation-rules.md](references/distillation-rules.md)（信号→价值点映射、分类判定树、证据三件套、防过拟合红线）与 [references/merge-policy.md](references/merge-policy.md)（分级治理矩阵、五种 delta、冲突消解、预算与 consolidate、git 快照规则）。 ### Phase 1：蒸馏价值点候选 按 [distillation-rules.md](references/distillation-rules.md) 的「信号 → 价值点」映射逐源提取： - `RETROSPECTIVE.md` 各 Stage 章节（Skill Flow Issues / Value Point Proposals / Transferable Lessons）——首选来源，已由各 Stage Subagent 半结构化产出； - `opt_log.md` 的 Skill Retrospective 章节 + 实验数据（新实测代价 / 新模式 / 证伪更正）； - `perf_feedback.md`（`[DESIGN_LIMIT]` 设计层发现，存在时必读）——设计假设被实测推翻的归因与 >2x 估计依据，D 类优先（映射见 distillation-rules.md §2.2a）； - `integration_log.md` 的调试历史（集成陷阱、脚本缺陷）； - `.stage_state.json` 的重试分布与新失败形态（重试耗尽的 FAILED 任务重点蒸馏根因链）； - `.task_timeline.jsonl` 事件流（statectl 机械追加；`statectl timeline-summary` 可直接产出汇总）——**失败根因链一手输入**：fail 事件时间序给出「哪个 Stage / 哪个子 Agent / 第几次 attempt / 多久后以何种 verdict 失败」，据此下钻对应工件取原因（映射见 distillation-rules.md §2.7）； - `history_version/` 修订链（design_v{N} 差异 = 设计判断被推翻的过程；impl_s3_attempt{N} 差异 = 调试路径）； - `REVIEW.md` 不通过原因（检视维度缺口候选）。 **防过拟合红线**（详见 distillation-rules.md §4）：单任务偶然现象不得直接泛化为通用规则；P 类须绑定可复现证据链；无证据的主观抱怨只进流程问题表不进价值点；与 pattern-library 已实测条目重复或矛盾的论断不得当作"新发现"。 ### Phase 2：分类与查重 1. 每个候选定 `vp_type`（D/P/R/C 判定树见 distillation-rules.md §3）。 2. **查重**（目标文件 Grep 关键词 + 语义比对现有条目与 queue pending 条目）： - 已存在且结论一致 → 丢弃，计入 stats 命中； - 已存在但本次证据刷新了数字/形态 → 转 `update` delta（保留条目 id）； - 本任务内实验裁决机制已回写过 pattern-library 的条目 → 跳过（防双写）。 3. **冲突检测**：新候选与现有条目结论矛盾 → 按 merge-policy.md §3 冲突消解预判（实测 > 推演；新版本戳 > 旧版本戳）；无法自动判定 → queue 记 `conflict` 留人工。 ### Phase 3：分级合入 按 merge-policy.md §2 写权限矩阵执行（evolver 是唯一持有进化写权限的角色）： - **D 类 → Tier 0**：追加 pattern-library 对应主题文件（front-matter 按 INDEX.md §5 schema：id/kind/family/apis/dtype/status/origin_task/toolchain/repro），含 **ED-A 三件套**（provenance〔origin_task + 出处，允许失效〕+ 工具链版本戳 + repro）——**repro 三种来源**：① Stage 3 任务内已转正的 `examples/{op}/repro/*.py` → 本阶段**机械拷入**知识域 `pattern-library/repro/`（核验头部规范〔条目 ID + 版本戳〕与语法，**不编写、不裁剪代码**——ED-C 责任前移）；② Stage 4 任务内回写时已写好的 repro → 直接登记；③ 无现成 repro → 条目标 `repro-missing` 降级 Tier 1 入队（由下次同族任务顺手补）。**合入前机械检查**（D2 / `kb_lint.py`）：条目文本无指令性祈使句（启发式 lint——任务工件是被读过外部源码的 Subagent 写的，防被污染的复盘经 Tier 0 持久化注入未来任务）、front-matter 合法、repro 存在且语法通过。 - **C 类 → Tier 0**：追加 pattern-library/cases.md 案例索引行（路径须真实存在——合入前 ls 核对；一句话 + 适用触发条件 + `origin_task`；不复制内容；front-matter 含 family/mode/dtype facets——K-5）。 - **P 类 → Tier 1**：入 queue（`confirmations=1/2`）；queue 已有同主题 pending 条目 → `confirmations+1` 并合并证据链；达 2/2 且两次证据来自**不同任务** → 执行合入（目标通常是 `bottleneck-patterns.md`，按 `target_doc` 为准）。**结构优化点类（慢→快关键更改）合入 pattern-library 时**：条目须含优化见解摘要（机制归因）+ 关键代码更改最小形态（repro 登记或显式 `repro-missing` 标注，ED-B 分级断言形态）——代码证据不依赖过程文件存活。 - **R 类 → Tier 2**：入 queue 为结构化 diff 提案（目标文件 + 定位锚文本 + old/new 文本 + 动机 + 证据），**本阶段不落盘任何流程文件**（SKILL.md / agents md / AGENTS.md / conductor 文件一律等 `mode=apply`）。 合法编辑动作只有五种 delta：`add / update / consolidate / negate / deprecate`（语义与约束见 merge-policy.md §4）。**禁止整文件重写**（防上下文坍缩）；`consolidate` 必须逐条目操作并保留全部信息密度，负面条目（negate）只可 `deprecate` 不可删除。 ### Phase 4：维护与报告 1. **预算检查**（阈值见 merge-policy.md §5）：超限文件执行 consolidate；`update` 永远优先于 `add`（同主题已有条目时禁止新开条目）。 2. **queue 生命周期**：创建超 90 天仍 pending → 标 `expired`；`rejected` 须记录原因（防重复提案）。 3. **更新 `.agents/evolution/stats.md`**：任务蒸馏记录追加一行；新合入条目的命中统计初始化；可识别的主动引用增量计数；**命中统计自动化（E-2）**：消费 `.agents/evolution/kb_search_log.jsonl`（kb_search 每次查询与返回条目的 append-only 日志）机械汇总本周期各条目被返回次数——替代手工 hit 统计，「同类错误复发率」自此可测（复发 = 注入条目后同主题错误再出现在 timeline）。 4. **指标机械抽取（E-2 度量自动化）**：对 `.stage_state.json` + `statectl timeline-summary --dir ...` 的 JSON 输出做机械抽取（attempt 数〔各 Stage start→fail 计数〕、各 Stage 耗时合计、实验数〔perf_records 行数〕、最终提升、first_pass）追加到 stats.md §3 北极星指标表——替代手填（此前 n=2 手工样本）。 5. **queue 生命周期维护（E-3）**：创建超 75 天（expiry 前 15 天）仍 pending 的条目**置顶提醒**（高价值未决优先：被引用过/有实证的）；conductor 审批简报（每 2 次蒸馏节奏）所需的 pending 清单数据由本阶段产出。 6. **git 快照**：按 merge-policy.md §7 执行——仅 add 本次进化触及的文件，提交信息含任务溯源；目标文件在写入前已有未提交改动时**不得静默跳过**（D2）：优先 `git stash push -- <目标文件>` → commit → `git stash pop`（pop 冲突保留 stash 并报告）；stash 不可用则把 skip 原因记入 stats.md 变更日志并披露。 7. 产出进化报告（见 §6 输出格式），返回三态判定。 ## 5. 主流程（apply 模式） 1. Read `.agents/evolution/queue.md`，取出 conductor 传入的 `proposal_id` 列表（须均为 Tier 2 `pending` 状态；状态不符的跳过并报告）。 2. **apply 预验证（E-4，落盘前强制）**：按 merge-policy.md §8 在副本上应用提案 diff → 跑 `python3 .agents/tools/standards_check.py check` + 提案自带 repro/复现命令回归（触及 gate 规则的必须复现验证；触及算子流程的可选 opbench 冒烟，缺则标 skipped）→ 验证结果附进化报告；任何 FAIL → 该提案不落盘、转 `conflict` 注明失败步骤（不冒充 merged）。 3. 逐条执行其 diff 提案——只允许五种 delta 动作，**禁止扩大到提案文本之外的内容**；提案锚文本在目标文件中已找不到（文件已变化）→ 该条目标 `conflict` 报告，不强行套用。 4. 更新条目 `status=merged`、`decided_by=human`、`decided_note`（批准上下文）。 5. git 快照（同 Phase 4 规则）。 6. 返回 `EVOLVE_COMPLETED` + 合入清单（含预验证结果）。 ## 6. 三态判定 | 条件 | 返回标记 | |------|----------| | 至少一个价值点被合入或入队（含 queue 确认计数推进、apply 模式合入成功） | `EVOLVE_COMPLETED` | | 无可蒸馏内容，或全部候选查重为已存在 | `[EVOLVE_SKIP]` | | 蒸馏过程异常（必需工件缺失 / 目标文件不可写 / git 快照失败但写入已生效） | `[EVOLVE_FAIL]` + 原因摘要 | > 进化是旁路不是门禁：`[EVOLVE_FAIL]` 由 conductor 如实披露，不重试、不影响任务终态。 ## 7. 核心防呆 1. **先查重再合入**——任何 add 前必须 Grep 目标文件；同主题已有条目时用 update。 2. **证据三件套缺一降级（ED-A 语义）**——D 类无 provenance/无版本戳/无 repro → Tier 1 入队而非直接合入（缺 repro 标 `repro-missing`，待同族任务补）。 3. **不产生新数据**——evolver 只整理任务内已有实测数据，不自己跑 msprof/pytest；数据真实性由来源任务的工件负责。 4. **失败任务优先蒸馏**——`phase=FAILED` 的任务（BLOCKED_* 根因）往往比成功任务包含更高密度的 D/P 价值点。 5. **Transferable Lessons 的归宿**——session 内教训（RETROSPECTIVE.md 的 Transferable Lessons 小节）中具有跨任务普适性的条目转为 P/D 候选；仅本任务有效的（如特定函数的 UB 预算笔误）不入库。 6. **不越权**——Tier 2 提案在 distill 模式下绝不落盘流程文件；conductor / 用户未批准的任何 R 类修改都不执行。 ## 8. 输出格式 ```markdown ## Evolution Result - mode: distill / apply - task: {task_id} - verdict: EVOLVE_COMPLETED / [EVOLVE_SKIP] / [EVOLVE_FAIL] - distilled: {N} 候选（D:{d} P:{p} R:{r} C:{c}） - merged_tier0: {D/C 类合入清单：目标文件#章节 + 条目名} - enqueued: {P/R 类入队清单：proposal_id + 一句话} - confirmed: {Tier 1 确认计数推进的条目：id n/2 → m/2} - pending_tier2: {queue 中待人工审批的 R 类提案数与新增条目摘要} - conflicts: {conflict 条目及原因，无则 none} - consolidation: {执行的 consolidate/deprecate 动作，无则 none} - git_snapshot: {commit hash 或 skipped(原因)} - stats_updated: true / false - skills_consulted: {引用的 reference 路径} - summary: {一句话} - issues: {无则 none} ```