10 KiB
可执行知识系统:[]() 的统一语法与跨文件闭环
| 状态 | Design Draft · v2.1 语义重构 |
| 核心判断 | []() 不是“普通代码”与“知识链接”的分界;每一个 []() 同时是代码、文档和知识图节点。 |
| 关联 | link-syntax.md · knowledge-layers.md · module-namespace.md · engineering-knowledge.md |
| 示例 | examples/executable-knowledge/ |
0. 一句话
[名称](载荷)是一个命名的可执行知识步骤:()做原有的任何事,[]说明这一步对人意味着什么;编译器把它们一起编入知识图。
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、 甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、 源位置、输入/输出、依赖和影响范围。
代码投影: eval([名称](载荷)) = eval(载荷)
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性; 三者同源,才是代码即文档、文档即知识、知识即可执行。
1. 统一节点:Named<T>
[]() 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
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. 大项目的寻址:可读短名与稳定身份同时成立
全局只靠 # 李白 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
但这不意味着作者要失去 李白.出生年份 的自然语言体验。
- 文件的既有 frontmatter
id是稳定身份; - 现有
import bind:target是代码中的规范加载/寻址; #/##是人可读的路径段;- 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定
symbol_id;歧义必须报错。
---
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。任意载荷都可能含有多个读、写、调用和循环依赖:
{
"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. 闭环:写、跑、看、查、变
作者写 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. 实施顺序
- 在表达式、遍历和正文三处统一保留
Named<T>;payload 复用各自现有 parser。 - 为任意
Named<T>提取inputs、outputs、dependencies、effect、roles;从单 target 演进为依赖集合。 - 让
#/##契约为内部步骤提供类型/公开边界;让 frontmatterid+ import 提供跨文件稳定解析。 - 把现有 EKC 图扩展为步骤图:
observes、derives、iterates、calls、acts、narrates、derived_from。 - 接入
check、view、verify、impact与 lock;让一次变更能回到具体的[]()和具体句子。
验收不是“能把一个类函数链接出来”,而是:改一处表字段、来源、规则或函数,系统能列出受影响的 取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。