# 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. 原仓库参考资料 - - - - - -