Files
marqdo-cli/docs/STABLE_RELEASE_IMPLEMENTATION.md
cflmy 18d9f39562 docs(release): reconcile status, compatibility and release evidence
- adopt docs/STABLE_RELEASE_IMPLEMENTATION.md as the single next-phase plan
- archive the stale M0.5 status snapshot under docs/history/
- record real local gate results, the red baseline CI, the Windows autocrlf
  reproduction and the unresolved macOS/native-CI status
- add COMPATIBILITY.md (protocol versions + honest platform matrix),
  CHANGELOG.md, dual license files, docs/releasing.md and docs/security-gate.md
- keep strict fail-closed: document the container EPERM/read-only cgroup probe
  and the exact G-C requirements instead of claiming isolation
- document foreign environment binding (ADR-0020) and add a release-candidate
  CI job that is gated on all platform jobs
2026-11-20 13:58:40 +08:00

1119 lines
83 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 CLI 稳定版本开发与发布实施总规范
> **定位:** 可直接提交到 `cflmy/marqdo-cli` 的 `docs/STABLE_RELEASE_IMPLEMENTATION.md`,并完整交由 DeepSeek Harness 执行。
> **状态:** Proposed / 下一阶段唯一总体实施计划(必须以实际代码、规范和测试验证结果修正状态)。
> **编写基线:** `cflmy/marqdo-cli`,默认分支 `master`,远程 HEAD `e966b7661f03ee7462df959917f5630353e66b10`(2026-11-20)。
> **最新远程 CI:** https://github.com/cflmy/marqdo-cli/actions/runs/44680378977 — Linux workspace 与 Schema 消费者通过;macOS/Windows workspace 未通过。
> **适用环境:** Ubuntu Linux 开发主机 + DeepSeek Harness;可使用经过用户授权的 `sudo`;跨平台结果以对应原生 CI 为准。
> **唯一目标:** 在不扩大语言核心、不增加不必要 CLI 顶层命令、不塞入 Knowledge/Proof/View 的前提下,修复所有承诺支持功能的正确性、可复现性、跨平台和安全缺口,最终发布**有明确定义的稳定版本**。
> **不要误读:** 本文不是从旧 `cflmy/marqdo` 仓库迁移代码的方案;当前项目是独立 Rust 实现。此文亦不承诺在首次稳定版中实现 JIT、通用 CAS、通用包注册表、IDE 或 Lean 证明。
---
## 0. 给第一次接触项目的开发者:十分钟了解任务
Marqdo 是 Markdown AST 原生承载计算语义的语言。日常文档既可以被 Markdown 阅读器阅读,也可以通过**独立的 Rust 解释器**执行。其理念为“代码即文档,文档即知识库,知识即可执行”,但**知识编译、形式证明、可视化是独立仓库**,不是本仓库内建的三个产品。
用户体验是一个 `marqdo` 命令:
```bash
marqdo run index.mq.md
marqdo call math.mq.md 计算面积 --arg r=3
marqdo check index.mq.md
marqdo add math --path deps/math
marqdo sync --locked
marqdo tool install ./some-tool/tool.json
marqdo <任意已注册工具名> ...
```
当前仓库另有 `init`、`lock`、`remove`、`inspect`、`fmt`、`plugin inspect` 等既有命令。**本阶段维持其已有合同,但不为了新功能继续增加顶层命令。** 任意新命令如 `marqdo view`、`marqdo prove`、`marqdo knowledge` 都由独立工具向通用 `Tool Protocol` 注册,而非修改内核源码。
从当前提交看:Markdown 解析/语义、原生解释器、Callable Registry、包图 lock v3、Analysis v2、Trace v2、Tool Protocol、ABI Worker、Foreign Provider 及相应测试已经存在。**核心任务是结束“实现存在,但发布证据、平台边界、安全闭环还不完整”的状态。**
### 0.1 给 Harness 的执行约束(必须遵守)
1. **先读本文件、`AGENTS.md`、`docs/STATUS.md`、相关 `spec/` 与 ADR,再改代码。** 它们可能互相过时,以当前源码与可复现测试为最终事实;遇到冲突先记录和修正文档。
2. **任何开发阶段先写能够复现缺口的测试,然后实现最小修复。** 不允许简单跳过失败测试、重写所有 golden、删除安全检查以通过 CI。
3. **普通构建永远使用非 root 用户。** `sudo` 只用于 OS/namespace/cgroup/AppArmor 诊断、测试 VM 系统配置和特定需要提权的安全测试,不使用 root 运行受试解释器或原生不可信插件。
4. **允许破坏性重构尚未稳定的内部 API**,但不擅自改 Markdown profile、已冻结语言语义和公开 ABI;若必须修改公开 Analysis/Trace/Tool schema,先给 ADR、schema 版本、迁移测试与消费者测试。
5. **不修改 CLI 来预先认识官方工具。** 第三方任意名称工具应与 View/Knowledge/Proof 完全同等接入。
6. **每阶段都给出:变更文件、为什么改、测试命令及结果、兼容性影响、剩余阻断项、commit SHA 和 CI URL。** 禁止把未运行的测试写成 PASS。
7. **发现新阻断项时可继续修复,但必须界定该项与当前发布合同的关系**;不因为“将来可能有用”增加新通用框架。正常情况下不要停下来等待设计确认;如果新问题改变语言语义/安全模型/项目发布范围,提交明确 ADR 后再推进。
8. **不要以 root、容器或某台机器上通过的结果替代普通用户和独立 CI 的验收。**
### 0.2 本文件里的用语
- **Implemented:** 当前源码存在实现,不代表全平台测试通过。
- **Verified:** 特定 commit、平台、测试命令确实通过且有日志。
- **Core Stable:** 受支持的语言、包管理、协议、运行时和 CLI 功能有完整回归测试和兼容承诺。
- **Strict Available:** 对特定 Linux 环境真实启用了隔离并通过逃逸/资源限制测试;未通过的环境继续 fail-closed。
- **Release blocker:** 在该版本明确承诺的支持矩阵内失败,必须修复才能发布。
---
## 1. 真实仓库基线,不要重新设计已经做完的东西
### 1.1 需要首先读取的资料
```text
README.md
AGENTS.md
Cargo.toml
crates/cli/src/main.rs
crates/cli/src/{commands,loader,analysis,trace,tool}.rs
crates/marqdo-package/src/{lib,fileset}.rs
crates/marqdo-host/src/{host,capability,plugin_worker,fs,handles,budget}.rs
crates/marqdo-foreign/src/lib.rs
crates/marqdo-sandbox/src/lib.rs
crates/marqdo-plugin-abi/src/{manifest,worker,wire,loader}.rs
spec/{markdown-profile,mapping,expression.ebnf,evaluation,references}.md
spec/{package-format,analysis-v2,trace-v2,tool-v1,plugin-abi,foreign,security}.md
docs/adr/0008-0019*.md
docs/STATUS.md
.github/workflows/ci.yml
crates/cli/tests/
tests/conformance/; tests/consumers/
```
现有代码库大约十五个 Rust crate,已有多种金样与负例,不需创建一套新的 monorepo 或把现有 crate 重新拆成更多微型 crate。
### 1.2 仓库已完成的基础(不要重复开发)
| 子系统 | 实际能力 | 源码/证据 | 需要保持的边界 |
|---|---|---|---|
| Markdown profile / AST | 固定 Markdown profile、金样解析 | `marqdo-markdown`、`spec/markdown-profile.md` | 不让工具插件改写 Markdown 语义 |
| 原生运行时 | 函数/表达式/分支/循环、原生 Rust 求值 | `marqdo-frontend`、`marqdo-runtime` | 不能经 Python 转译执行 |
| Callable Registry | 内置、模块函数、声明式 ABI export 的统一可调用描述 | `marqdo-ir/src/callable.rs`、ADR-0009 | 扩展可调用函数不修改多个 `match` |
| Package / lock | lock v3 全传递闭包、包实例身份、Git 固定版本、环境物化 | `marqdo-package`、ADR-0016 | 锁失败拒绝;`check` 不抓取依赖 |
| Analysis v2 | 逻辑身份、函数/公式/代码资源投影、独立消费者 | `cli/src/analysis.rs`、`spec/analysis-v2.md` | 外部不用私有 Rust IR |
| Trace v2 | 模块归属、容量预算、截断标识、来源摘要 | `cli/src/trace.rs`、`spec/trace-v2.md` | 没有执行就不产生 trace;不漏密钥 |
| Tool Protocol | 任意命令注册、SemVer 兼容、整包摘要校验 | `cli/src/tool.rs` | 不能内置 View/Proof/Knowledge 特判 |
| ABI Native/Worker | ABI v1、多导出、Worker IPC 与能力读取桥 | `marqdo-plugin-abi`、`marqdo-host`、ADR-0018 | Worker 不是 sandbox |
| Foreign Provider | 可外部注册、固定 provider/环境目录摘要 | `marqdo-foreign`、`spec/foreign.md` | 不把 uv/npm 硬编码进解释器 |
| 安全门禁 | `strict` 不可用时拒绝,不降级 | `marqdo-sandbox`、ADR-0019 | 仅真实隔离通过安全测试才翻开门禁 |
### 1.3 最新公开 CI 的确切结果(与旧 STATUS 描述区分)
在 `e966b766` 的 [CI #44680378977](https://github.com/cflmy/marqdo-cli/actions/runs/44680378977):
- Linux `fmt + clippy + cargo test --workspace + smoke`:**PASS**;
- Schema 实例验证 + Analysis/Trace 独立 Python 消费者:**PASS**;
- macOS `cargo test --workspace`:**FAIL**,`integration_cli::plugin_inspect_and_explicit_trusted_invocation` 假设 Linux `x86_64-unknown-linux-gnu` 插件 artifact 在 `aarch64-apple-darwin` 也可用,得到 `no_matching_artifact`;
- Windows `cargo test --workspace`:**FAIL**,`conformance_ast::ast_goldens_match_the_frozen_profile` 对第一个 golden 字符串不等,但按 `.lines()` 显示“0 line(s) differ”,需用字节级比较确定 CRLF/LF 或其他差异;
- 后两者因为 workspace 失败,后续 portable smoke 和 strict refusal 没执行。
**重要:** 所以截至此基线,不能写“全平台 CI 绿”、“G-B 已验收”。`docs/STATUS.md` 中“CI URL 缺失”现已过时,应修正到此 CI 链接,并记录红色结果。也不要将 Linux 的成功说成 Ubuntu 上的严格 OS 隔离成功。
### 1.4 本阶段禁止扩张的项目
不得为所谓稳定版强制加入:JIT/字节码、Web UI、Lean、知识图谱、向量数据库、通用插件市场、GitHub 注册表、SemVer SAT 求解器、长期 Foreign session、完整数学 CAS、通用调试服务器。除非已有正式语言规范要求其中某项才能保证正确性,否则全部列入后续独立项目或未来版本。
---
## 2. 目标架构、依赖方向与跨仓职责
```text
用户输入 `marqdo ...`
│
├── Core command surface: run / call / check / add / sync / tool
│ (现有 init/lock/remove/inspect/fmt/plugin inspect 暂时兼容)
│
├── Generic tool dispatcher ── tool.json / tool registry
│ └── external executable: 任意工具名
│ ├── marqdo-knowledge (独立仓)
│ ├── marqdo-proof (独立仓)
│ ├── marqdo-view (独立仓)
│ └── 第三方插件工具(和官方平等)
│
└── Core compile & execute
├── Markdown parser + language mapping (固定语义)
├── Semantic analysis + CallableRegistry
├── PackageResolver / lock v3 / physical source map
├── Analysis v2 export (公开投影,不是私有 IR)
├── Rust interpreter
│ ├── Value + error + module-aware span
│ └── Host authorization and effects
│ ├── Math
│ ├── Foreign Kernel Provider
│ └── ABI Native / Worker
├── Trace v2 export
└── strict OS isolation adapter (Linux security gate)
```
### 2.1 三个外部扩展域禁止混用
1. **CLI Tool:** `marqdo tool install ./tool.json` 注册一段独立本地程序,`marqdo benchmark ...` 通过通用分发器执行。它以使用者权限运行,不承诺自动受 Marqdo 语言沙箱保护。
2. **ABI Plugin:** 扩展 `.mq.md` 调用目标,以 C ABI v1、声明导出和 Host 权限判断为界。可信 Native 可进程内;Worker 只提供崩溃隔离,未进 strict 时不具备敌意代码沙箱。
3. **Foreign Kernel Provider:** 显式执行外部代码块内容,需要独立的 provider/executable/env/授权/协议。不能通过 CLI Tool 安装自动变成可执行的 Marqdo 内核,也不能靠一份 JSON 声明获得系统权限。
### 2.2 严格单向依赖
- `marqdo-markdown` 不依赖 runtime、host、tool、Web。
- `marqdo-runtime` 不依赖 Tool、Knowledge、Proof、View。
- `marqdo-package` 负责包图和来源;`cli` 只负责命令装配,不自行解释包依赖。
- `marqdo-host` 负责执行 effect 授权/代理,`marqdo-sandbox` 负责操作系统机制与能力检测;**Host 授权 ≠ OS 隔离**。
- 外部工具只依赖发布的 `marqdo` 命令、Analysis/Trace v2、Tool v1 协议,不链接私有 `marqdo-ir` Rust 类型。
- core 不认识 `knowledge`、`prove`、`view` 的具体名字,不维护官方专属白名单和下载地址。
### 2.3 语言与协议冻结
Markdown profile、代码节点判定、表达式语法、参数推断、显式导入和引用不执行属于语言层;不能为了 View 或 Proof 变通。Analysis v2、Trace v2、Tool v1 是面向外部消费者的交换层。新增不兼容字段须出独立版本及迁移测试;内部 IR 可以破坏性重构,不得泄露私有 Host 句柄或内存地址。
---
## 3. DeepSeek Harness 与 Ubuntu 的开发环境和提权规范
### 3.1 推荐开发环境
**推荐配置:** 独立 Ubuntu 24.04 LTS x86_64 主机或 KVM VM、普通开发用户、Git/Rust、Python3、C 编译器、Node.js(仅用于 Foreign 集成测试)、Bubblewrap、AppArmor 工具,以及可操作的 cgroup v2。内核可支持的机制必须用当前主机实际 probe 判定,不能凭操作系统版本猜测。
如果用户宿主机没有敏感数据,允许 Harness 用 `sudo` 安装软件/配置专用测试环境。但请始终遵守:**root 是 Harness 的管理权限,不是 Marqdo 被隔离程序的运行身份。** 一些安全测试必须由非 root 发起,以证明真实普通用户体验。
**建议流程:** 先由用户用 `sudo -v` 建立提权会话,确认 `sudo -n true` 是否成功;Harness 只对必要命令显式写 `sudo`。对于完全可销毁的 VM,可给特定开发账户 `sudo` 组或配置无密码提权,但必须让 Harness 将每次系统级改动记入日志,完成测试后恢复与验证。不要在日常主机上直接禁用系统 AppArmor 或永久修改全局 namespace 策略来制造虚假的 PASS。
### 3.1.1 如果确实需要让 Harness 无交互提权(仅限可销毁专用 VM)
普通 Ubuntu 主机先用管理员账户将开发用户加入 `sudo` 组(若尚未有权限),然后**重新登录**该用户:
```bash
# 在管理员终端执行;将 devuser 替换为实际开发用户名
sudo usermod -aG sudo devuser
# 重新登录开发用户后检查
id devuser
sudo -v
```
`sudo` 组默认可能仍要求输入密码。若 DeepSeek Harness 的终端不能交互输入密码,而你完全掌控、可以随时重建这台专用 VM,可以**有意识地**为此开发用户建立单独的临时 sudoers 规则:
```text
# 用 sudo visudo -f /etc/sudoers.d/marqdo-harness 编辑并校验语法
# 注意替换 devuser;下面允许该 VM 的此用户免密执行任意 sudo 命令
devuser ALL=(ALL) NOPASSWD: ALL
```
保存后用 `sudo visudo -c` 校验,切回 Harness 的开发账户执行 `sudo -n true`。如果无法通过,不要让 Harness用 `sudo` 的失败来推断内核缺少 namespace;先检查 Harness 自身终端 sandbox/权限审批、宿主 sudoers、父级容器限制。**完成开发后移除临时 sudoers 规则**(在管理终端执行 `sudo rm /etc/sudoers.d/marqdo-harness` 并再次 `sudo visudo -c`)。
这只是针对可销毁 VM 的开发便利设置,不应提交仓库、提供给普通 Marqdo 用户或用于发布的普通用户权限测试。不要把 root 作为 `marqdo` 普通运行的系统要求。
### 3.2 开始执行前输出环境基线
```bash
set -u
whoami; id; id -u
sudo -n true && echo 'SUDO_NONINTERACTIVE_OK' || echo 'SUDO_REQUIRES_APPROVAL'
cat /etc/os-release
uname -a
rustc -Vv; cargo -V; git --version
command -v cc || true; command -v python3 || true; command -v node || true
command -v bwrap || true; command -v aa-status || true
systemd-detect-virt --container || true
findmnt -t cgroup2 || true
cat /sys/fs/cgroup/cgroup.controllers 2>/dev/null || true
sysctl kernel.unprivileged_userns_clone 2>/dev/null || true
sysctl kernel.apparmor_restrict_unprivileged_userns 2>/dev/null || true
sysctl user.max_user_namespaces 2>/dev/null || true
unshare --user --map-root-user true; echo "userns=$?"
unshare --user --map-root-user --net true; echo "userns_net=$?"
```
**记录诊断,而不是盲目修改系统:** `EPERM` 可能由 Docker/LXC 的父级 seccomp、AppArmor、namespace 上限或权能限制导致。`sudo` 可能解决某一子项,也可能完全不能绕过上级容器配置。若不能在普通用户环境下可靠测试 strict,请建立专用可控的 Ubuntu VM 或 self-hosted security runner,不要在普通 CI 上假装执行了安全逃逸测试。
Ubuntu 24.04 AppArmor user namespace 参考:https://documentation.ubuntu.com/release-notes/24.04/ ;Bubblewrap 机制说明:https://github.com/containers/bubblewrap 。
### 3.3 Harness 的权限管理边界
1. `cargo build/test/clippy/fmt`、Git 修改/提交和普通 `.mq.md` 的 run:**非 root**。
2. 安装 apt 依赖、`apparmor_parser`、配置测试专用 namespace/cgroup 管理权:**按需 `sudo`**。
3. 用 root 建立隔离机制可行,但子程序必须降权并验证有效 UID/GID 与实际受限权限。
4. 每个涉及 `sudo` 的系统变更都记录操作命令、变更前后值、回滚方式和验证结果。
5. 不运行项目依赖中未知的安装脚本,不允许“为了测试通过”关闭 `strict` 的拒绝逻辑。
6. 如在 root 环境可运行而普通用户不能运行,则判定**普通用户支持门槛仍失败**,而不是宣称 strict 可用。
7. 不以当前主机没有敏感信息作为放弃安全负例测试的理由:发布给他人的 CLI 将运行在拥有真实数据的主机上。
### 3.4 建议工作区组织
```text
marqdo-cli/ # 正式受版本控制的代码
docs/STABLE_RELEASE_IMPLEMENTATION.md
docs/STATUS.md
docs/adr/...
crates/...
spec/...
tests/...
.github/workflows/...
../marqdo-security-lab/ # 测试脚本、恶意 fixture、临时沙箱数据(如需要)
../marqdo-evidence/ # 日志、真实 CI ID、检查报告(不要误提交敏感环境值)
```
系统测试 VM 快照/恢复流程应单独保存,**发布不能依赖当前开发主机的隐含配置**。
---
## 4. 发布目标、版本语义和范围
### 4.1 什么叫“稳定版”
稳定不是“所有想象功能都实现了”,而是**所有明确承诺的接口、执行能力、平台支持和安全语义都经测试成立,并对未来版本有可持续兼容约束**。
建议实行:
- **Linux Ubuntu x86_64:** 首个优先稳定目标,支持语言、包、Tool、Analysis/Trace、ABI、Foreign 的已声明子集。若版本对外宣称 `strict` 可用,则该 Ubuntu 平台必须完成 G-C 安全门禁。否则发布中只能明确写“strict 不可用”,不得虚称完整安全版。
- **Windows / macOS:** 可作为 Core Stable 支持平台,但只有对应原生 runtime / Tool / 外部协议 / 包环境测试全部通过才能列为支持平台;未实现 strict 的平台持续 fail-closed。不必为了跨平台严格沙箱而让 Linux Core 永远无法发布。
- **Foreign Python/Node:** 支持已声明、已固定/校验的 Provider 与环境;自动下载、安装包和运行任意 npm/uv 脚本不是语言核心的稳定性要求。如果发版文案承诺“自动物化 uv/npm 环境”,就必须实现独立可复现的流程、相应测试和 provenance;否则不作该承诺。
- **Knowledge/Proof/View:** 不存在于 CLI release bundle,只有公共 Tool/Analysis/Trace 兼容合同;不发布它们的功能性声明。
### 4.2 版本命名建议
当前工作区版本在基线附近为 `0.1.0`。不应因“用户希望稳定”就机械增加版本号:
1. 先做工程内部 Milestone `release-candidate`,通过第 5–12 章全部适用门槛;
2. 以 `v0.2.0-rc.1` 等候选版本演练(实际具体号应先检查现有 tags/releases 和 semver 计划);
3. 若语言、公开 ABI、Tool、Analysis/Trace 和包文件格式的兼容承诺均已冻结、受支持平台测试为绿,可考虑发布 `v1.0.0`;否则也可以发布明确定义稳定支持范围的 `v0.2.0`,不冒充全部能力稳定;
4. 任何标签都不能代替 CI、源码、release asset 与校验和证据。
### 4.3 分离的三道门禁
- **G-A / Ecosystem Development Ready:** 通用 Tool + Analysis/Trace 可以被陌生外部消费者读取,适合开始 View/Knowledge/Proof 独立开发。当前源码接近具备,不要求 strict。
- **G-B / Core Stable:** 当前承诺的语言/包图/协议/Native/Foreign 已严格测试;Linux CI 全绿,Windows/macOS 对支持平台全绿,文档/兼容矩阵真实。为稳定核心版本的必要条件。
- **G-C / Linux Strict Verified:** 在有权限和机制的 Ubuntu 环境执行真实 OS 隔离与逃逸测试通过;未通过平台拒绝,不隐式降级。只有声称支持严格隔离才需要对相应平台取得 G-C。
**本次用户期望:** 建议 Harness 尽力把 Ubuntu Linux 的 G-B + G-C 全部完成,同时修正 Windows/macOS 的已确认 CI 失败并提升跨平台真实测试;不能因个别环境缺少 namespace 自动认定工作已经完成。
## 5. P0:先把所有平台的现存 CI 测试修到真实全绿
> 优先级:Release blocker。必须在开发严肃隔离功能之前解决。完成后才有可信的回归基线。
### 5.1 Windows AST golden:先证明是字节问题还是语义问题
**证据:** 远程 `e966b766` 的 Windows job 在 `crates/cli/tests/conformance_ast.rs:134` 失败;`001-atx-h1.mq.md` 报告 expected != actual,但 `.lines()` 比较显示“0 line(s) differ”。`conformance_ast.rs::golden_text` 对 AST 序列化加一个 LF,`report_mismatch` 用 `.lines()` 打印,因此最有可能是 expected 中 CRLF 与 actual 中 LF 不一致;此为**高可信假设,尚须字节测试确认**。
**实施步骤:**
1. 在 Windows runner 或 Windows VM 取 `tests/conformance/ast/001-atx-h1.ast.json` 原始字节,记录 `CRLF`/`LF` 数量、文件长度及第一个不同字节。不要靠肉眼看渲染文本。
2. 在 `crates/cli/tests/conformance_ast.rs` 添加更有用的字节级差异诊断:首个不同字节位置、附近转义十六进制、是否仅行尾不同。**不要**修改 Markdown 语法来迁就测试文件换行。
3. 采用统一且可重复的金样存储策略。优先通过 `.gitattributes` 为 `.mq.md` / `.ast.json` / `.json` / `.yaml` 等需严格字节身份的规范 fixture 指定 `text eol=lf`;但若 `.mq.md` 语义测试需要保留 CRLF 特例,必须把这些特例单独设计为字节 fixture,而不是盲目全量归一化。
4. 在 `git add --renormalize` 后审查变更,避免意外修改语言原始文本或 Span 测试的期望。对依赖原始字节 Span 的 case,明确分别测试 LF/CRLF 输入的行为。
5. 再运行 `cargo test -p marqdo-cli --test conformance_ast` 于 Windows、Ubuntu、macOS,确认 AST 金样一致或将正当的换行行为作为显式语义规则。
**强制负例:** 人为更改 AST golden 的一个节点名称/Span 必须失败;仅当 profile 有经 ADR 批准的语义变更才可使用 `UPDATE_GOLDENS=1`,并提交完整 diff 审查。**绝不以批量重生成 golden 代替定位根因。**
**完成证据:** Windows 失败 fixture 再现后已消失;LF/CRLF 的语言语义与 Span 测试有独立可检查预期;同一 golden 由至少 Linux/Windows 读取通过。
### 5.2 macOS 插件测试:构建当前平台 artifact,不能依赖 Linux 目标
**证据:** `crates/cli/tests/integration_cli.rs::plugin_inspect_and_explicit_trusted_invocation` 在 macOS `aarch64-apple-darwin` 报 `no_matching_artifact`;仓库示例 `examples/plugin-demo/plugin.yaml` 只声明 `x86_64-unknown-linux-gnu`,`build.sh` 强制输出 `.so` 且使用 Linux `sha256sum`。
**必须改成两层测试:**
1. **跨平台的 Manifest/ABI 静态测试**:验证非本平台 artifact 时报告精确的 `no_matching_artifact`;不会隐式使用任意 `.so`/`.dll`/`.dylib`;不加载代码。可以跨平台无条件运行。
2. **真实动态库执行测试**:仅在本平台已构建兼容目标的 artifact、C 工具链具备时运行;Linux 使用 `.so`,macOS 使用 `.dylib`,Windows 使用 `.dll`;构建脚本/测试 harness 生成临时清单与正确 SHA-256。不能把不存在的平台产物当作语言解释器错误。
**建议实现:** 将示例插件构建逻辑抽成测试 helper(使用 `rustc -vV` 的实际 `host`、平台动态库后缀、可用 C 编译器),构建产物和 `plugin.yaml` 写入 tempdir。原 `examples/plugin-demo/build.sh` 可保留为 Linux 开发示例,但不能成为所有平台 CI 的隐含前提。**不要在测试中原地修改仓库内受版本控制的 `plugin.yaml`。**
**测试要求:** 当前平台成功 `plugin inspect` + Native(显式 trust)调用 + Worker 调用;故意给出其他平台 target 必须失败;错误 sha256、错误 ABI major、缺导出、多导出冲突必须失败且不发生隐式加载。
**完成证据:** macOS workspace 与相应 Smoke PASS;Windows 的 C ABI 动态库/Worker 测试若尚无条件,明确单列未支持并不得在发布矩阵中宣称已验证。
### 5.3 CI 自身的验证质量
需要把 `.github/workflows/ci.yml` 调整成**失败归因清楚、证据独立且不得静默跳过**的门禁:
- Linux 核心 job:`cargo fmt --all -- --check`、`cargo clippy --workspace --all-targets -- -D warnings`、`cargo test --workspace`、示例 smoke。
- Schema job:从真正 CLI 产出 Analysis v2、Trace v2,按相应 JSON Schema 验证,同时用独立 Python 消费者读取、验证 digest/stale 与非法输入。
- macOS / Windows:所有宣称可移植的核心测试真正运行,而不只 `cargo check`;C ABI/Worker/Foreign 运行测试必须单独明确 supported/skipped/failed,而非空测试视为成功。
- Linux strict security lane:**独立**于普通 CI,见第 10 章;不把缺权限普通 runner 的 `EPERM` 当作隔离机制已通过。
- Release job:只针对同一 SHA 的所有必需 job 成功才允许发 tag 或上传发行资产,禁止在红 CI 上发布。
CI 中任何 `#[cfg(unix)]` 或 `if tool_available` 跳过测试,都要有一张支持矩阵。**跳过不计为 PASS。** 外部依赖如 Python、Node、C toolchain、git,在目标平台应通过 CI 安装以保证该平台的承诺测试真正运行。
### 5.4 H0 验收命令
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p marqdo-cli --test conformance_ast
cargo test -p marqdo-cli --test integration_cli
cargo test -p marqdo-cli --test tool_protocol
cargo test -p marqdo-cli --test analysis_trace
```
每条命令必须以非 root 用户执行并记录运行时间、平台、退出码。CI 完成后将实际 SHA/URL 写入 `docs/STATUS.md`。如果有测试失败,下一轮仅专注修复,不开始以 `strict` 启用为目标的 PR。
---
## 6. P1:包图 lock v3、环境同步与正确性收尾
> 目标:继续使用现有 ADR-0016 与 lock v3,不重建包管理器,不增加 `tree/update/vendor` 命令;验证**真实可复现**而非“路径解析得到”。
### 6.1 现状与核心保证
`crates/marqdo-package/src/fileset.rs` 已将 `.git`、`.marqdo` 排除,限制普通文件、symlink、数量/大小/深度;`spec/package-format.md` 描述 package instance graph、完整依赖边、根 manifest digest 和严格 sync,`run/call/check` 不得自动下载或重写锁。
**不允许倒退到旧 lock v2 的“只锁第一层依赖”模式。** 正式版本的 lock v3 必须保证:同一来源/内容得到同一 package instance,不因缓存物理路径而变;路径/Git/传递依赖闭包完整;内容变化导致明确 stale,不能默默回退最新版本;同一个 alias 在不同 parent 下可以指向不同包实例。
### 6.2 必须补齐的测试与可疑边界
| 要求 | 正例 | 负例 / 破坏性输入 | 验收 |
|---|---|---|---|
| 跨目录确定性 | 项目复制到另一绝对路径后 lock/Analysis 与包身份一致 | 硬编码项目根路径 | 逻辑身份和摘要一致 |
| 完整依赖图 | A→B→C,B 与另一个包拥有同名 alias | 删除 C 的 lock 节点/依赖边 | 不能 `run`、`sync` 绕过缺失校验 |
| 多版本包 | B@v1、B@v2 并存 | 隐式选择先加载版本 | 唯一身份与显式引用 |
| Git pinned | 固定完整 SHA、已缓存离线重放 | URL/SHA/缓存内容篡改、修改 marker | 在加载前拒绝,不执行 hook |
| 文件集合 | 正常文件、排除 `.git`/`.marqdo` | symlink、特殊文件、超深、过大、遍历错误 | 锁和复制使用同一列表与字节 |
| 环境发布 | 已存在环境,原子更新成功 | 途中复制失败、无空间、并发 sync | 旧可用环境可恢复;不留半环境 |
| 锁严格 | `sync --locked` 与 `sync` 一致校验 lock | 旧 lock v1/v2、root manifest drift | 拒绝,并给出 relock 指引 |
| 检查副作用 | `check` 静态加载缓存资源 | 缺失 Git cache 时偷偷 clone | `check` 不发生网络写入/执行 |
### 6.3 建议代码落点
- `crates/marqdo-package/src/fileset.rs`:保持文件集 profile 的单一实现,增加错误路径和特殊文件测试;若优化 hash,必须与物化环境摘要一致。
- `crates/marqdo-package/src/lib.rs`:锁图解析、完整闭包、环检测、不可变已锁解析、cache marker 与原子 sync。
- `crates/cli/src/commands.rs`:`lock` 与 `sync` 命令只做交互装配,不自行重写 PackageResolver 的业务算法。
- `crates/cli/tests/package_env.rs`:通过真正 binary 验证 Git/path、传递边、stale drift 与跨目录行为;必要时在 `tests/fixtures` 增加稳定的小仓库 fixture。
**尽量不添加新抽象:** `SourceResolver` 已能处理 path/Git 时不要为了未来 registry 多建立“通用 source framework”。未支持来源明确报错即可。异常处理和缓存完整性优先于可扩展来源种类。
### 6.4 本阶段发布阻断项
如发现 `lock` 具有路径依赖不稳定、包内容变更未发现、物化时漏项、`sync` 会破坏现有可用环境或 `run/check` 在未锁定时自动获取依赖,则**阻断 G-B**。但不需要在本阶段开发公共包市场或网络下载代理。
---
## 7. P2:Analysis / Trace / Tool 公共协议最终稳定化
> 目标:证明三个外部仓库只依赖 CLI 已发布协议就能获得真实结构与执行证据,核心无须为它们写任何专门代码。
### 7.1 Analysis v2 应维持的合同
`marqdo check <file> --emit analysis.json` 必须:
- 仅静态解析/语义分析,不执行任何 `.mq.md` 指令、不加载动态库、不启动 Foreign;
- 输出明确的 `schema: marqdo.analysis`、`schema_version: 2`、语言 profile、生产者版本、逻辑项目身份、包实例/模块身份、源码摘要;
- 输出可用的函数签名、受支持的函数体语义节点、call/reference/import 边、作用域、资源信息(Formula / Code,包括来源 Span 与 digest);
- 跨机器/跨目录移动相同源与锁时不出现物理路径污染;
- 写入以原子方式完成;静态错误禁止遗留旧成功 artifact;
- 不声称“已经证明”“已经执行”“Unknown effect 是纯函数”。
**独立消费者最小验证:** Python / JavaScript 任意一门非 Rust 语言实现约百行样例,读取 `analysis.json`,查找指定函数、查找资源来源、解析跨模块调用、验证 Schema 与字节摘要。故意以 v1/v99 和错误来源 digest 输入时正确拒绝。
不要把 `marqdo-ir` 用 serde 直接输出,也不要继续叠加 `inspect --ir` 的私有格式作为公开 API。Proof 将来需要类型和语义模型的额外属性时,由独立消费用例驱动 `Analysis v2.x` 附加字段或 `Analysis v3`,而非现在就设计完整 Proof IR。
### 7.2 Trace v2 应维持的合同
`marqdo run/call --trace-file trace.json` 必须:
- 每个含 Span 的事件有真实 `module_id`;入口文件与被导入模块错误不会混淆;
- Trace 的 `analysis_digest` 等于按规范计算的同一项目 Analysis 产物字节摘要,并可识别 stale;
- 调用、分支、循环、返回、Host effect 的全局 sequence 单调;
- 大循环触发事件数/字节预算后记录 `trace.truncated`,不把执行结果改成成功或失败的错误状态;
- 默认不记录密钥、任意文件内容、插件 opaque handle;
- 没有实际执行的 `check`、View 阅读态等操作不能伪造 Trace;
- 截断、错误路径、取消和写盘失败时有清楚状态而不是半合法成功 JSON。
**额外稳定性测试:** 长时间运行的循环、含跨模块调用的链、插件/Foreign effect、超大输入、写盘失败、trace cap=0 的无限制语义(如允许此选项则须对内存保留边界),事件按模块追溯源码。考虑为实际写入模式增加流式或受限内存实现,但**只有已经观察到风险/压力测试失败时**才进行大规模重写。
### 7.3 Tool Protocol v1 应维持的合同
`marqdo tool install ./tool.json`、`list`、`remove` 和未知子命令分发:
- 工具名来自 manifest,官方与第三方无任何优先接入差别;保留核心命令优先、命令名冲突拒绝;
- 整包(不止入口文件)摘要与文件列表,在安装与运行时校验;目录逃逸、symlink、缺失/多余文件明确拒绝;
- `compatibility.marqdo` 用标准 SemVer;使用 Analysis/Trace 的工具在安装与 dispatch 时检测其支持的协议主版本;
- 保留调用者 `cwd`、stdin/stdout/stderr、原样 argv Unicode 参数和真实退出码;不用 shell 拼接执行;
- 不扫描 PATH 中的未知可执行文件并直接赋予 `marqdo` 子命令权限;
- Tool 本身不获得任何语言内部 Host API 权限;允许 Tool 自行通过公开 `marqdo check/run` 命令获取产物;
- 软件包安装失败必须回滚,删除不能越出 Tool home;可预防同目录并发安装与删除导致的污染。
**发布兼容测试:** 用源码中根本没提到的随机合法 command 名、独立 Python/Go/Rust 二进制,调用安装、执行、升级(首版可用 remove+install)、参数与退出码、篡改与拒绝。更换工具名或实现语言不能需要重新编译 `marqdo`。
### 7.4 协议演化与兼容矩阵
| 范围 | 已有版本 | 兼容性政策 |
|---|---|---|
| Markdown profile | `marqdo.md.v1` | 语义变更单独 ADR + 金样 + profile 版本 |
| 语言/CLI | workspace 版本当前 `0.1.0` | 稳定发布之后按 SemVer;CLI flags 破坏要明确声明 |
| `marqdo.lock` | v3 | 旧 v1/v2 明确拒绝,命令给出 relock 指引 |
| Analysis | v2 | 不兼容结构变更升级 major;消费者拒绝未知 major |
| Trace | v2 | 同上;source digest/staleness 语义固定 |
| CLI Tool | v1 | Manifest schema、version negotiation、bundle hash 稳定 |
| ABI | v1 | 不允许不经版本协商破坏二进制 layout |
| Foreign wire | 当前受支持版本 | 每次协议变更需独立 provider 的兼容测试 |
每项协议必须有**有效实例测试 + 非法实例测试 + 独立消费者测试**,而不是仅检验 schema 文件能被 `json.loads` 解析。任何协议示例都要与当前代码真实输出一致,不可以靠手写 JSON 代表测试。
---
## 8. P3:Foreign Provider / Python / Node 的环境闭环(B-12)
> 目标:修复“完整性校验存在,但环境关联与解释器选择可能不一致”的真实边界。不要把 uv/npm 发展为内核的另一个包管理器。
### 8.1 当前设计事实
`crates/marqdo-foreign/src/lib.rs` 已具有 `KernelRegistry`、外部 `KernelDescriptor`,后者可声明 `digest`、`environment_id`、`environment_digest`、`environment_dir`、`interpreter_version`;外部 provider 与其环境目录在注册及实际 spawn 前校验 SHA-256。环境目录的文件集禁止 symlink 和特殊文件,并有资源上限。已有 provider 正反测试。
**仍需专项核验:** 当前 `execute()` 会先 `resolve_program(descriptor)` 得到可执行路径,之后设置子进程的 `MARQDO_FOREIGN_ENV` 和扩展 `PATH`。对于显式外部 provider,其入口是 descriptor 的绝对路径;对于内置 Python/Node,`resolve_program` 用宿主 PATH 找出可执行文件,再给子进程增加环境 `bin`。因此校验了某个环境目录,并不自动意味着运行的解释器就是该目录中的解释器,也不自动意味着解释器依赖只来自固定环境。这是**代码可见的语义缺口/需要契约明确的行为**。
### 8.2 必须先决定“谁负责环境创建”
推荐设计:
1. **Marqdo Core 负责**:解析外部 Kernel manifest、明确 provider executable、校验 provider/env 内容摘要、在发起运行前校验版本协议、提供纯粹的生命周期/授权/超时/结果封装。
2. **可选、明确授权的外部 Provisioner 负责**:创建/下载 Python uv 或 Node npm 依赖,产生固定可执行路径、环境摘要和可审查的 recipe/lock;此工具可以通过通用 Tool Protocol 提供,但不能要求 CLI 特判它的名字。
3. **项目作者负责**:把 Provider 描述和所需环境工件/recipe 显式提交或登记。同步或检查 `.mq.md` 不隐式执行第三方安装脚本。
4. **不能宣称未实现的能力**:若没有自动物化功能,稳定版文档明确“支持固定环境验证,不自动创建”;这并不妨碍 Foreign v1 成为稳定的、范围明确的协议。
如果本轮确实要补齐 B-12 的**自动创建**,建议只交付一个**独立可执行的参考 provisioner**,在 `examples/` / `tools/` 作为单独 Tool fixture;让其对固定 uv lock / npm lock 做显式、可审计安装并输出 environment descriptor。不要在 `marqdo sync` 中引入运行 npm 生命周期脚本的隐式步骤。Tool 可以先支持最简单两种 recipe,不做通用软件包管理平台。
### 8.3 运行时必须绑定真实解释器与环境
- 如果 provider 声明 `environment_dir`,定义它是“只提供资源路径”还是“必须使用其解释器”;接口不能含糊。对于完整可复现模式,优先**固定 provider 可执行文件绝对路径与摘要**,并明确环境下的解释器和模块导入目录。不能只靠 prepend PATH 获得正确执行语义。
- 对环境内真实 interpreter 的定位规则必须稳定且可验证。若固定环境没有声明的解释器,则 fail-closed,不能回退宿主 `python3`。
- Python `sys.executable`、`sys.path`;Node `process.execPath` 和模块解析路径必须纳入测试证据。平台不同的 `bin/`/`Scripts/` 差异不能隐式假定相同。
- `interpreter_version` 如声明则必须做匹配检查或明确仅为展示字段;不能写了字段但实际不检查却宣称环境完全固定。
- `environment_digest` 必须和运行环境绑定;资源改动应在 spawn **之前**拒绝,已启动子进程不被实时文件改变强保证覆盖(不保证 TOCTOU 不可能,若需要强保证应从受保护的 immutable snapshot 启动)。
- Foreign 的授权仍由 Host 完成;`env_clear`、临时 cwd 和超时只是安全卫生,不是对恶意 Python/Node 的 OS 沙箱。
### 8.4 测试矩阵
| 测试 | 输入 | 期待 |
|---|---|---|
| 固定 provider 正例 | 明确绝对路径 + 正确 SHA + 完整环境 | 成功执行、产出 wire 值 |
| Provider 篡改 | 校验后修改可执行文件 | spawn 前拒绝 |
| Env 篡改 | 在环境目录中增删/修改普通文件 | spawn 前拒绝 |
| 双 Python 测试 | 宿主 Python 与环境 Python 明显不同 | 实际 `sys.executable` 与声明约定一致 |
| 双 Node 测试 | `process.execPath` 与声明不一致 | 明确失败或按定义选择固定解释器 |
| 版本漂移 | 更换解释器、版本标签错误 | 不得当作成功固定环境 |
| symlink/特殊文件 | 添加 symlink/FIFO | 检查拒绝 |
| 无授权 | 未提供 `--allow-foreign` | 绝不启动子进程 |
| 超时与进程树 | provider 创建子进程并卡住 | 所有可管理后代清理,无残留 |
| 不受支持系统 | 外部 Kernel 无平台适配 | 清楚提示不可用,不能冒用宿主默认 |
**门禁:** 上述固定环境行为、协议、可靠退出和基本 Foreign 测试必须在宣称提供 Foreign 稳定支持的平台通过。uv/npm 自动创建功能可以作为独立参考工具附带,也可以明确不属于首个核心稳定版;不要留下“似乎已经自动创建”的文档错觉。
---
## 9. P4:C ABI、Worker、能力代理及故障隔离完整性(H3-A)
### 9.1 不要把三种安全保证混为一谈
- `CapabilityBroker`:授权与 Host 受控代理。它可以拒绝 `fs.read` 越权请求,但**不能阻止 native/worker 插件直接调用系统函数**。
- `Worker`:地址空间与异常隔离,避免原生插件 crash 直接杀死解释器,支持 IPC timeout/请求限制。它仍然通常以用户权限运行。
- `Strict OS isolation`:操作系统强制的文件系统、网络、进程和资源边界;须 G-C 真实测试才能对不可信代码声明安全。
### 9.2 当前已经具备的能力
ADR-0018 已定义 worker `capability_request`/`capability_reply` 与请求 ID、Host 绑定真实插件身份、单次调用 deadline;当前已经通过 `ProjectFs` 实际执行获授权 `fs.read`,Native/Worker 都有测试,单次 64 次、每次 64 KiB 请求预算。**不要重做一个全新的 RPC 框架。**
### 9.3 仍需完成的工程工作
1. **Session / invocation 身份与生命周期**:Host 绑定 `worker instance + package + run/session/generation`;消息中声称的 package/id 不能获得权限;跨 invocation 旧句柄不可冒用。已有 `PluginHandleTable` 应继续成为权威表。
2. **实际可用能力名单**:当前仅 `fs.read` 构成完整实际服务闭环。`fs.write`、`net.request`、`process`、`clock`、`random` 等不能因为“Broker 返回允许”就被宣称已经提供完整实际代理。如果不在本版承诺,返回 `capability.unavailable` 且有稳定错误码;严禁返回空成功骗过插件。新增实际 Host API 仅从明确用途和可测试 contract 出发。
3. **Worker 传输失败后不能复活**:半帧、超长帧、错误 reply id、EOF、无效 JSON、进程 crash 后应标记会话失效并 kill/reap。不能继续使用可能错位的 frame。
4. **预算**:每 invocation 的 Host capability 请求数、字节数、完成时间包含往返;CPU/内存/子进程树独立于这些 IPC budget,不能以其中一项替代所有资源限制。
5. **动态库真实 ABI 合同**:测试结构体布局、大小、对齐、版本协商、导出名称唯一、不同前缀多导出、调用参数合法性、Wire 出入的所有基础 Value 类型;不依赖 Python SDK 才可使用。
6. **严格模式 Native 禁止**:`--trust-native-plugin` 在 strict 中必须拒绝。即便将来允许 Worker 在 strict,也要确认 Worker 由严格 Supervisor 派生且继承限制,且没有未受控系统调用权限。
### 9.4 建议测试
- Native grant `fs.read` 返回允许文件真实内容;拒绝未授权路径,审计有 owner 与结果;
- Worker 相同正/反例,带两个不同插件,不允许身份串用;
- 合法句柄在同 run 内可读写其对应资源;猜测 handle、跨 run、过期 generation、被卸载后重用都拒绝;
- 错误/重复 reply id、先发 capability reply、恶意 frame 嵌套与字节预算越界;
- Worker crash/timeout 解释器幸存、进程和管道全部回收;
- 同名 export 冲突必须提前报诊断;签名不匹配在 `check --plugin` 被拒绝,不靠运行时猜测;
- C 代码由另一仓库/独立 fixture 编译,不依赖核心 Rust 内部私有类型;
- 在 Linux、macOS、Windows 各支持平台使用真实动态库而不是只编译测试 Rust crate。
不要求这一版把所有可能的 Host API 都开发出来;只要**承诺可用的 API 确实闭环,其余明确拒绝**,并保持 ABI 不变,就能成为稳定的受限服务子集。
---
## 10. P5:Ubuntu Linux strict OS 隔离实现与安全验收(H3-B / G-C)
> **这是独立安全工程,不是给 `--mode strict` 放开一个布尔值。** 当前 `crates/marqdo-sandbox/src/lib.rs::PlatformCapabilities::detect` 对所有平台返回 `StrictIsolation::Unavailable`,是 ADR-0019 要求的正确 fail-closed 状态。开发任务是实现**真正可强制执行的 Linux 适配器**并通过完整测试,然后只在通过的环境上报告 Available。
### 10.1 Ubuntu namespace 失败究竟意味着什么
此前开发环境的 `unshare`/`bwrap` 返回 `Operation not permitted`。原因未必是缺 root:可能是受限容器禁止创建新 namespace、AppArmor 限制 userns、user namespace 数量为零或 cgroup 未受委派。**不能以一条 `sudo unshare` 成功来证明普通用户 `marqdo run --mode strict` 可以成功。**
建议 Harness 为其选择一台真正可控制的 Ubuntu VM,并留下环境报告:`id`、`uname -a`、`systemd-detect-virt`、AppArmor profile/sysctl、user namespace / net namespace probe、cgroup v2 controllers 和权限。用户允许在该专用开发 VM 内 sudo 做必要配置。遇到 AppArmor 限制,优先为 sandbox launcher 配置有界的专用 AppArmor profile;不要在发布验收中依赖全局关掉保护。Ubuntu AppArmor 已发布的文档中讨论了特定程序 `userns` 权限的正确授权模型。
如果当前宿主实际上是容器而父级拒绝 namespace,Harness 必须:
1. 记录无法完成安全验收的具体 `EPERM` 和运行环境信息;
2. 将安全测试迁到有权限的专用 Ubuntu VM/self-hosted runner;
3. **不要**将 `strict` 从 Unavailable 改为 Available;
4. 继续做不依赖该机制的 G-B 开发;
5. 不能宣称已经完成 G-C,直到真实安全 lane 通过。
### 10.2 最小可行安全架构
```text
marqdo run doc.mq.md --mode strict
│
CLI option parsing
│
Strict Supervisor (trusted)
│
┌─────────────────┼─────────────────────────┐
│ │ │
runtime OS probe capability policy resource budget
│ │ │
├─ mount/user/PID/NET namespaces │
├─ filesystem allowlist + readonly roots │
├─ seccomp / no_new_privs / no ambient caps│
├─ cgroup v2 or equivalent hard limits │
├─ inherited fd/env whitelist │
└─ process-tree supervisor/reaper │
│
Restricted execution child
non-root effective uid
interpreter + authorized Host
│
result + trace
```
可优先使用外部已维护的 Bubblewrap(固定版本范围、运行时能力检测)构造隔离边界,并补齐其未覆盖的 seccomp、cgroup/rlimit、FD、子进程树和错误处理。必要时在 `marqdo-sandbox` 内实现极小的受信 Supervisor,而不是自己重造一个通用 OCI 引擎。**Bubblewrap 只是构造机制,不是自动通过验收的证书。**
`strict` 的 CLI 表面不变;`marqdo-sandbox` 负责:
- `CapabilityProbe`: 检查每项机制是否可获取(非 root 能否启动、本次执行是否可配额);
- `PolicyBuilder`: 从当前 `--allow-*` 与沙箱模式导出**最小白名单**;
- `Launcher/Supervisor`: 为子程序搭建隔离、设置资源控制、管理文件描述符与进程树、回传结构化错误;
- `SecurityEvidence`: 运行时报告实际启用的机制,而非仅报告内核理论支持。
不要为此在 CLI 增加 `sandbox` 顶层命令,也不要让 Source Parser 自己实现 Linux namespace API。保持 `marqdo-sandbox` 现有职责,直接拓展受控实现。
### 10.3 按三个递增层级交付,不许跨级跳过测试
**L0 — 只验证机制可获得,默认 strict 仍不可用。**
- 在测试 VM 运行 `unshare`/Bubblewrap 基础探测;记录 UID/GID mapping、mount/PID/network namespace、cgroup 控制器权限及可用 AppArmor / seccomp。
- 提供对每项实际机制的错误原因;probe 只能判定环境,不能把“可用 namespace”当作整个 strict 已可用。
- 安全 fixture 和环境日志进入测试 evidence。普通用户无权限时维持不可用。
**L1 — 最小纯语言 strict。**
- 仅允许解释器、内置 Math、无不受控执行能力的 Host 操作。外部 ABI、Foreign Kernel 在本级 `strict` 中明确拒绝,直到它们真正继承隔离约束。
- 项目文件和固定包资源按白名单映射;默认只读;外部 `/etc`、`$HOME`、`/root`、其他项目目录不可读写。允许访问的 runtime/libs 只提供必要最小只读视图;不要把整个主机根目录映射进沙箱。
- 网络默认禁止;出站连接、监听、抽象 Unix socket、外部可达服务均需要检查拒绝能力。不允许利用 `/proc`、`/dev` 或继承文件描述符绕过。
- 新进程默认不允许;如果解释器必须允许某种内部运行机制,则显式限定路径与时机,不能让用户文档间接运行任意 shell。
- CPU、内存、运行时长、最大输出、文件描述符、进程数均有可验证的硬/软边界。实现超时后清理整棵进程树,不能残留子进程。
- 如果任何机制无法应用,必须在真正执行用户代码前失败,不得降级 `project`。`inspect --platform` 报真实原因。
**L2 — 扩展进程的严格继承。**
- 在已经通过 L1 后,允许明确受控的 ABI Worker 或 Foreign Provider 在严格 Supervisor 的**同一隔离域/等价更严格隔离**中运行;它们不允许脱离 sandbox 创建宿主进程。
- 真实 Plugin CapabilityBroker 仍做应用级授权,OS sandbox 额外兜底即使插件调用原生系统 API 也无法访问未授权对象。
- `--trust-native-plugin` 在 strict 下始终不可用,除非未来有彻底不同的可信模型和新 ADR;不要把其编译进同一用户进程。
- 如果某一平台只支持 L1,允许该平台将 strict 报告为**只支持纯语言**,但 CLI 调用 Foreign/Worker 时必须确定拒绝并在支持矩阵注明;不要把它展示成“strict 中可任意运行插件”。
### 10.4 root / sudo 的正确使用
- Harness 可 `sudo apt install`、设置专用 AppArmor profile、创建 VM/systemd 资源测试环境,也可用 root 创建测试隔离设施;
- **最终测试必须从普通用户执行 CLI**,并在隔离子程序中用 `id -u` 或等效行为证明没有宿主 root 权限;
- root-only 的内部 supervisor/helper 必须最小化可执行入口、严格拒绝任意路径与命令注入、降权、设置 no-new-privileges、关掉额外 fd/ambient caps;
- 不把 `sudo` 加进 `marqdo run` 的公开用法,不能要求最终用户全程 root 才能使用语言或 strict;
- 若 VM 无法委派 cgroup 或沙箱工具不支持必要机制,则在该配置上保持 strict unavailable。可新增一个受控 **security-lab** 自托管 CI runner,不以通用 CI runner 的权限缺口拒绝整个 G-B 交付。
### 10.5 安全测试矩阵(全部是运行时反例,不是静态断言)
| 测试族 | 测试方法 | 失败时必须怎样 | 通过标准 |
|---|---|---|---|
| 已授权 project read | 允许目录内已知文件 | 不该因无关路径被拒绝 | 正确读取,记录机制 |
| 未授权文件读取 | `/etc/...`、`$HOME`、其他项目、绝对路径 | 返回拒绝,无数据泄漏 | OS 层直接 syscall 也失败 |
| 写越界 | `../`、绝对路径、符号链接换指向、交换目录的竞争 | 不产生目标文件 | 不出现 TOCTOU 写入 |
| 设备与 proc | 访问 `/proc/*/fd`、宿主 `/dev`、已继承 fd | 不读到宿主敏感对象 | fd/mount 隔离正确 |
| 网络 | IPv4、IPv6、DNS、Unix socket、loopback | 连接建立失败/不越界 | 默认 deny 且可验证 |
| 进程生成 | fork/exec/后台子进程、进程组逃逸 | 拒绝或受限;无遗留子进程 | supervisor 完成清理 |
| CPU 限制 | 无限循环或受控忙循环 | 达预算后被停止 | 不占满宿主直到人工干预 |
| 内存限制 | 大量分配、内存映射、容器构造 | 预算内拒绝/杀死子进程 | 宿主保活 |
| FD / proc 数 | 打开大量 fd、快速创建进程 | 在限额拒绝 | 无资源逃逸 |
| 输出与时间 | 持续大输出/长时间卡死 | 到限后停止并报告 | 不无限增长 log |
| Native ABI | `--trust-native-plugin` + strict | **明确拒绝** | 拒绝发生在加载/执行前 |
| Worker/Foreign | L1 时显式请求运行 | **明确拒绝** | 未产生外部进程 |
| Worker/Foreign | L2 时 OS 直读越权 | OS deny | Broker/Worker 不可绕开 |
| 机制缺失 | 关闭某个测试用资源控制或人为拒绝 userns | strict unavailable | 绝不降级执行 |
| 非 root | 普通用户正常执行 strict 支持子集 | 支持时成功;不支持时拒绝 | 不能只有 root 成功 |
**注意:** 某些 Marqdo 程序本身不具备“直接发 socket / fork”的语法。为了真正验证 OS 边界,测试必须在**同一 Sandbox Launcher / 隔离策略**下运行独立的恶意原生测试 helper;只通过 Marqdo Host 权限拒绝不能证明 Linux sandbox 防 syscall 绕过。
### 10.6 安全 CI 运行方式
建议 `.github/workflows/security-linux.yml`(或现有 workflow 的独立 security job):
- 指向受控 Ubuntu VM/self-hosted runner,明确 CPU/内存/cgroup/userns/AppArmor 等可用;
- 执行真实隔离子进程与恶意 helper;
- 输出经过脱敏的机制 probe、隔离后的 UID/GID、mount/net/cgroup 状态和每个拒绝用例结果;
- 任何逃逸测试未运行、被跳过、意外成功都使 **G-C 失败**;
- 首次实现时使用 ADR-0020(建议编号,以当前仓库实际序号为准)记录 Linux 机制/威胁模型/依赖/拒绝规则;
- G-C 仅在该平台 lane 完整通过、审查已实施隔离后才能将 `StrictIsolation::Available` 打开。
**如果安全 lane 所需硬件无法获得:** 保持 `strict` 故意不可用,可以发布明确标注“不支持执行不可信代码”的 G-B Core Stable,但**不能以此版本对外宣称 G-C 或 Linux strict 已完成**。若本次 release 明确要求 G-C,则这一事实就是发布阻断,必须找到合适测试 VM 而不是简化门槛。
---
## 11. P6:稳定性与跨平台完整质量门禁(B-14、资源、诊断)
### 11.1 测试层次与证明范围
| 层 | 具体测试 | 不能代替的其它层 |
|---|---|---|
| 单元 | Parser、Value、Path/Manifest、SemVer、Broker 等 | 不能证明 CLI 子进程行为 |
| 金样 | Markdown AST、语义执行、负例 | 不等于跨平台 Byte-for-byte 一致 |
| CLI 黑盒 | run/call/check/add/sync/tool、参数、输出、退出码 | 不等于独立协议消费者可用 |
| 协议契约 | 真正产出 JSON、Schema+负例、跨语言消费者 | 不等于可安全运行恶意程序 |
| ABI integration | C lib、Native+Worker、多 export 与权限 | 不等于进程 OS 沙箱 |
| Foreign integration | 固定 provider/env、双版本解释器、超时 | 不等于 lock v3 包一致性 |
| 项目环境 | 多版本依赖、完整传递图、Git 缓存、物化 | 不等于公网上 registry 可用 |
| 压测/性质 | 流水线取消、无限循环预算、深递归、超大消息 | 不等于操作系统逃逸测试 |
| Security G-C | 真恶意 helper、网络/FS/进程/资源越权 | 不能靠 root 运行得到可信结论 |
| Release smoke | 安装打包产物、运行样例、验证 sha256 | 不等于源树 `cargo test` |
### 11.2 Rust 品质要求
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p marqdo-cli
cargo build --release --locked -p marqdo-cli
```
加固建议按可靠性排序:
1. **恐慌/越界**:未经信任的 `.mq.md`、JSON、IPC 帧和 lock 数据不得引起非预期宿主 panic 或栈溢出。对深度递归、庞大嵌套 List、无限 while、异常大值和跨模块错误增加限定性测试。已有 fuel/stack/output 预算要验证覆盖真实路径。
2. **线程与进程回收**:长时间运行 Worker、Foreign,故意杀死进程/关闭 Pipe;无僵尸、fd 泄漏、永不结束的等待线程。
3. **回滚与完整性**:Tool 安装与删除、Package sync、Analysis/Trace 写文件必须原子或能清楚失败,不能留下看起来合法但实际过期的产物。
4. **覆盖率/性质测试**:适当采用 proptest/cargo-fuzz 对 Markdown/表达式解析、JSON/Wire、lock v3 与路径处理,重点是**不崩溃、不失去确定性、不产生未授权 effect**;在 CI 无法负担时可建独立定时/手动 lane,而不是删掉。
5. **依赖审查**:保留 `Cargo.lock`、依赖版本固定与许可证审查;建议加入供应链漏洞扫描,但优先保证正确构建、CI 与发行资产完整。
6. **诊断**:用户错误必须有稳定 code、真实模块、可读提示。任何异常不能错误标注成入口文件或“已成功执行”。
### 11.3 平台支持矩阵必须真实填写
| 功能 | Ubuntu x86_64 | macOS arm64 | Windows x86_64 | 备注 |
|---|---|---|---|---|
| Markdown parser / Rust runtime | 必须 PASS | 发布平台则必须 PASS | 发布平台则必须 PASS | 语义金样严禁随意 regenerate |
| check/Analysis v2/Trace v2 | 必须 PASS | 必须 PASS | 必须 PASS | 独立消费者验证 |
| Tool Protocol v1 | 必须 PASS | 必须 PASS | 必须 PASS | 不依赖 sh,已有便携 Rust fixture |
| lock v3 path/Git | 必须 PASS | 发布平台则必须 PASS | 发布平台则必须 PASS | 不以 `#[cfg(unix)]` 空跳过计为 PASS |
| ABI Native & Worker | 必须 PASS | 要么有目标动态库 PASS,要么标 unsupported | 同左 | ABI 支持标签必须如实 |
| Foreign provider/env | 必须 PASS | 发布平台有对应测试才声称支持 | 同左 | 解释器与环境路径在不同 OS 不同 |
| strict | 需要 G-C 才宣称支持 | 默认 fail-closed | 默认 fail-closed | 不依赖其它平台同日实现 |
对 macOS/Windows 如果仅 Core Stable 被支持,发布说明必须明确 ABI/Foreign/strict 的细分状态。**不能因为 Linux 上可以运行,就无条件上传 macOS/Windows 发行二进制并宣称同等能力。**
### 11.4 发行包必须独立于源码工作树测试
正式发布时使用构建好的 `target/release/marqdo`、必要的发行文档/许可/完整性文件,在**干净目录**安装后执行:
- `marqdo --version`、`marqdo --help`;
- `marqdo run examples/hello.mq.md`;
- `marqdo call examples/factorial.mq.md 阶乘 --arg n=5`;
- `marqdo check examples/... --emit analysis.json`,独立消费者读;
- `marqdo run ... --trace-file trace.json`,校验摘要关联;
- `marqdo tool install` 一个随机名称工具,执行、删除、故意篡改拒绝;
- lock v3 项目 `marqdo sync --locked`,可重复物化并重跑;
- 本平台承诺的 Foreign 与 ABI 真实调用;
- Linux 如果发布说明宣称 strict,则在安全 runner 执行完整 G-C;未宣称 strict 则验证 fail-closed。
打包与文件布局必须与其发布安装说明一致;不可要求用户检出整个 workspace 才能运行基础示例。
---
## 12. P7:三仓独立消费的发布前演练(不在 CLI 中实现三仓)
### 12.1 独立 Tool 无需核心适配
用**三个第三方模拟工具**而不是在 CLI 中加入 `knowledge/prove/view` 固定枚举:
1. `sample-view`:读取 `.mq.md` 源码与 Analysis v2 / Trace v2,打印函数数量、资源类型、调用来源行号。不得执行 `check` 时的项目代码。
2. `sample-knowledge`:读取 Analysis v2,输出简单稳定索引(function id、resource id、source digest、引用边),不引入向量数据库。
3. `sample-proof`:仅读取 Analysis v2,挑选受支持的纯整数表达式节点并给出“可解析/不支持/未知效应”的保守分类;**不宣称 Lean 已证明程序**。
上述程序可以写为小型独立 Python/Go/Rust 测试 fixture;只作为 `tests/consumers` 或 `examples/` 的黑盒验证,不必创建新的发行仓库。
### 12.2 目标验收
- 三者都通过 Tool Protocol 使用合法随机名称安装;
- 三者消费同一份 Analysis v2 / Trace v2,不链接任何私有 `marqdo-*` crate;
- 相同源码和 lock 在不同目录的知识身份稳定;源码变化使关联证据 stale;
- 第三方 Tool 可以替换编程语言、升级版本、卸载,`marqdo-cli` 无需重新编译;
- 未支持的 AST node、未解决的引用、Effect unknown 显式标注,不虚构证明或执行结果;
- CI 真实编译/运行(Python fixture 需要安装 Python,不允许缺 Python 就假装已验证)。
该演练一旦通过,说明 Core 已有合格的**生态扩展边界**。不要趁机把示例工具发展为三个产品的正式实现。
---
## 13. P8:发布工程、文档一致性、兼容承诺与版本发布
### 13.1 修复已经可见的文档漂移
当前 `docs/STATUS.md` 顶部仍称 `M0.5`,但正文已描述 lock v3、Analysis v2、Trace v2 和新 CI;`spec/tool-v1.md` 可能残存 Proposed 语句;`spec/security.md` 的部分陈述仍在描述旧 Worker 不可用/单前缀 export 等历史限制。这些都容易误导新开发者。
**必须做的文档清理:**
- `docs/STATUS.md`:更新 HEAD SHA、真实 CI #44680378977 的 Linux PASS / macOS+Windows FAIL,随后每次修复后更新新 CI URL。将历史 snapshot 移到明确的“历史”章节,避免整篇以 M0.5 状态作为现状。
- `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`:保留为阶段性历史设计;注明其 `0adebe4` 基线已被当前稳定化规范超越,不能把旧未完成清单直接用于新代码。
- `docs/NEXT_PHASE_IMPLEMENTATION.md` 与早期 ADR:保留历史决策,不复制多个互相冲突的“最新总体计划”;本文件成为新增任务唯一总纲。
- `spec/analysis-v2.md`、`spec/trace-v2.md`、`spec/tool-v1.md`:用真实当前输出对齐字段、状态、版本、兼容规则和异常。
- `spec/security.md`、`docs/adr/0019`:明确 Worker 能做/不能做什么、H3-A 现有 `fs.read` 实际桥、strict 未启用的原因和未来 G-C 机制;**不要假定 `Landlock-only` 或 `Worker-only` 足够**。
- `README.md`、`AGENTS.md`、`docs/contributor-guide.md`:添加稳定支持矩阵与本文件入口;新开发者不会读聊天记录也能重现代码和 release gates。
### 13.2 正式发布资料要求
1. `CHANGELOG.md`:清楚列出语言兼容、包 lock v3、Analysis/Trace v2、Tool v1、ABI v1、Foreign 支持与安全限制。
2. `RELEASE.md` 或 `docs/releasing.md`:列出 tag、平台、编译工具链、资产上传、校验和、撤回/回滚方法及验证流程。
3. `COMPATIBILITY.md` 或独立章节:公开协议主版本、支持平台、最低环境依赖、严格沙箱可用条件、降级与拒绝规则。
4. 示例/Quickstart:干净 Ubuntu 用户无需安装 Knowledge/Proof/View 即可 `run/call/check/add/sync/tool`;文档准确描述 Python/Node 是否自动安装。
5. `LICENSE`、公开 C header/SDK、插件示例与 API ABI 版本,确保外部独立开发者能够合法、明确地接入。
6. Release binaries:至少 Ubuntu 官方目标平台真实 `--release --locked` 构建产物;每资产 SHA-256,建议附 SBOM/构建 provenance。源码 tag 与二进制必须对应同一 SHA。
7. 安装体验:新环境能够校验二进制摘要并执行金样;不要求用户有 root 来执行普通 Marqdo 文档。
### 13.3 稳定发行步骤
```bash
# 所有操作应在完成适用 gate 后运行;以下为建议的发布序列
git fetch origin --tags
git status --porcelain=v1
git rev-parse HEAD
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --locked -p marqdo-cli
# 由 release 流程按真实产物路径创建归档、SHA256 与 provenance
# 最终 tag/release 的具体版本号由兼容政策及全绿 CI 决定
```
**不能直接运行 `git tag v1.0.0` 并宣称完成。** 必须先在远程提交上获得必需 CI 通过、至少一次 release candidate 干净安装演练、实际发行产物验证及正式发布说明。
### 13.4 失败处理和回滚
- 某 CI 平台失败:不删测试;形成最小复现、修复、重新运行;如果是明确不支持平台/功能,把该项从发布支持矩阵移除,文档写清楚,不假称同等能力。
- G-C 不可通过:strict 保持 unavailable;可在修订版本范围并经用户确认后单独发布 G-B Core Stable,但不宣传不可信代码隔离。若当前版本目标承诺 Linux strict,则必须推迟该版本发布直至安全门禁通过。
- 发布资产校验失败:撤回资产或撤销 release candidate,而不是让用户忽略 checksum。
- 正式 API 不兼容:升级版本及提供迁移说明;不要悄悄重写 schema v2 的已有字段含义。
---
## 14. 任务顺序、PR 切片、依赖关系与回滚策略
为避免 Harness 一次铺开全栈、难以调试,**一个 PR 只处理一个清晰风险面**。按以下顺序推进;必要时可并行不相互依赖的测试工作,但**同一 PR 不要同时修改 Markdown 语义和安全模块**。
| 顺序 | PR / 工作包 | 前置 | 修改范围建议 | 核心验收 | 若失败 |
|---|---|---|---|---|---|
| 0 | `ci/windows-ast-line-endings` | 无 | `.gitattributes`、AST golden harness、fixture | Windows AST + Linux golden PASS | 不改变 profile,重现字节差异 |
| 1 | `ci/macos-native-plugin-fixtures` | 无 | `examples/plugin-*`、CLI integration、CI | macOS 真实适配 / 正确跳过未支持目标 | 不能以 Linux.so 冒充 macOS artifact |
| 2 | `docs/status-reconcile` | 0/1 的结果 | STATUS/security/spec/README | 当前 SHA/CI/平台状态真实 | 标明未验证,不预填 PASS |
| 3 | `package/repro-hardening` | 基线 CI 绿 | package/fileset/lock/sync/tests | 多版本/传递/Git/env 原子完整 | 旧语义不正确则新增 ADR |
| 4 | `protocol/consumer-hardening` | 3 或独立 | Analysis/Trace/Tool/Schema | 移目录/digest/stale/陌生 Tool PASS | 只更改公开协议时升级版本 |
| 5 | `foreign/pinned-environment` | 3/4 | Foreign/env descriptor/tests | 确定真实解释器与环境绑定 | 不内置 uv/npm 大生态 |
| 6 | `abi/session-broker-hardening` | 0/1 | Host/ABI/Worker/tests | 跨调用权限隔离、恶意 frame/超时 | 不修改既有 ABI layout |
| 7 | `security/linux-strict-probe` | 独立 VM 准备 | sandbox/ADR/security tests | 能力检测,不开放 strict | EPERM 记录并换 VM |
| 8 | `security/linux-strict-pure` | 7 | supervisor/sandbox/CLI | L1 所有 OS 逃逸负例 PASS | 失败则 strict 保持 Unavailable |
| 9 | `security/linux-strict-extensions` | 8、6 | sandbox/Worker/Foreign | L2 支持路径真实继承限制;不支持的明确拒绝 | 不得单纯相信 Worker |
| 10 | `ci/native-platform-matrix` | 1/5/6 | CI/fixtures/portability | 各宣称支持平台真实运行 PASS | 清晰标 unsupported |
| 11 | `ecosystem/consumer-smoke` | 4 | tests/consumers / Tool fixtures | 独立三类工具可读可用 | Core 不增加特殊 Tool 名称 |
| 12 | `release/rc-and-docs` | 0–11 适用项 | docs/workflow/version/assets | 全绿 CI + 安装演练 + SHA | 禁止给红 CI 打 stable tag |
**并行原则:** 修 Windows AST、macOS fixture 可并行;包图与协议可以由不同分支实现,但统一落盘/身份规则的冲突由 ADR 先解决。严格沙箱在单独安全 VM 开发,不阻塞纯协议测试。分支合并前用合并后的 SHA 重跑所有相交测试。
### 14.1 Harness 每个 PR 的最小输出模板
```text
PR title:
Baseline SHA:
Changed files:
Observed defect (link to file/function/test):
Why the prior design fails:
Chosen solution and rejected alternatives:
Compatibility impact (language/ABI/schema/CLI):
Red test before fix:
Green tests after fix (commands, platform, exit code):
Security/negative cases:
Documentation updated:
Commit SHA:
CI URL and exact conclusions:
Remaining blockers:
```
不接受只有“完成修复,测试通过”却没有具体测试证据的 PR 说明。
---
## 15. 完整测试命令与验收样例
以下命令是现有工具链中应保持的官方入口;个别测试文件名或 fixture 参数在后续 PR 改动时,开发者应先核对 `crates/cli/tests/` 和 `Cargo.toml`,**不能假装命令已存在或运行成功**。
### 15.1 Git 和工作区
```bash
git status -sb
git fetch origin --tags
git rev-parse HEAD
git rev-parse origin/master
git log --oneline --decorate -10
git log --oneline origin/master..HEAD # 仍未推送的本地提交
git diff --stat; git diff --check
```
不要在未保存用户现有修改时直接 `git reset --hard`、`git clean -fdx`、强推主分支或覆盖测试基准。若工作区有未提交内容,使用单独分支/worktree,保留未提交文件的原始差异。
### 15.2 核心质量
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p marqdo-cli --test conformance_ast
cargo test -p marqdo-cli --test conformance_semantics
cargo test -p marqdo-cli --test negative
cargo test -p marqdo-cli --test properties
cargo test -p marqdo-cli --test analysis_trace
cargo test -p marqdo-cli --test tool_protocol
cargo test -p marqdo-cli --test package_env
cargo test -p marqdo-cli --test plugin_worker
cargo test -p marqdo-cli --test integration_cli
cargo build --release --locked -p marqdo-cli
```
### 15.3 公共数据协议的端到端示例
```bash
cargo build -p marqdo-cli
./target/debug/marqdo check \
examples/multi-module/index.mq.md --refs --emit /tmp/analysis-v2.json
./target/debug/marqdo run \
examples/multi-module/index.mq.md --trace-file /tmp/trace-v2.json
python3 tests/consumers/analysis_consumer.py /tmp/analysis-v2.json
python3 tests/consumers/trace_consumer.py \
/tmp/analysis-v2.json /tmp/trace-v2.json
# 此脚本使用 jsonschema 包;先安装明确版本
python3 tests/consumers/validate_protocols.py \
/tmp/analysis-v2.json /tmp/trace-v2.json \
examples/tool-unknown-name/tool.json
```
不得为这些命令运行成功而调整 fixture 使其失去负例覆盖;如果 CLI 输出协议破坏消费者,则应检查是哪一侧错误并遵守版本政策。
### 15.4 插件、Foreign、环境与 Tool
```bash
# 参考当前代码中的真实参数/样例路径;Windows/macOS 需适配动态库
./target/debug/marqdo check examples/plugin-multi-export/plugin-call.mq.md \
--plugin examples/plugin-multi-export
./target/debug/marqdo run examples/kernel-mock/demo.mq.md \
--kernel examples/kernel-mock/kernel.json --allow-foreign
# 隔离 Tool 测试安装目录,避免影响主机用户注册表
export MARQDO_TOOL_HOME="$(mktemp -d)"
./target/debug/marqdo tool install examples/tool-unknown-name/tool.json
./target/debug/marqdo benchmark run .
./target/debug/marqdo tool list
./target/debug/marqdo tool remove benchmark
```
**重要:** 当前 `examples/plugin-demo/build.sh` 只适用于 Linux 开发示例且会改写示例 manifest。正式 CI 应通过临时 fixture 构建本平台动态库,不在运行测试时写回受版本控制的 manifest。
### 15.5 strict 的普通用户拒绝 / 安全 lane
```bash
# 当前尚未实现严格隔离时,退出非零是预期、正确行为
./target/debug/marqdo inspect --platform --json
./target/debug/marqdo run examples/hello.mq.md --mode strict
# 未来真正的 security lane 必须运行第 10.5 节所有真实 OS 负例
# 不能用这两条“拒绝测试”证明 strict 已支持
```
### 15.6 失败时的最短定位路线
1. `git rev-parse HEAD` 与 CI 失败 SHA 一致吗?
2. 故障仅 Windows/macOS,还是 Ubuntu 也重现?
3. 测试在比较字节、真实行为、协议 schema 还是构建目标?
4. 当前 shell 是否 root/容器/受限制的 AppArmor profile?
5. CLI 输入是被锁定版本、静态引用、显式插件 manifest 还是未知动态目标?
6. 如何写出最小、稳定、无网络的复现 fixture?
7. 改动是否会让此前拒绝路径变成默许执行?
8. 修复后被同一目录、另一目录、不同 OS、恶意输入测试覆盖了吗?
9. PR 是否记录了明确的版本/安全/兼容影响?
任何一项不清楚,就先做最小复现而不是提交大量“可能有帮助”的重构。
---
## 16. 质量门禁与可签署发布清单
下面每一项必须以 **PASS + 真实 SHA/CI URL/日志** 或 **EXPLICITLY UNSUPPORTED(不宣称支持)** 两类状态之一回答。除平台明确不承诺的可选能力外,核心必需项不得标为 UNSUPPORTED。
### 16.1 Core Stable / G-B 必要门禁
- [ ] GitHub 当前目标 SHA 的 Linux `fmt/clippy/cargo test/workspace/smoke` 全部通过。
- [ ] Windows AST golden 根因查明,受支持平台的语义 profile 一致;没有靠 `UPDATE_GOLDENS=1` 淹没问题。
- [ ] macOS 插件测试不再依赖 Linux artifact;支持的平台真正运行 Native 插件集成。
- [ ] Windows/macOS 所承诺的语言、包、协议、Tool 功能真正运行测试,结果不是 `cargo check` 或空跳过。
- [ ] 全部路径/Git/传递锁图 v3 测试通过;锁失败严格拒绝,不下载或重写。
- [ ] 完整包内容 hash、symlink/特殊文件/权限/缓存篡改测试通过。
- [ ] Analysis v2 逻辑身份与资源投影跨目录可移植,真实 Schema 和独立消费者 PASS。
- [ ] Trace v2 的跨模块事件归属、digest/stale、截断与隐私测试 PASS。
- [ ] Tool v1 的任意名称、SemVer/Analysis/Trace 兼容、整包 hash/路径逃逸、退出码、卸载原子性 PASS。
- [ ] 外部 C ABI SDK 编译成功,静态检查/多导出/ABI mismatch/Worker 失败均有回归。
- [ ] Host 能力代理已承诺的 `fs.read` 和其他**实际声明可用**服务通过真实授权/拒绝测试;不可用能力不假装成功。
- [ ] Foreign Provider 摘要、固定环境、真实解释器选择/版本、超时/输出预算/非法 wire 校验通过。
- [ ] `check`、`inspect`、Analysis 导出证明不执行任何 `.mq.md` / Foreign / Native 插件副作用。
- [ ] 代码/协议规范/STATUS/README/AGENTS/示例和 CI 支持矩阵互相一致。
- [ ] 三种独立 Tool 消费者可运行,不需要 CLI 为官方名称写特殊注册分支。
- [ ] 对外 ABI / Tool / Analysis / Trace / lock 版本与兼容、迁移拒绝规则已明确冻结。
- [ ] 在真正干净的系统或 VM 中安装 release artifact、验证 SHA-256、运行 smoke PASS。
- [ ] Tag 对应同一验证过的 HEAD;CHANGELOG、发行说明、兼容矩阵和回滚步骤齐全。
### 16.2 Linux Strict / G-C 独立必要门禁
- [ ] 测试在独立受控 Ubuntu VM 或受信 self-hosted runner 上真实运行。
- [ ] 普通用户可用性/机制 probe 结果明确;不会靠根权限假装普通用户可用。
- [ ] 严格 Supervisor 正确隔离文件系统、网络、进程/FD 和资源上限。
- [ ] 直接 syscall 恶意 helper 的逃逸负例全部执行且拒绝成功。
- [ ] 子进程及其子树被可靠回收,time/memory/CPU/FD/process/output 均有真实预算测试。
- [ ] Native ABI 在 strict 拒绝;Worker/Foreign 只能在真正继承 OS 约束时启用。
- [ ] 任一机制不可用时继续 fail-closed,无隐式 `project` 回退。
- [ ] 安全 ADR、威胁模型、平台能力和逃逸测试均有对应 commit + security CI URL。
- [ ] 对外严格描述实际支持范围,不将 Worker、Landlock-only 或有 `sudo` 误认为完整沙箱。
### 16.3 最终发布判定
```text
Release candidate:
Source SHA:
Target version/tag:
Linux CI URL / status:
Windows CI URL / status:
macOS CI URL / status:
Protocol consumer CI URL / status:
Security G-C CI URL / status:
Package/Tool/ABI/Foreign integration summary:
Release artifact SHA-256:
Clean-install smoke report:
Supported platforms / explicitly unsupported features:
Known non-blocking limitations:
Release notes and compatibility link:
Final decision: RELEASE / DO NOT RELEASE
Reason:
```
**任何缺少真实来源的 PASS 都要降为 UNVERIFIED;不能把“代码已写完”“本地 sudo 下通过”填写为发布验收通过。**
---
## 17. 可直接交给 DeepSeek Harness 的总任务指令
> 下列内容可以复制到 DeepSeek Harness 的代码任务会话中。它的职责是执行本文件,并在有权限、资源和代码访问的条件下持续推进到发布门槛,而不是仅提出下一份设计方案。若用户尚未授权向远程发布 tag/release,可先准备并验证 RC,待明确发布授权后执行最终动作。
```text
你是 cflmy/marqdo-cli 的资深 Rust / Linux 系统安全 / CI 工程负责人。
仓库内的 docs/STABLE_RELEASE_IMPLEMENTATION.md 是本次完整的实施规范。
请先完整阅读该文档、AGENTS.md、docs/STATUS.md、spec/ 与 ADR-0008 至 0019,
再对照当前真实源码与 GitHub CI。不要依赖任何此前的聊天记录,也不要假定
旧 cflmy/marqdo 仓库的代码应被迁移;这个 CLI 是独立 Rust 实现。
最终目标:在保留 Markdown-native 语言及轻量 CLI 架构的前提下,完成该文档
定义的所有适用稳定版门禁 G-B,并在可控 Ubuntu 安全 VM 上争取完成 G-C,
形成发布候选版本、真实发行资产、测试证据、兼容矩阵与发布说明。
允许在本机使用明确授权的 sudo 安装系统工具、配置专用 AppArmor / namespace /
cgroup 测试环境;但普通 build 和正式测试不可总是 root,被测不可信程序必须
在真实 OS 隔离内以低权限运行。sudo 无法解除上级容器限制时,应报告证据并
转移安全测试到合适 Ubuntu VM,不得关掉 strict 的 fail-closed 来凑通过。
执行要求:
1. 基于最新 SHA 先修现有 CI:Windows AST golden 换行/字节差异和 macOS
平台不匹配的插件 artifact。保留失败复现和正反测试,不允许无差别重生 goldens。
2. 复核 lock v3 全图、Git cache、内容 hash/环境发布的可复现性质。
3. 收尾公开 Analysis v2、Trace v2、Tool v1,包括跨仓独立消费者的黑盒测试。
4. 完成 Foreign provider 与固定环境/真实解释器绑定的完整性语义;任何自动
uv/npm 环境创建应在独立明确授权的工具中完成,不要写死进解释器。
5. 完成 ABI Native/Worker/Host Broker 的真实调用和会话边界测试。
6. 实现 Linux strict 的真实 OS 隔离:先机制 probe、再纯语言模式,再按测试门禁
扩展 Worker/Foreign;文件/网络/进程/资源逃逸负例必须真的执行。
7. 加强 CI 平台矩阵与 release job;使实际支持矩阵与测试结果一致。
8. 完成文档和 STATUS 清理、发行资产、SHA256、干净安装 smoke、release candidate。
不可做:
- 不新增不必要的 CLI 顶层命令;不把 Knowledge/Proof/View 代码放入核心;
- 不引入第二个解释器、通用注册表、JIT、IDE、CAS、Lean 等本轮不必要功能;
- 不为官方 Tool 做特殊接入分支;不让插件篡改 Markdown 语言语义;
- 不以 root 下单次成功、跳过测试、忽略 CI 失败或静态权限检查代替隔离验证;
- 不强推主分支、不删除用户未提交工作、不在未得到发布授权时擅自给正式版打 tag。
工作方式:
- 分小 PR / commits;每项先做失败复现测试,再最小修复,再完整回归。
- 允许破坏性重构尚未稳定的内部 API,但公开 schema/ABI 变更须 ADR 和版本迁移。
- 若有必须补充的核心正确性缺陷,不因它没写在本文件就跳过;但先证明影响
和复现,再进行最小必要修复。
- 每阶段汇报真实修改、通过和失败的测试、日志、SHA、CI URL、剩余阻断。
- 更新 docs/STATUS.md,不能保留与最新源码矛盾的“已完成/未完成”描述。
- 在每阶段现有门禁未绿前不要直接声称项目完成。
从仓库基线审计和现有 CI 失败复现开始,随后按文档第 14 节推进。
目标是实现并验证真正可稳定发布的结果,而不是再写一份规划。
```
### 17.1 对 Harness 的交互指引
开始时只需对它下达上述总任务,并指明本文件路径。它可以从小阶段开始编码、测试、提交。若 Harness 在一个会话里难以完整完成所有任务,下一次会话应让它读取 `docs/STATUS.md`、最新 CI、`git log` 和第 16 节验收表继续,不需要重述我们的历史对话。**同一份文档是项目唯一的任务解释权威,测试和代码是事实权威。**
当它问到 sudo:允许它按需为**专用开发/测试 VM** 提权,要求说明目的和将运行的命令;你可以批准该系统操作。若它请求让所有生产 CLI 和测试都以 root 常态运行,应拒绝这种设计,因为这不能验证最终普通用户体验。
当它问到 G-C 和 Linux namespace:先给它当前 Ubuntu 诊断输出。若无法访问安全测试 VM,可继续 G-B,不要为了完成一行状态清单冒险修改 `PlatformCapabilities::detect()` 返回值。
当它问到 uv/npm:不要把 package manager 直接嵌入解释器;按第 8 章做固定 Provider/环境验证与可选外部 provisioner。如确有必须进 core 的跨平台依赖/协议需要,先以独立消费者用例证明,避免重现过去的内核膨胀。
当它问到发版:以第 16 节完整签署验收为准。对 stable release 名称和是否包含 G-C,必须与公开支持声明一致。用户可单独授权发布 tag/GitHub release;在此之前先完成全部工程内容和 RC 演练。
---
## 18. 与历史文件的关系、引用和保留策略
本文件是新阶段总实施计划,不取代规范里已经确定的具体语言语义:
- 语言权威:`spec/markdown-profile.md`、`spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`。
- Package:`spec/package-format.md`、ADR-0016。
- Public API:`spec/analysis-v2.md`、`spec/trace-v2.md`、`spec/tool-v1.md`、`spec/plugin-abi.md`、`spec/foreign.md`。
- Security:`spec/security.md`、ADR-0004、ADR-0011、ADR-0018、ADR-0019;strict 新实现须有独立新 ADR。
- 项目历史:`docs/DEVELOPMENT_BLUEPRINT.md`、`docs/NEXT_PHASE_IMPLEMENTATION.md`、`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` 可保留,但涉及阶段优先级和旧 HEAD 的事实时以当前源码及本文件任务规范为准。
供开发者查阅的参考链接:
- 仓库: https://github.com/cflmy/marqdo-cli
- 本次基线 CI: https://github.com/cflmy/marqdo-cli/actions/runs/44680378977
- Ubuntu 24.04 AppArmor/userns: https://documentation.ubuntu.com/release-notes/24.04/
- Ubuntu AppArmor 安全配置: https://documentation.ubuntu.com/security/security-features/privilege-restriction/apparmor/
- Bubblewrap: https://github.com/containers/bubblewrap
- DeepSeek Harness: https://www.deepseek.com/harness/en/
- DeepSeek Harness 开发文档: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
---
## 19. 作为开发负责人的最终工程判断
Marqdo CLI 的核心扩展架构**已经基本建立,不能把“没有 G-C”误解为“还需要重新设计一套 CLI”**。真正需要完结的是:
1. 当前 CI 明确可复现的两个平台问题;
2. 包与协议的稳定性和边界测试,不仅仅是功能演示;
3. Foreign 固定环境要约束真实执行目标,ABI 要有实际授权/错误与会话保证;
4. 在可控 Ubuntu VM 上实现并验证严格隔离,若无法取得足够 OS 权限,诚实保留 fail-closed;
5. 实际发行产物、兼容矩阵、独立工具消费者与全绿 CI 的真实证据。
**没有任何一项要求新增 `marqdo knowledge` / `marqdo prove` / `marqdo view` 的内置分支。** 如果未来某个扩展需求一定要修改 CLI 源码才能接入第三方命令、普通 Foreign kernel 或普通 ABI export,应首先视为扩展协议的架构缺陷,再决定最小修正。
**完成定义:** 当第 16.1 节所有适用 G-B 门禁均具备可审计的 PASS,首个核心稳定版本可以发行;当第 16.2 节 G-C 也确实通过时,才可以进一步对所测的 Linux 环境宣称支持 strict。切忌把“我们愿意给 Harness root”写成 OS 安全保证,也切忌因追求全功能而再次膨胀轻量内核。