Files
marqdo/doc/research/occlusion-vs-executable-knowledge-2026-10.md
cflmy 5ad1a07f5c docs(language): 链接语法与知识分层设计声明 + 示例
- []() 零新语法:描述 + 已有类/函数调用,不引入 ref/别名/开关
- # 是类、## 是函数;类.函数 是类调用;跨文档用项目类索引
- 知识分层:原始语料 / 本体 / 单体知识类 / 调用面;出处与还原验证
- 新增 link-syntax、knowledge-layers 设计声明与两组可运行/目标示例
2026-10-23 14:52:23 +08:00

1149 lines
50 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 遮蔽语法与可执行知识:一次以证据为准的复核
| | |
|---|---|
| 状态 | **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<Box<Expr>>,
}
```
- `label`:`[]` 里的自由文本,**不执行**,只被扫描关键词、检查反引号引用、做 T1 指纹;
- `payload`:`()` 里的表达式,**唯一执行**;
- `payload: None`:空载荷桩,值为 `None`。
### 2.2 求值:完全透明
来源:[src/interp.rs:1117](../../src/interp.rs#L1117)
```rust
// `<TAB>` 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 | 文内 `<<chunk>>`,非跨文档事实 | 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 里渲染为 `<a href="...">` 是 CommonMark 规范推断(D),不是本机截图;但设计文档自己也说它「渲染成超链接」。
2. **未做性能/规模测试**:本文关注语义与工程规范,不评价 1000 标签文件的性能。
3. **未逐个审计 90 个 occlusion 文件**:采用率是机械计数;「label=key」统计是对 `access(...)` 形做的正则匹配(231/204),没有逐个人工判断语义。
4. **`type: Fact` 的运行时接入是提案**:当前代码只把它当 EKC 元数据;本文没有实现它。
5. **用户意图存在两种读法**(遮蔽 vs 引用):本文两种都评估了;如果用户本意只是「遮蔽」,那么 §3 的第 3/4/5 层失败仍然成立,只是「引用」部分不适用。
---
## 附:一句话总结
> **遮蔽让读者不必读代码;引用让知识可以被找到。**
> 前者是排版,后者是语义。
> Marqdo 现在有一个不错的排版层,但还没有语义层的地址、解析与验证。
> 把这两件事分开,才是「可执行知识」真正变成核心能力的开始。