- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
37 KiB
Executable File
链接语法:命名载荷、类-函数调用与可执行知识
| 状态 | 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 链接形 |
本文定义四件事:
- 语义:
#/##如何形成类/函数,类.函数如何成为类调用;label如何命名任意既有载荷并形成知识步骤; - 解析:
()与**代码**共用 parser/evaluator;跨文档按类索引解析; - 校验:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
- 呈现: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 跨文档:模块身份优先,类索引只做发现
链接目标可以跨文档。可运行代码的解析顺序:
- 局部变量/对象:第一段是当前作用域变量 → 实例调用;
- 当前文档类/函数:
# 类/## 函数; - 已 import 的模块:现有
import bind:target绑定; - 内置/插件。
文件 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能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
4.4 links CLI(可选)
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 关键实现点
- 类函数判定:扫描函数体是否出现
self/自;出现 → 实例函数;不出现 → 类函数。 - 隐式调用:点号路径解析到零参函数时,求值为调用;带参必须
(...);解析到类名不调用。 - 类索引:只索引
#/##名、签名、文件、行;排除# main;同名报歧义。 []()分类:- payload 是类/函数路径 → 知识链接;
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
- payload 是单标识符且解析为集合 → 旧取元(兼容;
markup模式可强制链接); - 正文
[]()→ 正文链接(view/check)。
- 正文链接不执行:
run不改行为;view/check解析;要输出用代码链接 +print。 - LinkInfo:check/view/catalog 共用;任意
[]()都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。 - 图:每个
[]()是步骤节点;按角色建observes/derives/iterates/calls/acts/narrates边,来源只是其中一种边。 - 安全:类调用不构造实例;沙箱;根目录;标签不可信。
最小改动原则(证明「不新增语法」):
| 层 | 现状 | 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. 示例
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加catalog能建边。 四者缺一,说明#/##的类-函数语义还没补齐。
8. 风险与开放问题
| 风险 | 说明 | 缓解 |
|---|---|---|
| 类名歧义 | 多个 # 李白 |
link.ambiguous;文档.类.函数 |
| 实例/类判定 | 依赖 self/自 扫描 |
明确规则;无法判定时 link.instance_only |
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
| 无返回值 | 知识函数只有叙述 | link.no_value;要求 *值*/表 |
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
| 旧取元歧义 | [key](collection) |
单标识符/集合按旧取元;markup 兼容;逐步迁移 |
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
开放问题:
- 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
# 类的构造体与类函数的关系?v1 类调用不构造;实例函数用self。- 同名类跨文档是否允许?v1 报歧义;用
文档.类.函数。 - 正文链接是否要在
run中渲染?v1 不执行;view 显示;v1.1 可加--render-links。 []()与旧取元的自动分类是否足够稳定?先保留markup兼容;v2.2 再移除。- 是否需要函数作为一等值?v1 不需要;
类.函数解析即调用。
9. 结论
[]()不是新语法,它是「命名载荷 + 已有语义」的组合。#是类,##是函数,类.函数是类调用;()与**同权。 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
v2.0.0 把 ## 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 []() 收窄成了本地遮蔽。
v2.1 要补的是语义,不是语法:
#/##→ 类/函数;不使用self的函数是类函数;类.函数→ 类调用;跨文档用项目类索引;[]()→ 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;- 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 图 |