本方案的价值主张是"用每轮几十 token 的常驻成本,换掉每类错误无限次重犯的事后成本"。 这句话能不能成立,必须由数据说了算——这也是本仓库与"个人心得"类项目的分水岭。 本文件定义记录协议与指标;记录从 2026-08-06 开始(见
data/validation-log.md), 满 4 周后回填首份报告。
| 指标 | 定义 | 计算方法 |
|---|---|---|
| 命中率 Hit Rate | 元规则触发检索的次数中,命中有用禁则并因此改变写法的比例 | HIT / 检索次数(Preflight) —— 检索次数必须由事件流记录(非事后补录),否则不统计 |
| 避错数 Prevented | 因命中禁则而没有发生的报错次数 | 每次 HIT 记 1( |
| 复发数 Regressions | 已在错题本中的禁则,同类错误再次发生的次数 | 每次 INCIDENT 且命中已有禁则记 1 |
衍生指标:
- 复发率:
复发数 / exposure 次数(exposure = 该禁则实际被应用到同类场景的次数)——必须记录 exposure 才能算真实复发率;未记录时只能报 observed regressions 绝对数,禁止用复发/(避错+复发)(该式把 HIT 与复发两种不同 exposure 混同,是 40% 虚高的根源)。 - 估算节省 token:
避错数 × 单次纠错平均成本(经验系数 3)——同上,受反事实影响,仅作参考不作证明。
为保证效果 claim 不被污染,所有事件/规则按来源分层,只有 A 层可作效果验证:
| 层 | 定义 | 可用于 |
|---|---|---|
| A · instrumented | 事件流逐条记录、可归因、有 exposure | 效果验证(复发率/命中率) |
| B · historical | 带日期/场景归因的历史沉淀,但未逐条关联事件 | 知识库 |
| C · external | 用户/他处提供的案例 | 候选规则 |
| D · unattributed | 批量补录、无逐日归因 | 仅知识库,禁止用于效果 claim |
2026-08-06 ~ 09-02 周期数据:规则大多带实测日期(归 B 层),但未逐条关联 RULE 事件且无 exposure 记录,严谨计为 D 层——本周期无法给出任何真实效果率。
分层不是拍脑袋,由 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(可恢复),不是删除。
每次工具调用前执行核对仪式时记录,无论是否命中(无命中 = 该动作成功暴露于规则但未触发,也是 exposure):
- [2026-09-02] PREFLIGHT 动作=bash 领域=[bash][Windows] 涉及规则=「标注文本禁则」 结论=命中→改写 / 无命中
记什么:日期、动作类型、领域、涉及的核心规则 ID/条目名(引用原文片段)、结论(命中改写 / 无命中)。 exposure 定义:某规则在该动作场景下被检查到的次数 = PREFLIGHT 事件中「涉及规则」含该条目的次数。 只有 PREFLIGHT 逐条记录后,复发率 = incidents_after_rule / exposures_to_rule 才可计算。
- [2026-08-06] HIT 领域=bash 禁则=「禁止直接 ls 不存在路径」 效果=改用 `[ -d p ] &&` 写法 避错=1
记什么:日期、命中的禁则、实际换成的写法、是否确认避免了报错。
- [2026-08-06] INCIDENT 命令=... 根因=... 命中已有禁则=是/否
沉淀=新增/扩充/不沉淀(不沉淀的原因:一次性噪音/环境问题)
记什么:任何 exit code 非 0 或工具报错。重点标记:是否命中已有禁则—— 命中 = 复发(机制失效,需查原因);未命中 = 新坑(沉淀后未来可避)。
- [2026-08-06] RULE 新增/扩充 条目=「禁止 X —— 因为会 Y」
记什么:错题本的每次增删改,与 revision 对应。
| 来源 | 用途 |
|---|---|
| 会话历史(Agent 平台自动保存) | 回溯 INCIDENT 与 HIT,核查 Agent 是否真的执行了元规则 |
| 错题本修订记录(revision) | RULE 事件:条目增长曲线 |
| 用户反馈 | 用户纠正 = 最高质量的沉淀信号(前置,非报错) |
scripts/wrongbook-audit.py(2026-09-02 新增) |
扫日志统计 PREFLIGHT(核对) 次数 Y vs 工具调用次数 X;核对率 = Y/X;提取 exposure 计数 |
## 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 绝对数)
- 结论:本周期验证了什么 / 机制哪里失效 / 下一步- 错题本(
self-improvement-lessons):9 条禁则 - 命中数:0(记录尚未开始)
- 已知复发 0 次
- 常驻成本实测:全局 REASONIX.md 12 行 ≈ 每轮 <60 token
⚠️ 诚实声明:在本文件建立之前的所有"真实案例"都是一次性叙事,不构成验证数据。 从 2026-08-06 起按本协议记录的数据,才可作为 README 中的验证 claim。