Files
marqdo/doc/design/executable-knowledge-system.md
T
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00

207 lines
10 KiB
Markdown
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.
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
| | |
|---|---|
| 状态 | **Design Draft · v2.1 语义重构** |
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
---
## 0. 一句话
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
源位置、输入/输出、依赖和影响范围。
```text
代码投影: eval([名称](载荷)) = eval(载荷)
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
```
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
三者同源,才是代码即文档、文档即知识、知识即可执行。
---
## 1. 统一节点:`Named<T>`
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
```text
Named<T> { label, inner: T, span }
```
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
| 既有位置 | `T` | 示例 | 知识角色 |
|---|---|---|---|
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
### 1.1 每个节点都有角色,而不是两套语法
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
| role | 如何识别 | `check` 应问什么 |
|---|---|---|
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
---
## 2. 知识层不是目录隔离,而是同一图的不同投影
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
同一份 `.mq.md` 可以同时有多层节点。
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|---|---|---|---|
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
这正是通用语法本身兼容知识体系的含义。
### 2.1 `#` / `##` 的位置
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
`[]()` 是知识单元的内部结构。
---
## 3. 大项目的寻址:可读短名与稳定身份同时成立
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
1. 文件的既有 frontmatter `id` 是稳定身份;
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
3. `#` / `##` 是人可读的路径段;
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
```markdown
---
id: knowledge.people.li-bai
import:
li_bai: knowledge/people/li-bai.mq.md
---
# 回答
**year = [李白的出生年份](li_bai.李白.出生年份)**
李白出生于[公元 701 年](李白.出生年份)。
```
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
而是可读的查询,必须由 lock 固化。
---
## 4. 每个 `[]()` 产生统一的知识记录
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
"inputs": ["订单.行"],
"outputs": ["行"],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
],
"effect": "pure",
"fingerprint": "sha256:…"
}
```
此记录就是统一知识图节点:
- 本地取元有输入/类型边;
- 纯计算有输入/输出/公式边;
- 循环有集合、变量绑定和循环体边;
- 调用有 `calls`/`uses` 边;
- 有来源的事实再增加 `derived_from` 边;
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
---
## 5. 闭环:写、跑、看、查、变
```text
作者写 Named<T>
│
├─ run:擦除 label,按原语义执行
├─ view:显示 label,可展开值、输入、步骤和来源
└─ check:解析所有依赖,编译统一知识图
│
catalog / lock / context pack
│
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
│
作者或 agent 修复后重新 check/verify
```
### 5.1 命令边界
| 操作 | 做什么 | 不做什么 |
|---|---|---|
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
---
## 6. 实施顺序
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**