Files
marqdo/doc/next/009.md
T

25 KiB
Raw Permalink Blame History

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。

它针对 v2.0.0 测试了一个典型案例:在一个文档里定义“李白的出生年份”,再由另一个文档通过链接读取。结果发现,正文链接没有进入执行 AST,跨文档类名没有得到解析,类函数不能直接调用,而且原始知识函数也没有实际返回值。

这份报告说明:问题不是 []() 的形式不够优美,而是链接背后的知识语义基础尚未建成。

这也解释了为什么你已经设计了链接语法,却还没有获得想象中的知识复用能力。

二、我建议保留你的两个目标,但增加第三个目标

目标一 · Presentation

自然语言呈现

用 [] 给复杂、不适合人类直接阅读的可执行表达式一个清楚的描述。

目标二 · Executable Reference

确定性知识引用

让 () 可以绑定已经编译、可解析、可验证的知识单元,而不仅是临时拼出的表达式。

目标三 · Knowledge Integrity

知识一致性保障

当知识定义、实现、版本、证据或适用条件变化时,能检测引用是否仍然有效,阻止 AI 把“能够运行”误认为“知识正确”。

第三个目标不是另加一种语法,而是让前两个目标真正成立所必须的编译器能力。

我倾向于把它称为 Verified Knowledge Reference(可验证知识引用)。

三、关键转变:不要把“函数”直接等同于“知识”

目前 link-syntax.md 的核心设计是:

[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 提出用 # 李白 = > 诗人 表示知识个体,也就是“单体知识类”。

这可以作为兼容实现路径,但我不建议把它提升为最终的知识本体。

因为“李白是诗人的一个个体”与“李白是诗人的子类”并不相同。让每一个事实实体都成为一个类,可能在知识库规模扩大后引入继承关系和个体关系的混淆。

更理想的是:让编译器内部明确区分 Type、Entity、Fact、Function、Capability 等制品类型。Markdown 源码可以继续使用现有的标题、表格和 frontmatter 承载这些信息,不要求立即增加新语法。

2. 不要让 check 与 EKC 各自维护一套知识理解

目前 EKC 已经有 Symbol、Capability、Knowledge、Graph 和 REUSE→ADAPT→CREATE 等概念。参见 engineering-knowledge.md。

这里完全没有必要再为 []() 平行开发另一套知识注册表。

我建议把架构整理成:

  • 编译器负责产出统一 Semantic IR、符号信息和引用关系;
  • check 消费这些信息进行验证;
  • EKC 将它们投影成知识图和上下文包;
  • view 消费同一份信息展示可读知识;
  • Agent 使用同一份引用解析接口,而不是重新理解 .mq.md 文本。

如此一来,编译器就是事实上的知识系统基础,EKC 不再承担第二次解释源码的职责。

3. 不要认为“描述过期”和“知识过期”是一回事

仓库中的 occlusion-syntax.md 已经意识到遮蔽会产生信任负债,并设计了标签引用一致性和新鲜度检查。这是有价值的方向。

但是,三类变化必须区分:

变化 应该检查什么
实现变了,描述没变 描述是否仍与行为一致
知识来源变了,函数没变 知识事实是否仍然有证据支持
引用目标变了,代码还能运行 是否仍满足原始契约和版本要求

尤其是第三种: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 的地方:它现在主要把链接理解为“表达式 + 描述 + 元数据”;下一版应明确规定,表达式可以解析到独立的、具有身份与验证状态的知识制品。

当这种绑定成立时,[]() 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。

而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 .mq.md 的作者身上。

是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 Marqdo 的最终目标。

实际上,这两者应当区分。

你最初提出的:

代码即文档,文档即知识库,知识即可执行。

并不只是一句理念性的口号,它本身已经包含了完整的目标链条:

  1. 代码即文档:知识与程序不再被割裂为两套独立的表达体系。
  2. 文档即知识库:文档中的内容不再只是供人阅读的信息,而是可以被组织、定位、理解和关联的知识。
  3. 知识即可执行:知识不再停留在被检索和解释的阶段,而是能够被直接调用、组合和复用。

其中,知识复用就是第三阶段最重要的结果之一。

因此,我之前提出的“可寻址、可验证、可执行、可复用”,实际上是在描述达成第三阶段需要具备的工程性质,而不是一个比原始理念更高层次的新目标。

真正需要解决的是:什么才算知识被复用?

我认为这里才是 Marqdo 当前设计最值得深入的地方。

假设 AI 需要计算一笔订单的最终价格。

传统方式可能是:

  • 检索价格计算文档;
  • 阅读文档中的公式和约束;
  • AI 自己理解并重新编写计算逻辑;
  • 执行新生成的代码。

这个过程中,知识被读取了,但未必真正被复用。AI 仍然可能理解错误、遗漏约束或生成不一致的实现。

而你想实现的 Marqdo 应该是:

订单最终价格为[计算后的价格](订单.最终价格(订单数据))。

这里 AI 不需要重新理解定价公式并生成一套新算法,而是引用已经存在的知识实现。

如果该实现的身份、依赖、契约和适用条件都能被确定,那么 AI 的任务就从:

“根据知识重新生成答案或程序”

转变成:

“发现知识 → 判断是否适用 → 引用知识 → 执行知识 → 使用结果”

这才是 Marqdo 的核心价值。

所以,[]() 应该承担什么角色?

我建议将整个体系理解成:

代码即文档

统一人类叙述与机器可执行内容

文档即知识库

知识具有结构、身份、关联与约束

知识即可执行

知识能够被确定性引用、调用和组合

知识真正复用

AI 优先使用既有知识,而非反复解释和重新生成

[]() 不需要独自完成这一切。

它应该成为整个体系中知识从文档进入使用场景的统一入口。

而编译器、符号系统、知识索引、验证系统与 EKC,则共同保证这个入口背后的知识可以可靠使用。

这里有一个很重要的区别:

  • []() 负责表达“我要使用这段知识”。
  • 编译器负责确定“究竟是哪段知识”。
  • 验证系统负责判断“这段知识是否满足当前使用条件”。
  • 运行时负责执行知识。

这些职责不应该全部压到 []() 的语法设计上。

我现在更倾向于保留你的原始理念

甚至不建议用我之前那段冗长的定义替换它。

“代码即文档,文档即知识库,知识即可执行”已经足够准确。

真正值得补充的是它背后的一个技术原则:

知识复用应当基于已编译知识的确定性引用,而不是基于自然语言的重复解释与生成。

这句话比单纯强调“可寻址、可验证”更接近你真正想解决的 AI 问题。

不过还需要保持一个边界:确定性引用能够减少 AI 在重新解释和生成过程中产生的错误,却不能自动保证被引用的知识本身正确。因此验证仍然必要,只是它属于实现可靠复用的手段。

我认为 Marqdo 下一步最值得研究的,已经不是“如何让文档变成知识库”,而是一个更具体的问题:

如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?

如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。

Marqdo 可执行知识体系:设计规范与完整范例

我已经基于 Marqdo 当前仓库的语法规范、[]() 设计、知识分层、对象模型和 EKC,整理了两份详细文档。

这次设计保留了你的原始理念:

代码即文档,文档即知识库,知识即可执行。

核心目标不是让 AI 更容易生成 Marqdo 代码,而是让 AI 尽可能不必重新生成已经存在的知识,转而通过编译器确定性地发现、引用、验证和执行既有知识。

第一份:完整架构设计规范

涵盖语义制品、知识引用、编译器架构、解析优先级、效应安全、版本管理、EKC 集成、Agent 复用协议和实施验收。

阅读设计文档

第二份:多文件可执行知识范例

以虚构书店定价为例,从原始政策文档开始,逐步构造知识定义、对象、计算能力、业务入口、AI 问答、知识复用和错误验证。

阅读完整示例

两份文档打包

下载 ZIP

一、这份设计最重要的三个决定

Marqdo 可执行知识体系:核心设计纲领

核心理念:代码即文档,文档即知识库,知识即可执行。

1. 知识是可编译的语义制品

文档经过 Marqdo 编译器处理后,不只产生可执行逻辑,还应产生具有稳定身份、类型、签名、契约、依赖关系、来源和验证状态的语义制品(Semantic Artifact)。

知识可以表现为事实、函数、能力、约束、数据集或类型。它们无需全部被强制编码为类。

2. []() 是知识使用的统一入口

[描述](目标) 保留 Markdown 的可读性。

  • [] 面向人类,描述意图、意义或用途。
  • () 面向编译器,包含既有 Marqdo 表达式或者可解析的知识目标。
  • 描述不改变执行结果,也不能作为可信性依据。
  • 编译器负责将目标解析为确定的符号身份,并验证使用条件。

既支持隐藏不易阅读的代码,也支持引用已经编译的知识。

3. AI 复用知识,而不是重新解释知识

AI 面对新任务时,应该遵循:

Discover → Resolve → Verify → Reuse → Execute → Trace

当知识缺失或不适用时,才进入 ADAPT 或 CREATE 流程。

检索可以模糊,但最终绑定必须确定。验证必须区分程序可执行性、契约符合性和现实事实正确性。

4. 编译器是知识系统的基础

AST、Semantic IR、符号索引、链接关系和知识验证应当由同一套语义体系产生。

解释器、字节码 VM、View、EKC 和 Agent 消费统一的编译结果,而不是各自重新解析文档。

5. 最终验收标准

一个 AI 能够发现现有知识、确定其身份、检查适用条件、直接执行既有能力、引用结果和来源,并在知识发生变化时识别受影响的调用者。

只有这条链条成立,Marqdo 才真正实现知识的可执行复用。

二、示例将展示什么

我选择了一个具有明确规则和复用价值的业务案例,而不只是使用“李白出生年份”这样的静态事实。

用户购买两件单价 60 元的商品,金卡折扣为 90%,满 100 元免运费。

AI 要处理的业务请求

请计算这笔金卡订单的最终应付款,并解释依据。

传统路径

检索政策 → AI 阅读规则 → 重新推导计算 → 生成新代码或答案

Marqdo 目标路径

发现定价能力 → 绑定已编译函数 → 检查输入与政策 → 执行 → 引用结果

目标语法示意(v2.1+,不是 v2.0.0 实测)

**应付 = [订单最终应付款](定价.计算应付金额(60, 2, "金卡"))**

根据演示政策计算

¥108

这套例子进一步展示了参数和返回值、类与继承、表格、条件分支、循环、跨文档调用、自然语言遮蔽,以及知识来源改变时的影响分析。

三、与当前版本的兼容边界

我特别保留了一个重要区分:设计目标不等于当前已经实现的功能。

根据这次读取的仓库内容,v2.0.0 已支持本地表达式遮蔽、对象、方法、控制流、表格集合、导入以及现有 EKC 基础;但无实例类函数调用、跨文档知识自动解析、完整 LinkInfo 和语义制品绑定仍需要进一步开发。

因此示例文档明确标注了目标语法和现有兼容写法,没有将尚未验证的代码描述为已经跑通。

四、我的主要架构建议

我认为接下来的开发不应该从 []() 的外观继续扩展,而应该先实现:

统一符号索引 → 稳定知识身份 → 引用绑定 → 契约验证 → EKC 复用。

还有一点值得特别强调:我不赞成为了建立知识系统,再单独实现一个与 Marqdo 解释器并列的“知识编译器”。那样会重新制造你希望消除的表示碎片。

更合适的架构是让现有 Marqdo 编译管线产出统一的语义中间表示,然后由运行时、View、EKC 和 Agent 各自消费。

这意味着 Marqdo 的知识体系不是一个外挂的 RAG 框架,而是语言本身的语义能力。

我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。