# 链接语法:命名载荷、类-函数调用与可执行知识 | | | |---|---| | 状态 | **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` 的输入/输出/依赖/效果提取;类/模块解析;`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` 步骤记录、依赖/效果提取、诊断、指纹、图边 | | `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 图 |