# 可执行知识系统:`[]()` 的统一语法与跨文件闭环 | | | |---|---| | 状态 | **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` `[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器: ```text Named { 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`。所以循环不会被误判成“返回一个事实”,取元也不会 被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。 ### 1.1 每个节点都有角色,而不是两套语法 角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束: | role | 如何识别 | `check` 应问什么 | |---|---|---| | `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 | | `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 | | `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 | | `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 | | `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 | | `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 | 一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖 若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。 --- ## 2. 知识层不是目录隔离,而是同一图的不同投影 “几层知识”不应把语法和项目切断。它们是同一个 `Named` 图中不同职责的节点; 同一份 `.mq.md` 可以同时有多层节点。 | 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 | |---|---|---|---| | **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? | | **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? | | **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named` | 哪个可调用单元给出什么知识? | | **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named` / `Named` | 如何从已有知识得到新结论/行动? | | **N 叙述知识** | 段落与正文调用槽 | 正文 `Named` | 如何把结论说给人或 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 │ ├─ run:擦除 label,按原语义执行 ├─ view:显示 label,可展开值、输入、步骤和来源 └─ check:解析所有依赖,编译统一知识图 │ catalog / lock / context pack │ 来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named 与叙述句子 │ 作者或 agent 修复后重新 check/verify ``` ### 5.1 命令边界 | 操作 | 做什么 | 不做什么 | |---|---|---| | `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 | | `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 | | `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 | | `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 | | `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 | 这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。 --- ## 6. 实施顺序 1. 在表达式、遍历和正文三处统一保留 `Named`;payload 复用各自现有 parser。 2. 为任意 `Named` 提取 `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;让一次变更能回到具体的 `[]()` 和具体句子。 验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的 取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**