Files
marqdo-cli/docs/architecture/RFC-EXT-0001.md
T
cflmy 0b01cbd2a4 evidence(ext): SHA-bound frozen-CLI external conformance manifest; finalize RFC-EXT-0001 record
- docs/evidence/extension/6a7bb98.../manifest.json: tested_sha 6a7bb98,
  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 at 6a7bb98 is byte-identical; this commit adds evidence/docs only.
2026-11-22 00:48:39 +08:00

1195 lines
98 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 sha256 `28e3776d…`,fixture repo `e4b7352c…`,全部必需结果 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`)并独立构建以下五类扩展:
1. 一个固定 Git SHA 的外部纯 `.mq.md` 库,具有跨模块函数,使用 `marqdo sync` + `run/check` 正确引用;
2. 一个导出多个不同前缀函数的外部 Callable Plugin(Worker 默认),静态签名和运行参数绑定一致;
3. 一个语言标签完全未知(例如 `mocklang`)的 Foreign Kernel,通过 `--kernel` 登记并执行;
4. 一个资源种类完全未知(例如 `demo.sensor`)的 Resource Provider,通过**普通 CLI**加载,完整实现 `open/read/write/close`,未授权时拒绝;
5. 一个独立 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 分层图
```text
任何独立的第三方 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 结构表达元数据,例如:
````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 前移)
```bash
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**:
```rust
#[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,不再通过重复验证消除先后错误。
**建议的新代码组织**:
```text
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
```
统一流程伪代码:
```rust
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, &registry)?; // 仅此一次
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`:
1. 静态加载 `plugin.yaml` 时,解析完整参数名称、顺序、必选性,拒绝重名、非法名字、不支持的默认表达式;返回注解如 `-> Int` 当前若仅展示,明确写为 `advisory`,不虚称运行时类型证明。
2. 静态检查时用 descriptor 执行 `validate_args`;除签名明确允许的参数外不得接受未知参数。对于 ABI v1 当前使用 map 传参的事实,支持位置参数时必须先将其确定性映射为签名参数名;若无法做到,必须在静态阶段明确拒绝位置参数,**禁止静态通过而运行时才拒绝**。
3. 推荐本阶段实现一致的位置参数绑定:例如 `solver.add(1, b=2)` 规范化为 `{a:1,b:2}`;任何重复、未知、缺失参数先失败。对于带缺省值的 ABI 参数,v1 首先可直接拒绝在清单中定义默认值,直到语义与 Wire 版本明确,不允许随便在运行时隐式注入。
4. Host `plugin_exports()` 返回的 `name/signature/digest/package` 必须与静态 manifest 集合**精确一一对应**。多出、少了、签名不同、Owner 不同、工件 SHA 不同,统一返回 `ext.plugin_binding_mismatch` 且禁止执行;不允许以 `params: Vec::new()` 合成描述符。
5. Runtime `dispatch` 不得再次 `builtins::find(qualified)` 或以 `external_callables.is_empty()` 作为 fallback 条件;根据绑定结果 `Builtin | Marqdo | AbiPlugin | DynamicValue` 分发。`DynamicValue` 仅对真正的语言可调用值有效。
6. 有多插件时按完整导出名注册,不以 `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 公共合同(本阶段必须实现)
```text
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` 必须完整定义下面的字段和拒绝条件:
```json
{
"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 解析规则:
1. `schema`/`schema_version` 必须恰好匹配;`name` 与每个 `kind` 必须非空、符合允许的分段命名语法(采用 Plugin 名称校验中的 ASCII 小写段 + `.`;若允许 Unicode 名称须另立 ADR);保留 `stdio/file/tcp/tls/udp/tcp-listener` 等核心 kind,禁止第三方覆盖。
2. `version` 为严格 SemVer;`abi` v2 初期只支持 `c-abi-1`;`transport` v2 初期只支持 `worker`。未来新增 transport 必须明确增加枚举与测试,不自动解释未知字符串。
3. `artifacts` 必须非空,不能重复 target;选择当前目标后校验普通文件、bundle 内位置、大小上限、SHA-256 精确相符;目标缺失返回 `ext.no_matching_artifact`,不使用 `default` 的其他平台二进制替补。
4. `permissions_requested` 为**声明**,不授予权限;v2 `open/read/write/close` 只按 `--allow-provider` + rights 受控,不能因为声明了 `vendor.*` 就给 Host 新权限。
5. schema 版本内未知的安全影响字段拒绝;可扩展元数据统一放入 `metadata` 映射且不具有执行意义。manifest 自身保存为 UTF-8 JSON。相对路径解析前阻止 `..`、绝对路径、符号链接逃逸;绝不将内容拼接给 shell。
6. 加载前验证完整 manifest + artifact;若要强制工件真实性,交由发布签名/信任根或用户固定的期望摘要额外处理。SHA-256 是**完整性**检查,不是来源身份认证,文档不得混淆。
### 5.4 精确落地的代码修改
1. `crates/cli/src/main.rs`:为 `SandboxArgs` 增加 `provider: Vec<PathBuf>`(CLI 名 `--provider`)和 `allow_provider: Vec<String>`(CLI 名 `--allow-provider`)。两个选项同用于 `run/call`,不得在 `check` 阶段启动 Worker。
2. `crates/cli/src/commands/sandbox.rs`:为 `SandboxSettings` 加同名字段;`capabilities()` 的 `Project` 分支对每个名称执行 `allow_resource_provider(name)`;`Pure`/`Strict` 的拒绝条件均包含两个新字段;`strict_preflight()` 输出固定、结构化错误码。
3. 新建 `crates/cli/src/provider_manifest.rs`(而非新大 crate):解析 v2;校验语法、artifact、sha256、target;产出 `VerifiedProvider { name, kinds, selected_artifact, transport, manifest_digest }`;不要与 Plugin `plugin.yaml` 共享错误的 ABI 解析器。
4. 新建或复用 `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。
5. Worker 可执行程序解析:使用发行包中和 `marqdo` 同目标三元组的 `marqdo-provider-worker`(从当前 CLI 可执行文件的兄弟目录解析),拒绝 PATH 任意同名可执行文件回退;发行归档必须一起交付、记录摘要。若某平台尚未支持,返回 `ext.platform_unsupported`,不可伪装成功。
6. 在 `run/call` 的通用 `assemble_host` 中加载 kernels、Callable plugins、resource providers;为各类型使用相同的可重复、确定性错误输出规则,但保持不同执行协议。加载顺序严格:parse + compile → 校验扩展唯一性与工件摘要 → 验证授权 → 初始化必要的 Worker → 执行主函数;无语义副作用的检查绝不 spawn。
7. `StdHost` Provider 注册 API 的代码重复部分要复用 `register_provider_checked`;保障按**完整 kind**索引,重复 kind 跨 Provider 不得覆盖;单个 Provider 同时导出两个 kind 都必须可用。
8. 结束 Session 时关闭所有 Provider tokens 并终止对应 Worker;单次 Worker crash 要转结构化错误,不能让 CLI panic;禁止在资源使用中断后静默回退其他 Provider。
### 5.5 可复制的 Provider 调用 fixture(现有语法)
`index.mq.md`:
```markdown
# @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):
```rust
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: ...}}` 的需求字段不得被悄悄解释为可运行工件;若保留,就明确仅为“需求”,不用于隐式选择;建议后续一次性迁移到下面的显式扩展选择结构:
```yaml
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 组合根配置优先级和安全规则
1. **声明**:`marqdo.yaml.extensions` 是项目明确启用的候选扩展来源;`--plugin/--kernel/--provider` 是本次运行临时追加来源;两个来源若相同逻辑身份且摘要一致则幂等,否则拒绝冲突。
2. **锁定**:`sync`/`lock` 负责把可复现的来源、包 SHA、manifest 内容 SHA、目标工件 SHA 记录到 lock;运行只消费已经锁定的物化源,不调用网络下载。测试中的临时显式 CLI 路径如果不在 project lock,可作为本机开发/调试形式使用,但输出 `unlocked_extension` 标记;发布模式不接受未锁定扩展。
3. **验证**:`check` 使用静态可读 descriptor + lock identity;`run` 在启动前重新核对所有实际工件,不能用 `check` 的旧哈希替代当前校验。
4. **授权**:`--allow-plugin`, `--allow-provider`, `--allow-foreign` 与文件/网络/进程等 Host grant 是独立权限;即便依赖包请求权限,Host 默认不授予。
5. **执行**:ABI Plugin、Kernel、Provider 使用各自的明确路径,不能让 `Tool` 充当偷偷运行库代码的 shell 执行后门;`Tool` 仍在独立 CLI 进程域。
6. **失败**:未解析 alias、未锁定依赖、摘要不匹配、无授权、缺当前平台工件均 fail-closed;不可自动退到最新版本或某个系统安装。
7. **可观测**:`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` 加一行就宣称新增服务已接通。
统一权限链必须满足:
```text
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 增加显式处理器目录。最小建议接口:
```rust
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 公开协议稳定性规则
1. CLI 的 Analysis、Trace 与版本化数据输出是正式的消费者边界。私有 IR(包括新 `CallBindingTable`)不要求跨发布稳定;Analysis 公开 schema、版本字段、Unit/Module identity、source span、源码 SHA、声明导出和 Call target 信息如已有字段不可悄悄改义。
2. 如确实要对外暴露 `resolved_call_target`,新增 `Analysis v3` 或合法的向后兼容可选字段,并提供 **v2→v3** 迁移说明与 golden;不能把内部 `CallableId` 直接裸序列化到现有 Analysis v2 并假定消费者无感。
3. Trace 的 `call/return/branch/loop/host-effect` 有可关联来源标识,密钥、完整网络 payload、敏感 argv 默认不输出;运行时关闭 Trace 时,不能因构造 Trace 文本导致显著性能损失。
4. `check --emit`、`inspect` 必须完全无执行副作用;`view/proof/knowledge` 通过已注册 Tool 执行时也不能偷偷获得项目 grants。
5. Tool 的子进程如需运行项目,必须显式启动新一轮 `marqdo run` 并重新按公开 CLI 合同获得授权;Tool 安装不等于运行权限。
6. Unknown JSON fields 和 schema version 应按对应公共规范处理:版本不兼容拒绝,允许的额外字段忽略,不能把所有未知字段当语义指令。
### 9.3 第三方证明消费者验收(无需实现证明内核)
在外部 fixture 中实现一个不到 100 行的 Python/Go/任意语言消费者:仅用标准 JSON 库读取 `check --emit` 的 Analysis、列举函数及其源位置,并输出对某个 heading anchor 的确定性摘要。再用独立 Tool Protocol 安装到同一冻结 CLI:
```bash
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 物理分离)
```text
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`:
```yaml
project:
name: example-math
version: 0.1.0
```
`pure-lib/index.mq.md`:
```markdown
# @exec 示例数学库
## 加倍
`params(x: Int)`
`return x * 2`
```
`consumer/index.mq.md`(消费者通过显式 alias 导入外部依赖):
```markdown
---
import:
m: "@math"
---
## @exec main
`return m.加倍(21)`
```
`consumer/marqdo.yaml` 示例(本地构建时使用 path;完成测试后替换为已提交的固定 Git revision):
```yaml
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/`:
```bash
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 运行侧四类典型命令
```bash
# 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 取代。
新增测试位置建议:
```text
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 编译与静态测试(每个提交都运行)
```bash
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`,至少包含:
```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 发布条件(必须全部满足)
1. PR-00~08 所有强制测试、正例与负例 PASS;所有公共 CLI 选项有 `--help`、spec、fixture 和错误码文档。
2. 外部仓库套件冻结 CLI binary SHA,构建新 `.mq.md` 库、新 plugin、新 kernel、新 provider、新 tool 全部无需 CLI 源码修改且无重编译;对真实未支持平台有明确 unsupported。
3. `check/run/inspect` 唯一解析语义闭合,未知调用在静态阶段拒绝,动态 FunctionRef 不可逃逸为 PluginInvoke。
4. Plugin/Provider manifests、锁文件与 Worker ABI 均有版本与摘要校验;Native trust 与 Worker 信任边界真实表述。
5. 现有官方 stdlib、打印、内存、资源、HTTP、JSON/CSV、Package、Tool、Analysis/Trace goldens 不退化;禁止修改 golden 使错误通过而无审查记录。
6. `docs/STATUS.md`、`docs/architecture/CURRENT.md`、`COMPATIBILITY.md`、`README.md`、`spec/*` 与新增 ADR 同步更新;发布报告指向**同 SHA** 的执行证据。
7. 既有仓库 `docs/releasing.md` 的主发布门禁(包括独立 G-C 和 G4)仍然生效。本 RFC 的扩展测试是**新增的必要条件**,绝不替代任何安全/平台门禁。
8. 未满足时设置 `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.md` fixture/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. 重要的设计否决事项(防止后续开发者偷懒)
以下提交一律拒绝:
1. **以“扩展语义”为由让第三方覆盖 `@exec/@knowledge`**:这会使同一 Markdown 文档在不同扩展环境下有不同执行含义,破坏可验证性。
2. **为一个新函数增加 3 个 `match` 分支**:比如为 `quantum.hadamard` 同时改 frontend、runtime 和 host。普通算法通过 `.mq.md`;性能加速走 Plugin;设备 I/O 走 Provider。
3. **让 `check` 真的加载或运行插件**:哪怕只是探测导出签名,也违反静态检查的安全与可重复性。
4. **根据 runtime 能否加载再改变静态符号解析**:未知函数不能在全无插件时落入“试执行”路径。
5. **在 `run` 合成不存在的插件签名**:不能用空参数签名、泛化 `effects=[host]` 掩盖 manifest/runtime 不一致。
6. **把 `--allow-provider` 视为可信任二进制授权**:Operator grant 允许资源操作,不能把未经 OS 隔离的 Worker 描述为安全的第三方代码环境。
7. **把 `provider.json v1` 伪装为完整性锁定**:v1 没有新 schema 中的工件 hash,需要升级为 v2 或显式可信本地 API。
8. **把 Tool、Foreign、Plugin、Provider 统一进无约束 shell 命令**:他们的生命周期、值模型、权限与故障边界不同。
9. **偷偷修改 `marqdo.lock` 的旧版本含义**:必须 bump schema 且写清迁移;不得无锁自动下载“最新”扩展。
10. **为标准库每个高级函数复制 `print_override` 模式**:必须实现一次标准函数公开别名绑定,普通三方函数仍走 import。
11. **测试夹带假路径、假 hash、无效 YAML 而声称通过**:示例里的 `<占位符>` 必须由脚本真实填充,输出依据当前真实 CLI 的退出码断言。
12. **借一套“平台抽象层”重新拆分很多 crate**:在已存在的 workspace 上小步重构,不重复建立第二套 IR、runtime、plugin SDK。
13. **声称远端 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 唯一装载时序(关键代码不得颠倒)
```text
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 生命周期与失败传播状态机
```text
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.