Files
marqdo/doc/design/link-syntax.md
T
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00

800 lines
37 KiB
Markdown
Raw 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.
# 链接语法:命名载荷、类-函数调用与可执行知识
| | |
|---|---|
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
| 日期 | 2026-10-23 |
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 |
| 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** |
| 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) |
| 示例 | [examples/link-syntax/](../../examples/link-syntax/) |
| 关联 | [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [engineering-knowledge.md](engineering-knowledge.md) · [view.md](view.md) |
---
## 0. 设计声明
### 0.1 一句话
> **`[]()` 本身不制作新语法。**
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。
### 0.1.1 还缺的一步:链接是「命名的可执行步骤」
`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。
所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。
> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。**
它始终同时有三种投影:
| 投影 | 规则 | 目的 |
|------|------|------|
| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 |
| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 |
| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 |
`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。
它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。
例如:
```markdown
**name = [订单收件人](at(订单, "收件人"))**
**gross = [含税金额](金额 * (1 + 税率))**
- [逐个订单行](遍历 订单.行 为 行)
订单总额为[含税总价](定价.订单定价.含税总价(订单))。
```
它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义,
但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源;
不能要求每一次取元或循环都伪造来源表。
这才同时实现三件事:
- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒;
- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值;
- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。
完整的跨文件闭环、稳定寻址和层次投影见
[executable-knowledge-system.md](executable-knowledge-system.md)。
### 0.2 三个「不新增」
| 不新增 | 说明 |
|--------|------|
| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 |
| **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 |
| **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 |
**本文定义四件事**:
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
### 0.3 原始意图
第一个可执行文档:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白出生于*某年*
```
在 Marqdo 里:
- `# 李白` = **类**;
- `## 李白的出生年份` = 该类下的**函数**;
- `李白.李白的出生年份` = **类调用这个函数**。
> 注意:正文「李白出生于*某年*」是**叙述**;函数要可调用,需要显式返回值(`*701*` 或表,见 §2.6)。
第二个文档:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`。它不需要 `print`:
**view 模式天然显示 `()` 的调用信息**。如果要终端输出,加一行 `print` 即可:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
这不是两套语法,而是同一套语法的两种呈现:
- `**year = 李白.李白的出生年份**` 是代码;
- `[李白的出生年份](李白.李白的出生年份)` 是**带描述的同一段代码**;
- `[描述](...)` 唯一新增的是「描述」与「view/compiler 元数据」,不是执行规则。
### 0.4 当前实现的偏差
v2.0.0 把「类-函数」收窄成了「实例方法」:
| 设计意图 | 当前实现 | 后果 |
|----------|---------|------|
| `# 李白` 是类 | `# 李白` 是对象/类型 | 可以,但 `##` 被当成实例方法 |
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
### 0.5 三个统一
| 统一 | 链接语法的作用 |
|------|---------------|
| **代码即文档** | 调用写在文档里;`**` 是代码,`[]()` 是同一段代码 + 人话描述 |
| **文档即知识库** | `#` 类是知识命名空间,`##` 函数是知识单元;`类.函数` 是地址 |
| **知识即可执行** | 链接解析到类/函数并求值;view 显示调用点;编译器返回 LinkInfo |
形式化:
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
---
## 1. 术语
| 术语 | 定义 |
|------|------|
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
| **类(class)** | `# 名称`;知识命名空间/类型 |
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
| **类调用(class call)** | `类.函数`;不构造实例,直接调用类函数 |
| **实例调用(instance call)** | `对象.函数`;对象是局部变量/实例,函数可使用 `self`/`自` |
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
---
## 2. 语义
### 2.1 描述永不执行,载荷唯一执行
```text
[label](expr) ≡ expr
```
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
- `()` 是唯一执行体;空 `()` 值为 `None`;
- `label.missing` / `label.empty_payload` 仍是结构诊断;
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
### 2.2 `#` 是类,`##` 是函数
| 标记 | 语义 |
|------|------|
| `# 名称` | 类/知识命名空间;正文是构造体 |
| `## 名称` | 类下的函数;可被 `类.函数` 调用 |
| `###` … | 更深层函数/子命名空间 |
| 顶层 `## 名称` | 模块级自由函数;可被 `模块.函数` 调用 |
**函数与实例的关系**:
- 函数体使用 `self` / `自` → **实例函数**,只能通过实例调用(`obj.函数`);
- 函数体不使用 `self` / `自` → **类函数**,可被 `类.函数` 直接调用;
- 类函数不执行 `# 类` 的构造体,不产生实例;
- 实例函数保留现有 `> 对象.函数` / `obj.函数()` 语义。
这条规则只用已有语法(`#`、`##`、`self`/`自`、`.`),不新增标记。
### 2.3 `类.函数` 是类调用
| 写法 | 语义 |
|------|------|
| `李白.李白的出生年份` | 类 `李白` 的零参函数 `李白的出生年份`;**隐式调用** |
| `李白.问候("世界")` | 类 `李白` 的函数 `问候`,带位置参数 |
| `李白.计税(档位=2, 金额=100)` | 具名参数,复用现有实参文法 |
| `obj.李白的出生年份()` | 实例调用;`obj` 是局部变量/实例 |
| `文档.李白.李白的出生年份` | 文档限定;用于同名类消歧 |
**隐式调用规则**:当点号路径解析到一个**零参函数**时,路径表达式就是调用,值为函数返回值;
带参数时必须写 `(...)`;解析到类名本身(无函数段)时,仍是类型/构造,不隐式调用。
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
### 2.4 跨文档:模块身份优先,类索引只做发现
链接目标可以跨文档。可运行代码的解析顺序:
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
2. **当前文档类/函数**:`# 类` / `## 函数`;
3. **已 import 的模块**:现有 `import bind:target` 绑定;
4. **内置/插件**。
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
按名加载机制:
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
- 排除 `# main`;
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
- 索引只在项目根内(`--fs-root`),不访问网络;
- 索引可缓存(按文件 mtime)。
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
### 2.5 `()` 与 `**代码**` 同权
| 能力 | `**代码**` | `[描述](载荷)` 的 `()` |
|------|-----------|----------------------|
| 算术/比较/布尔 | ✅ | ✅ 同一 parser |
| 变量/插值 | ✅ | ✅ |
| 本地调用 `callee(args)` | ✅ | ✅ |
| 类调用 `类.函数` | ✅ | ✅ |
| 实例调用 `obj.函数` | ✅ | ✅ |
| 表/列/映射 | ✅ | ✅ |
| 返回值 | Value | Value(同类型系统) |
| 副作用 | 可 | 可(受沙箱限制) |
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
**代码链接 vs 正文链接**:
| 上下文 | `[]()` 行为 |
|--------|-------------|
| `**...**` / `*...*` / 调用实参 / 表格单元格 | 代码链接:求值,参与表达式 |
| 正文(叙述) | 正文链接:view/check 解析并显示;`run` 不执行 |
| 标题 / frontmatter | 不执行;按普通文本处理 |
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
要终端输出,就把同一段代码放进代码链接并加 `print`。
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
### 2.6 输出:值知识必须有值,过程知识必须声明效果
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
```markdown
## 李白的出生年份
*701*
```
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
- `run` 得到 `None`;
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
- view 显示「无返回值」;
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
### 2.7 view 显示调用信息
**代码链接**:
```text
┌─ 链接 ─────────────────────────────┐
│ `year` = [李白的出生年份] │
│ → 李白.李白的出生年份 │
│ class 李白 · function · () -> number │
│ value 701 · ok │
└────────────────────────────────────┘
```
**正文链接**:
```text
用户想要知道李白的出生年份,我们要告诉用户 701。
↑
悬浮:李白的出生年份 → 李白.李白的出生年份
class 李白 · () -> number · value 701
```
- Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
- Execution 模式:显示值;
- 点击目标:跳到目标文档/类/函数;
- 错误:错误 chip + 诊断码 + 修复建议;
- 无返回值:显示「无返回值」,不伪造值。
**这就是「示例不带 print」的原因**:view 显示调用信息;`run` 才需要 `print` 才有终端输出。
### 2.8 编译器返回 LinkInfo
每个 `[]()` 产出:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "pricing.mq.md", "line": 18, "col": 3},
"inputs": [{"path": "订单.行", "type": "list<订单行>"}],
"outputs": [{"name": "行", "type": "订单行"}],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.pricing::订单定价.含税价"}
],
"effect": "pure",
"value": null,
"fingerprint": "sha256:…"
}
```
- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法;
- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导;
- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用;
- `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填;
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录
`LinkInfo` 至少要区分三类状态:
| 层 | 要回答的问题 | 典型状态 |
|------|-------------|----------|
| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` |
| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` |
| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` |
三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或
正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖
`link.unresolved` 或副作用越权。
来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。
这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。
### 2.9 链接既是步骤节点,也是图边
```text
定价.订单定价 --contains--> step#逐个订单行
step#逐个订单行 --observes--> 订单.行
step#逐个订单行 --calls--> 定价.订单定价.含税价
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
```
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
`narrates` 等边的一种;
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
- `catalog` 模块页显示「链接到/被链接」;
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
都可精确找出受影响的代码步骤和句子;
- view 的 Structure 面板显示上下游。
### 2.10 安全
| 风险 | 规则 |
|------|------|
| 类名歧义 | `link.ambiguous`;要求 `文档.类.函数` |
| 实例函数被类调用 | `link.instance_only`;提示用实例 |
| 构造副作用 | 类调用不执行构造体;不会隐式构造实例 |
| 函数副作用 | 目标函数可能写文件/发请求;`run`/live view 受沙箱限制;`check` 不执行 |
| 循环 | 链接图检测环;运行时深度/步数上限 |
| 路径逃逸 | 项目类索引只在根内;`--fs-root` 限制;不访问网络 |
| 标签欺骗 | 标签不可信;解析/权限只看 target,不看 label |
| view | 静态模式不执行;live 执行需用户操作;错误不吞 |
### 2.11 可复现(可选,生成物)
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
- 这是生成物/工具,不是新语法。
### 2.12 知识分层:类、知识个体、调用面
链接语法是**调用面**;它上面还有两层知识结构(详见 [knowledge-layers.md](knowledge-layers.md)):
```markdown
# 诗人 # L1 本体:类/模式
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# 李白 = > 诗人 # L2 知识个体:单体知识类
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
**术语**:
- `# 李白 = > 诗人` 是**知识个体/单体类**(语法上是继承/特化),不是运行时实例;
- `> 李白` 才是运行时实例(map + `_type`);
- `李白.李白的出生年份` 是类调用;
- `[]()` 是调用面,不新增语法。
**为什么不在 v2.1 引入运行时实例作为知识实体**:
- 运行时实例是值,不是文档里的稳定地址;跨文档链接需要实例注册表/导出;
- EKC 的节点是文档/类/函数,不是运行时 map;
- 单体类已经能表达「李白是诗人,李白有出生年份」,且零新语法。
---
## 3. 当前实现 vs 目标
### 3.1 已具备(v2.0.0)
| 能力 | 状态 | 证据 |
|------|------|------|
| `[描述](表达式)` 解析 | ✅ | `Expr::Occluded` / `markup: occlusion` |
| `()` 内 `callee(args)` | ✅ | M1;`加一 号(31)` |
| 本地表达式透明求值 | ✅ | `interp.rs:1117` |
| view 本地链接卡 | ✅ | `render.rs:1227` |
| 标签诊断/检索 | ✅ | `label.*` / `marqdo labels` |
| 实例调用 | ✅ | `obj.method()` / `> obj.method` |
### 3.2 缺失(v2.1 目标)
| 能力 | 状态 | 影响 |
|------|------|------|
| `类.函数` 类调用 | ❌ | `李白.李白的出生年份` 被当成变量/实例方法 |
| 跨文档类索引 | ❌ | 裸类名不解析;必须 import + 实例 |
| 统一 `[]()` 分类 | ❌ | 默认 Classic 下 `[]()` 是取元;需 `markup` |
| LinkInfo | ❌ | 编译器不返回链接信息 |
| view 目标/类/函数/值 | ⚠️ 只有本地卡片 | 没有跨文档目标信息 |
| 链接图边(EKC) | ❌ | 知识图不从链接取边 |
| 正文链接解析 | ❌ | 第二个文档的链接不解析 |
| 类函数契约/返回校验 | ❌ | 无返回值也不报 |
### 3.3 为什么旧例子失败
| 层 | 旧例子 | 设计要求 |
|----|--------|---------|
| 上下文 | 正文普通链接 | 正文链接由 view/check 解析(run 不执行) |
| 类索引 | 无 import | 项目类索引解析 `李白` |
| 调用 | `李白.李白的出生年份` 被当变量 | 解析为类函数,隐式调用 |
| 分派 | `##` 是实例方法 | 不使用 `self` 的函数是类函数 |
| 值 | 方法体无返回 | 知识函数必须返回 `701` |
| 静态检查 | 不解析 | `check` 报 `link.*` |
---
## 4. 编译器 / view / CLI 表面
### 4.1 `check --json`
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
- 不执行目标函数;
- `link.ok` 可作 info,不阻断;
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
### 4.2 MLSP
| method | 作用 |
|--------|------|
| `link.resolve` | 解析一个链接 → LinkInfo |
| `links.list` | 列出文件/项目所有链接 |
| `links.graph` | 返回链接图 |
| `link.check` | 校验一个链接 |
AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`/`run`。
### 4.3 `catalog` / EKC
- `catalog` 增加 `links:` 段与链接图;
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
### 4.4 `links` CLI(可选)
```bash
marqdo links list [PATH] --json
marqdo links resolve FILE:LINE:COL
marqdo links graph [PATH] --json
marqdo links lock [PATH] # 可选,生成指纹锁
```
### 4.5 诊断
| code | 级别 | 触发 | 建议 |
|------|------|------|------|
| `link.unresolved` | error | 类/函数/文档不存在 | 检查类名/文档名/拼写 |
| `link.ambiguous` | error | 同名类/函数 | 用 `文档.类.函数` 限定 |
| `link.instance_only` | error | 类调用命中实例函数 | 用实例 `obj.函数`,或去掉 `self` |
| `link.no_value` | warning | 知识函数无返回 | 加 `*值*` 或表/契约 |
| `link.arg_mismatch` | error | 参数数量/名称不匹配 | 按签名补/删 |
| `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 |
| `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 |
| `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 |
| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 |
| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock |
| `label.missing` | error | 空描述 | 写一句人话 |
| `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 |
---
## 5. 开发指导
### 5.1 里程碑
| 阶段 | 目标 | 交付 |
|------|------|------|
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
### 5.2 文件级改动
| 文件 | 改动 |
|------|------|
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
| `src/link.rs`(新增) | 模块/类解析、`Named<T>` 步骤记录、依赖/效果提取、诊断、指纹、图边 |
| `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 |
| `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` |
| `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 |
| `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 |
| `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 |
| `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 |
| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 |
| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 |
| `src/catalog.rs` | links 段/图 |
| `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` |
| `src/main.rs` | `links` 子命令;check 选项 |
| `README.md` | 链接语法章节(不新增语法) |
| `doc/README.md` | 登记本文/示例 |
| `examples/link-syntax/` | 用户原始示例 + compat |
### 5.3 关键实现点
1. **类函数判定**:扫描函数体是否出现 `self` / `自`;出现 → 实例函数;不出现 → 类函数。
2. **隐式调用**:点号路径解析到零参函数时,求值为调用;带参必须 `(...)`;解析到类名不调用。
3. **类索引**:只索引 `#`/`##` 名、签名、文件、行;排除 `# main`;同名报歧义。
4. **`[]()` 分类**:
- payload 是类/函数路径 → 知识链接;
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
- 正文 `[]()` → 正文链接(view/check)。
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
**最小改动原则**(证明「不新增语法」):
| 层 | 现状 | v2.1 改动 |
|----|------|-----------|
| parser | `[label](payload)` → `Occluded { label, payload }` | **不改 grammar**;可把节点改名为 `Bracket` 便于阅读 |
| payload | 已是表达式,`callee(args)` 已支持 | 不改;`类.函数` 是现有 dot path |
| AST | `Occluded { label, payload }` | 不新增 `Ref`/`Class` 节点;类/函数用现有 `Function`/`is_object` |
| resolver | 无 | **新增**:类索引 + `类.函数` 解析 + `self` 判定 |
| interp | 透明求值 payload | **新增**:dot path 解析到类函数时隐式调用 |
| view/check | 本地卡片/契约 | **新增**:正文 `[]()` 扫描 + LinkInfo |
| 语法 | — | **零新增**:没有协议前缀、别名、执行开关、模式关键字 |
> 当前 `李白.李白的出生年份` 在 AST 里是 `Var("李白.李白的出生年份")`(v2.0.0 实测报 `undefined variable`)。
> **不要依赖 parser 生成新节点**:resolver 按 `.` 拆分这个变量名,先找类 `李白`,再找函数 `李白的出生年份`;
> 找到后按类调用求值。若 parser 已生成 `Call { path: ["李白","李白的出生年份"] }`,同样按 path 解析。
### 5.4 测试
| 层 | 用例 |
|----|------|
| 单元 | `类.函数` 解析;零参隐式调用;带参;`self` 判定;同名歧义 |
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
| 双后端 | tree + bytecode 一致 |
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
### 5.5 迁移
- `#`/`##` 的实例调用保持;
- 不使用 `self` 的现有方法自动获得类调用能力(增量);
- `类.函数` 是新增解析,不改变旧调用;
- `[]()` 在 `markup: occlusion` 下继续是链接;在 Classic 下按 payload 分类,单标识符/集合仍是旧取元;
- 目标:v2.2 移除 `markup` 方言,统一按 payload 分类。
---
## 6. 示例
完整见 [examples/link-syntax/](../../examples/link-syntax/)。
### 6.1 用户原始示例(目标)
`libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白的出生年份是公元 701 年。
*701*
```
`main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
- `view`:正文链接显示 `李白.李白的出生年份`、类 `李白`、函数、签名、值 `701`;
- `run`:无输出(正文链接不执行);加 `print` 才有终端输出;
- `check --json`:LinkInfo(target/class/function/signature/status);
- `catalog`:`main.mq.md --calls--> libai.mq.md::李白.李白的出生年份`。
### 6.2 加 print(终端输出)
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 6.3 带参数
```markdown
# main
**greeting = [问候](李白.问候("世界"))**
> print text=`greeting`
```
### 6.4 当前兼容写法(v2.0.0)
```markdown
---
markup: occlusion
import:
libai: libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
输出 `701`。这只是**当前实现**的等价写法;v2.1 的目标是去掉 `import`/实例两步。
---
## 7. 验收标准
| # | 验收 | 判定 |
|---|------|------|
| 1 | 用户原始示例的 `view` 显示 `701` 与调用信息 | view 快照 |
| 2 | `**year = [..](李白.李白的出生年份)**` + `print` 输出 701 | run |
| 3 | `check --json` 返回 LinkInfo(class/function/signature/status) | link.ok |
| 4 | 类名改成不存在 → `link.unresolved` | 反例 |
| 5 | 同名类 → `link.ambiguous` | 反例 |
| 6 | 实例函数被类调用 → `link.instance_only` | 反例 |
| 7 | 无返回值 → `link.no_value` | 反例 |
| 8 | EKC 出现 `calls` 边 | graph.json |
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
**一句话验收**:
> **`[李白的出生年份](李白.李白的出生年份)` 不新增任何语法;`view` 能显示它,`check` 能解析它,`run` 加 `print` 能输出 701,`catalog` 能建边。**
> 四者缺一,说明 `#`/`##` 的类-函数语义还没补齐。
---
## 8. 风险与开放问题
| 风险 | 说明 | 缓解 |
|------|------|------|
| 类名歧义 | 多个 `# 李白` | `link.ambiguous`;`文档.类.函数` |
| 实例/类判定 | 依赖 `self`/`自` 扫描 | 明确规则;无法判定时 `link.instance_only` |
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
| 无返回值 | 知识函数只有叙述 | `link.no_value`;要求 `*值*`/表 |
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
| 旧取元歧义 | `[key](collection)` | 单标识符/集合按旧取元;`markup` 兼容;逐步迁移 |
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
**开放问题**:
1. 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
2. `# 类` 的构造体与类函数的关系?v1 类调用不构造;实例函数用 `self`。
3. 同名类跨文档是否允许?v1 报歧义;用 `文档.类.函数`。
4. 正文链接是否要在 `run` 中渲染?v1 不执行;view 显示;v1.1 可加 `--render-links`。
5. `[]()` 与旧取元的自动分类是否足够稳定?先保留 `markup` 兼容;v2.2 再移除。
6. 是否需要函数作为一等值?v1 不需要;`类.函数` 解析即调用。
---
## 9. 结论
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
v2.1 要补的是**语义**,不是语法:
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
2. `类.函数` → 类调用;跨文档用项目类索引;
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
**一句话**:
> **不是给 `[]()` 加语法,而是让 `#`/`##` 真正成为类/函数,让 `类.函数` 真正可调用;`[]()` 只是把这次调用写成一句人话。**
---
## 附录 A:一页速查
```markdown
# 类
## 函数
*701*
# 代码链接(求值)
**year = [出生年份](李白.李白的出生年份)**
> print text=`year`
# 正文链接(view/check 解析,run 不执行)
李白出生于 [李白的出生年份](李白.李白的出生年份)。
# 带参类调用
**g = [问候](李白.问候("世界"))**
```
| 写法 | 执行 | 用途 |
|------|------|------|
| `**类.函数**` | ✅ | 普通代码/调用 |
| `[描述](类.函数)`(代码内) | ✅ | 带描述的类调用 |
| `[描述](类.函数)`(正文) | ❌ run / ✅ view/check | 知识链接 |
| `[描述](expr)`(代码内) | ✅ | 本地表达式链接 |
| `[描述](url)` | ❌ | 普通导航 |
## 附录 B:与旧文档的关系
| 旧文档 | 关系 |
|--------|------|
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 |
| [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo |
| [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` |
| [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 |
| [module-namespace.md](module-namespace.md) | `import` 仍用于代码模块;链接额外支持项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | 链接边接入 EKC 图 |