Files
marqdo-cli/docs/STABLE_RELEASE_IMPLEMENTATION.md
T
cflmy 49835424ee docs(spec): adopt RFC-LANG-0002 unified language semantics
Replace the Strong/Emph/List/Quote mapping in place with the single
@exec/@knowledge heading-mode model, unified payload carriers and keyword
control flow.

- add the authoritative RFC, ADR-0052 and a historical ADR index
- rewrite spec/mapping.md and spec/expression.ebnf as the normative
  mapping/statement grammar; update evaluation, references, math,
  foreign, package-format, plugin-abi, security and schema notes
- rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking
  language change; update the architecture index/overview and active docs
- mark superseded planning docs, compute RFCs, evidence and syntax-role
  ADRs as historical/superseded without rewriting their decisions
- add migration guide, per-file inventory and dev-only audit scripts

The frontend/stdlib migration is completed in the following commits; this
commit contains documentation only.
2026-11-21 12:24:19 +08:00

84 KiB
Raw Blame History

Marqdo CLI 稳定版本开发与发布实施总规范

Historical roadmap note / superseded language syntax. 本文件是稳定版本 规划快照(编写基线 e966b766,2026-11-20),不是执行状态记录。其语言前提 早于 docs/architecture/RFC-LANG-0002-unified-semantics.md (ADR-0052):旧 Strong=执行、 Emph=返回、列表=分支/循环、引用块=调用的映射已被废止;语言语义只以该 RFC 与 spec/mapping.md / spec/expression.ebnf 为准。发布计划/门槛内容仍可作为 下一阶段规划的参考输入,但必须按当前 HEAD、docs/STATUS.md 与迁移台账刷新后 才能当作现行门禁;不得据此声称新语法或任一平台已完成。

定位: 可直接提交到 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 命令:

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 需要首先读取的资料

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:

  • 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. 目标架构、依赖方向与跨仓职责

用户输入 `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 组(若尚未有权限),然后重新登录该用户:

# 在管理员终端执行;将 devuser 替换为实际开发用户名
sudo usermod -aG sudo devuser
# 重新登录开发用户后检查
id devuser
sudo -v

sudo 组默认可能仍要求输入密码。若 DeepSeek Harness 的终端不能交互输入密码,而你完全掌控、可以随时重建这台专用 VM,可以有意识地为此开发用户建立单独的临时 sudoers 规则:

# 用 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 开始执行前输出环境基线

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 建议工作区组织

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 验收命令

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 最小可行安全架构

          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 品质要求

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 稳定发行步骤

# 所有操作应在完成适用 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 的最小输出模板

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 和工作区

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 核心质量

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 公共数据协议的端到端示例

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

# 参考当前代码中的真实参数/样例路径;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

# 当前尚未实现严格隔离时,退出非零是预期、正确行为
./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 最终发布判定

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,待明确发布授权后执行最终动作。

你是 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 的事实时以当前源码及本文件任务规范为准。

供开发者查阅的参考链接:


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 安全保证,也切忌因追求全功能而再次膨胀轻量内核。