Files
marqdo/doc/design/label-freshness-and-repair.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

17 KiB
Executable File
Raw Permalink Blame History

纯度路线细化 + 标签过期检测:面向可执行知识体系的一致性机制

状态 Accepted(含语法落地、诊断 schema、分阶段计划)
日期 2026-10-22
决策来源 用户:取纯度;标签可省略但编译器须报错;循环写法不重要;重点:标签过期与 agent 误导
前置 bracket-as-label-evaluation.md
依托设施 src/diagnostics.rs(doc_anchor/doc_quote/contract_ref)· src/mlsp.rs(validate/repair_targets/repair_apply)· src/repair.rs(有界修复)· src/knowledge/fingerprint.rs · src/knowledge/lifecycle.rs(已有 find_stale)

0. 决策记录与一个推论

已定:

  1. 纯度:() 只装机器语句,[] 只装人话;取元搬进 ()。
  2. 标签可省略,但编译器报错:写空方括号是可能的,但那是一个错误。
  3. 循环写法从简:[] 已是描述,() 内部只要自洽即可。

由此得到一个必须先说清的推论:

纯度强制两件东西同时存在: ① 一个不带标签的普通表达式写法(否则每个访问都被迫配一段人话 = 仪式感复辟); ② 带标签的形式作为一个可选包装。

也就是说 [标签](表达式) 不是"唯一的表达式语法",而是"当你想做断言时才用的包装"。 这一条同时解决了我在上一份文档里担心的"标签凑数"退化: 不想断言,就别用这个形式——而不是"必须写标签但可以写废话"。


1. 纯度路线下的语法落地

1.1 形式

带标签表达式 ::= '[' 人话 ']' '(' 表达式 ')'
  • 表达式 = 现有 Marqdo 表达式文法(不新增语言)
  • 人话 = 任意自然语言,必须是关于这个值的断言(§2)
  • 出现位置:表达式位置、语句位置、循环位置

1.2 关键缺口:普通取元怎么写

纯度之后 [键](集合) 不再是取元,所以必须给出不带标签的取元写法。四个候选:

方案 写法 优 劣
A 现有内建 [第一项](at value=篮子 index=1) 零新语法,今天就能实现 啰嗦;value=/index= 是机器腔
B 后置方括号 [第一项](篮子[1]) 最像通用语言;篮子[拿铁] 读起来自然 [] 出现两种角色(前置=人话,后置=索引),视觉易混
C 函数式 + 逗号参数 [第一项](at(篮子, 1)) 与 加一函数(31) 统一;顺带解决前几轮想要的 f(args) 需支持逗号分隔实参(要改参数分词器)
D 点号 [拿铁价格](菜单.拿铁) 短 与库路径 txt.str_trim、对象方法 obj.m 三者同形

我的建议:C。

理由:你前面想要 f(args) 这种"人读友好"的调用,而 C 与它同一个改动—— 一次性把 () 内的表达式升级为「可带括号实参」的形式, at(篮子, 1)、加一函数(31)、get(菜单, 拿铁) 全部成立,且不新增第二种方括号角色。 代价是参数分词器要支持 ) 终止与逗号(前几轮原型已验证方向可行,全量 554/0 回归)。

若你希望零实现风险,选 A:今天就能用,只是啰嗦,后续可再收窄成 C。

1.3 空标签 = 硬错误

[](at(篮子, 1))        # ❌ label.missing

诊断:code: "label.missing",severity: error,doc_quote: "[]",建议: 「给这段语句写一句人话描述,或改用不带标签的普通表达式」。

这一条是整套设计的门槛:它把"标签"从可选装饰变成"用了就得负责"的承诺。 也正好落实你说的「可以省略,但编译器应当报错」。

1.4 循环

你说不重要,那我给最省事、且与纯度一致的一条:

- [从篮子取出的每个果子](foreach 篮子 为 果)
  • [] 是描述(人读)
  • () 是机器语句:遍历什么、绑定给谁
  • 循环变量名从 [] 搬进 ()——因为 [] 不再承担绑定职责

若嫌 foreach 篮子 为 果 太新,可就近用现有词: - [从篮子取出的每个果子](遍历 篮子 绑定 果)。 关键是别再让 [] 兼任变量名——否则"描述"与"标识符"又会打架。


2. 标签是什么:可校验断言的载体

标签不是注释。三者区别:

注释 标签
位置 游离于代码之外 锚定在 AST 节点上(有 span,可定位)
可核验 不能 能(§3)
可进修复协议 不能 能(随诊断导出给 LLM)
变更感知 无 能(代码变了会撞上旧断言)

一句话:标签 = 贴在可执行片段上、可被机器复核的断言。 这正是 Marqdo 相对传统"文档 + 注释"的核心增量。


3. 过期检测:三层机制

你问的核心是:() 改了,怎么让 [] 的旧描述"叫起来"。 这需要三种能力,缺一不可,且分属不同层。

3.1 L1 引用一致性(无状态、确定性、零成本)

规则:标签内用反引号写出的名字 = 实体断言。

[按 `税率` 计算总价](...)

可核验的断言:

  1. `税率` 必须可解析(在当前作用域/模块里存在)
  2. 它必须出现在 () 的实际内容中(或经调用链可达)

任一条不成立 → label.stale(引用已腐烂)。

为什么低假阳性:只有显式反引号才算断言,普通汉字不参与判定。 这复用了 Marqdo 已有的 `名` = 实体 的约定,没有新增记号。

局限(必须承认):它只查"引用",查不出"语义"。 税率 还在,但操作从"乘"改成"除",L1 看不见。

3.2 L2 指纹台账(有状态、能查语义腐烂)

做法:把「标签写下时,它描述的那段代码」记一份指纹。

.marqdo/labels.json(与 EKC 产物同目录,视为缓存):

{
  "按税率计算总价#1": {
    "code_fingerprint": "9f2a…",
    "code_quote": "at(税率表, 档位) * 金额",
    "confirmed_at": "2026-10-22T09:00:00Z"
  }
}
  • code_fingerprint:复用 src/knowledge/fingerprint.rs(已有 collect_calls / ops_hint / fingerprint_hash) → 调用与运算变了,指纹就变
  • code_quote:旧代码的文本快照——这就是你说的"保留内容用于校验"的对称物: doc_quote 保留 [],code_quote 保留 (),两者一起导出给 LLM 对比
  • 键 = 规范化标签文本 + 同文本序号(按标签键而不是按行号,移动代码不会误报)

命中规则:

变化 判定
() 指纹变 stale:标签描述的代码已变,需复核
标签文本变 新断言:无历史,首次确认即可
两者都没变 通过

局限:需要状态文件;合并冲突要处理(§8.2)。

3.3 L3 LLM 复核(修复协议闭环)

诊断被导出时同时携带三方信息:

  • doc_quote:[] 里的原话
  • code_past:() 当时的文本(来自台账)
  • code_now:() 现在的文本

模型据此判定三选一:

  1. 改标签(代码意图是对的,描述过期了)
  2. 改代码(描述是对的,实现跑偏了)
  3. 确认无害(改动不影响断言,写回台账 confirmed)

这正好接进已有的修复回路(src/repair.rs):validate → repair_targets → 模型行编辑 → repair_apply(越界必拒)→ 复验。

3.4 为什么三层都要

层 查什么 能否查"乘改除" 需要状态 假阳性
L1 引用腐烂(改名/删除) ❌ 无 极低
L2 语义腐烂(同引用、不同操作) ✅ 需台账 中(无害改动也报)
L3 谁错了(标签 or 代码) ✅ 复用 L2 由模型判

L1 是地基(确定性、零成本、可先上),L2 是覆盖(能查语义),L3 是裁决(谁改)。


4. 与现有设施的对接(这决定了落地成本)

4.1 诊断字段:已经齐备,不需要新造

src/diagnostics.rs 的 to_json 已输出:

{
  "code": "…", "severity": "…", "message": "…",
  "span": {"file":…, "line":…, "col":…},
  "doc_anchor": …,      ← 标签位置
  "doc_quote": …,       ← 标签原文
  "contract_ref": {"unit":…, "kind":…, "name":…, "declared":…},
  "suggestion": …
}

contract_ref.declared 就是"声明"这一侧的先例: 契约诊断说的是「declared number,actual text」, 标签诊断说的是「declared(标签里的人话),actual(() 现在的代码)」—— 同一个模式,只是从类型层下沉到散文层。

这也回答了你的问题:"导出时能否保留 [] 的内容用于校验"—— 能,而且字段已经在协议里了:doc_quote 就是它。

4.2 契约诊断是现成的范式

src/contract.rs:203 的 Contract::diagnostic(...) 一次性装配 code + severity + suggestion + doc_anchor + doc_quote + contract_ref。 标签诊断可以照抄这套装配,只是 kind 从 "contract" 换成 "label"。

4.3 修复范围:允许"标签行 ∪ 代码行"

现在 repair_apply 的形状是 ranges: [[起, 止], …],天然支持多个区间。 label.stale 只需把两段都放进 ranges:

允许范围 原因
标签所在行 修法 1:改描述
() 所在行 修法 2:改实现

护栏不变:越界改动一律拒绝(abstain)——这正是 src/repair.rs 已经强制的语义。

4.4 知识层:stale 概念已经存在

src/knowledge/lifecycle.rs 已有 find_stale / stale_json / verify。 标签过期可以走同一条 stale 通道,进入 EKC/OKF 的 marqdo verify / marqdo stale 报告,成为知识库的健康指标。

这一点很重要:标签过期 = 知识腐烂,而 Marqdo 已经有"知识会腐烂"的机制, 标签只是给它增加了一种新的腐烂类型(文档断言 vs 实现)。


5. 诊断 schema 草案

{
  "code": "label.stale",
  "severity": "warning",
  "message": "标签可能过期:标签提到 `税率`,但当前语句已不再引用它",
  "span": { "file": "报价.mq.md", "line": 42, "col": 12 },
  "doc_anchor": { "file": "报价.mq.md", "line": 42, "quote": "按 `税率` 计算总价" },
  "doc_quote": "按 `税率` 计算总价",
  "label_ref": {
    "kind": "label",
    "text": "按 `税率` 计算总价",
    "refs": ["税率"],
    "missing_refs": ["税率"],
    "code_past": "at(税率表, 档位) * 金额",
    "code_now": "at(税率表, 档位) / 金额",
    "fingerprint_past": "9f2a…",
    "fingerprint_now": "3c71…",
    "layer": "L2"
  },
  "suggestion": "若意图是乘,请还原 `*`;若意图改为除,请把标签改成「按档位折算比例」",
  "ranges": [[42, 42]]
}

要点:

  • 复用 doc_anchor / doc_quote,不新造字段名
  • label_ref 仿 contract_ref(kind: "label")
  • code_past / code_now 并置 → 模型一眼看出差异
  • layer 标明是 L1 还是 L2 检出(便于分级治理)

6. 工作流

作者 / agent 改代码
      ↓
marqdo check  或  MLSP validate
      ↓
label.stale / label.missing 诊断(带 doc_quote + code_past + code_now)
      ↓
MLSP repair_targets(ranges = 标签行 ∪ 代码行)
      ↓
LLM 三选一:改标签 / 改代码 / 确认无害
      ↓
repair_apply(越界必拒)
      ↓
复验 → 通过后写回 .marqdo/labels.json(confirmed_fingerprint 更新)

CI 用法:

  • 普通项目:label.stale 默认 warning(不阻塞)
  • 知识库项目(OKF/EKC 仓):可配置为 error,把"断言必须新鲜"作为门禁

7. 反幻觉:这一步到底解决了什么

必须把话说准,否则容易过度承诺。

7.1 它解决的具体一类

文档断言与实现不一致(doc–code drift at the claim level)。

传统文档的失败模式:

失败模式 传统文档 Marqdo(本设计)
注释过期 无声腐烂 L1/L2 检出
签名漂移 靠类型检查(有) 契约已有
散文描述与实现不符 完全无解 本设计(新能力)
知识库引用失效 靠人工审阅 可机械化

7.2 它不解决什么

  • 模型凭空编造(幻觉的另一种)
  • 代码本身写错
  • 标签写得含糊但"不算错"(L1 查不到,L2 只能报"变了")

所以正确的表述是:

它把"文档可信度"从"靠人自觉"提升到"可被机械复核 + 可被 LLM 裁决"。

7.3 为什么这对"可执行知识体系"是决定性的

一个知识库的价值 = 断言的密度 × 断言的可信度。 传统知识库只能提高密度(多写),无法保证可信度(写完就腐)。 Marqdo 若能把"断言→复核"闭环,就第一次让知识库有了保鲜机制—— 这也正好接上 EKC 已有的 stale / verify 体系。


8. 风险与反对意见(诚实清单)

8.1 误报疲劳(最危险)

如果 label.stale 天天响,用户会在三天内学会忽略它。 对策:

  • L1 只在能证明冲突时报(引用了不存在的实体 / 引用的实体不在语句里)
  • L2 默认只报 warning,且同一标签同一指纹只报一次(台账记录"已复核")
  • 诊断里必须给可执行建议(改哪一行、改成什么),否则就是噪音

8.2 台账的腐烂与合并冲突

.marqdo/labels.json 是缓存,不是真相。对策:

  • 语义上可丢弃:删掉后重建,最多一次全量确认
  • 合并冲突策略:重算优先(以代码指纹为准,冲突时保留 confirmed_at 较新者)
  • 不放进版本库时(.gitignore),退化为"本地提示";放进版本库时,成为团队级门禁

8.3 语义鸿沟

L1 只能查引用;标签写"算总价"而代码改成了"算单价",若两者都引用 税率,L1 沉默。 这是 L2 存在的理由,也是必须承认的能力边界。

8.4 LLM 修标签可能引入新幻觉

"用幻觉修幻觉"是真风险。对策:

  • 护栏:只允许改标签行或代码行(repair_apply 已强制)
  • 修改必须双向可逆:诊断里给出"过去/现在"两侧,让模型做判定而不是创作
  • 知识库仓建议:L2 级修改需人工确认(--confirm)

8.5 标签不得参与安全判定

这是我在上一份文档里提的、也是你关心的"agent 误导"的另一面: 如果沙箱/权限判定读标签,那标签就成了攻击面。 硬约束:策略、沙箱、工具白名单只读 () 的语义,永不读 []。 标签只服务于"人读"与"AI 复核",不服务于"机器授权"。

8.6 成本

每标签一次指纹计算与比对。可增量:只对本次变更的文件做 L2 校验 (与 EKC 的增量编译一致)。


9. 分阶段落地

阶段 内容 依赖 风险
P0 纯度语法:[标签](表达式) + label.missing + 普通取元(A 或 C) 解析器 中(506 处迁移)
P1 L1 引用一致性 + label.stale 诊断(无状态) 诊断字段已有 低
P2 诊断 schema + MLSP ranges 并集 + 修复回路 mlsp.rs / repair.rs 低
P3 L2 指纹台账 + 增量校验 fingerprint.rs 中
P4 L3 LLM 复核 + confirmed 写回 + CI 门禁 P2+P3 中

建议先做 P1:它零状态、确定性、能立刻抓住"引用了不存在的东西"这类最硬的腐烂, 且不依赖纯度迁移——可以在旧语法上先验证"标签断言"这个概念是否好用。


10. 待你决策

  1. 普通取元选 A(at value=… index=…,零新语法)还是 C(at(篮子, 1),需逗号参数)?
  2. L1 的断言规则:只认标签内的反引号 `名`,还是也认"与代码标识符同名"的中文词? (只认反引号更准;认中文词更聪明但假阳性高)
  3. 台账位置:.marqdo/labels.json(默认忽略)还是纳入版本库(团队门禁)?
  4. label.stale 默认级别:warning(推荐)还是 error?
  5. 是否先只做 P1(在旧语法上验证"标签断言"概念),再决定纯度迁移?

我的建议顺序:P1 → P2 → P0 → P3 → P4。 先在旧语法上把"断言 + 复核 + 修复回路"这条链路跑通(它不依赖纯度), 再动 506 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。