- 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。
17 KiB
Executable File
纯度路线细化 + 标签过期检测:面向可执行知识体系的一致性机制
| 状态 | 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. 纯度路线下的语法落地
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 引用一致性(无状态、确定性、零成本)
规则:标签内用反引号写出的名字 = 实体断言。
[按 `税率` 计算总价](...)
可核验的断言:
`税率`必须可解析(在当前作用域/模块里存在)- 它必须出现在
()的实际内容中(或经调用链可达)
任一条不成立 → 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:()现在的文本
模型据此判定三选一:
- 改标签(代码意图是对的,描述过期了)
- 改代码(描述是对的,实现跑偏了)
- 确认无害(改动不影响断言,写回台账
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. 待你决策
- 普通取元选 A(
at value=… index=…,零新语法)还是 C(at(篮子, 1),需逗号参数)? - L1 的断言规则:只认标签内的反引号
`名`,还是也认"与代码标识符同名"的中文词? (只认反引号更准;认中文词更聪明但假阳性高) - 台账位置:
.marqdo/labels.json(默认忽略)还是纳入版本库(团队门禁)? label.stale默认级别:warning(推荐)还是 error?- 是否先只做 P1(在旧语法上验证"标签断言"概念),再决定纯度迁移?
我的建议顺序:P1 → P2 → P0 → P3 → P4。 先在旧语法上把"断言 + 复核 + 修复回路"这条链路跑通(它不依赖纯度), 再动 506 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。