- 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。
444 lines
17 KiB
Markdown
Executable File
444 lines
17 KiB
Markdown
Executable File
# 知识分层:原始语料、可执行知识、调用面
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Design Review · Recommended(v2.1 语法设计评审)** |
|
||
| 日期 | 2026-10-23 |
|
||
| 问题 | 「诗人类 → 用李白知识实例化 → `[]()` 调用」的三/四层模型,从**语法设计**上是否自洽? |
|
||
| 推荐 | **单体知识类(singleton knowledge class)**:`# 诗人` 是类,`# 李白 = > 诗人` 是知识个体;`李白.出生年份` 是类调用;零新语法 |
|
||
| 关联 | [link-syntax.md](link-syntax.md) · [objects.md](objects.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) · [okf.md](okf.md) |
|
||
| 示例 | [examples/knowledge-layers/](../../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 本体 / 模式
|
||
|
||
```markdown
|
||
# 诗人
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| 姓名 | text | 诗人姓名 |
|
||
| 出生年份 | number | 公元年份 |
|
||
```
|
||
|
||
| 问题 | 结论 |
|
||
|------|------|
|
||
| `# 诗人` 能否表达类? | ✅ `#` 就是类/类型 |
|
||
| 字段/类型能否表达? | ✅ 现有表格 + 契约表 |
|
||
| 是否需要新语法? | ❌ 不需要;用字段/类型表的列名约定 |
|
||
| 是否能被检查? | 需要新增 `knowledge.schema_*` 检查(工具,不是语法) |
|
||
|
||
**语法结论**:L1 完全用现有 `#` + 表格;只需要约定「字段表」的列名与语义。
|
||
|
||
### 3.3 L2 可执行知识:关键歧义
|
||
|
||
「用李白的知识实例化诗人」有两种落法:
|
||
|
||
#### A. 单体知识类(推荐)
|
||
|
||
```markdown
|
||
# 李白 = > 诗人
|
||
|
||
## 李白的出生年份
|
||
|
||
*701*
|
||
```
|
||
|
||
- 语法:`# 李白 = > 诗人` = 继承/特化;
|
||
- 语义:李白是诗人(is-a),并且 `# 李白` 是一个**命名的知识个体**;
|
||
- 调用:`李白.李白的出生年份` = 类调用(不使用 `self` 的函数);
|
||
- 地址:`# 李白` 是文档里的稳定类名,可被项目类索引解析;
|
||
- 运行时:如果需要 map,仍可 `> 李白` 构造实例;
|
||
- 代价:**术语上不是「实例」**,是「单体类/知识个体」。
|
||
|
||
#### B. 运行时实例(不推荐作为 v2.1 语法)
|
||
|
||
```markdown
|
||
# 诗人
|
||
|
||
## 李白
|
||
|
||
*> 诗人 姓名="李白" 出生年份=701*
|
||
```
|
||
|
||
- 语法:`## 李白` 是函数,返回一个实例 map;
|
||
- 调用:`李白().出生年份`(函数返回实例,再取方法);
|
||
- 地址:`李白` 是函数名,不是实体;跨文档要函数索引/缓存;
|
||
- 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
|
||
- 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。
|
||
|
||
#### C. 显式个体声明(未来可选)
|
||
|
||
```markdown
|
||
# 李白 : 诗人
|
||
```
|
||
|
||
- `:` 明确「李白是诗人个体」;
|
||
- 语法更贴近本体(instance-of),但**新增一个标记**;
|
||
- 与 `# Child = > Parent` 形成两种关系,需要决定何时用哪种;
|
||
- 不建议 v2.1 引入;可作为 v2.2 的候选。
|
||
|
||
### 3.4 L3 调用面
|
||
|
||
```markdown
|
||
[出生年份](李白.李白的出生年份)
|
||
```
|
||
|
||
| 问题 | 结论 |
|
||
|------|------|
|
||
| `[]` 是描述、`()` 是调用? | ✅ 现有语义 |
|
||
| `()` 与 `**` 同权? | ✅ 同一 parser/evaluator |
|
||
| 跨文档类名能否解析? | 需要项目类索引(v2.1) |
|
||
| 正文链接是否执行? | view/check 解析;run 不执行(安全) |
|
||
| 终端输出? | 代码链接 + `print` |
|
||
| 编译器能否返回 LinkInfo? | 需要新增(工具,不是语法) |
|
||
| view 能否显示调用点? | 需要新增(工具,不是语法) |
|
||
|
||
**语法结论**:L3 不需要新语法;缺的是**解析器/类索引/视图/编译器输出**。
|
||
|
||
---
|
||
|
||
## 4. 推荐模型:单体知识类
|
||
|
||
### 4.1 定义
|
||
|
||
> **单体知识类**:一个 `# 名称 = > 父类` 的类,代表一个知识个体;它的 `##` 函数是该个体的知识字段/事实;它不需要运行时实例即可被 `类.函数` 调用。
|
||
|
||
```markdown
|
||
# 诗人
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| 姓名 | text | 诗人姓名 |
|
||
| 出生年份 | number | 公元年份 |
|
||
|
||
# 李白 = > 诗人
|
||
|
||
## 李白的出生年份
|
||
|
||
| 返回 | 类型 | 来源 |
|
||
|------|------|------|
|
||
| 701 | number | corpus/libai.md#出生年份 |
|
||
|
||
*701*
|
||
```
|
||
|
||
调用:
|
||
|
||
```markdown
|
||
# main
|
||
|
||
**year = [李白的出生年份](李白.李白的出生年份)**
|
||
> print text=`year`
|
||
```
|
||
|
||
输出:`701`。
|
||
|
||
### 4.2 为什么推荐 A
|
||
|
||
| 维度 | A 单体类 | B 运行时实例 |
|
||
|------|---------|-------------|
|
||
| 语法新增 | **零** | 需要实例导出/注册/函数索引 |
|
||
| 地址稳定 | ✅ 类名 | ❌ 函数返回值 |
|
||
| 跨文档 | ✅ 项目类索引 | ❌ 需要实例注册表 |
|
||
| EKC 映射 | ✅ 文档/类/函数节点 | ❌ 实例不是文档节点 |
|
||
| 可还原 | ✅ 类/函数 + 来源表 | ⚠️ 实例是运行时值 |
|
||
| 可检查 | ✅ 类/函数/契约 | ⚠️ 实例状态难静态检查 |
|
||
| 术语 | ⚠️ 叫「个体」不叫「实例」 | ✅ 叫实例 |
|
||
| 多实例 | ⚠️ 每个个体一个类 | ✅ 自然 |
|
||
|
||
**结论**:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。
|
||
|
||
### 4.3 术语约定
|
||
|
||
| 术语 | 含义 | 语法 |
|
||
|------|------|------|
|
||
| **类 / 本体** | 诗人的模式 | `# 诗人` |
|
||
| **知识个体(单体类)** | 李白这个知识实体 | `# 李白 = > 诗人` |
|
||
| **知识字段 / 事实** | 李白的出生年份 | `## 李白的出生年份` + `*701*` |
|
||
| **类调用** | 读取知识个体的字段 | `李白.李白的出生年份` |
|
||
| **运行时实例** | 代码里 `> 李白` 得到的 map | `> 李白` / `_type` |
|
||
| **知识链接** | 描述 + 类调用 | `[出生年份](李白.李白的出生年份)` |
|
||
|
||
> **重要**:语法文档里不要再用「实例化」描述 `# 李白 = > 诗人`;用「知识个体化/单体类」。
|
||
> 「实例」保留给运行时 `> 诗人` 产生的 map。这样语法、文档、EKC 三者才一致。
|
||
|
||
### 4.4 多诗人怎么办
|
||
|
||
```markdown
|
||
# 李白 = > 诗人
|
||
# 杜甫 = > 诗人
|
||
# 王维 = > 诗人
|
||
```
|
||
|
||
- 每个个体是一个单体类;项目类索引登记它们;
|
||
- `李白.出生年份` / `杜甫.出生年份` 分别解析;
|
||
- 这是「命名个体注册表」,不是运行时实例集合;
|
||
- 如果个体成千上万,类索引会变大;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 出处是数据,不是注释
|
||
|
||
```markdown
|
||
## 李白的出生年份
|
||
|
||
| 返回 | 类型 | 来源 |
|
||
|------|------|------|
|
||
| 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. 调用面:智能体如何使用
|
||
|
||
```markdown
|
||
# 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 标记:
|
||
|
||
```markdown
|
||
---
|
||
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:一页对照
|
||
|
||
```markdown
|
||
# L1 本体
|
||
# 诗人
|
||
| 字段 | 类型 | 说明 |
|
||
| 姓名 | text | ... |
|
||
| 出生年份 | number | ... |
|
||
|
||
# L2 知识个体(单体类)
|
||
# 李白 = > 诗人
|
||
## 李白的出生年份
|
||
| 返回 | 类型 | 来源 |
|
||
| 701 | number | corpus/libai.md#出生年份 |
|
||
*701*
|
||
|
||
# L3 调用面
|
||
[李白的出生年份](李白.李白的出生年份)
|
||
```
|
||
|
||
| 层 | 语法 | 语义 |
|
||
|----|------|------|
|
||
| L0 | `.md` 原文 + 来源 | 不可执行 |
|
||
| L1 | `# 诗人` + 字段表 | 类/模式 |
|
||
| L2 | `# 李白 = > 诗人` + `##` + `*701*` | 知识个体/事实 |
|
||
| L3 | `[描述](类.函数)` | 类调用/链接 |
|
||
| 运行时 | `> 诗人` / `> 李白` | map 实例(可选) |
|
||
|
||
## 附录 B:与现有文档的关系
|
||
|
||
| 文档 | 关系 |
|
||
|------|------|
|
||
| [link-syntax.md](link-syntax.md) | 调用面的语法;本文补知识分层与单体类 |
|
||
| [objects.md](objects.md) | `#`/`##`/`= >` 的对象模型;本文把 `= >` 用于知识个体 |
|
||
| [module-namespace.md](module-namespace.md) | 跨文档解析;本文用项目类索引 |
|
||
| [engineering-knowledge.md](engineering-knowledge.md) | EKC L0–L4;本文映射到四层 |
|
||
| [okf.md](okf.md) | Fact/Concept/路径即身份;本文的 L2 与 Fact 对应 |
|