docs: define executable knowledge implementation baseline

This commit is contained in:
cflmy committed 2026-10-23 08:06:38 +00:00
1 parent 8bbe017a5e
commit 92de46aca4
5 files changed
+2260 -1

No files matched your search

+3
View File
@@ -13,6 +13,8 @@
## 当前文档
> **可执行知识下一阶段的规范优先级**:实现 `[]()`、Semantic Artifact、知识绑定、验证、锁定、EKC/Agent 复用时,以 [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) 为实施基线。与其冲突的早期链接、遮蔽、知识分层或 EKC 设计只作历史参考。
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
@@ -108,6 +110,7 @@
| [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 闭环 |
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
| [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 计划 |
+108 -1
View File
@@ -343,4 +343,111 @@ Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行
当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。
而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。
而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。
是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 Marqdo 的最终目标。
实际上,这两者应当区分。
你最初提出的:
> 代码即文档,文档即知识库,知识即可执行。
并不只是一句理念性的口号,它本身已经包含了完整的目标链条:
1. 代码即文档:知识与程序不再被割裂为两套独立的表达体系。
2. 文档即知识库:文档中的内容不再只是供人阅读的信息,而是可以被组织、定位、理解和关联的知识。
3. 知识即可执行:知识不再停留在被检索和解释的阶段,而是能够被直接调用、组合和复用。
其中,知识复用就是第三阶段最重要的结果之一。
因此,我之前提出的“可寻址、可验证、可执行、可复用”,实际上是在描述达成第三阶段需要具备的工程性质,而不是一个比原始理念更高层次的新目标。
## 真正需要解决的是:什么才算知识被复用?
我认为这里才是 Marqdo 当前设计最值得深入的地方。
假设 AI 需要计算一笔订单的最终价格。
传统方式可能是:
- 检索价格计算文档;
- 阅读文档中的公式和约束;
- AI 自己理解并重新编写计算逻辑;
- 执行新生成的代码。
这个过程中,知识被读取了,但未必真正被复用。AI 仍然可能理解错误、遗漏约束或生成不一致的实现。
而你想实现的 Marqdo 应该是:
```
订单最终价格为[计算后的价格](订单.最终价格(订单数据))。
```
这里 AI 不需要重新理解定价公式并生成一套新算法,而是引用已经存在的知识实现。
如果该实现的身份、依赖、契约和适用条件都能被确定,那么 AI 的任务就从:
“根据知识重新生成答案或程序”
转变成:
“发现知识 → 判断是否适用 → 引用知识 → 执行知识 → 使用结果”
这才是 Marqdo 的核心价值。
## 所以,`[]()` 应该承担什么角色?
我建议将整个体系理解成:
代码即文档
统一人类叙述与机器可执行内容
文档即知识库
知识具有结构、身份、关联与约束
知识即可执行
知识能够被确定性引用、调用和组合
知识真正复用
AI 优先使用既有知识,而非反复解释和重新生成
`[]()` 不需要独自完成这一切。
它应该成为整个体系中知识从文档进入使用场景的统一入口。
而编译器、符号系统、知识索引、验证系统与 EKC,则共同保证这个入口背后的知识可以可靠使用。
这里有一个很重要的区别:
- `[]()` 负责表达“我要使用这段知识”。
- 编译器负责确定“究竟是哪段知识”。
- 验证系统负责判断“这段知识是否满足当前使用条件”。
- 运行时负责执行知识。
这些职责不应该全部压到 `[]()` 的语法设计上。
## 我现在更倾向于保留你的原始理念
甚至不建议用我之前那段冗长的定义替换它。
“代码即文档,文档即知识库,知识即可执行”已经足够准确。
真正值得补充的是它背后的一个技术原则:
> 知识复用应当基于已编译知识的确定性引用,而不是基于自然语言的重复解释与生成。
这句话比单纯强调“可寻址、可验证”更接近你真正想解决的 AI 问题。
不过还需要保持一个边界:确定性引用能够减少 AI 在重新解释和生成过程中产生的错误,却不能自动保证被引用的知识本身正确。因此验证仍然必要,只是它属于实现可靠复用的手段。
我认为 Marqdo 下一步最值得研究的,已经不是“如何让文档变成知识库”,而是一个更具体的问题:
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
@@ -0,0 +1,295 @@
# Marqdo 可执行知识体系:统一语义制品与知识引用设计规范
> 状态:设计提案(非当前版本的已实现功能)
> 基线:仓库 main,2026-10-23;README 标记 v2.0.0;跨文档类调用与 LinkInfo 为 v2.1 目标
> 宗旨:**代码即文档,文档即知识库,知识即可执行。**
> 核心判据:当 AI 遇到任务时,能否先发现已有知识,并以确定性绑定复用,而不是再生成一份“看起来相同”的知识或实现?
## 1. 决策摘要
保持 `[描述](表达式或知识目标)` 的 Markdown 形态,不引入新的前缀或第二套表达式文法。`[]` 是面向读者的陈述,`()` 内的内容进入统一表达式解析器。语言内部建立稳定的 **Semantic Artifact(语义制品)** 和 **Verified Knowledge Reference(可验证知识引用)** 两种核心抽象。前者承载身份、语义、实现、依赖、契约与来源;后者是一个经编译期解析、受上下文约束的引用。它们不必对应新语法标记,而是 `.mq.md` 经语义分析得到的统一中间表示。
**三项不变式:**
1. **表达式透明性**:在求值上下文中 `[L](E)` 与 `E` 取得同一类型和值;`L` 不进入符号绑定或改变结果。引用额外产生诊断与溯源元数据。
2. **文本安全性**:叙述中的知识链接在 `check/view` 中解析;`run` 不因正文出现链接而隐式执行有副作用的函数。导航链接(HTTP、相对文档路径)仍属于普通 Markdown 链接。
3. **知识可信边界**:`resolved`、`compiled`、`tested`、`source_verified`、`domain_validated` 是不同状态。能执行不等于事实真;有来源不等于来源仍然适用。没有证据时允许展示,但不得向 agent 宣称为已验证知识。
### 1.1 不是要做的事
- 不将 Markdown 转成一个独立于解释器的新运行语言。
- 不把所有知识都强制构建为类,也不等同“知识 = 函数”。
- 不把自然语言标签作为权限或事实正确性的证明。
- 不把符号名的字符串匹配当成稳定知识复用。
- 不要求所有调用都锁版本:本地临时表达式可无锁,跨文档公共知识/关键业务则可选或强制锁定。
## 2. 以真实仓库为准的兼容边界
| 语法或能力 | 当前已支持 | 目标设计/注意事项 |
|---|---|---|
| `.mq.md` 和 Markdown 叙述 | 是 | 原有叙述默认安全 |
| `#` 对象/类型,`##` 函数/方法 | 是 | 目标:不依赖 `self` 的函数可通过类命名空间直接调用 |
| `**表达式**`、`*返回*` | 是 | 复用现有表达式解析器,不另造链接表达式 |
| `+ \`参数\``/叙述推断参数 | 是 | 签名必须能静态抽取并生成规范化形式 |
| `1.` 条件分支、`-` 循环 | 是 | 新版链接循环形式须通过模式迁移;旧式依赖 Classic |
| Markdown 表格→List/Map/列向表/行向记录 | 是 | 数据语义与契约表应从上下文区别 |
| Frontmatter `import` | 是 | 可作为当前跨文档路径的兼容实现 |
| `[描述](本地表达式)` | v2.0.0 已有,主要需 `markup: occlusion` | 统一后免模式开关;旧 `[键](集合)` 必须避免静默变义 |
| `类.函数` 无实例直接调用 | 未按目标实现 | **新能力**:区分类函数/实例方法、隐式零参调用 |
| 跨文档项目符号索引 | 尚缺 | **新能力**:可控作用域、同名消歧、增量索引 |
| LinkInfo/知识引用图/links.lock | 目标设计 | **新能力**;与已有 EKC 统一,拒绝第二套知识图 |
| 双执行后端(树遍历、字节码) | 是 | 引用语义必须在两个后端一致 |
项目示例分为:**V2-目标示例**(体现最终范式)与**V2.0-兼容示例**(现有调用方式)。所有目标示例是规范性设计,不宣称已在 v2.0.0 执行验证。
## 3. 知识不是代码字符串:规范化语义模型
### 3.1 Semantic Artifact
每个可引用实体编译为 `Artifact`,而非仅落入 AST 一个节点。
```text
Artifact {
symbol_id: StableSymbolId, // 跨增量构建稳定的身份(命名空间 + 显式/规范化路径)
kind: Type | Entity | Fact | Function | Capability | Constraint | Policy | Dataset,
visibility: Local | Module | Project | Exported,
source_span: SourceSpan,
signature: CanonicalSignature?, // 参数、返回值、默认值、单位与结构类型
ir: CompiledIR?, // 运行逻辑或规范化常量;普通叙述可无
effects: EffectSet, // pure / fs.read / fs.write / network / llm / time / random ...
dependencies: [SymbolId],
contract: [Predicate | Schema | Condition],
provenance: [SourceRef],
hashes: { interface, implementation, dependency_closure, evidence },
verification: VerificationRecord
}
```
区分以下四个概念:
- **Identity(身份)**:目标属于哪一知识单元;名称调整可使用迁移映射,不允许悄悄重绑定到不同实体。
- **Content(内容)**:符号当前定义和可执行 IR;代码变更指纹改变。
- **Applicability(适用性)**:参数、业务前提、单位、时间/地区/场景等约束;匹配才可复用。
- **Evidence(证据)**:来源、测试与验证结果。证据改变不等同于程序改变,但需要重新评估可信状态。
### 3.2 Knowledge Reference
```text
KnowledgeRef {
label: String,
payload_ast: Expr,
context: Narrative | Code | Return | Argument | Table | Heading,
resolution: ResolvedSymbol | LocalExpression | NavigationURL | Unresolved,
target_symbol_id: SymbolId?,
target_digest: Digest?,
expected_signature: Signature?,
required_verification: VerificationPolicy,
source_span: SourceSpan
}
```
`[描述](E)` 在运行语义上是透明的,但其静态解析必须构建 KnowledgeRef。在调用点将地址绑定到 `SymbolId`,不能每次由 AI 重新解释描述。
### 3.3 类型 / 知识实体 / 计算能力分别建模
- `# 诗人` 是 Type;`# 李白 = > 诗人` 在现有语法中仍是**继承/特化**。作为 v2.1 过渡方案可视为“单体知识类”,但不得默认为真正的 `instance_of`。
- 事实可以由 `## 出生年份` + 返回值 + 来源表承载;编译器推导为 Fact Artifact。是否是事实要根据可检查的声明/契约,不应仅凭函数名字猜测。
- 业务函数如 `## 计算应付` 是 Function/Capability;不应因为带中文说明就被误识别成事实。
- 未来需要大规模实体库时,Entity/Fact 应支持表驱动注册,不为每个实体强制生成 Rust 或 Marqdo 类。
## 4. `[]()` 的确定语义
### 4.1 一个表面形式、三种解析结果
| 表面形式 | 静态解释 | `run` | `check` / `view` |
|---|---|---|---|
| `**总额=[应付](数量*单价)**` | 本地表达式遮蔽 | 求值 | 保存标签、表达式和诊断 |
| `**总额=[计算总额](Pricing.计算总额(订单))**` | 知识能力调用 | 绑定后调用 | 检查签名、效应、依赖和版本 |
| `文中参见[税率](Policy.税率)` | 叙述知识引用 | 不执行 | 解析、展示受信任/未验证状态,纯目标可选择显式求值 |
| `[项目文档](./guide.md)` | 导航链接 | 不执行 | 保持 Markdown 导航 |
语法上的“同权”是 `()` 与 `**...**` 共用表达式文法;**不是正文和代码拥有相同的执行许可**。 `view` 对具外部效应的目标默认只展示元数据,必须明确授权才允许运行。
### 4.2 最小语义规则
```text
parse_bracket(label, payload, context) -> KnowledgeRef
context ∈ executable_context:
verify_resolved_target(); evaluate(payload_ast)
context ∈ narrative_context:
resolve_only(); never_schedule_effects()
payload ∈ ordinary_navigation:
preserve_as_markdown_link()
```
### 4.3 唯一性与优先级
1. 当前词法作用域的变量/接收者;
2. 当前文档的声明;
3. 显式 `import` 命名空间;
4. 项目导出索引(受 `--fs-root` 和导出策略约束);
5. 内置/已安装扩展。
如果两个候选都满足同一级优先规则,报 `link.ambiguous`;不能随文件顺序自动挑一个。解析失败必须有诊断,不能把知识目标悄悄解释成字面字符串或导航路径。
### 4.4 类函数 vs 实例方法
- 目标函数使用 `self/自` → 实例方法,必须有显式接收者。
- 函数不使用接收者 → 可由 `类.函数` 调用;不运行类的构造体。
- 路径解析到零参函数时可以省略 `()`,但**函数作为一等值的语义必须避免与隐式调用冲突**。建议只有被 `[]()` 用作知识目标、或显式值需求时才触发零参隐式调用;直接 `类.函数` 在函数值场景需明确消歧。最终以一致的形式化语义测试冻结。
### 4.5 版本策略与效应
`interface_digest` 代表签名兼容性,`implementation_digest` 代表实现变化,`dependency_closure_digest` 代表传递依赖;`evidence_digest` 代表证据状态。既存调用在接口未变时不必全部报错,但“严格复现”任务应使用 lock 来禁止目标悄然变化。
纯知识事实允许受控求值与缓存;依赖网络、时间、随机数、外部模型的调用即使锁了源码也不天然确定。必须记录输入快照、环境与效应,并明确“不保证结果复现”的状态。
## 5. 静态分析、来源与可信性
### 5.1 五层验证(必须分层报告)
1. **Parse**:Markdown 结构/语法可解析。
2. **Resolve**:目标存在,歧义可消除。
3. **Type/Contract**:签名、入参与结构类型、单位、前置条件匹配。
4. **Execution/Test**:纯函数或受控沙箱完成运行与测试。
5. **Evidence/Domain**:事实来源可访问,内容匹配,满足适用范围;复杂自然语言事实可能需要人工或 LLM 辅助复核,复核结果必须标识非确定性。
严禁将 `check OK` 展示成“现实知识已被证明正确”。
### 5.2 诊断码草案
| Code | 默认级别 | 含义 |
|---|---|---|
| `link.unresolved` | error | 找不到可绑定的目标 |
| `link.ambiguous` | error | 目标符号不唯一 |
| `link.kind_mismatch` | error | 把类型/实例/函数错当为可执行知识 |
| `link.instance_only` | error | 类调用命中实例方法 |
| `link.arg_mismatch` | error | 参数与签名不符 |
| `link.effect_forbidden` | error | 当前位置不允许此类副作用 |
| `link.target_changed` | warning/error | 被锁定或要求稳定的目标发生变更 |
| `knowledge.source_missing` | warning/error | 来源缺失 |
| `knowledge.source_changed` | warning | 来源指纹变化尚未复核 |
| `knowledge.constraint_unmet` | error | 当前输入不满足适用条件 |
| `knowledge.unverified` | info/warning | 可用但未得到所需级别的验证 |
| `label.ref_dangling` | error | 标签中反引号引用无法解析(保留已有规则) |
| `label.possibly_stale` | hint | 代码变更但描述未更新,需要人工检查 |
标签里提到的自然语言不能被静态类型系统完全证明。所有自动语义比对必须报告置信限制。
## 6. 编译器实施架构
```text
Markdown Source
│
├─ CommonMark/GFM-aware parse + Marqdo lexical context
▼
Syntax AST (prose + code + table + heading + bracket)
▼
Symbol Index (module, class, function, fact, export)
▼
Resolution & Type / Contract / Effect Analysis
▼
Semantic Artifact IR + KnowledgeRef IR
├──────────────┬──────────────────┬───────────────────────┐
▼ ▼ ▼ ▼
Tree Interpreter Bytecode VM View / Debug EKC/Catalog/MLSP
│ │
└──────────┬────────────┘
▼
Agent deterministic reuse
```
**实现优先原则**:统一在语义分析层生成符号与引用元信息。不要在 view、EKC、Agent 中分别重新解析 `.mq.md` 来猜同一段代码代表什么。
### 6.1 Markdown 链接兼容性
`[描述](含空格或括号的表达式)` 不是任意标准 Markdown 渲染器都可识别的合法 URL 目标。Marqdo 必须定义其**源码级别的上下文语义和渲染行为**:先保留有意义的源码跨度,再由专属 view 转为原生可读的标签及悬浮信息;不能假设 GitHub Markdown 会在所有表达式上正确渲染。代码围栏、行内代码、转义以及普通 URL 链接不能被误识别成可执行引用。
### 6.2 旧语法迁移
Classic 的 `[键](集合)` 曾用于取元,`- [项](集合)` 曾用于循环。默认统一为遮蔽含义前,需要 AST 辅助迁移:
```text
[key](table) → [可读描述](at(table, key))
- [item](list) → - [逐项遍历](遍历 list 为 item)
```
避免靠简单正则批量替换;不能把旧代码成功运行但产生不同值视为兼容。迁移应生成审计报告、变更 diff 与双后端对照测试。
## 7. EKC 与 Agent 复用协议
当前 EKC 已有 Symbol、Capability、Knowledge、Context Pack、REUSE→ADAPT→CREATE。将这些能力变为统一 Semantic Artifact 的**投影/索引**,不要再建第二套符号管理器。
Agent 必须按以下状态机处理:
```text
TASK → DISCOVER → RESOLVE → CONTRACT_CHECK
│ │
│ ├─ verified + applicable → REUSE → EXECUTE → TRACE
│ ├─ adaptable → ADAPT → VERIFY → PROMOTE
│ └─ absent/unusable → CREATE → VERIFY → PROMOTE
└─ ambiguous → REQUEST_DISAMBIGUATION / FAIL_CLOSED
```
- **Discovery 是召回**,可以模糊检索,不等于可信复用。
- **Resolve 必须精确**,让自然语言意图最终绑定到具体 `SymbolId`。
- **Reuse 是编译器行为**:Agent 持有可验证引用,并使用明确的输入与契约,不复制代码段。
- **Promote 是门槛**:新生成内容必须通过所需静态检查、测试与来源规则才可进入已验证知识索引。
- **Trace 可审计**:保存“这次回答具体用了哪些符号、哪些版本和哪些输入”,不是仅存 LLM 的解释文本。
建议新增的 MLSP 读接口:`artifact.find`、`artifact.inspect`、`link.resolve`、`artifact.verify`、`artifact.impact`、`artifact.bind`;后者在编译器确定性解析后返回可调用句柄/引用描述,不应凭自然语言标签直接执行。
## 8. 里程碑与硬验收
### M0 语义冻结
明确新语义与 Classic 的区别,形成机器可读 gold cases,涵盖 URL、嵌套括号、空标签、取元、循环、代码围栏、换行、标题、叙述链接与作用域。所有未经标注的旧语义变化不得静默放行。
### M1 符号身份与项目索引
构建导出符号表、稳定 `SymbolId`、同名诊断。验收:同仓两个 `李白` 定义应报歧义;限定名可解析;改变目录扫描顺序不影响绑定结果。
### M2 统一 Bracket IR 与类函数调用
语法识别→表达式解析→目标绑定→双后端执行。验收:含 `self` 与不含 `self` 的函数正确分派,构造不产生意外副作用;正文不自动执行。
### M3 Semantic Artifact / 验证
签名、effect、contract、provenance、验证记录与指纹。验收:接口修改、依赖修改、证据变化、适用条件不匹配得到不同诊断。
### M4 EKC、view、agent 集成
整个工具链共享 SymbolId/LinkInfo,生成 links graph、可查看调用与来源、可追踪复用。验收:图边与实际编译的调用目标完全一致;Agent 命中已有能力时不得偷偷生成新实现。
### M5 基准实验(对照 Python/Notebook/普通 Markdown+检索)
同一模型、同一任务集、相当的工具与提示预算;分别统计可执行成功率、知识错误引用率、重复实现比例、文件改动数、调用/修复次数、总 tokens、端到端时延、可复核程度。公开任务、生成器、冻结环境、置信区间和失败样本;不要使用只在 Marqdo 方案可解的夹具,也不要把编译器固有优势等同整个 Agent 的领先。
## 9. 设计原则冻结
1. **源码可读,编译结果确定**。
2. **知识是制品,不是文本片段**。
3. **检索可以模糊,绑定必须确定**。
4. **知识能够执行,但执行不等于真实**。
5. **知识可以复用,但必须满足契约与适用条件**。
6. **显示文字可自由,语义判断不依赖显示文字**。
7. **默认保持叙述安全,副作用需要明确执行上下文**。
8. **保持一种语法,一个语义解析器,一套符号索引**。
9. **双后端与 view/EKC 使用同一份语义中间表示**。
10. **失败必须可观察,不能因为链接看起来优雅而隐去错误**。
## 10. 来源依据
仓库:<https://github.com/cflmy/marqdo>。重点阅读:
- `README.md`(v2.0.0 现状与 v2.1 目标)
- `doc/design/markdown-mapping-v0.3.md`(基本语法)
- `doc/design/objects.md`(类、实例、自/self、继承)
- `doc/design/link-syntax.md`(现有链接设计声明)
- `doc/design/occlusion-syntax.md`(遮蔽与描述新鲜度)
- `doc/design/knowledge-layers.md`(知识分层、过渡型单体类)
- `doc/design/engineering-knowledge.md`(EKC 与复用流程)
- `.cursor/skills/marqdo/reference.md` 与 `examples.md`(参考语法;其部分 Classic 旧写法必须经过迁移)
附录项目:`Marqdo_Executable_Knowledge_Example.md`。其中对未实现特性逐项标注,所有业务数据均为虚构演示数据。
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,400 @@
# Marqdo 可执行知识范式:多文件完整示例与对照
> **规范性目标示例**:用于描述 v2.1+ 期望语义;并非宣称 v2.0.0 已能运行所有代码。示例内价格、折扣、门槛均为虚构业务数据。
> 展示:Markdown 叙述、frontmatter 导入、`#` 类型、`##` 函数、继承、表格集合、隐式形参、`**` 代码、`*` 返回、条件有序列表、循环无序列表、变量反引号、带描述的 `[]()`、对象、契约、来源、知识索引与 Agent 复用。
## 1. 实际业务场景
一家虚构的“云雀书店”需要将定价规则维护为**人类可阅读的运营文档**,由网站、客服机器人、后端结算、审计报告复用,而不是让四个 AI 分别根据文字重新写四次逻辑。业务规则:普通会员 100% 计价,银卡会员 95%,金卡会员 90%;订单满 100 元免 8 元运费;仅处理人民币订单,件数为正整数。所有规则均为示例,没有现实效力。
### 项目结构
```text
bookshop/
├─ corpus/
│ └─ pricing-policy.md # 业务原始资料(不可执行)
├─ knowledge/
│ ├─ policy.mq.md # 已编译的政策知识
│ ├─ order.mq.md # 数据类型及订单操作
│ └─ pricing.mq.md # 定价能力
├─ apps/
│ ├─ checkout.mq.md # 业务执行入口
│ ├─ assistant.mq.md # AI 问答呈现/知识引用
│ └─ batch.mq.md # 列表与循环
└─ .marqdo/ # 生成:catalog、symbols、graph、links.lock
```
## 2. 原始资料 `corpus/pricing-policy.md`
```markdown
# 云雀书店价格政策(演示)
生效范围:2026 年演示订单,人民币;不代表任何真实商店。
## 会员折扣
普通会员不优惠;银卡会员九五折;金卡会员九折。
## 运费
商品合计满 100 元免运费,否则运费为 8 元。
## 约束
商品单价不得为负;数量必须为正整数。会员等级仅允许普通、银卡、金卡。
```
这是原始证据,并非运行时调用目标。它可被查看、引用和版本化,但不能因为被 AI 读到就自动获得 `verified` 状态。
## 3. 政策知识 `knowledge/policy.mq.md`
使用现有类/函数、返回值与契约表,将业务知识拆成稳定的、可发现的编译单元。
```markdown
---
title: 云雀书店演示定价政策
type: policy
---
# 书店政策
这是云雀书店的演示业务政策,供结算、客服和审计引用。
规则只适用于人民币演示订单,来源为
[价格政策原文](../corpus/pricing-policy.md)。
## 金卡折扣
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 0.90 | number | ratio | corpus/pricing-policy.md#会员折扣 |
*0.90*
## 银卡折扣
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 0.95 | number | ratio | corpus/pricing-policy.md#会员折扣 |
*0.95*
## 免运费门槛
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 100 | number | CNY | corpus/pricing-policy.md#运费 |
*100*
## 基础运费
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 8 | number | CNY | corpus/pricing-policy.md#运费 |
*8*
## 获取折扣
根据输入会员等级`等级`确定折扣比例。
| 参数 | 类型 | 说明 |
|---|---|---|
| 等级 | text | 普通、银卡、金卡 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 比例 | number | 0 到 1 之间的比例 |
1. `等级` == "金卡"
*[金卡优惠比例](书店政策.金卡折扣)*
2. `等级` == "银卡"
*[银卡优惠比例](书店政策.银卡折扣)*
3. *
*1*
```
**说明**:`书店政策.金卡折扣` 等类函数直接调用属于 v2.1 目标;现有 `#` 类型/`##` 方法和表格、分支是当前语言能力。严格策略下,非法会员等级应报 `knowledge.constraint_unmet` 而不是无条件走默认分支;此处末尾 `3. *` 只是语言分支结构示范,正式实现需要额外拒绝非法等级。
## 4. 订单类型与继承 `knowledge/order.mq.md`
```markdown
# 订单
一个订单至少包含数量、单价和会员等级。
## 描述
本方法使用`自`读取对象字段,属于**实例方法**。
*自*
# 线上订单 = > 订单
线上订单是订单类型的一个特化。此处是实际继承语义,不把它误称为“知识实体实例化”。
## 渠道
*"online"*
```
注意:`# 线上订单 = > 订单` 在 Marqdo 中的确代表子类型继承;`> 线上订单` 构造实例,实例方法需要实例接收者。在知识分层中,普通 Fact 不应强制视为类实例。
## 5. 核心能力 `knowledge/pricing.mq.md`
这是“知识直接被复用”的核心,而不是把文字重新交给 AI 算一遍。
```markdown
---
title: 价格计算能力
import policy:knowledge/policy.mq.md
---
# 定价
下列函数实现演示书店的结算规则,适用于人民币演示订单。
## 计算商品小计
输入商品`单价`和`数量`。
| 参数 | 类型 | 约束 |
|---|---|---|
| 单价 | number | 大于等于 0;单位 CNY |
| 数量 | number | 大于 0,且为整数 |
| 返回 | 类型 | 单位 |
|---|---|---|
| 小计 | number | CNY |
**小计 = [商品小计](单价 * 数量)**
*小计*
## 计算运费
根据商品折扣后的金额`金额`决定是否免运费。
1. `金额` >= [免运费门槛](书店政策.免运费门槛)
*0*
2. *
*[基础运费](书店政策.基础运费)*
## 计算应付金额
接受`单价`、`数量`、`等级`;输出应付总金额。
**小计 = [商品小计](定价.计算商品小计(单价, 数量))**
**折扣 = [当前会员折扣](书店政策.获取折扣(等级))**
**折后价 = [折扣后商品金额](小计 * 折扣)**
**运费 = [应收运费](定价.计算运费(折后价))**
**应付 = [最终应付人民币金额](折后价 + 运费)**
*应付*
```
**目标能力标记**:这一示例使用 `类.函数` 静态调用、跨文档自动类索引以及嵌入条件表达式中的知识引用,这些是计划实现的语义。当前实际版本中,一般需要显式 `import` 和实例句柄。其余 `**代码**`、`*返回*`、契约表、分支为现有基础。
这里看得最清楚:对读者,整段代码是一个有清晰描述的计算故事;对编译器,括号内是有类型、依赖、来源的调用图;对 AI,复用的不是价格公式的自然语言解释,而是绑定到已有符号的能力。
## 6. 结算入口 `apps/checkout.mq.md`
```markdown
---
title: 演示结算
import pricing:knowledge/pricing.mq.md
---
# main
一位金卡用户购买两件单价 60 元的商品。
**单价 = 60**
**数量 = 2**
**等级 = "金卡"**
**应付 = [本次订单应付款](定价.计算应付金额(单价, 数量, 等级))**
> 打印 内容=`应付`
```
预期:`60 × 2 × 0.90 = 108` 元,达到免运费门槛,输出 `108`。这是目标语义下的预期值,而非当前版本的实测输出。
**对照(相对现有版本更接近可执行)**:使用 `import`、构造实例,再调用实例方法。下面的最小兼容样例来自仓库 `examples/link-syntax/main.compat.mq.md`:
```markdown
---
markup: occlusion
import libai:libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
此兼容片段是仓库实例,不能直接替代上面的定价案例:它用于说明当前版本与目标引用模型之间的差距。
## 7. 文档问答 `apps/assistant.mq.md`
```markdown
# main
# 云雀书店结算说明
普通会员原价结算;金卡会员使用[已登记的金卡折扣](书店政策.金卡折扣)。
当前免运费门槛为[已登记的门槛金额](书店政策.免运费门槛)。
关于政策出处,参见[原始价格政策](../corpus/pricing-policy.md)。
```
这展示**知识链接与导航链接共存**:前两条必须由编译器解析知识目标,最后一条仍是传统 Markdown 导航。不应把全文正文都作为主动执行入口。UI 可以显示“来源文件/目标类型/验证状态/必要时的值”;若目标未验证,应明确标注。
## 8. 表格几何与循环 `apps/batch.mq.md`
演示一列 List、横表 Map、`@` 行向记录、无序列表循环和条件分支。根据 v2.0 新语义,旧 `[key](collection)` 取元改为 `at(collection,key)`。
```markdown
---
markup: occlusion
---
# main
`会员等级` =
| 等级 |
|---|
| 普通 |
| 银卡 |
| 金卡 |
`折扣说明` =
| 普通 | 银卡 | 金卡 |
|---|---|---|
| 1 | 0.95 | 0.90 |
`演示订单` =
| @ | 客户 | 等级 | 单价 | 数量 |
|---|---|---|---|---|
| 1 | 甲 | 金卡 | 60 | 2 |
| 2 | 乙 | 银卡 | 30 | 2 |
**银卡比例 = [银卡折扣值](at(折扣说明, "银卡"))**
- [逐个检查会员等级](遍历 会员等级 为 等级)
1. `等级` == "金卡"
> 打印 内容="识别到金卡会员"
2. *
> 打印 内容=`等级`
```
表格语义:单列→List;两列以上一数据行→Map;首列 `@`→按行组成的 List of Map。此处只演示集合构造、访问与循环,避免假定尚未验证的嵌套函数语义。`遍历` 链接循环是新设计形式,必须通过现有版本的解析器验收后才能标记为已实现。
## 9. 编译后的产物应当长什么样
下列均是**建议输出示意**,不是现有 CLI 的真实输出:
```json
{
"symbol": "knowledge://bookshop/定价/计算应付金额",
"kind": "capability",
"signature": {
"params": ["单价:number", "数量:number", "等级:text"],
"returns": "number:CNY"
},
"dependencies": [
"knowledge://bookshop/定价/计算商品小计",
"knowledge://bookshop/书店政策/获取折扣",
"knowledge://bookshop/定价/计算运费"
],
"effects": ["pure"],
"verification": {"parse": "ok", "resolve": "ok", "contracts": "ok", "evidence": "pending"}
}
```
假设用户把政策金卡折扣由 0.90 改为 0.88,正确行为应该是:
1. `书店政策.金卡折扣` 的实现摘要变化;
2. `书店政策.获取折扣` 与 `定价.计算应付金额` 的传递依赖指纹变化;
3. 所有引用这些知识的文档都能由 `impact` 找到;
4. 如果使用 lock,校验报告“知识目标变更”,而不是静默引用新版;
5. 修改政策的原始来源还需要单独复核,不把源码更新等同于证据更新;
6. Agent 必须先检查适用性和验证状态,不能拿一个未复核的版本装作确定事实。
## 10. AI 原生复用:有无语义制品的差别
**传统文档 + RAG**:
```text
用户问“金卡买两件 60 元的商品多少钱?”
→ 检索到价格政策.md
→ LLM 阅读、复述并临时写计算步骤
→ 得到 108(本次碰巧正确)
→ 下次又重新解释规则,可能遗漏免运费条件
```
**Marqdo 目标路径**:
```text
用户请求
→ EKC.find("计算应付金额") // 发现候选,不等于信任
→ artifact.inspect(定价.计算应付金额) // 得到签名、适用范围、来源
→ link.resolve(...) // 确定性绑定具体符号
→ verify(contract, input) // 单价60、数量2、等级金卡
→ execute(bound_symbol, input) // 执行编译制品,得到108
→ trace(symbol+digest+input+result) // 可审计记录
→ AI 用自然语言解释结果
```
AI 不必记住“满百免运费”的公式,也不用每次生成新的结算代码。它需要做的是找准能力、验证条件并引用它。
## 11. 演示必须通过的负例
| 变更/攻击输入 | 期待结果 |
|---|---|
| 将 `书店政策.金卡折扣` 改名但未迁移引用 | `link.unresolved` |
| 新增第二个同名 `书店政策` | `link.ambiguous` |
| 对 `定价.计算应付金额` 漏传数量 | `link.arg_mismatch` |
| 数量传入 0 | `knowledge.constraint_unmet` |
| 来源 `pricing-policy.md` 删除 | `knowledge.source_missing` |
| 来源内容变化但知识函数不变 | `knowledge.source_changed` |
| 来源规则仍然正确但业务已过期 | 需要过期/适用期检查,不能自动声称 verified |
| 尝试在正文链接里执行网络支付 | `link.effect_forbidden` 或只解析不执行 |
| 标签写“免费”但表达式仍产生费用 | 结构检查可能通过;标签语义审查需报警或人工审核,不得保证静态证明 |
| 类实例方法经 `类.方法` 直接调用 | `link.instance_only` |
## 12. 为什么这个范式更强
1. **人类维护规则**:读的是 Markdown 业务故事、表格与政策,不是必须遍历全仓源码。
2. **编译器复用行为**:跨文档引用已绑定语义制品,避免重复造轮子。
3. **错误能被提前拦截**:同名、失效、类型、契约、来源变化有各自诊断。
4. **审计能回答“依据是什么”**:结果、符号、版本、输入和来源可追踪。
5. **AI 只负责不确定环节**:意图匹配、适用性判断、结果解释;确定性的计算留给编译制品。
6. **上下文可以缩短,但不是无条件保证**:目标是让 Agent 读取能力摘要而非每次粘贴全部实现;是否节省 tokens 需要客观实验。
**核心竞争力不是 Markdown 链接本身,而是“自然语言描述 → 精确符号绑定 → 可验证语义制品 → 执行与复用”的完整链条。**
## 13. 语法覆盖与非目标
本示例涵盖语法主干,但“全部语法”还包括外联代码围栏、公式 `$$`、浏览器/WASM、原生插件 ABI、量子与线性代数扩展、MCP/Agent、网络和文件 API 等。它们的具体运行依赖扩展与环境,不能当作知识引用所必需的语言核心;统一 IR 应允许这些能力以受效应约束的 Artifact 注册和复用,而不必将每种扩展硬塞入同一个教学案例。
建议另建生态回归套件:
- foreign/LLM/network 函数注册为 EffectSet 的非纯函数;
- 数学公式与表格按返回类型编译为 Artifact;
- 浏览器和 Web 插件导出的能力经符号索引显式引用;
- Agent 的复用接口通过 MLSP 获得固定签名与效果说明。
## 14. 原仓库参考资料
- <https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/objects.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md>
- <https://github.com/cflmy/marqdo/blob/main/examples/link-syntax/main.compat.mq.md>