# 遮蔽语法与可执行知识:一次以证据为准的复核 | | | |---|---| | 状态 | **Research · Open(待决策)** | | 日期 | 2026-10-23 | | 复核对象 | `marqdo 2.0.0`(`target/release/marqdo`,2026-10-22 提交 `bcfc763`) | | 触发 | 用户提出:`[]()` 遮蔽语法可能是「AI 时代编程语言的内化核心能力」的入口,并用「李白文档 + main 文档」的跨文档引用作为证据 | | 方法 | 设计文档 + 源码 + CLI 实测 + `--dump-ast` + 语料统计;以**可复现行为**优先于文档声明 | | 关联 | [occlusion-syntax.md](../design/occlusion-syntax.md) · [occlusion-description-and-search.md](../design/occlusion-description-and-search.md) · [bracket-as-label-evaluation.md](../design/bracket-as-label-evaluation.md) · [module-namespace.md](../design/module-namespace.md) · [objects.md](../design/objects.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [change-m7-migration.md](../design/change-m7-migration.md) | | 后续 | **[link-syntax.md](../design/link-syntax.md)** — 把本文的评判落成 v2.1 设计声明(类-函数调用 / 项目类索引 / LinkInfo / view / 图边) | **目录**:0 摘要 · 1 问题/方法 · 2 `[]()` 的实现事实 · 3 两文档复现 · 4 逐条评判 · 5 三个概念混淆 · 6 遮蔽的价值与代价 · 7 工程规范硬证据 · 8 能力阶梯与提案 · 9 路线图与验收 · 10 结论 · 附录 A 复现 · B 证据索引 · C 术语 · D 局限 > **2026-10-23 补记(用户澄清)**:`[]()` **不新增语法**;`()` 就是已有代码,`#`/`##` 是类/函数,`类.函数` 是类调用。本文 §4.3/§5 的「呈现层」判断针对 **v2.0.0 实现**;原始设计缺的是类函数语义与跨文档类索引,不是新语法。设计声明见 [link-syntax.md](../design/link-syntax.md)。 --- ## 0. 摘要 ### 0.1 一句话结论 **你的方向是对的,但证据不支持「遮蔽语法已经是这个方向的核心」。** - **可执行知识**是 Marqdo 值得追求的核心方向; - **`[]()` 遮蔽**是**呈现层**语法,不是语义层能力:`[描述](实现)` 的值恒等于 `实现`,标签不参与绑定、作用域、类型、求值; - **你给的两文档例子按现状不可执行**:`run` 退出 0、无输出,`check` 通过;`--dump-ast` 显示 `# main` 是空对象、`# 李白` 的方法体为空; - 你的第三句话——**「工程规范做得不够好」**——**成立**,而且有可复现的硬证据;但根因不是「遮蔽还不够多」,而是「引用、解析、静态校验」这条闭环没有建立。 一句话建议: > **把遮蔽降级为表层工效学,把「引用 / 解析 / 校验」升级为语言核心。** > 知识要可执行,先给它**地址**、**解析器**和**验证器**,再谈链接长什么样。 ### 0.2 五条判断,先给结论 | # | 你的判断 | 证据结论 | 判定 | |---|---------|---------|------| | 1 | Marqdo 已经有 AI 时代的东西 | 有 LLM / agent / MCP / WASM / catalog / EKC / view,但大多是**生态层**,不是语言核心 | ✅ 基本成立 | | 2 | 接下来需要「内化」的核心能力 | 方向正确;缺的确实是核心,但不是遮蔽 | ✅ 成立 | | 3 | `[]()` 遮蔽可以充当那个核心能力 | 它是透明的文档注解,**不增加可计算性**,也不提供跨文档解析 | ❌ 不成立(层级混淆) | | 4 | 两文档例子证明可执行知识的威力 | 例子没有进入执行层;方法体为空;目标不是可调用的静态事实 | ❌ 作为证据不成立 | | 5 | 设计已经到了这一步,只是工程规范不够好 | 默认仍是 Classic;只有 90/886 文件启用;`check` 不做名字解析(只查契约+标签);知识图不从 Markdown 链接取边 | ⚠️ 后半句成立,前半句不成立 | ### 0.3 四个最重要的发现 1. **你的例子实际说明的是「叙述默认安全」,而不是「可执行知识」。** `[李白的出生年份](李白.李白的出生年份)` 在正文里是 Markdown 链接,不是代码;`--dump-ast` 里 `# main` 完全为空。`run` 的退出码 0 只表示「没有东西可执行」,不表示「链接执行成功」。 2. **`[]()` 的语义是恒等式 `[d](e) ≡ e`,它是「呈现层」,不是「语义层」。** 它解决的是可读性、带空格函数名、循环来源、桩申报和 view 呈现;它不解决命名、寻址、解析、类型、跨文档引用。把这些说成「核心能力」,是把「读者看到什么」误当成「语言能做什么」。 3. **工程规范问题确实存在,而且是「契约没有闭环」,不是「文档不够多」。** README 的 `marqdo labels pending` 实测扫 0 个文件(真实值是 6);README 说 v2.0.0 遮蔽,默认解析仍是 Classic;`check` 对未定义变量、未知函数实测放行;EKC 的运行图不从正文链接取边。一个以「知识-代码一致性」为旗帜的项目,自己的文档和代码先漂移了。 4. **迁移把「遮蔽」变成了「键名复述」。** 全仓 231 处 `[label](access(x, "key"))` 形中,**204 处 label 与 key 完全相同(88%)**;设计文档承诺的 `label.provisional`(提醒「标签退化成键名」)在源码中不存在。语法税交了,信息增量没有。 --- ## 1. 问题、方法与证据等级 ### 1.1 要回答的三个问题 1. `[]()` 遮蔽语法**实际上**做了什么?它是不是「编程语言的核心能力」? 2. 用户给的两文档例子,是否真的展示了「可执行知识」?如果没跑起来,失败在哪一层? 3. 如果目标真是「可执行知识」,Marqdo 还缺什么?应该先补哪一块? ### 1.2 方法 - **读设计**:occlusion / label / module-namespace / objects / EKC 的 Accepted 文档; - **读实现**:AST、解析模式、求值、字节码、`check`、`mlsp`、`label`、`knowledge::graph`; - **实测**:在隔离目录 `/tmp/mq-probe` 复现用户的两份文档及其变体,记录退出码、stdout/stderr、`--dump-ast`; - **统计**:全仓 `.mq.md` 与 `markup: occlusion` 的采用率、`access(` 迁移痕迹、`labels` 命中数。 ### 1.3 证据等级 | 等级 | 含义 | 本文用法 | |------|------|---------| | **A** | 本机实测(命令 + 输出) | 结论的主要依据 | | **B** | 源码事实(可定位到文件/行) | 解释行为为何如此 | | **C** | 设计文档声明 | 用于对照「说的」与「做的」 | | **D** | 规范推断(CommonMark / 语言设计) | 明确标注为推断,不冒充实测 | > 本文的原则:**文档说过的,不算数;跑出来的,才算数。** --- ## 2. `[]()` 在实现里到底是什么 ### 2.1 AST:它只是一个「带标签的表达式」 来源:[src/ast.rs:261](../../src/ast.rs#L261) ```rust Occluded { label: String, payload: Option>, } ``` - `label`:`[]` 里的自由文本,**不执行**,只被扫描关键词、检查反引号引用、做 T1 指纹; - `payload`:`()` 里的表达式,**唯一执行**; - `payload: None`:空载荷桩,值为 `None`。 ### 2.2 求值:完全透明 来源:[src/interp.rs:1117](../../src/interp.rs#L1117) ```rust // `` M2: the label is inert prose; only the payload evaluates. Expr::Occluded { payload, .. } => match payload { Some(inner) => self.eval_expr(module, fun, env, inner), None => Ok(Value::None), }, ``` 字节码后端同样只编译 payload([src/bytecode/compile.rs:831](../../src/bytecode/compile.rs#L831))。 **形式化**: > 对任意表达式 `e`、任意标签 `d`:`eval([d](e)) = eval(e)`。 > 标签对求值**零贡献**。 这不是「语义能力」,而是「语义透明的包装」。用 PL 的话说,它是 annotation / transparent wrapper / 文档宏,不是新的求值规则。 ### 2.3 标签被用来做什么 | 用途 | 实现 | 说明 | |------|------|------| | 关键词检索 | `src/label.rs` + `marqdo labels` | 找「待开发 / 模拟 / 桩」等 | | 结构诊断 | `label.missing`(error)、`label.empty_payload`(warning) | 空标签 / 空载荷 | | 引用一致性 | `label.ref_dangling`(error) | **只认反引号实体**,纯口语不检查 | | T1 过期检测 | MLSP `repair_apply` 的 before/after 指纹 | 只在一次修复会话内;`check` 不报 stale | | 视图呈现 | `view` 的 `occl-card` | 标签作正文、payload 作 code chip([src/view/render.rs:1227](../../src/view/render.rs#L1227)) | 注意最后两行:**「过期检测」是会话内、按修复动作触发的**;它不是 CI 级的 `label.stale`。设计文档把它叫「信任负债的代价」,但 CLI 的 `check` 并没有收这笔债。 ### 2.4 解析模式:默认仍是 Classic 来源:[src/parse/expr.rs:14](../../src/parse/expr.rs#L14) ```rust /// The default is `Classic` until M7 migrates the corpus and flips the gate /// (otherwise every legacy index would silently change meaning). pub enum Markup { #[default] Classic, Occlusion, } ``` 文件只有在 frontmatter 写 `markup: occlusion`(或 `标记: 遮蔽`)时才按遮蔽解析([src/load.rs:292](../../src/load.rs#L292))。同一进程可以按文件切换,import 也各自保持模式。 **这意味着**: - 一个普通的 `.mq.md` 里写 `[a](b)`,默认含义仍是**取元**,不是遮蔽; - 用户例子里的 `[]()` 在正文里连取元都不是,只是 Markdown 链接; - README 的「v2.0.0 遮蔽语法」是**功能可用**,不是**默认语义**。 ### 2.5 能力矩阵:它能做什么,不能做什么 | 能力 | 由 `[]()` 提供? | 证据 | |------|----------------|------| | 求值(等于 payload) | ✅ | `interp.rs:1117` | | 人话标签(不执行) | ✅ | `ast.rs:261` | | 可读的嵌套取值 | ✅(写法上) | 设计 §1.1 | | 带空格函数名调用 | ✅(`callee(args)`) | M1 / `m2` 实测 | | 循环来源可见 | ✅(`遍历`) | M3 | | 桩申报 / 债务盘点 | ✅ | `label.rs` / `labels` | | view 呈现 | ✅ | `render.rs:1227` | | **跨文档引用** | ❌ | `f4` 实测失败 | | **名字解析 / 静态检查** | ❌ | `check` 对未定义变量放行 | | **类型 / 契约求值** | ❌ | `check` 只查契约表/标签,不求值 | | **知识实体 / 事实模型** | ❌ | `Fact` 是 frontmatter 元数据,不是 `[]()` | | **知识图边** | ❌ | `knowledge::graph` 不从正文链接取边(边来自 import/call/tests/related/reuse/knowledge) | ### 2.6 一句话定义 > **`[]()` 是「给读者看的描述 + 给机器跑的表达式」的绑定语法。** > 它让读者少读代码,让机器照常执行;它**不**让语言多算任何东西。 这就是为什么它是**表层工效学**,不是**语义核心**。 --- ## 3. 用户两文档的逐层复现 ### 3.1 原文 `libai.mq.md`: ```markdown # 李白 这个文档存储了李白的信息 ## 李白的出生年份 李白出生于*某年* ``` `main.mq.md`: ```markdown # main 用户想要直到李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份) ``` ### 3.2 实测结果 环境:`marqdo 2.0.0`,两份文件在 `/tmp/mq-probe` 下。 | 命令 | 退出码 | stdout | stderr | 解释 | |------|--------|--------|--------|------| | `marqdo run main.mq.md` | **0** | 空 | 空 | 没有任何语句执行 | | `marqdo check main.mq.md` | **0** | `contract check OK: 无契约问题` | 空 | 契约检查通过,不代表程序可运行 | | `marqdo run libai.mq.md` | **0** | 空 | 空 | 只构造对象,不调用方法 | | `marqdo run main.mq.md --dump-ast` | 0 | `(object level=1 "main" params=[] @1:1)` | 空 | **`# main` 是空对象;链接不在 AST 里** | | `marqdo run libai.mq.md --dump-ast` | 0 | 方法 `李白的出生年份` 下无语句 | 空 | **方法体为空,没有返回值** | `main.mq.md` 的 AST(关键部分): ```text (object level=1 "main" params=[] @1:1 ) ``` `libai.mq.md` 的 AST(关键部分): ```text (object level=1 "李白" params=[] @1:1 (fun level=2 "李白的出生年份" params=[] @5:1 ) ) ``` ### 3.3 失败在哪五层 这不是「一个拼写错误」,而是五个层次的连续缺口: | 层 | 期望 | 实际 | 证据 | |----|------|------|------| | **1. 上下文层** | 正文链接由 `view`/`check` 解析 | 正文默认是叙述(注释),`run` 不解析、不进入 AST | `--dump-ast` 空 | | **2. 索引层** | 项目类索引能找到类 `李白` | 没有类索引;裸类名不是绑定名 | `f4` 即使 import 也失败 | | **3. 表达式层** | `李白.李白的出生年份` 是类调用 | 它被当成点号路径的**变量读取**;类函数语义缺失 | `f3`:`undefined variable` | | **4. 分派层** | 类 `李白` 直接调用函数 | `# 李白` 是类型,`##` 被实现成实例方法;类调用被拒绝 | `n2`:`is an instance method; call it as var.李白的出生年份` | | **5. 值层** | 方法返回年份 | 方法体为空(`李白出生于*某年*` 是带斜体的叙述,不是返回语句),返回 `None` | `n1` 输出 `None`;`--dump-ast` 空 | > **关键**:即使把第 1 层补上(加 `**`),第 3/4/5 层仍然会失败。 > 这不是「写法不够甜」,是**语义模型不匹配**。 ### 3.4 三个最小可运行改写 #### A. 顶层自由函数 + `>` 调用(跨文档,但不用遮蔽) `k1_lib.mq.md`: ```markdown ## 李白的出生年份 *701* ``` `k2_main.mq.md`: ```markdown --- import lb:k1_lib.mq.md --- # main **year = > lb.李白的出生年份** > print text=`year` ``` 实测:**输出 `701`,退出码 0**。 #### B. 对象 + 实例方法 + 遮蔽(跨文档,且用 `[]()`) `lib2.mq.md`: ```markdown # 李白 ## 李白的出生年份 *701* ``` `n3.mq.md`: ```markdown --- markup: occlusion import lb:lib2.mq.md --- # main **li = > lb.李白** **year = [出生年份](li.李白的出生年份())** > print text=`year` ``` 实测:**输出 `701`,退出码 0**;AST 里能看到 `Occluded { label: "出生年份", payload: Call(...) }`。 #### C. 纯本地遮蔽(证明它只是表达式包装) ```markdown --- markup: occlusion --- # main **x = [二](1 + 1)** > print text=`x` ``` 实测:**输出 `2`,退出码 0**;默认 Classic 下同一文件会报 `footnote index needs list or map`。 ### 3.5 结论 - **能跑的是 A/B 的「模块 + 对象 + 调用」系统**,不是「文档链接」; - B 里的 `[]()` 只是把 `li.李白的出生年份()` 这行代码包了一层人话; - 用户原始例子缺的正好是 A/B 的核心:**绑定、调用、值**; - 所以它**不能**作为「可执行知识已经到位」的证据。它最多证明「可执行知识的语法外形可以长成链接」,而这一点设计文档已经说过。 --- ## 4. 对用户判断的逐条评判 ### 4.1 判断一:Marqdo 已经有 AI 时代的东西 **基本成立,但要区分层次。** | 层 | 已有 | |----|------| | 语言核心 | 表达式、对象、模块、字节码、契约表 | | 运行时 | stdlib、插件 ABI、WASM、沙箱、子任务 | | 工具 | view、debug、catalog、EKC、MLSP | | AI | ext/llm、ext/agent、MCP、Skill | 这些是**生态层**的 AI 能力。它们能证明 Marqdo 适合做 AI 的工程底座,但不能证明语言核心已经「内化」了知识。**生态丰富 ≠ 语言核心强。** ### 4.2 判断二:需要内化的核心能力 **成立。** 而且这是本文最同意的一句。 Marqdo 现在的强项是「文档即代码」的**呈现**和**执行**;弱项是「知识即实体」的**寻址**、**解析**、**验证**。后者才是「可执行知识」的承重结构。 ### 4.3 判断三:`[]()` 可以充当那个核心 **要分两层说。** - **v2.0.0 的实现**:不成立。它只做了「标签 + 表达式」;`##` 仍是实例方法,跨文档类名不解析,所以它只是呈现层。 - **原始设计**:成立,但前提是 `#`/`##` 真正成为类/函数,`类.函数` 可直接调用,项目类索引可用。这时 `[d](e)` 的语义来自 `e`(类调用),链接只增加 label/元数据,不是新语法。 `[d](e) ≡ e` 仍然成立。问题不是「链接要不要语义」,而是「`e` 能否解析成类/函数调用」。v2.0.0 的答案是不能;v2.1 要补的是这个解析,不是新语法。 **所以:当前实现是「读者的眼镜」;原始设计是「描述 + 地址(类/函数)」。补上类函数语义后,它才是核心。** ### 4.4 判断四:两文档例子证明可执行知识的威力 **作为证据不成立。** 见 §3:例子没有进入 AST,方法体为空,目标不是可调用的静态事实。 但**作为需求**它是成立的:它精确地指出了用户想要的东西—— > 「我在 A 文档里写下一个事实,在 B 文档里用一句人话引用它,B 能执行并拿到值。」 这个需求是真实的;只是 `[]()` 不是实现它的语法。 ### 4.5 判断五:设计已经到了这一步,工程规范不够好 **后半句成立,前半句不成立。** - 「设计到了这一步」:默认 Classic;90/886 文件启用;`lib/` 0 启用;真正带描述的遮蔽标签只有 6 处(其中 4 处在测试);`check` 不解析名字;知识图不从链接取边。**这不是「到了」,是「有一个可用的原型」**。 - 「工程规范不够好」:**完全成立**,而且比你说的更严重——不是规范执行不严,而是**规范没有闭环**(见 §7)。 ### 4.6 总评分 | 维度 | 评分 | 理由 | |------|------|------| | 愿景(可执行知识) | ★★★★★ | 方向正确,且与 OKF / literate programming 同构 | | 对 `[]()` 的定位 | ★★☆☆☆ | 把呈现层当语义层 | | 对现状的判断 | ★★☆☆☆ | 例子不可执行,默认未启用,采用率低 | | 对工程规范的判断 | ★★★★★ | 有硬证据,且是当前最大瓶颈 | | 建议的可执行性 | ★★★★☆ | 先补引用/解析/校验,再谈链接外形 | --- ## 5. 三个概念混淆(理论核心) 这一节解释「为什么这个例子看起来很美,实际却跑不起来」。 ### 5.1 混淆一:呈现 vs 语义 | | 呈现层 | 语义层 | |---|--------|--------| | 关心 | 读者看到什么 | 程序能解析/验证/执行什么 | | 例子 | 标签、注释、doc、view | 变量、作用域、类型、调用、模块 | | 失败后果 | 读者误解 | 程序报错 / 静默错义 | | **v2.0.0 的 `[]()`** | ✅ 主要在这里 | ❌ 只做透明传递 | 把呈现层说成核心,会导致资源投入到「更好看的语法」,而真正的解析器/校验器没人做。**用户例子跑不起来,正是这个错位的直接后果。** > **原始设计**:`[]()` 不是纯呈现;`e` 是类/函数调用,语义在 `e`。v2.0.0 没实现类函数解析,所以它**看起来**才像纯呈现。 ### 5.2 混淆二:变量读取 vs 类调用 `()` 里是**表达式**,在当前环境求值。`李白.李白的出生年份` 被解析成「变量读取」,所以报 `undefined variable`。 而用户想要的是**类调用**:`李白` 是类,`李白的出生年份` 是函数;解析器应在当前文档/import/项目类索引里找到它并调用。 | | 变量读取(当前) | 类调用(目标) | |---|------------------|----------------| | 含义 | 当前环境的一个变量 | 类命名空间里的函数 | | 解析 | 运行时环境 | 当前文档 / import / 项目类索引 | | 失败 | `undefined variable` | `link.unresolved` / `link.instance_only` | | 例子 | `x` | `李白.李白的出生年份` | | 用户目标 | 被当变量 → 失败 | 类调用 → 未实现 | **`()` 是表达式槽;类调用是表达式的一种,不需要新的地址语法。** ### 5.3 混淆三:文档 vs 类型 用户的心理模型: > `# 李白` 是文档标题,`## 李白的出生年份` 是文档的一节,`李白.李白的出生年份` 是这一节的地址。 Marqdo 的实际语义([objects.md](../design/objects.md#L14)): > `#` 是对象/类型;`##` 是函数/方法;方法通过 `_type` 分派,需要实例。 | 用户以为 | Marqdo 实际 | |---------|------------| | `# 李白` = 文档 | `# 李白` = 类型 | | `## 出生年份` = 一节/一个事实 | `## 出生年份` = 方法 | | `李白.出生年份` = 事实地址 | 点号路径 = 类/函数;不使用 `self` 的函数可类调用,使用 `self` 的需实例 | | 文档「存储信息」 | 文档「执行代码」;正文是注释 | 这不是小差别,是**文档模型 vs 类/函数模型**的差别。原始设计就是 `#` 类 + `##` 函数 + `类.函数` 类调用;不需要新语法,只需要把 `##` 从「实例方法」恢复为「类函数(`self` 时例外)」并建立跨文档类索引。 ### 5.4 Markdown 链接三难 用户想要三件事同时成立: 1. **L**:它仍是普通 Markdown 链接(`[文本](目标)`,目标是一个 URL/路径); 2. **X**:目标可执行(点一下/引用一下就运行); 3. **S**:叙述默认安全(无标记的正文永远不执行)。 | 组合 | 是否可能 | 说明 | |------|---------|------| | L + S | ✅ | 当前状态:正文链接是惰性的 URL | | X + S | ✅ | 只在显式代码标记内(遮蔽);但它不再是「文档链接」 | | L + X | ✅ | 但正文链接会变成代码入口,破坏 S | | **L + X + S** | ❌ | **三者不可兼得** | 用户例子假设了 L + X + S 同时成立;这就是它「看起来该跑、实际不跑」的根源。 **结论**:要么接受「正文链接在 `run` 中是惰性的」,要么给「可执行引用」一个显式标记。Marqdo 可以选择前者 + `#`/`##` 类函数解析:**正文链接是 view 的知识调用,代码链接才是 `run` 的执行体**;这样不需要新语法,也不破坏叙述默认安全。 ### 5.5 「内化」的五条判定标准 一个能力算不算「语言核心」,可以拿这五问去测: | # | 问题 | 遮蔽 | 跨文档引用 | |---|------|------|-----------| | 1 | **可指称**:有稳定地址吗? | ❌ 标签不是地址 | ⚠️ 路径是地址,但未解析 | | 2 | **可绑定**:进入作用域/导入系统吗? | ❌ 标签不绑定 | ⚠️ import 有,但事实无 | | 3 | **可组合**:能作为值/参数/返回值吗? | ✅ 透明传递 | ⚠️ 只能调用,不能当值 | | 4 | **可验证**:工具链能证明它对吗? | ⚠️ 只查反引号/空载荷 | ❌ `check` 不解析 | | 5 | **可观察**:运行时/诊断能看到吗? | ✅ view / 错误锚点 | ⚠️ 只有运行时错误 | 遮蔽在 5 问里只拿到 2 个 ✅、1 个 ⚠️;**它不是核心,是表层**。 跨文档引用拿到 0 个 ✅、3 个 ⚠️;**它有雏形,但不是能力**。 ### 5.6 结论 > **在 v2.0.0 里,`[]()` 只完成了「描述 + 表达式」;在原始设计里,`[]()` 是「描述 + 类/函数调用」。** > 缺的不是一种新语法,而是 `#`/`##` 的类函数语义与跨文档类索引;补上后,链接的语义来自调用,标签仍只是排版。 ### 5.7 相关系统对照:它更像什么,不像什么 以下为高层对照(C/D),不是对各系统规范的逐条审计: | 系统 / 传统 | 人话与代码的关系 | 跨文档引用 | 执行 | 对 Marqdo 的启示 | |------------|----------------|-----------|------|-----------------| | **Literate programming(Knuth)** | chunk 名 + 代码;weave/tangle | 文内 `<>`,非跨文档事实 | tangle 后执行 | 遮蔽 ≈ chunk 名;chunk 名是宏地址,不是知识事实 | | **Org-mode + Babel** | 散文 + 显式 `#+begin_src` | ID/链接用于导航 | 只在 src block 内执行 | **显式标记**是可执行的前提 | | **Jupyter** | Markdown cell + code cell | 无原生文档间引用 | kernel 执行 | cell 边界是显式语法,不是「长得像链接」 | | **Observable** | 散文 + 响应式 JS cell | cell 名互相引用 | 数据流执行 | 最接近「可执行知识」,但不是 Markdown 原生 | | **Obsidian / Roam** | wiki link / backlink | ✅ 链接图 | ❌(插件另说) | **链接图 ≠ 执行图** | | **Notion / Coda** | 文档 + 公式/按钮 | ✅ 跨文档引用 | ✅(专有) | 地址 + 公式模型,不是 Markdown | | **OKF** | frontmatter + Markdown 链接 | ✅ 路径即 ID、链接即关系 | ❌(元数据) | 可借鉴「路径即身份」 | | **Marqdo 现在** | `[label](code)`(代码内) | ❌ | ✅ payload | 表面强,类-函数调用缺 | **结论**: - 遮蔽更像 **literate programming 的 chunk 名**或 **Org-babel 的 prose label**:它服务于「读」和「组织」,不是「跨文档求值」; - 用户的直觉更像 **Obsidian 的链接** + **Observable 的响应式引用**:那需要**地址**和**解析器**,不是把 `()` 换成代码; - Obsidian 的链接图之所以有用,是因为它**不执行**;一旦链接执行,安全模型就完全不同了。Marqdo 必须在「链接图」和「执行图」之间划清边界。 --- ## 6. 遮蔽语法的真实价值与代价 ### 6.1 真实价值(这部分是肯定的) 1. **可读调用 / 带空格函数名** `[加一之后的值](加一 号(31))` 解决了 D8:`(` 是明确边界,空格不再切词。 实测 `m2`:`[出生年份](lb.李白的出生年份())` → `701`。 2. **嵌套取值可读** `[水果类里苹果的第 1 项价格](at(at(at(货架, 水果类), 苹果), 1))` 读者只看人话,机器看嵌套。这是真实的认知负担下降。 3. **循环来源可见** `- [从篮子里取出的每个果子](遍历 篮子 为 果)` 比 `- [果](篮子)` 更能自解释「从哪来」。 4. **桩 / 债务申报** `[搜索接入,接口未接,待开发](None)` 让「没接」变成可计数、可检索、可门禁的债务,而不是静默假功能。这是设计里最有价值的工程创新之一。 5. **view 呈现** 标签作正文、payload 作 code chip;读者先读人话,需要时再看代码。 这些价值都是真的,但都属于**可读性 / 可审查性 / 工程治理**,不是「语言能算得更多」。 ### 6.2 代价(这部分必须算清) | 代价 | 说明 | 证据 | |------|------|------| | **同形歧义** | `[a](b)` 可能是 Markdown 链接、旧取元、遮蔽、调用 | 设计文档 §9 / M7 | | **逐文件方言** | 同一仓库两种语义,靠 frontmatter 区分 | `expr.rs:14` / 90/886 | | **Markdown 兼容裂缝** | `()` 里是代码,不是 URL;GFM 的链接目标会是代码/非 URL(能否成链接取决于括号/空格),不可导航 | D(CommonMark 推断) | | **信任负债** | 标签是自然语言,可能说谎;只查反引号 | 设计 §2.2 / `label.rs` | | **Agent 攻击面** | 标签可能误导 agent(「只读」标签 + 删除 payload) | `bracket-as-label-evaluation.md` §4.3 | | **迁移语义空壳** | `[key](access(...))` 的标签常等于键,无信息增量 | 231 处形,204 处(88%)label=key;`label.provisional` 未实现 | | **采用率低** | 90/886 文件启用;`lib/` 0;真正带描述的标签 6 处 | 统计 | ### 6.3 迁移留下的「语义空壳」 迁移工具把旧取元改成了: ```markdown **timeout = [timeout_sec](access(self, "timeout_sec"))** ``` - 标签 `timeout_sec` 只是键名的重复; - 设计文档 §1.6 明确说这是**反例**(「描述等于变量名,无信息增量」); - 设计文档 §9 承诺 `label.provisional`(hint)来提醒这种退化; - **源码里没有 `label.provisional`**(`grep` 无结果)。 结果:对 231 处 `[label](access(x, "key"))` 的机械统计显示,**204 处 label 与 key 完全相同(88%)**。这不是「描述」,是「键名复述」;不是为了读者,是为了让语法通过。这不是「内化」,是「语法税」。 ### 6.4 采用率:它不是默认,也不是主流 | 目录 | `.mq.md` 总数 | `markup: occlusion` | 占比 | |------|-------------|---------------------|------| | `lib/` | 53 | 0 | 0% | | `ext/` | 31 | 8 | 26% | | `examples/` | 90 | 7 | 8% | | `public/` | 100 | 26 | 26% | | `tests/` | 603 | 48 | 8% | | **合计** | **886** | **90** | **10.2%** | (排除 `target/`、`dist/`、`.marqdo/`;统计命令见附录 A。) - `lib/` 是标准库,0 启用:说明「遮蔽」不是语言运行时的默认契约; - 真正带**描述性标签**的遮蔽只有 6 处(`labels --json`),其中 4 处在测试; - 90 个启用文件里,大多数是迁移后的 `[key](access(...))`,不是人写的「一句人话」。 **结论**:遮蔽目前是**一个可用的、局部的、实验性的表面**,不是「全语言的核心能力」。 ### 6.5 对遮蔽的最终定位 | 选项 | 评价 | |------|------| | 删除遮蔽 | ❌ 可惜;它确实解决了 D8、嵌套可读、桩申报 | | 把它当核心 | ❌ 层级错误;会继续把资源投到语法糖 | | **保留为表层工效学,另建类-函数调用层** | ✅ **推荐** | --- ## 7. 工程规范的硬证据:文档-代码漂移 用户的第三句话「工程规范做得不够好」是对的。下面每一条都可复现。 ### 7.1 总表 | 文档说 | 实际做 | 证据等级 | 证据 | |--------|--------|---------|------| | README:v2.0.0 遮蔽语法 | 默认仍是 Classic;需 frontmatter | A/B | `run e3` 报 `footnote index`;`expr.rs:14` | | README:`marqdo labels pending` | 扫 0 个文件(真实 6) | A | 附录 A | | README:`labels search --grep ...` | 扫 0 个文件(真实 2) | A | 附录 A | | README:Markdown 链接天然长成知识图 | 运行图不从正文链接取边(来自 import/call/tests/...) | B | `knowledge/graph.rs` | | README:AI 可验证语言 | `check` 只查契约+标签;未定义变量/函数实测放行 | A/B | `check.rs:1`;`e1/e2` | | 设计:M0–M10 全部完成 | 默认未翻转;per-file 模式 | C/B | `change-m7:22`;`expr.rs:14` | | 设计:506 处取元 + 44 处循环 | 实施记录 256 + 23(口径未说明) | C | `occlusion-syntax:318` vs `change-m7:11` | | 设计:`label.provisional` | 未实现 | B | `grep provisional` 无结果 | | 测试:项目称 605 全绿 | 没有跨文档 headline 场景 | B | `tests/occlusion.rs` 只有本地用例 | ### 7.2 `labels pending`:最危险的「假 0」 README 把这条命令当作「还有多少未完成」的默认口径: ```bash marqdo labels pending # 内置口径:还有多少未完成 marqdo labels pending --count --baseline .marqdo/pending.json --fail-on-increase ``` 实测: ```text $ marqdo labels --count 6 $ marqdo labels pending --count 0 $ marqdo labels --grep 待开发 --count 2 $ marqdo labels search --grep 待开发 --count 0 ``` 原因([src/main.rs:631](../../src/main.rs#L631)): ```rust // Accept the documented shapes `labels pending` / `labels search` // as no-op words (the flags carry the real intent). let paths: Vec<&PathBuf> = paths.iter().filter(|p| { let s = p.to_string_lossy(); !(s == "pending" || s == "search") }).collect(); ``` 它把 `pending`/`search` 从路径里过滤掉,但**没有回退到 `.`**。于是「文档里最常用的无路径盘点形式」会扫 0 个文件、返回 0。 **这是最能说明问题的一条**:一个以「不允许假装完成」为工程习惯的项目,自己的默认盘点命令会报告「没有未完成」。如果 CI 用这个无路径形式做棘轮,它会一直通过。 ### 7.3 `check`:通过 ≠ 可运行 `check` 的文档写的是「静态契约互查」,这本身没错;但它的输出是: ```text contract check OK: 无契约问题 ``` 对下面这个文件: ```markdown # main **x = > 不存在的函数 n=1** > print text=`x` ``` `check` 退出 0,`run` 才报 `unknown function`。未定义变量同理。 `mlsp validate` 也只是 `check_module`([src/mlsp.rs:199](../../src/mlsp.rs#L199)),所以 AI 的「validate」也拿不到名字解析错误。 **影响**:AI 生成一个「结构正确、名字全错」的程序,`check` 会说 OK;直到运行时才炸。这与 README 的「AI 可验证语言」叙事有距离。 ### 7.4 默认 Classic:v2.0.0 的「遮蔽」是 opt-in `expr.rs` 的注释写得很清楚:默认 Classic,等 M7 迁移完再翻转。但 M7 文档说「per-file 声明」,README 说「v2.0.0 遮蔽语法」。三者并不完全矛盾,但**读者会误解**: - 「v2.0.0 有遮蔽语法」= 你可以用; - 「默认是遮蔽」= ❌; - 「全仓已迁移」= ❌(90/886)。 一个语言特性的「发布」到底是「可用」还是「默认」,必须在 README 里写清楚。否则用户按 README 写 `[a](b)`,得到的是取元,不是遮蔽。 ### 7.5 知识图:链接没有变成边 README 的愿景 #4: > `.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。 实际 `knowledge/graph.rs` 的边来自: - module 的 `imports` → `depends_on` - symbol 的 `calls` → `uses` - tests / related / reuse / knowledge applies_to **没有一条代码路径**从正文的 Markdown 链接提取边。`catalog` 会把依赖渲染成链接,但那是「图 → 链接」,不是「链接 → 图」。 所以用户例子里的 `[李白的出生年份](李白.李白的出生年份)` 不会成为任何图边;`marqdo catalog` 只会把它当作模块 `main` 的一段叙述。 ### 7.6 测试没有覆盖 headline 场景 `tests/occlusion.rs` 覆盖了: - 本地遮蔽值 = payload; - Classic / Occlusion 双模式; - 空标签 / 空载荷 / 反引号悬空; - labels 检索; - T1 会话内过期。 它**没有**覆盖: - 跨文档 import + 对象方法 + 遮蔽标签; - 正文链接的悬空检测; - 用户两文档的「事实引用」场景; - `labels pending` 的文档命令形式。 所以「605 全绿」不能证明「用户例子能跑」;它只证明了被测的部分能跑。 ### 7.7 这不是「文档不够多」,是「契约没有闭环」 项目已经有大量设计文档、ADR、变更记录、研究文档。问题不是数量,而是: 1. **文档里的命令没有变成测试**(`labels pending`); 2. **文档里的承诺没有变成诊断**(`label.provisional`、`label.stale` 在 CLI); 3. **文档里的默认值没有和代码对齐**(v2.0.0 vs Classic); 4. **文档里的 headline 例子没有金样**(两文档场景); 5. **发布说明没有采用率/覆盖率指标**(90/886、6 个标签)。 对一个以「知识-代码一致性」为旗帜的项目,这五条是**自我指涉的失败**:它没有用自己的方法管理自己。 --- ## 8. 如果要做成核心:能力阶梯与提案 ### 8.1 能力阶梯 | 层 | 能力 | Marqdo 现状 | |----|------|------------| | **L0** | 叙述 + 本地表达式 | ✅ | | **L1** | 变量 / 函数 / 对象 | ✅ | | **L2** | 模块 / import / 点号路径 | ✅ | | **L3** | **静态名字解析 / 类型检查 / 悬空引用** | ❌ 缺 | | **L4** | **知识实体 / 稳定地址 / 图边** | ⚠️ 只有 EKC 元数据,未接执行 | | **L5** | **可执行知识查询(`类.函数` → 值)** | ❌ 缺 | **用户以为在 L5;证据显示在 L2 + 一个 L0.5 的呈现层。** ### 8.2 四个必需件 1. **类/函数语义** - `#` 是类,`##` 是函数; - 不使用 `self`/`自` 的函数是**类函数**,可 `类.函数` 调用; - 使用 `self`/`自` 的是**实例函数**,只能 `obj.函数` 调用。 2. **项目类索引** - 扫描项目根 `.mq.md` 的 `#`/`##`、签名、位置; - 跨文档解析 `类.函数`;同名 `link.ambiguous`; - 排除 `# main`;只在根内。 3. **类调用** - `类.函数` 零参隐式调用;带参 `类.函数(...)`; - 不构造实例;实例函数拒绝; - 正文链接由 `view`/`check` 解析;代码链接由 `run` 求值。 4. **验证** - `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` / `link.arg_mismatch` / `link.type_mismatch`; - LinkInfo;`check --json`;MLSP; - 图边。 ### 8.3 语义提案:不新增语法,补类-函数调用 **不要**给 `()` 增加新语法。`()` 就是 `**` 代码;要补的是下面四条语义: 1. `#` 是类,`##` 是函数;不使用 `self`/`自` 的函数是**类函数**; 2. `类.函数` 是类调用;零参函数隐式调用,带参写 `类.函数(...)`; 3. 项目类索引跨文档解析;同名类 `link.ambiguous`; 4. 代码链接求值;正文链接由 `view`/`check` 解析,`run` 不执行;要终端输出用代码链接 + `print`。 | 场景 | 写法 | 语义 | |------|------|------| | 本地表达式 | `[描述](表达式)` | 值 = 表达式;标签 inert | | 类调用 | `[描述](李白.李白的出生年份)` | 解析类/函数并调用 | | 实例调用 | `[描述](li.李白的出生年份())` | 现有实例方法 | | 正文链接 | 同上 | view/check 解析;run 不执行 | 不要新增协议前缀、别名、执行开关;不要靠「内容像路径」来猜语义——靠类索引和解析器。 ### 8.4 知识文档约定 `type: Fact` 是 EKC 元数据,不是新语法;知识文档的「值」仍由 `##` 函数返回: ```markdown --- type: Fact id: libai.birth_year title: 李白的出生年份 --- # 李白 ## 李白的出生年份 | 返回 | 类型 | 说明 | |------|------|------| | 701 | number | 公元 701 年 | *701* ``` - `# 李白` = 类;`##` = 函数;`*701*` = 值; - 类函数不使用 `self`,可 `李白.李白的出生年份` 直接调用; - `type: Fact` 只影响 catalog/EKC,不影响调用; - 知识函数必须有返回值;无返回 → `link.no_value`。 ### 8.5 用户例子的验收形态 `libai.mq.md`: ```markdown # 李白 这个文档存储了李白的信息。 ## 李白的出生年份 *701* ``` `main.mq.md`: ```markdown # main 用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份) ``` 期望: - `view`:显示链接目标 `李白.李白的出生年份`、类/函数、值 `701`; - `run`:无输出(正文链接不执行);代码链接 + `print` 输出 701; - `check`:`link.ok`(class/function/signature); - 类名不存在 → `link.unresolved`; - 函数不存在 → `link.unresolved`; - 同名类 → `link.ambiguous`; - 无返回值 → `link.no_value`。 这是「描述 + 已有调用」,不是新语法。 ### 8.6 安全边界:标签是不可信文本 - **策略/权限永远不看标签**,只看 payload / 解析后的类函数; - agent 提示词要写:标签是自然语言,可能误导;以 payload 与类函数解析结果为准; - `view` 必须同时显示标签与 payload(当前实现已显示 code chip,这是对的); - 对「标签说只读、payload 写文件」这类不一致,至少给 hint(设计文档 §4.2 提议过词重叠校验,但未实现)。 --- ## 9. 路线图与验收 ### 9.0 能力规划总表 | 能力 | 层次 | 现状 | 优先级 | 验收 | |------|------|------|--------|------| | 名字解析 / 类型检查 | L3 | 缺 | **P0** | `check --strict` 报未定义变量/函数 | | 正文链接 / 类调用解析 | L3 | 缺 | **P0** | `check --links` 报 `link.*` | | 类-函数调用 | L4 | 缺 | **P1** | `类.函数` 直接调用 | | 项目类索引 | L4 | 缺 | **P1** | 跨文档解析类名 | | 知识文档 / 事实 | L4 | 部分(EKC 元数据) | **P1** | `type: Fact` + 返回值 | | 图边(链接 → 图) | L4 | 缺 | **P1** | `graph.json` 有 `calls` 边 | | 执行 / 查询 | L5 | 缺 | **P1** | `run`/`view` 输出 701 | | AI schema / 修复 | L5 | 部分 | **P2** | MLSP `link.resolve` | > **顺序建议**:P0 先让「假成功」消失;P1 再让「类-函数调用」成立;P2 才谈 AI 闭环。不要在 L3 缺失时翻转遮蔽默认。 ### 9.1 P0:先止血(1–2 周) | # | 事项 | 验收 | |---|------|------| | P0-1 | 修 `labels` 路径回退:过滤 `pending`/`search` 后若无路径,默认 `.` | `labels pending --count` == `labels --count` == 6 | | P0-2 | `check` 输出改为「contract check only」;新增 `--strict` 名字解析 | `check --strict e2` 报 `undefined variable`;`e1` 报 `unknown function` | | P0-3 | 新增 `check --links`:解析正文 `[]()`,校验类/函数 | 用户例子的 `李白.李白的出生年份` 报 `link.*`(或 `link.ok`) | | P0-4 | 把用户两文档加入金样:要么 `view` 显示 701,要么 `check` 精确报错 | 不允许「exit 0 + 空输出」被当成通过 | | P0-5 | 修文档:v2.0.0 的「可用 ≠ 默认」;M7 的 per-file 模式;`labels` 命令;506 vs 256 口径 | README / 设计文档与实测一致 | | P0-6 | `label.provisional` 落地,或迁移时不再生成「键名标签」 | 231 处 `access` 标签(204 处 label=key)有 hint 或被清理 | ### 9.2 P1:补类-函数调用(核心) | # | 事项 | 验收 | |---|------|------| | P1-1 | 补齐 `#`/`##` 的类-函数语义:`类.函数` 直接调用;项目类索引解析跨文档 | 正文可写 `[描述](李白.李白的出生年份)` | | P1-2 | 静态解析器:类 → 函数 → 契约 | `check` 报 `link.unresolved` / `link.type_mismatch` | | P1-3 | 知识文档:`type: Fact` + 返回值 + 表/函数 | `run`/`view` 取值 701;`find`/`impact` 能用 | | P1-4 | EKC 从链接取边;`catalog` 图与运行时解析同源 | `graph.json` 有 `calls` / `references` 边 | | P1-5 | `view` 解析链接并显示 provenance | 点击/展开能看值与来源 | ### 9.3 P2:AI 原生闭环 | # | 事项 | 验收 | |---|------|------| | P2-1 | MLSP `link.resolve` / `link.check` / schema | AI 可查「这个链接指向哪个类/函数、类型对不对」 | | P2-2 | agent 提示词:标签不可信;以 payload/类函数为准 | 注入「只读标签 + 删除 payload」测试 | | P2-3 | 指标:采用率、解析率、check 覆盖率、stale 标签 | 发布报告可见 | | P2-4 | 基准:AI 生成带类调用的文档 vs 纯代码 | 错误率/修复轮次/token 对比 | ### 9.4 总验收(一句话) > **用户的两份文档:`view` 显示 701,`check` 返回 `link.ok`;加 `print` 的代码链接输出 701。** > **不允许「退出 0、无输出、显示 OK」这种假成功。** --- ## 10. 结论 ### 10.1 直接回答「遮蔽到底有什么用」 **v2.0.0 的 `[]()`**: - 它让**读者**不必读复杂表达式(嵌套、长算式、循环来源); - 它让**带空格的函数名**有了明确边界; - 它让**未完成的桩**变成可检索、可计数、可门禁的债务; - 它让 **view** 能先显示人话、再显示代码; - 它**不**提供类-函数调用、跨文档类索引、名字解析、LinkInfo、图边。 **原始设计还要加的四件事**(都不需要新语法): 1. `#`/`##` 的类/函数语义; 2. `类.函数` 类调用; 3. 项目类索引跨文档解析; 4. view/LinkInfo/图边。 ### 10.2 对你思路的最终评判 | 你的话 | 评判 | |--------|------| | 「可执行知识是核心」 | ✅ 对 | | 「工程规范不够好」 | ✅ 对,且有硬证据 | | 「`[]()` 遮蔽可以充当内化核心」 | ⚠️ **v2.0.0 实现**不成立(只是呈现层);**原始设计**成立,前提是补类-函数语义与类索引 | | 「两文档例子证明威力」 | ❌ 当前例子跑不起来(正文不解析、类调用未实现、函数无返回值) | | 「设计已经到了这一步」 | ❌ 到了原型,没到核心;默认未启用,采用率 10% | ### 10.3 一句话建议 > **先把 `#`/`##` 的类-函数语义与项目类索引做进语言核心;`[]()` 只是「描述 + 已有调用」,不需要新语法。** 当 `[李白的出生年份](李白.李白的出生年份)` 能让 `view` 显示目标/签名/值、让 `check` 返回 `link.ok`、让 `run`(加 print)输出 701、让 EKC 建边时,「可执行知识」才真正展示威力。那时你会发现:**它不需要 `[]()` 变成新语法;它需要 `#`/`##` 真正成为类/函数。** --- ## 附录 A:复现命令 以下命令在 `marqdo 2.0.0` 下执行;`M=/workspace/marqdo/target/release/marqdo`。 ### A.1 用户两文档 ```bash mkdir -p /tmp/mq-probe && cd /tmp/mq-probe cat > libai.mq.md <<'EOF' # 李白 这个文档存储了李白的信息 ## 李白的出生年份 李白出生于*某年* EOF cat > main.mq.md <<'EOF' # main 用户想要直到李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份) EOF $M run main.mq.md; echo "exit=$?" $M check main.mq.md; echo "exit=$?" $M run main.mq.md --dump-ast $M run libai.mq.md --dump-ast ``` ### A.2 遮蔽在代码里才执行 ```bash cat > p5_prose.mq.md <<'EOF' # main [运行一个副作用](print("PROSE-RAN")) EOF cat > p4_code.mq.md <<'EOF' --- markup: occlusion --- # main **x = [运行一个副作用](print("CODE-RAN"))** EOF $M run p5_prose.mq.md --dump-ast # 空对象 $M run p5_prose.mq.md # 无输出,exit 0 $M run p4_code.mq.md # CODE-RAN ``` ### A.3 跨文档:三种写法 ```bash # A. 顶层函数 + > 调用 cat > k1_lib.mq.md <<'EOF' ## 李白的出生年份 *701* EOF cat > k2_main.mq.md <<'EOF' --- import lb:k1_lib.mq.md --- # main **year = > lb.李白的出生年份** > print text=`year` EOF $M run k2_main.mq.md # 701 # B. 对象 + 实例方法 + 遮蔽 cat > lib2.mq.md <<'EOF' # 李白 ## 李白的出生年份 *701* EOF cat > n3.mq.md <<'EOF' --- markup: occlusion import lb:lib2.mq.md --- # main **li = > lb.李白** **year = [出生年份](li.李白的出生年份())** > print text=`year` EOF $M run n3.mq.md # 701 # C. 静态调用对象方法(应失败) cat > n2.mq.md <<'EOF' --- markup: occlusion import lb:lib2.mq.md --- # main **year = [出生年份](lb.李白.李白的出生年份())** > print text=`year` EOF $M run n2.mq.md # error: ... is an instance method ``` ### A.4 静态检查的假通过 ```bash cat > e1.mq.md <<'EOF' # main **x = > 不存在的函数 n=1** > print text=`x` EOF cat > e2.mq.md <<'EOF' # main **x = 未定义变量 + 1** > print text=`x` EOF $M check e1.mq.md; echo "exit=$?" # 0,输出 contract check OK $M run e1.mq.md; echo "exit=$?" # 1,unknown function $M check e2.mq.md; echo "exit=$?" # 0 $M run e2.mq.md; echo "exit=$?" # 1,undefined variable ``` ### A.5 `labels` 文档命令的假 0 ```bash cd /workspace/marqdo $M labels --count $M labels pending --count $M labels --grep 待开发 --count $M labels search --grep 待开发 --count ``` ### A.6 采用率统计 ```bash cd /workspace/marqdo for d in lib ext examples public tests; do t=$(find "$d" -name '*.mq.md' | wc -l) o=$(grep -rl '^markup: occlusion' --include='*.mq.md' "$d" 2>/dev/null | wc -l) echo "$d total=$t occlusion=$o" done $M labels --json # 迁移形中 label 与 key 完全相同的比例 find lib ext examples public tests -name '*.mq.md' -print0 \ | xargs -0 perl -ne 'while (/\[([^\]]+)\]\(access\(([^,]+),\s*"([^"]+)"\)\)/g) { $t++; $s++ if $1 eq $3; } END { print "total=$t same=$s\n" }' # total=231 same=204 ``` --- ## 附录 B:证据索引 | 主题 | 文件 | |------|------| | AST 节点 | [src/ast.rs:261](../../src/ast.rs#L261) | | 求值透明 | [src/interp.rs:1117](../../src/interp.rs#L1117) | | 字节码透明 | [src/bytecode/compile.rs:831](../../src/bytecode/compile.rs#L831) | | 默认 Classic | [src/parse/expr.rs:14](../../src/parse/expr.rs#L14) | | frontmatter 模式 | [src/load.rs:292](../../src/load.rs#L292) | | 标签检查 | [src/label.rs:1](../../src/label.rs#L1) | | `check` 只查契约+标签 | [src/check.rs:1](../../src/check.rs#L1) | | `mlsp validate` | [src/mlsp.rs:199](../../src/mlsp.rs#L199) | | `labels` 路径过滤 | [src/main.rs:631](../../src/main.rs#L631) | | EKC 图边 | [src/knowledge/graph.rs:1](../../src/knowledge/graph.rs#L1) | | `type: Fact` | [src/knowledge/extract.rs:313](../../src/knowledge/extract.rs#L313) | | 遮蔽渲染 | [src/view/render.rs:1227](../../src/view/render.rs#L1227) | | 遮蔽设计总纲 | [occlusion-syntax.md](../design/occlusion-syntax.md) | | 信任负债 | [occlusion-syntax.md:173](../design/occlusion-syntax.md#L173) | | 标签漂移/安全面 | [bracket-as-label-evaluation.md:160](../design/bracket-as-label-evaluation.md#L160) | | per-file 迁移 | [change-m7-migration.md:22](../design/change-m7-migration.md#L22) | | 点号寻址 / 实例方法 | [module-namespace.md:117](../design/module-namespace.md#L117) | | 对象 / 方法 | [objects.md:14](../design/objects.md#L14) | | 知识类型 | [engineering-knowledge.md:31](../design/engineering-knowledge.md#L31) | | 遮蔽测试 | [tests/occlusion.rs](../../tests/occlusion.rs) | --- ## 附录 C:术语 | 术语 | 本文用法 | |------|---------| | **遮蔽(occlusion)** | `[描述](实现)`;标签不执行,payload 执行;`[d](e) ≡ e` | | **遮蔽(shadowing)** | 编程语言里「内层绑定遮住外层」;**本文不取这个义**,但中文同名,需在文档里区分 | | **表达式** | 在当前环境求值的语法;`()` 里的东西 | | **引用(reference)** | 在命名空间里指称实体;应由解析器/链接器处理 | | **地址(address)** | 稳定 ID / 路径 / 锚点;引用的目标 | | **解析(resolution)** | 把名字/路径映射到实体,并检查可见性/类型 | | **呈现层** | 读者看到什么;标签、view、doc | | **语义层** | 程序能解析/验证/执行什么;作用域、类型、调用、模块 | | **L0–L5** | 本文的能力阶梯,见 §8.1 | --- ## 附录 D:局限 1. **GFM 渲染未在本机实测**:`[]()` 在 GFM 里渲染为 `` 是 CommonMark 规范推断(D),不是本机截图;但设计文档自己也说它「渲染成超链接」。 2. **未做性能/规模测试**:本文关注语义与工程规范,不评价 1000 标签文件的性能。 3. **未逐个审计 90 个 occlusion 文件**:采用率是机械计数;「label=key」统计是对 `access(...)` 形做的正则匹配(231/204),没有逐个人工判断语义。 4. **`type: Fact` 的运行时接入是提案**:当前代码只把它当 EKC 元数据;本文没有实现它。 5. **用户意图存在两种读法**(遮蔽 vs 引用):本文两种都评估了;如果用户本意只是「遮蔽」,那么 §3 的第 3/4/5 层失败仍然成立,只是「引用」部分不适用。 --- ## 附:一句话总结 > **遮蔽让读者不必读代码;引用让知识可以被找到。** > 前者是排版,后者是语义。 > Marqdo 现在有一个不错的排版层,但还没有语义层的地址、解析与验证。 > 把这两件事分开,才是「可执行知识」真正变成核心能力的开始。