- docs/evidence/extension/6a7bb98.../manifest.json: tested_sha6a7bb98, cli sha256 28e3776d..., fixture repo e4b7352c..., all 7 required categories PASS - RFC-EXT-0001 status Implemented with PR-by-PR record and honest release caveat - STATUS/CURRENT/COMPATIBILITY/evidence report bind the executed result - workspace gate re-run: fmt/clippy clean, 599 passed across 67 targets Code tree at6a7bb98is byte-identical; this commit adds evidence/docs only.
98 KiB
RFC-EXT-0001:Marqdo CLI 可扩展性闭环与第三方仓库彻底解耦实施规范
状态:Implemented(实现与证据已按本文件验收,见 §19)。 本文同时保留为规范性任务书和验收记录;其中
MUST项目已由 PR-00…PR-08 实现并测试。发布 tag 仍受仓库既有的 G3/G4/平台门禁与 Owner 批准约束,见docs/releasing.md。实现基线:
6a7bb98(feat/extensible-ecosystem,2026-11-22,Linux x86_64)。实现与测试证据:docs/evidence/2026-11-22-ext-implementation.md;冻结 CLI 外部证据:docs/evidence/extension/6a7bb983c3b34fd0340afdcba9f197f7f50cba2a/manifest.json(CLI sha25628e3776d…,fixture repoe4b7352c…,全部必需结果 PASS)。**原始任务书文本保留如下。**文中标注
MUST的项目是必须达成的验收要求;SHOULD为建议,偏离须写 ADR;MAY为可选。本文同时给出架构、接口、程序顺序、负例、操作命令、交付物和退出条件。未明确授权修改仓库;实施者应以 PR 形式完成并保留全部证据。固定审查基线:
cflmy/marqdo-cli,master@595279fe38048b52b96d9ff1e7d57a867ec5c4c6(2026-11-21 查验)。原仓库:https://github.com/cflmy/marqdo-cli 。如果开发开始时 HEAD 已移动,先按 §2 的盘点模板重新核对事实,不能把本文基线判断无条件套用到新 SHA。语言权威:现行单一语义 RFC-LANG-0002 / ADR-0052;不得恢复 V1 兼容解释器,不得使用
syntax:/marqdo_semantics:选择双语义。现有 Plugin ABI v1、Value Wire、Analysis v2、Trace v2 等公开协议不得静默改义;需要破坏时另立版本并给出明确不兼容错误。本阶段目标:新增第三方
.mq.md函数库、Callable 插件、Foreign Kernel、Resource Provider、CLI Tool 或只读知识/证明消费者时,开发者不修改 marqdo-cli 源代码、不增加内置分发分支、不重新编译既有 CLI;通过显式声明、加载、授权、版本固定与协议测试即可使用。对基础语法、新基本类型、新 OS 原语的变更不作这项保证。
0. 执行摘要:哪些事必须做到,哪些坚决不做
0.1 完成定义(Definition of Done)
在冻结的同一份 Marqdo CLI 二进制上,另建 marqdo-ext-fixtures(仓库可命名为 marqdo-extension-conformance)并独立构建以下五类扩展:
- 一个固定 Git SHA 的外部纯
.mq.md库,具有跨模块函数,使用marqdo sync+run/check正确引用; - 一个导出多个不同前缀函数的外部 Callable Plugin(Worker 默认),静态签名和运行参数绑定一致;
- 一个语言标签完全未知(例如
mocklang)的 Foreign Kernel,通过--kernel登记并执行; - 一个资源种类完全未知(例如
demo.sensor)的 Resource Provider,通过普通 CLI加载,完整实现open/read/write/close,未授权时拒绝; - 一个独立 CLI Tool,通过已存在的
tool.json安装并调用公开 Analysis/Trace 合同,不依赖私有 Rust IR。
每项均要求:无 marqdo-cli 文件改动;未重编译 CLI;合法调用通过;未知导出、错误参数、重名、权限拒绝、工件篡改或版本不符都在可预期阶段失败且有结构化诊断;check 从不加载或运行第三方二进制。在全部通过前,不得在 README 中写“第三方生态已完全解耦”。
0.2 四条不可破坏的不变量
- S1 单语义:Markdown AST →
@exec/@knowledge→ H2 函数 → 语句载荷 → IR 由核心定义。@exec是固定核心语言关键字不是需要通用注册的插件。插件只能扩展函数/资源/工具/分析消费者;不允许按项目随意重定义 Markdown 控制流。 - S2 统一解析:同一调用点的
check与run必须绑定同一CallableId;Runtime 禁止重新按名字猜 Builtin/Module/Plugin;任何扩展必须先提供可静态读取的描述符。 - S3 权限不继承:加载/依赖/导入/清单声明只表示可见或请求,不是授权。所有 I/O 都在真实执行位置进行权限检查和审计。
project/Worker 不得被宣传为 OS 严格沙箱;现有strict L1继续拒绝第三方 Worker/Foreign/Provider。 - S4 低层内核稳定:普通算法、格式化、AI API、量子门组合、数据处理实现均使用
.mq.md、现有基础资源操作或独立 Provider;不得因一个新业务函数修改marqdo-ir::builtins::BUILTINS、builtins_impl.rs::dispatch、HostOp或resource_request()的字符串分支。
0.3 本阶段不做
不开发包注册中心、自动网络搜索插件、插件任意宏改写 Markdown、JIT、WASM 执行、跨设备共享裸指针、让未经 OS 约束的 Worker 支持 strict、将自定义业务对象不断加到 Value 枚举、拆出官方 stdlib/ 仓库、发布独立的分析/证明引擎。第三方 @agent/@proof 只能作为惰性文档元数据处理,不成为新的执行语义。新增语言级 if 变体、异步调度、原子内存操作、量子计算后端指令须另立语言/核心 RFC,不能借“可扩展”绕过评审。
1. 架构目标与边界:谁拥有哪一层
1.1 分层图
任何独立的第三方 Git 仓库
┌──────────────────────────────────────────────────────┐
│ .mq.md 库 │ plugin.yaml │ kernel.json │ provider.json │
│ tool.json │ 知识/证明/View 的 Analysis/Trace 消费者 │
└───────────────────────┬──────────────────────────────┘
│ 版本化清单 + hash + 显式引用
┌───────────────────────────▼─────────────────────────────┐
│ CLI Composition Root │
│ 收集 packages / plugin descriptors / kernel / providers │
│ 解析锁定身份;校验签名;授权策略;组装 Host │
└──────────┬───────────────────────┬───────────────────────┘
│ │
┌───────▼───────────────────────▼────────────────┐
│ Markdown AST → Frontend → CallableRegistry │
│ → BoundCallTable → IR │
│ 基础语法固定;静态绑定;副作用请求摘要 │
└──────────────────┬─────────────────────────────┘
│ CallableId(不重新猜名字)
┌──────────────────▼─────────────────────────────┐
│ Runtime:值 / 内存 / 控制流 / 执行调度 │
│ 核心 Builtin | Marqdo 函数 | 已绑定 ABI export │
└──────────────────┬─────────────────────────────┘
│ 显式可审计的 Host API
┌──────────────────▼─────────────────────────────┐
│ Host:Capability Broker / 资源句柄 / 预算 / Trace│
│ Plugin Worker │ Foreign Kernel │ Resource Worker│
└────────────────────────────────────────────────┘
旁路:CLI Tool 由独立进程执行,仅消费公开 CLI/Analysis/Trace;
Tool 不获得 Runtime 内存访问权,也不因安装而获得项目授权。
1.2 明确的职责与禁止依赖
| 层 | 负责 | 绝不能做 |
|---|---|---|
marqdo-markdown |
保真 Markdown AST / Span / 原始标题文本 | 按插件改变 Markdown 语法 |
marqdo-expression |
固定表达式与 if/else/while/end/return/params |
识别数据库/量子/AI 的业务函数 |
marqdo-frontend |
语义单元、作用域、签名、静态调用绑定、Analysis | 加载插件二进制;查询 OS 权限;网络搜索库 |
marqdo-ir |
公共内部 CallableId/Descriptor、可执行 IR、绑定表 |
硬编码新第三方导出名 |
marqdo-runtime |
只按绑定身份调用、内存和值计算、Trace 语义事件 | 根据字符串 fallback 猜插件、直接拉网络 |
marqdo-host |
最终授权、资源/进程适配、受控注册、审计 | 由未信任清单直接授予权限 |
marqdo-package |
锁定包实例/来源、路径与固定 Git SHA | 根据运行时 PATH 猜测代码来源 |
marqdo-plugin-abi / marqdo-foreign |
对外 ABI/外语 wire 版本边界 | 把第三方协议当成内部 Rust 对象 |
crates/cli |
组合装载/声明式参数/输出,不含扩展业务逻辑 | 在 run 命令中写每个扩展的专用分支 |
stdlib/ |
官方 .mq.md 高层函数 |
代替权限 Broker 持有真实 OS 权限 |
依赖方向:第三方仓库只依赖公开协议、头文件/SDK、.mq.md 模块以及 CLI 合同,不得依赖 marqdo-runtime、marqdo-frontend 或 marqdo-ir 私有结构和 include!()/path = ../marqdo-cli 风格的私有源码。Host 嵌入者可以使用公开 Rust API,但这是另一种产品分发形式;“无需重新编译 CLI”验收专门以命令行黑盒为准。
1.3 五类扩展不得合并成一个万能机制
| 类别 | 静态发现 | 执行形式 | 授权 | 典型应用 |
|---|---|---|---|---|
.mq.md Package |
marqdo.yaml + marqdo.lock |
Marqdo Runtime | 实际资源 I/O 时 | 数据处理、算法、Agent SKILL |
| Callable Plugin | plugin.yaml + 目标 ABI 工件 |
本机动态库或 Plugin Worker | --allow-plugin + 实际 Broker |
数值加速、设备 SDK 包装 |
| Foreign Kernel | kernel.json + pin 的可执行程序 |
独立子进程 | --allow-foreign |
兼容 Julia/R/Python 工具 |
| Resource Provider | provider.json + 工件 |
Resource Worker / trusted C ABI | --allow-provider + resource rights |
新设备、数据库连接、量子设备流 |
| CLI Tool | tool.json 安装记录 |
运行独立 CLI | Tool 独立授信;无隐式项目权限 | View、Proof、Knowledge、IDE |
1.4 元数据扩展,不引入动态 @exec
@exec、@knowledge 以及 H2 可调用性仍由 SemanticMode::{Exec, Knowledge} 决定;第三方不得注册 @agent 作为第三种执行状态。第三方库使用现有 Markdown 结构表达元数据,例如:
# @knowledge 量子实验
## @exec main
计算代码照常写在语句载荷中,调用 `quantum.run(...)`。
### @knowledge 证明与实验元数据
```json
{"schema":"vendor.quantum.proof","version":1,"obligation":"unit:#main"}
```
上例中的 JSON Fence 是惰性代码资源,在解析和渲染时不执行;第三方 Tool 通过公开 Analysis/源码读取并解释它。真正的 @agent 文本如需展示,可作为普通正文或章节名称,不使用目前会被拒绝的 @agent 标题模式。如果未来需要统一元数据 schema,另立 marqdo.metadata 描述协议,不修改 SemanticMode,也不自动赋予权限。
2. 当前源代码审计与刷新方式
2.1 基线确认的事实、影响、修复入口
| ID | 源码事实(595279f) | 影响 | 本 RFC 处理 |
|---|---|---|---|
| EXT-01 | marqdo-frontend/src/units.rs 的 SemanticMode 仅 Exec/Knowledge;未知 @xxx 报 SEM_INVALID_MODE_MARKER |
第三方不能加执行模式;但这是有意的语言闭包 | 保留;仅惰性元数据扩展 |
| EXT-02 | frontend/src/calls.rs 的 Member 调用先查 Builtin 再 import;runtime/src/interpreter.rs 对同类调用先查 import 再 Builtin |
编译与运行可能命中不同目标 | P0 统一静态绑定 |
| EXT-03 | ir/src/callable.rs 已有 CallableRegistry,但调用链仍分别使用 builtins::find 与运行时 fallback |
registry 未成为唯一真相;新 origin 需多处修补 | P0 解析与 dispatch 闭环 |
| EXT-04 | interpreter.rs 在无外部描述符时允许未知 alias.name 猜作插件调用 |
静态未知符号可能运行时才失败 | 删除 fallback;统一 symbol.unknown |
| EXT-05 | cli/src/commands/run.rs 从已加载导出补建缺失描述符时,签名曾使用 params: Vec::new(),特效请求使用泛化 host |
与真实 manifest 签名不一致;验证无法保证 | 禁止补录;静态与动态清单比对一致 |
| EXT-06 | cli/src/loader.rs 在加载主模块后才进行 validate_program;之后 CLI 再追加静态插件描述符并重复检查 |
错误时序、重复 diagnostics、check/run 分歧风险 |
P0 把扩展描述符提前注入一次性 finalize |
| EXT-07 | host/src/host/providers.rs 支持 Rust/C/Worker Provider,resource_ops.rs 提供未识别 kind 的注册分发 |
Host 可扩,普通 CLI 尚不能装载/授权 Provider | P0 增加 --provider/--allow-provider |
| EXT-08 | host/src/capability.rs::execute 目前仅 fs.read 具有实作处理,其余已识别能力走 unavailable |
注册了权限名不代表能实际执行 | P1 Handler table 与权限分离 |
| EXT-09 | host/src/host.rs::resource_request 有 process.run / regex.* 等逐字符串特例 |
每加新的非流式资源操作可能改核心 | P1 操作注册合同,现有核心操作保留 |
| EXT-10 | cli/src/loader.rs 的 program_uses_print 注入 stdlib/io.mq.md,Runtime 对 print 特判 |
标准库迁移若复制此模式将堆积硬编码 | P1 通用标准库别名绑定 |
| EXT-11 | foreign/src/lib.rs::KernelRegistry 已支持注册未知语言;旧 normalize_language 只认识 Python/Node |
新语言实际执行路径可扩,但公共帮助 API 可能误导 | 维持 registry 为唯一执行查询、标明 legacy 辅助函数 |
| EXT-12 | Plugin ABI v1 Native/Worker 已实现,Wasm 显式 unsupported;Tool Protocol 已有测试 | 不应重造插件/Tool 平台 | 保留并补签名与完整性契约 |
| EXT-13 | package/src/lib.rs 支持 path + pinned Git 及包实例;stdlib/ 是已验证的内置 bundle |
第三方 .mq.md 已有真实源码解耦路径 |
保持;补跨仓库黑盒测试 |
| EXT-14 | 目前 strict L1 仅允许受限纯计算与 stdout,Worker/Foreign/Provider 等拒绝 |
项目模式与严格安全模式不能混称 | 保持 fail-closed;L2 另 RFC |
注意:docs/EXTENSIBILITY_AUDIT.md 是历史计划,部分曾经的问题已经解决;本 RFC 不可机械复制旧 E01–E16 状态。当前 .mq.md 语法参考 docs/architecture/RFC-LANG-0002-unified-semantics.md 与 docs/adr/0052-unified-markdown-semantics.md。
2.2 开发开始前必须运行的静态盘点(允许 HEAD 前移)
set -euo pipefail
git fetch origin
git checkout -b feat/extensible-ecosystem origin/master
git rev-parse HEAD
rg -n 'enum SemanticMode|heading_declaration' crates/marqdo-frontend/src
rg -n 'builtins::find|external_callable|PluginInvoke|print_override' crates
rg -n 'register_.*provider|allow_resource_provider|resource_request' crates
rg -n 'add_static_plugin_descriptors|validate_program|plugin_exports' crates/cli
rg -n 'KNOWN_CAPABILITIES|fn execute|capability.unavailable' crates/marqdo-host crates/marqdo-plugin-abi
rg -n 'SUPPORTED_LANGUAGES|KernelRegistry|normalize_language' crates/marqdo-foreign
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
填写 docs/evidence/ext-baseline-<SHA>.md:git SHA、Rust/Cargo 版本、OS/arch、每个命令退出码、已复现问题、未复现问题、现行 CI run URL。上述命令的成功不等于新功能完成,只是基线。若看到本文某项问题已被修复,应标为 already_closed 并引用对应测试,不允许重新实现一个平行系统。
3. 顶层开发顺序、每个 PR 的原子边界
禁止“大爆炸一次性全部替换”。 每个 PR 都应能在当前平台上独立构建、通过相关回归测试,且产出一份 evidence 文件。
| PR | 任务 | 主要改动 | 前置 | 可合并门禁 |
|---|---|---|---|---|
| PR-00 | 基线与测试脚手架 | 冲突 fixture、冻结 CLI 黑盒驱动、架构依赖门禁 | 无 | 新测试先红(或者证明已绿),不能仅新增文档 |
| PR-01 | Callable 唯一静态解析 | ir/callable.rs、frontend/calls.rs、CLI loader/finalize |
PR-00 | 同一个 call site 唯一绑定,冲突矩阵全绿 |
| PR-02 | Runtime 只按已解析身份分发 | runtime/interpreter.rs、ABI 绑定、删除 fallback |
PR-01 | check == run、参数/签名完全一致 |
| PR-03 | Resource Provider CLI 闭环 | CLI settings、Provider manifest v2、Worker assembly | PR-00、建议 PR-02 | 外部 Provider 在冻结二进制运行且拒绝越权 |
| PR-04 | Package/Extension 版本与装载归一 | CLI 配置组合根、解析/授权去重、完整性记录 | PR-02/03 | 多包/多插件、多版本、离线闭环 |
| PR-05 | Capability Handler 与操作扩展 | Host Broker + 可注册 operation handler | PR-03 | 未定义 handler 不执行,权限有审计 |
| PR-06 | 标准库别名去魔法化 | loader.rs、Builtin/stdlib 绑定层 |
PR-02 | print 既有正负例等价,无按函数名扫描的新增特例 |
| PR-07 | 公共 Analysis/Trace 与第三方消费者 | spec/goldens、Tool e2e、外部仓库 CI | PR-01~06 | 外部工具只依赖公共 schema |
| PR-08 | 发布/安全/文档收敛 | README、STATUS、ADR、CI 矩阵、releasing | 所有前置 | §11 所有门禁通过才可 release |
并行规则:PR-03 可与 PR-01/02 并行;PR-05 不得与 PR-03 同时引入第二种不兼容 Provider schema;PR-06 必须在唯一绑定稳定之后进行。PR-07 的外部 fixture 框架可在 PR-00 建立,待功能就绪逐一解除 expected_failure,最后禁止剩余 xfail。
4. PR-01/PR-02:唯一 Callable 解析、绑定与运行分发(最高优先级)
4.1 需要修复的具体调用矛盾
当前 Expr::Member(alias, name) 在 crates/marqdo-frontend/src/calls.rs 的检查顺序与 crates/marqdo-runtime/src/interpreter.rs 的执行顺序不同;Expr::Ident 又有局部变量、打印重定向、Builtin、函数的独立优先级。更严重的是,Runtime 在 program.external_callables 为空时容忍未声明的 alias.xxx 并发往 PluginInvoke;以及 run.rs 为已加载但未静态描述的 export 合成空参数签名。会造成:静态通过但实际调用另一实现、扩展名冲突不稳定、错误延后到执行时、调用合同不一致。
红灯测试 A(本阶段先写后修):用 import: { math: "./math.mq.md" },在导入模块中实现 eval,同时主文件调用 math.eval(...);静态解析和实际运行必须一致。建议的最终行为为编译时报别名冲突,而不是静态按内置检查、运行时执行导入函数。红灯测试 B:不传 --plugin 时调用 solver.add(a=1,b=2),check 与 run 都必须在编译期返回 symbol.unknown;不得尝试 Host PluginInvoke。红灯测试 C:插件清单只有 solver.add(a,b) 而执行时调用不存在的 solver.subtract,必须静态拒绝,不受其他已加载插件数量影响。
4.2 新增/调整的数据模型(建议形状;公开 IR 之外的内部实现可微调)
在 crates/marqdo-ir/src/callable.rs 补齐只读 CallableRegistry;在 marqdo-ir/src/lib.rs 或独立 call_binding.rs 保存已经决议的调用点。优先不增 crate:
#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
pub struct CallSiteKey {
pub module: ModuleId,
pub function: FunctionId,
pub span_start: usize,
pub span_end: usize,
}
#[derive(Clone, Debug)]
pub enum BoundTarget {
Static(CallableId),
// 局部变量持有 FunctionRef 等运行时值,此路径只允许语言值调用;
// 不允许在此路径退化为未知字符串的 ABI 调用。
DynamicValue,
}
#[derive(Clone, Debug, Default)]
pub struct CallBindingTable {
pub sites: BTreeMap<CallSiteKey, BoundTarget>,
}
#[derive(Clone, Debug)]
pub struct BoundCallable {
pub descriptor: CallableDescriptor,
pub target: CallableTarget, // 内部闭包,不包含裸主机指针
}
pub enum CallableTarget {
Builtin { canonical_name: String },
Marqdo { function_id: FunctionId },
AbiPlugin { package: String, export: String, digest: String },
}
这段 Rust 是实现接口草案,不是现有代码可直接复制编译的补丁。开发者必须沿用真实的 FunctionId、ModuleId、Span 构造方式,确保现行 Analysis v2 与 Trace v2 协议不被内部字段变化误改;新增内部绑定表不应默认暴露为公开 JSON。CallableId MUST 具有确定性,不依赖磁盘物理路径、注册顺序或随机 HashMap 遍历。第三方插件的身份至少包括插件包身份、完整导出名与已验证的工件摘要;包的多版本实例使用锁文件的包实例标识,不能只用显示名。
4.3 静态解析优先级:必须明确、可复现,无模糊试探
本阶段采用显式命名冲突拒绝优先,优于“恰好哪个先匹配”。
| 调用形式 | 规则 | 允许的例外 |
|---|---|---|
f(...) |
优先本地变量(若为可调用 FunctionRef,运行时动态调用);否则解析未占用的 Builtin 名,再按当前 namespace/可见模块函数查找 |
同名不同 namespace 且未显式限定,报 ambiguity |
alias.f(...) |
alias 若是显式 import,唯一绑定到该包内函数 |
未声明函数编译错误,不降级成插件/内置函数 |
core_alias.f(...) |
alias 若与核心内置函数的 dotted namespace 冲突,声明 import 时拒绝,并给出改名提示 |
不允许把内置 math.eval 在同一作用域隐式改成导入 math.eval |
vendor.f(...) |
既不是 import 别名也不是本地动态值时,仅按静态插件完整导出名查找 | 未加载描述符直接 symbol.unknown |
some_map.f(...) |
若 some_map 为局部值,在编译期标为 DynamicValue,运行时依语言 Member/FunctionRef 既有规则判定 |
不能作为任意 PluginInvoke 后门 |
print(...) / 打印(...) |
本阶段保留既有公开打印行为,PR-06 改为通用标准库 alias;先保持所有格式化/Trace goldens | 不因此新增另一打印专属调度路径 |
名字合法性:插件导出必须有明确 namespace.function 结构且不能使用核心保留前缀;静态表中存在同名 Builtin、模块导出、插件导出时,MUST 在装载/绑定时给出冲突诊断;禁止“last wins”“first wins”以及根据注册顺序遮蔽。可以保留合法局部变量对未限定函数名的覆盖,但这应作为语言变量作用域规则写入规范,不得影响 alias.f 的显式静态目标。
包内导入命名空间:在加载该模块的前置阶段即可汇总所有显式 import alias、内置 dotted prefix 和可见插件 prefix,冲突按本表拒绝。对于旧文档中恰好名为 math 等的 alias,提供错误解释和重命名建议;用户允许 0.x 破坏性语义修正,但无 --legacy 兼容开关。第三方实际导出名称不可因为冲突被自动加后缀。
4.4 统一装载流程:先描述符,后 validate_program
当前 Loader::load() 先完成跨模块检查,CLI 后续通过 add_static_plugin_descriptors 追加插件并再次调用 validate_program。必须改为一次 finalize,不再通过重复验证消除先后错误。
建议的新代码组织:
crates/cli/src/
loader.rs # 只加载 Markdown / pinned dependencies,保留源位置信息
extension_descriptors.rs # 读取 Plugin manifests / External descriptors,不执行二进制
project_prepare.rs # prepare(file, ExtensionSet) -> PreparedProgram
commands/check.rs # 调用 prepare;消费诊断,无 Host side effect
commands/run.rs # 调用同一 prepare;核验工件并组装 Host,执行已绑定目标
crates/marqdo-ir/src/
callable.rs # descriptor、registry、唯一命名查找
call_binding.rs # CallSiteKey/BoundTarget(或等价位置)
crates/marqdo-frontend/src/
calls.rs # 由 registry 产生 CallBindingTable + Diagnostic
统一流程伪代码:
fn prepare(file: &Path, extensions: &ExtensionSelection)
-> Result<PreparedProgram, Vec<Diagnostic>>
{
let mut loaded = load_module_graph(file)?; // 只读源码、清单、锁文件
let external = read_plugin_descriptors(extensions)?; // 不 dlopen、不 spawn
let registry = CallableRegistry::build(&loaded, &external)?;
let bindings = validate_and_bind(&loaded, ®istry)?; // 仅此一次
Ok(PreparedProgram { loaded, registry, bindings, external })
}
fn run(prepared: PreparedProgram, selection: &ExtensionSelection, grant: &GrantSet) {
let mut host = assemble_host(grant)?;
let runtime_exports = load_selected_plugins(&mut host, selection)?;
reconcile_exact_exports(&prepared.external, &runtime_exports)?;
execute_bound_program(prepared, host);
}
prepare() 的全部可执行边界是文件读取、清单解析、静态摘要/工件元数据验证;不得调用 LoadedPlugin::open_with、WorkerPlugin::spawn、Foreign.run、ResourceProvider.open、网络 fetch 或任意 shell。静态检查 MUST 复用同一份 PreparedProgram 绑定逻辑;inspect / Analysis emit 也消费它。run() 必须在准备成功后才能启动 Worker。run 的 Plugin manifest 指向缺失或不匹配工件,应在真实加载前失败且不执行主函数。
4.5 插件签名、默认值、参数位置与运行绑定(明确禁止空签名填充)
在 cli/src/commands.rs::plugin_signature 的现有签名读取基础上,让 Runtime 拿到同一份 CallableSignature:
- 静态加载
plugin.yaml时,解析完整参数名称、顺序、必选性,拒绝重名、非法名字、不支持的默认表达式;返回注解如-> Int当前若仅展示,明确写为advisory,不虚称运行时类型证明。 - 静态检查时用 descriptor 执行
validate_args;除签名明确允许的参数外不得接受未知参数。对于 ABI v1 当前使用 map 传参的事实,支持位置参数时必须先将其确定性映射为签名参数名;若无法做到,必须在静态阶段明确拒绝位置参数,禁止静态通过而运行时才拒绝。 - 推荐本阶段实现一致的位置参数绑定:例如
solver.add(1, b=2)规范化为{a:1,b:2};任何重复、未知、缺失参数先失败。对于带缺省值的 ABI 参数,v1 首先可直接拒绝在清单中定义默认值,直到语义与 Wire 版本明确,不允许随便在运行时隐式注入。 - Host
plugin_exports()返回的name/signature/digest/package必须与静态 manifest 集合精确一一对应。多出、少了、签名不同、Owner 不同、工件 SHA 不同,统一返回ext.plugin_binding_mismatch且禁止执行;不允许以params: Vec::new()合成描述符。 - Runtime
dispatch不得再次builtins::find(qualified)或以external_callables.is_empty()作为 fallback 条件;根据绑定结果Builtin | Marqdo | AbiPlugin | DynamicValue分发。DynamicValue仅对真正的语言可调用值有效。 - 有多插件时按完整导出名注册,不以
solver字符串前缀挑选“第一插件”;跨插件重名是确定性错误,Worker 与 Native 在签名绑定层无差别。
4.6 必须新增的精确测试
新增 crates/cli/tests/callable_resolution.rs(黑盒 CLI)与 crates/marqdo-frontend 对应单元测试,至少:
| 编号 | 构造 | 期待结果 |
|---|---|---|
| CALL-01 | import alias 与 math.* Builtin prefix 冲突 |
check 确定性编译错误,run 不执行 |
| CALL-02 | math.eval(...) 无 import 且参数合法 |
check 和 run 都绑定 Builtin |
| CALL-03 | math 重命名为 mymath 并调用 mymath.eval() |
check 和 run 都调用模块函数 |
| CALL-04 | solver.add 无插件描述符 |
symbol.unknown,无 Host fallback |
| CALL-05 | solver.add 在不同数量的无关插件下缺失 |
同一诊断、位置、状态码 |
| CALL-06 | 插件真实两个不同前缀 exports | 两个函数都可静态检查并运行 |
| CALL-07 | 两个插件同名完整 export | 准备阶段冲突;不启动其中任何一个 |
| CALL-08 | 错误参数名/少参数/重复参数/过多位置参数 | check 阶段失败,run 同诊断 |
| CALL-09 | 参数合法但运行时加载的 artifact SHA 改变 | 执行主函数前拒绝 |
| CALL-10 | 清单签名与运行时导出签名不一致 | ext.plugin_binding_mismatch |
| CALL-11 | 局部变量是真实 FunctionRef | 可运行,不能转为插件 fallback |
| CALL-12 | 无法静态确定的局部调用目标值是 Text | not_callable,不调用 Host |
| CALL-13 | 两个不同 package instance 有同名局部函数 | 按显式导入实例绑定,物理缓存位置无关 |
| CALL-14 | check --plugin 时放置不应被执行的插件启动副作用脚本 |
仅读取静态清单;该脚本未运行 |
| CALL-15 | 从 check --emit 到 run 的绑定身份一致 |
原因与来源可由公开诊断/测试投影核对 |
| CALL-16 | 原有 打印/print 标准库行为 |
输出字节、Error、Trace goldens 等价 |
完成定义:Runtime 所有静态 call site 都有绑定项;没有由 qualified 字符串推测插件的分支;CallableRegistry::from_program 不只是一个孤立的数据结构,实际 check/run/inspect 都消费同一解析结果;所有上述红灯测试变绿。
5. PR-03:普通 CLI 的第三方 Resource Provider 完整接入
5.1 现状与约束
StdHost::register_resource_provider、register_worker_resource_provider、register_c_resource_provider 和 register_provider_package 已存在;resource.open(other) 能在 self.resource_providers 中按新 kind 找到处理器并检查 Capabilities::check_resource_provider(name,...)。这是可复用的正确内核,不能重新写一个资源运行时。
但 crates/cli/src/main.rs 的 SandboxArgs、commands/sandbox.rs 的 SandboxSettings 和 commands/run.rs 不接受/装载/授权第三方 Provider,因此新仓库无法仅凭 marqdo run 使用。采用新增一个 CLI 组合根入口,不新增 HostOp 枚举分支、不新增语法关键字。
5.2 新 CLI 公共合同(本阶段必须实现)
marqdo run FILE --mode project \
--provider PATH/TO/provider.json \
--allow-provider PROVIDER_NAME
marqdo call FILE FUNCTION [named arguments...] --mode project \
--provider PATH/TO/provider.json \
--allow-provider PROVIDER_NAME
marqdo check FILE # 检查 Marqdo 文档,不加载 Provider
--provider:可重复;仅显式注册,无目录扫描;支持相对当前工作目录或绝对 manifest 路径,标准化后必须是普通文件;相对工件路径以 manifest 父目录为根,禁止../symlink 跳出已声明 bundle。--allow-provider:可重复;精确匹配经过清单声明和授权的name;不允许*通配符;仅--provider不会授权;仅--allow-provider而无 Provider,不自动寻找或下载。pure/strict:带--provider、--allow-provider均在 preflight 明确拒绝,不能静默切成 project;strict L2未实装时不放开。- Provider 名称和 kind 重复、协议版本不支持、worker 程序缺失、库文件 hash 错误、工件目标不兼容,全部在运行主函数前 fail-closed;不得回退为 Native。
check默认不解析 Provider 作为新的函数语义来源;Provider kind 是resource.open的运行参数,不自动添加全局 Marqdo 函数。
5.3 Provider manifest:为新 CLI 入口定义 v2,保留 v1 显式历史边界
现有 ADR-0037 的 marqdo.provider schema_version=1 只有 name/kinds/abi/library,缺少可移植的目标工件摘要与版本字段。本阶段新增 schema_version=2(仍使用 provider.json 文件名),CLI 扩展装载只接受 v2;旧 v1 可以继续通过既有显式 StdHost::register_provider_package 供可信嵌入者使用。不得静默把 v1 当 v2,也不得伪造它有工件校验。新的 spec/resource-provider-v2.md 必须完整定义下面的字段和拒绝条件:
{
"schema": "marqdo.provider",
"schema_version": 2,
"name": "demo.sensor",
"version": "0.1.0",
"abi": "c-abi-1",
"transport": "worker",
"kinds": ["demo.sensor"],
"artifacts": [
{
"target": "x86_64-unknown-linux-gnu",
"path": "lib/libdemo_sensor.so",
"sha256": "<64-lowercase-hex-sha256>"
}
],
"permissions_requested": []
}
上述 sha256 是占位符,构建时必须替换为真实二进制摘要;目标三元组须和 marqdo_plugin_abi::HostTarget::current().triple() 的结果一致。v2 解析规则:
schema/schema_version必须恰好匹配;name与每个kind必须非空、符合允许的分段命名语法(采用 Plugin 名称校验中的 ASCII 小写段 +.;若允许 Unicode 名称须另立 ADR);保留stdio/file/tcp/tls/udp/tcp-listener等核心 kind,禁止第三方覆盖。version为严格 SemVer;abiv2 初期只支持c-abi-1;transportv2 初期只支持worker。未来新增 transport 必须明确增加枚举与测试,不自动解释未知字符串。artifacts必须非空,不能重复 target;选择当前目标后校验普通文件、bundle 内位置、大小上限、SHA-256 精确相符;目标缺失返回ext.no_matching_artifact,不使用default的其他平台二进制替补。permissions_requested为声明,不授予权限;v2open/read/write/close只按--allow-provider+ rights 受控,不能因为声明了vendor.*就给 Host 新权限。- schema 版本内未知的安全影响字段拒绝;可扩展元数据统一放入
metadata映射且不具有执行意义。manifest 自身保存为 UTF-8 JSON。相对路径解析前阻止..、绝对路径、符号链接逃逸;绝不将内容拼接给 shell。 - 加载前验证完整 manifest + artifact;若要强制工件真实性,交由发布签名/信任根或用户固定的期望摘要额外处理。SHA-256 是完整性检查,不是来源身份认证,文档不得混淆。
5.4 精确落地的代码修改
crates/cli/src/main.rs:为SandboxArgs增加provider: Vec<PathBuf>(CLI 名--provider)和allow_provider: Vec<String>(CLI 名--allow-provider)。两个选项同用于run/call,不得在check阶段启动 Worker。crates/cli/src/commands/sandbox.rs:为SandboxSettings加同名字段;capabilities()的Project分支对每个名称执行allow_resource_provider(name);Pure/Strict的拒绝条件均包含两个新字段;strict_preflight()输出固定、结构化错误码。- 新建
crates/cli/src/provider_manifest.rs(而非新大 crate):解析 v2;校验语法、artifact、sha256、target;产出VerifiedProvider { name, kinds, selected_artifact, transport, manifest_digest };不要与 Pluginplugin.yaml共享错误的 ABI 解析器。 - 新建或复用
commands::load_resource_provider_into_host(...):先验 manifest 与工件,确认--allow-provider NAME存在;调用已有StdHost::register_worker_resource_provider(name, kinds, worker_program, [artifact_path]);Host 最终对 resource.open 再次授权;失败不得尝试注册受信 Native。 - Worker 可执行程序解析:使用发行包中和
marqdo同目标三元组的marqdo-provider-worker(从当前 CLI 可执行文件的兄弟目录解析),拒绝 PATH 任意同名可执行文件回退;发行归档必须一起交付、记录摘要。若某平台尚未支持,返回ext.platform_unsupported,不可伪装成功。 - 在
run/call的通用assemble_host中加载 kernels、Callable plugins、resource providers;为各类型使用相同的可重复、确定性错误输出规则,但保持不同执行协议。加载顺序严格:parse + compile → 校验扩展唯一性与工件摘要 → 验证授权 → 初始化必要的 Worker → 执行主函数;无语义副作用的检查绝不 spawn。 StdHostProvider 注册 API 的代码重复部分要复用register_provider_checked;保障按完整 kind索引,重复 kind 跨 Provider 不得覆盖;单个 Provider 同时导出两个 kind 都必须可用。- 结束 Session 时关闭所有 Provider tokens 并终止对应 Worker;单次 Worker crash 要转结构化错误,不能让 CLI panic;禁止在资源使用中断后静默回退其他 Provider。
5.5 可复制的 Provider 调用 fixture(现有语法)
index.mq.md:
# @knowledge 设备测试
## @exec main
打开独立仓库提供的资源;此标题仅决定文档语义,不涉及 Provider 注册。
`流 = resource.open("demo.sensor", "unit-1", ["read"])`
`内存 = memory.new(1, 1)`
`读取 = resource.read(流, 内存, 0, 5)`
`关闭 = resource.close(流)`
`if not 读取.ok`
`return 读取`
`else`
`if not 关闭.ok`
`return 关闭`
`else`
`if true`
`return 读取.value.count`
`end`
`end`
`end`
配套 fixture Worker open 返回独立 provider token;第一次 read 返回字节 hello,eof=true,返回 count=5;close 必须仅发生一次,运行结果为整数 5。注意 Resource 与 Memory 均为语言层不透明句柄,不可从 Wire 随意反序列化。有关 buffer 长度、权限及 Result 结构使用仓库真实 stdlib/fs/file.mq.md 现行调用约定,不应发明新的 resource.read(bytes=...) 形态。
5.6 Provider 测试矩阵
| ID | 输入 | 预期 |
|---|---|---|
| PROV-01 | 外部 v2 Worker + grant + read 5 bytes | 返回 5,stdout 不变,Host Trace 有 resource effect |
| PROV-02 | v2 Worker,无 grant | permission.denied;不得先启动未授权 Worker |
| PROV-03 | 只 grant,不提供 manifest | resource.unsupported 或装载诊断,不自动发现 |
| PROV-04 | 同 kind 不同 Provider | 准备阶段冲突,不能“后注册覆盖” |
| PROV-05 | 同一 Provider 有两个非保留 kind | 两个 kind 分别可 open/read/close |
| PROV-06 | kind="stdio" / kind="file" |
注册拒绝,不可覆盖核心资源 |
| PROV-07 | digest 不匹配、symlink 外逃、路径 ../ |
spawn 前拒绝,安全错误稳定 |
| PROV-08 | 缺少当前 target | ext.no_matching_artifact |
| PROV-09 | v1 传入新 CLI | ext.unsupported_provider_schema;无 silent migration |
| PROV-10 | pure 与 strict 带 Provider 参数 |
preflight 拒绝、无 Worker |
| PROV-11 | Worker 崩溃/超时/返回超大帧 | Host 结构化错误,CLI 不 crash,不退回 Native |
| PROV-12 | token 关闭后读、跨 run 重用、伪造值 | fail-closed,不能泄漏其他资源 |
| PROV-13 | 无 marqdo-provider-worker 同目录 helper |
清晰报缺失,不 PATH fallback |
| PROV-14 | 多次并发开启/退出同 Worker(以当前同步 API 测试) | 生命周期/句柄隔离,关闭幂等性按现有 API 规范 |
| PROV-15 | 外部仓库安装并在冻结 CLI 上跑 | 哈希证明 CLI 二进制未变,源码无改动 |
说明:当前 C ABI Worker 相关 fixture 可能仅覆盖 Unix 平台。新增 v2 Provider CLI 首先在 Linux x86_64 做强制门禁;macOS 如支持则同门禁;Windows 保持可编译且显式 unsupported,直到有独立 native fixture 和真实 C/Worker 证据才标 supported。不得因为 Linux 通过就宣布全平台支持。
6. PR-04:Package 与 Extension 组合根——独立仓库可以发布,使用端显式激活
6.1 为什么现有 Package 机制基本正确,但尚未完全闭合
marqdo-package 的 Dependency::{path,git,rev}、ResolvedPackage、PackageInstanceId + relative_path、lock v3 与 Git cache 已经形成普通 .mq.md 仓库之间的解耦基础。不得为“插件系统”重新实现一个隐藏的 Marqdo 源码包管理器。 当前的缺口是:项目 marqdo.yaml 里存在 Plugin 版本需求,但 CLI --plugin 路径、--kernel、计划中的 --provider 与 Package 锁身份未形成清晰、一致的装配事实表。当前只能靠开发者命令行重复传路径;若从其他独立仓库部署,容易出现 descriptor/执行工件不同步。
6.2 唯一 Project Extension Selection 结构
建议新增内部 ExtensionSelection(放在 CLI 组合根而非新 crate):
pub struct ExtensionSelection {
pub plugins: Vec<ResolvedPluginManifest>,
pub kernels: Vec<ResolvedKernelDescriptor>,
pub providers: Vec<ResolvedProviderManifest>,
}
pub struct ExtensionIdentity {
pub kind: ExtensionKind, // plugin | kernel | provider
pub logical_owner: String, // 来自当前已锁定包或当前项目
pub name: String, // 包/Provider 稳定声明名
pub version: String, // 若本协议支持版本
pub manifest_digest: String,
pub artifact_digest: String,
pub selected_target: String,
}
每一种现有扩展都保留各自的解析器与 ABI;ExtensionSelection 只负责把“谁、版本、摘要、来源、用户启用”统一成可审计事实。相同完整身份可去重;同名不同 digest、一个 kind 被两个 Provider 声明、同名 Plugin Export 重复,都必须给出确定性冲突。绝不能按目录遍历顺序决定使用哪个实现。
6.3 后续 marqdo.yaml 可声明扩展激活源,但绝不自动授权
PR-04 把下列语法作为唯一新增的项目 manifest 结构(须更新 crates/marqdo-package/src/lib.rs::Manifest,写规范与 round-trip tests)。此前已有 plugins: {name: {version: ...}} 的需求字段不得被悄悄解释为可运行工件;若保留,就明确仅为“需求”,不用于隐式选择;建议后续一次性迁移到下面的显式扩展选择结构:
project:
name: research-demo
version: 0.1.0
dependencies:
quantum:
git: "https://github.com/EXAMPLE/marqdo-quantum.git"
rev: "<完整固定的 Git commit SHA>"
extensions:
plugins:
- from: "@quantum/adapter/plugin.yaml"
kernels: []
providers:
- from: "@quantum/adapter/provider.json"
这是新提议的 manifest 合同,基线版本尚不存在。from 值仅允许两种形式:相对项目目录的 ./path,以及显式 @alias/relative/path(alias 必须属于当前已锁定依赖闭包)。不得支持任意 HTTP URL、未固定 Git 分支、主机 PATH 中任意搜索、从 import 文本隐式发现扩展。每个 from 解析为包内普通文件,文件必须在所属包文件集/锁定的源码快照内;manifest/artifact 摘要都记录在新锁版本中,不能仅记录路径。
锁文件升级:当前 lock v3 是公开有序依赖图。若加入选定的扩展 manifest/artifact identity,升级为 lock v4,同时更新 lock spec、读写器、goldens、构建 fixture、离线验证和迁移文档;不允许 v3 中凭空塞入同名字段而仍声称 v3 兼容。对于不涉及扩展的旧 lock v3,可选择继续只读支持,或者给出确定的迁移命令;迁移结果必须显式写入新 v4,不实现隐藏的语言兼容模式。marqdo sync 可物化已锁定内容但不自动授权或执行其中二进制。
6.4 组合根配置优先级和安全规则
- 声明:
marqdo.yaml.extensions是项目明确启用的候选扩展来源;--plugin/--kernel/--provider是本次运行临时追加来源;两个来源若相同逻辑身份且摘要一致则幂等,否则拒绝冲突。 - 锁定:
sync/lock负责把可复现的来源、包 SHA、manifest 内容 SHA、目标工件 SHA 记录到 lock;运行只消费已经锁定的物化源,不调用网络下载。测试中的临时显式 CLI 路径如果不在 project lock,可作为本机开发/调试形式使用,但输出unlocked_extension标记;发布模式不接受未锁定扩展。 - 验证:
check使用静态可读 descriptor + lock identity;run在启动前重新核对所有实际工件,不能用check的旧哈希替代当前校验。 - 授权:
--allow-plugin,--allow-provider,--allow-foreign与文件/网络/进程等 Host grant 是独立权限;即便依赖包请求权限,Host 默认不授予。 - 执行:ABI Plugin、Kernel、Provider 使用各自的明确路径,不能让
Tool充当偷偷运行库代码的 shell 执行后门;Tool仍在独立 CLI 进程域。 - 失败:未解析 alias、未锁定依赖、摘要不匹配、无授权、缺当前平台工件均 fail-closed;不可自动退到最新版本或某个系统安装。
- 可观测:
inspect --extensions --json(为现有 inspect 增加 flag,不新建顶层命令)列出来源、类型、完整身份、选中工件、验证状态、授权状态;不泄漏密钥/环境变量。
6.5 与多版本依赖、相对路径、SDK 的关系
- 同一第三方包 v1/v2 可以在依赖图中同时存在,因为
ModuleId由 package instance + package-relative path 决定;但调用者导入必须显式选定 alias,不靠“最新”或搜索顺序。 - 插件的完整导出名在单个程序执行空间是全局唯一的;两个版本都导出
solver.add时,除非显式定义不同的对外 alias,否则拒绝。扩展 alias 功能若未实现,就以冲突错误交付本阶段,不实现悄悄加后缀。 - 工件在物理 cache 中移动不应改变逻辑身份;同摘要不同来源的信任处理与 lock 身份是独立概念,不能单凭 hash 判定 publisher。
- 第三方 SDK 可在其仓库使用已发布的 ABI header、Plugin SDK、Wire schema;不能通过直接修改
marqdo-cli/crates/...来提供扩展实现。 - 发行物必须声明支持平台矩阵;未知架构不是“试试 Linux 的 so”,而是明确拒绝。
6.6 PR-04 验收测试
PKG-01 同一项目通过固定 Git SHA 的 .mq.md 依赖调用成功;PKG-02 离线 cache 一致、无联网仍可运行;PKG-03 cache 移位不改 logical ModuleId;PKG-04 同名不同版本在不同 alias 下调用不混淆;PKG-05 未固定 Git rev 不允许;PKG-06 锁定工件被修改必拒绝;PKG-07 extensions 声明而无 grants 时不可执行 Provider/Plugin;PKG-08 CLI 与项目双重选中同摘要幂等、不同摘要冲突;PKG-09 扩展依赖的 @alias 无法逃离所属包范围;PKG-10 恶意 ../、symlink、非普通文件、超大 bundle 被拒绝;PKG-11 lock v3/v4 版本切换有确定错误或显式迁移;PKG-12 check 无插件初始化副作用。
7. PR-05:Capability Broker 与非流式资源操作的长期扩展边界
7.1 把“能声明能力”与“能执行能力”彻底分开
现有 KNOWN_CAPABILITIES 包含 fs.read/fs.write/net.request/process/clock/random/...,允许带命名空间的 vendor.*;但 Broker 实际 execute() 只实现了受控 fs.read。因此不得只在 KNOWN_CAPABILITIES 或 CapabilityBroker::decide 加一行就宣称新增服务已接通。
统一权限链必须满足:
extension manifest requires capability
└→ parser 只接收声明,校验标识合法
└→ CLI / operator 明确 grant + 有效范围
└→ CapabilityBroker 查受信任 Handler 是否安装
└→ 实际调用再核对 owner / grant / 作用域 / budget
└→ Handler 执行受控操作
└→ Audit { identity, effect, decision, duration, trace_id }
核心预置能力是有限的基础系统原语;Vendor 能力是有命名空间的申请,不能跳过 Broker 直接变成特权的宿主调用。第三方项目只修改 manifest 不意味着可在 Host 注册特权 Handler。
7.2 处理器注册模型(Rust Host 内部可扩,不再增加长 match)
为 marqdo-host 的 Broker 增加显式处理器目录。最小建议接口:
pub struct CapabilityRequest<'a> {
pub package_instance: &'a str,
pub capability: &'a str,
pub payload: &'a [u8],
pub trace_id: &'a str,
}
pub trait CapabilityHandler: Send {
fn name(&self) -> &str;
fn execute(&mut self, request: &CapabilityRequest<'_>,
policy: &EffectiveGrant,
budget: &mut ResourceBudget)
-> Result<Vec<u8>, CapabilityError>;
}
// Host/Broker 中注册,由受信任的组合根调用:
// register_capability_handler(Box<dyn CapabilityHandler>).
EffectiveGrant 与 ResourceBudget 在此为设计接口名,实施时应复用 Capabilities、现有时限/字节限制结构,而不是复制一套权限系统。Handler 注册必须拒绝同名、保留名前缀、未受信任来源以及声明协议不符。既有 fs.read 改为标准 Handler;其他核心能力可以逐步迁移,但没有真实执行处理的能力继续返回 capability.unavailable,不能只给空字节当“成功”。decide 不得把 vendor 能力字符串存在 allow-list 就当作 Handler 已安装;授权通过后仍需 Handler 存在才能执行。
7.3 第三方非流式 API 推荐怎样在 CLI 外完成?
第一优先级:在独立 .mq.md 库中使用既有 resource.open/read/write/close。 例如数据库查询、设备指令、量子线路提交可以将请求序列化成有限字节写入 Provider stream,再读回 Result;这是现阶段完全不用新增 HostOp 的扩展路径。请求/响应二进制协议由第三方库和 Provider 自己版本化,Host 只管 handle/budget/rights,不解释 SQL 或量子指令。
第二优先级:针对确实不可映射为 stream 的系统原语,可通过受控 resource.request 的 Operation Registry 追加可信操作。新增 OperationDescriptor { public_name, args_schema, result_schema, capability, handler_id, version } 与 BTreeMap<String, Handler>;核心 process.run、fs.*、regex.* 等可以逐步整理为内置 Handler,但这不是让任意 vendor.* 清单直接注入 Rust 回调。第三方仅用 CLI 的 Provider v2 stream 即可开发;需要直接注册 Operation Handler 的场景属于可信 Host embedder 能力,不在本阶段 --provider 对外暴露的 ABI 内。
不得承诺现有 Resource Provider ABI v1 已经能执行任意新 resource.request("vendor.op", args);实际上它只保证 open/read/write/close。若未来把 Operation 暴露给 ABI Worker,应另立版本化 ResourceOperation ABI v2,明确 wire、预算、效果、支持平台和迁移测试;不能在 v1 的 Worker 消息里悄悄塞一个 request 并要求所有现有实现兼容。
7.4 安全检查点(必须覆盖)
- 受控
fs.read依然受ProjectFs根路径限制、glob 和最大输出字节数限制;不能调用裸std::fs::read绕过策略。 - 时间、熵、进程、网络等能力分别有实际 Host 授权与执行路径时才可宣称支持;权限 Handler 的审计记录必须体现
denied/unavailable/granted,不能误把“允许声明”当“已执行”。 - Capability request payload 的 JSON/字节长度、嵌套深度、编码、错误码、响应上限受既有预算约束;无界缓冲、递归调用、异常退出必须可恢复。
- PluginHandle / ResourceHandle 由 Host/Runtime 签发,wire 输入不能凭
id字段重建高权限 handle;跨运行、伪造、释放后重用必须拒绝。 - 每次调用都绑定 owner package、已选择工件 digest、运行会话/trace,不能信任插件自报的 package 名和
capability字符串就越权。 - Worker 进程隔离并非 OS sandbox:恶意二进制仍可能直接访问其同用户 OS 权限。正式支持不可信 Provider 必须另行开发 strict L2,并完成真实系统调用负例后才开放;当前明确标
trusted worker。
7.5 必须有的 tests
CAP-01 仅声明 vendor 权限但未授权 → denied;CAP-02 授权但无 Handler → unavailable;CAP-03 有 Handler 但跨 package 冒名 → denied;CAP-04 注册同名 Handler → conflict;CAP-05 Handler 读超范围文件 → denied;CAP-06 返回超过预算 → resource limit;CAP-07 Worker 返回伪造 PluginHandle/ResourceHandle → rejected;CAP-08 卸载/关闭/新 run 后重放旧 handle → rejected;CAP-09 审计不含文件原文/密钥;CAP-10 resource 请求低层 open/read/write/close 性能不劣化到不可接受;CAP-11 默认 project 不得被标记为 OS strict;CAP-12 没有 Handler 的核心能力始终 unavailable 而非 silent OK。
8. PR-06:官方标准库函数绑定去魔法化,而不是让每个新库都改内核
8.1 现有特殊行为的边界
cli/src/loader.rs::program_uses_print 遍历整个 AST 检测 打印/print,然后载入 stdlib/io.mq.md,把 写值 指定成 print_override;runtime/interpreter.rs 对 打印/print 特判。为了在迁移期维持完整的 Unicode/复杂值格式化,这种 Compat-C 是合理过渡;但将其复制到其他高级函数会破坏扩展性。
8.2 最小替代方案:官方标准库公开别名描述符
- 保留受核心保护的公开名字
打印/print;不允许第三方抢占。 - 在官方 stdlib bundle 的版本化元数据中定义
PublicAlias { public_name, target_module, target_function, expected_signature },例如打印与print都指向std:io::写值。此元数据与stdlib.json的内容摘要一起封装、校验,并与CallableRegistry的核心预置描述符合并。不是运行时根据if name == "print"重定向。 CallableRegistry解析到官方PublicAlias时,Loader按需加载官方已验证io.mq.md并生成普通FunctionId绑定;Runtime只执行Marqdo Function目标,不对打印名称特殊处理。- 别名元数据只能来自官方已校验 stdlib bundle,不接受第三方伪造
core.*或std.*名称;通用第三方导入正常以 package alias 暴露,不能修改核心全局函数别名。 - 删除
program_uses_print/stmts_use_print/expr_uses_print及Program.print_override(在回归测试全部通过后);不保留--legacy-print或双调度。必要时以单独 ADR 记录打印语义从特殊覆盖到通用绑定的实现迁移,输出、权限和错误行为必须不变。 - 不重新引入 Host
Print操作;仍然通过 Marqdo 标准库format.显示、io.写值走resource.write(stdout),保持纯计算与 I/O 的界限。 - 只因某个公开别名被真实引用时才加载目标模块;无打印调用的程序启动成本、模块图、Analysis 不应增长。
8.3 对外部第三方库的影响
第三方 marqdo-ai、marqdo-quantum、marqdo-proof 不用添加官方标准库别名就能运行。它们通过 import 声明可调用函数,或者 plugin.yaml 声明加速入口。官方 bundle 的内部公开别名表仅用于语言标准 API 迁移;不是所有第三方必须申请核心名字的注册表。
8.4 PR-06 退出标准
至少运行现有打印全值类型测试、格式化 goldens、stdout/stderr 隔离、pure/project/strict 授权测试、--json 输出与 Trace goldens、缺 bundle 报错、未使用打印时不加载 io、两个不同包均可正常使用全局打印、与本阶段 Callable 冲突规则一致。打印 byte-for-byte 输出差异为阻塞;禁止以“新设计更合理”删除现行正常使用行为而不经 ADR 批准。
9. PR-07:View / Proof / Knowledge / Agent 等其他仓库只消费稳定边界
9.1 独立第三方仓库的合法依赖方式
marqdo-view:使用 marqdo check FILE --emit ANALYSIS.json 和 marqdo run FILE --trace-file TRACE.json,再以原 Markdown 源文档渲染;严禁把私有 AST/IR Rust 结构链接到 View 中。marqdo-proof:消费 Analysis、锚点/引用/函数符号、源码摘要,产生自己的证明义务和证明证书;证明结果不能直接改变 Runtime 权限。marqdo-knowledge:从普通 Markdown AST/source + Analysis 收集文档知识锚点,索引结果由自身管理。qdagent:根 SKILL/聊天 SKILL 等正常 .mq.md 文档调用外部算法模块与 Provider,不应要求 CLI 增加 agent Builtin 或专用 @agent mode。
9.2 公开协议稳定性规则
- CLI 的 Analysis、Trace 与版本化数据输出是正式的消费者边界。私有 IR(包括新
CallBindingTable)不要求跨发布稳定;Analysis 公开 schema、版本字段、Unit/Module identity、source span、源码 SHA、声明导出和 Call target 信息如已有字段不可悄悄改义。 - 如确实要对外暴露
resolved_call_target,新增Analysis v3或合法的向后兼容可选字段,并提供 v2→v3 迁移说明与 golden;不能把内部CallableId直接裸序列化到现有 Analysis v2 并假定消费者无感。 - Trace 的
call/return/branch/loop/host-effect有可关联来源标识,密钥、完整网络 payload、敏感 argv 默认不输出;运行时关闭 Trace 时,不能因构造 Trace 文本导致显著性能损失。 check --emit、inspect必须完全无执行副作用;view/proof/knowledge通过已注册 Tool 执行时也不能偷偷获得项目 grants。- Tool 的子进程如需运行项目,必须显式启动新一轮
marqdo run并重新按公开 CLI 合同获得授权;Tool 安装不等于运行权限。 - Unknown JSON fields 和 schema version 应按对应公共规范处理:版本不兼容拒绝,允许的额外字段忽略,不能把所有未知字段当语义指令。
9.3 第三方证明消费者验收(无需实现证明内核)
在外部 fixture 中实现一个不到 100 行的 Python/Go/任意语言消费者:仅用标准 JSON 库读取 check --emit 的 Analysis、列举函数及其源位置,并输出对某个 heading anchor 的确定性摘要。再用独立 Tool Protocol 安装到同一冻结 CLI:
marqdo tool install ./fixtures/tool-inspect/tool.json
marqdo inspect-ext --help
marqdo check examples/factorial.mq.md --emit /tmp/analysis.json
上面的 inspect-ext 为 fixture 中自行声明的 Tool command,非核心内置命令;调用 Analysis 的具体格式以当前 spec/analysis-v2.md 为准。完成标准为:独立 Tool 在无 Rust workspace 依赖情况下消费 Analysis;更新核心私有 IR 而不改 Analysis schema 后,consumer goldens 不变;插件缺失或未授予运行权限时,Tool 不会因为已安装就启动任意项目。
10. 外部仓库开发模板与可复制黑盒脚本
10.1 推荐第三方仓库目录(与 marqdo-cli 物理分离)
marqdo-extension-conformance/ # 独立 Git 仓库,不加入 marqdo-cli workspace
README.md
CONTRACT.md # 使用的 Marqdo/ABI/Wire 版本
.github/workflows/conformance.yml
pure-lib/
marqdo.yaml
index.mq.md
consumer/
marqdo.yaml
index.mq.md
plugin/
plugin.yaml
solver.c
build.sh
kernel/
kernel.json
mocklang # 独立可执行程序
demo.mq.md
provider/
provider.json
sensor.c
build.sh
demo.mq.md
tool/
tool.json
inspect_ext.py
tests/
verify_frozen_cli.py
test_positive.py
test_negative.py
evidence/
binary-sha256.txt
results.json
真实业务仓库 marqdo-quantum / marqdo-ai 可以只拥有其中一类或多类扩展,而不是每个仓库都必须复制全部结构。pure-lib 的例子:
pure-lib/marqdo.yaml:
project:
name: example-math
version: 0.1.0
pure-lib/index.mq.md:
# @exec 示例数学库
## 加倍
`params(x: Int)`
`return x * 2`
consumer/index.mq.md(消费者通过显式 alias 导入外部依赖):
---
import:
m: "@math"
---
## @exec main
`return m.加倍(21)`
consumer/marqdo.yaml 示例(本地构建时使用 path;完成测试后替换为已提交的固定 Git revision):
project:
name: example-consumer
version: 0.1.0
dependencies:
math:
path: "./vendor/pure-lib"
上述本地 path fixture 要先将外部库的已固定版本快照复制到 consumer/vendor/pure-lib,它只是本地依赖功能测试。真正的跨仓库解耦黑盒必须把第三方 pure-lib 独立提交为 Git repo,并使用经允许的 git: 源形式和完整固定 SHA,不能靠把外部仓库源码直接纳入 CLI Workspace;任何 ../ 逃出项目根的路径都应保持拒绝。
10.2 冻结 CLI 验收:不能在安装第三方扩展后重编译核心
在 marqdo-cli 根目录先生成一个独立的候选发行二进制;构建出来后所有外部扩展脚本只接受该二进制的绝对路径,禁止 cargo run、cargo build -p cli 或把第三方源码复制入 crates/:
set -euo pipefail
cargo build --release -p marqdo-cli
CLI="$(realpath target/release/marqdo)"
sha256sum "$CLI" > /tmp/marqdo-frozen.sha256
# 此后转到完全独立的外部仓库工作目录
cd /path/to/marqdo-extension-conformance
export MARQDO_BIN="$CLI"
python3 tests/test_positive.py
python3 tests/test_negative.py
sha256sum -c /tmp/marqdo-frozen.sha256
以上只是执行器命令草案:开发者必须在对应 OS/包中根据真实 Cargo.toml 的 binary 名称验证 cargo build --release -p marqdo-cli 可用;如果当前 Cargo package 名不同,使用实际 Cargo package 名,但不得改变“冻结并校验同一二进制”的要求。外部套件必须记录其 Git SHA、CLI SHA、Host target、插件 Provider SHA、每条测试结果、错误码与最小可复现命令。每个文件由 fixture 自己构建,不直接消费核心源码目录中的测试 fixture。
10.3 运行侧四类典型命令
# 1. 普通外部 .mq.md 包:
marqdo sync # 物化 pinned Git dependencies
marqdo check consumer/index.mq.md
marqdo run consumer/index.mq.md
# 2. Callable Plugin:沿用现有支持的 flags:
marqdo run plugin/demo.mq.md \
--plugin plugin/plugin.yaml --allow-plugin demo.solver
# 3. Foreign Kernel:沿用现有注册方式:
marqdo run kernel/demo.mq.md \
--kernel kernel/kernel.json --allow-foreign
# 4. Resource Provider:PR-03 完成之后的新 flags:
marqdo run provider/demo.mq.md \
--provider provider/provider.json --allow-provider demo.sensor
这里 --provider 和 --allow-provider 当前尚不存在;marqdo.sync 的运行目录必须拥有正确的 project manifest。命令是预期验收契约,开发者须随本 RFC 一并实现;不应误把示例作为已验证的现行命令。
10.4 不依赖网络的 Git 固定版本 fixture
外部测试可在临时目录中:git init 一个纯 Marqdo 库,git -c user.name=Fixture -c user.email=fixture@example.invalid commit,读取完整 SHA,生成消费者的 marqdo.yaml 用 git: file://... 且 rev 固定 SHA,运行 marqdo lock / sync。随后删除网络访问和源工作目录,仅保留已校验缓存,再运行 check/run;证明包源与运行时分离。在 Windows 使用平台合法的 file URL 或本地 Git 路径形式,不能假定 Unix file:///tmp 永远成立。若当前 Git resolver 限制 file://,先加入明确可控的测试源适配或使用完全离线的本地 bare Git repo,并为新的 SourceResolver 写安全 ADR,而不是临时启用未经审计的任意 URL。
10.5 外部生态必须提供的 CONTRACT.md
逐项列出:需要的 Marqdo Core 版本范围、语言语义 RFC、ABI/Wire/Analysis/Trace 版本(只列实际使用的)、选用的 target triples、manifest/schema 版本、外部依赖 SHA、如何计算工件 hash、是否需要 Host grants、默认运行模式与对未知平台/缺权限的行为。不要写“最新版本均兼容”,不要隐式依赖系统已安装 Node/Python/USB 驱动。需要的运行时通过 Kernel/Provider 的 manifest 明确声明,缺环境时 fail-closed。
11. PR-08:回归、CI、性能、安全与发布硬门禁
11.1 测试分层:任何红灯都不能以“文档解释”掩盖
L0 单元测试:Registry 重名、优先级、不同模块作用域、签名绑定、Provider v2 parser、路径/target/hash、Capability Handler 缺失、句柄生命周期。L1 内部集成:check/run/inspect 从同一个 PreparedProgram 走,Host Worker/ABI,持久化 lock。L2 黑盒命令:通过真实 CARGO_BIN_EXE_marqdo 执行独立 fixture,核对退出码、stdout、stderr/JSON diagnostics 与无副作用。L3 外部仓库:冻结发行二进制后,单独 git init 外部库和插件,构建扩展并成功调用,验证 CLI SHA 不变。L4 平台/安全:在真实 Linux/macOS/Windows 上按声明矩阵验证;Linux strict L1 继续 fail-closed,独立 OS VM lane 不能用容器 smoke 取代。
新增测试位置建议:
crates/cli/tests/callable_resolution.rs
crates/cli/tests/provider_cli.rs
crates/cli/tests/extension_selection.rs
crates/cli/tests/stdlib_alias_routing.rs
crates/cli/tests/external_repo_conformance.rs
crates/marqdo-host/tests/capability_handlers.rs
crates/marqdo-host/tests/provider_worker_v2.rs
crates/marqdo-frontend/src/calls.rs (单元 fixture)
tests/conformance/semantics/* (统一语法 fixture / golden)
tests/consumers/* (公开协议消费者)
tools/ci/verify_extension_contracts.py (冻结二进制 E2E)
现有 architecture_boundaries.rs 只检查目录依赖和部分源码形状,不能替代真实黑盒;但应该新增“禁止核心硬编码第三方名字”的结构测试。不要以 rg 命中个数替代行为测试。
11.2 编译与静态测试(每个提交都运行)
set -euo pipefail
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
cargo build --release --locked -p marqdo-cli
cargo test -p marqdo-cli --test callable_resolution --locked
cargo test -p marqdo-cli --test provider_cli --locked
cargo test -p marqdo-cli --test extension_selection --locked
cargo test -p marqdo-cli --test external_repo_conformance --locked
每个新测试文件必须在加入后才启用其对应 cargo test --test ... 命令,PR-00 阶段可先生成空的可编译脚手架,但不得以空测试声称通过。完成 PR-08 时这些文件都必须存在,且每个包含正反例。对于 platform-specific fixture 用 #[cfg] 显式标记,CI 结果需区分 PASS、UNSUPPORTED、SKIPPED;被跳过的平台不能算 PASS。
11.3 不可替代的黑盒证据清单
每次 release candidate 必须自动生成 docs/evidence/extension/<SHA>/manifest.json,至少包含:
{
"schema": "marqdo.extension-evidence",
"schema_version": 1,
"tested_sha": "<40-hex-source-SHA>",
"cli_binary_sha256": "<64-hex>",
"fixture_repo_sha": "<40-hex>",
"os": "linux",
"arch": "x86_64",
"results": {
"callable_registry": "PASS",
"plugin_worker": "PASS",
"foreign_kernel": "PASS",
"resource_provider_cli": "PASS",
"package_pinned_git": "PASS",
"tool_analysis_consumer": "PASS",
"negative_security": "PASS"
},
"commands": ["cargo test --workspace --locked"],
"failures": [],
"unverified": []
}
占位符由 CI 实际数据替换;不允许人工手填 PASS。tested_sha 与当前 release SHA 不一致时整份证据无效。单独存在单元测试结果而没有冻结 CLI SHA 的套件也不能认定外部仓库解耦完成。仓库必须为这个 JSON 提供 JSON schema 和校验脚本,并将它挂到既有 tools/ci/release_evidence.py 或等价的主发布门禁,不能造独立“绿色但不参与发布”的报告。
11.4 性能基线与回归判定
该架构改动涉及每次函数调用的解析路径、启动时的静态绑定和 Provider 工件校验。要求测量四类基线:
| Workload | 测量 | 要求 |
|---|---|---|
| 纯递归/循环/函数调用 | 运行 CPU 时间 / calls/s | 不因每次调用重新扫描全局 Registry 而退化;绑定查找应为 O(1) 或 O(log n) |
| 无外部扩展的 hello/简单函数 | 冷启动中位时间、最大 RSS | 不应强制装载插件或 Provider,不因无用模块导入显著增大成本 |
| 有 1、10、100 个静态 descriptor 的项目 | check 耗时、峰值内存、重复导入成本 |
扩展装载至多线性于描述符数或有合理索引,不得每次调用重复扫描全量清单 |
Resource Worker read/write 往返 |
p50/p95 latency、吞吐与峰值缓冲 | 不复制多层无界 JSON,不向正常纯计算路径引入 Worker 开销 |
采用仓库现有 tools/perf/bench.py 的固定节点方式:同一 OS/arch、Rust 版本、CPU governor、--release --locked、构建配置与输入;暖机后各测不少于 20 次,记录 median/p95、测量波动、前后 SHA。默认回归门限:纯计算与无扩展冷启动的 median 不得比基线慢超过 10%,且差异应大于固定节点测量抖动;如果超出,必须提供 flamegraph/基准分析、优化或经维护者批准的独立 performance ADR。跨平台 CI runner 的绝对耗时不可直接互相比较;容器/QEMU 只能 smoke,不作为 MEASURED 性能门禁。增加 Provider/Plugin 时的必要启动成本可单独统计,不应归责于无扩展路径。
11.5 平台与 strict 安全矩阵
| Lane | 必须跑的任务 | 允许声明 |
|---|---|---|
| Linux native x86_64 | workspace fmt/clippy/test,Plugin Worker,Foreign mock,Provider CLI v2、Tool/Package 外部仓库 | 这些全部真实 PASS 时可声明 supported |
| macOS native | Rust 构建/运行、真实目标 dylib、Worker、Foreign、Plugin/Provider 目标工件 | 只有实跑对应 fixture 才声明该扩展 supported |
| Windows native | Rust 构建/测试、纯 .mq.md Package、Tool/Foreign 已支持部分;Native/Worker C ABI 需目标实现 |
尚未实现的 ABI 明确 UNSUPPORTED,不得由 Linux PASS 代替 |
| Linux strict disposable VM | 原 L1 pure/Math/stdout 正例,Foreign/Plugin/Provider 否定用例,真实隔离证据 | L1 PASS,不宣称 L2 |
| Fixed Linux perf node | tools/perf 固定输入与前后 SHA 对比 |
MEASURED、WARN 或 UNVERIFIED,绝不把 SMOKE 当性能结论 |
strict VM 需符合仓库 docs/security-vm.md 对宿主内核、Bubblewrap、用户、namespace、真实 OS 隔离的条件。不能用 sudo 下“随意拥有更多权限”的运行结果证明拒绝路径;不能用 CI 运行器本身隔离的事实替代 Marqdo strict supervisor。对第三方 Worker 的 --mode strict 必须继续拒绝,直到另有 strict L2 RFC 和独立破坏性安全测试。
11.6 发布条件(必须全部满足)
- PR-00~08 所有强制测试、正例与负例 PASS;所有公共 CLI 选项有
--help、spec、fixture 和错误码文档。 - 外部仓库套件冻结 CLI binary SHA,构建新
.mq.md库、新 plugin、新 kernel、新 provider、新 tool 全部无需 CLI 源码修改且无重编译;对真实未支持平台有明确 unsupported。 check/run/inspect唯一解析语义闭合,未知调用在静态阶段拒绝,动态 FunctionRef 不可逃逸为 PluginInvoke。- Plugin/Provider manifests、锁文件与 Worker ABI 均有版本与摘要校验;Native trust 与 Worker 信任边界真实表述。
- 现有官方 stdlib、打印、内存、资源、HTTP、JSON/CSV、Package、Tool、Analysis/Trace goldens 不退化;禁止修改 golden 使错误通过而无审查记录。
docs/STATUS.md、docs/architecture/CURRENT.md、COMPATIBILITY.md、README.md、spec/*与新增 ADR 同步更新;发布报告指向同 SHA 的执行证据。- 既有仓库
docs/releasing.md的主发布门禁(包括独立 G-C 和 G4)仍然生效。本 RFC 的扩展测试是新增的必要条件,绝不替代任何安全/平台门禁。 - 未满足时设置
DO NOT RELEASE;如只是某平台扩展未实现,要清楚标平台不支持并使运行时拒绝,而不是悄悄把未验证功能宣称跨平台可用。版本号、tag、发布资产必须经仓库所有者批准,开发计划本身不构成授权。
12. 全仓库文档、示例、测试和协议迁移清单
12.1 必须新建的文件
| 路径 | 内容 | 所属 PR |
|---|---|---|
docs/architecture/RFC-EXT-0001.md |
本文完整规范;状态 Proposed → Implemented 需同 SHA 证据 | PR-00 / PR-08 |
docs/adr/0054-callable-binding-single-source.md |
已绑定 CallableId 的静态/运行一致性、冲突策略 | PR-01 |
docs/adr/0055-resource-provider-cli-v2.md |
Provider v2 清单、CLI/Worker 生命周期、信任边界 | PR-03 |
docs/adr/0056-extension-selection-locking.md |
ExtensionSelection、lock v4、显式 activation 与授权 | PR-04 |
docs/adr/0057-capability-handler-registration.md |
处理器目录、权限链、不支持服务的失败语义 | PR-05 |
docs/adr/0058-stdlib-public-alias.md |
官方 bundle 公共函数 alias、打印迁移与权威边界 | PR-06 |
spec/resource-provider-v2.md |
JSON schema、target/sha256/transport/rights、Worker 用法 | PR-03 |
spec/callable-resolution.md |
本 RFC §4.3 的命名解析/绑定冲突矩阵及诊断 | PR-01 |
spec/extension-selection.md |
marqdo.yaml.extensions、锁文件与 CLI 选择优先级 |
PR-04 |
tests/consumers/extension-schema-consumer.* |
不链接私有 IR 的独立消费 fixture | PR-07 |
tools/ci/verify_extension_contracts.py |
冻结 CLI SHA、外部黑盒及 evidence 校验 | PR-07 |
docs/evidence/extension/<SHA>/manifest.json |
自动生成的本 SHA 外部生态证据 | PR-08 |
文件编号冲突规则:上述 ADR 编号仅为建议。创建时若仓库已有 0054/0055 等编号,取下一个未占用编号并修改全部引用;不覆盖别人的 ADR。docs/architecture/CURRENT.md 继续作为唯一当前架构总览,本 RFC 是开发计划,不是第二份当前状态文档。
12.2 必须修改并重新验证的现有文件
| 文件范围 | 需要做什么 | 为什么不能省 |
|---|---|---|
README.md |
新增明确的五类扩展示例、--provider/--allow-provider、明确 strict 限制 |
新使用者无需看历史 RFC 才知道怎么接扩展 |
COMPATIBILITY.md |
Plugin ABI/Provider schema/Wire/Analysis/Trace/Lock 等版本和支持 OS 矩阵 | 避免把 Host 接口存在当作 CLI 跨平台支持 |
CHANGELOG.md |
描述 CLI Provider、函数绑定、lock 变动及破坏性修正 | 用户可识别迁移成本 |
docs/STATUS.md |
按新 SHA 填 IMPLEMENTED/TESTED/UNVERIFIED/UNSUPPORTED,不复制历史值 | 状态应与证据一一对应 |
docs/architecture/CURRENT.md |
新组合根、BoundCallable、Provider CLI、操作权限层、仍保留的语义封闭边界 | 防止后人重新造第二套架构 |
docs/ci.md / docs/releasing.md |
外部仓库证据、provider worker 发行、原 G3/G4 不变 | 扩展通过不能替代发布安全证据 |
spec/plugin-abi.md |
显式说明静态/运行 descriptor 一致、参数位置、Worker parity、错误 | ABI v1 不可静默改义 |
spec/evaluation.md / spec/security.md |
调用目标、Provider 授权、句柄、strict L1 边界 | 让结果与权限语义可测试 |
spec/value-wire.md |
明确是否可传某类 handle;不得把插件输出变成权限凭据 | 避免跨进程伪造句柄 |
spec/analysis-v2.md / spec/trace-v2.md |
仅在确有字段变更时更新;必要时新开 v3 | 外部消费者合同稳定 |
stdlib/stdlib.json / tools/pack-stdlib.py |
若新增 public alias metadata,将它计入官方包摘要与验证 | 避免元数据被替换而运行了别的函数 |
examples/ |
新增外部 Plugin/Provider/Foreign/Package 示例;所有 .mq.md 使用现行语法 |
示例必须真实可运行 |
crates/cli/tests/*、crates/marqdo-host/tests/* |
新正反例、目标工件跨平台 fixture、专用黑盒 | 不接受只改 README 而没有测试 |
.github/workflows/ci.yml、security-linux.yml、performance-linux.yml |
扩展生态门禁、平台区分、固定性能节点、strict 不放宽 | 证据必须在真正的 runner 上产生 |
12.3 迁移约束
- 语言版本不分叉:仍是统一 RFC-LANG-0002;所有新增
.mq.mdfixture/stdlib/README 都遵循该语法;不得为了兼容老**/*/列表控制映射添加新的编译分支。 - 内部允许破坏,外部必须版本化:
CallableRegistry、IR 私有绑定、CLI CompositionRoot 可以破坏;Plugin ABI v1、Analysis/Trace v2、Provider v1、Lock v3 涉及公开消费时必须明确新版本或兼容范围。 - 整个 README/文档同步迁移:如果本次更改公开命令、函数解析冲突规则、Provider schema,必须批量搜索所有相应词条和示例,对涉及的 md/fixture/JSON goldens 同 PR 修改;保留历史计划文件时加
Historical说明,不能让读者误认是当前实现。 - 测试不得偷偷调整 golden:旧 goldens 改动须附差异表,说明预期语义变化、理由、对应 ADR;输出/诊断变更先审后改。
- 构建产物不进入源码:Provider/Plugin .so/.dylib/.dll 由 fixture 或发行构建产生;源码里只存示例、manifest 模板及真实测试脚本,不提交本机私有二进制或密钥。
13. PR Review Checklist(逐个 PR 强制填写)
每个 PR 描述必须回答并给证据路径:
- 当前
git rev-parse HEAD是多少,和本 RFC 基线相比哪些源代码事实已变化? - 这次新增的能力属于
.mq.md包、Callable Plugin、Foreign Kernel、Resource Provider、Tool,还是需要另立语言 RFC? - 是否可以仅更改扩展仓库实现?如果不可以,是缺少哪个稳定基础原语/版本化协议,而不是哪个业务函数还没写进 Core?
- 有没有新增
BUILTINS、HostOp、resource_request()的业务分支?如果有,提供不能通过现有.mq.md或 Provider 实现的证明、ADR 与替代方案比较。 check是否从不执行第三方插件/Worker/Foreign?run是否使用同一绑定结果?- 所有新 public names 是否有 owner、signature、digest、version、权限说明以及命名冲突负例?
pure/project/strict的差异是否测试?Worker 是否被错误描述为 OS sandbox?- 非授权、超时、崩溃、重复注册、工件被篡改、版本不匹配、错误目标平台是否 fail-closed?
- 是不是保留真实官方 stdlib、Analysis/Trace、Package、Tool 的正常行为并执行 goldens?
- 能否用冻结 CLI + 独立 Git repo 做一次无需改 Core 的功能测试?
- 是否更新
README、STATUS、CURRENT、COMPATIBILITY、spec/ADR、CI evidence? - CI 安全/性能/平台证据是否与当前 SHA 相同?有没有跳过却宣称通过的 lane?
14. 重要的设计否决事项(防止后续开发者偷懒)
以下提交一律拒绝:
- 以“扩展语义”为由让第三方覆盖
@exec/@knowledge:这会使同一 Markdown 文档在不同扩展环境下有不同执行含义,破坏可验证性。 - 为一个新函数增加 3 个
match分支:比如为quantum.hadamard同时改 frontend、runtime 和 host。普通算法通过.mq.md;性能加速走 Plugin;设备 I/O 走 Provider。 - 让
check真的加载或运行插件:哪怕只是探测导出签名,也违反静态检查的安全与可重复性。 - 根据 runtime 能否加载再改变静态符号解析:未知函数不能在全无插件时落入“试执行”路径。
- 在
run合成不存在的插件签名:不能用空参数签名、泛化effects=[host]掩盖 manifest/runtime 不一致。 - 把
--allow-provider视为可信任二进制授权:Operator grant 允许资源操作,不能把未经 OS 隔离的 Worker 描述为安全的第三方代码环境。 - 把
provider.json v1伪装为完整性锁定:v1 没有新 schema 中的工件 hash,需要升级为 v2 或显式可信本地 API。 - 把 Tool、Foreign、Plugin、Provider 统一进无约束 shell 命令:他们的生命周期、值模型、权限与故障边界不同。
- 偷偷修改
marqdo.lock的旧版本含义:必须 bump schema 且写清迁移;不得无锁自动下载“最新”扩展。 - 为标准库每个高级函数复制
print_override模式:必须实现一次标准函数公开别名绑定,普通三方函数仍走 import。 - 测试夹带假路径、假 hash、无效 YAML 而声称通过:示例里的
<占位符>必须由脚本真实填充,输出依据当前真实 CLI 的退出码断言。 - 借一套“平台抽象层”重新拆分很多 crate:在已存在的 workspace 上小步重构,不重复建立第二套 IR、runtime、plugin SDK。
- 声称远端 green 但没有确切 SHA/runner 证据:安全与性能门禁不能用本机 smoke 或另一个提交的 PASS 代替。
15. 故障处理、回滚与阶段退出准则
15.1 开发中发现本 RFC 设计不适配真实源码时
遵循以下顺序:复现;最小 fixture;确认现行规范;选用最少新抽象的修复路径;更新对应 ADR(尤其公共版本);增加负例;重新运行本阶段与全仓测试;更新 evidence。不可自行发明一个“legacy”开关;不可为了满足示例去放宽 OS 权限或弱化 manifest 校验。
15.2 对已经合并的每个 PR 的稳定性要求
PR-01合并后,即使 PR-02 未完成,也不允许删除 Registry 或让旧解析结果和新结果并存且对外随机采用;实现期间如需要过渡,必须显式测试新旧结果一致,合并 PR-02 时删除过渡分支。PR-03合并后,Provider CLI v2 无法运行/授权的情况必须以正确错误码失败,不保留回退 Trusted Native 路径。PR-04合并后,marqdo.lock的 version/identity 不得静默回退;用户必须可以定位到实际使用的 artifact SHA。PR-06合并后,旧print_override代码应被移除,不保留两条运行路径。- 外部 consumer 的公开协议测试不能链接私有 IR 以绕开版本兼容问题。
15.3 关键成功/失败判定
阶段 P0 成功:PR-00~03 全部通过;第三方 .mq.md/Plugin/Kernel/ResourceProvider 可以在冻结二进制上独立提供;Callable 前后端唯一解析;受控 Provider 使用 CLI 且失败安全。此时可宣布“核心第三方执行扩展闭环(project 模式、支持平台)”;仍不得宣布 strict L2 或自动扩展生态完成。
全部完成:PR-00~08 完成且本 RFC §11 发布门禁通过;官方 bundle 的高级函数迁移无硬编码蔓延;锁定的扩展集合可重复装载;外部 View/Proof/Knowledge 工具只消费公开合同;Linux/macOS/Windows 的声明矩阵与证据一致;无未解释的 xfail、无红色 mandatory lane。
必须保持的发布状态:任何失效的安全/平台/performance gate,或者某项“已支持”的扩展缺外部独立仓库验收,状态为 DO NOT RELEASE。未支持的平台可以真实标 UNSUPPORTED,但这不等于已满足跨平台发布目标;发布决策以仓库 docs/releasing.md 更严格要求为准。发布前需要 Owner 对标签与资产进行单独批准。
16. 补充规范:错误码、装载顺序、扩展状态机与代码审查中的歧义消除
18.1 对外错误协议(本阶段冻结新增错误的名称)
新错误码采用 ext. 前缀;已有成熟的 symbol.unknown、permission.denied、kernel.unavailable、resource.unsupported 等沿用,不为同一事件制造两个不兼容错误码。新增建议的规范性错误:
| 新错误码 | 产生阶段 | 精确触发条件 |
|---|---|---|
ext.duplicate_callable |
prepare | 同一可见作用域的完整静态导出名冲突 |
ext.import_namespace_conflict |
prepare | 导入别名与 core/插件 namespace 冲突 |
ext.plugin_binding_mismatch |
run 初始化 | 已加载 Plugin 的导出名/签名/owner/工件摘要与静态声明不完全一致 |
ext.duplicate_provider_kind |
run 初始化 | 两个 Provider 试图注册同一非保留 kind |
ext.unsupported_provider_schema |
manifest 读取 | v1/未来版本传给只接受 v2 的 CLI Provider 入口 |
ext.no_matching_artifact |
manifest 校验 | 目标三元组找不到对应 artifact |
ext.artifact_integrity |
manifest 校验 | sha256 不符合、路径逃逸、非普通文件或不允许的 symlink |
ext.worker_unavailable |
run 初始化 | 匹配当前发布目标的 helper 不存在或无法启动 |
ext.platform_unsupported |
run 初始化 | 显式不支持当前平台对应的 Provider/Worker transport |
ext.extension_lock_mismatch |
prepare/run | 依赖/manifest/artifact 的已锁定身份与实际文件不一致 |
ext.capability_handler_unavailable |
Host effect | 声明且获授权的能力无可信执行 Handler;如已有 capability.unavailable,以其为 wire 公共码并将本行作为内部类型别名,禁止在同版本出现两种对外码 |
诊断内容:每个错误至少具有 code、人类可读 message、必要时 module_id / span / manifest_path、最少一个可执行修复提示;不得把密钥、插件私有二进制内存、完整敏感请求体输出为诊断。--json 只输出一个可解析 JSON document,程序 stdout/stderr 与 CLI 诊断保持既有约定。CLI 代码要集中复用 emit_error / RuntimeError,不散落 println! 风格新错误。
退出码建议:显式的 manifest/CLI 选项错误返回 2;编译/加载/运行失败返回 1;成功返回 0;如与仓库现有某命令公开规范冲突,应保持现行语义并在对应命令的 spec 中明确列出,不要同一错误在 run/check 间无原因变化。结构化错误码优先于从 stderr 字符串判断错误种类。对跨平台文件不存在等 OS 细节,错误码保持一致,message 可以提供平台补充说明。
18.2 唯一装载时序(关键代码不得颠倒)
T0 解析 CLI 参数与项目路径、确定 mode;纯模式/strict 先对扩展授权做 preflight
T1 读取 marqdo.yaml、锁文件、依赖图、Markdown 源码(不执行)
T2 读取 Plugin/Kernel/Provider 的描述符,解析 Source/ABI/Wire 版本(不执行)
T3 按包实例、完整导出名、namespace、kind 检查重复和冲突(不执行)
T4 由唯一 CallableRegistry 完成所有静态 call binding 和诊断(不执行)
T5 生成 PreparedProgram;check/inspect/Analysis 在此终止并写诊断/投影
T6 run/call 检查选定工件、平台、路径、完整性、权限声明与有效 grants
T7 组装 Host,启动被明确选择且已授权的 Worker/Kernel adapter
T8 精确比对 Plugin 动态 exports 与 T2 静态 descriptors
T9 进入 Runtime,按已绑定 CallableId 调用;每次真实资源效果都再次检查 grants
T10 正常/异常/超时退出时关闭句柄、终止 Worker、写完整审计/Trace 与退出码
T2 的 Kernel descriptor 读取可以发生在 check,但不得探测/启动 Kernel,check 也不必须为了检查纯 .mq.md 文档而要求本机安装第三方可执行程序。若 check 被显式传入扩展描述符,可验证声明及可见性;真正的可执行工件校验允许移到 T6。T7 启动 Worker 属于执行准备动作,不等于项目 .mq.md 主函数已经执行;但任何未知或未获授权的二进制不得在 T7 启动。
18.3 生命周期与失败传播状态机
UNDECLARED ──(显式声明)──> DECLARED ──(校验签名/版本)──> RESOLVED
│ │ │
└──unknown──> ERROR └──invalid──> ERROR └──hash/collision──> ERROR
│
(run + grants + artifact)
▼
ACTIVATED
/ \
INVOKED ERROR
│
CLOSED/EXITED
只有 RESOLVED 能出现在 check 的静态输出;ACTIVATED 之后必须有实际授权;INVOKED 前不得修改静态 Callable 目标;ERROR 不自动重新选择其他实现。资源句柄应绑定 run id + provider id + token/generation;Worker 中断后该 provider 的未关闭句柄全部失效。二次关闭/释放后重用的行为按当前 Resource API 规范返回确定错误或 Result 失败,而不是 Host panic。资源读写的上界必须有预算;read 返回的 count 不能超过请求的 max_bytes。
18.4 修改边界精确定位表(开发者逐文件检查)
| 文件 | 允许/期望的最小改动 | 明确禁止 |
|---|---|---|
crates/marqdo-ir/src/callable.rs |
Registry API、owner+digest 的身份及冲突检测 | 使用未锁定物理路径当唯一 ID |
crates/marqdo-ir/src/lib.rs |
增内部 CallBindingTable/Program 绑定存储 | 无版本地改变 Analysis v2 wire |
crates/marqdo-frontend/src/calls.rs |
单入口 bind_program_calls 读取 registry |
再次按 Builtin/Plugin 各自写独立优先级 |
crates/cli/src/loader.rs |
load 与 finalize 分离、stdlib alias 的按需加载 |
打印以外再加 program_uses_xxx |
crates/cli/src/commands/check.rs |
调用共享 prepare,静态检查插件 export |
加载 .so/.dll / spawn 子进程检查签名 |
crates/cli/src/commands/run.rs |
共享 prepare、reconcile、统一 Host 装配 |
补造 params=[]、按名字猜运行入口 |
crates/marqdo-runtime/src/interpreter.rs |
按 BoundCallable ID 唯一 dispatch | if external_callables.is_empty() fallback |
crates/marqdo-runtime/src/builtins_impl.rs |
必要内核基础计算、现有 Builtin | 加 quantum.*、ai.* 业务分支 |
crates/marqdo-host/src/host.rs |
统一操作/权限/audit,不改 Resource handle owner | 未授权执行插件功能 |
crates/marqdo-host/src/host/providers.rs |
复用现有 provider table + 校验 | 重新造第二套 provider 名字解析 |
crates/marqdo-host/src/host/resource_ops.rs |
现有内置 endpoint 和新 kind 的 registry fallback | 每个第三方 kind 再写 match arm |
crates/marqdo-host/src/capability.rs |
受信 Handler、真实执行预算与审计 | 用字符串 allow-list 代替真实 Handler |
crates/cli/src/main.rs |
参数声明、--provider/--allow-provider |
增加 marqdo quantum 等业务顶层命令 |
crates/cli/src/commands/sandbox.rs |
现有 capability 构造和 strict preflight 新字段 | 以安装成功绕开 grants |
crates/marqdo-package/src/lib.rs |
显式 extension source + lock identity 版本 | 自动取某分支最新提交 |
crates/marqdo-foreign/src/lib.rs |
继续用 KernelRegistry 查询 | 为 R/Julia 再 hardcode 执行路径 |
crates/marqdo-plugin-abi/src/manifest.rs |
ABI v1 清单的已定字段及严格校验 | 为 Provider v2 随意复用同名不同义字段 |
stdlib/ |
业务算法、通用格式/数据/资源编排 | 通过私有 Rust Hook 获取 OS 超权限 |
18.5 负责人实际操作的验收判定速查
| 用户想做的新事 | 应选的扩展方式 | 如果必须改 CLI,应如何处置 |
|---|---|---|
| 新 AI 模型提供商 / OpenAI-compatible API | 独立 .mq.md 网络库(TLS/HTTP),外部密钥从受控 env/配置能力获取 |
缺底层 TLS/stream/权限原语时才改 Host,并写基础协议 ADR |
| 新量子算法/变分线路生成 | .mq.md 可调用算法函数 |
计算原语不足时先证明最小 core necessity,不硬编码算法名 |
| 接入量子硬件 SDK | Callable Plugin 或 Resource Provider | 只可能补通用 ABI/Provider 支持,不加 quantum 特例 |
| 新数据库驱动 | Provider stream + .mq.md 查询/编码 API |
不改 parser / HostOp,仅在 Provider 协议真缺能力时升版本 |
| 新语言 R/Julia 执行 | 新 kernel.json + 已支持 wire 的外语程序 |
不修改 SUPPORTED_LANGUAGES 分支,仅修通用 Registry bug |
| 新的 Proof/Knowledge/View | CLI Tool + Analysis/Trace/源文档 | 公共投影缺确切证据字段才版本化扩充 Analysis,而非改语言执行语义 |
新的 @agent 执行关键字 |
不允许第三方修改 @exec 规则;改用固定语义中的库调用 + 惰性元数据 |
如确有新语言构造,另立语言 RFC,全面迁移测试后发布 |
| 新基本数值类型、原子并发或 GPU 原生指令 | 正式核心语义/后端 RFC | 这类变更不在“无核心变动”的扩展保证中 |
验收公式(文字约束,不是数学证明):外部新功能成功 = 已存在的语言语义 + 版本化的公开扩展合同 + 显式加载与授权 + 可复现实现身份 + 黑盒正反测试。任何新增扩展若靠“修改 Core 的业务分支”才能成功,必须回到上述边界重新判定,而不是把新增内核分支作为本 RFC 的完成证据。
17. 开发者执行指令(可以直接复制到新开发任务中)
你正在
cflmy/marqdo-cli进行可扩展性闭环开发。以当前仓库master最新 SHA 为准核验本 RFC §2 的源码事实;禁止猜测代码状态。严格按 PR-00~08 的顺序或允许的并行依赖实施。保持 RFC-LANG-0002 的单一 Markdown 语义,第三方不得改变@exec/@knowledge。先修唯一 Callable 解析、移除未知插件 fallback 和运行时空签名合成,再贯通 CLI Resource Provider,再做可锁定扩展选择、权限 Handler、官方 stdlib alias、独立消费者与发布门禁。所有功能必须带编译/运行一致性测试、负面权限与版本测试、独立仓库冻结 CLI 二进制 black-box 验收。不要新增业务 Builtin/HostOp,不要引入第二套插件架构或兼容旧语言 mapper。每个 PR 交付代码、spec/ADR、README/STATUS/CURRENT、测试、当前 SHA 的 evidence 和未完成项。若某路径已在当前 HEAD 完成,用证据标记已闭环,不重复造轮子。未满足任何强制门禁则维持 DO NOT RELEASE。不得未经 Owner 授权打 tag 或发布。
18. 本 RFC 的参考基线与关系
本规范已涵盖实施所需的原则、接口约束、示例、顺序与验收,不要求开发者先阅读旧审计才能知道该做什么;以下仅作为对照来源,发生矛盾时以当前代码、正式已接受 ADR、公开 spec为事实来源,并在 PR 中修正本 RFC:
- 语言语义:
docs/architecture/RFC-LANG-0002-unified-semantics.md与docs/adr/0052-unified-markdown-semantics.md。 - Callable:
crates/marqdo-ir/src/callable.rs、crates/marqdo-frontend/src/calls.rs、crates/marqdo-runtime/src/interpreter.rs,已有 ADR-0009、ADR-0010。 - Plugin:
crates/marqdo-plugin-abi/*、crates/marqdo-host/src/host.rs,spec/plugin-abi.md。 - Foreign:
crates/marqdo-foreign/src/lib.rs、ADR-0012 与 ADR-0020。 - Provider:
crates/marqdo-host/src/host/providers.rs、resource_ops.rs、provider_c.rs、provider_worker.rs,ADR-0033~0038。 - Package:
crates/marqdo-package/src/lib.rs、crates/cli/src/loader.rs,marqdo.lock现行 spec。 - 标准库:
stdlib/、crates/cli/src/stdlib.rs、ADR-0039。 - Tool/Analysis/Trace:
spec/tool-v1.md、spec/analysis-v2.md、spec/trace-v2.md。 - 原有安全/发布:
docs/security-vm.md、docs/security-gate.md、docs/releasing.md、docs/performance.md。 - 代码事实基线:https://github.com/cflmy/marqdo-cli/tree/595279fe38048b52b96d9ff1e7d57a867ec5c4c6
最终原则:让外部库扩展的是能力、算法、资源与可读知识制品,而不是篡改 Marqdo 的唯一执行语义。以单一静态绑定与受控 Host 为中心,保证语言内核和独立生态在功能增加时不互相挟持。
19. Implementation record (2026-11-22)
This section records the executed state. It does not tag a release or override
docs/releasing.md; the owner still decides tags/assets.
| PR | State | Evidence |
|---|---|---|
| PR-00 baseline | done | docs/evidence/ext-baseline-595279f.md (fmt/clippy/test green at 595279f) |
| PR-01/02 unique callable binding | done | CallSiteKey/CallBindingTable, one bind_program_calls, runtime dispatch by identity; crates/cli/tests/callable_resolution.rs 14 tests; spec/callable-resolution.md, ADR-0054 |
| PR-03 provider v2 CLI | done on linux/x86_64 | crates/cli/tests/provider_cli.rs 12 tests; spec/resource-provider-v2.md, ADR-0055; macOS/Windows FAIL-CLOSED |
| PR-04 extension selection/lock v4 | done | extensions: manifest block, lock v4 identity, inspect --extensions; crates/cli/tests/extension_selection.rs 13 tests; spec/extension-selection.md, ADR-0056 |
| PR-05 capability handlers | done | handler registry + real fs.read; crates/marqdo-host/tests/capability_handlers.rs 12 tests; ADR-0057 |
| PR-06 stdlib public aliases | done | verified public_aliases/aliases_digest; print_override/scan/runtime branch removed; stdlib_alias_routing 5 tests; ADR-0058 |
| PR-07 external consumers | done | separate repo marqdo-extension-conformance (pure pinned-Git lib, plugin, unknown kernel, provider v2, Analysis/Trace tool) + frozen-CLI suite |
| PR-08 release/docs convergence | implemented; release-tag rerun pending | workspace gate 599 passed / 67 targets, fmt/clippy clean; evidence manifest bound to 6a7bb98; the tag action itself requires owner approval and the unchanged G3/G4/native gates |
Known deviations are recorded in docs/evidence/2026-11-22-ext-implementation.md
§4 (provider transport linux/x86_64 only; additive provider error codes;
analysis calls[] projection; no tag).
Do not treat this record as a release. The release decision remains
DO NOT RELEASE until the remote G3 artifact and same-SHA mandatory lanes
exist; the external-extension manifest is an additional necessary gate, never a
substitute.