Files
marqdo-cli/docs/MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md
cflmy 2c7c4f31e7
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
Linux strict security lane (G-C) / strict isolation escape matrix (push) Canceled after 0s
CI / fmt + clippy + test (Linux x86_64) (push) Canceled after 0s
CI / schema instance validation + consumers (push) Canceled after 0s
CI / runtime contract (macos-latest) (push) Canceled after 0s
CI / runtime contract (windows-latest) (push) Canceled after 0s
CI / release evidence manifest (push) Canceled after 0s
CI / release candidate artifact (macos-latest) (push) Canceled after 0s
CI / release candidate artifact (ubuntu-latest) (push) Canceled after 0s
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

507 lines
22 KiB
Markdown
Raw Permalink 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.
# Marqdo 3.x 第三方开发者接入手册
> 状态:**随 `3.0.0-beta.1` 发布**(Linux x86_64 beta)。产品版本为 `3.0.0-beta.1`;协议版本独立:Analysis v2、Trace v2、Tool v1、Plugin ABI v1、Foreign wire v1、Provider manifest v2、Lock v4、Markdown profile `marqdo.md.v1`。官方 stdlib 包版本 `0.1.0`、插件/工具/示例包版本也都是独立版本轴,不随产品版本变化。
>
> 本文是入门与工程接洽流程;与已发布二进制冲突时,以该版本 `--help`、`--version`、`spec/` 和 release notes 为准。本文所有命令片段都已在 `3.0.0-beta.1` 二进制上验证;未验证的可能平台行为会明确标注为 UNVERIFIED/UNSUPPORTED,绝不默认为支持。
配套入口:[`developers/README.md`](developers/README.md)(按任务分拆的
quickstart/libraries/tools/extensions/analysis-trace/compatibility)和
[`developers/release-limits.md`](developers/release-limits.md)(beta 限制)。
## 0. 快速定位:你要开发的是什么?
| 目标 | 必须使用的扩展入口 | 可否完全独立于核心仓库 | 第三方主要交付物 |
|---|---|---|---|
| 普通 AI、数学、量子算法、SKILL、数据处理 | Marqdo `.mq.md` 包 | 是 | `index.mq.md`、`marqdo.yaml`、README、fixtures |
| 知识分析、Proof、View、IDE、Lint 等外部工具 | CLI Tool Protocol v1 | 是 | 独立可执行程序、`tool.json`、Analysis/Trace 消费者 |
| 高性能原生算法/量子门适配函数 | Callable Plugin ABI v1 | 是(遵循 ABI) | `plugin.yaml`、目标平台动态库、C header/SDK |
| 新的 Python/R/Julia 等外语执行后端 | Foreign Kernel | 是(遵循 wire) | `kernel.json`、可执行 provider、固定环境 |
| 硬件资源、数据库会话、外部流设备 | Resource Provider v2 | 是(遵循别名协议) | `provider.json`、C ABI library(`marqdo-provider-worker` 由 CLI 发行包提供,不随扩展分发) |
| 改变 `@exec` 语义、增添 `if` 关键字/原生数值类型 | 正式语言 RFC | **不是**第三方扩展 | core 变更 + 迁移 + 完整语言一致性测试 |
**最重要的架构规则:** 第三方仓库只依赖已发布的 CLI/规范协议;禁止依赖
`marqdo-ir` 私有 Rust 结构、内部 `HostOp`、CLI 当前源码相对路径、未冻结的
`inspect --ir` 私有结构或运行时进程内存布局。新领域函数不得靠在核心
`builtins_impl.rs` 加 `quantum.*`/`agent.*` 分支获得支持。
## 1. 前置条件、安装布局与版本协商
### 1.1 发布归档
`3.0.0-beta.1` 只发布 **Linux x86_64 (glibc)** 归档:
```text
marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz
marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz.sha256
```
```bash
sha256sum -c marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz.sha256
tar -xzf marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz
cd marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu
./marqdo --version # marqdo 3.0.0-beta.1
```
归档内至少包含:`marqdo`、**同目录的** `marqdo-provider-worker`、
`RELEASE_INFO.json`(source SHA/target/toolchain/binary SHA256)、`SOURCE_SHA`、
`KNOWN_LIMITATIONS.md`、`spec/`、`docs/developers/`、`examples/`、
`tests/consumers/`。`sha256` 只证明内容完整性,**不是**发布者身份签名。
`marqdo-provider-worker` 只按 `marqdo` 可执行文件同目录解析,不查 `PATH`、
不退化为 Host 进程内加载;缺失时 Provider 请求以
`ext.worker_unavailable` fail-closed。Provider 扩展作者只交付
`provider.json` + C ABI library。
### 1.2 源码/工具链前置条件
- 消费扩展:不需要 Rust。需要 `git`(Git 依赖)、`python3`(归档中的
Analysis/Trace consumer)。
- 自己编译插件/Provider:Rust 1.82+ 或仅 C 编译器(`cc`)+ 冻结 C header。
- 内置 Foreign kernel:系统 `python3`/`node`(或显式固定环境)。
- `--mode strict`:仅 Linux,需要 Bubblewrap 且内核/环境允许 namespace;
否则 fail-closed。
### 1.3 版本轴与 SemVer 预发布规则
产品版本、协议版本、包版本是三个独立轴:
| 轴 | 当前值 | 说明 |
|---|---|---|
| 产品/CLI | `3.0.0-beta.1` | `marqdo --version`、Analysis `producer.version` |
| 协议 | Analysis v2、Trace v2、Tool v1、Plugin ABI v1、Foreign wire v1、Provider manifest v2、Lock v4 | 不因产品叫 3.0 而改成 v3 |
| 包 | 官方 stdlib `0.1.0`;示例插件/工具/项目 `0.1.0` | 各自 SemVer 轴 |
Beta 期必须显式包含预发布号。`">=3.0.0,<4.0.0"` **不会**匹配
`3.0.0-beta.1`(SemVer 规则);请写
`">=3.0.0-beta.1,<4.0.0"`。`tool.json` 的 `compatibility.marqdo` 与
`marqdo.yaml` 的 `project.marqdo` 都按此规则**强制执行**,不匹配分别报
`requires marqdo …` / `package.marqdo_incompatible`,不会静默忽略。
### 1.4 安全模式
- `--mode pure`:纯语言执行,不授予任何外部系统权限。
- `--mode project`(默认):只能通过显式 CLI grant/授权访问资源;**不是**安全
OS sandbox,默认按当前用户身份运行。
- `--mode strict`:Linux-only、Bubblewrap probe-gated 的 L1 隔离(pure 语言 +
native Math)。它拒绝 `--allow-*`、`--plugin`、`--provider`、`--kernel`、
`--trust-native-plugin` 和 `--trace-file`;strict L2(Worker/Foreign/Provider)
未实现。没有该发行 SHA 的隔离证据时,发布说明必须明确 `strict: unsupported`
并保持 fail-closed。
## 2. 纯 `.mq.md` 库:优先采用
推荐独立仓库结构:
```text
marqdo-quantum/
README.md
marqdo.yaml
index.mq.md
tests/
examples/
```
`marqdo.yaml`(`project.marqdo` 在 beta 起强制校验):
```yaml
project:
name: quantum
version: 0.1.0
marqdo: ">=3.0.0-beta.1,<4.0.0"
dependencies: {}
```
`index.mq.md`(符合 RFC-LANG-0002):
```markdown
# @knowledge 量子数学工具
此包在不修改 Marqdo 内核的情况下向外公开领域函数。
## @exec 加倍
`params(x: Int)`
`return x * 2`
```
消费者固定真实 Git commit(**小写 40 或 64 位完整 SHA**;分支/标签不可复现):
```yaml
# consumer/marqdo.yaml
project:
name: quantum-consumer
version: 0.1.0
marqdo: ">=3.0.0-beta.1,<4.0.0"
dependencies:
quantum:
git: https://github.com/your-org/marqdo-quantum.git
rev: 0123456789abcdef0123456789abcdef01234567
```
```markdown
---
import:
quantum: "@quantum"
---
## @exec main
`return quantum.加倍(x=21)`
```
`@quantum` 绑定依赖包的入口 `index.mq.md`;调用需带别名前缀。路径依赖使用
`path: ./deps/x`(必须位于项目根内);`marqdo add <alias> --git <url> --rev
<sha>` 可代写。
运行步骤(消费者项目根):
```bash
marqdo lock
marqdo sync --locked
marqdo check index.mq.md --refs
marqdo call index.mq.md main # -> 42
```
### 2.1 Lockfile 行为(必须理解)
- 声明依赖后,`check`/`run`/`call`/`inspect` **要求** `marqdo.lock`;缺失报
`project.lock` 并要求先运行 `marqdo lock`。
- `run`/`check` 从不 fetch,也从不改写 lock。普通 `sync` 可能按 lock 取回
缺失的 pinned Git revision;`sync --locked` 禁止 fetch,只用已验证缓存。
两者都校验内容摘要,绝不静默更新 lock。
- lock v4 记录完整包实例闭包(`dep:name@version#content-digest`)、alias 边和
扩展 manifest/artifact 身份;v3 会得到显式 `marqdo lock` 迁移错误。
- 提交 `marqdo.lock`,忽略 `.marqdo/`(`init` 已写 `.gitignore`)。
## 3. Knowledge / Prove / View:使用 Tool Protocol v1
这是外部工具的首选架构:核心只提供语言/公开协议,工具是独立进程。
```text
marqdo-cli (语言核心,不依赖工具仓库)
| check --emit / run --trace-file / call / public spec
v
marqdo-knowledge / marqdo-prove / marqdo-view (各自独立仓库)
```
建议仓库:
```text
marqdo-view/
README.md
tool.json
bin/marqdo-view # 独立编译后生成,不能是核心源码依赖
src/
tests/contract/
examples/
```
`tool.json`(已可在 beta 上安装):
```json
{
"schema": "marqdo.cli-tool",
"schema_version": 1,
"name": "marqdo-view",
"version": "0.1.0",
"command": "view",
"entrypoint": "bin/marqdo-view",
"compatibility": {
"marqdo": ">=3.0.0-beta.1,<4.0.0",
"analysis": [2],
"trace": [2]
}
}
```
安装和调用:
```bash
marqdo tool install ./marqdo-view # 目录或 tool.json
marqdo tool list
marqdo view --help
marqdo view index.mq.md
marqdo tool remove view
```
**Tool 运行契约:**
- CLI 原生命令优先;未知顶层命令只有已注册 `tool.json` 才分发,绝不扫描
`PATH` 猜测执行。
- 安装:读取并校验 schema/SemVer/协议交集、entrypoint 不越界、命令不冲突;收集
整包清单(相对路径/大小/SHA-256,拒绝符号链接/特殊文件,限制 4096 文件/
256 MiB),复制到 staging 后重新计算并逐项比对,最后原子发布。安装目录为
`$MARQDO_TOOL_HOME`(若设置)或用户配置目录下的 `marqdo/tools`。
- 分发:启动前重新计算整包清单并与记录比对,entrypoint 必须属于该清单;保留
`cwd`、stdio、argv 和退出码,不经 shell、不拼接命令行。
- 工具环境变量:`MARQDO_BIN`(当前 CLI 绝对路径)、
`MARQDO_TOOL_PROTOCOL=1`,以及协商成功后提供的
`MARQDO_PROTOCOL_ANALYSIS=2` / `MARQDO_PROTOCOL_TRACE=2`。
- 工具不应猜测 `marqdo` 在 `PATH` 中的位置,优先调用 `MARQDO_BIN`,通过 argv
数组传参。
- Tool 是用户主动执行的普通进程,**不继承** `.mq.md` 程序的
`pure/project/strict` 隔离;不得静默执行文档或继承授权。
- 负例:未知 schema major、`marqdo` 范围不匹配、保留命令、逃逸/符号链接
entrypoint、篡改 bundle、缺失 entrypoint 都必须 fail-closed;协议不匹配报
`tool.protocol_incompatible`。
### 3.1 公共 Analysis v2:静态输入
```bash
marqdo check index.mq.md --emit ./analysis.json
```
只在退出码为 0 后读取 artifact。`--refs` 是**独立**的 Markdown 链接校验,可能让
`check` 失败;失败时 `check` 会删除旧的 emit 目标文件,因此不要用
`check --refs --emit` 生成消费 artifact 而不检查退出码。
成功时为 JSON `schema: marqdo.analysis`、`schema_version: 2`。顶层字段:
`producer`、`project`(`root_id`、`identity_kind`、`lock_digest`——无 lock 时为
空字符串、`stdlib`——可能为 null)、`modules`、`diagnostics`。模块字段:
`id`、`package_instance_id`、`relative_path`、`source_digest`、`units`、
`functions`、`imports`、`references`、`calls`、`resources`。字节偏移以 UTF-8
源文本为准;稳定索引键用包实例身份而非本地绝对路径。完整字段与 JSON Schema:
`spec/analysis-v2.md`、`spec/schemas/analysis-v2.schema.json`。`check` 不加载
插件库、不启动内核/Provider、不运行程序。
**View 责任**:读取原始 Markdown 渲染(不能用 Analysis JSON 代替原文);把源
字节偏移/标题单元/可调用映射关联到渲染内容;运行展示只读 Trace,不能自行执行
`.mq.md` 或产生不受 Host 控制的副作用。
**Knowledge 责任**:消费 Analysis 的标题锚点、链接、资源、包身份与来源摘要;
生成索引/知识图;不假定 `@knowledge` 有运行效果;跨包地址使用显式 import/锁定
身份,禁止按物理路径猜目标。
**Prove 责任**:从公开 Analysis 提取可证明子集/证明义务,通过外部证明器生成
证书;要求源摘要、语义与契约身份一致;明确区分
`proved / disproved / unknown / unsupported`。无法证明不等于程序错误。不得修改
core IR 或把“模型说证明了”当可信证书;缺公共字段应先提版本化协议提案。
### 3.2 公共 Trace v2:动态输入
```bash
marqdo run index.mq.md --trace-file ./trace.json
```
读取 `schema: marqdo.trace`、`schema_version: 2`。把 `source.analysis_digest`
与实际 Analysis JSON **文件字节**的 SHA256 对照;不一致提示 stale trace。事件
包含 `call.enter`、`call.exit`、`branch.eval`、`loop.iteration`、`return`、
`effect`,以及可能的 `trace.truncated`;每个带来源事件包含 module id + UTF-8
span。Trace 不记录参数值、秘密或文件内容。默认预算 100000 事件 / 32 MiB,可用
`--trace-max-events` / `--trace-max-bytes` 调整;工具不得假定 trace 永远完整。
`run --trace-file` 不生成 Analysis,digest 只适合与同一项目/同一投影配置的
Analysis 对比。详见 `spec/trace-v2.md`、`spec/schemas/trace-v2.schema.json`。
**不要依赖** `inspect --ir` 的当前 JSON 形态(不是冻结跨仓协议);需要结构信息
用 `check --emit`。
## 4. 计算插件:Callable Plugin ABI v1
平台矩阵:**Linux x86_64 的 native 与 worker 是 beta 支持目标**;macOS
native/worker 为 UNVERIFIED,Windows native/worker 为 UNSUPPORTED(Unix-gated)。
首发只应交付 `x86_64-unknown-linux-gnu` 的 `.so`。
公开 ABI 头文件 `include/marqdo_plugin_abi_v1.h`,Rust SDK
`crates/marqdo-plugin-sdk`(`mq_plugin_entry!`)。`plugin.yaml`:
```yaml
plugin:
name: demo.solver
version: 0.1.0
abi: "^1.0"
kind: worker # native 需 --trust-native-plugin;worker 为崩溃隔离
exports:
- name: solver.add
signature: "($a: Int, $b: Int) -> Int"
requires: []
artifacts:
- target: x86_64-unknown-linux-gnu # 必须与宿主 triple 精确相等
file: libsolver.so
sha256: "<实际工件的64位小写十六进制SHA256>"
```
消费(**只接受命名参数**;`--allow-plugin` 匹配 `plugin.name` 全名):
```markdown
## @exec main
`return solver.add(a=20, b=22)`
```
```bash
marqdo plugin inspect path/to/plugin.yaml # 仅静态,不加载
marqdo check index.mq.md --plugin path/to/plugin.yaml
marqdo run index.mq.md --plugin path/to/plugin.yaml --allow-plugin demo.solver
```
`check` 按 Manifest 做静态签名绑定,不加载插件(工件可以尚不存在)。`run` 先
验证工件 hash/目标平台/grant,再核对静态与动态 export 清单一一一致,不能在
运行时猜名字或合成空签名。`kind: native` 进程内执行,必须显式
`--trust-native-plugin`,可直接破坏宿主;`kind: worker` 在子进程中加载同一
library,是崩溃/地址空间隔离,**不是** OS sandbox。ABI v1 配置默认值被拒绝;
参数字面量位置参数会被规范化但库调用约定仍是命名。规范源:
`spec/plugin-abi.md`、`spec/callable-resolution.md`;可运行示例
`examples/plugin-demo/`(归档内含 host 构建工件)。
## 5. Resource Provider v2:设备/外部流
平台:**Linux x86_64**(worker transport);macOS/Windows 不声称。
```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位小写十六进制SHA256>"
}],
"permissions_requested": []
}
```
```bash
marqdo run index.mq.md \
--provider /path/to/provider.json \
--allow-provider demo.sensor
```
程序中继续使用普通语言接口 `resource.open("demo.sensor", "unit-1", ["read"])`
配合 `resource.read/write/close` 和 `Memory` 搬运 bytes。Provider 不新增语言
关键字或 callable。一个资源 kind 只能匹配一个 Provider,重复与未授权在真正执行
前拒绝。`marqdo-provider-worker` 必须与 `marqdo` 同目录、同目标平台;缺失时报
`ext.worker_unavailable`,不退化到 PATH 或进程内加载。`check`/`inspect` 不接受
`--provider`,也从不加载 Provider。当前特性不是安全沙箱。规范源:
`spec/resource-provider-v2.md`、ADR-0055;可运行示例 `examples/provider-demo/`
(先运行其 `build.sh`;仓库内模板 manifest 的 digest 是零值,只有生成的
`build/provider.json` 可运行)。
## 6. Foreign Kernel:新增未知语言无需改内核
使用 `kernel.json` 注册新语言标签;`Code`/`Formula` 仍是惰性值,必须显式调用
`foreign.run/foreign.call`。最小描述符(字段以 `spec/foreign.md` 为准):
```json
{
"provider_id": "mocklang",
"languages": ["mocklang", "mock"],
"wire_version": 1,
"entrypoint": "./mocklang",
"permissions_requested": [],
"digest": "<entrypoint/环境工件的64位小写SHA256,必填>",
"environment_id": "mocklang-env-1"
}
```
```bash
marqdo run demo.mq.md --kernel path/to/kernel.json --allow-foreign
```
`wire_version` 当前必须为 1;相对 `entrypoint` 相对描述符目录解析且必须
canonicalize 到普通文件;`digest` 必填并在每次 spawn 前校验;`builtin: true`
被拒绝;`--kernel` 可重复。Host 必须拒绝未授权执行、digest 不匹配、异常退出、
超时与不兼容 wire。不要按语言名在 core 加 `if language == "julia"`。示例:
`examples/kernel-mock/kernel.json` 与 `demo.mq.md`;规范源:`spec/foreign.md`。
## 7. 可复现扩展选择:`marqdo.yaml.extensions` / lock v4
```yaml
project:
name: my-research
version: 0.1.0
marqdo: ">=3.0.0-beta.1,<4.0.0"
dependencies:
quantum:
git: https://github.com/your-org/marqdo-quantum.git
rev: 0123456789abcdef0123456789abcdef01234567
extensions:
plugins:
- from: "@quantum/adapter/plugin.yaml"
kernels: []
providers:
- from: "@quantum/adapter/provider.json"
```
- `from` 仅支持 `./` 相对路径或 `@alias/` 已声明包依赖路径;不允许 URL、绝对
路径、通配符、`..`、空路径或 symlink 逃逸。
- `marqdo lock` 将已选扩展的 manifest/目标 artifact 摘要及逻辑包实例写入 lock
v4;`marqdo inspect index.mq.md --extensions --json` 只显示身份与 lock 状态,
不执行。
- `check`/`sync` 检查声明与 lock 一致(`ext.extension_lock_mismatch`);
`run/call` 在授权前再次检查实际工件。
- **选择扩展永远不等于授予权限**。`--allow-plugin NAME`、
`--allow-provider NAME`、`--allow-foreign` 仍必须显式。`strict`/`pure` 不允许
第三方执行扩展。
- Manifest 任何签名/路径/版本/目标平台/SHA256 不符都 fail-closed,不得“自动找
可用最新版本”。
## 8. 跨仓库契约测试(任何外部工具/库都要交付)
**正向**:独立 Git repo、真实固定 SHA 导入;在已发布二进制上 `check`、`run/call`;
Tool 执行 `marqdo tool install ...` 和真实命令;Analysis/Trace 消费者验证
schema、digest、源码 span;Provider 与 Plugin 在正确授权下返回确定结果。
**负向**:未知语法标记不会被执行;错误函数名/arity;导入别名与 builtin 命名
空间冲突;重复导出;缺失/错误摘要;未授权;缺 Provider Worker;平台不匹配;
混淆 lock v3/v4;过期 Trace;未知 schema major;Worker 崩溃/超时;上述都必须
产生预期诊断,没有“失败后静默改用其他实现”。
**冻结 CLI 测试**:先构建或下载固定来源 SHA 的 CLI 二进制并记录 SHA256,然后
仅修改外部仓库重复完整正负验收;严格验证二进制哈希不变:
```bash
python3 tools/ci/verify_extension_contracts.py \
--cli /path/to/frozen/marqdo \
--fixtures /path/to/marqdo-extension-conformance \
--out docs/evidence/extension/<release-sha>/manifest.json
```
参考独立仓库
[`marqdo-extension-conformance`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance)、
`docs/evidence/extension/schema.json`。若每新增一个函数都必须重编 CLI,该扩展
不合格。
## 9. 开源发布与支持政策
- 每个第三方包发布:README、最小示例、实际支持的 CLI 产品版本范围、独立协议
版本、目标平台矩阵、权限清单、可复现工件 digest、测试命令、限制与安全声明。
- 明确 `sha256` 仅验证内容完整性,不等于发布者身份认证;不能仅凭未知 Git URL
的 hash 就把扩展当可信代码。
- `developers/README.md` 指向按任务拆分的 Tool/Library/Plugin/Kernel/Provider
教程和 `spec/` 规范协议。
- `3.0.0-beta.N` 阶段的第三方应把破坏性变更视为真实风险;LTS 承诺尚未宣布。
- 本 beta 的支持平台只有 Linux x86_64;G4 是固定节点上的 Beta-only WARN,
strict 策略以发布证据为准;这些都不是 LTS 承诺。
## 10. 独立工具开发清单(Knowledge/Prove/View)
- [ ] 独立仓库构建,`marqdo-cli` 没有任何依赖指向本仓库。
- [ ] `tool.json` 合法、入口文件属于安装包、Tool 版本与 CLI 协商成功。
- [ ] 从 `MARQDO_BIN` 派生调用,而非内部 Rust API。
- [ ] `check --emit` 读 Analysis v2;`run --trace-file` 读 Trace v2;强校验
schema/version/digest 与退出码。
- [ ] 只解析用户授权源文件及显式依赖闭包,路径兼容多包实例/不同 checkout。
- [ ] 确定性输出、错误诊断、fixture、中文/英文快速教程齐备。
- [ ] 未验证 strict、不可证明内容、无设备支持等边界明确提示,不默默声称支持。
- [ ] 冻结 CLI 黑盒测试及反向兼容性测试 PASS;无 core source edit。
## 11. 本文引用的仓库规范
- `spec/mapping.md`、`spec/expression.ebnf`、
`docs/architecture/RFC-LANG-0002-unified-semantics.md`
- `spec/package-format.md`、`spec/extension-selection.md`、
`spec/callable-resolution.md`、`spec/references.md`
- `spec/tool-v1.md`、`spec/analysis-v2.md`、`spec/trace-v2.md`、
`spec/plugin-abi.md`、`spec/resource-provider-v2.md`、`spec/foreign.md`
- `spec/security.md`、`spec/markdown-profile.md`、`spec/value-wire.md`
- `spec/schemas/analysis-v2.schema.json`、`spec/schemas/trace-v2.schema.json`
- `include/marqdo_plugin_abi_v1.h`、`crates/marqdo-plugin-sdk`
- `docs/releasing.md`、`COMPATIBILITY.md`、`docs/evidence/extension/README.md`
- `docs/developers/README.md`、`docs/developers/release-limits.md`