- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
9.4 KiB
Executable File
修订:变更检测不该依赖 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 契约(五条硬规则)
- 核心不依赖:T0/T1 必须在任何环境可用,不得引入 provider 前置条件。
- 缺失即降级:provider 不可用 → 静默关闭该层能力,绝不报错、绝不提示。
- 能力必须自述:
labels status必须显示"当前启用 T0/T1/T2/T3 中的哪些"。 ——否则用户会误以为"没报 = 没问题",这是比噪音更坏的失败。 - 判定单一定义:
stale的定义只有一处实现;provider 只提供prev,不参与判定。 ——否则不同环境会给出不同结论,语言就没有统一语义了。 - 不写进文档: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. 待你决策
- 接受「T0+T1 为核心,T2/T3 可选」这个分层吗?
- T1 是否足够作为 agent 回路的默认能力?(我认为够——它覆盖了"刚改完"这个主场景)
- 能力自述要不要做成
labels status的固定输出 (含"本次无法检测历史漂移"这类明确提示)? - T2 的适配范围:只做 git,还是留一个通用接口(返回"某文件的上一版文本")由宿主实现?
- T3 台账是否推迟到有明确需求再做?(我建议推迟——先把 T0+T1 做扎实)
我的建议:先只做 T0 + T1,把「变更驱动 + 零依赖 + 能力自述」这条骨架立住。 这样无论用户在 git、hg、WASM 还是沙箱里,Marqdo 的标签保鲜都成立, 只是"能看多远"不同——而这一点会被明确告知,不会假装。