Files
marqdo/doc/next/Marqdo_Executable_Knowledge_Example.md
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

14 KiB
Executable File
Raw Permalink Blame History

Marqdo 可执行知识范式:多文件完整示例与对照

规范性目标示例:用于描述 v2.1+ 期望语义;并非宣称 v2.0.0 已能运行所有代码。示例内价格、折扣、门槛均为虚构业务数据。
展示:Markdown 叙述、frontmatter 导入、# 类型、## 函数、继承、表格集合、隐式形参、** 代码、* 返回、条件有序列表、循环无序列表、变量反引号、带描述的 []()、对象、契约、来源、知识索引与 Agent 复用。

1. 实际业务场景

一家虚构的“云雀书店”需要将定价规则维护为人类可阅读的运营文档,由网站、客服机器人、后端结算、审计报告复用,而不是让四个 AI 分别根据文字重新写四次逻辑。业务规则:普通会员 100% 计价,银卡会员 95%,金卡会员 90%;订单满 100 元免 8 元运费;仅处理人民币订单,件数为正整数。所有规则均为示例,没有现实效力。

项目结构

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

# 云雀书店价格政策(演示)

生效范围:2026 年演示订单,人民币;不代表任何真实商店。

## 会员折扣

普通会员不优惠;银卡会员九五折;金卡会员九折。

## 运费

商品合计满 100 元免运费,否则运费为 8 元。

## 约束

商品单价不得为负;数量必须为正整数。会员等级仅允许普通、银卡、金卡。

这是原始证据,并非运行时调用目标。它可被查看、引用和版本化,但不能因为被 AI 读到就自动获得 verified 状态。

3. 政策知识 knowledge/policy.mq.md

使用现有类/函数、返回值与契约表,将业务知识拆成稳定的、可发现的编译单元。

---
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

# 订单

一个订单至少包含数量、单价和会员等级。

## 描述

本方法使用`自`读取对象字段,属于**实例方法**。

*自*

# 线上订单 = > 订单

线上订单是订单类型的一个特化。此处是实际继承语义,不把它误称为“知识实体实例化”。

## 渠道

*"online"*

注意:# 线上订单 = > 订单 在 Marqdo 中的确代表子类型继承;> 线上订单 构造实例,实例方法需要实例接收者。在知识分层中,普通 Fact 不应强制视为类实例。

5. 核心能力 knowledge/pricing.mq.md

这是“知识直接被复用”的核心,而不是把文字重新交给 AI 算一遍。

---
title: 价格计算能力
import policy:knowledge/policy.mq.md
---

# 定价

下列函数实现演示书店的结算规则,适用于人民币演示订单。

## 计算商品小计

输入商品`单价`和`数量`。

| 参数 | 类型 | 约束 |
|---|---|---|
| 单价 | number | 大于等于 0;单位 CNY |
| 数量 | number | 大于 0,且为整数 |

| 返回 | 类型 | 单位 |
|---|---|---|
| 小计 | number | CNY |

**小计 = [商品小计](单价 * 数量)**
*小计*

## 计算运费

根据商品折扣后的金额`金额`决定是否免运费。

1. `金额` >= [免运费门槛](书店政策.免运费门槛)
  *0*
2. *
  *[基础运费](书店政策.基础运费)*

## 计算应付金额

接受`单价`、`数量`、`等级`;输出应付总金额。

**小计 = [商品小计](定价.计算商品小计(单价, 数量))**
**折扣 = [当前会员折扣](书店政策.获取折扣(等级))**
**折后价 = [折扣后商品金额](小计 * 折扣)**
**运费 = [应收运费](定价.计算运费(折后价))**
**应付 = [最终应付人民币金额](折后价 + 运费)**
*应付*

目标能力标记:这一示例使用 类.函数 静态调用、跨文档自动类索引以及嵌入条件表达式中的知识引用,这些是计划实现的语义。当前实际版本中,一般需要显式 import 和实例句柄。其余 **代码**、*返回*、契约表、分支为现有基础。

这里看得最清楚:对读者,整段代码是一个有清晰描述的计算故事;对编译器,括号内是有类型、依赖、来源的调用图;对 AI,复用的不是价格公式的自然语言解释,而是绑定到已有符号的能力。

6. 结算入口 apps/checkout.mq.md

---
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:

---
markup: occlusion
import libai:libai.mq.md
---

# main

**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`

此兼容片段是仓库实例,不能直接替代上面的定价案例:它用于说明当前版本与目标引用模型之间的差距。

7. 文档问答 apps/assistant.mq.md

# main

# 云雀书店结算说明

普通会员原价结算;金卡会员使用[已登记的金卡折扣](书店政策.金卡折扣)。

当前免运费门槛为[已登记的门槛金额](书店政策.免运费门槛)。

关于政策出处,参见[原始价格政策](../corpus/pricing-policy.md)。

这展示知识链接与导航链接共存:前两条必须由编译器解析知识目标,最后一条仍是传统 Markdown 导航。不应把全文正文都作为主动执行入口。UI 可以显示“来源文件/目标类型/验证状态/必要时的值”;若目标未验证,应明确标注。

8. 表格几何与循环 apps/batch.mq.md

演示一列 List、横表 Map、@ 行向记录、无序列表循环和条件分支。根据 v2.0 新语义,旧 [key](collection) 取元改为 at(collection,key)。

---
markup: occlusion
---

# main

`会员等级` =

| 等级 |
|---|
| 普通 |
| 银卡 |
| 金卡 |

`折扣说明` =

| 普通 | 银卡 | 金卡 |
|---|---|---|
| 1 | 0.95 | 0.90 |

`演示订单` =

| @ | 客户 | 等级 | 单价 | 数量 |
|---|---|---|---|---|
| 1 | 甲 | 金卡 | 60 | 2 |
| 2 | 乙 | 银卡 | 30 | 2 |

**银卡比例 = [银卡折扣值](at(折扣说明, "银卡"))**

- [逐个检查会员等级](遍历 会员等级 为 等级)
  1. `等级` == "金卡"
    > 打印 内容="识别到金卡会员"
  2. *
    > 打印 内容=`等级`

表格语义:单列→List;两列以上一数据行→Map;首列 @→按行组成的 List of Map。此处只演示集合构造、访问与循环,避免假定尚未验证的嵌套函数语义。遍历 链接循环是新设计形式,必须通过现有版本的解析器验收后才能标记为已实现。

9. 编译后的产物应当长什么样

下列均是建议输出示意,不是现有 CLI 的真实输出:

{
  "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:

用户问“金卡买两件 60 元的商品多少钱?”
→ 检索到价格政策.md
→ LLM 阅读、复述并临时写计算步骤
→ 得到 108(本次碰巧正确)
→ 下次又重新解释规则,可能遗漏免运费条件

Marqdo 目标路径:

用户请求
→ 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. 原仓库参考资料