docs(design): 修订 — 标签保鲜不该依赖 git,改为「前一状态」provider 分层

用户反驳成立:不是所有开发都用 git,依赖 git 不是好设计。三条理由:
1. 环境覆盖不到:沙箱 allow_exec=false(src/host/sandbox_fs.rs:378)文档内调不了 git;
   浏览器 WASM(wasm32)无进程能力;单文件/zip 工件无 .git;非 git 用户无从使用
2. 语言不该绑定 VCS:把语义正确性外包给"某工具目录是否存在"
3. 最要命的:最高价值场景(agent 修复回路)恰在不能调 git 的环境里

修订方案:保住 M5 的**原则**(变更驱动而非扫描驱动),把"前一状态"抽象为 provider:
判定逻辑只有一份 stale ⟺ fingerprint(()) 变 ∧ label 未变;变的只是 prev 从哪来。

四层能力:
- T0 引用一致性(零依赖,纯文档)——查引用腐烂
- T1 会话内前后对照(零依赖,最高性价比)——repair_apply / view 保存 / 编辑器钩子 / agent diff
- T2 外部历史源(可选,git/hg/svn 适配器)——跨会话漂移
- T3 台账(可选,.marqdo/labels.json)——无 VCS 时的持久化 + 确认状态

环境能力矩阵:CLI+git / CLI 无 VCS / agent 沙箱 / 浏览器 WASM / 单文件 / 对象存储,
**没有一行全 ❌**——T0+T1 在所有环境成立,足以支撑"agent 改动即时提醒"。

最关键一条:repair_apply 已同时持有 before(source) 与 after(应用 edits 后),
所以建议协议加一个可选 base_code / check_labels 字段,Marqdo 在同一次调用内即可算出
"哪些标签的 () 指纹变了而 [] 没变",返回带 code_past / code_now 的 stale 列表。
零外部状态、零依赖、零 git——而这正是模型改完代码别忘了改描述的场景。

provider 五条硬规则:核心不依赖 / 缺失即静默降级(不报错不提示)/ 能力必须自述
(labels status 显示启用层级,避免"没报=没问题"的误判)/ 判定单一定义 / 不写进文档。

被否:强制 git、文档内嵌指纹、零宽字符、mtime 启发式、# noqa、静音清单。

同步修订 warning-fatigue-control.md:M5a 由"核心"降级为可选 T2 适配器,
补一条验收指标"provider 缺失时标签相关输出也必须为 0"。其余结论不受影响。

未改代码。附五项待决策(是否接受分层、T1 是否够、能力自述、T2 适配范围、T3 是否推迟)。
This commit is contained in:
cflmy committed 2026-10-22 13:49:03 +08:00
1 parent 0ac661eef2
commit 2c4dac005c
2 files changed
+231 -1

No files matched your search

+223
View File
@@ -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 的标签保鲜都成立,
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
+8 -1
View File
@@ -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 只在"`()` 变了、`[]` 没变"时报,且只针对本次变更集。**