Files
marqdo/doc/design/executable-knowledge-system.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

10 KiB
Executable File
Raw Blame History

可执行知识系统:[]() 的统一语法与跨文件闭环

状态 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. 大项目的寻址:可读短名与稳定身份同时成立

全局只靠 # 李白 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。 但这不意味着作者要失去 李白.出生年份 的自然语言体验。

  1. 文件的既有 frontmatter id 是稳定身份;
  2. 现有 import bind:target 是代码中的规范加载/寻址;
  3. # / ## 是人可读的路径段;
  4. 正文短地址由 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. 实施顺序

  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;让一次变更能回到具体的 []() 和具体句子。

验收不是“能把一个类函数链接出来”,而是:改一处表字段、来源、规则或函数,系统能列出受影响的 取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。