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

37 KiB
Raw Permalink Blame History

链接语法:命名载荷、类-函数调用与可执行知识

状态 Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)
日期 2026-10-23
定位 []() 不新增语法:它是 Markdown 链接 + 已有表达式 + 已有 #/## 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据
取代/扩展 取代 occlusion-syntax.md 的「遮蔽」单一框架;把「遮蔽」保留为显示属性
证据复核 occlusion-vs-executable-knowledge-2026-10.md
示例 examples/link-syntax/
关联 knowledge-layers.md · module-namespace.md · objects.md · markdown-mapping-v0.3.md · engineering-knowledge.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 提供意图,二者共同形成可执行知识步骤。

例如:

**name = [订单收件人](at(订单, "收件人"))**
**gross = [含税金额](金额 * (1 + 税率))**
- [逐个订单行](遍历 订单.行 为 行)
订单总额为[含税总价](定价.订单定价.含税总价(订单))。

它们分别是观测、推导、过程和叙述调用;四者使用同一个 [](),在运行时都复用已有载荷语义, 但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源; 不能要求每一次取元或循环都伪造来源表。

这才同时实现三件事:

  • 代码即文档:函数内部的每一步都有可读意图,不是一个黑盒;
  • 文档即代码:正文中的命名步骤能解析到实际依赖和可选值;
  • 知识即可执行:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。

完整的跨文件闭环、稳定寻址和层次投影见 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 原始意图

第一个可执行文档:

# 李白

这个文档存储了李白的信息。

## 李白的出生年份

李白出生于*某年*

在 Marqdo 里:

  • # 李白 = 类;
  • ## 李白的出生年份 = 该类下的函数;
  • 李白.李白的出生年份 = 类调用这个函数。

注意:正文「李白出生于某年」是叙述;函数要可调用,需要显式返回值(*701* 或表,见 §2.6)。

第二个文档:

# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)

[] 是描述,() 是已有调用 李白.李白的出生年份。它不需要 print: view 模式天然显示 () 的调用信息。如果要终端输出,加一行 print 即可:

**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 描述永不执行,载荷唯一执行

[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 输出:值知识必须有值,过程知识必须声明效果

当一个 ## 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:

## 李白的出生年份

*701*

或者用表格/契约声明返回值。正文叙述可以保留(例如「李白出生于某年」),但叙述不是值;值知识要的是返回值/表。只有叙述、没有返回的函数:

  • run 得到 None;
  • check 报 link.no_value(warning/error,视知识链接用途);
  • view 显示「无返回值」;
  • 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值, 但 LinkInfo 必须记录输入、输出绑定和 effect,以便 view、权限检查与影响分析。

2.7 view 显示调用信息

代码链接:

┌─ 链接 ─────────────────────────────┐
│ `year` = [李白的出生年份]            │
│ → 李白.李白的出生年份                 │
│ class 李白 · function · () -> number │
│ value 701 · ok                      │
└────────────────────────────────────┘

正文链接:

用户想要知道李白的出生年份,我们要告诉用户 701。
                                      ↑
        悬浮:李白的出生年份 → 李白.李白的出生年份
              class 李白 · () -> number · value 701
  • Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
  • Execution 模式:显示值;
  • 点击目标:跳到目标文档/类/函数;
  • 错误:错误 chip + 诊断码 + 修复建议;
  • 无返回值:显示「无返回值」,不伪造值。

这就是「示例不带 print」的原因:view 显示调用信息;run 才需要 print 才有终端输出。

2.8 编译器返回 LinkInfo

每个 []() 产出:

{
  "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 链接既是步骤节点,也是图边

定价.订单定价 --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):

# 诗人                      # 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 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
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/。

6.1 用户原始示例(目标)

libai.mq.md:

# 李白

这个文档存储了李白的信息。

## 李白的出生年份

李白的出生年份是公元 701 年。

*701*

main.mq.md:

# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
  • view:正文链接显示 李白.李白的出生年份、类 李白、函数、签名、值 701;
  • run:无输出(正文链接不执行);加 print 才有终端输出;
  • check --json:LinkInfo(target/class/function/signature/status);
  • catalog:main.mq.md --calls--> libai.mq.md::李白.李白的出生年份。

6.2 加 print(终端输出)

# main

**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`

输出:701。

6.3 带参数

# main

**greeting = [问候](李白.问候("世界"))**
> print text=`greeting`

6.4 当前兼容写法(v2.0.0)

---
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:一页速查

# 类
## 函数
*701*

# 代码链接(求值)
**year = [出生年份](李白.李白的出生年份)**
> print text=`year`

# 正文链接(view/check 解析,run 不执行)
李白出生于 [李白的出生年份](李白.李白的出生年份)。

# 带参类调用
**g = [问候](李白.问候("世界"))**
写法 执行 用途
**类.函数** ✅ 普通代码/调用
[描述](类.函数)(代码内) ✅ 带描述的类调用
[描述](类.函数)(正文) ❌ run / ✅ view/check 知识链接
[描述](expr)(代码内) ✅ 本地表达式链接
[描述](url) ❌ 普通导航

附录 B:与旧文档的关系

旧文档 关系
occlusion-syntax.md 旧文把 []() 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性
occlusion-description-and-search.md 标签/桩/检索仍适用;本文把标签归入 LinkInfo
change-m7-migration.md 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 markup
objects.md 扩展:# 类是命名空间;## 不使用 self 时是类函数
module-namespace.md import 仍用于代码模块;链接额外支持项目类索引
engineering-knowledge.md 链接边接入 EKC 图