Files
marqdo/doc/design/knowledge-layers.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

17 KiB
Executable File
Raw Blame History

知识分层:原始语料、可执行知识、调用面

状态 Design Review · Recommended(v2.1 语法设计评审)
日期 2026-10-23
问题 「诗人类 → 用李白知识实例化 → []() 调用」的三/四层模型,从语法设计上是否自洽?
推荐 单体知识类(singleton knowledge class):# 诗人 是类,# 李白 = > 诗人 是知识个体;李白.出生年份 是类调用;零新语法
关联 link-syntax.md · objects.md · module-namespace.md · engineering-knowledge.md · okf.md
示例 examples/knowledge-layers/

0. 结论先行

0.1 一句话

分层逻辑是自洽的;不自洽的是「实例化」这个词与当前 #/= > 语法。 如果「实例化」指知识个体,用 # 李白 = > 诗人 编码即可,零新语法; 如果「实例化」指运行时对象,就需要新的可寻址实例声明/注册表,语法成本明显更高。

0.2 三层 / 四层:推荐四层

层 名称 内容 语法载体
L0 原始语料 原文、出处、引用、版本 .md / .mq.md 叙述 + 来源 表
L1 本体 / 模式 类、字段、类型、约束 # 诗人 + 字段/类型表
L2 可执行知识 知识个体、事实、返回值、出处 # 李白 = > 诗人 + ## 出生年份 + *701*
L3 调用面 链接、类调用、view、LinkInfo、EKC、agent [出生年份](李白.出生年份)

三层版可以把 L1/L2 合并为「可执行知识体系」;四层版把本体与个体分开,正好对应 EKC 的 schema/knowledge 分层。

0.3 核心判断

判断 结论
原始语料 → 可执行知识 → 调用面,逻辑成立 ✅
可执行知识能还原/验证回原始语料 ✅ 需要出处/校验约定,语法上可行
# 诗人 是类 ✅ 现有 # 语义
# 李白 = > 诗人 是「实例化」 ⚠️ 语法上是继承/特化,不是运行时实例化
李白.出生年份 是类调用 ✅ 需要类函数 + 项目类索引(v2.1 目标)
[]() 是调用面,不新增语法 ✅ [描述](类.函数) = 描述 + 已有调用

1. 你的模型(精确复述)

  1. 有一个诗人类(# 诗人),定义诗人应该有什么字段/函数;
  2. 用李白的知识把这个类「实例化」:
    • 李白是诗人;
    • 李白有姓名、出生年份等事实;
  3. 通过 []() 链接语法调用这个知识:
    • [出生年份](李白.出生年份);
  4. 整个体系分层:
    • 原始语料;
    • 改写/抽象后的可执行知识(可还原验证回原始知识);
    • 智能体回答/思考时的调用面。

这个模型在知识架构上没有问题;问题只在第 2 步的「实例化」如何落到语法。


2. 当前语法事实

语法 当前语义 对模型的影响
# 诗人 类/类型;正文是构造体 ✅ 可做本体
# 李白 = > 诗人 继承/子类;不是实例 ⚠️ 与「实例化」字面不符
## 李白的出生年份 方法;可用 self/自 ⚠️ 当前是实例方法
> 李白 构造实例(map + _type) ✅ 运行时实例
李白.李白的出生年份 当前被当变量/实例方法路径 ❌ 类调用未实现
[描述](...) 描述 + 表达式 ✅ 调用面
import 跨文档绑定 ⚠️ 当前跨文档继承/调用需 import

实测(marqdo 2.0.0):

  • # 李白 = > 诗人 在另一个文档定义 # 诗人 时,未 import 会报 unknown base type 诗人;
  • import 后可以继承,但调用仍需 > libai.李白 构造实例,再 `li`.李白的出生年份() → 701;
  • 李白.李白的出生年份 直接调用报 undefined variable;
  • 跨文档类索引不存在。

所以「诗人类 → 李白实例 → 链接调用」在目标模型上成立,在当前语法上只完成了「类 + 继承 + 实例方法」,缺「类调用 + 类索引」。


3. 自洽性检查:逐层

3.1 L0 原始语料

问题 结论
原始语料是否可执行? 否;它是出处,不是程序
能否被引用? ✅ 现有 Markdown 相对链接/来源 表
能否保留原文? ✅ 叙述、引用块、表格
语法负担 零:就是现有文档

要点:原始语料必须保持「不可执行」的独立身份;一旦把原文改写成代码,就失去了「还原验证」的基准。所以 L0 与 L2 要物理/逻辑分离(corpus/ vs knowledge/)。

3.2 L1 本体 / 模式

# 诗人

| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
问题 结论
# 诗人 能否表达类? ✅ # 就是类/类型
字段/类型能否表达? ✅ 现有表格 + 契约表
是否需要新语法? ❌ 不需要;用字段/类型表的列名约定
是否能被检查? 需要新增 knowledge.schema_* 检查(工具,不是语法)

语法结论:L1 完全用现有 # + 表格;只需要约定「字段表」的列名与语义。

3.3 L2 可执行知识:关键歧义

「用李白的知识实例化诗人」有两种落法:

A. 单体知识类(推荐)

# 李白 = > 诗人

## 李白的出生年份

*701*
  • 语法:# 李白 = > 诗人 = 继承/特化;
  • 语义:李白是诗人(is-a),并且 # 李白 是一个命名的知识个体;
  • 调用:李白.李白的出生年份 = 类调用(不使用 self 的函数);
  • 地址:# 李白 是文档里的稳定类名,可被项目类索引解析;
  • 运行时:如果需要 map,仍可 > 李白 构造实例;
  • 代价:术语上不是「实例」,是「单体类/知识个体」。

B. 运行时实例(不推荐作为 v2.1 语法)

# 诗人

## 李白

*> 诗人 姓名="李白" 出生年份=701*
  • 语法:## 李白 是函数,返回一个实例 map;
  • 调用:李白().出生年份(函数返回实例,再取方法);
  • 地址:李白 是函数名,不是实体;跨文档要函数索引/缓存;
  • 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
  • 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。

C. 显式个体声明(未来可选)

# 李白 : 诗人
  • : 明确「李白是诗人个体」;
  • 语法更贴近本体(instance-of),但新增一个标记;
  • 与 # Child = > Parent 形成两种关系,需要决定何时用哪种;
  • 不建议 v2.1 引入;可作为 v2.2 的候选。

3.4 L3 调用面

[出生年份](李白.李白的出生年份)
问题 结论
[] 是描述、() 是调用? ✅ 现有语义
() 与 ** 同权? ✅ 同一 parser/evaluator
跨文档类名能否解析? 需要项目类索引(v2.1)
正文链接是否执行? view/check 解析;run 不执行(安全)
终端输出? 代码链接 + print
编译器能否返回 LinkInfo? 需要新增(工具,不是语法)
view 能否显示调用点? 需要新增(工具,不是语法)

语法结论:L3 不需要新语法;缺的是解析器/类索引/视图/编译器输出。


4. 推荐模型:单体知识类

4.1 定义

单体知识类:一个 # 名称 = > 父类 的类,代表一个知识个体;它的 ## 函数是该个体的知识字段/事实;它不需要运行时实例即可被 类.函数 调用。

# 诗人

| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |

# 李白 = > 诗人

## 李白的出生年份

| 返回 | 类型 | 来源 |
|------|------|------|
| 701  | number | corpus/libai.md#出生年份 |

*701*

调用:

# main

**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`

输出:701。

4.2 为什么推荐 A

维度 A 单体类 B 运行时实例
语法新增 零 需要实例导出/注册/函数索引
地址稳定 ✅ 类名 ❌ 函数返回值
跨文档 ✅ 项目类索引 ❌ 需要实例注册表
EKC 映射 ✅ 文档/类/函数节点 ❌ 实例不是文档节点
可还原 ✅ 类/函数 + 来源表 ⚠️ 实例是运行时值
可检查 ✅ 类/函数/契约 ⚠️ 实例状态难静态检查
术语 ⚠️ 叫「个体」不叫「实例」 ✅ 叫实例
多实例 ⚠️ 每个个体一个类 ✅ 自然

结论:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。

4.3 术语约定

术语 含义 语法
类 / 本体 诗人的模式 # 诗人
知识个体(单体类) 李白这个知识实体 # 李白 = > 诗人
知识字段 / 事实 李白的出生年份 ## 李白的出生年份 + *701*
类调用 读取知识个体的字段 李白.李白的出生年份
运行时实例 代码里 > 李白 得到的 map > 李白 / _type
知识链接 描述 + 类调用 [出生年份](李白.李白的出生年份)

重要:语法文档里不要再用「实例化」描述 # 李白 = > 诗人;用「知识个体化/单体类」。 「实例」保留给运行时 > 诗人 产生的 map。这样语法、文档、EKC 三者才一致。

4.4 多诗人怎么办

# 李白 = > 诗人
# 杜甫 = > 诗人
# 王维 = > 诗人
  • 每个个体是一个单体类;项目类索引登记它们;
  • 李白.出生年份 / 杜甫.出生年份 分别解析;
  • 这是「命名个体注册表」,不是运行时实例集合;
  • 如果个体成千上万,类索引会变大;v2.2 可引入表驱动的个体注册(但不改变调用语法)。

5. 与 EKC 的映射

层 EKC 层 节点/边
L0 原始语料 Repository / sources documented_by / derived_from
L1 本体 Capability / Schema # 诗人 class 节点
L2 知识个体 Knowledge / Symbol # 李白 class 节点 + ## fact 节点;specializes 边 → 诗人
L3 调用面 Symbol / Capability []() 链接 → calls 边;LinkInfo
L4 Agent Agent / Context Pack find/reuse/link.resolve

新增边(建议):

  • specializes:# 李白 = > 诗人(语法上是继承;知识语义上是 is-a);
  • derived_from:fact → 原始语料;
  • calls:调用文档 → 李白.出生年份;
  • has_fact:# 李白 → ## 出生年份。

EKC 现有 depends_on/uses/implements/documented_by 可以复用;specializes 建议新增。


6. 还原 / 验证(L2 → L0)

「可执行知识能还原验证回原始知识」需要三件事:

6.1 出处是数据,不是注释

## 李白的出生年份

| 返回 | 类型 | 来源 |
|------|------|------|
| 701  | number | corpus/libai.md#出生年份 |

*701*
  • 来源 列指向原始语料(路径 + 标题/锚点);
  • 也可以放 frontmatter sources:;
  • check 验证来源存在;verify 验证值/引文一致(能自动化的部分)。

6.2 可还原的渲染

  • view 把 # 李白 渲染成「知识文档」:字段 + 值 + 来源;
  • catalog 生成 OKF Fact 页,resource: 指向 .mq.md;
  • 渲染结果与原始语料可人工/机器对照;
  • 这不是新语法,是 view/catalog 的输出。

6.3 漂移检查

诊断 触发
knowledge.source_missing 事实没有来源
knowledge.source_dangling 来源路径/锚点不存在
knowledge.value_mismatch 事实值与来源引文不一致(可自动判断时)
knowledge.schema_mismatch # 李白 字段与 # 诗人 不匹配
knowledge.fact_drift 原始语料变了,知识未复核

这些是工具诊断,不是语法。


7. 调用面:智能体如何使用

# main

用户想知道李白的出生年份,我们回答:[李白的出生年份](李白.李白的出生年份)
  • view 显示:李白.李白的出生年份 → 701 → 来源 corpus/libai.md#出生年份;
  • check --json 返回 LinkInfo(class/function/value/source);
  • agent 通过 link.resolve / find 取到值 + 出处,回答时可引用来源;
  • run 加 print 才输出;正文链接不执行,保证叙述安全。

这就是「调用面」:不是自然语言猜,而是可解析、可验证、可引用的类调用。


8. 反例与边界

场景 用 A 单体类 说明
李白、杜甫、王维 三个单体类 类索引;命名个体
同一诗人的多个版本 多个事实/来源,或子个体 版本是事实维度,不是实例
需要运行时状态(可变对象) > 李白 构造实例 运行时实例仍存在,但与知识个体分离
上千个诗人 类索引/表驱动注册 v2.2 优化;语法不变
需要 instanceof # 李白 = > 诗人 的 specializes 边 知识语义;不是运行时 _type
需要多继承 现有不支持 不在本设计范围

9. 决策建议

  1. v2.1 采用 A(单体知识类):# 诗人 + # 李白 = > 诗人 + ## 事实 + []() 类调用;零新语法。
  2. 术语冻结:# 李白 = > 诗人 叫「知识个体/单体类」,不叫「实例」;> 诗人 才是运行时实例。
  3. 补类函数与类索引:不使用 self 的 ## 是类函数;项目类索引解析跨文档 李白。
  4. 补出处/验证:来源 列或 sources:;check/verify;view/catalog 可还原。
  5. EKC 边:specializes / derived_from / calls / has_fact。
  6. 保留 B/C 作为未来:如果真需要运行时实例/个体声明,再评估 # 李白 : 诗人 或实例注册表;不在 v2.1 引入。

9.1 备选:frontmatter 个体声明(零语法,但换元数据)

如果不想把 = > 的继承语义借给「个体」,可以用 frontmatter 标记:

---
type: Individual
class: 诗人
id: libai
---

# 李白

## 出生年份

*701*
维度 单体类 A frontmatter 个体
可见性 # 李白 = > 诗人 一眼可见 类型在 frontmatter,正文只看到 # 李白
语法 现有 = > 现有 frontmatter,无新标记
语义纯度 继承/特化 明确 individual-of
EKC class + specializes individual + instance_of
代价 术语「个体」不是「实例」 两套 is-a 表达(= > 与 class:)需要约定

建议:v2.1 先用 A(可读、零语法);如果 EKC/本体需要严格区分 class/individual,再启用 frontmatter type: Individual,并规定「= > 只用于类-类,个体用 frontmatter」。


10. 结论

三层/四层模型自洽;「实例化」是唯一需要修正的词。 在 Marqdo 的语法里,# 李白 = > 诗人 是继承/特化,不是运行时实例; 把它用作单体知识类,就能在不新增语法的情况下得到「李白是诗人、李白有出生年份、李白.出生年份 可调用」。 这正是 EKC 的「文档即知识、知识可执行」:类是本体的地址,单体类是知识个体的地址,[]() 是调用面。


附录 A:一页对照

# L1 本体
# 诗人
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |

# L2 知识个体(单体类)
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*

# L3 调用面
[李白的出生年份](李白.李白的出生年份)
层 语法 语义
L0 .md 原文 + 来源 不可执行
L1 # 诗人 + 字段表 类/模式
L2 # 李白 = > 诗人 + ## + *701* 知识个体/事实
L3 [描述](类.函数) 类调用/链接
运行时 > 诗人 / > 李白 map 实例(可选)

附录 B:与现有文档的关系

文档 关系
link-syntax.md 调用面的语法;本文补知识分层与单体类
objects.md #/##/= > 的对象模型;本文把 = > 用于知识个体
module-namespace.md 跨文档解析;本文用项目类索引
engineering-knowledge.md EKC L0–L4;本文映射到四层
okf.md Fact/Concept/路径即身份;本文的 L2 与 Fact 对应