- 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。
18 KiB
Executable File
Marqdo 可执行知识体系:统一语义制品与知识引用设计规范
状态:设计提案(非当前版本的已实现功能)
基线:仓库 main,2026-10-23;README 标记 v2.0.0;跨文档类调用与 LinkInfo 为 v2.1 目标
宗旨:代码即文档,文档即知识库,知识即可执行。
核心判据:当 AI 遇到任务时,能否先发现已有知识,并以确定性绑定复用,而不是再生成一份“看起来相同”的知识或实现?
1. 决策摘要
保持 [描述](表达式或知识目标) 的 Markdown 形态,不引入新的前缀或第二套表达式文法。[] 是面向读者的陈述,() 内的内容进入统一表达式解析器。语言内部建立稳定的 Semantic Artifact(语义制品) 和 Verified Knowledge Reference(可验证知识引用) 两种核心抽象。前者承载身份、语义、实现、依赖、契约与来源;后者是一个经编译期解析、受上下文约束的引用。它们不必对应新语法标记,而是 .mq.md 经语义分析得到的统一中间表示。
三项不变式:
- 表达式透明性:在求值上下文中
[L](E)与E取得同一类型和值;L不进入符号绑定或改变结果。引用额外产生诊断与溯源元数据。 - 文本安全性:叙述中的知识链接在
check/view中解析;run不因正文出现链接而隐式执行有副作用的函数。导航链接(HTTP、相对文档路径)仍属于普通 Markdown 链接。 - 知识可信边界:
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 一个节点。
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
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 最小语义规则
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 唯一性与优先级
- 当前词法作用域的变量/接收者;
- 当前文档的声明;
- 显式
import命名空间; - 项目导出索引(受
--fs-root和导出策略约束); - 内置/已安装扩展。
如果两个候选都满足同一级优先规则,报 link.ambiguous;不能随文件顺序自动挑一个。解析失败必须有诊断,不能把知识目标悄悄解释成字面字符串或导航路径。
4.4 类函数 vs 实例方法
- 目标函数使用
self/自→ 实例方法,必须有显式接收者。 - 函数不使用接收者 → 可由
类.函数调用;不运行类的构造体。 - 路径解析到零参函数时可以省略
(),但函数作为一等值的语义必须避免与隐式调用冲突。建议只有被[]()用作知识目标、或显式值需求时才触发零参隐式调用;直接类.函数在函数值场景需明确消歧。最终以一致的形式化语义测试冻结。
4.5 版本策略与效应
interface_digest 代表签名兼容性,implementation_digest 代表实现变化,dependency_closure_digest 代表传递依赖;evidence_digest 代表证据状态。既存调用在接口未变时不必全部报错,但“严格复现”任务应使用 lock 来禁止目标悄然变化。
纯知识事实允许受控求值与缓存;依赖网络、时间、随机数、外部模型的调用即使锁了源码也不天然确定。必须记录输入快照、环境与效应,并明确“不保证结果复现”的状态。
5. 静态分析、来源与可信性
5.1 五层验证(必须分层报告)
- Parse:Markdown 结构/语法可解析。
- Resolve:目标存在,歧义可消除。
- Type/Contract:签名、入参与结构类型、单位、前置条件匹配。
- Execution/Test:纯函数或受控沙箱完成运行与测试。
- 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. 编译器实施架构
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 辅助迁移:
[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 必须按以下状态机处理:
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. 设计原则冻结
- 源码可读,编译结果确定。
- 知识是制品,不是文本片段。
- 检索可以模糊,绑定必须确定。
- 知识能够执行,但执行不等于真实。
- 知识可以复用,但必须满足契约与适用条件。
- 显示文字可自由,语义判断不依赖显示文字。
- 默认保持叙述安全,副作用需要明确执行上下文。
- 保持一种语法,一个语义解析器,一套符号索引。
- 双后端与 view/EKC 使用同一份语义中间表示。
- 失败必须可观察,不能因为链接看起来优雅而隐去错误。
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。其中对未实现特性逐项标注,所有业务数据均为虚构演示数据。