From 8bbe017a5efa824f6872e43ace979ace90bedcaa Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 23 Oct 2026 15:46:02 +0800 Subject: [PATCH] docs: define executable knowledge step architecture --- doc/README.md | 1 + doc/design/executable-knowledge-system.md | 205 +++++++++++ doc/design/link-syntax.md | 208 +++++++---- doc/next/009.md | 346 ++++++++++++++++++ examples/executable-knowledge/README.md | 35 ++ .../capabilities/order-pricing.mq.md | 26 ++ .../corpus/tax-policy-2026.md | 5 + .../docs/invoice-answer.mq.md | 13 + .../knowledge/tax-2026.mq.md | 18 + .../executable-knowledge/schema/order.mq.md | 17 + 10 files changed, 806 insertions(+), 68 deletions(-) create mode 100644 doc/design/executable-knowledge-system.md create mode 100644 doc/next/009.md create mode 100644 examples/executable-knowledge/README.md create mode 100644 examples/executable-knowledge/capabilities/order-pricing.mq.md create mode 100644 examples/executable-knowledge/corpus/tax-policy-2026.md create mode 100644 examples/executable-knowledge/docs/invoice-answer.mq.md create mode 100644 examples/executable-knowledge/knowledge/tax-2026.mq.md create mode 100644 examples/executable-knowledge/schema/order.mq.md diff --git a/doc/README.md b/doc/README.md index ebda891..591191b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -107,6 +107,7 @@ | [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) | | [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 | | [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 | +| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 | | [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 | | [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 | | [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 | diff --git a/doc/design/executable-knowledge-system.md b/doc/design/executable-knowledge-system.md new file mode 100644 index 0000000..eb06bb7 --- /dev/null +++ b/doc/design/executable-knowledge-system.md @@ -0,0 +1,205 @@ +# 可执行知识系统:`[]()` 的统一语法与跨文件闭环 + +| | | +|---|---| +| 状态 | **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;让一次变更能回到具体的 `[]()` 和具体句子。 + +验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的 +取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。** diff --git a/doc/design/link-syntax.md b/doc/design/link-syntax.md index b523de4..c86a51d 100644 --- a/doc/design/link-syntax.md +++ b/doc/design/link-syntax.md @@ -1,10 +1,10 @@ -# 链接语法:类-函数调用与可执行知识 +# 链接语法:命名载荷、类-函数调用与可执行知识 | | | |---|---| -| 状态 | **Accepted · Design Declaration(v2.1 目标;v2.0.0 仅实现本地表达式链接)** | +| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** | | 日期 | 2026-10-23 | -| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;链接只是给一次调用加一个「人话名字」和 view/compiler 元数据 | +| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 | | 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** | | 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) | | 示例 | [examples/link-syntax/](../../examples/link-syntax/) | @@ -19,21 +19,62 @@ > **`[]()` 本身不制作新语法。** > `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。 > `#` 是类,`##` 是函数;`类.函数` 就是类调用。 -> 链接只是把「一次已有调用」写进文档,并给它一个人话名字;view 显示调用信息,编译器返回链接信息。 +> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。 + +### 0.1.1 还缺的一步:链接是「命名的可执行步骤」 + +`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。 +所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。 + +> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。** + +它始终同时有三种投影: + +| 投影 | 规则 | 目的 | +|------|------|------| +| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 | +| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 | +| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 | + +`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。 +它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。 + +例如: + +```markdown +**name = [订单收件人](at(订单, "收件人"))** +**gross = [含税金额](金额 * (1 + 税率))** +- [逐个订单行](遍历 订单.行 为 行) +订单总额为[含税总价](定价.订单定价.含税总价(订单))。 +``` + +它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义, +但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源; +不能要求每一次取元或循环都伪造来源表。 + +这才同时实现三件事: + +- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒; +- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值; +- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。 + +完整的跨文件闭环、稳定寻址和层次投影见 +[executable-knowledge-system.md](executable-knowledge-system.md)。 ### 0.2 三个「不新增」 | 不新增 | 说明 | |--------|------| -| **不新增协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档用 `类.函数` 或 `文档.类.函数` | +| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 | | **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 | | **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 | -**本文只定义三件事**: +**本文定义四件事**: -1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用,链接如何解析; +1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤; 2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析; -3. **呈现**:view 显示调用点;编译器返回 LinkInfo;EKC 建边;lock 可选。 +3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子; +4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。 > **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。 @@ -90,7 +131,7 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: | `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 | | `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 | | 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` | -| 链接是「描述 + 已有调用」 | 被收窄成「遮蔽/本地表达式」 | 跨文档链接、LinkInfo、view 目标信息、图边缺失 | +| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 | 这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。** @@ -105,7 +146,7 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: 形式化: > **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。** -> 链接不改变求值,只增加 label、view 呈现、编译器元数据、图边。 +> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。 --- @@ -113,8 +154,8 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: | 术语 | 定义 | |------|------| -| **链接语法** | `[描述](表达式)`;描述 inert,表达式是已有代码 | -| **描述(label)** | `[]` 内自由文本;只用于显示、检索、诊断、LinkInfo;永不执行 | +| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 | +| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 | | **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 | | **类(class)** | `# 名称`;知识命名空间/类型 | | **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 | @@ -123,8 +164,8 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: | **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 | | **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 | | **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) | -| **LinkInfo** | 编译器返回的链接信息:描述、源位置、目标类/函数、签名、状态、值/指纹 | -| **链接图** | 文档/类/函数为点,链接为边;EKC/catalog/view 共用 | +| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 | +| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 | | **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 | --- @@ -137,10 +178,10 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: [label](expr) ≡ expr ``` -- `[]` 不进符号表、不参与求值、不改变作用域; +- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口; - `()` 是唯一执行体;空 `()` 值为 `None`; - `label.missing` / `label.empty_payload` 仍是结构诊断; -- 链接的「知识性」来自 `expr` 的类/函数解析,不来自标签。 +- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。 ### 2.2 `#` 是类,`##` 是函数 @@ -176,26 +217,27 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: > 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。 > 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。 -### 2.4 跨文档:类索引,不是新语法 +### 2.4 跨文档:模块身份优先,类索引只做发现 -链接目标可以跨文档。解析顺序: +链接目标可以跨文档。可运行代码的解析顺序: 1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用; 2. **当前文档类/函数**:`# 类` / `## 函数`; 3. **已 import 的模块**:现有 `import bind:target` 绑定; -4. **项目类索引**:扫描项目根下 `.mq.md` 的 `# 类` 与 `## 函数`; -5. **内置/插件**。 +4. **内置/插件**。 -项目类索引是**编译器/链接器的索引**,不是语法: +文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如 +`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的 +按名加载机制: -- 只索引 `# 类` 名、`## 函数` 名、签名、文件位置; +- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置; - 排除 `# main`; -- 同名类 → `link.ambiguous`,要求 `文档.类.函数` 限定; +- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹; - 索引只在项目根内(`--fs-root`),不访问网络; - 索引可缓存(按文件 mtime)。 -> 这就是第二个文档能直接写 `李白.李白的出生年份` 的原因: -> `李白` 是项目里的类名,编译器在类索引里找到它;不需要 `import`,也不需要协议前缀。 +> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock; +> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。 ### 2.5 `()` 与 `**代码**` 同权 @@ -210,7 +252,8 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: | 返回值 | Value | Value(同类型系统) | | 副作用 | 可 | 可(受沙箱限制) | -**实现约束**:`[label](payload)` 的 payload 必须复用 `**代码**` 的表达式入口;禁止另造「简化表达式」。 +**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的 +`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。 **代码链接 vs 正文链接**: @@ -223,11 +266,13 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: 正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。 要终端输出,就把同一段代码放进代码链接并加 `print`。 -**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 能解析为类/函数 → **知识链接**;payload 是 URL/相对路径且不是类/函数 → **导航链接**;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。 +**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有 +载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历 +都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。 -### 2.6 返回值:知识函数必须有值 +### 2.6 输出:值知识必须有值,过程知识必须声明效果 -知识链接要「可执行」,目标函数必须返回一个值: +当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值: ```markdown ## 李白的出生年份 @@ -235,12 +280,13 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: *701* ``` -或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;知识链接要的是返回值/表。只有叙述、没有返回的函数: +或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数: - `run` 得到 `None`; - `check` 报 `link.no_value`(warning/error,视知识链接用途); - view 显示「无返回值」; -- 这不是语法问题,是知识单元没有编码值。 +- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值, + 但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。 ### 2.7 view 显示调用信息 @@ -278,37 +324,60 @@ v2.0.0 把「类-函数」收窄成了「实例方法」: ```json { - "label": "李白的出生年份", - "source": {"file": "main.mq.md", "line": 3, "col": 41}, - "target": { - "class": "李白", - "function": "李白的出生年份", - "doc": "libai.mq.md", - "kind": "class_function", - "signature": {"params": [], "returns": "number"}, - "instance_only": false - }, - "status": "ok", + "label": "逐个订单行", + "payload_kind": "loop", + "roles": ["iterate"], + "source": {"file": "pricing.mq.md", "line": 18, "col": 3}, + "inputs": [{"path": "订单.行", "type": "list<订单行>"}], + "outputs": [{"name": "行", "type": "订单行"}], + "dependencies": [ + {"kind": "local_value", "path": "订单.行"}, + {"kind": "symbol", "id": "capability.pricing::订单定价.含税价"} + ], + "effect": "pure", "value": null, "fingerprint": "sha256:…" } ``` +- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法; +- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导; +- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用; - `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填; -- `status`:`ok` / `unresolved` / `ambiguous` / `instance_only` / `no_value` / `arg_mismatch` / `type_mismatch` / `cycle` / `stale`; -- `fingerprint`:目标函数体/签名哈希;用于过期检测(可选 lock); -- `doc`:类所在文档;用于跳转/图边; -- `kind`:`class_function` / `module_function` / `instance_method` / `table` / `unknown`。 +- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。 -### 2.9 链接是图边 +### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录 + +`LinkInfo` 至少要区分三类状态: + +| 层 | 要回答的问题 | 典型状态 | +|------|-------------|----------| +| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` | +| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` | +| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` | + +三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或 +正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖 +`link.unresolved` 或副作用越权。 + +来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。 +这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。 + +### 2.9 链接既是步骤节点,也是图边 ```text -main.mq.md --calls--> libai.mq.md::李白.李白的出生年份 +定价.订单定价 --contains--> step#逐个订单行 +step#逐个订单行 --observes--> 订单.行 +step#逐个订单行 --calls--> 定价.订单定价.含税价 +定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率 ``` -- EKC `graph.json` 增加 class/function 节点和 `calls`/`references` 边; +- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/ + `narrates` 等边的一种; +- EKC `graph.json` 增加 class/function/步骤节点和上述关系边; - `catalog` 模块页显示「链接到/被链接」; -- `find`/`impact`/`verify` 沿链接边遍历; +- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时, + 都可精确找出受影响的代码步骤和句子; - view 的 Structure 面板显示上下游。 ### 2.10 安全 @@ -326,9 +395,9 @@ main.mq.md --calls--> libai.mq.md::李白.李白的出生年份 ### 2.11 可复现(可选,生成物) -- LinkInfo 带目标指纹; +- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹; - `marqdo links lock` 生成 `.marqdo/links.lock.yaml`; -- `check --locked` 校验;目标变化 → `link.stale`; +- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`; - 这是生成物/工具,不是新语法。 ### 2.12 知识分层:类、知识个体、调用面 @@ -409,7 +478,7 @@ main.mq.md --calls--> libai.mq.md::李白.李白的出生年份 ### 4.1 `check --json` -- 解析所有 `[]()`(代码 + 正文),输出 LinkInfo 与 `link.*` 诊断; +- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断; - 不执行目标函数; - `link.ok` 可作 info,不阻断; - `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。 @@ -428,8 +497,8 @@ AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view` ### 4.3 `catalog` / EKC - `catalog` 增加 `links:` 段与链接图; -- EKC `graph.json` 增加 class/function 节点与 `calls`/`references` 边; -- `find`/`impact` 能按类/函数检索。 +- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边; +- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。 ### 4.4 `links` CLI(可选) @@ -452,6 +521,8 @@ marqdo links lock [PATH] # 可选,生成指纹锁 | `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 | | `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 | | `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 | +| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 | +| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock | | `label.missing` | error | 空描述 | 写一句人话 | | `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 | @@ -464,10 +535,10 @@ marqdo links lock [PATH] # 可选,生成指纹锁 | 阶段 | 目标 | 交付 | |------|------|------| | **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 | -| **L1** | 类索引 + 解析 | 项目类索引;`类.函数` 解析;`link.*` 诊断;LinkInfo | +| **L1** | 步骤索引 + 解析 | `Named` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 | | **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 | | **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 | -| **L4** | 图 + lock | EKC 边;catalog;可选 lock/stale | +| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale | | **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 | **顺序**:L0 → L1 → L2 → L3 → L4 → L5。 @@ -480,15 +551,15 @@ L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。 | `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 | | `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 | | `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 | -| `src/link.rs`(新增) | 类索引、`类.函数` 解析、LinkInfo、诊断、指纹、图边 | +| `src/link.rs`(新增) | 模块/类解析、`Named` 步骤记录、依赖/效果提取、诊断、指纹、图边 | | `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 | | `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` | | `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 | | `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 | | `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 | | `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 | -| `src/knowledge/graph.rs` | class/function 节点;`calls`/`references` 边 | -| `src/knowledge/extract.rs` | 类/函数提取;链接关系 | +| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 | +| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 | | `src/catalog.rs` | links 段/图 | | `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` | | `src/main.rs` | `links` 子命令;check 选项 | @@ -507,8 +578,8 @@ L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。 - payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接); - 正文 `[]()` → 正文链接(view/check)。 5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。 -6. **LinkInfo**:check/view/catalog 共用;不执行即可得目标/签名/状态。 -7. **图边**:链接是边;class/function 是节点;文档是容器。 +6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。 +7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。 8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。 **最小改动原则**(证明「不新增语法」): @@ -535,7 +606,7 @@ L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。 | 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 | | 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle | | view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 | -| 图 | EKC 边;catalog;impact | +| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact | | 双后端 | tree + bytecode 一致 | | 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 | | 安全 | 根目录逃逸、循环、副作用、标签注入 | @@ -635,6 +706,7 @@ import libai:libai.mq.md | 8 | EKC 出现 `calls` 边 | graph.json | | 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 | | 10 | 旧 605 测试不减;实例调用不变 | 回归 | +| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 | **一句话验收**: @@ -670,17 +742,17 @@ import libai:libai.mq.md ## 9. 结论 -> **`[]()` 不是新语法,它是「描述 + 已有调用」的组合。** +> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。** > `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。 -> 链接只是给这次调用加一个名字,并让 view/compiler 能看见它。 +> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。 v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。 v2.1 要补的是**语义**,不是语法: 1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数; 2. `类.函数` → 类调用;跨文档用项目类索引; -3. `[]()` → 描述 + 已有调用;代码链接求值,正文链接由 view/check 解析; -4. LinkInfo / view / EKC 图边 —— 让链接可查、可看、可建图。 +3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析; +4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。 **一句话**: @@ -718,7 +790,7 @@ v2.1 要补的是**语义**,不是语法: | 旧文档 | 关系 | |--------|------| -| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「描述 + 已有调用」;遮蔽只是显示属性 | +| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 | | [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo | | [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` | | [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 | diff --git a/doc/next/009.md b/doc/next/009.md new file mode 100644 index 0000000..a4803dc --- /dev/null +++ b/doc/next/009.md @@ -0,0 +1,346 @@ +# Marqdo 的 `[]()`:从可读语法走向可验证的知识引用 + +我重新读取了仓库当前 `main` 分支(提交 `1a139892`)的 README、链接语法设计、知识分层设计,以及仓库中针对现有实现的复核报告。 + +这次我认为应当调整之前对 Marqdo 的评价:你提出的 `[]()` 不只是改善语法外观,它确实有机会成为 Marqdo 从“可执行文档”走向“可复用知识系统”的关键入口。 + +但当前设计有一个尚未解决的根本问题: + +它已经尝试统一“可读描述”和“可执行表达式”,却还没有真正统一“知识的身份、知识的含义、知识的实现、知识的证据,以及知识的版本”。 + +仅仅让链接能解析到一个函数,并不能保证 AI 没有用错知识。仅仅让函数有一个确定的编译结果,也不能保证这个结果所表达的知识是真的。 + +这恰恰可能是你不断修改设计,却始终没有得到预期效果的原因。 + +## 一、先区分仓库已经实现了什么 + +当前 README 标明的是 v2.0.0,`doc/design/link-syntax.md` 将跨文档类函数调用列为 v2.1 目标。 + +| 能力 | 仓库当前状态 | +| ---------------- | ---------------------------- | +| `[描述](表达式)` 本地遮蔽 | 已实现,主要通过 `markup: occlusion` | +| `()` 中表达式求值 | 已实现 | +| 用自然语言描述隐藏复杂代码 | 已实现基础能力 | +| `类.函数` 直接调用 | 设计目标,尚未按文档实现 | +| 跨文档自动解析知识目标 | 设计目标 | +| 编译器生成 LinkInfo | 设计目标 | +| 链接进入 EKC 知识图 | 设计目标 | +| 版本指纹和链接锁定 | 设计目标 | + +仓库还有一份很重要的复核报告:[occlusion-vs-executable-knowledge-2026-10.md](https://github.com/cflmy/marqdo/blob/main/doc/research/occlusion-vs-executable-knowledge-2026-10.md?utm_source=chatgpt.com)。 + +它针对 v2.0.0 测试了一个典型案例:在一个文档里定义“李白的出生年份”,再由另一个文档通过链接读取。结果发现,正文链接没有进入执行 AST,跨文档类名没有得到解析,类函数不能直接调用,而且原始知识函数也没有实际返回值。 + +这份报告说明:问题不是 `[]()` 的形式不够优美,而是链接背后的知识语义基础尚未建成。 + +这也解释了为什么你已经设计了链接语法,却还没有获得想象中的知识复用能力。 + +## 二、我建议保留你的两个目标,但增加第三个目标 + +目标一 · Presentation + +自然语言呈现 + +用 `[]` 给复杂、不适合人类直接阅读的可执行表达式一个清楚的描述。 + +目标二 · Executable Reference + +确定性知识引用 + +让 `()` 可以绑定已经编译、可解析、可验证的知识单元,而不仅是临时拼出的表达式。 + +目标三 · Knowledge Integrity + +知识一致性保障 + +当知识定义、实现、版本、证据或适用条件变化时,能检测引用是否仍然有效,阻止 AI 把“能够运行”误认为“知识正确”。 + +第三个目标不是另加一种语法,而是让前两个目标真正成立所必须的编译器能力。 + +我倾向于把它称为 Verified Knowledge Reference(可验证知识引用)。 + +## 三、关键转变:不要把“函数”直接等同于“知识” + +目前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的核心设计是: + +``` +[label](expr) ≡ expr +``` + +它规定标签不改变计算语义,链接只为表达式增加人类描述和编译器元数据。 + +这个规则作为表达式语义是合理的,但作为完整知识模型还不够。 + +原因在于,至少有三种不同的东西可能进入 `()`: + +| 内容 | 例子 | 实质 | +| ---- | ---------------------------- | --------------- | +| 表达式 | `[税额](amount * rate)` | 一次计算 | +| 函数 | `[计算税额](Tax.calculate(100))` | 一种计算能力的调用 | +| 知识事实 | `[适用税率](TaxPolicy.rate)` | 一项具有来源、范围、版本的知识 | + +第三种不能只靠前两种来解释。 + +例如,编译器能确定 `TaxPolicy.rate` 返回 `0.10`,只能证明“目标被正确解析并返回该值”,不能证明“2026 年某个地区、某种业务适用的税率确实是 10%”。 + +确定性执行和知识真实性是两个独立维度。 + +我建议把 Marqdo 的知识模型扩展为以下结构: + +Markdown 文档 + +自然语言叙述、表格、函数与知识定义 + +Semantic Artifact · 语义制品 + +稳定身份、类型、签名、实现、契约、依赖、证据 + +Verified Knowledge Reference + +解析引用、检查约束、固定版本、判定可否复用 + +解释执行 + +知识检索 + +AI 复用 + +这里最重要的新概念不是链接,而是 Semantic Artifact(语义制品)。 + +它应当是 Marqdo 编译器第一次真正统一代码、文档与知识的中间产物。 + +### 一个语义制品应该包含什么? + +建议最小模型如下。这里是我的架构提案,不是当前仓库已经实现的格式。 + +``` +{ + "id": "knowledge://project/TaxPolicy/rate", + "kind": "fact", + "signature": { + "params": [], + "returns": "number" + }, + "implementation": { + "ir": "compiled-reference", + "digest": "sha256:..." + }, + "contract": { + "unit": "ratio", + "scope": "example-policy", + "effects": "pure" + }, + "provenance": { + "source": "policy.md#rate", + "digest": "sha256:..." + }, + "verification": { + "status": "verified", + "methods": ["source-check", "contract-test"] + } +} +``` + +其中 `id` 是符号身份,`implementation.digest` 是编译内容指纹,`provenance` 是来源证据,`verification` 是验证记录。 + +这样一来,AI 复用的对象就不再是“某个名字看起来正确的函数”,而是一个具有明确身份和约束的知识制品。 + +需要注意:这里的 `verified` 只能表示通过了所声明的验证方法,不能凭此宣称该知识在所有现实情境下都正确。 + +## 四、重新定义 `[]()`:统一写法,不强行统一所有行为 + +我建议继续保持你所追求的语法纯度: + +``` +[人类可读的描述](机器可解析的目标) +``` + +不引入额外的 `knowledge:`、`call:` 或 `ref:` 前缀,也不让 AI 记忆复杂的新标记。 + +但编译器必须区分目标的性质,而不是把一切都当作普通表达式立即求值。 + +A · 表达式遮蔽 + +计算 + +``` +**total = [应付总额](price * quantity + shipping)** +``` + +对原有表达式的透明包装。编译后仍是普通表达式,描述不改变值。 + +B · 能力引用 + +复用 + +``` +**total = [计算应付总额](Pricing.total(订单))** +``` + +解析到已编译函数,检查参数、类型、依赖、权限和版本,然后调用。 + +C · 知识事实引用 + +知识 + +``` +用户可以查阅[李白的出生年份](李白.出生年份)。 +``` + +解析到知识制品;view 展示事实、来源和验证状态。正文保持惰性,不自动产生副作用。 + +这种设计保留了 `[label](expr) ≡ expr` 的计算规则,但增加了一个重要条件:编译器首先要解析 `expr` 的目标类型,然后才能决定它应该怎样验证、绑定和使用。 + +这不会使语言多出三套语法,反而能够避免当前设计中“语法统一了,但知识语义仍然散落在工具中”的问题。 + +## 五、你的第二个目标,最关键的是“绑定”而不是“调用” + +假设有这样一份知识文档: + +``` +# 李白 + +## 出生年份 + +| 返回 | 类型 | 来源 | +|---|---|---| +| 701 | number | corpus/libai.md#birth | + +*701* +``` + +另一个文档写: + +``` +李白的[出生年份](李白.出生年份)是 701 年。 +``` + +理想情况下,编译器应该执行一条确定性的处理链: + +Resolve — 查找 `李白.出生年份` 指向哪个知识单元 + +Bind — 绑定稳定 Symbol ID,而不是仅保存字符串 + +Validate — 检查返回类型、来源、契约与依赖 + +Pin — 根据需要固定知识版本和内容指纹 + +Evaluate — 仅在允许执行的上下文中求值 + +Trace — 将引用关系、验证结果与来源写入知识图 + +此时,编译器内部的引用不应该只是: + +``` +"李白.出生年份" +``` + +而应该更接近: + +``` +KnowledgeRef { + target_symbol_id, + resolved_artifact_id, + expected_signature, + pinned_digest, + verification_policy, + source_span +} +``` + +其中的 `target_symbol_id` 解决“引用谁”,`pinned_digest` 解决“引用哪个版本”,`verification_policy` 解决“什么时候可以信任它”。 + +这才是让 AI 不必重新生成已有知识,而是能够确定性地调用已有知识的技术基础。 + +还有一个必须考虑的问题:如果编译器只记录函数源码哈希,而函数内部调用的其他知识已经发生变化,那么源码没有变,实际执行语义也可能已经变化。因此,至少要对调用依赖形成可追踪的版本关系;对需要严格复现的纯函数,还应生成包含传递依赖的制品指纹。对于网络请求、时间、随机数等外部效应,则必须记录环境和执行条件,不能简单承诺重放一定得到相同结果。 + +## 六、仓库当前设计里,我最想修改的三个地方 + +### 1. 不要继续把类当作所有知识的唯一载体 + +[knowledge-layers.md](https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md?utm_source=chatgpt.com) 提出用 `# 李白 = > 诗人` 表示知识个体,也就是“单体知识类”。 + +这可以作为兼容实现路径,但我不建议把它提升为最终的知识本体。 + +因为“李白是诗人的一个个体”与“李白是诗人的子类”并不相同。让每一个事实实体都成为一个类,可能在知识库规模扩大后引入继承关系和个体关系的混淆。 + +更理想的是:让编译器内部明确区分 `Type`、`Entity`、`Fact`、`Function`、`Capability` 等制品类型。Markdown 源码可以继续使用现有的标题、表格和 frontmatter 承载这些信息,不要求立即增加新语法。 + +### 2. 不要让 `check` 与 EKC 各自维护一套知识理解 + +目前 EKC 已经有 Symbol、Capability、Knowledge、Graph 和 REUSE→ADAPT→CREATE 等概念。参见 [engineering-knowledge.md](https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md?utm_source=chatgpt.com)。 + +这里完全没有必要再为 `[]()` 平行开发另一套知识注册表。 + +我建议把架构整理成: + +- 编译器负责产出统一 Semantic IR、符号信息和引用关系; +- `check` 消费这些信息进行验证; +- EKC 将它们投影成知识图和上下文包; +- `view` 消费同一份信息展示可读知识; +- Agent 使用同一份引用解析接口,而不是重新理解 `.mq.md` 文本。 + +如此一来,编译器就是事实上的知识系统基础,EKC 不再承担第二次解释源码的职责。 + +### 3. 不要认为“描述过期”和“知识过期”是一回事 + +仓库中的 [occlusion-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/occlusion-syntax.md?utm_source=chatgpt.com) 已经意识到遮蔽会产生信任负债,并设计了标签引用一致性和新鲜度检查。这是有价值的方向。 + +但是,三类变化必须区分: + +| 变化 | 应该检查什么 | +| ------------- | -------------- | +| 实现变了,描述没变 | 描述是否仍与行为一致 | +| 知识来源变了,函数没变 | 知识事实是否仍然有证据支持 | +| 引用目标变了,代码还能运行 | 是否仍满足原始契约和版本要求 | + +尤其是第三种:AI 幻觉可能表现为调用了一个真实存在、类型也正确、但是业务含义完全错误的函数。 + +纯粹的符号解析和类型检查抓不住这种错误。因此,需要让能力契约、适用范围和知识来源成为可检查的制品属性,而不是只依赖 `[]` 中的自然语言。 + +## 七、建议的实施顺序 + +不要一次性实现完整知识图谱、版本锁定、自动修复和复杂本体系统。我建议分成四个阶段,每一阶段都必须有独立的可执行验收。 + +| 阶段 | 核心交付 | 必须通过的测试 | +| ------------ | ------------------------------------- | ---------------------------------- | +| P0 · 统一引用语义 | `[]()` 的统一 AST、目标类型识别、正文/代码上下文区分 | 不再因 Classic/Occlusion 模式造成静默错义 | +| P1 · 稳定寻址 | 项目符号索引、类函数解析、稳定 Symbol ID、静态 LinkInfo | 两文档李白示例无需实例化即可完成解析与引用 | +| P2 · 可验证知识制品 | Semantic Artifact、契约、来源、指纹、统一诊断 | 删除目标、修改签名、改变来源,均得到准确诊断 | +| P3 · 确定性复用 | 依赖图、制品锁定、EKC 集成、Agent 引用优先策略 | AI 不重新生成已存在的能力;错误、过期和不适用的知识被阻止直接复用 | + +我特别建议设置一个不依赖 LLM 的核心验收实验: + +准备 100 个知识单元,包含同名符号、跨文档引用、版本变更、类型不匹配、来源缺失、循环依赖和正常复用。由程序自动生成和验证预期结果。 + +先证明编译器能够正确识别、绑定和诊断这些情况,再引入 AI 测试上下文成本和幻觉率。否则很容易把模型能力、索引召回率与编译器的正确性混在一起。 + +## 八、重新评价 Marqdo 的研究主张 + +过去 Marqdo 的核心叙述是: + +> 代码即文档,文档即知识库,知识即可执行。 + +我认为现在可以把它变得更加严格: + +Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行、可复用的知识制品的语言与编译系统。 + +这个定位的价值不在于“Markdown 可以运行代码”,也不在于“Markdown 链接能调用函数”。这两点单独来看都不足以形成很强的研究贡献。 + +它真正值得探索的创新组合是: + +一份自然语言与程序混合的源码,经过统一编译后,同时生成可执行程序、语义符号体系、验证证据、版本化知识引用和 AI 可消费的复用接口。 + +当然,这仍然是一个待证明的系统设计目标,而不是当前 v2.0.0 已经达到的状态。 + +## 最终判断 + +你的 `[]()` 方向值得保留,甚至值得作为下一轮 Marqdo 核心架构调整的切入点。但我不建议继续把主要精力投入到如何让 `[]()` 兼容更多语法、更多函数调用形式或更多 Markdown 场景。 + +你现在缺少的不是更漂亮的链接语法,而是一个由编译器负责维护的“知识身份与语义绑定层”。 + +这也是我认为应该优先修正当前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的地方:它现在主要把链接理解为“表达式 + 描述 + 元数据”;下一版应明确规定,表达式可以解析到独立的、具有身份与验证状态的知识制品。 + +当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。 + +而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。 \ No newline at end of file diff --git a/examples/executable-knowledge/README.md b/examples/executable-knowledge/README.md new file mode 100644 index 0000000..5cce801 --- /dev/null +++ b/examples/executable-knowledge/README.md @@ -0,0 +1,35 @@ +# 可执行知识系统示例:订单含税总额 + +这是 [可执行知识系统设计](../../doc/design/executable-knowledge-system.md) 的目标示例。 +它刻意展示 `[]()` 不只包“知识函数”:同一套语法同时命名取元、循环、推导、跨文件调用和正文结论。 + +| 文件 | 图中的职责 | 关键步骤 | +|---|---|---| +| `corpus/tax-policy-2026.md` | E:证据 | 税率原文 | +| `schema/order.mq.md` | C:概念 | 订单/订单行字段与单位 | +| `knowledge/tax-2026.mq.md` | K:原子知识 | `[标准税率](0.13)` 及来源 | +| `capabilities/order-pricing.mq.md` | D:推导知识 | 取元、调用、循环、汇总 | +| `docs/invoice-answer.mq.md` | N:叙述知识 | 用同一个计算给人可读的回答 | + +## 读法 + +`[]()` 的每一次出现都是 `Named`: + +```markdown +[订单行金额](at(行, "金额")) # observe +[本行含税价](订单行金额 * (1 + 税率)) # derive +[逐个订单行](遍历 订单.行 为 行) # iterate +[含税总价](pricing.订单定价.含税总额(订单)) # reuse / narrate +``` + +它们不是四种语法。`()` 中仍是原有的取元、算术、循环和调用;`[]` 让每一步同时可读、可查、 +可在图中定位。当前实现尚不能完整运行该目标形式(类函数、统一 `Named`、步骤图仍是设计目标), +但它给出了实际项目中应当写成什么样子。 + +## 预期闭环 + +1. `check` 从每个 `[]()` 提取观测、推导、遍历和调用依赖; +2. `view` 在“含税总额”旁显示所经过的订单行、标准税率和税率原文; +3. 税率原文变更时,`impact` 找到原子税率、订单定价、发票回答中的每一个命名步骤; +4. `verify` 只重算 pure 步骤,不执行写入或发送等 `act` 步骤; +5. agent 通过 catalog 得到“已有订单定价能力”和其证据链,不必从自然语言猜测。 diff --git a/examples/executable-knowledge/capabilities/order-pricing.mq.md b/examples/executable-knowledge/capabilities/order-pricing.mq.md new file mode 100644 index 0000000..9cf7a43 --- /dev/null +++ b/examples/executable-knowledge/capabilities/order-pricing.mq.md @@ -0,0 +1,26 @@ +--- +id: capability.order-pricing +type: Capability +import tax:../knowledge/tax-2026.mq.md +import order:../schema/order.mq.md +--- + +# 订单定价 + +## 含税价 + + `行` + +**金额 = [订单行金额](at(行, "金额"))** +**品类 = [订单行品类](at(行, "品类"))** +**税率 = [适用税率](tax.标准税率.查询(品类))** +**结果 = [本行含税价](金额 * (1 + 税率))** +**结果** + +## 含税总额 + + `订单` + +- [逐个订单行](遍历 订单.行 为 行) + **行含税价 = [计算本行含税价](订单定价.含税价(行))** + +**总额 = [汇总全部行含税价](sum(行含税价))** +**总额** diff --git a/examples/executable-knowledge/corpus/tax-policy-2026.md b/examples/executable-knowledge/corpus/tax-policy-2026.md new file mode 100644 index 0000000..dceea99 --- /dev/null +++ b/examples/executable-knowledge/corpus/tax-policy-2026.md @@ -0,0 +1,5 @@ +# 2026 年标准增值税率 + +本示例的原始证据:标准税率为 13%。 + +此文件只作来源定位,不执行。 diff --git a/examples/executable-knowledge/docs/invoice-answer.mq.md b/examples/executable-knowledge/docs/invoice-answer.mq.md new file mode 100644 index 0000000..1731efe --- /dev/null +++ b/examples/executable-knowledge/docs/invoice-answer.mq.md @@ -0,0 +1,13 @@ +--- +id: document.invoice-answer +type: Answer +import pricing:../capabilities/order-pricing.mq.md +--- + +# 发票回答 + +**总额 = [订单的含税总价](pricing.订单定价.含税总额(订单))** + +这张订单的含税总额是[含税总价](总额)。 + +> view 应可展开:含税总价 → 汇总全部行含税价 → 逐个订单行 → 本行含税价 → 适用税率 → 税率原文。 diff --git a/examples/executable-knowledge/knowledge/tax-2026.mq.md b/examples/executable-knowledge/knowledge/tax-2026.mq.md new file mode 100644 index 0000000..0e95c95 --- /dev/null +++ b/examples/executable-knowledge/knowledge/tax-2026.mq.md @@ -0,0 +1,18 @@ +--- +id: knowledge.tax.standard-2026 +type: Fact +sources: + - ../corpus/tax-policy-2026.md#2026 年标准增值税率 +--- + +# 标准税率 + +## 查询 + + `品类` + +| 返回 | 类型 | 来源 | +|---|---|---| +| 0.13 | number | corpus/tax-policy-2026.md#2026 年标准增值税率 | + +**税率 = [标准税率](0.13)** +**税率** diff --git a/examples/executable-knowledge/schema/order.mq.md b/examples/executable-knowledge/schema/order.mq.md new file mode 100644 index 0000000..b6fcc57 --- /dev/null +++ b/examples/executable-knowledge/schema/order.mq.md @@ -0,0 +1,17 @@ +--- +id: schema.order +type: Schema +--- + +# 订单 + +| 字段 | 类型 | 说明 | +|---|---|---| +| 行 | list<订单行> | 待计价的订单行 | + +## 订单行 + +| 字段 | 类型 | 说明 | +|---|---|---| +| 金额 | number | 未税金额 | +| 品类 | text | 用于选择税率 |