# Marqdo 可执行知识系统详细开发规范 | | | |---|---| | 状态 | **实施基线(Draft for Implementation)** | | 日期 | 2026-10-23 | | 适用版本 | v2.1 及后续兼容演进 | | 真实意图来源 | [`009.md`](009.md)、[`Marqdo_Executable_Knowledge_Design.md`](Marqdo_Executable_Knowledge_Design.md)、[`Marqdo_Executable_Knowledge_Example.md`](Marqdo_Executable_Knowledge_Example.md) | | 核心目标 | **代码即文档,文档即知识库,知识库可执行,可执行知识可确定性复用。** | ## 0. 文档地位与执行规则 本文把上述三份文档中的真实产品意图整理为可编码、可测试、可迁移、可验收的开发规范。开发本轮能力时,应以本文和三份意图来源为准;仓库中更早的链接、遮蔽、知识分层、类模型、OKF 或 EKC 文档若与本文冲突,不得据其改变本轮设计。 优先级从高到低如下: 1. `009.md` 中确认的产品目标与边界; 2. 本文冻结的工程决策、数据结构和验收条件; 3. 两份附属文档中的概念设计与完整示例; 4. 当前代码的兼容事实; 5. 其他旧文档,仅可作为历史背景,不是规范依据。 本文不宣称目标能力已经实现。表格中“当前”表示仓库 v2.0.0 的实际行为,“目标”表示完成相应里程碑后的行为。任何阶段只有在对应的自动化测试、双后端一致性测试和迁移测试全部通过后,才可从“目标”改标为“已实现”。 --- ## 1. 产品目标与成功判据 ### 1.1 目标链条 Marqdo 不是“能运行 Markdown 中几段代码”的解释器,也不是“给 RAG 提供更多 Markdown”的资料库。它要建立以下连续链条: ```text 代码即文档 └─ 程序、说明、契约和示例共址 ↓ 编译 文档即知识库 └─ 内容拥有稳定身份、类型、关系、来源和适用条件 ↓ 确定性绑定 知识库可执行 └─ 知识不是重新解释的文本,而是可调用的编译制品 ↓ 发现、校验、执行、追踪 可执行知识可复用 └─ 人和 Agent 优先复用既有能力,不重复生成同义实现 ``` ### 1.2 产品级成功判据 最终系统必须同时满足以下条件: - 人只维护 `.mq.md`、原始资料和显式配置,不手工同步另一份知识图; - 同一份源码能够生成运行程序、语义制品、引用图、可读 view 和 Agent 接口; - `[描述](载荷)` 在可执行位置与裸载荷取得同一值,在叙述位置默认不产生副作用; - 跨文档引用最终绑定到稳定 `SymbolId`,不能只保留名字字符串; - 模糊搜索只负责发现候选,真正执行前必须精确解析、校验契约和适用性; - 代码、依赖、来源或验证状态变化时,影响范围能够被程序找出; - Tree Interpreter 与 Bytecode VM 对同一已绑定程序产生一致结果和诊断; - Agent 命中已有且适用的制品时,得到的是可调用句柄,不是让模型复制源码再写一遍; - 系统从不把 `compiled`、`tested` 或 `source_present` 误报成“现实世界事实已证明正确”。 ### 1.3 不在本轮目标内 - 不设计第二套链接专用表达式语言; - 不增加 `knowledge:`、`call:`、`ref:` 等作者必须记忆的前缀; - 不把全部知识强制建模为类或函数; - 不在第一阶段实现通用 OWL/RDF 本体推理; - 不承诺网络、时间、随机数、LLM 或外部进程可由源码哈希完全重放; - 不用 LLM 替代确定性的解析、绑定、类型检查和权限检查; - 不把自然语言标签当作授权、契约或事实正确性的依据; - 不让 EKC、view、check、Agent 各自再次解析源码并形成不同理解。 --- ## 2. 当前实现基线与真实缺口 ### 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 `[]()` 的唯一表面形式 ```text [人类可读描述](机器可解析载荷) ``` `[]` 中的 label 是人话接口;`()` 中的 payload 使用所在上下文已有的 Marqdo 语法。二者共同形成一个命名步骤,但只有 payload 决定值、类型、依赖和副作用。 在可执行表达式上下文中: ```text 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 目标管线 ```text 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 建议的源码目录 ```text 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 公开编译入口 ```rust pub struct CompileOptions { pub project_root: PathBuf, pub entry: Option, 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, } pub fn compile_project(options: &CompileOptions) -> Result; ``` `run`、`check`、`view`、`knowledge compile` 和 MLSP 必须最终汇入此入口。针对内存源码的编辑器调用提供 `compile_overlay(project, overlays)`,不能另写简化语义。 --- ## 5. 统一语义中间表示 ### 5.1 标识类型 禁止在核心 API 中混用裸 `String` 表示文件、符号、制品和摘要: ```rust 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 ```rust 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, pub implementation: Option, pub contract: ContractSet, pub effects: EffectSet, pub dependencies: Vec, pub provenance: Vec, 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 ```rust 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), Unresolved, } pub struct KnowledgeStep { pub id: ArtifactId, pub reference: RefId, pub kind: StepKind, pub inputs: Vec, pub outputs: Vec, pub calls: Vec, pub effects: EffectSet, pub source: SourceLocation, } ``` 引用是“绑定关系”,步骤是“本次命名计算/叙述”。调用同一函数的两个位置拥有同一目标 `SymbolId`,但拥有不同 `RefId` 和 Step Artifact,便于回答“哪个句子受影响”。 ### 5.4 规范签名 ```rust pub struct CanonicalSignature { pub receiver: ReceiverKind, pub params: Vec, pub returns: CanonicalType, pub effects: EffectSet, } pub struct CanonicalParam { pub name: String, pub ty: CanonicalType, pub required: bool, pub default_digest: Option, pub unit: Option, pub constraints: Vec, } ``` 参数顺序、名称、是否必填、类型、单位、默认值和 receiver 都进入接口摘要。说明文字不进入接口摘要,但进入证据/文档摘要。 ### 5.5 EffectSet 第一版固定以下 effect: ```text 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 来源与验证记录 ```rust pub struct SourceRef { pub uri: String, pub locator: Option, pub content_digest: Option, pub retrieved_at: Option, 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, pub methods: Vec, } ``` 禁止单个 `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 建议序列化格式: ```text mq:///#// ``` 示例: ```text 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` 以降低回归风险,但重命名计划如下: ```rust Expr::Named { label: String, payload: Option>, syntax_id: SyntaxNodeId, } ``` 正文增加: ```rust pub enum NarrativeInline { Text(String), Code(String), Link(NarrativeLink), Emphasis(Vec), } ``` `Module` 不应保存完整语义结果,只保留解析结构和 `SyntaxNodeId`。Semantic tables 通过 ID 关联,避免 AST 被工具专用字段污染。 ### 7.3 Classic 迁移 统一语义启用前必须先迁移旧 `[键](集合)`: ```text [键](集合) → 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 前必须变成以下之一: ```rust 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` 至少支持: ```text 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 四类摘要 ```rust 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`,规范结构: ```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 新增或调整操作码: ```text 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 从“再次阅读源码并猜测工程知识”调整为: ```text 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。 核心边: ```text 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 状态机 ```text 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 获得许可、版本策略通过。搜索分数只用于候选排序。 ### 12.4 BoundArtifactHandle ```rust 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, } ``` Agent 执行必须携带 handle 和显式输入;runtime 再次核对摘要和权限,防止发现后到执行前目标变化。handle 是能力引用,不包含可由模型修改后悄悄执行的源码副本。 ### 12.5 Promote 门槛 Agent 新建或适配的知识进入可复用索引前,至少完成: - Parse/Resolve/Type/Contract 通过; - 声明 effect; - pure 逻辑有测试,外部 effect 有 mock/沙箱证明或人工批准; - 来源型知识附 SourceRef; - 生命周期从 `draft` 开始; - 生成者、输入、工具版本、变更 diff 可审计; - 未达到门槛的内容只在 quarantine/draft index 中可见。 --- ## 13. CLI、MLSP 与文件产物 ### 13.1 CLI 演进 保留现有命令,增加能力而不是平行造新命令族: ```bash 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 生成目录 ```text .marqdo/ ├─ project.json ├─ symbols.json ├─ artifacts/ │ └─ .json ├─ refs.json ├─ graph/ │ ├─ nodes.json │ └─ edges.json ├─ links.lock.json ├─ verification/ │ └─ .json ├─ traces/ │ └─ .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 | 新语义可显式开启;迁移报告必开 | Classic 发 deprecated warning | | 2.1 stable | 新语义默认;旧形状必须已迁移 | `--legacy-markup` 只读运行一个周期 | | 2.2 | 删除全局模式与旧 parser 分支 | 仅保留明确错误和迁移建议 | 具体版本可随发布计划调整,但顺序不能颠倒。 ### 16.2 不破坏的能力 - 现有显式 import; - 实例构造与实例方法; - 当前契约表; - Tree/Bytecode CLI 入口; - EKC 的 `find/reuse/impact` 用户命令; - Web/Endpoint Artifact metadata; - 无 `[]()` 文件的既有执行结果。 ### 16.3 必须显式变化的能力 - `[键](集合)` 迁为 `at`; - 链接不再依赖进程级 markup 模式; - `类.函数` 对无 receiver 函数成为合法 AssociatedFunction 调用; - 正文知识链接被解析和诊断,但不自动执行; - EKC 的 calls/edges 由 Bound IR 取代名字猜测; - lock 更新从普通编译中分离。 ### 16.4 迁移报告 ```json { "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:语义冻结与测试生成器 交付: - 本文进入仓库并被文档索引引用; - `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 不允许的制品不会被标记为 REUSE ready。 ### M6:迁移默认值与发布 交付: - 全仓 Classic 语法迁移; - 默认切换、兼容 flag、弃用说明; - public/examples/tutorial 更新; - schema 文档、升级指南和 release notes; - 100 单元基准与 Agent 对照实验。 完成条件: - 全部现有 gold tests 加新套件通过; - 仓库不再依赖全局 Markup 状态; - 迁移前后无未说明的输出变化; - 性能、正确性和复用指标达到发布阈值。 --- ## 18. 文件级实施清单 | 文件/模块 | 修改 | |---|---| | `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、输入和来源。 ### 20.3 发布门槛 - 核心确定性套件 100% 通过; - 双后端目标用例 100% 一致; - 正文安全测试 0 次外部 effect; - 符号歧义无静默选择; - 迁移工具对已自动改写样例 100% 语义等价; - graph calls 与 bound calls 一致; - Agent 不适用知识误用率不得高于现有基线; - 性能退化超过预设阈值必须有明确批准与记录。 不要只报告平均值;保存失败样本、任务定义、环境、置信区间和版本摘要。 --- ## 21. 书店示例的最终验收链 以附属示例为系统级验收: ```text 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 才真正达成: **代码即文档,文档即知识库,知识库可执行,可执行知识可复用。**