docs(design): 防警告疲劳机制 — stale 必须是「变更报告」而非「扫描报告」
触发:用户指出 []() 每次报 warning 会导致烦躁与忽略,机制必须先定再开工。 一、为什么标签检查特别容易被忽视 高频(标签密度≈每个取值/调用)、主观(自然语言断言,机器只能近似)、 持续(代码天天改)。且实测基线是**零噪音**:lib/ + ext/ai/ 共 59 文件跑 check, warning=0、error=0 —— 标签校验会成为项目第一个持续警告源,一次就要做对。 二、疲劳的真正根因不是"报得多",而是「同一件已知的事被反复告知」。 目标改成三条硬约束:没有新信息就不说话 / 说了就能做点什么 / 说过的就不再重复。 三、六个机制评估 M1 分级(按证据强度:error=能证明断裂,warning=能证明变化但不知谁错,hint=弱信号) M2 聚合(check 人类输出最多一行,细节进 --json / view / labels) M3 基线(bootstrap 静默吸收,用于迁移后的存量) M4 确认即静默(ack 台账,同指纹不再报) M5 **结构化 diff(推荐核心)**:stale 只在「() 变了 ∧ [] 没变 ∧ 在本次变更集」时报 M6 文档内抑制 # noqa —— **否决**(污染文档、不可审计、会永久化;抑制只放台账/配置) 四、M5 的性质(这是把疲劳问题降级的关键) 零台账(git 即台账,无新文件/无合并冲突)、零基线(首次也安静)、 零重复(提交后 diff 清空报告即消失)、天生带 before/after(正好是 LLM 复核输入)、 格式化免疫(比 AST 指纹而非文本)。非 git 环境降级为 L1,仍安静。 五、推荐组合 默认:M5a + 默认 hint + check 最多一行 + 每条带定位/before-after/建议 + 变更集去重 + 非 git 降级 严格模式(知识库仓 opt-in):升 warning/error + 基线与确认台账 + **棘轮(允许存量、禁止新增)** + labels status 进 CI。棘轮是最值得抄的机制:老债不阻塞、新债立刻拦、债务数字可下降。 六、确认的三种语义:改标签 / 改代码 / 显式确认。 建议三者都提供,但显式确认留痕(confirmed_by + 次数)——**被反复确认的标签本身是坏味道**。 七、可证伪原则:只有能被证伪的断言才被检查。标签含反引号实体→参与 L1;纯口语→L1 不检查。 检查成本由书写具体程度决定,同时反向抑制"为凑数写废话"。 八、agent 节流:只对它自己刚改到的标签做检查,每轮一次,超 N 条只报前 N+汇总。 模型看到的是"你刚改的这处描述可能不成立",而不是"全仓库 200 处过期"。 九、防「用忽视解决」三道闸:债务可见(labels status 给数字)、可 gate(error)、 可审计抑制(labels audit + 过期抑制提示)。 十、验收指标(写进文档防走样):无变更时标签相关输出=0;单变更集提示≤3 或≤20%; 重复=0;可行动率 100%;误报≤10%;check 人类输出≤1 行;hint/warning 不影响退出码。 未改代码。附五项待决策(核心机制、默认级别、棘轮、确认留痕、check 聚合行是否常显)。
This commit is contained in:
1 parent
1dd74578b5
commit
0ac661eef2
1 file changed
+254
@@ -0,0 +1,254 @@
|
||||
# 防警告疲劳:标签校验必须自带的「静默机制」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Proposed · 开工前必须先定**(未改代码) |
|
||||
| 日期 | 2026-10-22 |
|
||||
| 触发 | 用户:`[]()` 每次报 warning 会导致烦躁与忽略,必须先有机制再开工 |
|
||||
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) |
|
||||
| 结论 | stale **不是"扫描报告",而是"变更报告"**;默认零噪音,严格模式 opt-in |
|
||||
|
||||
---
|
||||
|
||||
## 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(**推荐作为核心**)
|
||||
|
||||
> **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 条警告。
|
||||
Reference in new issue
Block a user