Files
marqdo/doc/next/Marqdo_Executable_Knowledge_Example.md
T

401 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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>