- 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。
800 lines
37 KiB
Markdown
Executable File
800 lines
37 KiB
Markdown
Executable File
# 链接语法:命名载荷、类-函数调用与可执行知识
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **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 图 |
|