docs: define executable knowledge step architecture
This commit is contained in:
1 parent
1a13989230
commit
8bbe017a5e
10 files changed
+806
-68
No files matched your search
@@ -107,6 +107,7 @@
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
|
||||
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
|
||||
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
|
||||
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
|
||||
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
|
||||
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
|
||||
|
||||
@@ -0,0 +1,205 @@
|
||||
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Design Draft · v2.1 语义重构** |
|
||||
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
|
||||
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
|
||||
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
|
||||
|
||||
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
|
||||
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
|
||||
源位置、输入/输出、依赖和影响范围。
|
||||
|
||||
```text
|
||||
代码投影: eval([名称](载荷)) = eval(载荷)
|
||||
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
|
||||
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
|
||||
```
|
||||
|
||||
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
|
||||
三者同源,才是代码即文档、文档即知识、知识即可执行。
|
||||
|
||||
---
|
||||
|
||||
## 1. 统一节点:`Named<T>`
|
||||
|
||||
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
|
||||
|
||||
```text
|
||||
Named<T> { label, inner: T, span }
|
||||
```
|
||||
|
||||
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
|
||||
|
||||
| 既有位置 | `T` | 示例 | 知识角色 |
|
||||
|---|---|---|---|
|
||||
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
|
||||
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
|
||||
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
|
||||
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
|
||||
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
|
||||
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
|
||||
|
||||
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
|
||||
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
|
||||
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
|
||||
|
||||
### 1.1 每个节点都有角色,而不是两套语法
|
||||
|
||||
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
|
||||
|
||||
| role | 如何识别 | `check` 应问什么 |
|
||||
|---|---|---|
|
||||
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
|
||||
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
|
||||
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
|
||||
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
|
||||
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
|
||||
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
|
||||
|
||||
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
|
||||
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
|
||||
|
||||
---
|
||||
|
||||
## 2. 知识层不是目录隔离,而是同一图的不同投影
|
||||
|
||||
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
|
||||
同一份 `.mq.md` 可以同时有多层节点。
|
||||
|
||||
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|
||||
|---|---|---|---|
|
||||
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
|
||||
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
|
||||
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
|
||||
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
|
||||
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
|
||||
|
||||
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
|
||||
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
|
||||
这正是通用语法本身兼容知识体系的含义。
|
||||
|
||||
### 2.1 `#` / `##` 的位置
|
||||
|
||||
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
|
||||
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
|
||||
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
|
||||
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
|
||||
|
||||
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
|
||||
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
|
||||
`[]()` 是知识单元的内部结构。
|
||||
|
||||
---
|
||||
|
||||
## 3. 大项目的寻址:可读短名与稳定身份同时成立
|
||||
|
||||
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
|
||||
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
|
||||
|
||||
1. 文件的既有 frontmatter `id` 是稳定身份;
|
||||
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
|
||||
3. `#` / `##` 是人可读的路径段;
|
||||
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: knowledge.people.li-bai
|
||||
import li_bai:knowledge/people/li-bai.mq.md
|
||||
---
|
||||
|
||||
# 回答
|
||||
|
||||
**year = [李白的出生年份](li_bai.李白.出生年份)**
|
||||
李白出生于[公元 701 年](李白.出生年份)。
|
||||
```
|
||||
|
||||
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
|
||||
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
|
||||
而是可读的查询,必须由 lock 固化。
|
||||
|
||||
---
|
||||
|
||||
## 4. 每个 `[]()` 产生统一的知识记录
|
||||
|
||||
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "逐个订单行",
|
||||
"payload_kind": "loop",
|
||||
"roles": ["iterate"],
|
||||
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
|
||||
"inputs": ["订单.行"],
|
||||
"outputs": ["行"],
|
||||
"dependencies": [
|
||||
{"kind": "local_value", "path": "订单.行"},
|
||||
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
|
||||
],
|
||||
"effect": "pure",
|
||||
"fingerprint": "sha256:…"
|
||||
}
|
||||
```
|
||||
|
||||
此记录就是统一知识图节点:
|
||||
|
||||
- 本地取元有输入/类型边;
|
||||
- 纯计算有输入/输出/公式边;
|
||||
- 循环有集合、变量绑定和循环体边;
|
||||
- 调用有 `calls`/`uses` 边;
|
||||
- 有来源的事实再增加 `derived_from` 边;
|
||||
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
|
||||
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
|
||||
|
||||
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
|
||||
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
|
||||
|
||||
---
|
||||
|
||||
## 5. 闭环:写、跑、看、查、变
|
||||
|
||||
```text
|
||||
作者写 Named<T>
|
||||
│
|
||||
├─ run:擦除 label,按原语义执行
|
||||
├─ view:显示 label,可展开值、输入、步骤和来源
|
||||
└─ check:解析所有依赖,编译统一知识图
|
||||
│
|
||||
catalog / lock / context pack
|
||||
│
|
||||
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
|
||||
│
|
||||
作者或 agent 修复后重新 check/verify
|
||||
```
|
||||
|
||||
### 5.1 命令边界
|
||||
|
||||
| 操作 | 做什么 | 不做什么 |
|
||||
|---|---|---|
|
||||
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
|
||||
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
|
||||
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
|
||||
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
|
||||
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
|
||||
|
||||
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施顺序
|
||||
|
||||
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
|
||||
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
|
||||
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
|
||||
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
|
||||
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
|
||||
|
||||
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
|
||||
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
|
||||
+140
-68
@@ -1,10 +1,10 @@
|
||||
# 链接语法:类-函数调用与可执行知识
|
||||
# 链接语法:命名载荷、类-函数调用与可执行知识
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Design Declaration(v2.1 目标;v2.0.0 仅实现本地表达式链接)** |
|
||||
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
|
||||
| 日期 | 2026-10-23 |
|
||||
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;链接只是给一次调用加一个「人话名字」和 view/compiler 元数据 |
|
||||
| 定位 | `[]()` **不新增语法**:它是 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/) |
|
||||
@@ -19,21 +19,62 @@
|
||||
> **`[]()` 本身不制作新语法。**
|
||||
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
|
||||
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
|
||||
> 链接只是把「一次已有调用」写进文档,并给它一个人话名字;view 显示调用信息,编译器返回链接信息。
|
||||
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;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. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用,链接如何解析;
|
||||
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
|
||||
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
|
||||
3. **呈现**:view 显示调用点;编译器返回 LinkInfo;EKC 建边;lock 可选。
|
||||
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
|
||||
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
|
||||
|
||||
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
|
||||
|
||||
@@ -90,7 +131,7 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
|
||||
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
|
||||
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
|
||||
| 链接是「描述 + 已有调用」 | 被收窄成「遮蔽/本地表达式」 | 跨文档链接、LinkInfo、view 目标信息、图边缺失 |
|
||||
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
|
||||
|
||||
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
|
||||
|
||||
@@ -105,7 +146,7 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
形式化:
|
||||
|
||||
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
|
||||
> 链接不改变求值,只增加 label、view 呈现、编译器元数据、图边。
|
||||
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
|
||||
|
||||
---
|
||||
|
||||
@@ -113,8 +154,8 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
|
||||
| 术语 | 定义 |
|
||||
|------|------|
|
||||
| **链接语法** | `[描述](表达式)`;描述 inert,表达式是已有代码 |
|
||||
| **描述(label)** | `[]` 内自由文本;只用于显示、检索、诊断、LinkInfo;永不执行 |
|
||||
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
|
||||
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
|
||||
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
|
||||
| **类(class)** | `# 名称`;知识命名空间/类型 |
|
||||
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
|
||||
@@ -123,8 +164,8 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
|
||||
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
|
||||
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
|
||||
| **LinkInfo** | 编译器返回的链接信息:描述、源位置、目标类/函数、签名、状态、值/指纹 |
|
||||
| **链接图** | 文档/类/函数为点,链接为边;EKC/catalog/view 共用 |
|
||||
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
|
||||
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
|
||||
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
|
||||
|
||||
---
|
||||
@@ -137,10 +178,10 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
[label](expr) ≡ expr
|
||||
```
|
||||
|
||||
- `[]` 不进符号表、不参与求值、不改变作用域;
|
||||
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
|
||||
- `()` 是唯一执行体;空 `()` 值为 `None`;
|
||||
- `label.missing` / `label.empty_payload` 仍是结构诊断;
|
||||
- 链接的「知识性」来自 `expr` 的类/函数解析,不来自标签。
|
||||
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
|
||||
|
||||
### 2.2 `#` 是类,`##` 是函数
|
||||
|
||||
@@ -176,26 +217,27 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
|
||||
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
|
||||
|
||||
### 2.4 跨文档:类索引,不是新语法
|
||||
### 2.4 跨文档:模块身份优先,类索引只做发现
|
||||
|
||||
链接目标可以跨文档。解析顺序:
|
||||
链接目标可以跨文档。可运行代码的解析顺序:
|
||||
|
||||
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
|
||||
2. **当前文档类/函数**:`# 类` / `## 函数`;
|
||||
3. **已 import 的模块**:现有 `import bind:target` 绑定;
|
||||
4. **项目类索引**:扫描项目根下 `.mq.md` 的 `# 类` 与 `## 函数`;
|
||||
5. **内置/插件**。
|
||||
4. **内置/插件**。
|
||||
|
||||
项目类索引是**编译器/链接器的索引**,不是语法:
|
||||
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
|
||||
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
|
||||
按名加载机制:
|
||||
|
||||
- 只索引 `# 类` 名、`## 函数` 名、签名、文件位置;
|
||||
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
|
||||
- 排除 `# main`;
|
||||
- 同名类 → `link.ambiguous`,要求 `文档.类.函数` 限定;
|
||||
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
|
||||
- 索引只在项目根内(`--fs-root`),不访问网络;
|
||||
- 索引可缓存(按文件 mtime)。
|
||||
|
||||
> 这就是第二个文档能直接写 `李白.李白的出生年份` 的原因:
|
||||
> `李白` 是项目里的类名,编译器在类索引里找到它;不需要 `import`,也不需要协议前缀。
|
||||
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
|
||||
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
|
||||
|
||||
### 2.5 `()` 与 `**代码**` 同权
|
||||
|
||||
@@ -210,7 +252,8 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
| 返回值 | Value | Value(同类型系统) |
|
||||
| 副作用 | 可 | 可(受沙箱限制) |
|
||||
|
||||
**实现约束**:`[label](payload)` 的 payload 必须复用 `**代码**` 的表达式入口;禁止另造「简化表达式」。
|
||||
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
|
||||
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
|
||||
|
||||
**代码链接 vs 正文链接**:
|
||||
|
||||
@@ -223,11 +266,13 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
|
||||
要终端输出,就把同一段代码放进代码链接并加 `print`。
|
||||
|
||||
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 能解析为类/函数 → **知识链接**;payload 是 URL/相对路径且不是类/函数 → **导航链接**;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
|
||||
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
|
||||
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
|
||||
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
|
||||
|
||||
### 2.6 返回值:知识函数必须有值
|
||||
### 2.6 输出:值知识必须有值,过程知识必须声明效果
|
||||
|
||||
知识链接要「可执行」,目标函数必须返回一个值:
|
||||
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
|
||||
|
||||
```markdown
|
||||
## 李白的出生年份
|
||||
@@ -235,12 +280,13 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
*701*
|
||||
```
|
||||
|
||||
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;知识链接要的是返回值/表。只有叙述、没有返回的函数:
|
||||
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
|
||||
|
||||
- `run` 得到 `None`;
|
||||
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
|
||||
- view 显示「无返回值」;
|
||||
- 这不是语法问题,是知识单元没有编码值。
|
||||
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
|
||||
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
|
||||
|
||||
### 2.7 view 显示调用信息
|
||||
|
||||
@@ -278,37 +324,60 @@ v2.0.0 把「类-函数」收窄成了「实例方法」:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "李白的出生年份",
|
||||
"source": {"file": "main.mq.md", "line": 3, "col": 41},
|
||||
"target": {
|
||||
"class": "李白",
|
||||
"function": "李白的出生年份",
|
||||
"doc": "libai.mq.md",
|
||||
"kind": "class_function",
|
||||
"signature": {"params": [], "returns": "number"},
|
||||
"instance_only": false
|
||||
},
|
||||
"status": "ok",
|
||||
"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` 中可填;
|
||||
- `status`:`ok` / `unresolved` / `ambiguous` / `instance_only` / `no_value` / `arg_mismatch` / `type_mismatch` / `cycle` / `stale`;
|
||||
- `fingerprint`:目标函数体/签名哈希;用于过期检测(可选 lock);
|
||||
- `doc`:类所在文档;用于跳转/图边;
|
||||
- `kind`:`class_function` / `module_function` / `instance_method` / `table` / `unknown`。
|
||||
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
|
||||
|
||||
### 2.9 链接是图边
|
||||
### 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
|
||||
main.mq.md --calls--> libai.mq.md::李白.李白的出生年份
|
||||
定价.订单定价 --contains--> step#逐个订单行
|
||||
step#逐个订单行 --observes--> 订单.行
|
||||
step#逐个订单行 --calls--> 定价.订单定价.含税价
|
||||
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
|
||||
```
|
||||
|
||||
- EKC `graph.json` 增加 class/function 节点和 `calls`/`references` 边;
|
||||
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
|
||||
`narrates` 等边的一种;
|
||||
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
|
||||
- `catalog` 模块页显示「链接到/被链接」;
|
||||
- `find`/`impact`/`verify` 沿链接边遍历;
|
||||
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
|
||||
都可精确找出受影响的代码步骤和句子;
|
||||
- view 的 Structure 面板显示上下游。
|
||||
|
||||
### 2.10 安全
|
||||
@@ -326,9 +395,9 @@ main.mq.md --calls--> libai.mq.md::李白.李白的出生年份
|
||||
|
||||
### 2.11 可复现(可选,生成物)
|
||||
|
||||
- LinkInfo 带目标指纹;
|
||||
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
|
||||
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
|
||||
- `check --locked` 校验;目标变化 → `link.stale`;
|
||||
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
|
||||
- 这是生成物/工具,不是新语法。
|
||||
|
||||
### 2.12 知识分层:类、知识个体、调用面
|
||||
@@ -409,7 +478,7 @@ main.mq.md --calls--> libai.mq.md::李白.李白的出生年份
|
||||
|
||||
### 4.1 `check --json`
|
||||
|
||||
- 解析所有 `[]()`(代码 + 正文),输出 LinkInfo 与 `link.*` 诊断;
|
||||
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
|
||||
- 不执行目标函数;
|
||||
- `link.ok` 可作 info,不阻断;
|
||||
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
|
||||
@@ -428,8 +497,8 @@ AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`
|
||||
### 4.3 `catalog` / EKC
|
||||
|
||||
- `catalog` 增加 `links:` 段与链接图;
|
||||
- EKC `graph.json` 增加 class/function 节点与 `calls`/`references` 边;
|
||||
- `find`/`impact` 能按类/函数检索。
|
||||
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
|
||||
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
|
||||
|
||||
### 4.4 `links` CLI(可选)
|
||||
|
||||
@@ -452,6 +521,8 @@ marqdo links lock [PATH] # 可选,生成指纹锁
|
||||
| `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` 或真实目标 |
|
||||
|
||||
@@ -464,10 +535,10 @@ marqdo links lock [PATH] # 可选,生成指纹锁
|
||||
| 阶段 | 目标 | 交付 |
|
||||
|------|------|------|
|
||||
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
|
||||
| **L1** | 类索引 + 解析 | 项目类索引;`类.函数` 解析;`link.*` 诊断;LinkInfo |
|
||||
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
|
||||
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
|
||||
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
|
||||
| **L4** | 图 + lock | EKC 边;catalog;可选 lock/stale |
|
||||
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
|
||||
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
|
||||
|
||||
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
|
||||
@@ -480,15 +551,15 @@ L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
|
||||
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
|
||||
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
|
||||
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
|
||||
| `src/link.rs`(新增) | 类索引、`类.函数` 解析、LinkInfo、诊断、指纹、图边 |
|
||||
| `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 节点;`calls`/`references` 边 |
|
||||
| `src/knowledge/extract.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 选项 |
|
||||
@@ -507,8 +578,8 @@ L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
|
||||
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
|
||||
- 正文 `[]()` → 正文链接(view/check)。
|
||||
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
|
||||
6. **LinkInfo**:check/view/catalog 共用;不执行即可得目标/签名/状态。
|
||||
7. **图边**:链接是边;class/function 是节点;文档是容器。
|
||||
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
|
||||
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
|
||||
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
|
||||
|
||||
**最小改动原则**(证明「不新增语法」):
|
||||
@@ -535,7 +606,7 @@ L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
|
||||
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
|
||||
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
|
||||
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
|
||||
| 图 | EKC 边;catalog;impact |
|
||||
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
|
||||
| 双后端 | tree + bytecode 一致 |
|
||||
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
|
||||
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
|
||||
@@ -635,6 +706,7 @@ import libai:libai.mq.md
|
||||
| 8 | EKC 出现 `calls` 边 | graph.json |
|
||||
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
|
||||
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
|
||||
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
|
||||
|
||||
**一句话验收**:
|
||||
|
||||
@@ -670,17 +742,17 @@ import libai:libai.mq.md
|
||||
|
||||
## 9. 结论
|
||||
|
||||
> **`[]()` 不是新语法,它是「描述 + 已有调用」的组合。**
|
||||
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
|
||||
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
|
||||
> 链接只是给这次调用加一个名字,并让 view/compiler 能看见它。
|
||||
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
|
||||
|
||||
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
|
||||
v2.1 要补的是**语义**,不是语法:
|
||||
|
||||
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
|
||||
2. `类.函数` → 类调用;跨文档用项目类索引;
|
||||
3. `[]()` → 描述 + 已有调用;代码链接求值,正文链接由 view/check 解析;
|
||||
4. LinkInfo / view / EKC 图边 —— 让链接可查、可看、可建图。
|
||||
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
|
||||
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
|
||||
|
||||
**一句话**:
|
||||
|
||||
@@ -718,7 +790,7 @@ v2.1 要补的是**语义**,不是语法:
|
||||
|
||||
| 旧文档 | 关系 |
|
||||
|--------|------|
|
||||
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「描述 + 已有调用」;遮蔽只是显示属性 |
|
||||
| [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` 时是类函数 |
|
||||
|
||||
+346
@@ -0,0 +1,346 @@
|
||||
# Marqdo 的 `[]()`:从可读语法走向可验证的知识引用
|
||||
|
||||
我重新读取了仓库当前 `main` 分支(提交 `1a139892`)的 README、链接语法设计、知识分层设计,以及仓库中针对现有实现的复核报告。
|
||||
|
||||
这次我认为应当调整之前对 Marqdo 的评价:你提出的 `[]()` 不只是改善语法外观,它确实有机会成为 Marqdo 从“可执行文档”走向“可复用知识系统”的关键入口。
|
||||
|
||||
但当前设计有一个尚未解决的根本问题:
|
||||
|
||||
它已经尝试统一“可读描述”和“可执行表达式”,却还没有真正统一“知识的身份、知识的含义、知识的实现、知识的证据,以及知识的版本”。
|
||||
|
||||
仅仅让链接能解析到一个函数,并不能保证 AI 没有用错知识。仅仅让函数有一个确定的编译结果,也不能保证这个结果所表达的知识是真的。
|
||||
|
||||
这恰恰可能是你不断修改设计,却始终没有得到预期效果的原因。
|
||||
|
||||
## 一、先区分仓库已经实现了什么
|
||||
|
||||
当前 README 标明的是 v2.0.0,`doc/design/link-syntax.md` 将跨文档类函数调用列为 v2.1 目标。
|
||||
|
||||
| 能力 | 仓库当前状态 |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `[描述](表达式)` 本地遮蔽 | 已实现,主要通过 `markup: occlusion` |
|
||||
| `()` 中表达式求值 | 已实现 |
|
||||
| 用自然语言描述隐藏复杂代码 | 已实现基础能力 |
|
||||
| `类.函数` 直接调用 | 设计目标,尚未按文档实现 |
|
||||
| 跨文档自动解析知识目标 | 设计目标 |
|
||||
| 编译器生成 LinkInfo | 设计目标 |
|
||||
| 链接进入 EKC 知识图 | 设计目标 |
|
||||
| 版本指纹和链接锁定 | 设计目标 |
|
||||
|
||||
仓库还有一份很重要的复核报告:[occlusion-vs-executable-knowledge-2026-10.md](https://github.com/cflmy/marqdo/blob/main/doc/research/occlusion-vs-executable-knowledge-2026-10.md?utm_source=chatgpt.com)。
|
||||
|
||||
它针对 v2.0.0 测试了一个典型案例:在一个文档里定义“李白的出生年份”,再由另一个文档通过链接读取。结果发现,正文链接没有进入执行 AST,跨文档类名没有得到解析,类函数不能直接调用,而且原始知识函数也没有实际返回值。
|
||||
|
||||
这份报告说明:问题不是 `[]()` 的形式不够优美,而是链接背后的知识语义基础尚未建成。
|
||||
|
||||
这也解释了为什么你已经设计了链接语法,却还没有获得想象中的知识复用能力。
|
||||
|
||||
## 二、我建议保留你的两个目标,但增加第三个目标
|
||||
|
||||
目标一 · Presentation
|
||||
|
||||
自然语言呈现
|
||||
|
||||
用 `[]` 给复杂、不适合人类直接阅读的可执行表达式一个清楚的描述。
|
||||
|
||||
目标二 · Executable Reference
|
||||
|
||||
确定性知识引用
|
||||
|
||||
让 `()` 可以绑定已经编译、可解析、可验证的知识单元,而不仅是临时拼出的表达式。
|
||||
|
||||
目标三 · Knowledge Integrity
|
||||
|
||||
知识一致性保障
|
||||
|
||||
当知识定义、实现、版本、证据或适用条件变化时,能检测引用是否仍然有效,阻止 AI 把“能够运行”误认为“知识正确”。
|
||||
|
||||
第三个目标不是另加一种语法,而是让前两个目标真正成立所必须的编译器能力。
|
||||
|
||||
我倾向于把它称为 Verified Knowledge Reference(可验证知识引用)。
|
||||
|
||||
## 三、关键转变:不要把“函数”直接等同于“知识”
|
||||
|
||||
目前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的核心设计是:
|
||||
|
||||
```
|
||||
[label](expr) ≡ expr
|
||||
```
|
||||
|
||||
它规定标签不改变计算语义,链接只为表达式增加人类描述和编译器元数据。
|
||||
|
||||
这个规则作为表达式语义是合理的,但作为完整知识模型还不够。
|
||||
|
||||
原因在于,至少有三种不同的东西可能进入 `()`:
|
||||
|
||||
| 内容 | 例子 | 实质 |
|
||||
| ---- | ---------------------------- | --------------- |
|
||||
| 表达式 | `[税额](amount * rate)` | 一次计算 |
|
||||
| 函数 | `[计算税额](Tax.calculate(100))` | 一种计算能力的调用 |
|
||||
| 知识事实 | `[适用税率](TaxPolicy.rate)` | 一项具有来源、范围、版本的知识 |
|
||||
|
||||
第三种不能只靠前两种来解释。
|
||||
|
||||
例如,编译器能确定 `TaxPolicy.rate` 返回 `0.10`,只能证明“目标被正确解析并返回该值”,不能证明“2026 年某个地区、某种业务适用的税率确实是 10%”。
|
||||
|
||||
确定性执行和知识真实性是两个独立维度。
|
||||
|
||||
我建议把 Marqdo 的知识模型扩展为以下结构:
|
||||
|
||||
Markdown 文档
|
||||
|
||||
自然语言叙述、表格、函数与知识定义
|
||||
|
||||
Semantic Artifact · 语义制品
|
||||
|
||||
稳定身份、类型、签名、实现、契约、依赖、证据
|
||||
|
||||
Verified Knowledge Reference
|
||||
|
||||
解析引用、检查约束、固定版本、判定可否复用
|
||||
|
||||
解释执行
|
||||
|
||||
知识检索
|
||||
|
||||
AI 复用
|
||||
|
||||
这里最重要的新概念不是链接,而是 Semantic Artifact(语义制品)。
|
||||
|
||||
它应当是 Marqdo 编译器第一次真正统一代码、文档与知识的中间产物。
|
||||
|
||||
### 一个语义制品应该包含什么?
|
||||
|
||||
建议最小模型如下。这里是我的架构提案,不是当前仓库已经实现的格式。
|
||||
|
||||
```
|
||||
{
|
||||
"id": "knowledge://project/TaxPolicy/rate",
|
||||
"kind": "fact",
|
||||
"signature": {
|
||||
"params": [],
|
||||
"returns": "number"
|
||||
},
|
||||
"implementation": {
|
||||
"ir": "compiled-reference",
|
||||
"digest": "sha256:..."
|
||||
},
|
||||
"contract": {
|
||||
"unit": "ratio",
|
||||
"scope": "example-policy",
|
||||
"effects": "pure"
|
||||
},
|
||||
"provenance": {
|
||||
"source": "policy.md#rate",
|
||||
"digest": "sha256:..."
|
||||
},
|
||||
"verification": {
|
||||
"status": "verified",
|
||||
"methods": ["source-check", "contract-test"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中 `id` 是符号身份,`implementation.digest` 是编译内容指纹,`provenance` 是来源证据,`verification` 是验证记录。
|
||||
|
||||
这样一来,AI 复用的对象就不再是“某个名字看起来正确的函数”,而是一个具有明确身份和约束的知识制品。
|
||||
|
||||
需要注意:这里的 `verified` 只能表示通过了所声明的验证方法,不能凭此宣称该知识在所有现实情境下都正确。
|
||||
|
||||
## 四、重新定义 `[]()`:统一写法,不强行统一所有行为
|
||||
|
||||
我建议继续保持你所追求的语法纯度:
|
||||
|
||||
```
|
||||
[人类可读的描述](机器可解析的目标)
|
||||
```
|
||||
|
||||
不引入额外的 `knowledge:`、`call:` 或 `ref:` 前缀,也不让 AI 记忆复杂的新标记。
|
||||
|
||||
但编译器必须区分目标的性质,而不是把一切都当作普通表达式立即求值。
|
||||
|
||||
A · 表达式遮蔽
|
||||
|
||||
计算
|
||||
|
||||
```
|
||||
**total = [应付总额](price * quantity + shipping)**
|
||||
```
|
||||
|
||||
对原有表达式的透明包装。编译后仍是普通表达式,描述不改变值。
|
||||
|
||||
B · 能力引用
|
||||
|
||||
复用
|
||||
|
||||
```
|
||||
**total = [计算应付总额](Pricing.total(订单))**
|
||||
```
|
||||
|
||||
解析到已编译函数,检查参数、类型、依赖、权限和版本,然后调用。
|
||||
|
||||
C · 知识事实引用
|
||||
|
||||
知识
|
||||
|
||||
```
|
||||
用户可以查阅[李白的出生年份](李白.出生年份)。
|
||||
```
|
||||
|
||||
解析到知识制品;view 展示事实、来源和验证状态。正文保持惰性,不自动产生副作用。
|
||||
|
||||
这种设计保留了 `[label](expr) ≡ expr` 的计算规则,但增加了一个重要条件:编译器首先要解析 `expr` 的目标类型,然后才能决定它应该怎样验证、绑定和使用。
|
||||
|
||||
这不会使语言多出三套语法,反而能够避免当前设计中“语法统一了,但知识语义仍然散落在工具中”的问题。
|
||||
|
||||
## 五、你的第二个目标,最关键的是“绑定”而不是“调用”
|
||||
|
||||
假设有这样一份知识文档:
|
||||
|
||||
```
|
||||
# 李白
|
||||
|
||||
## 出生年份
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|---|---|---|
|
||||
| 701 | number | corpus/libai.md#birth |
|
||||
|
||||
*701*
|
||||
```
|
||||
|
||||
另一个文档写:
|
||||
|
||||
```
|
||||
李白的[出生年份](李白.出生年份)是 701 年。
|
||||
```
|
||||
|
||||
理想情况下,编译器应该执行一条确定性的处理链:
|
||||
|
||||
Resolve — 查找 `李白.出生年份` 指向哪个知识单元
|
||||
|
||||
Bind — 绑定稳定 Symbol ID,而不是仅保存字符串
|
||||
|
||||
Validate — 检查返回类型、来源、契约与依赖
|
||||
|
||||
Pin — 根据需要固定知识版本和内容指纹
|
||||
|
||||
Evaluate — 仅在允许执行的上下文中求值
|
||||
|
||||
Trace — 将引用关系、验证结果与来源写入知识图
|
||||
|
||||
此时,编译器内部的引用不应该只是:
|
||||
|
||||
```
|
||||
"李白.出生年份"
|
||||
```
|
||||
|
||||
而应该更接近:
|
||||
|
||||
```
|
||||
KnowledgeRef {
|
||||
target_symbol_id,
|
||||
resolved_artifact_id,
|
||||
expected_signature,
|
||||
pinned_digest,
|
||||
verification_policy,
|
||||
source_span
|
||||
}
|
||||
```
|
||||
|
||||
其中的 `target_symbol_id` 解决“引用谁”,`pinned_digest` 解决“引用哪个版本”,`verification_policy` 解决“什么时候可以信任它”。
|
||||
|
||||
这才是让 AI 不必重新生成已有知识,而是能够确定性地调用已有知识的技术基础。
|
||||
|
||||
还有一个必须考虑的问题:如果编译器只记录函数源码哈希,而函数内部调用的其他知识已经发生变化,那么源码没有变,实际执行语义也可能已经变化。因此,至少要对调用依赖形成可追踪的版本关系;对需要严格复现的纯函数,还应生成包含传递依赖的制品指纹。对于网络请求、时间、随机数等外部效应,则必须记录环境和执行条件,不能简单承诺重放一定得到相同结果。
|
||||
|
||||
## 六、仓库当前设计里,我最想修改的三个地方
|
||||
|
||||
### 1. 不要继续把类当作所有知识的唯一载体
|
||||
|
||||
[knowledge-layers.md](https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md?utm_source=chatgpt.com) 提出用 `# 李白 = > 诗人` 表示知识个体,也就是“单体知识类”。
|
||||
|
||||
这可以作为兼容实现路径,但我不建议把它提升为最终的知识本体。
|
||||
|
||||
因为“李白是诗人的一个个体”与“李白是诗人的子类”并不相同。让每一个事实实体都成为一个类,可能在知识库规模扩大后引入继承关系和个体关系的混淆。
|
||||
|
||||
更理想的是:让编译器内部明确区分 `Type`、`Entity`、`Fact`、`Function`、`Capability` 等制品类型。Markdown 源码可以继续使用现有的标题、表格和 frontmatter 承载这些信息,不要求立即增加新语法。
|
||||
|
||||
### 2. 不要让 `check` 与 EKC 各自维护一套知识理解
|
||||
|
||||
目前 EKC 已经有 Symbol、Capability、Knowledge、Graph 和 REUSE→ADAPT→CREATE 等概念。参见 [engineering-knowledge.md](https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md?utm_source=chatgpt.com)。
|
||||
|
||||
这里完全没有必要再为 `[]()` 平行开发另一套知识注册表。
|
||||
|
||||
我建议把架构整理成:
|
||||
|
||||
- 编译器负责产出统一 Semantic IR、符号信息和引用关系;
|
||||
- `check` 消费这些信息进行验证;
|
||||
- EKC 将它们投影成知识图和上下文包;
|
||||
- `view` 消费同一份信息展示可读知识;
|
||||
- Agent 使用同一份引用解析接口,而不是重新理解 `.mq.md` 文本。
|
||||
|
||||
如此一来,编译器就是事实上的知识系统基础,EKC 不再承担第二次解释源码的职责。
|
||||
|
||||
### 3. 不要认为“描述过期”和“知识过期”是一回事
|
||||
|
||||
仓库中的 [occlusion-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/occlusion-syntax.md?utm_source=chatgpt.com) 已经意识到遮蔽会产生信任负债,并设计了标签引用一致性和新鲜度检查。这是有价值的方向。
|
||||
|
||||
但是,三类变化必须区分:
|
||||
|
||||
| 变化 | 应该检查什么 |
|
||||
| ------------- | -------------- |
|
||||
| 实现变了,描述没变 | 描述是否仍与行为一致 |
|
||||
| 知识来源变了,函数没变 | 知识事实是否仍然有证据支持 |
|
||||
| 引用目标变了,代码还能运行 | 是否仍满足原始契约和版本要求 |
|
||||
|
||||
尤其是第三种:AI 幻觉可能表现为调用了一个真实存在、类型也正确、但是业务含义完全错误的函数。
|
||||
|
||||
纯粹的符号解析和类型检查抓不住这种错误。因此,需要让能力契约、适用范围和知识来源成为可检查的制品属性,而不是只依赖 `[]` 中的自然语言。
|
||||
|
||||
## 七、建议的实施顺序
|
||||
|
||||
不要一次性实现完整知识图谱、版本锁定、自动修复和复杂本体系统。我建议分成四个阶段,每一阶段都必须有独立的可执行验收。
|
||||
|
||||
| 阶段 | 核心交付 | 必须通过的测试 |
|
||||
| ------------ | ------------------------------------- | ---------------------------------- |
|
||||
| P0 · 统一引用语义 | `[]()` 的统一 AST、目标类型识别、正文/代码上下文区分 | 不再因 Classic/Occlusion 模式造成静默错义 |
|
||||
| P1 · 稳定寻址 | 项目符号索引、类函数解析、稳定 Symbol ID、静态 LinkInfo | 两文档李白示例无需实例化即可完成解析与引用 |
|
||||
| P2 · 可验证知识制品 | Semantic Artifact、契约、来源、指纹、统一诊断 | 删除目标、修改签名、改变来源,均得到准确诊断 |
|
||||
| P3 · 确定性复用 | 依赖图、制品锁定、EKC 集成、Agent 引用优先策略 | AI 不重新生成已存在的能力;错误、过期和不适用的知识被阻止直接复用 |
|
||||
|
||||
我特别建议设置一个不依赖 LLM 的核心验收实验:
|
||||
|
||||
准备 100 个知识单元,包含同名符号、跨文档引用、版本变更、类型不匹配、来源缺失、循环依赖和正常复用。由程序自动生成和验证预期结果。
|
||||
|
||||
先证明编译器能够正确识别、绑定和诊断这些情况,再引入 AI 测试上下文成本和幻觉率。否则很容易把模型能力、索引召回率与编译器的正确性混在一起。
|
||||
|
||||
## 八、重新评价 Marqdo 的研究主张
|
||||
|
||||
过去 Marqdo 的核心叙述是:
|
||||
|
||||
> 代码即文档,文档即知识库,知识即可执行。
|
||||
|
||||
我认为现在可以把它变得更加严格:
|
||||
|
||||
Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行、可复用的知识制品的语言与编译系统。
|
||||
|
||||
这个定位的价值不在于“Markdown 可以运行代码”,也不在于“Markdown 链接能调用函数”。这两点单独来看都不足以形成很强的研究贡献。
|
||||
|
||||
它真正值得探索的创新组合是:
|
||||
|
||||
一份自然语言与程序混合的源码,经过统一编译后,同时生成可执行程序、语义符号体系、验证证据、版本化知识引用和 AI 可消费的复用接口。
|
||||
|
||||
当然,这仍然是一个待证明的系统设计目标,而不是当前 v2.0.0 已经达到的状态。
|
||||
|
||||
## 最终判断
|
||||
|
||||
你的 `[]()` 方向值得保留,甚至值得作为下一轮 Marqdo 核心架构调整的切入点。但我不建议继续把主要精力投入到如何让 `[]()` 兼容更多语法、更多函数调用形式或更多 Markdown 场景。
|
||||
|
||||
你现在缺少的不是更漂亮的链接语法,而是一个由编译器负责维护的“知识身份与语义绑定层”。
|
||||
|
||||
这也是我认为应该优先修正当前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的地方:它现在主要把链接理解为“表达式 + 描述 + 元数据”;下一版应明确规定,表达式可以解析到独立的、具有身份与验证状态的知识制品。
|
||||
|
||||
当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。
|
||||
|
||||
而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 可执行知识系统示例:订单含税总额
|
||||
|
||||
这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例。
|
||||
它刻意展示 `[]()` 不只包“知识函数”:同一套语法同时命名取元、循环、推导、跨文件调用和正文结论。
|
||||
|
||||
| 文件 | 图中的职责 | 关键步骤 |
|
||||
|---|---|---|
|
||||
| `corpus/tax-policy-2026.md` | E:证据 | 税率原文 |
|
||||
| `schema/order.mq.md` | C:概念 | 订单/订单行字段与单位 |
|
||||
| `knowledge/tax-2026.mq.md` | K:原子知识 | `[标准税率](0.13)` 及来源 |
|
||||
| `capabilities/order-pricing.mq.md` | D:推导知识 | 取元、调用、循环、汇总 |
|
||||
| `docs/invoice-answer.mq.md` | N:叙述知识 | 用同一个计算给人可读的回答 |
|
||||
|
||||
## 读法
|
||||
|
||||
`[]()` 的每一次出现都是 `Named<T>`:
|
||||
|
||||
```markdown
|
||||
[订单行金额](at(行, "金额")) # observe
|
||||
[本行含税价](订单行金额 * (1 + 税率)) # derive
|
||||
[逐个订单行](遍历 订单.行 为 行) # iterate
|
||||
[含税总价](pricing.订单定价.含税总额(订单)) # reuse / narrate
|
||||
```
|
||||
|
||||
它们不是四种语法。`()` 中仍是原有的取元、算术、循环和调用;`[]` 让每一步同时可读、可查、
|
||||
可在图中定位。当前实现尚不能完整运行该目标形式(类函数、统一 `Named<T>`、步骤图仍是设计目标),
|
||||
但它给出了实际项目中应当写成什么样子。
|
||||
|
||||
## 预期闭环
|
||||
|
||||
1. `check` 从每个 `[]()` 提取观测、推导、遍历和调用依赖;
|
||||
2. `view` 在“含税总额”旁显示所经过的订单行、标准税率和税率原文;
|
||||
3. 税率原文变更时,`impact` 找到原子税率、订单定价、发票回答中的每一个命名步骤;
|
||||
4. `verify` 只重算 pure 步骤,不执行写入或发送等 `act` 步骤;
|
||||
5. agent 通过 catalog 得到“已有订单定价能力”和其证据链,不必从自然语言猜测。
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
id: capability.order-pricing
|
||||
type: Capability
|
||||
import tax:../knowledge/tax-2026.mq.md
|
||||
import order:../schema/order.mq.md
|
||||
---
|
||||
|
||||
# 订单定价
|
||||
|
||||
## 含税价
|
||||
+ `行`
|
||||
|
||||
**金额 = [订单行金额](at(行, "金额"))**
|
||||
**品类 = [订单行品类](at(行, "品类"))**
|
||||
**税率 = [适用税率](tax.标准税率.查询(品类))**
|
||||
**结果 = [本行含税价](金额 * (1 + 税率))**
|
||||
**结果**
|
||||
|
||||
## 含税总额
|
||||
+ `订单`
|
||||
|
||||
- [逐个订单行](遍历 订单.行 为 行)
|
||||
**行含税价 = [计算本行含税价](订单定价.含税价(行))**
|
||||
|
||||
**总额 = [汇总全部行含税价](sum(行含税价))**
|
||||
**总额**
|
||||
@@ -0,0 +1,5 @@
|
||||
# 2026 年标准增值税率
|
||||
|
||||
本示例的原始证据:标准税率为 13%。
|
||||
|
||||
此文件只作来源定位,不执行。
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: document.invoice-answer
|
||||
type: Answer
|
||||
import pricing:../capabilities/order-pricing.mq.md
|
||||
---
|
||||
|
||||
# 发票回答
|
||||
|
||||
**总额 = [订单的含税总价](pricing.订单定价.含税总额(订单))**
|
||||
|
||||
这张订单的含税总额是[含税总价](总额)。
|
||||
|
||||
> view 应可展开:含税总价 → 汇总全部行含税价 → 逐个订单行 → 本行含税价 → 适用税率 → 税率原文。
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
id: knowledge.tax.standard-2026
|
||||
type: Fact
|
||||
sources:
|
||||
- ../corpus/tax-policy-2026.md#2026 年标准增值税率
|
||||
---
|
||||
|
||||
# 标准税率
|
||||
|
||||
## 查询
|
||||
+ `品类`
|
||||
|
||||
| 返回 | 类型 | 来源 |
|
||||
|---|---|---|
|
||||
| 0.13 | number | corpus/tax-policy-2026.md#2026 年标准增值税率 |
|
||||
|
||||
**税率 = [标准税率](0.13)**
|
||||
**税率**
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: schema.order
|
||||
type: Schema
|
||||
---
|
||||
|
||||
# 订单
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 行 | list<订单行> | 待计价的订单行 |
|
||||
|
||||
## 订单行
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 金额 | number | 未税金额 |
|
||||
| 品类 | text | 用于选择税率 |
|
||||
Reference in new issue
Block a user