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

59 KiB
Executable File
Raw Blame History

Marqdo 可执行知识系统详细开发规范

状态 目标实施规范;按文档原生指导修订交付与政策分级
日期 2026-10-23
适用版本 v2.1 及后续兼容演进
真实意图来源 009.md、Marqdo_Executable_Knowledge_Design.md、Marqdo_Executable_Knowledge_Example.md
核心目标 代码即文档,文档即知识库,知识库可执行,可执行知识可确定性复用。

0. 文档地位与执行规则

本文把上述三份文档中的真实产品意图整理为可编码、可测试、可迁移、可验收的开发规范。2026-10-23 的文档原生开发指导进一步约束作者负担、AI 编辑与复用、场景分级和交付顺序;本文的内部结构不能反向要求作者重复填写注册表、工具 schema 或知识图。仓库中更早的链接、遮蔽、知识分层、类模型、OKF 或 EKC 文档若与上述方向冲突,不得据其改变本轮设计。

优先级从高到低如下:

  1. 009.md 中确认的产品目标与边界;
  2. 文档原生开发指导对作者体验、政策分级和交付排序的修订;
  3. 本文的工程决策、数据结构和验收条件;
  4. 两份附属文档中的概念设计与完整示例;
  5. 其他旧文档,仅可作为历史背景,不是规范依据。

本文不宣称目标能力已经实现。未另行标日期的“当前”表格与 §2 缺口保留最初 v2.0.0 审计背景,不能继续当作 v2.1 的实时状态:默认 Occlusion、线程局部解析作用域、关联函数与零参路径等已经演进。当前实现判断见2026-10-23 缺口审计及对应源码/测试;代码事实证明实现范围,不自动取代产品目标。任何阶段只有在对应的自动化测试、双后端一致性测试和迁移测试全部通过后,才可改标为“已实现”。CLI/API 示意与结构定义仍是目标协议,使用前须核对实现。


1. 产品目标与成功判据

1.1 目标链条

Marqdo 不是“能运行 Markdown 中几段代码”的解释器,也不是“给 RAG 提供更多 Markdown”的资料库。它要建立以下连续链条:

代码即文档
  └─ 程序、说明、契约和示例共址
       ↓ 编译
文档即知识库
  └─ 内容拥有稳定身份、类型、关系、来源和适用条件
       ↓ 确定性绑定
知识库可执行
  └─ 知识不是重新解释的文本,而是可调用的编译制品
       ↓ 发现、校验、执行、追踪
可执行知识可复用
  └─ 人和 Agent 优先复用既有能力,不重复生成同义实现

1.2 产品级成功判据

最终系统必须同时满足以下条件:

  • 人只维护 .mq.md、原始资料和显式配置,不手工同步另一份知识图;
  • 同一份源码能够生成运行程序、语义制品、引用图、可读 view 和 Agent 接口;
  • [描述](载荷) 在可执行位置与裸载荷取得同一值,在叙述位置默认不产生副作用;
  • 跨文档引用最终绑定到稳定 SymbolId,不能只保留名字字符串;
  • 模糊搜索只负责发现候选,真正执行前必须精确解析、校验契约和适用性;
  • 代码、依赖、来源或验证状态变化时,影响范围能够被程序找出;
  • Tree Interpreter 与 Bytecode VM 对同一已绑定程序产生一致结果和诊断;
  • Agent 命中已有且适用的制品时,得到的是可调用句柄,不是让模型复制源码再写一遍;
  • 系统从不把 compiled、tested 或 source_present 误报成“现实世界事实已证明正确”;
  • 作者能从正文计算开始,按需要提取命名能力与跨文档复用,不先建立知识治理工程;
  • 人和 AI 能按标题/步骤获得最小上下文、局部修改并查看语义影响,不必整篇重生成;
  • 每个交付切片同时证明阅读、修改或复用的实际收益,而不只证明内部字段存在。

1.3 不在本轮目标内

  • 不设计第二套链接专用表达式语言;
  • 不增加 knowledge:、call:、ref: 等作者必须记忆的前缀;
  • 不把全部知识强制建模为类或函数;
  • 不在第一阶段实现通用 OWL/RDF 本体推理;
  • 不承诺网络、时间、随机数、LLM 或外部进程可由源码哈希完全重放;
  • 不用 LLM 替代确定性的解析、绑定、类型检查和权限检查;
  • 不把自然语言标签当作授权、契约或事实正确性的依据;
  • 不让 EKC、view、check、Agent 各自再次解析源码并形成不同理解。

1.4 作者成本与渐进严格

标题、叙述、表格、链接描述和执行语句是作者的主要工作面;符号 ID、步骤 ID、规范签名、效应闭包、工具 schema、图和摘要由工具生成。不能推导的领域条件、来源和许可由作者明确补充,不要求每个纯工具函数都填写事实证据。

本地探索允许无锁运行草稿,但不绕过宿主能力限制;项目自动复用按所选 policy 校验;严格业务再增加必要证据、版本锁和新鲜度;远程/多租户另有可信授权与隔离门槛。这是同一语法上的政策分级,不是新的语法模式。纯预览可复用已授予的项目/会话政策,不做逐链接重复确认。详情见指导 §6。

自然语言标签是发现、解释和局部编辑的重要信息,但不证明 payload 正确。AI 可以选候选、组合、适配、重构及补测试;编译器确定实际绑定、类型和效应,宿主决定能力上限。不得把“不用模型决定语义”误读成“模型只能搜索”。


2. 初始实现基线与缺口背景(非 v2.1 实时清单)

2.1 可以复用的现有基础

位置 当前能力 本轮处理
src/ast.rs Module、Function、Stmt、Expr::Occluded、Span 保留 Syntax AST;补正文结构、节点身份和语义映射,不直接塞入全部分析结果
src/parse/expr.rs Classic/Occlusion 两种 []() 解释;payload 复用表达式解析 迁移后冻结为统一链接语义,移除运行时全局模式依赖
src/load.rs 递归 import、模块绑定、循环导入检测 拆分“源码装载”和“项目编译”;显式 import 仍是可执行代码的规范依赖
src/contract.rs、src/check.rs 渐进式契约、类型名、漂移和错位检查 接入统一 Sema;扩展为引用、effect、provenance、lock 诊断
src/interp.rs Tree 执行、实例方法、运行时契约 改为执行已解析引用;不在运行时重复猜目标
src/bytecode/ Bytecode 编译与 VM、函数/实例方法调用 消费相同的 Bound IR,新增静态目标调用,不自行解析名字
src/knowledge/ EKC、L0–L4、检索、reuse、impact、preflight 保留用户接口;内部改成 Semantic Artifact/Graph 的投影与查询层
src/mlsp.rs locate、validate、schema 等 JSONL 接口 增加 artifact/link/verify/impact/bind 只读接口
src/view/ AST 文档、执行捕获、注解 显示同一份 LinkInfo、验证状态、来源与依赖,不自行推断目标
src/artifact/ Web/Endpoint/Prompt 元数据分类 避免命名冲突;迁为 artifact::web 或更名,不能冒充统一语义制品

2.2 必须修复的结构性缺口

  1. Expr::Occluded 只有标签与 payload,没有上下文、解析目标、制品身份和引用策略。
  2. 正文目前不会完整进入能做知识引用分析的结构化 AST。
  3. Classic/Occlusion 用进程全局状态和 frontmatter 切换,同一形状可能静默表示索引或遮蔽。
  4. CallExpr.path 在 Tree 和 Bytecode 中分别解释,绑定不是独立编译阶段。
  5. 当前路径调用把对象下函数统一拒绝为实例方法,未根据 self/自 使用情况区分类函数和实例方法。
  6. EKC 的符号、调用和图边主要由名字/文本提取形成,不能保证与实际执行目标一致。
  7. 当前 fingerprint 更偏向相似性检索,不是接口、实现、传递依赖和证据的规范内容摘要。
  8. check 主要做契约检查,没有项目级 Resolve、LinkInfo、effect、来源和 lock 校验。
  9. Agent 的 REUSE/ADAPT/CREATE 可以发现相似条目,但没有“已绑定且可调用”的强制交接点。

2.3 两个必须避免的概念冲突

Artifact 命名冲突:当前 src/artifact/mod.rs 的 ArtifactKind 只是 Web/Endpoint/Prompt 分类。统一语义制品应命名为 SemanticArtifact,放入新的 src/sema/;现有模块迁到 src/artifact/web.rs 或改名为 document_artifact。

Knowledge IR 重复真相源:当前 src/knowledge/ir.rs 是 EKC 输出模型。它不得升级成第二套编译 AST。编译器先生成 SemanticProject,EKC 再无损投影成兼容的 catalog/graph/context pack。


3. 冻结的语言语义

3.1 []() 的唯一表面形式

[人类可读描述](机器可解析载荷)

[] 中的 label 是人话接口;() 中的 payload 使用所在上下文已有的 Marqdo 语法。二者共同形成一个命名步骤,但只有 payload 决定值、类型、依赖和副作用。

在可执行表达式上下文中:

value([L](E)) = value(E)
type([L](E))  = type(E)
effect([L](E)) = effect(E)

label 不参与变量绑定,不改变控制流,不赋予权限,也不证明 payload 正确。编译器额外生成 KnowledgeRef/KnowledgeStep,因此透明不等于丢弃元数据。

3.2 上下文决定“是否执行”,目标种类决定“如何校验”

上下文 编译行为 运行行为
**...**、*...*、调用实参、表格表达式 解析、绑定、校验并生成 BoundExpr 正常求值
循环载荷 解析成既有 LoopSpec,生成命名步骤 按原循环语义执行
普通正文 解析导航或知识引用,生成 NarrativeRef run 不执行;view 仅可按策略预览 pure 目标
标题、frontmatter、代码围栏、行内代码 不识别为可执行链接 保持原文本/原结构
HTTP(S)、锚点、相对 .md 路径 NavigationRef 不执行

禁止通过“目标是函数”推导它在正文中可以执行。执行许可由上下文和 effect policy 共同决定。

3.3 一个语法,四种语义投影

示例 StepKind 核心依赖
[订单行金额](at(行, "金额")) Observe 变量、字段
[折后价](小计 * 折扣) Derive 输入表达式
[计算应付](定价.计算应付金额(...)) Invoke 目标 SymbolId、实参
[逐行处理](遍历 订单.行 为 行) Iterate 集合、迭代变量
正文 [免邮门槛](书店政策.免运费门槛) Narrate 知识目标

StepKind 由已解析的 payload 和位置推导,不由 label 中的自然语言猜测。

3.4 类函数与实例方法

现有 #/## 表面语法保持不变,语义分析阶段明确区分:

  • ## 函数体直接使用 self/自,或调用同一类型中依赖接收者的方法:InstanceMethod,必须有实例接收者;
  • 不使用接收者:AssociatedFunction,可由 类.函数(...) 调用,且不执行 # 类 的构造体;
  • # 仍可承载类型/命名空间的兼容写法,但这不表示所有知识都是类;
  • Entity、Fact、Policy、Constraint、Dataset 等是 Semantic Artifact kind,不强制增加源码关键字;
  • 顶层自由函数和导入模块函数继续存在,不必包装成类。

接收者依赖必须在语义分析中递归确定。直接读取 self/自 是确定证据;调用同类型实例方法会传播接收者依赖;仅在叙述里出现“自”不算依赖。

3.5 零参路径

零参函数省略 () 只允许在以下明确的“需要值”位置:

  • []() payload 的最终路径;
  • 赋值、返回、参数、条件或表格单元格中的值表达式;
  • 正文知识引用的目标路径。

当语法位置允许函数值时,裸路径不做隐式调用;若语言当前没有一等函数值,则在引入一等函数前将此行为冻结为“路径解析到零参函数即调用”。带参数函数省略 () 必须报 link.arg_mismatch,不能返回函数对象或 None。

3.6 导航链接与知识引用消歧

识别顺序如下:

  1. 明确 URI scheme(如 https:、mailto:)或 #anchor → Navigation;
  2. 以 ./、../、/ 开头且指向文档/资源的路径 → Navigation;
  3. 其余 payload 尝试使用 Marqdo 语法解析;
  4. 解析成功 → Knowledge/Expression Reference;
  5. 解析失败且符合普通 Markdown 目标 → Navigation;
  6. 两种解释都成立 → 报 link.ambiguous_syntax,要求作者改为明确相对路径或合法表达式。

不能因为解析失败就无声地把预期知识引用降级成普通 URL。


4. 编译管线与模块边界

4.1 目标管线

Source files
   ↓ SourceMap + Markdown-aware scan
SyntaxProject
   ├─ executable AST
   ├─ narrative nodes / links
   └─ contracts / metadata / source spans
   ↓ Declaration collection
ProjectIndex
   ↓ Name resolution
ResolvedProject
   ↓ type + contract + effect + provenance analysis
SemanticProject
   ├─ SemanticArtifact[]
   ├─ KnowledgeRef[] / KnowledgeStep[]
   ├─ DependencyGraph
   ├─ Diagnostic[]
   └─ HashManifest
   ↓ lowering
BoundProgram ──→ Tree Interpreter
             └─→ Bytecode compiler / VM
SemanticProject ──→ check / view / EKC / MLSP / lock / Agent

关键约束:运行器和工具链只能消费语义阶段已经确定的目标,不再用字符串搜索复制一套解析规则。

4.2 建议的源码目录

src/
├─ syntax/                  # 后续从 parse/ast 渐进迁移;第一阶段可保持旧位置
├─ project/
│  ├─ mod.rs                # ProjectRoot、编译入口、缓存
│  ├─ discover.rs           # 文件发现与边界
│  ├─ module_id.rs          # ModuleId 规范化
│  └─ source_map.rs         # FileId、Span、源码摘要
├─ sema/
│  ├─ mod.rs
│  ├─ ir.rs                 # SemanticProject、Artifact、Ref、Step
│  ├─ symbols.rs            # 声明收集、SymbolId、索引
│  ├─ resolve.rs            # 名称解析与歧义诊断
│  ├─ classify.rs           # Type/Entity/Fact/Function/Capability...
│  ├─ types.rs              # CanonicalSignature、结构类型、单位
│  ├─ effects.rs            # EffectSet 推导
│  ├─ provenance.rs         # SourceRef 与证据解析
│  ├─ hashes.rs             # 四类 digest
│  └─ lock.rs               # links.lock 读写校验
├─ lower/
│  ├─ tree.rs               # Semantic IR → tree 可执行形式
│  └─ bytecode.rs           # Semantic IR → bytecode 输入
├─ knowledge/               # SemanticProject 的 EKC 投影/检索/复用
└─ artifact/
   └─ web.rs                # 现有 Web Artifact 分类,避免与 SemanticArtifact 混名

第一阶段不要求大规模搬文件。可以先新增 project/sema,让旧 ast、parse 成为输入;只有测试稳定后再做目录迁移。

4.3 公开编译入口

pub struct CompileOptions {
    pub project_root: PathBuf,
    pub entry: Option<PathBuf>,
    pub profile: BuildProfile,
    pub lock_mode: LockMode,
    pub effect_policy: EffectPolicy,
}

pub struct Compilation {
    pub sources: SourceMap,
    pub syntax: SyntaxProject,
    pub semantics: SemanticProject,
    pub diagnostics: Vec<Diagnostic>,
}

pub fn compile_project(options: &CompileOptions) -> Result<Compilation>;

run、check、view、knowledge compile 和 MLSP 必须最终汇入此入口。针对内存源码的编辑器调用提供 compile_overlay(project, overlays),不能另写简化语义。


5. 统一语义中间表示

5.1 标识类型

禁止在核心 API 中混用裸 String 表示文件、符号、制品和摘要:

pub struct FileId(u32);
pub struct ModuleId(String);
pub struct SymbolId(String);
pub struct ArtifactId(String);
pub struct RefId(String);
pub struct Digest(String);

序列化采用显式字符串格式;内存中保持 newtype,避免把显示名误当稳定身份。

5.2 SemanticArtifact

pub struct SemanticArtifact {
    pub artifact_id: ArtifactId,
    pub symbol_id: SymbolId,
    pub display_name: String,
    pub kind: SemanticArtifactKind,
    pub visibility: Visibility,
    pub source: SourceLocation,
    pub signature: Option<CanonicalSignature>,
    pub implementation: Option<BoundBody>,
    pub contract: ContractSet,
    pub effects: EffectSet,
    pub dependencies: Vec<ArtifactDependency>,
    pub provenance: Vec<SourceRef>,
    pub applicability: Applicability,
    pub hashes: ArtifactHashes,
    pub verification: VerificationRecord,
    pub lifecycle: Lifecycle,
}

pub enum SemanticArtifactKind {
    Module,
    Namespace,
    Type,
    Entity,
    Fact,
    Function,
    Capability,
    Constraint,
    Policy,
    Dataset,
    Document,
    ExternalCapability,
}

SemanticArtifactKind 是语义分类,不要求每一类都有新的 Markdown 标记。分类信息来源依次为:显式 metadata/type、结构位置与可检查契约、保守推导。无法确定时选择更一般的 Function/Document,不得根据函数名猜成 Fact。

5.3 KnowledgeRef 与 KnowledgeStep

pub struct KnowledgeRef {
    pub id: RefId,
    pub label: String,
    pub context: RefContext,
    pub payload: SyntaxNodeId,
    pub resolution: Resolution,
    pub expected: ExpectedContract,
    pub policy: VerificationPolicy,
    pub source: SourceLocation,
}

pub enum Resolution {
    LocalExpression,
    Navigation(NavigationTarget),
    Symbol {
        symbol_id: SymbolId,
        artifact_id: ArtifactId,
        binding: BindingKind,
    },
    Ambiguous(Vec<SymbolId>),
    Unresolved,
}

pub struct KnowledgeStep {
    pub id: ArtifactId,
    pub reference: RefId,
    pub kind: StepKind,
    pub inputs: Vec<DataDependency>,
    pub outputs: Vec<DataOutput>,
    pub calls: Vec<SymbolId>,
    pub effects: EffectSet,
    pub source: SourceLocation,
}

引用是“绑定关系”,步骤是“本次命名计算/叙述”。调用同一函数的两个位置拥有同一目标 SymbolId,但拥有不同 RefId 和 Step Artifact,便于回答“哪个句子受影响”。

5.4 规范签名

pub struct CanonicalSignature {
    pub receiver: ReceiverKind,
    pub params: Vec<CanonicalParam>,
    pub returns: CanonicalType,
    pub effects: EffectSet,
}

pub struct CanonicalParam {
    pub name: String,
    pub ty: CanonicalType,
    pub required: bool,
    pub default_digest: Option<Digest>,
    pub unit: Option<String>,
    pub constraints: Vec<Predicate>,
}

参数顺序、名称、是否必填、类型、单位、默认值和 receiver 都进入接口摘要。说明文字不进入接口摘要,但进入证据/文档摘要。

5.5 EffectSet

第一版固定以下 effect:

pure
fs.read       fs.write
network.read  network.write
process.exec
plugin.call
llm.call
time.read
random.read
user.input
output.write
unknown

规则:

  • 字面量、算术、纯集合操作为 pure;
  • 内置/扩展注册时声明 effect;未声明的外部能力为 unknown;
  • 函数 effect 是本体操作与所有调用依赖 effect 的并集;
  • 递归 SCC 求不动点;
  • pure 不与其他 effect 同时保存,出现其他 effect 即移除 pure;
  • Narrative context 默认只允许 pure 的解析和元数据展示,不自动求值;
  • lock 锁定代码不能消除运行环境 effect。

5.6 来源与验证记录

pub struct SourceRef {
    pub uri: String,
    pub locator: Option<String>,
    pub content_digest: Option<Digest>,
    pub retrieved_at: Option<DateTime>,
    pub relation: SourceRelation,
}

pub struct VerificationRecord {
    pub parse: CheckState,
    pub resolve: CheckState,
    pub contract: CheckState,
    pub execution: CheckState,
    pub tests: CheckState,
    pub evidence: CheckState,
    pub domain: CheckState,
    pub checked_at: Option<DateTime>,
    pub methods: Vec<VerificationMethod>,
}

禁止单个 verified: bool。API 可以派生 reuse_readiness,但必须保留每层状态与方法。


6. 稳定寻址与项目符号索引

6.1 项目边界

项目根解析顺序:

  1. CLI 明确 --project-root/现有 --fs-root;
  2. 从入口文件向上寻找 .marqdo/project.toml;
  3. 从入口文件向上寻找 .git,但只作为默认边界;
  4. 否则使用入口文件所在目录。

索引不得越过项目根,不跟随逃逸根目录的符号链接,不访问网络。target、.git、.marqdo/cache、node_modules 等生成目录默认排除,规则集中定义,不能由 EKC 与编译器各维护一份。

6.2 ModuleId

优先级:

  1. frontmatter 显式 id;
  2. 相对项目根的规范路径,移除 .mq.md;
  3. 内置和扩展使用其注册的 package/module ID。

显式 id 在项目内必须唯一。fallback 路径移动会改变 ModuleId,属于可观察变更;需要保持身份时应先补 id 或生成 alias migration。

6.3 SymbolId

建议序列化格式:

mq://<project-id>/<module-id>#/<kind>/<declaration-path>

示例:

mq://bookshop/knowledge.pricing#/capability/定价/计算应付金额
mq://bookshop/knowledge.policy#/fact/书店政策/金卡折扣

declaration-path 使用源码声明层级,不使用数组序号;各段做 UTF-8 percent encoding。相同父级下同 kind 同名声明为硬错误。显示名称可以相同,只要规范地址不同。

6.4 ArtifactId 与 RefId

  • 声明制品:ArtifactId = SymbolId + artifact schema version;
  • 命名步骤:基于所属 SymbolId、规范 AST 路径和显式 source anchor 形成;
  • 引用:基于 source ModuleId、source span anchor、目标 SymbolId 形成。

行号不能单独作为长期身份,因为插入文字会导致全文件漂移。第一版使用“所属声明 + 规范节点路径 + payload digest”,行列仅用于显示和重定位。

6.5 名称解析顺序

可执行代码:

  1. 局部变量与显式接收者;
  2. 词法父级声明;
  3. 当前模块声明;
  4. 显式 use;
  5. 显式 import 绑定;
  6. 内置和已注册扩展。

正文知识引用可以额外使用项目导出索引做发现,但唯一命中后必须写入具体 SymbolId/lock。代码路径默认不得依赖“扫描全项目后恰好唯一”,否则新增同名文件会改变运行结果。若产品决定允许代码短地址,也必须在首次绑定后要求 lock,且无 lock 构建发出诊断。

6.6 歧义和重命名

  • 同一优先级两个候选 → link.ambiguous;
  • 不允许根据目录遍历顺序、最近修改时间或搜索分数选择;
  • 正式重命名由 symbol-aliases.json 或迁移命令生成旧→新映射;
  • alias 只能用于给出迁移建议,严格模式下不能永久静默转发;
  • alias 链禁止循环,默认最多一跳。

7. Markdown 与解析实现

7.1 两层解析而非正则扫描

第一层用 CommonMark/GFM 解析块与 inline,保留 source offset;第二层仅在 Marqdo 允许的节点和链接 destination 中调用现有表达式解析器。必须正确处理:

  • destination 中的平衡括号;
  • 转义的 \]、\(、\);
  • 中文标识符和 Unicode;
  • 多个同一行链接;
  • 行内代码与 fenced code 中看似链接的文本;
  • 图片 ![alt](src);
  • 普通 URL、锚点与相对文档链接;
  • **、* 与 Markdown emphasis 的冲突;
  • 表格单元格中的链接表达式;
  • 正文链接与可执行表达式链接的不同上下文。

不得用简单正则从全文提取 []()。

7.2 Syntax AST 的最小变化

短期保留 Expr::Occluded 以降低回归风险,但重命名计划如下:

Expr::Named {
    label: String,
    payload: Option<Box<Expr>>,
    syntax_id: SyntaxNodeId,
}

正文增加:

pub enum NarrativeInline {
    Text(String),
    Code(String),
    Link(NarrativeLink),
    Emphasis(Vec<NarrativeInline>),
}

Module 不应保存完整语义结果,只保留解析结构和 SyntaxNodeId。Semantic tables 通过 ID 关联,避免 AST 被工具专用字段污染。

7.3 Classic 迁移

统一语义启用前必须先迁移旧 [键](集合):

[键](集合)       → at(集合, "键")
[`键名`](集合)   → at(集合, 键名)
- [项](集合)     → 旧循环的规范新写法

迁移工具必须:

  1. 在 Classic 模式解析旧文件;
  2. 根据 AST 节点类型改写,不做正则替换;
  3. 输出文件、行、旧 AST、新 AST 和文本 diff;
  4. 默认 dry-run;
  5. --write 前后分别以 Tree/Bytecode 运行可运行样例并对照结果;
  6. 无法证明等价时拒绝自动改写并生成待办;
  7. 完成仓库迁移后删除进程全局 MARKUP_DEFAULT,保留一个版本周期的只读兼容诊断。

不能让未声明模式的同一源码在升级后成功运行但产生不同值。


8. 绑定、类型、契约与适用性

8.1 绑定先于执行

每个 Call/Path/KnowledgeRef 在 lowering 前必须变成以下之一:

pub enum BoundTarget {
    Local(SymbolId),
    AssociatedFunction(SymbolId),
    InstanceMethod { method: SymbolId, receiver: BoundExprId },
    Imported(SymbolId),
    Builtin(BuiltinId),
    Extension(ExternalSymbolId),
}

Tree 和 Bytecode 都执行 BoundTarget,不再调用各自的 lookup_function/resolve_call 猜测相同名字。运行时只允许动态语言特性明确要求的 lookup,例如 call_fn(text);这类动态调用必须带 dynamic.invoke effect/图边并降低静态可验证程度。

8.2 渐进式类型

保持 Marqdo 动态运行值,但在语义层建立渐进式类型:

  • 有契约:以契约为主,并与推断参数双向互查;
  • 无契约:从字面量、表达式、返回点和调用目标推断;
  • 无法确定:Any/Unknown,不伪造精确类型;
  • number:CNY 与 number:ratio 的运行存储可以相同,静态契约不可随意互换;
  • Map/List/记录结构使用规范 schema;
  • 参数、返回、字段、单位与枚举约束分别报告,不合并成笼统“类型错误”。

8.3 适用性

Applicability 至少支持:

input predicates
unit / currency
region
valid_from / valid_until
audience / tenant
environment
required capabilities

第一版仅实现可以确定性验证的表格契约和 metadata;未支持的自由文本条件保存为 declared_unchecked,Agent 使用前必须看到该状态。不能因解析不了而丢弃条件。

8.4 失败关闭边界

以下情况禁止直接执行/复用:

  • 目标未解析或歧义;
  • 调用实例方法但没有接收者;
  • 参数、返回类型或硬约束不匹配;
  • 当前上下文禁止目标 effect;
  • strict lock 下 digest 不匹配;
  • 策略要求 evidence/domain verified 而状态不满足;
  • 目标 deprecated/superseded 且策略禁止旧版本。

knowledge.unverified 在普通浏览可为 warning,但在调用方明确要求 verified 时升级为 error。


9. 指纹、锁定与增量构建

9.1 四类摘要

pub struct ArtifactHashes {
    pub interface: Digest,
    pub implementation: Digest,
    pub dependency_closure: Digest,
    pub evidence: Digest,
}
  • interface:kind、receiver、规范签名、公开契约、effect 声明;
  • implementation:去除无语义格式差异后的 Bound IR;
  • dependency_closure:implementation 加所有静态依赖的 interface/implementation/closure,按 SymbolId 排序;
  • evidence:规范化来源定位、内容摘要、验证方法和验证结果。

哈希输入必须带 schema version 和域分隔符,例如 marqdo:artifact-interface:v1\0...,防止不同对象的相同 JSON 偶然共用语义。

9.2 依赖环

先对调用图求 SCC:

  • SCC 内节点先基于各自 implementation 生成 member digest;
  • SCC digest 由排序后的成员 SymbolId/member digest 和外部依赖 closure 生成;
  • 成员 closure 使用 SCC digest;
  • 这样递归不会无限计算,也不依赖遍历顺序。

9.3 links.lock

默认路径 .marqdo/links.lock.json,规范结构:

{
  "schema": 1,
  "project": "bookshop",
  "compiler": "marqdo/2.1.0",
  "links": [
    {
      "ref_id": "...",
      "from": "document.invoice-answer",
      "target_symbol_id": "mq://bookshop/knowledge.policy#/fact/书店政策/金卡折扣",
      "interface_digest": "sha256:...",
      "implementation_digest": "sha256:...",
      "dependency_closure_digest": "sha256:...",
      "evidence_digest": "sha256:...",
      "policy": "compatible"
    }
  ]
}

LockMode:

  • off:只解析,不读写 lock;
  • check:有条目则校验,无条目提示;
  • strict:公共/跨文档引用必须存在且完全符合策略;
  • update:显式更新,生成变更摘要,绝不由普通 run 偷偷改写。

9.4 缓存

.marqdo/cache/sema/ 只保存可再生内容。缓存 key 至少包含:源码 digest、编译器版本、IR schema、项目配置、目标平台、扩展 registry digest。缓存损坏应回退重编译,不影响正确性。

文件扫描、索引和序列化必须排序;相同输入在不同机器、线程数和目录枚举顺序下产生相同摘要与 JSON。


10. 验证模型与诊断

10.1 七层状态

层 问题 可自动化程度
Parse 源码结构是否有效 确定性
Resolve 名字是否唯一绑定 确定性
Type 类型、参数、单位是否匹配 大部分确定性
Contract 前置条件/结构约束是否满足 声明范围内确定性
Execute/Test 受控执行和测试是否通过 取决于 effect/环境
Evidence 来源是否存在、内容是否变化、声明是否对应 部分确定性
Domain 现实业务/专业语境中是否正确、仍适用 人工或受标注的模型辅助

CLI 输出必须逐层展示。check OK 只能表示本次启用的检查没有 error。

10.2 诊断码

Code 默认等级 触发条件
link.unresolved error 无可绑定目标
link.ambiguous error 同优先级多目标
link.ambiguous_syntax error 导航和表达式解释冲突
link.kind_mismatch error 目标 kind 不可用于当前位置
link.instance_only error 用类路径调用实例方法
link.arg_mismatch error 参数数量/名称不匹配
link.type_mismatch error 静态类型或单位不匹配
link.no_value warning/error 值上下文目标无返回
link.effect_forbidden error 当前上下文/能力策略不允许 effect
link.target_changed warning/error lock 目标或摘要改变
link.dynamic_unverified warning 动态调用无法静态绑定
knowledge.source_missing warning/error 声明来源不存在
knowledge.source_changed warning 来源摘要变化未复核
knowledge.constraint_unmet error 硬适用条件不满足
knowledge.not_yet_valid error 尚未生效
knowledge.expired warning/error 超出有效期
knowledge.unverified info/warning/error 未达到调用方所需验证策略
knowledge.deprecated warning/error 复用过时制品
label.ref_dangling error label 中结构化反引号引用无目标
label.possibly_stale hint 实现变化但 label 未复核

每条诊断必须包含 code、severity、source span、相关声明 span、候选目标(若有)、建议和所依据的 policy。JSON 结构向后兼容现有 Diagnostic::to_json(),新增字段不得把旧字段改义。

10.3 标签语义边界

label 与 payload 的自然语言一致性无法由类型系统完全证明。确定性检查仅覆盖:

  • label 内反引号引用存在;
  • payload 或目标变更后的 stale 提示;
  • 明显单位/返回类型冲突;
  • 显式词表规则。

LLM 语义复核是可选 provider,结果必须标为 heuristic,不能阻止离线编译,也不能覆盖确定性诊断。


11. 执行后端改造

11.1 Tree Interpreter

改造目标:

  • eval_call 接受 BoundCall,不再按字符串顺序尝试 local/path/builtin/plugin;
  • AssociatedFunction 直接用目标函数及所属模块执行,不运行对象构造体;
  • InstanceMethod 保留 _type/继承链行为,但 method 已在语义层确定;
  • Expr::Named 只透传 payload 值,同时向 trace 记录 RefId、ArtifactId、target digest;
  • Host/Plugin 调用从 registry 获取签名和 effect;
  • 运行时契约继续作为动态防线,不能因静态检查存在而删除。

11.2 Bytecode

新增或调整操作码:

CallBound(symbol_index, argc)
CallMethodBound(symbol_index, argc)
TraceRefEnter(ref_index)
TraceRefExit(ref_index)

Program 增加 symbol/ref tables,disassemble 显示 SymbolId 和来源。旧 Call(fid, argc) 可以作为内部 lowering 结果保留,但编译阶段必须来自 BoundTarget,而不是 resolve_call(name)。

11.3 双后端一致性

每个 gold case 同时运行 Tree 和 Bytecode,比较:

  • 返回值;
  • stdout;
  • 结构化错误 code 和 source span;
  • 实际调用的 SymbolId 序列;
  • KnowledgeRef trace;
  • effect 拒绝结果。

仅文本错误措辞可允许微小差异;机器字段不得不同。

11.4 叙述预览

view 若显示正文 pure 引用的值,应通过单独的 PreviewExecutor:

  • 默认仅允许 pure;
  • 有输入的函数不自动调用;
  • 有未知 effect 不调用;
  • 限制步数、递归深度、输出大小和总时间;
  • 超限只显示“可解析但未预览”,不影响页面其余部分;
  • 预览结果标识输入、digest 和时间,不写回源码。

12. EKC、知识图与 Agent 复用

12.1 EKC 角色调整

EKC 从“再次阅读源码并猜测工程知识”调整为:

SemanticProject
   ├─ project_symbols()  → L0/L1/L2
   ├─ capabilities()     → L3
   ├─ authored_knowledge → L4
   ├─ graph_edges()      → graph
   └─ search_documents() → lexical/vector optional index

短期兼容 KnowledgeGraph、现有 CLI 和 .marqdo/catalog/** 输出;内部字段逐步由 SemanticArtifact 填充。旧文本提取只为非 .mq.md authored knowledge 保留,不能覆盖编译器确定的符号和调用边。

12.2 图节点与边

节点:Project、Module、SemanticArtifact、KnowledgeStep、Evidence、Test、Execution、AgentEpisode。

核心边:

contains
declares
references
calls
reads
derives
iterates
produces
depends_on
constrained_by
supported_by
tested_by
verified_by
supersedes
conflicts_with
executed_in
reused_in

calls/references/depends_on 必须来自 Bound IR;搜索命中不得直接生成事实图边。

12.3 Agent 状态机

TASK
  → DISCOVER          模糊查找候选
  → RESOLVE           精确绑定 SymbolId
  → INSPECT           获取签名/effect/适用性/来源/状态
  → CONTRACT_CHECK
      ├─ ready        → BIND → EXECUTE → TRACE
      ├─ adaptable    → ADAPT → VERIFY → PROMOTE
      ├─ unusable     → 继续发现或 CREATE
      └─ ambiguous    → 请求消歧/失败关闭
  → CREATE            仅在 reuse budget 和 policy 允许时
  → VERIFY → PROMOTE

REUSE 的判据不是“搜索分数超过阈值”,而是候选已经精确绑定、输入满足契约、effect 获得许可、版本策略通过。搜索分数只用于候选排序。

ready 是对所选 policy、输入与上下文的判断,不是所有知识必须先获得的全局认证。AI 可以从候选中选择明确目标;歧义不能交给执行器按扫描顺序消解。ADAPT/CREATE 必须遵守任务写权限和预算,缺少业务决策时请求补充,而非擅自改变适用条件。草稿可被发现并在明确权限下探索执行,但不得冒充已通过严格政策的事实。

发现结果应按需包含标题/步骤、源码片段、输入角色、契约、效应、来源、验证缺口和相关失败经验。局部编辑须携带期望源码摘要,应用后检查语义 diff 与相关测试;不以重写整份文档作为默认修复方式。协议及受限试点范围见指导 §5。

12.4 BoundArtifactHandle

pub struct BoundArtifactHandle {
    pub symbol_id: SymbolId,
    pub artifact_id: ArtifactId,
    pub interface_digest: Digest,
    pub dependency_closure_digest: Digest,
    pub accepted_effects: EffectSet,
    pub verification_policy: VerificationPolicy,
    pub expires_at: Option<DateTime>,
}

Agent 执行必须携带 handle 和显式输入;runtime 再次核对摘要和权限,防止发现后到执行前目标变化。handle 是能力引用,不包含可由模型修改后悄悄执行的源码副本。

上述结构表达绑定内容,不独自构成远程授权凭据。受信本地调用可先采用精确引用和摘要复核;不受信/远程调用必须另有服务端认可的主体、能力范围、防伪及撤销/期限机制,客户端自报 accepted_effects 不能扩大宿主许可。handle 由工具产生,不要求作者维护;是否检查 lock 和来源新鲜度取决于明确的 policy。

12.5 Promote 门槛

Agent 新建或适配的知识进入共享自动复用的 ready 集合前,按目标 policy 至少完成:

  • Parse/Resolve/Type/Contract 通过;
  • effect 已由静态绑定与宿主/扩展元数据推导;不能推导时保留 unknown 并按政策拒绝或要求明确能力许可,不要求业务作者抄写闭包;
  • pure 逻辑有测试,外部 effect 有 mock/沙箱证明或人工批准;
  • 来源型知识附 SourceRef;
  • 生命周期从 draft 开始;
  • 生成者、输入、工具版本、变更 diff 可审计;
  • 未达到门槛的内容保持 draft/quarantine 状态;可在同一权威索引中过滤展示,不另造语义身份。

这是晋升政策,不是普通 .mq.md 文件被索引、查看或本地执行的前置注册流程。简单纯计算不强制现实来源;声称业务事实成立的知识不能用测试通过替代所需证据。


13. CLI、MLSP 与文件产物

13.1 CLI 演进

保留现有命令,增加能力而不是平行造新命令族:

marqdo check PATH --project-root ROOT --lock check --json
marqdo run FILE --lock strict --trace-knowledge trace.json
marqdo knowledge compile PATH
marqdo knowledge inspect SYMBOL
marqdo knowledge resolve EXPR --from FILE
marqdo knowledge verify SYMBOL --policy POLICY
marqdo knowledge impact SYMBOL_OR_PATH
marqdo knowledge lock [--check|--update]
marqdo migrate labels PATH [--write]

退出码:

  • 0:成功且无 error;
  • 1:程序/验证失败;
  • 2:CLI 使用错误;
  • 3:strict lock 不一致;
  • 4:effect/权限拒绝;
  • 5:项目索引或缓存损坏且无法重建。

13.2 MLSP 方法

新增:

Method 输入 输出
artifact.find query、kind、limit、project 候选摘要;仅 discovery
artifact.inspect SymbolId/ArtifactId 签名、契约、effect、来源、hash、状态
link.resolve source file、payload/span Resolution、候选、诊断
artifact.verify SymbolId、policy、可选输入 分层 VerificationRecord
artifact.impact SymbolId/digest/path 反向依赖与受影响步骤
artifact.bind SymbolId、expected digest、policy BoundArtifactHandle;不直接执行
artifact.execute handle、inputs、capabilities result、trace、更新后的状态

所有方法复用 compile_project,支持 overlay,不得自己调用 EKC 字符串搜索来完成 resolve。

13.3 生成目录

.marqdo/
├─ project.json
├─ symbols.json
├─ artifacts/
│  └─ <artifact-id>.json
├─ refs.json
├─ graph/
│  ├─ nodes.json
│  └─ edges.json
├─ links.lock.json
├─ verification/
│  └─ <artifact-id>.json
├─ traces/
│  └─ <execution-id>.json
├─ catalog/                 # 兼容现有 EKC
├─ knowledge/               # 兼容现有 EKC
└─ cache/                   # 可删除、可重建

所有生成文件写入前先在临时文件完整生成和校验,再原子替换;编译失败不得留下“半新半旧”的项目图。

13.4 JSON schema 与版本

每类生成物必须有 schema_version,schema 文件纳入仓库。新增可选字段为兼容变化;删除、改义或类型变化必须提升 major schema。测试用 JSON 不比较键顺序,但生产输出按固定顺序生成以便 review。


14. View 与可解释性

14.1 每个引用的最小展示

View 至少展示:

  • label 和 payload;
  • 目标显示名、SymbolId、kind;
  • 签名、单位、effect;
  • 解析/契约/测试/证据状态;
  • 当前值或“未执行”的原因;
  • 来源与目标源码跳转;
  • interface/implementation 是否与 lock 一致;
  • 上游依赖和下游影响入口。

14.2 状态措辞

允许:

  • “已解析到……”
  • “契约检查通过”
  • “测试于某版本通过”
  • “来源存在但尚未完成领域复核”

禁止:

  • 仅因函数能运行显示“知识正确”;
  • 仅因 URL 可访问显示“来源已验证”;
  • 仅因搜索命中显示“已复用”;
  • 隐藏 effect 或 lock 变化。

14.3 可达性和静态导出

状态不能只靠颜色表达;HTML 使用文本、图标和可访问标签。view output --no-exec 仍展示解析与验证元数据,只隐藏运行值。静态导出不得为了显示知识值而放宽运行权限。


15. 安全、权限与可信边界

15.1 能力安全

沿用现有 HostCaps,并扩展到细粒度 EffectPolicy。编译期 effect 是预检查,运行时 capability 是最终授权。两者缺一不可。

正文链接、view 预览、check 和 knowledge compile 必须是只读路径,不得因为分析引用而触发:

  • 文件写入;
  • 网络写操作;
  • 外部进程;
  • 插件动态加载;
  • LLM 请求;
  • 用户输入等待。

15.2 路径与来源

  • 项目文件和相对 SourceRef 规范化后必须仍在允许根内;
  • symlink 逃逸按真实路径检查;
  • 来源摘要读取大小有上限;
  • 远程来源默认不在编译时抓取,只使用已有快照/显式 verify;
  • URL 凭据、token 和查询机密不得进入 graph、lock 或 trace;
  • trace 对参数和值执行现有 secrets/redaction 策略。

15.3 TOCTOU

解析、绑定与执行之间,用 source/hash 校验防止目标变化。严格执行时发现 handle digest 与磁盘当前制品不一致,应拒绝并要求重新绑定。


16. 迁移与兼容策略

16.1 版本阶段

阶段 默认行为 兼容行为
2.0.x Classic 默认,Occlusion opt-in 历史行为
2.1 preview 新语义默认;全仓语料具有文件级 markup: occlusion --legacy-markup / 显式 markup: classic 只读过渡
2.1 stable 新语义默认;旧形状必须已迁移 --legacy-markup 只读运行一个周期
2.2 删除全局模式与旧 parser 分支 仅保留明确错误和迁移建议

具体版本可随发布计划调整,但顺序不能颠倒。

16.2 不破坏的能力

  • 现有显式 import;
  • 实例构造与实例方法;
  • 当前契约表;
  • Tree/Bytecode CLI 入口;
  • EKC 的 find/reuse/impact 用户命令;
  • Web/Endpoint Artifact metadata;
  • 无 []() 文件的既有执行结果。

16.3 必须显式变化的能力

  • [键](集合) 迁为 access(集合, "键");
  • 链接不再依赖进程级 markup 模式;
  • 类.函数 对无 receiver 函数成为合法 AssociatedFunction 调用;
  • 正文知识链接被解析和诊断,但不自动执行;
  • EKC 的 calls/edges 由 Bound IR 取代名字猜测;
  • lock 更新从普通编译中分离。

16.4 迁移报告

{
  "file": "...",
  "before_mode": "classic",
  "changes": [
    {
      "span": {"line": 10, "col": 4},
      "kind": "index_to_at",
      "before": "[银卡](折扣表)",
      "after": "at(折扣表, \"银卡\")",
      "semantic_check": "equivalent"
    }
  ],
  "manual_review": [],
  "tree_equivalent": true,
  "bytecode_equivalent": true
}

17. 分阶段开发计划

M0–M6 保留为工程能力与验收项目,不再作为顺序排期;部分迁移能力已经完成,状态见现状审计。实际工作按文档原生 S0–S6形成可独立合并的垂直切片:早期联动 M1/M2/M3/M5 的安全子集,交付可读步骤和真实复用,不能等 M4 全部做完才让作者或 Agent 使用。100 单元生成器逐步增长,不阻塞最小故事;不得先大规模重构再等待最后一次性验收。

M0:语义冻结与测试生成器

交付:

  • 本文进入仓库并被文档索引引用;
  • tests/executable_knowledge/ gold case 结构;
  • 100 单元项目生成器,固定随机种子;
  • 解析上下文、导航链接、旧索引、正文安全的测试矩阵;
  • 当前行为快照和预期变化清单。

完成条件:

  • 测试可以明确区分“当前失败(expected fail)”与回归;
  • 所有新诊断 code、JSON 最小字段和退出码冻结;
  • 不依赖 LLM 或网络即可运行核心套件。

M1:ProjectIndex 与稳定身份

交付:

  • project/、sema::symbols;
  • FileId/ModuleId/SymbolId;
  • 项目范围、确定性扫描、duplicate/ambiguous 诊断;
  • 显式 import 与正文项目发现索引;
  • marqdo knowledge inspect/resolve 最小接口。

完成条件:

  • 改变文件扫描顺序不改变绑定或输出;
  • 同名李白示例报歧义,限定地址能解析;
  • 同一源码连续构建的 SymbolId 完全一致;
  • fallback 路径移动被 lock/impact 识别。

M2:统一 Named/Ref IR 与类函数

交付:

  • Markdown-aware narrative links;
  • Expr::Named/兼容 lowering;
  • KnowledgeRef/KnowledgeStep;
  • AssociatedFunction/InstanceMethod 分类;
  • Tree 和 Bytecode 使用 BoundTarget;
  • 正文不执行测试。

完成条件:

  • 两文档李白示例无需构造实例即可解析;
  • 代码上下文可求得 701,正文上下文只解析;
  • 使用 self/自 的方法经类路径调用报 link.instance_only;
  • 两后端返回值、调用 SymbolId 和错误 code 一致。

M3:SemanticArtifact、契约、effect、来源

交付:

  • 完整 Artifact IR 和分类;
  • CanonicalSignature、EffectSet、Applicability;
  • SourceRef 和分层 VerificationRecord;
  • 四类 digest;
  • 扩充 check --json。

完成条件:

  • 参数、类型、单位、适用条件和 effect 分别诊断;
  • pure/外部 effect 传递闭包正确;
  • 来源删除、内容变化与实现变化产生不同状态;
  • 格式化空白不改变 implementation digest,语义变更会改变。

M4:Lock、增量与影响分析

交付:

  • links.lock check/update/strict;
  • SCC closure digest;
  • 原子写入、缓存和确定性序列化;
  • 反向引用/依赖/证据影响查询。

完成条件:

  • 金卡折扣变化能找到获取折扣、计算应付、结算入口和正文说明;
  • interface/implementation/evidence 变化能分别展示;
  • strict 模式拒绝未审阅的目标变化;
  • 清空缓存后结果与增量构建完全一致。

M5:EKC、View、MLSP 与 Agent

交付:

  • EKC 消费 SemanticProject;
  • view 的引用卡片、来源链和状态;
  • MLSP 七个 artifact 方法;
  • BoundArtifactHandle 和 Agent 复用 trace;
  • draft/quarantine/promote 流程。

完成条件:

  • 图中 calls 边与实际运行 trace 的静态目标一致;
  • Agent 命中 ready 制品时执行 handle,不生成新函数;
  • 只有模糊候选时不能直接执行;
  • 不满足所选验证政策、已过相关有效期或 effect 不允许的制品不会被标记为该 policy 下的 REUSE ready;本地探索不冒充严格验证。

M6:迁移默认值与发布

交付:

  • 全仓 Classic 语法迁移;
  • 默认切换、兼容 flag、弃用说明;
  • public/examples/tutorial 更新;
  • schema 文档、升级指南和 release notes;
  • 100 单元基准与 Agent 对照实验。

完成条件:

  • 全部现有 gold tests 加新套件通过;
  • 仓库不再依赖全局 Markup 状态;
  • 迁移前后无未说明的输出变化;
  • 性能、正确性和复用指标达到发布阈值。

18. 文件级实施清单

下表是目标职责映射,不是“所有文件尚未创建”的任务表。src/project/、src/sema/ 和部分 API 已存在,先检查对应缺口与测试,再增量修改;不要依照旧“新建”措辞重复搭建模块或移走仍被消费者使用的能力。

文件/模块 修改
src/ast.rs 增加 SyntaxNodeId;Occluded 迁为 Named;承载 Narrative AST 的最小引用
src/parse/prose.rs 用 Markdown event/span 构建正文 inline/link,不执行
src/parse/expr.rs 统一 []();隔离并最终删除 Classic 分支和全局状态
src/load.rs 保留单模块加载;项目构建改由 project 编排;frontmatter mode 进入迁移诊断
src/project/* 新建项目发现、SourceMap、ModuleId、缓存
src/sema/* 新建符号、解析、类型、effect、来源、hash、lock、统一 IR
src/check.rs 成为 SemanticProject 诊断聚合器;保留当前契约规则
src/contract.rs 输出规范 CanonicalType/Predicate;运行时校验复用同一声明
src/interp.rs 从 BoundProgram 执行;AssociatedFunction;Ref trace
src/bytecode/compile.rs 删除独立名字绑定职责;从 BoundCall 生成 opcode
src/bytecode/vm.rs 执行 bound symbol/ref table;统一 trace 与诊断
src/artifact/mod.rs 迁移现有 Web 分类,释放概念命名
src/knowledge/extract.rs .mq.md 改从 SemanticProject 投影;普通 .md 仍可提取 authored knowledge
src/knowledge/fingerprint.rs 相似性 fingerprint 保留作检索;规范 digest 改用 sema::hashes
src/knowledge/graph.rs 从已绑定依赖生成边;移除“第一个同名符号”策略
src/knowledge/reuse.rs 搜索分数只做 discover;新增 readiness/bind gate
src/mlsp.rs 加 artifact API;dispatch 共享 project compiler 与 overlay
src/view/* 消费 LinkInfo/VerificationRecord;PreviewExecutor 隔离执行
src/main.rs CLI 参数、lock/trace/inspect/resolve 子命令和退出码
tests/executable_knowledge/* 正负例、双后端、迁移、lock、effect、图、Agent 测试
examples/executable-knowledge/* 以书店示例替换占位目标,标注每阶段可运行状态

实现时每个 PR 只覆盖一个可验收切片;不要在同一提交混合语法迁移、IR 重构和 UI 大改。


19. 自动化测试规范

19.1 单元测试

  • SymbolId/ModuleId 规范化、Unicode、路径移动;
  • Markdown destination 平衡括号与转义;
  • 导航/知识引用消歧;
  • AssociatedFunction/InstanceMethod 分类和传播;
  • CanonicalSignature/类型/单位;
  • EffectSet 合并与 SCC;
  • 四类 digest 的稳定性;
  • lock policy;
  • VerificationRecord 状态提升/降级;
  • JSON schema round-trip。

19.2 集成正例

  • 李白两文档事实;
  • 书店政策→定价→结算→客服说明;
  • 显式 import 的类函数;
  • 本地表达式遮蔽;
  • 正文 pure 引用 view 预览;
  • 实例继承方法保持行为;
  • 表格/循环/取元形成 KnowledgeStep;
  • 中文/英文双名与扩展能力;
  • Tree/Bytecode 完全一致。

19.3 集成负例

至少覆盖:

  • 目标删除/改名;
  • 同级同名;
  • 文档发现唯一但代码缺显式 import;
  • 漏参、多参、错误具名参数;
  • number/text、CNY/ratio 错配;
  • 类路径调用实例方法;
  • 零参省略作用于有参函数;
  • 正文调用网络、写文件、支付或 LLM;
  • 来源删除、来源内容变化、有效期过期;
  • 实现未变但传递依赖变化;
  • lock 的 target/interface/implementation/evidence 分别变化;
  • 递归依赖和循环 import;
  • symlink 越界;
  • label 与代码明显冲突;
  • 动态调用无法验证;
  • 缓存损坏;
  • 目录扫描顺序扰动。

19.4 100 单元确定性夹具

生成器固定包含:

类别 数量建议
正常跨文档调用链 25
同名/限定名/导入消歧 15
签名/类型/单位错误 15
来源/有效期/验证状态 10
effect 与正文安全 10
依赖变化/lock/impact 15
递归、循环和动态调用 10

每次生成额外随机打乱文件创建顺序。断言绑定结果、诊断集合、digest 和图边与顺序无关。

19.5 属性与模糊测试

  • [L](E) 与 E 在执行上下文的值/type/effect 等价;
  • 格式化和无语义叙述变化不改变 implementation digest;
  • 任一 Bound call 对应且仅对应一个静态 target;
  • graph 的静态 calls 边覆盖所有非动态运行调用;
  • lock update 后 strict check 通过;
  • parser 对任意输入不 panic;
  • view/check 对正文链接永不触发外部 effect。

20. 基准、实验与发布门槛

20.1 编译器指标

  • 冷构建耗时、峰值内存;
  • 单文件变更增量耗时;
  • 1k/10k/100k artifact 索引规模;
  • 符号解析准确率;
  • 影响分析 precision/recall;
  • 两后端一致率;
  • 缓存命中率;
  • 生成物确定性。

20.2 Agent 复用指标

在相同模型、任务、工具、token 预算和超时下比较普通 Markdown+RAG、当前 EKC、Semantic Artifact 方案:

  • 已有能力发现率;
  • 正确绑定率;
  • 不适用知识误用率;
  • 重复函数新增率;
  • REUSE/ADAPT/CREATE 分布;
  • 首次可运行成功率;
  • 总 token、工具调用、修复轮次和耗时;
  • 回答能否追溯到 SymbolId、digest、输入和来源。

同时记录作者手写声明/重复字段/配置数量、阅读定位准确率、语义步骤修改范围、无关 diff、并发补丁冲突和首次写作成本。比较时各方案应获得同等现有能力与输入信息,不向新方案额外提供答案;将编译和人工准备成本计入总成本。先通过正确性与权限硬门槛,再讨论 token 和速度收益,参见指导 §8。

20.3 发布门槛

  • 核心确定性套件 100% 通过;
  • 双后端目标用例 100% 一致;
  • 正文安全测试 0 次外部 effect;
  • 符号歧义无静默选择;
  • 迁移工具对已自动改写样例 100% 语义等价;
  • graph calls 与 bound calls 一致;
  • Agent 不适用知识误用率不得高于现有基线;
  • 性能退化超过预设阈值必须有明确批准与记录。

不要只报告平均值;保存失败样本、任务定义、环境、置信区间和版本摘要。

以上按发布宣称的能力范围执行。语法兼容、本地确定性复用、严格业务复用、远程执行分别有独立证据,不以一个总体 done 替代。M0–M6 保留为工程能力检查项,实际交付顺序采用修订路线 S0–S6:早期完成一篇文档的读/执行/复用闭环,再增加治理深度;任何已开放执行路径都不能延后安全门禁。


21. 书店示例的最终验收链

以附属示例为系统级验收:

corpus/pricing-policy.md
  └─ supported_by
knowledge/policy.mq.md
  ├─ 书店政策.金卡折扣
  ├─ 书店政策.银卡折扣
  ├─ 书店政策.免运费门槛
  └─ 书店政策.基础运费
       ↓ calls / depends_on
knowledge/pricing.mq.md
  └─ 定价.计算应付金额
       ├─ 计算商品小计
       ├─ 获取折扣
       └─ 计算运费
            ↓ reused_in
apps/checkout.mq.md + apps/assistant.mq.md

必须验证以下全过程:

  1. 项目编译产生稳定 SymbolId;
  2. 所有 []() 产生 Ref/Step;
  3. 60 × 2 × 0.90 = 108 由 Tree/Bytecode 同样计算;
  4. assistant 正文不在 run 中执行;
  5. view 可显示门槛、折扣、来源和验证层级;
  6. 修改金卡折扣到 0.88 后 implementation 和 closure 改变;
  7. 未更新来源时显示 evidence 不一致;
  8. impact 找到所有下游引用;
  9. strict lock 拒绝静默使用新版;
  10. 审阅并 update lock 后 Agent 可重新 bind/execute;
  11. 输入数量为 0 时在执行前报 knowledge.constraint_unmet;
  12. 在正文引用支付能力时拒绝 effect,而不是发起支付。

22. 开发过程约束

  1. 一套语义事实源:parser 只认语法,sema 决定身份和含义,runtime 执行 bound target,EKC/view/Agent 消费结果。
  2. 先确定性,后智能化:解析、绑定、契约、effect、hash、lock 不使用 LLM。
  3. 先负例,后演示:每新增一种成功路径,至少增加一个歧义/权限/变化负例。
  4. 不静默兼容:旧写法可能改义时必须迁移或报错。
  5. 不伪造可信度:未知就是 unknown,待复核就是 pending。
  6. 不复制源码复用:复用结果是 SymbolId/handle/trace,不是代码片段。
  7. 生成物可删除:.marqdo 投影永远可以从源码和显式证据重建。
  8. 产物可审计:每个值知道由哪个符号、版本、输入和 effect 得到。
  9. 变化可传播:实现、依赖、证据和适用性分开变更、分开报告。
  10. 文档与代码共同验收:示例未能由当前版本运行前,必须继续标为目标而不是已实现。

23. 最终定义

Marqdo 的本轮开发不以“链接语法更漂亮”为终点,而以以下能力闭环为终点:

一份由人维护的可读文档,被编译为具有稳定身份、明确契约、可追踪来源、受控副作用和版本摘要的语义制品;人或 AI 可以先发现它,再精确绑定它,在满足适用条件与权限后直接执行它,并把实际复用关系写回可审计的知识图。

[]() 是这条链路统一、低负担的作者入口;Semantic Artifact 是编译器的统一事实;Verified Knowledge Reference 是从文档到执行的确定性桥梁;EKC、view、MLSP 和 Agent 是同一语义结果的不同投影与消费者。

只有当“发现已有知识 → 确定绑定 → 验证适用 → 执行既有制品 → 追踪复用结果”能够在不重新生成同义实现的情况下完成,Marqdo 才真正达成:

代码即文档,文档即知识库,知识库可执行,可执行知识可复用。