| name | evolution-loop |
| tier | meta-meta |
| description | Drive continuous improvement of skills and workflows through the diagnose-classify-fix-retest cycle. Use after any testing round reveals failures, when production quality control flags issues, or when accuracy drops below thresholds. Covers failure analysis, distinguishing systemic issues from corner cases, deciding whether to rewrite or patch, and knowing when to stop iterating. The evolution loop is the heartbeat of the system. Also use when transitioning between lifecycle phases (skill testing, workflow testing, production monitoring). |
演化循环：诊断-分类-修复-回归的持续改进机制
演化循环是系统的心跳
没有演化循环，技能和工作流就是静态的产物——写完即弃，遇到问题束手无策。演化循环赋予系统自我修正的能力：发现问题、定位原因、分类处理、修复验证，循环往复，直到达到稳态。
系统的准确率不是一次写对的，是一轮一轮迭代出来的。
循环的完整步骤
测试 → 观察 → 反思 → 诊断 → 分类 → 修复 → 回归测试 → 记录
↑ ↓
←←←←←←←←←←←← 未达标则继续循环 ←←←←←←←←←←←←←←←←←←←←←
退出条件（满足任一即停止）
- 准确率达到
.env 中设定的阈值（SKILL_ACCURACY 或 WORKFLOW_ACCURACY）
- 迭代轮次达到
MAX_ITERATIONS 上限
- 剩余失败案例全部为不可消除的边界案例（已记录、已与开发者用户确认）
- 收敛条件已满足（参见下文「收敛追踪」章节）
第一步：测试
运行技能或工作流，对测试集中的所有样本执行核查。
测试集的构成
assets/samples.json：初始测试样本assets/corner_cases.json：历史迭代中积累的边界案例- 如果是工作流测试，还需要与技能结果进行对比
测试执行规范
- 每轮测试必须运行完整测试集，不能只测新增的案例
- 记录每个案例的判定结果、置信度、执行耗时
- 将测试结果保存到
logs/evolution/ 目录
第二步：观察
不要拿到测试结果就急于修改。先整体审视结果，寻找规律。
观察要点
- 通过率是多少？与上一轮相比是上升还是下降？
- 失败案例集中在哪些类型的单据上？
- 是否存在批量性的同类错误？
- 高置信度的案例中是否混入了错误判定？
- 上一轮修复的问题是否引入了新的回归？
用户反馈作为基准真值
当开发者用户或终端用户对核查结果报告错误时，将这些更正视为基准真值。用户报告的更正优先于编程智能体自身的质量判断。在演化循环中，优先诊断用户报告的错误，再处理智能体自行检测到的问题——用户反馈代表的是已确认的失败，而非疑似问题。
通过仪表盘中内置的反馈机制收集用户错误报告（参见 dashboard-reporting）。每条报告都应转化为测试案例，加入回归测试集。
记录观察结论
{
"iteration": 3,
"total_cases": 25,
"pass": 21,
"fail": 3,
"unable_to_verify": 1,
"accuracy": 0.84,
"delta_from_last": +0.04,
"observation": "三个失败案例均涉及框架合同下的订单发票，疑似作用域定义不足"
}
第三步：反思
在诊断新问题之前，回顾已经尝试过的方案。这是防止在相同的失败修复方案中循环的关键步骤。
读取 logs/evolution/{rule_id}/ 中的结构化迭代日志，关注：
- 历史迭代中识别了哪些失败类型
- 尝试了哪些修复方案，效果如何——准确率上升、下降还是持平？
- 是否有修复方案因引入回归而被回退
反模式检测：如果当前失败匹配的模式在历史上已被诊断并"修复"过，说明之前的修复不充分。应升级修复策略——例如，从提示词微调升级为逻辑重写，或从逻辑重写升级为架构调整。不要对同类问题尝试同类修复两次。
产出：生成简要的迭代历史摘要，供诊断步骤参考。摘要应说明哪些方案已经尝试过、效果如何。第一轮迭代（无历史记录）跳过此步骤。
三个反思维度
审查失败案例时，从三个交叉维度进行分析：
-
按规则维度——同一规则在不同文档上的表现：某条规则（如 R003）是否在特定子集的文档上频繁失败？这揭示的是规则层面的缺陷——可能是提取提示词无法处理某种特定的文档格式。
-
按文档维度——同一文档在不同规则上的表现：某类文档是否导致多条规则同时失败？这揭示的是文档层面的问题——可能是某个模板的解析存在问题，影响了所有下游提取。
-
全局维度——是否存在系统性关联？例如：
- 失败集中在由特定模型层级处理的文档上。
- 失败集中在经过特定解析器层级处理的文档上。
- 仅当文档长度超过某个阈值时才出现失败。
交叉对比这三个维度，往往能揭示从单一视角看不到的根因。例如，"R003 在 X 类文档上失败"是按规则维度的发现，但如果 X 类文档同时导致 R007 和 R012 失败，那真正的问题出在文档类型上，而非任何单条规则。
第四步：诊断
对每个失败案例逐一分析根因。失败的原因通常归为以下四类：
解析失败（Parsing Failure）
系统未能正确识别或提取单据中的目标字段。
表现：提取的字段值与实际不符，或提取结果为空。
常见原因：单据格式变体未覆盖、OCR 质量差、字段位置偏移。
提取失败（Extraction Failure）
字段识别正确，但提取的值不完整或有误。
表现：日期少了年份、金额少了小数位、名称截断。
常见原因：提示词中的提取规则不够严格、字段格式超出预期。
判定失败（Judgment Failure）
字段提取正确，但核查结论错误。
表现：明明应该通过却判定为不通过，或反之。
常见原因：判定逻辑有缺陷、边界条件处理不当、例外情形未覆盖。
作用域失败（Scope Failure）
规则被应用到了不适用的场景，或者未被应用到应该覆盖的场景。
表现：对不适用的单据类型给出了核查结论，或对应该核查的单据跳过了检查。
常见原因：规则的适用范围描述不精确、前提条件缺失。
第五步：分类
根据失败的影响范围分为两类，决定不同的修复策略。
系统性问题（影响 >10% 的测试案例）
同一根因导致多个案例失败。这意味着核查逻辑本身存在缺陷，需要重写或大幅修改。
判定标准：同类错误出现在超过 10% 的测试案例中。
修复策略：重写——回到技能的核心逻辑，修改判定规则、补充遗漏条件、重构提取流程。
边界案例（影响 <10% 的测试案例）
个别特殊情况导致的失败。核查逻辑整体正确，只是没有覆盖到某些特殊情形。
判定标准：只影响个别案例，不存在共性模式。
修复策略：记录——将边界案例添加到 corner_cases.json，在 SKILL.md 的边界情况章节中补充说明。如果边界案例可以通过简单的条件分支处理，也可以小幅修改逻辑。
第六步：修复
系统性问题的修复
- 明确根因和影响范围
- 设计修复方案（可能涉及重写 SKILL.md 的判定逻辑、修改 scripts/ 中的代码）
- 在修改前创建新版本（参照版本控制技能）
- 实施修改
- 先对失败案例做单点验证，确认修复有效
边界案例的处理
- 将案例详细记录到
corner_cases.json
- 在 SKILL.md 中补充边界情况说明
- 如果需要代码层面的处理，添加条件分支
- 如果属于业务上的模糊地带，标记为「待开发者用户确认」
第七步：回归测试
修复后必须运行完整测试集，而非只测修复的案例。
回归检查要点
- 修复的案例是否确实通过了？
- 之前通过的案例是否仍然通过？（无回归）
- 整体准确率是否提升？
- 如果出现回归，需要立即分析原因——修复不能以牺牲其他案例为代价
回归不可接受
如果修复导致已通过的案例回归为失败，说明修复方案有问题。回退修改，重新设计修复方案。
第八步：记录
每一轮迭代都必须完整记录，包括 JSON 格式的结构化日志和可读的文本日志。结构化日志是反思步骤（第三步）的数据来源——确保日志可被程序化扫描。
结构化日志
存放于 logs/evolution/{rule_id}/iteration_{N}.json：
{
"rule_id": "R001",
"iteration": 3,
"phase": "skill_testing",
"timestamp": "2025-04-01T14:30:00Z",
"reflection": "第2轮尝试了相同的正则修复方案，准确率未变",
"test_results": {
"total": 25,
"pass": 23,
"fail": 1,
"unable_to_verify": 1,
"accuracy": 0.92
},
"failures": [
{
"case_id": "S012",
"diagnosis": "judgment_failure",
"classification"
文本日志
存放于 logs/evolution/{rule_id}/iteration_{N}.md，使用自然语言描述本轮迭代的关键发现和决策，便于开发者用户阅读。
收敛追踪
每轮迭代追踪三个指标，以判断何时停止：
- 修正量：与上一轮相比，有多少测试案例的结果发生了变化（占总数的百分比）。
- 新模式数：本轮识别出了多少此前未见过的失败模式。
- 回归数：有多少上一轮通过的测试案例在本轮变为失败。
停止条件
当一轮迭代同时满足以下三个条件时，停止循环：
- 修正量 < 总测试案例的 5%。
- 新模式数 = 0。
- 回归数 = 0。
或者满足单独的准确率收敛条件（D5，2026-04-23 新增）：
- 连续两轮迭代之间的整体准确率变化 < 1%。即
|accuracy[N+1] - accuracy[N]| < 0.01。
条件 4 是为了防止观察到的过度迭代模式——从 v5 一直迭代到 v12，每轮都在 0.5% 的精度范围内来回波动。当模型已经达到"足够好"时，继续迭代只会消耗 token，不会带来实质改进。一旦准确率趋于稳定，应当进入下一阶段（蒸馏/生产）。
如果修正量在连续两轮迭代之间增加，这是回归信号。暂停循环，先诊断原因再继续——上一轮的修复可能正在破坏系统的稳定性。
预期收敛速度
收敛不是线性的。预期早期迭代快速改善，随后收益递减：
| 文档数量 | 典型收敛轮次 |
|---|
| < 50 | 3–5 |
| 50–200 | 4–7 |
| 200–1000 | 5–10 |
| 1000+ | 7–15 |
以上为经验估算。实际收敛取决于规则复杂度、文档多样性和模型能力。如果收敛轮次显著超出预期，应重新审视方法，而非继续硬磨更多轮次。
详见 references/convergence-guide.md 的诊断流程和实际收敛数据。
三个运行阶段
演化循环在系统的不同生命周期阶段有不同的运行模式：
演化阶段（Active Evolution）
- 触发：技能或工作流正在开发和迭代中
- 频率：每次修改后立即运行
- 测试集：完整的 samples.json + corner_cases.json
- 目标：达到准确率阈值
监控阶段（Quality Control）
- 触发：工作流已部署到生产，通过质量监控发现问题
- 频率：由质量监控技能决定
- 测试集：生产中发现的问题案例 + 原有测试集
- 目标：修复生产中暴露的新问题
稳态阶段（Stability）
- 触发：连续 N 个批次无新问题
- 频率：仅在质量监控发出警报时运行
- 特征：迭代频率趋近于零
- 目标：维持准确率不下降
何时向开发者用户求助
不是所有问题都能靠迭代解决。以下情况应及时上报：
- 法规解读分歧：你对法规条文的理解可能有误，需要业务专家确认
- 不可消除的失败：达到
MAX_ITERATIONS 后仍有无法修复的案例
- 矛盾的规则：两条规则对同一场景给出相反的要求
- 样本不足：测试集覆盖的场景不够，无法判断修复是否有效
- 成本与准确率的权衡：提升最后 5% 的准确率需要大幅增加成本，需开发者用户决策
上报时提供结构化的问题描述、你的分析、建议的选项，让开发者用户能高效决策。
