Skip to content

Latest commit

 

History

History
144 lines (99 loc) · 7.46 KB

validation.md

File metadata and controls

144 lines (99 loc) · 7.46 KB

验证方法:如何量化「前置防错」的效果

本方案的价值主张是"用每轮几十 token 的常驻成本,换掉每类错误无限次重犯的事后成本"。 这句话能不能成立,必须由数据说了算——这也是本仓库与"个人心得"类项目的分水岭。 本文件定义记录协议与指标;记录从 2026-08-06 开始(见 data/validation-log.md), 满 4 周后回填首份报告。


1. 三个核心指标

指标 定义 计算方法
命中率 Hit Rate 元规则触发检索的次数中,命中有用禁则并因此改变写法的比例 HIT / 检索次数(Preflight) —— 检索次数必须由事件流记录(非事后补录),否则不统计
避错数 Prevented 因命中禁则而没有发生的报错次数 每次 HIT 记 1(⚠️ 反事实问题:HIT ≠ 真避错——原写法可能本来就不会错。仅作行为指标,不作效果 claim)
复发数 Regressions 已在错题本中的禁则,同类错误再次发生的次数 每次 INCIDENT 且命中已有禁则记 1

衍生指标:

  • 复发率:复发数 / exposure 次数(exposure = 该禁则实际被应用到同类场景的次数)——必须记录 exposure 才能算真实复发率;未记录时只能报 observed regressions 绝对数,禁止用 复发/(避错+复发)(该式把 HIT 与复发两种不同 exposure 混同,是 40% 虚高的根源)。
  • 估算节省 token:避错数 × 单次纠错平均成本(经验系数 3)——同上,受反事实影响,仅作参考不作证明。

1.5 数据集分层(v0.1 数据治理)

为保证效果 claim 不被污染,所有事件/规则按来源分层,只有 A 层可作效果验证:

层 定义 可用于
A · instrumented 事件流逐条记录、可归因、有 exposure 效果验证(复发率/命中率)
B · historical 带日期/场景归因的历史沉淀,但未逐条关联事件 知识库
C · external 用户/他处提供的案例 候选规则
D · unattributed 批量补录、无逐日归因 仅知识库,禁止用于效果 claim

2026-08-06 ~ 09-02 周期数据:规则大多带实测日期(归 B 层),但未逐条关联 RULE 事件且无 exposure 记录,严谨计为 D 层——本周期无法给出任何真实效果率。


1.6 规则生命周期(v0.3,2026-09-02 —— 防二次膨胀 + 事件窗口)

分层不是拍脑袋,由 wrongbook-audit.py 按数据算分,人确认后执行(脚本只出清单,不改规则库)。

时间窗口 = 事件窗口(不是日历日):以"最近 N 个活跃会话"为滚动窗口(默认 N=20,--window 可调)。 活跃会话定义:新开会话且产生 ≥1 次模型/工具调用。只打开软件更新、不干活的日子不产生活跃会话,窗口不推进—— 长时间闲置(如一个月不用)不会把规则误判为"零暴露过期"。

Risk Score(每条规则,窗口内):

RiskScore = 命中率(hit/exposure) × 0.5 + 复发数(归一化) × 0.3 + 影响等级 × 0.2
复发数 ≥ 2 → 一票升级(复发是"查了还踩",权重最高)

容量:核心区硬上限 15 条(当前 12,预留 3 动态席位),一进一出(晋级必挤掉最低分核心);参考区不设上限,季度清理。

决策表(audit 输出三清单,人工确认;"窗口"均指最近 N 个活跃会话):

动作 量化触发(事件窗口) 执行
参考→核心 窗口内 exposure≥15 且 命中率≥30%;或 复发≥2;且核心有空位 挤掉最低分核心
核心→参考 窗口内 命中率<10% 且 复发=0;或 exposure<5 降级
规则→淘汰 连续 2 个窗口 exposure=0 且 复发=0 移入 archive
回滚 降级后窗口内新核心整体命中率掉 >5% 自动回滚 + 豁免观察 4 个窗口
数据失效 操作数/核对数 > 5:1 该周期数据 invalid,不参与升降级

兜底原则:命中必须有结果证据("看过规则"≠"命中");脚本算分、人决定,避免 Agent 自我维护 + 避免"亲手写的核心被降级"的心理抵触;淘汰 = 移入 archive(可恢复),不是删除。


2. 记录协议:四类事件

PREFLIGHT(核对,exposure 计数 —— 2026-09-02 新增,效果验证的关键)

每次工具调用前执行核对仪式时记录,无论是否命中(无命中 = 该动作成功暴露于规则但未触发,也是 exposure):

- [2026-09-02] PREFLIGHT 动作=bash 领域=[bash][Windows] 涉及规则=「标注文本禁则」 结论=命中→改写 / 无命中

记什么:日期、动作类型、领域、涉及的核心规则 ID/条目名(引用原文片段)、结论(命中改写 / 无命中)。 exposure 定义:某规则在该动作场景下被检查到的次数 = PREFLIGHT 事件中「涉及规则」含该条目的次数。 只有 PREFLIGHT 逐条记录后,复发率 = incidents_after_rule / exposures_to_rule 才可计算。

HIT(命中,前置生效)

- [2026-08-06] HIT  领域=bash 禁则=「禁止直接 ls 不存在路径」 效果=改用 `[ -d p ] &&` 写法 避错=1

记什么:日期、命中的禁则、实际换成的写法、是否确认避免了报错。

INCIDENT(报错,无论是否命中)

- [2026-08-06] INCIDENT 命令=... 根因=... 命中已有禁则=是/否
  沉淀=新增/扩充/不沉淀(不沉淀的原因:一次性噪音/环境问题)

记什么:任何 exit code 非 0 或工具报错。重点标记:是否命中已有禁则—— 命中 = 复发(机制失效,需查原因);未命中 = 新坑(沉淀后未来可避)。

RULE(沉淀)

- [2026-08-06] RULE 新增/扩充 条目=「禁止 X —— 因为会 Y」

记什么:错题本的每次增删改,与 revision 对应。


3. 数据来源

来源 用途
会话历史(Agent 平台自动保存) 回溯 INCIDENT 与 HIT,核查 Agent 是否真的执行了元规则
错题本修订记录(revision) RULE 事件:条目增长曲线
用户反馈 用户纠正 = 最高质量的沉淀信号(前置,非报错)
scripts/wrongbook-audit.py(2026-09-02 新增) 扫日志统计 PREFLIGHT(核对) 次数 Y vs 工具调用次数 X;核对率 = Y/X;提取 exposure 计数

4. 月度报告模板

## 2026-09 验证报告(周期:08-06 ~ 09-05)

- 错题本条目:9 → N(+M,其中新增 K / 扩充 L / 修剪 P)
- 核对率 Compliance:PREFLIGHT 次数 Y / 工具调用次数 X(audit 脚本统计)
- 命中率 Hit Rate:HIT 次数 / PREFLIGHT 次数(Y 层数据)
- 复发:R 次(**复发率 = R / exposure 次数**——exposure 由 PREFLIGHT「涉及规则」计数;无 exposure 时只报 R 绝对数)
- 结论:本周期验证了什么 / 机制哪里失效 / 下一步

5. 现状基线(2026-08-06 启动时)

  • 错题本(self-improvement-lessons):9 条禁则
  • 命中数:0(记录尚未开始)
  • 已知复发 0 次
  • 常驻成本实测:全局 REASONIX.md 12 行 ≈ 每轮 <60 token

⚠️ 诚实声明:在本文件建立之前的所有"真实案例"都是一次性叙事,不构成验证数据。 从 2026-08-06 起按本协议记录的数据,才可作为 README 中的验证 claim。