Files
marqdo/doc/design/staleness-providers.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

9.4 KiB
Raw Permalink Blame History

修订:变更检测不该依赖 git —— 「前一状态」的 provider 分层

状态 Accepted · 修订(取代 warning-fatigue-control.md §2 的 M5a)
日期 2026-10-22
触发 用户:不是所有开发都用 git,依赖 git 是否是好设计
结论 不是好设计。保住「变更驱动」原则,把「前一状态」抽象为可插拔 provider;核心能力零依赖
前置 label-freshness-and-repair.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 的参数里已经同时有前后两版:

// src/mlsp.rs:repair_apply 收到 source + ranges + edits
let source = source_text(params)?;
// → 应用 edits 得到 after

所以只要给协议补一个字段 base_code(或让 repair_apply 自己在内部保留 before), Marqdo 就能在同一次调用内算出:

哪些标签的 () 指纹变了、而 [] 没变 → 输出 stale 提示。

零外部状态、零依赖、零 git。 而这正是"模型改了代码别忘了改描述"的场景。

具体协议建议(只需一个可选字段):

{ "method": "repair_apply",
  "params": { "source": "…", "ranges": [[42,42]], "edits": [...],
              "check_labels": true } }

返回里附:

{ "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 的标签保鲜都成立, 只是"能看多远"不同——而这一点会被明确告知,不会假装。