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>
207 lines
10 KiB
Markdown
207 lines
10 KiB
Markdown
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **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;让一次变更能回到具体的 `[]()` 和具体句子。
|
||
|
||
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
|
||
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
|