Files
marqdo/doc/design/warning-fatigue-control.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

11 KiB
Executable File
Raw Permalink Blame History

防警告疲劳:标签校验必须自带的「静默机制」

状态 Accepted(机制基线:stale 是变更报告)
日期 2026-10-22
触发 用户:[]() 每次报 warning 会导致烦躁与忽略,必须先有机制再开工
前置 label-freshness-and-repair.md
结论 stale 不是"扫描报告",而是"变更报告";默认零噪音,严格模式 opt-in

§2 的 M5 已修订:原文以 git diff 作为核心机制是错的——沙箱 exec=false 调不了 git、 浏览器 WASM 无进程能力、非 git 用户无从使用,而最需要它的 agent 修复回路恰在这些环境里。 现改为 「前一状态」provider 分层:T0 引用一致性 + T1 会话内前后对照 为核心(零依赖), T2 外部历史源(git 等) 与 T3 台账 为可选适配器。 见 staleness-providers.md。本文其余结论(分级、聚合、去重、 可证伪、节流、三道闸、验收指标)不受影响。


0. 为什么标签检查比一般 lint 更容易被忽视

三个结构性原因:

原因 说明
高频 纯度之后标签密度会接近"每个取值/调用一处"(现有索引 506 处 + 循环 44 处是下限)
主观 标签是自然语言,机器只能近似判断;报告天然带"可能"二字,说服力弱
持续 代码天天改,断言天天可能过期 → 报告是常驻背景音,不是一次性事件

而当前基线是零噪音:实测 lib/ + ext/ai/ 共 59 个文件跑 marqdo check, warning = 0、error = 0 (契约检查只在真错时报 error)。也就是说:

标签校验会成为这个项目第一个持续的警告源。 第一次引入就必须做对——一旦用户学会忽略,再想收回就晚了。


1. 疲劳的真正根因

不是"报得多",也不是"偶尔报错",而是:

同一件已知的事,被反复告知。

心理学上这叫 habituation:信号无新信息 → 大脑过滤 → 真警报也被过滤。

所以设计目标不是"少报",而是三条更硬的:

  1. 没有新信息就不说话(变化驱动,而非扫描驱动)
  2. 说了就必须能做点什么(可执行、有定位、有建议)
  3. 说过的就不再重复(确认即静默)

2. 六个候选机制与评估

M1 分级(hint / warning / error)

按证据强度分级,而不是按"我觉得重要":

级别 判据 人类可见 影响退出码
error 能证明断裂:引用了不存在的实体、空标签 label.missing ✅ ✅
warning 能证明变化,但无法判断谁错(L2 指纹漂移) ✅(默认聚合) ❌
hint 弱信号:标签提到的实体仍在,但不在当前语句 ❌(仅 JSON / view / labels) ❌

关键:默认级别取 hint,只有项目显式升档才进人类可见输出。 这让"默认安静"成为语言行为,而不是团队纪律。

M2 聚合(一条汇总,细节下沉)

check 的人类输出最多一行:

contract check OK(另有 3 条标签提示,见 marqdo labels status --json)

细节走 --json(机器)、view(徽章)、labels(逐条复核)。 理由:check 是 CI 工具,人很少逐条读;真正的阅读界面是 view 与编辑器。

M3 基线(bootstrap 静默吸收)

全量扫描第一次跑时只写台账、不报告,把存量债务吸收掉。 适用:从旧语法迁移到纯度之后的第一次。

M4 确认即静默(ack)

对某个「标签 + () 指纹」组合确认后,记录 confirmed → 同样的组合不再报。 这是最直接的对症药:说过的就不再说。

M5 结构化 diff(已修订:降级为可选 provider T2,见 staleness-providers.md)

stale 只在"() 变了、[] 没变"时报,且只针对本次变更集。

三种实现层次:

层次 做法 状态 噪音
M5a 工作区 vs HEAD:解析两版本文本,比较同一标签的 () AST 指纹 零状态 无变更即零
M5b 工作区 vs 「标签文本最后一次被修改的提交」(git blame 定位) 零状态 更精确,但依赖 blame 语义
M5c 台账比对(上一份文档的 L2) 需台账 中(首次需 bootstrap)

M5a 的性质非常关键:

  • 零台账:git 就是台账,不需要新文件、不会合并冲突
  • 零基线:不需要 bootstrap,第一次跑就安静(因为没变更)
  • 零重复:提交之后 diff 清空 → 报告自动消失(除非再次改到同一处)
  • 天生带 before/after:报告直接给旧代码与新代码,正好是 LLM 复核需要的输入
  • 格式化免疫:比较的是 AST 指纹,不是文本

边界:不在 git 仓库 / 无 git 时,M5 自动降级为「只做 L1 引用一致性」(仍然确定性、零噪音)。

M6 文档内抑制([描述](…) # noqa)—— 否决

理由:

  1. 污染文档:noqa 是机器垃圾,与"文档即散文"直接冲突
  2. 不可审计:抑制理由丢失,后来者不知道当初为什么不查
  3. 永久化:抑制会累积,最终整个文件静音

替代:抑制放台账/配置(可审计、可过期、可统计),不进文档。


3. 推荐组合:默认零噪音 + 严格模式 opt-in

3.1 默认(所有项目)

规则 效果
stale 只在 M5a(结构化 diff)时报 无变更 → 完全静默
默认级别 hint 不进 check 人类输出;仅 JSON / view
check 最多一行聚合 CI 日志干净
每条提示必须带:定位、doc_quote、code_past/code_now、一句可执行建议 可行动
同一标签在未处理前只报一次(按变更集去重) 不重复
非 git 环境降级为 L1 仍然安静

3.2 严格模式(知识库仓,opt-in)

在默认之上加:

规则 效果
stale 升为 warning 或 error 可作 CI gate
启用 M3 基线 + M4 确认台账 存量债务可管理
棘轮(ratchet):允许债务存在,但禁止增加 只拦新增,不清旧账
labels status 进 CI 报告 债务可见

棘轮是我认为最值得抄的机制:baseline.json 记 {"stale": 12}, labels check 只在 数量增加 时失败。这样:

  • 老债不阻塞任何人
  • 新债立刻被拦
  • 债务数字可下降,团队有正反馈

4. 「确认」的三种语义

M4 需要一个"确认"动作,三种可选:

语义 操作 优 劣
改标签 编辑 [] 文本 留下真实痕迹,最诚实 有时标签确实无需改
改代码 恢复 () 的行为 守住原意图 有时代码才是对的
显式确认 marqdo labels confirm <标签>,台账记新指纹 最省事 易被当成"消除警告按钮"

设计建议:三者都提供,但显式确认要留痕—— 台账记录 confirmed_at 与 confirmed_by(人或模型), labels status 能显示"这条被确认过几次"。 被反复确认的标签,本身就是坏味道(说明描述与实现长期脱节),值得在状态里暴露。


5. 可证伪原则:写得越具体,越接受检查

这条是从根上减少噪音的机制:

只有能被证伪的断言才被检查。

  • 标签含 `实体` 反引号 → 可证伪 → 参与 L1
  • 标签是纯口语("按档位折算")→ 不可证伪 → L1 完全不检查

于是检查成本由作者的书写具体程度决定: 写具体的作者获得更强的保鲜保证,也接受更多检查; 写笼统的作者不被检查(但也得不到保护)。

这不是漏洞,而是诚实的对齐:机器只能校验它看得懂的断言。 同时它反向抑制了"为凑数而写废话"——废话没人查,也就没有价值。


6. agent 侧节流:只问它自己刚改的

智能体是主要编辑者,最容易被警告淹没。规则:

场景 行为
一次 repair_apply 改了 () 只对它改到的那些标签做 stale 检查,最多 N 条(如 5)
未触碰的标签 一条都不报
同一修复轮内 只报一次,不随每次编辑重报
超过 N 条 只报前 N 条 + 汇总("另有 K 条")

这样模型每轮的输入里最多几条相关提示,且都带 before/after—— 它看到的是"你刚改的这处,描述可能不再成立",而不是"全仓库有 200 处过期"。


7. 防"用忽视解决"的三道闸

即使有静默机制,用户仍可能整体忽略。三道闸让它不可能"无声地"忽略:

  1. 债务可见:labels status 输出「12 条待复核 / 共 412 条标签」。 数字不报警,但每次问就给——忽略变成有意识的选择而非无意识。
  2. 可 gate:知识库仓把 stale 设为 error,CI 红。
  3. 可审计的抑制:抑制只存在于台账,labels audit 能列出所有抑制及其年龄。 超过 N 天未复核的抑制 → 提示"这条抑制过期了"。

8. 与现有设施的对接

现有 复用方式
marqdo check 增加一行聚合;细节不给
--json 诊断输出 hint 走这里,机器可读
MLSP validate 默认不含 hint,可传 labels: "strict" 打开
MLSP repair_targets / repair_apply ranges = 标签行 ∪ 代码行(已有能力)
marqdo view 标签徽章(新鲜 / 待复核);点击跳到标签与代码
marqdo verify / stale 复用已有的知识 stale 通道,进健康报告
新增 marqdo labels status / review / confirm / audit 四个子命令

9. 验收指标(可量化,写进文档以免日后走样)

上线前必须满足:

指标 目标
默认静默率 无代码变更时,check 输出中标签相关行 = 0
报告密度 单次变更集中标签提示 ≤ 3 条,或 ≤ 变更涉及标签数的 20%
重复率 同一标签在未修改前重复提示 = 0
可行动率 每条提示带定位 + before/after + 建议 = 100%
误报率 人工抽检 50 条,误报 ≤ 10%
默认可见性 check 人类输出最多 1 行;逐条只在 JSON / view / labels
退出码 hint / warning 不影响退出码

10. 待你决策

  1. 核心机制选 M5a(结构化 diff,零状态)吗? 我强烈建议选它——它把"疲劳"从设计问题降级为几乎不存在,且不需要台账。
  2. 默认级别:hint(我建议)还是 warning?
  3. 严格模式的棘轮(禁止新增、允许存量)要不要一并做?我建议要,成本很低。
  4. 显式确认要不要留痕(confirmed_by / 次数)?我建议要——反复确认的标签本身就是坏味道。
  5. check 的聚合行要不要固定出现("标签 0 待复核"也算信息)? 我建议不出现:零噪音优先,labels status 才回答这个问题。

定了这五条,我就可以按 P1(L1 + 诊断 + MLSP 往返)开工—— 因为 P1 只做"能证明断裂"的 error 与 hint,且天然走 M5 的变更口径, 不会在第一天就制造出 506 条警告。