diff --git a/doc/design/staleness-providers.md b/doc/design/staleness-providers.md new file mode 100644 index 0000000..8f58b23 --- /dev/null +++ b/doc/design/staleness-providers.md @@ -0,0 +1,223 @@ +# 修订:变更检测不该依赖 git —— 「前一状态」的 provider 分层 + +| | | +|---|---| +| 状态 | **Proposed · 修订**(取代 [warning-fatigue-control.md](warning-fatigue-control.md) §2 的 M5a) | +| 日期 | 2026-10-22 | +| 触发 | 用户:不是所有开发都用 git,依赖 git 是否是好设计 | +| 结论 | **不是好设计**。保住「变更驱动」原则,把「前一状态」抽象为可插拔 provider;核心能力零依赖 | +| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) | + +--- + +## 0. 直接回答:不该依赖 git + +三条理由,一条比一条硬: + +### 0.1 环境覆盖不到 + +| 环境 | 能调 git 吗 | 依据 | +|------|------------|------| +| 浏览器 WASM | ❌ | `marqdo-wasm`(wasm32-unknown-unknown),无进程能力 | +| **沙箱内执行** | ❌ | `src/host/sandbox_fs.rs`:`allow_exec: false` | +| 单文件分发 / zip 工件 | ❌ | 没有 `.git` | +| CI 容器(浅克隆/无 VCS) | ⚠️ 常常没有 | 取决于流水线 | +| 非 git 用户(hg / svn / fossil / 无) | ❌ 或需另写适配 | — | + +### 0.2 语言不该绑定某个 VCS + +Marqdo 是**语言与运行时**。把"断言是否过期"的判定建立在"某个工具的目录是否存在"上, +等于把语言的语义正确性外包给环境。今天 git 是主流,明天不是;语言不能跟着换。 + +### 0.3 最要命的:最重要的消费者恰在不能调 git 的地方 + +标签过期检测的**最高价值场景**是 agent 修复回路—— +模型改了代码,Marqdo 提醒它"你改的这处描述可能不成立了"。 + +而这个回路: +- 常在沙箱里跑(`exec=false`,**调不了 git**) +- 编辑目标是内存中的文本(`repair_apply` 的 `source`),不一定落在 git 工作区 + +**如果核心机制依赖 git,那它恰好在最需要它的地方失灵。** 这是设计错误的铁证。 + +--- + +## 1. 但 M5 的原则要保住 + +上一份文档的 M5 有两个部分,必须分开看: + +| 部分 | 判定 | +|------|------| +| **原则**:stale 是"变更报告",不是"扫描报告"(没有新信息就不说话) | ✅ **保留**,这是防疲劳的根 | +| **实现**:用 `git diff` 提供"前一状态" | ❌ **降级为可选 provider** | + +也就是说: + +> **判定逻辑只有一份:`stale ⟺ fingerprint(()) 变了 ∧ label 没变`。 +> 变的只是「前一个 `()` 从哪来」。** + +这一步抽象之后,git 只是**四种来源之一**。 + +--- + +## 2. 四层能力(provider 分层) + +### T0 — 引用一致性(零依赖,永远可用) + +纯文档分析:标签里的 `` `实体` `` 必须可解析、且出现在 `()` 中。 + +- 需要:只读当前文件(甚至只需文本) +- 能力:查**引用腐烂**(改名、删除、错引) +- 查不了:语义腐烂(`*` 改 `/`) + +### T1 — 会话内前后对照(零依赖,最高性价比) + +**任何"编辑前 + 编辑后"都在手的场合**都能算 stale: + +| 场合 | 前一状态从哪来 | +|------|---------------| +| `MLSP repair_apply` | 调用方传入的 `source` + `edits` → 前/后两版都在内存里 | +| `view`(保存后检查) | 保存前的模块 AST | +| 编辑器保存钩子 | 编辑器持有的旧缓冲 | +| agent 的 diff | 它自己的编辑集 | + +**关键**:只看「本次会话改了哪些标签的 `()` 且没改 `[]`」。 +天然变更驱动、天然零台账、天然带 before/after——**而且不需要 git**。 + +### T2 — 外部历史源(可选,自动探测) + +`git` / `hg` / `svn` / 任意"能取到上一版文件内容"的适配器。 + +- 检测:工作区存在 `.git` / `.hg` 且二进制可用 +- 用途:**跨会话**漂移(昨天改了代码,今天才检查) +- 缺失时:**静默关闭**,不报错、不提示、不产生噪音 + +### T3 — 台账(可选,无 VCS 时的持久化) + +`.marqdo/labels.json`:`{标签键 → {code_fingerprint, code_quote, confirmed_at}}` + +- 用途:没有 VCS 的环境(沙箱长期任务、编辑器插件)+ 严格模式的"确认"状态 +- 语义:**可丢弃缓存**(删了重建,最多一次全量确认) +- 已知代价:合并冲突、需要 bootstrap(因此作为 opt-in,不做默认) + +--- + +## 3. 环境能力矩阵 + +| 环境 | T0 引用 | T1 会话内 | T2 历史源 | T3 台账 | +|------|--------|----------|----------|--------| +| CLI + git 仓库 | ✅ | ✅ | ✅ | ✅ | +| CLI + hg/svn(有适配) | ✅ | ✅ | ✅ | ✅ | +| CLI 无 VCS | ✅ | ✅ | ❌ | ✅ | +| **agent 沙箱(exec=false)** | ✅ | ✅ | ❌ | ⚠️ CoW 内可写但不持久 | +| **浏览器 WASM** | ✅ | ✅ | ❌ | ❌ 无持久 fs | +| 单文件 / zip 工件 | ✅ | ✅ | ❌ | ❌ | +| 数据库/对象存储里的 `.mq.md` | ✅ | ✅ | ❌ | 由宿主提供 | + +**读法**:矩阵里**没有一行全 ❌**。T0+T1 在所有环境都成立—— +这两层就足以支撑"agent 改动即时提醒"这个最高价值场景。 + +--- + +## 4. 各层的能力边界(必须诚实) + +| 层 | 能查 | 查不了 | +|----|------|--------| +| T0 | 引用了不存在的实体;引用的实体不在语句里 | 语义腐烂(乘改除) | +| T1 | **本次会话内**的 `()` 变化 | 跨天/跨机器的漂移 | +| T2 | 跨会话、跨机器的漂移(若 VCS 有历史) | 未提交历史之外的变化;跨仓库移动 | +| T3 | 持久化的漂移(若台账被维护) | 台账未覆盖的标签;合并后需重算 | + +**组合起来的语义**: +- 有 T2 → 严格(能查历史) +- 只有 T0+T1 → **会话级严格**(够 agent 用) +- 什么都没有(WASM 首次打开) → 只查引用(T0),且**明确告知能力级别** + +--- + +## 5. 最关键的一条:agent 回路不需要任何 VCS + +`MLSP repair_apply` 的参数里**已经同时有前后两版**: + +```rust +// src/mlsp.rs:repair_apply 收到 source + ranges + edits +let source = source_text(params)?; +// → 应用 edits 得到 after +``` + +所以只要给协议补一个字段 `base_code`(或让 `repair_apply` 自己在内部保留 before), +Marqdo 就能在**同一次调用内**算出: + +> 哪些标签的 `()` 指纹变了、而 `[]` 没变 → 输出 stale 提示。 + +**零外部状态、零依赖、零 git。** 而这正是"模型改了代码别忘了改描述"的场景。 + +**具体协议建议**(只需一个可选字段): + +```json +{ "method": "repair_apply", + "params": { "source": "…", "ranges": [[42,42]], "edits": [...], + "check_labels": true } } +``` + +返回里附: + +```json +{ "labels": [{ "stale": 1, "items": [{ "text": "按 `税率` 计算总价", + "code_past": "…* 金额", "code_now": "…/ 金额", "span": {...} }] }] } +``` + +这样 agent 每轮只看到**自己刚弄脏的那几条**,且带前后对照。 + +--- + +## 6. provider 契约(五条硬规则) + +1. **核心不依赖**:T0/T1 必须在任何环境可用,不得引入 provider 前置条件。 +2. **缺失即降级**:provider 不可用 → 静默关闭该层能力,**绝不报错、绝不提示**。 +3. **能力必须自述**:`labels status` 必须显示"当前启用 T0/T1/T2/T3 中的哪些"。 + ——否则用户会误以为"没报 = 没问题",这是比噪音更坏的失败。 +4. **判定单一定义**:`stale` 的定义只有一处实现;provider 只提供 `prev`,不参与判定。 + ——否则不同环境会给出不同结论,语言就没有统一语义了。 +5. **不写进文档**:provider 的状态、指纹、抑制**一律不进 `.mq.md`**。 + 文档里只允许有人的语言与代码。 + +> 第 3 条是我这次最想强调的:**宁可少报,也不能假装"检查过了"。** + +--- + +## 7. 被否决的方案 + +| 方案 | 否决理由 | +|------|---------| +| **强制 git 作为核心** | 环境覆盖不到(§0.1);语言绑定 VCS(§0.2);最关键场景失灵(§0.3) | +| 文档内嵌指纹 | 污染文档;作者一改就失效;与"文档即散文"冲突 | +| 零宽字符隐藏指纹 | 不可见 = 不可审计;复制粘贴即损坏;工具链噩梦 | +| mtime 启发式 | 不可靠(checkout、touch、云同步都会变) | +| `# noqa` 抑制 | 已否(污染 + 不可审计 + 会永久化) | +| 只做全量扫描 + 静音清单 | 静音清单就是台账,且首次即爆炸 | + +--- + +## 8. 对上一份文档的修订 + +| 原条目 | 修订后 | +|--------|--------| +| M5a「git 结构化 diff」为核心机制 | 降级为 **T2 的一个适配器**;核心改为 **T0 + T1** | +| 严格模式依赖台账 | 严格模式 = 任意 T2 **或** T3 可用即可;无 provider 时按 T0/T1 运行 | +| 验收指标「无变更时输出 = 0」 | 保留,且补一条:**provider 缺失时也必须为 0,并在 `labels status` 里说明** | + +--- + +## 9. 待你决策 + +1. **接受「T0+T1 为核心,T2/T3 可选」这个分层吗?** +2. **T1 是否足够**作为 agent 回路的默认能力?(我认为够——它覆盖了"刚改完"这个主场景) +3. **能力自述**要不要做成 `labels status` 的固定输出 + (含"本次无法检测历史漂移"这类明确提示)? +4. **T2 的适配范围**:只做 git,还是留一个通用接口(返回"某文件的上一版文本")由宿主实现? +5. **T3 台账**是否推迟到有明确需求再做?(我建议推迟——先把 T0+T1 做扎实) + +> 我的建议:**先只做 T0 + T1**,把「变更驱动 + 零依赖 + 能力自述」这条骨架立住。 +> 这样无论用户在 git、hg、WASM 还是沙箱里,Marqdo 的标签保鲜都成立, +> 只是"能看多远"不同——而这一点会被明确告知,不会假装。 diff --git a/doc/design/warning-fatigue-control.md b/doc/design/warning-fatigue-control.md index 39243bf..7e4d946 100644 --- a/doc/design/warning-fatigue-control.md +++ b/doc/design/warning-fatigue-control.md @@ -8,6 +8,13 @@ | 前置 | [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 更容易被忽视 @@ -81,7 +88,7 @@ contract check OK(另有 3 条标签提示,见 marqdo labels status --json 对某个「标签 + `()` 指纹」组合确认后,记录 `confirmed` → 同样的组合不再报。 这是最直接的对症药:**说过的就不再说**。 -### M5 结构化 diff(**推荐作为核心**) +### M5 结构化 diff(**已修订:降级为可选 provider T2**,见 [staleness-providers.md](staleness-providers.md)) > **stale 只在"`()` 变了、`[]` 没变"时报,且只针对本次变更集。**