Files
marqdo/doc/design/warning-fatigue-control.md
cflmy 8926f7bed6 docs(design): M0 语义冻结 — 遮蔽语法系列文档标记 Accepted
用户已批准:内置词表先按现方案(六组、两级检索),后续可调。
本提交只改文档状态,不动代码:

- occlusion-syntax.md:Proposed → Accepted · 实施中(M0 起)
- occlusion-description-and-search.md:Proposed → Accepted · 实施中
- warning-fatigue-control.md:Proposed → Accepted(机制基线:stale 是变更报告)
- staleness-providers.md:Proposed → Accepted · 修订
- t1-session-staleness.md:Proposed → Accepted · 机制说明
- label-freshness-and-repair.md:Proposed → Accepted

后续按 M1 → M2 → M2.5 → M4 → M9 → M10 → M6 → M5 → M3 → M7 → M8 逐步落地。
2026-10-22 15:03:26 +08:00

262 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 防警告疲劳:标签校验必须自带的「静默机制」
| | |
|---|---|
| 状态 | **Accepted**(机制基线:stale 是变更报告) |
| 日期 | 2026-10-22 |
| 触发 | 用户:`[]()` 每次报 warning 会导致烦躁与忽略,必须先有机制再开工 |
| 前置 | [label-freshness-and-repair.md](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](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](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 条警告。