From 92de46aca4d77d158fc1506cc5f356c237b9dd66 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 23 Oct 2026 08:06:38 +0000 Subject: [PATCH] docs: define executable knowledge implementation baseline --- doc/README.md | 3 + doc/next/009.md | 109 +- .../Marqdo_Executable_Knowledge_Design.md | 295 ++++ ...Marqdo_Executable_Knowledge_Development.md | 1454 +++++++++++++++++ .../Marqdo_Executable_Knowledge_Example.md | 400 +++++ 5 files changed, 2260 insertions(+), 1 deletion(-) create mode 100644 doc/next/Marqdo_Executable_Knowledge_Design.md create mode 100644 doc/next/Marqdo_Executable_Knowledge_Development.md create mode 100644 doc/next/Marqdo_Executable_Knowledge_Example.md diff --git a/doc/README.md b/doc/README.md index 591191b..e84ed85 100644 --- a/doc/README.md +++ b/doc/README.md @@ -13,6 +13,8 @@ ## 当前文档 +> **可执行知识下一阶段的规范优先级**:实现 `[]()`、Semantic Artifact、知识绑定、验证、锁定、EKC/Agent 复用时,以 [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) 为实施基线。与其冲突的早期链接、遮蔽、知识分层或 EKC 设计只作历史参考。 + | 文档 | 摘要 | |------|------| | [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** | @@ -108,6 +110,7 @@ | [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 | | [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 | | [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 | +| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 | | [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 | | [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 | | [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 | diff --git a/doc/next/009.md b/doc/next/009.md index a4803dc..f7d0c7f 100644 --- a/doc/next/009.md +++ b/doc/next/009.md @@ -343,4 +343,111 @@ Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行 当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。 -而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。 \ No newline at end of file +而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。 + + +是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 Marqdo 的最终目标。 + +实际上,这两者应当区分。 + +你最初提出的: + +> 代码即文档,文档即知识库,知识即可执行。 + +并不只是一句理念性的口号,它本身已经包含了完整的目标链条: + +1. 代码即文档:知识与程序不再被割裂为两套独立的表达体系。 +2. 文档即知识库:文档中的内容不再只是供人阅读的信息,而是可以被组织、定位、理解和关联的知识。 +3. 知识即可执行:知识不再停留在被检索和解释的阶段,而是能够被直接调用、组合和复用。 + +其中,知识复用就是第三阶段最重要的结果之一。 + +因此,我之前提出的“可寻址、可验证、可执行、可复用”,实际上是在描述达成第三阶段需要具备的工程性质,而不是一个比原始理念更高层次的新目标。 + +## 真正需要解决的是:什么才算知识被复用? + +我认为这里才是 Marqdo 当前设计最值得深入的地方。 + +假设 AI 需要计算一笔订单的最终价格。 + +传统方式可能是: + +- 检索价格计算文档; +- 阅读文档中的公式和约束; +- AI 自己理解并重新编写计算逻辑; +- 执行新生成的代码。 + +这个过程中,知识被读取了,但未必真正被复用。AI 仍然可能理解错误、遗漏约束或生成不一致的实现。 + +而你想实现的 Marqdo 应该是: + +``` +订单最终价格为[计算后的价格](订单.最终价格(订单数据))。 +``` + +这里 AI 不需要重新理解定价公式并生成一套新算法,而是引用已经存在的知识实现。 + +如果该实现的身份、依赖、契约和适用条件都能被确定,那么 AI 的任务就从: + +“根据知识重新生成答案或程序” + +转变成: + +“发现知识 → 判断是否适用 → 引用知识 → 执行知识 → 使用结果” + +这才是 Marqdo 的核心价值。 + +## 所以,`[]()` 应该承担什么角色? + +我建议将整个体系理解成: + +代码即文档 + +统一人类叙述与机器可执行内容 + +文档即知识库 + +知识具有结构、身份、关联与约束 + +知识即可执行 + +知识能够被确定性引用、调用和组合 + +知识真正复用 + +AI 优先使用既有知识,而非反复解释和重新生成 + +`[]()` 不需要独自完成这一切。 + +它应该成为整个体系中知识从文档进入使用场景的统一入口。 + +而编译器、符号系统、知识索引、验证系统与 EKC,则共同保证这个入口背后的知识可以可靠使用。 + +这里有一个很重要的区别: + +- `[]()` 负责表达“我要使用这段知识”。 +- 编译器负责确定“究竟是哪段知识”。 +- 验证系统负责判断“这段知识是否满足当前使用条件”。 +- 运行时负责执行知识。 + +这些职责不应该全部压到 `[]()` 的语法设计上。 + +## 我现在更倾向于保留你的原始理念 + +甚至不建议用我之前那段冗长的定义替换它。 + +“代码即文档,文档即知识库,知识即可执行”已经足够准确。 + +真正值得补充的是它背后的一个技术原则: + +> 知识复用应当基于已编译知识的确定性引用,而不是基于自然语言的重复解释与生成。 + +这句话比单纯强调“可寻址、可验证”更接近你真正想解决的 AI 问题。 + +不过还需要保持一个边界:确定性引用能够减少 AI 在重新解释和生成过程中产生的错误,却不能自动保证被引用的知识本身正确。因此验证仍然必要,只是它属于实现可靠复用的手段。 + +我认为 Marqdo 下一步最值得研究的,已经不是“如何让文档变成知识库”,而是一个更具体的问题: + +如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它? + +如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。 \ No newline at end of file diff --git a/doc/next/Marqdo_Executable_Knowledge_Design.md b/doc/next/Marqdo_Executable_Knowledge_Design.md new file mode 100644 index 0000000..43a3b2c --- /dev/null +++ b/doc/next/Marqdo_Executable_Knowledge_Design.md @@ -0,0 +1,295 @@ +# Marqdo 可执行知识体系:统一语义制品与知识引用设计规范 + +> 状态:设计提案(非当前版本的已实现功能) +> 基线:仓库 main,2026-10-23;README 标记 v2.0.0;跨文档类调用与 LinkInfo 为 v2.1 目标 +> 宗旨:**代码即文档,文档即知识库,知识即可执行。** +> 核心判据:当 AI 遇到任务时,能否先发现已有知识,并以确定性绑定复用,而不是再生成一份“看起来相同”的知识或实现? + +## 1. 决策摘要 + +保持 `[描述](表达式或知识目标)` 的 Markdown 形态,不引入新的前缀或第二套表达式文法。`[]` 是面向读者的陈述,`()` 内的内容进入统一表达式解析器。语言内部建立稳定的 **Semantic Artifact(语义制品)** 和 **Verified Knowledge Reference(可验证知识引用)** 两种核心抽象。前者承载身份、语义、实现、依赖、契约与来源;后者是一个经编译期解析、受上下文约束的引用。它们不必对应新语法标记,而是 `.mq.md` 经语义分析得到的统一中间表示。 + +**三项不变式:** + +1. **表达式透明性**:在求值上下文中 `[L](E)` 与 `E` 取得同一类型和值;`L` 不进入符号绑定或改变结果。引用额外产生诊断与溯源元数据。 +2. **文本安全性**:叙述中的知识链接在 `check/view` 中解析;`run` 不因正文出现链接而隐式执行有副作用的函数。导航链接(HTTP、相对文档路径)仍属于普通 Markdown 链接。 +3. **知识可信边界**:`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 一个节点。 + +```text +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 + +```text +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 最小语义规则 + +```text +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 唯一性与优先级 + +1. 当前词法作用域的变量/接收者; +2. 当前文档的声明; +3. 显式 `import` 命名空间; +4. 项目导出索引(受 `--fs-root` 和导出策略约束); +5. 内置/已安装扩展。 + +如果两个候选都满足同一级优先规则,报 `link.ambiguous`;不能随文件顺序自动挑一个。解析失败必须有诊断,不能把知识目标悄悄解释成字面字符串或导航路径。 + +### 4.4 类函数 vs 实例方法 + +- 目标函数使用 `self/自` → 实例方法,必须有显式接收者。 +- 函数不使用接收者 → 可由 `类.函数` 调用;不运行类的构造体。 +- 路径解析到零参函数时可以省略 `()`,但**函数作为一等值的语义必须避免与隐式调用冲突**。建议只有被 `[]()` 用作知识目标、或显式值需求时才触发零参隐式调用;直接 `类.函数` 在函数值场景需明确消歧。最终以一致的形式化语义测试冻结。 + +### 4.5 版本策略与效应 + +`interface_digest` 代表签名兼容性,`implementation_digest` 代表实现变化,`dependency_closure_digest` 代表传递依赖;`evidence_digest` 代表证据状态。既存调用在接口未变时不必全部报错,但“严格复现”任务应使用 lock 来禁止目标悄然变化。 + +纯知识事实允许受控求值与缓存;依赖网络、时间、随机数、外部模型的调用即使锁了源码也不天然确定。必须记录输入快照、环境与效应,并明确“不保证结果复现”的状态。 + +## 5. 静态分析、来源与可信性 + +### 5.1 五层验证(必须分层报告) + +1. **Parse**:Markdown 结构/语法可解析。 +2. **Resolve**:目标存在,歧义可消除。 +3. **Type/Contract**:签名、入参与结构类型、单位、前置条件匹配。 +4. **Execution/Test**:纯函数或受控沙箱完成运行与测试。 +5. **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. 编译器实施架构 + +```text +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 辅助迁移: + +```text +[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 必须按以下状态机处理: + +```text +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. 设计原则冻结 + +1. **源码可读,编译结果确定**。 +2. **知识是制品,不是文本片段**。 +3. **检索可以模糊,绑定必须确定**。 +4. **知识能够执行,但执行不等于真实**。 +5. **知识可以复用,但必须满足契约与适用条件**。 +6. **显示文字可自由,语义判断不依赖显示文字**。 +7. **默认保持叙述安全,副作用需要明确执行上下文**。 +8. **保持一种语法,一个语义解析器,一套符号索引**。 +9. **双后端与 view/EKC 使用同一份语义中间表示**。 +10. **失败必须可观察,不能因为链接看起来优雅而隐去错误**。 + +## 10. 来源依据 + +仓库:。重点阅读: + +- `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`。其中对未实现特性逐项标注,所有业务数据均为虚构演示数据。 diff --git a/doc/next/Marqdo_Executable_Knowledge_Development.md b/doc/next/Marqdo_Executable_Knowledge_Development.md new file mode 100644 index 0000000..ae5eecb --- /dev/null +++ b/doc/next/Marqdo_Executable_Knowledge_Development.md @@ -0,0 +1,1454 @@ +# 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 才真正达成: + +**代码即文档,文档即知识库,知识库可执行,可执行知识可复用。** diff --git a/doc/next/Marqdo_Executable_Knowledge_Example.md b/doc/next/Marqdo_Executable_Knowledge_Example.md new file mode 100644 index 0000000..b1549bc --- /dev/null +++ b/doc/next/Marqdo_Executable_Knowledge_Example.md @@ -0,0 +1,400 @@ +# 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. 原仓库参考资料 + +- +- +- +- +- +-