Files
marqdo/doc/next/009.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

576 lines
25 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 的作者身上。
是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 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 框架,而是语言本身的语义能力。
我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。