- 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。
17 KiB
Executable File
知识分层:原始语料、可执行知识、调用面
| 状态 | 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. 你的模型(精确复述)
- 有一个诗人类(
# 诗人),定义诗人应该有什么字段/函数; - 用李白的知识把这个类「实例化」:
- 李白是诗人;
- 李白有姓名、出生年份等事实;
- 通过
[]()链接语法调用这个知识:[出生年份](李白.出生年份);
- 整个体系分层:
- 原始语料;
- 改写/抽象后的可执行知识(可还原验证回原始知识);
- 智能体回答/思考时的调用面。
这个模型在知识架构上没有问题;问题只在第 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生成 OKFFact页,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. 决策建议
- v2.1 采用 A(单体知识类):
# 诗人+# 李白 = > 诗人+##事实 +[]()类调用;零新语法。 - 术语冻结:
# 李白 = > 诗人叫「知识个体/单体类」,不叫「实例」;> 诗人才是运行时实例。 - 补类函数与类索引:不使用
self的##是类函数;项目类索引解析跨文档李白。 - 补出处/验证:
来源列或sources:;check/verify;view/catalog可还原。 - EKC 边:
specializes/derived_from/calls/has_fact。 - 保留 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 对应 |