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.
63 KiB
Marqdo CLI 核心稳定化、协议冻结与独立生态准入实施规范
Historical / Superseded review baseline (
0adebe4, 2026-11-20). The source review and CI facts here are a snapshot, not current state. The current overview isarchitecture/CURRENT.md; executed status is inSTATUS.md.语言语义已被取代: 本文件的语言描述早于
docs/architecture/RFC-LANG-0002-unified-semantics.md(ADR-0052)。现行唯一语言规范是 该 RFC 与spec/mapping.md/spec/expression.ebnf;本文的旧分阶段路线、 问题清单和门槛均为历史输入,不表示已实现,也不得覆盖 RFC。下一阶段计划以STABLE_RELEASE_IMPLEMENTATION.md为准。
文档状态:Proposed / 可直接用作下一阶段工程实施基线
源码审查基线:cflmy/marqdo-cli@0adebe42f14d72a2a275564d03ff9558f197766e,master,2026-11-20。
验证来源: 对上述提交的 GitHub 源码、规范、测试、CI workflow 和 CI run #44671025763 日志的静态审阅;未在本文写作环境重新本地编译、运行测试或验证 OS 沙箱。
仓库位置:docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md。
适用范围: 只针对全新 Rust 仓库cflmy/marqdo-cli的后续开发。不涉及从历史仓库cflmy/marqdo迁移代码,也不继承其 ABI 或隐式语义。
读者: 第一次接触本项目的 Rust 开发者、测试开发者、插件作者、独立 Knowledge / Proof / View 工具作者及 AI 编程助手。
0. 执行摘要:先做什么,不做什么
当前 CLI 不是待重写的空壳。它已有 Markdown AST 驱动的原生 Rust 解释器、模块/函数、Math/Foreign 基础能力、C ABI v1、可运行的外部工具分发器,以及 Analysis v1 和 Trace v1。新阶段的正确任务是:收敛已经形成的架构缺口,冻结能够被独立工具长期依赖的最小协议。不要再设计大型 CLI 命令体系,更不要把知识编译、Lean 证明、Web View 放入本仓库。
本阶段执行三条主线:
- H0/H1 — 正确性与可复现性:修复当前 CI,完成全依赖图锁定、包内容标准化、
sync一致性、跨模块错误定位。 - H2 — 外部协议可以真正被消费:修正 Analysis 身份/资源投影,完成 Tool 版本协商、安装包完整性和跨仓黑盒消费测试;冻结公开 Analysis/Trace/Tool 的兼容规则。
- H3 — 有条件的可信执行:补全 ABI Host Broker 的实际受控操作、Foreign 环境及权限边界;在至少一个 OS 上实现可验证的 strict 隔离,其他平台必须 fail closed。H3 不阻塞 View/Knowledge/Proof 的早期独立开发,但阻塞“安全执行不可信代码”的宣传。
禁止新增顶层 CLI 命令。 继续使用 run、call、check、add、sync、tool 作为推荐的主要入口,允许维护当前既有 init、lock、remove、inspect、fmt、plugin inspect 的兼容性,但不因本阶段需求扩大它们的产品边界。marqdo knowledge、marqdo prove、marqdo view 均由独立仓库提供、通过 marqdo tool 注册。
0.1 三道发布门槛,不能混为一谈
| 门槛 | 解锁事项 | 必须通过 | 不要求 |
|---|---|---|---|
| G-A:外部工具原型可用 | 独立开发 View、Knowledge、Proof 原型 | 当前 CI 修复;Tool 分发黑盒测试;可读的 Analysis/Trace 基础消费;稳定错误码 | 完整 strict 沙箱、公共注册表、完整符号证明 |
| G-B:Core Stable / 公共协议冻结 | 正式稳定依赖 CLI,生产可复现构建 | H0+H1+H2;跨平台协议测试;锁文件闭包;资源/模块身份;所有公测协议被 Schema 和外部消费者测试保护 | Lean、知识索引、CAS、JIT、全部平台 strict |
| G-C:Strict Trust / 不可信执行 | 宣称支持某个平台上的不可信代码/原生插件受限执行 | 在相应平台上通过 OS 隔离、逃逸负例、资源限制和真实 Broker 测试 | 其他平台自动具备同等隔离能力 |
任何人声称“已经完成”,必须明确说的是 G-A、G-B 还是 G-C,且提供该提交上运行通过的 CI 地址和测试结果。
1. 项目定位、语言语义和仓库边界
1.1 Marqdo CLI 是什么
Marqdo 是以 Markdown 语法树为正式结构、具有确定执行语义的编程语言。其基础原则为“代码即文档,文档即知识库,知识即可执行”。它不是将 Markdown 翻译成 Python 后执行的工具。普通文档内容保持 Markdown 可读性,具有执行语义的结构由固定 Markdown profile 和 language mapping 解释,再由独立 Rust 解释器运行。
语言规范权威入口(现行):docs/architecture/RFC-LANG-0002-unified-semantics.md 及其摘要 spec/mapping.md、spec/expression.ebnf、spec/evaluation.md、spec/references.md;spec/markdown-profile.md 仍固定 Markdown profile。(本句在写作时指向旧映射,已按 RFC 更新;下文其余叙述为历史。)修改这些文件规定的语义属于语言版本变更,必须单独提出 ADR 和金样测试;本文件不会擅自改变它们。
语言核心应独立完成 Markdown AST 解析、函数和参数推断、表达式与控制流、模块/显式导入、静态检查、确定的值及错误语义、Rust 原生执行、能力检查、依赖环境。编译/运行 不需要 Knowledge、Proof 或 View。
1.2 四个仓库如何合作
用户终端
│
▼
marqdo
│
┌────────────┴────────────┐
▼ ▼
内置语言/工程命令 Generic Tool Dispatcher
run/call/check/add/... │
│ tool.json + 已安装记录
▼ │
Markdown → Semantic → Rust Runtime ├── marqdo knowledge ...
│ ├── marqdo prove ...
├── Analysis ├── marqdo view ...
└── Trace └── marqdo <任意第三方工具> ...
▲ ▲
└── 版本化文件协议 ────┘
marqdo-cli:提供且仅提供语言权威、项目与执行环境、开放 CLI 工具发现分发、必要的公共分析/运行事实。marqdo-knowledge:独立仓库中的知识编译、索引、知识制品与交换;不得要求 CLI 内建知识图数据库。marqdo-proof:独立仓库中的契约、可证明语义子集、Lean 适配与证书;不得修改解释器以替代证明。marqdo-view:独立仓库中的 Markdown 阅读、追踪、导航与可视化;不得重新实现另一套语义解释器。- 未被 CLI 预定义的第三方工具应与官方工具完全等价接入。官方工具名不是内置白名单。
1.3 三种“插件”必须严格区分
| 类别 | 做什么 | 接入方式 | 权限身份 |
|---|---|---|---|
| CLI Tool | 扩展 marqdo xxx 用户命令 |
tool.json + 独立可执行程序,由 marqdo tool install 注册 |
用户主动启动的本地程序,不自动受 .mq.md 沙箱保护 |
| 语言运行时 ABI Plugin | 给 .mq.md 增加可调用函数 |
plugin.yaml + ABI v1(受信 Native 或 Worker) |
通过 Host、插件身份和能力授权约束;C ABI ≠ 沙箱 |
| Foreign Kernel Provider | 执行显式调用的外语 Code 值 | kernel.json + Foreign wire 协议 |
单独进程,foreign 授权 + OS 级边界,不是 CLI Tool |
不要为了复用文件名而合并三者注册表、安装命令或信任关系。
2. 当前仓库的真实基线与证据强度
2.1 代码已经存在的能力
| 领域 | 已在 HEAD 可定位的实现 | 当前结论 |
|---|---|---|
| Markdown 解析/固定 profile | crates/marqdo-markdown/,AST goldens |
存在且已有测试;保持稳定 |
| 前端、签名和解释器 | marqdo-expression、marqdo-frontend、marqdo-ir、marqdo-runtime |
Rust 原生执行路径已建立 |
| 通用可调用符号描述 | crates/marqdo-ir/src/callable.rs,ADR-0009 |
已解决此前多处手动注册的主要问题 |
| 包实例身份/解析 | crates/marqdo-package/src/lib.rs,ADR-0008 |
path/Git、传递导入已出现,但锁定闭包未完成 |
| Tool 扩展 | crates/cli/src/tool.rs,spec/tool-v1.md |
本地任意工具名可分发,仍缺完整兼容协商与包完整性 |
| 公开 Analysis/Trace | crates/cli/src/{analysis,trace}.rs,spec/{analysis,trace}-v1.md |
已可导出;身份、资源、跨模块追踪仍有缺口 |
| ABI/Worker | crates/marqdo-host/src/plugin_worker.rs、crates/marqdo-plugin-abi/ |
已有崩溃隔离;不是 strict OS 沙箱 |
| Foreign Provider | crates/marqdo-foreign/src/lib.rs |
KernelRegistry 已支持外部 provider;环境管理未完成 |
| Host capability / handles | crates/marqdo-host/src/{capability,handles}.rs |
已有权限检查与 owner/run/generation 表;真正能力代理尚不完整 |
2.2 CI 的事实,不得“按文档标记 Done”替代验证
最新 HEAD 的 CI run #44671025763 为 failure:Linux 上 fmt 和 Clippy 成功,工作区测试失败于 crates/cli/tests/properties.rs:328:
assertion failed: repo_root().join("tests").join("properties").is_dir()
原因是 Git 不跟踪空目录,仓库检出后的 tests/properties/ 不存在。该失败不是已发现的语言语义不变性错误。Windows/macOS job 为 cargo check 成功,不能推论其运行测试通过。Linux 在测试失败后跳过了后续公共 Schema 和示例 smoke 验证。必须先修复这一基线才有资格说最新代码测试通过。
2.3 证据分级
- 源码确认:本文件明确指出的函数或逻辑在基线提交中实际存在。
- 运行记录确认:有可核对的 GitHub Actions 日志支持。
- 由代码推出的逻辑风险:能够从条件分支和数据结构发现,但还应写复现测试。
- 设计建议:推荐但尚未实现的方案,不得描述为现状。
每次后续更新文档时,先刷新 HEAD SHA、CI 证据,并为变更项记录实际测试,而不能机械继承本文件的状态判断。
3. 稳定内核的工程约束
- 最小语义核心。Markdown AST 映射、表达式、函数作用域、值类型和授权的最终裁决属于核心,不能让第三方 Tool 或任意 ABI 插件覆盖。
- 不增加新的顶层命令。新的功能优先通过原命令参数、现有
tool协议或独立仓库实现;不要为了每个协议新增analyze、graph、env、kernel等新一级命令。 - 无二次解析与双运行时。Knowledge、Proof、View 只消费公开的标准分析/追踪或源码,不链接和序列化私有 Rust
marqdo-ir,不重新决定何为执行节点。 - 工具开放不代表语言可任意扩语法。ABI/Kernel/Tool 的名称和实现由外部声明注册,但 Markdown 结构语义仍由核心规范控制。
- 构建和检查不执行。
check与 Analysis 导出不得运行文档、加载动态库或启动 Foreign;依赖安装/锁定不得执行安装脚本。 - 来源声明不授予权限。
marqdo.yaml/plugin.yaml/kernel.json的请求不是用户授权;实际能力在每次使用时受 Host 或 OS 限制。 - 无隐式降级。缺少 strict 隔离、缺少已锁版本、缺少契约支持时要用稳定错误码拒绝,不能悄悄恢复为不安全/不确定模式。
- 允许破坏性内部重构,但对外协议必须显式版本化。目前暂无正式稳定发布,推荐在首次 G-B 冻结前修正身份和锁文件格式;采用 ADR、迁移 fixture、Schema 版本和清楚的诊断,不要靠旧设计包袱维持错误。
4. 目标架构:改职责,不制造更多 crate
保留仓库现有 Rust workspace,以有限模块重构职责,而不是增加一串微型 crate。建议职责如下:
crates/
marqdo-markdown/ # CommonMark/GFM/Math profile, AST and SourceSpan
marqdo-expression/ # expression lexer/parser/AST
marqdo-frontend/ # language mapping, inference, static resolution
marqdo-ir/ # private executable IR and CallableRegistry
marqdo-runtime/ # independent Rust evaluator (no Python transpilation)
marqdo-value/ # typed values, wire values, diagnostic/error
marqdo-span/ # per-module source spans and locations
marqdo-package/ # package graph, hashes, lock, env, cache
marqdo-host/ # capability checks, effect calls, traces, workers
marqdo-sandbox/ # per-platform isolation capability and enforcement
marqdo-plugin-abi/ # stable C ABI, manifest, wire, worker framing
marqdo-plugin-sdk/ # independent third-party Rust API
marqdo-foreign/ # explicit kernel registry and process boundary
marqdo-math/ # documented native mathematical subset
cli/ # command composition, project loading, public exports,
# Tool Protocol (no Knowledge/Proof/View implementations)
spec/
package-format.md
tool-v1.md
analysis-v1.md # if breaking fields: new v2 document + transition
trace-v1.md
schemas/
docs/
adr/
CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md
crates/cli/tests/
tests/consumers/
4.1 关键依赖方向
cli -> package/frontend/runtime/host/foreign/plugin-abi,只在 CLI 中装配;package不调用 CLI;runtime不知道 Tool 和 UI;markdown不依赖 Host。- 外部 Tool 使用发布的 CLI 子进程接口 + 公开 JSON/文件协议,不依赖
crates/cli/src/analysis.rs的 Rust 私有函数。 marqdo-proof对公开投影的受支持语义子集建立模型;不向解释器注入 Lean 代码,也不让 Lean 成为运行时依赖。- 公开协议只能含稳定的
ModuleId/FunctionId/资源身份、语义投影、来源哈希、运行事件;不能暴露内部 Host 指针、插件 handle 的实际权限、Box/Rc或私有优化 IR。
4.2 设计取舍:为什么不把一切都做成通用插件
语言运行正确性依赖一套确定的求值规则,安全依赖可审计的 Host 权限边界。盲目把 AST 节点语义、内置操作、权限裁决全部开放会使 check 与 run 对同一程序给出不一致结果。应将 可调用实现、Foreign Provider、CLI Tool、包来源扩展设为开放注册点;将 语法、运行值、名称解析规则和权限最终判决固定在核心。开放的是有明确协议的边界,而不是开放任意劫持入口。
5. 问题清单与优先级(截至基线提交)
| ID | 优先级 | 确认/风险 | 问题 | 直接影响 | 主负责落点 |
|---|---|---|---|---|---|
| B-01 | P0 | CI 确认 | 属性测试依赖 Git 不保留的空目录,HEAD 的 Linux CI 红灯 | 无可信发布基线 | crates/cli/tests/properties.rs,tests/ |
| B-02 | P0 | 源码确认 | 锁文件生成只遍历根直接依赖,传递闭包不完整 | 多包不能充分可复现 | cli/src/commands.rs::build_lockfile、marqdo-package |
| B-03 | P0 | 源码确认 | check_lock 找不到锁条目就成功返回 |
未锁传递依赖可能被静默接受 | marqdo-package::PackageResolver |
| B-04 | P0 | 源码确认 | sync 使用计算出的新锁结果物化环境,却未见相应写回锁文件 |
manifest/lock/env 可以分歧 | cli/src/commands.rs::sync |
| B-05 | P0 | 源码确认 | hash_tree 包含生成目录且吞掉 WalkDir 错误;copy_tree 未形成统一文件集策略 |
哈希不稳定、不可重现或复制错误 | marqdo-package/src/lib.rs |
| B-06 | P0 | 源码确认 | Analysis project.root_id = 绝对物理路径哈希 |
换机器/目录分析和 Trace 失配 | cli/src/{analysis,trace}.rs |
| B-07 | P0 | 源码确认 | Analysis 仅 resources: <数量> |
公式/代码资源无法由外部独立编译 | cli/src/analysis.rs::build |
| B-08 | P0 | 源码确认 | 运行时错误用入口文件解释跨模块 Span | 报错行列与原模块不符 | marqdo-value / runtime / cli |
| B-09 | P1 | 源码确认 | Tool 安装校验 Marqdo 版本,但未对 Analysis/Trace 协议完整协商 | 外部工具可能不兼容 | cli/src/tool.rs |
| B-10 | P1 | 源码确认 | 仅校验 Tool 入口文件哈希,不校验完整包 | 辅助脚本/资源被替换后仍可运行 | cli/src/tool.rs |
| B-11 | P1 | 源码+文档确认 | Worker 能隔离崩溃但未提供 OS 沙箱,CapabilityBroker 主要做授权判定 | 原生扩展不能安全宣称不可信执行 | marqdo-host / plugin-abi / sandbox |
| B-12 | P1 | 源码/功能缺口 | Foreign Provider 缺少锁定的环境/内核依赖闭包 | Python/Node/R 等环境不能完整重现 | marqdo-foreign / marqdo-package |
| B-13 | P1 | 源码确认 | Schema CI 只解析 schema JSON,未用 schema 验证真实产物 | 公共协议回归保护不足 | spec/schemas / CI / tests/consumers |
| B-14 | P1 | 源码确认 | Win/macOS CI 只执行 cargo check |
原生 Tool/Worker/路径行为没有跨平台运行证据 | .github/workflows/ci.yml |
| B-15 | P1 | 设计缺口 | 插件重复导出名尚无正式的按包限定别名机制 | 多供应商同名插件不方便共存 | CallableRegistry、frontend、包 manifest |
| B-16 | P1 | 源码确认 | Trace 无事件数量预算、Worker 单帧上限高且失败路径需硬化 | 大循环或恶意插件可消耗过多内存/磁盘 | cli/src/trace.rs、plugin-abi/src/worker.rs |
| B-17 | P2 | 已知缺口 | 跨模块 LinkCall 语法不支持,ref 选择资源有限 |
远期知识可寻址体验受限 | spec/references.md + 单独 ADR |
| B-18 | P2 | 已知缺口 | Math CAS、优化字节码、包 Registry、通用 REPL 等未实现 | 不影响首轮独立生态闭环 | 不纳入本阶段 |
优先级说明: P0 阻止 G-B;P1 按门槛区分:Tool/Schema/跨平台项阻止 G-B,OS strict 项阻止 G-C;P2 不阻止本阶段。每个条目必须用新增正反测试关闭,而非仅修改 STATUS.md 的文字。
6. H0:立即恢复可信 CI 基线
6.1 原因与定位
crates/cli/tests/properties.rs::pure_prose_edits_do_not_change_executable_ir 在正式运行测试逻辑前断言一个空目录存在。Git 不追踪空目录,因而新检出失败。不允许删掉“纯叙述编辑不改变执行语义”的测试。
6.2 实施方案
首选将该测试变成不依赖无内容目录的内存 fixture 测试;测试数据已存在代码内时,不需要断言空目录。若确需外部 fixture,则在 tests/properties/ 放入实际有意义的版本化 fixture 文件,并让测试逐一读取,不能仅用空 .gitkeep 掩盖依赖不成立的设计。
修改之后固定基线:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p marqdo-cli --test properties
cargo test -p marqdo-cli --test tool_protocol
cargo test -p marqdo-cli --test analysis_trace
若 CLI 或脚本因环境缺少 Python、Node、C 编译器而跳过可选测试,必须在 CI 中增加装有相应依赖的专用 job;跳过不能算通过第三方扩展协议验收。收集通过的 workflow run 链接并写入 docs/STATUS.md 的本阶段基线栏。
6.3 验收(H0-GATE)
- 全新
git clone下不需要手动创建目录,cargo test --workspace全绿。 - 叙述插入/删除的等价性测试没有被禁用或削弱。
- CI 的 Schema/Smoke job 不再因前置测试失败而跳过。
- 文档记录实际 SHA、job URL、平台和工具链版本,不依赖开发者本机状态。
7. H1-A:包图、锁文件及可复现依赖体系
7.1 为什么必须破坏性修改当前 lock 结构
当前 LockFile 是平铺的 {name, instance_id, source, sha256} 列表,build_lockfile 只遍历根 manifest 的直接 alias,而运行时 resolve_alias_from() 支持从依赖包自己的 manifest 访问后续依赖。这两条语义必须对齐,否则“可执行传递依赖”并不意味着“已锁定传递依赖”。另外 check_lock() 对缺失项返回 Ok(()),导致本应拒绝的未锁状态可能被当成有效。为了保证可重复构建,锁定对象应是包实例及其依赖关系组成的闭包,而不是根项目的一组别名。
7.2 推荐的 lock v3 逻辑模型
以下仅定义逻辑结构;YAML 字段名称、顺序在实施 ADR 中最终冻结。应采用有约束的最小模型,避免提前开发复杂依赖求解器:
lock_version: 3
root:
package: root:quantum@0.1.0
manifest_digest: sha256:...
packages:
- id: dep:math@1.0.0#<完整摘要或足够长的消歧部分>
name: math
version: 1.0.0
source: {kind: git, url: https://example.invalid/math.git, rev: <固定提交>}
content_digest: sha256:...
dependencies:
helper: dep:helper@2.0.0#...
- id: dep:helper@2.0.0#...
name: helper
version: 2.0.0
source: {kind: path, path: packages/helper}
content_digest: sha256:...
dependencies: {}
root_dependencies:
math: dep:math@1.0.0#...
关键约束:
id唯一代表一个确定包实例;根名、name、version不能作为唯一 ID,同名多版本可以并存。ID 的摘要不能仅靠未经碰撞检测的短前缀作为安全唯一性依据。若人类可读短名则必须有完整摘要消歧校验。- 依赖边由“包实例 + alias → 目标实例”表示,相同 alias 在不同包的含义不必相同。
- 每个包实例有来源、固定 Git commit 或项目相对路径、规范化内容摘要、自己的依赖边。无锁包一律拒绝,除非处于显式生成锁定图的操作中。
- 锁文件记录 root manifest digest;
run/check默认不从网络补充依赖,也不静默改写锁。 - 本阶段只支持path + pinned Git;不要求 Registry、SemVer 求解器、依赖脚本、自动更新或签名服务。
7.3 解析流程(伪代码)
fn resolve_lock_graph(root_manifest: Manifest) -> Result<LockGraph> {
// 1. 检查根清单,装入每个显式 alias。
// 2. 对每个来源按其固定路径 / Git 提交读取包清单。
// 3. 计算规范化包内容摘要,导出 PackageInstanceId。
// 4. 以 PackageInstanceId 去重;检查同 ID 内容相异冲突。
// 5. 遍历包清单的所有依赖,记录从包实例出发的 alias 边。
// 6. 对传递图做 cycle/缺失/冲突诊断,而非无限递归。
// 7. 输出按 ID、alias 确定性排序的完整闭包及根边。
}
fn check_locked(graph: &LockGraph, wanted: &ResolvedGraph) -> Result<()> {
// 不存在的包实例、边、摘要、来源、固定提交 => 明确拒绝。
// 所有已锁实例都要满足其锁摘要。
}
具体模块建议:
marqdo-package/src/lib.rs:提取LockGraph、PackageInstance、LockedDependencyEdge、包闭包构建/校验逻辑。无需增加marqdo-lock独立 crate。cli/src/commands.rs::build_lockfile:从“遍历直接依赖”改为调用包层resolve_lock_graph。PackageResolver::check_lock:必须用当前包实例 + alias 来查锁边,而不是全局 alias 名。锁不存在时拒绝,禁止静默Ok(())。cli/src/loader.rs:只消费解析完成的ResolvedModule,不得自创另一套依赖匹配逻辑。
7.4 统一的文件集与哈希规范
hash_tree 与 copy_tree 必须使用同一个规范化文件选择策略。不要在 hash 和复制时使用不同的排除规则,否则 hash 指纹无法可靠代表被执行环境。
最小规则:
- 纳入
.mq.md、marqdo.yaml、包内实际需要的资源文件以及明确声明的可执行资产;默认忽略.git/、.marqdo/、构建缓存、临时 staging 等生成目录。 - 规范化包内相对路径为 UTF-8、
/分隔、无..、无绝对路径;不接受同一规范化路径映射到两个实际文件。 - 目录遍历不允许
.filter_map(Result::ok)静默吞掉错误;遇到权限不足、不可读文件必须终止构建。 - 明确 symlink 策略:第一版推荐拒绝包含 symlink 的可执行包源;避免 hash 时跟随、复制时拒绝引起不一致。
- 采用域分隔和文件名+文件长度+文件内容的确定性编码;包括
content_profile_version,将来更换忽略规则须改变 profile 版本。 - Git checkout 必须校验指定 revision 精确对应的提交对象,缓存命中仍要验证源及内容摘要。缓存不可信,不能仅凭目录存在就跳过验证。
- 对源包设置文件数、单文件字节、总字节、深度预算,避免恶意包或异常目录树耗尽内存/磁盘。
示例策略(规范性测试期待,不是已实现 API):
source package: packages/math/
index.mq.md INCLUDE
marqdo.yaml INCLUDE
assets/formula.json INCLUDE
.git/ EXCLUDE
.marqdo/env/ EXCLUDE
target/ EXCLUDE (仅在规范明确为生成目录时)
symlink -> /etc/passwd REJECT
7.5 sync 的事务语义
存在两种可行方案,必须选定一种并在 CLI 帮助/规范中公开。推荐方案 A,减少隐式状态变更:
marqdo lock:计算并写入完整 lock v3(已存在的命令);可以显式访问网络获取 pinned Git。marqdo sync --locked:只读取现有锁并校验、物化,不更改锁;缺失/漂移直接失败。marqdo sync:如果沿用旧行为要自动重锁,则必须把新 lock + 新 env作为同一事务(同 staging、fsync/回滚策略)发布;否则改为拒绝过期锁并指导用户运行marqdo lock。禁止只把新 env 生成了却留下旧 lock。
为了减少状态机复杂度,更建议 sync 首版默认严格执行锁,更新仅由 lock 明确触发;这是一个有意允许的行为改变,须写 ADR 和迁移/错误提示。
7.6 H1-A 测试矩阵
| 测试 | 输入/操作 | 应当得到 |
|---|---|---|
| 一级传递 | A → B → C | lock 包含 B/C,含 B→C 边,sync 可全部物化 |
| 多版本并存 | A→B@1 / A→C→B@2 | 两个 B 实例身份和实际导入互不干扰 |
| 不存在锁条目 | 删除 C 的锁节点或 B→C 边 | sync --locked / check 按契约失败,不静默接受 |
| 依赖漂移 | 修改 B 自己的 manifest,使其 C 改变 | 锁失配错误,禁止自动网络修复 |
| Git 迁移目录 | 同一固定 Git commit 在两台不同目录恢复 | 包实例 ID、导入解析保持相同 |
| 缓存污染 | 修改 .marqdo/cache/git/... 已缓存包内容 |
不能以“目录存在”接受污染内容 |
| 生成目录 | 增加 .git / .marqdo / target |
包内容指纹不因非分发内容改变 |
| 遍历失败 | 把包内某文件变为不可读 | 明确报错,不产生“部分哈希” |
| 恶意路径 | ../、绝对、symlink/循环 |
拒绝且不离开包根 |
| 事务失败 | 物化环境中途断电模拟或注入 rename 失败 | 保留旧一致状态,无半成品锁/env |
验收: marqdo.lock 足以表达完整已支持的包闭包,在清洁机器有源/缓存可恢复;不锁定、不匹配、不完整一律失败。成功时锁、环境和实际执行模块一致。
8. H1-B:跨模块诊断与源码身份
8.1 当前错误
cli/src/commands.rs::runtime_error_json / render_runtime_error 用 project.entry_file().source 的行索引解释 error.span。如果运行错误发生在导入模块,Span 起止位置可能是那个模块的局部偏移,不能映射到入口文件。
8.2 目标模型
将源码位置当成不可分割的二元组:
struct SourceLocation {
module_id: ModuleId, // 包实例 + 相对路径,逻辑身份
span: Span, // 该文件 UTF-8 字节偏移
}
调用栈可以额外保存 function_id 和调用点 SourceLocation,并由 CLI 根据 module_id → LoadedFile 查找真实路径及 LineIndex。不要让 Span 单独跨文件传递后再猜是哪份源码。
设计建议:
- 优先扩展
RuntimeError的源模块或定位结构,而不是只在 CLI 做字符串补丁。 - 所有执行节点/Host 效应可以携带已有
ExecutionContext.module;错误产生时附上该来源,转成 JSON 时保持module_id和span,UI 字符行列只是展示层派生信息。 - Plugin/Foreign 产生的错误若只有调用点位置,应标记
origin: callsite而非捏造外语内部栈;可选附加内核自己的错误信息。 - 错误 JSON 与 Trace v2(若需要)使用同一逻辑模块身份,禁止混用绝对文件路径作为持久地址。
测试:根入口 index.mq.md 调用 deps/physics/index.mq.md,在后者第 8 行故意除零;应报告后者的模块和第 8 行,而不是 index.mq.md 第 8 行。再测试多版本包两个同名相对路径的错误都能区分。
验收: 所有跨模块运行异常、调用栈及导出的 SourceSpan 都可以唯一映射至真实模块,不因同名文件、不同包实例或缓存位置产生歧义。
9. H2-A:重新冻结公开 Analysis 协议
9.1 为什么现在不能直接将 Analysis v1 永久冻结
现有 cli/src/analysis.rs::build 将项目 root_id 设为项目绝对路径的 SHA-256;同一项目复制到不同目录会变更 root_id,进而变更整个分析 JSON 摘要和 Trace 的 analysis_digest。与此同时,每模块的 resources 只有一个数量整数,无法为知识编译建立资源级的稳定寻址与来源关联。
这是协议模型问题,不是 Knowledge 项目该做的补丁。如果让 Knowledge 自己另建一套身份和 Markdown 解析规则,就会重新导致仓库耦合。
9.2 三种身份必须独立
| 概念 | 用途 | 修改时是否变化 |
|---|---|---|
ProjectIdentity / ModuleId |
逻辑归属、符号寻址 | 项目名称或符号/模块身份变更时变化;不因存储路径变化 |
SourceDigest / PackageContentDigest |
内容变化检测与缓存 | 源码或真实分发内容变化时必须变化 |
AnalysisDigest |
对整份语义投影及指定编译配置建立快照 | 语义投影、profile、锁图、编译器语义版本改变时变化 |
不要用 hash(absolute_path) 充当项目身份。 可以根据根 manifest project.name + version 和显式持久项目标识形成逻辑归属。无 manifest 的单文件场景需要独立定义 workspace_snapshot_id(可以使用来源内容摘要以区分无名项目),并说明其没有跨重命名持久身份承诺。
AnalysisDigest 必须使用规范化序列化的内容、必要的语义版本和规范化 lock;不能包含本机路径、临时文件名、当前时间、进程 PID 等与语义无关的数据。内容变更后 digest 应变化,纯位置迁移不应变化。普通叙述变更是否影响 AnalysisDigest 必须明确:因为源码源映射 span 会变化,所以完整 Analysis snapshot digest 可以变化,但同一函数的独立语义摘要可以不变;不要混淆二者。
9.3 资源级投影:知识编译不可或缺的最小字段
建议将原 resources: <integer> 改为资源数组,必要时另设 resource_count。资源目录内容读取仍通过源码路径/偏移而不是强行将所有文档内容复制到 Analysis。示例仅展示结构:
{
"id": "resource:root:quantum@0.1.0::index.mq.md#formula-1",
"module_id": "root:quantum@0.1.0::index.mq.md",
"unit_id": "<所属章节的 UnitId>",
"kind": "formula",
"span": {"start": 112, "end": 144},
"content_digest": "sha256:<实际资源内容摘要>",
"language": null
}
应覆盖公式(Formula)、代码围栏(Code)、可静态提取的 GFM 表格等实际由 marqdo-ir::Resource/AST 支持的资源。先精确定义当前存在的资源种类,不得虚构尚未实现的 AST 节点。 资源身份可由 ModuleId + UnitId + 资源标识 确定;如果同章节存在多个无显式锚点资源,须制定确定的、可检测重排和歧义的寻址规则。
SourceSpan 应始终指向具体资源所属模块,导出模块内规范化 relative_path 和 source_digest。View/Knowledge 可通过模块内容+span 获取资源,不得在 Analysis 中泄漏环境变量或执行时秘密。
9.4 分离可复用语义和原始语法信息
functions[]:提供名称、签名、可观察的归一化函数体节点、来源定位、保守效应摘要。imports[]:显式别名、解析状态、目标 ModuleId;缺失绝不默默变“external”。references[]:Markdown 链接关系,独立于calls[],引用不意味着调用。calls[]:源函数、调用点、解析状态、绑定目标及必要参数信息;由与执行一致的符号解析机制生成。resources[]:可定位资源,保持原始 Markdown/公式/围栏文档源映射;静态投影不调用 Foreign 或 Math。effects[]或effects:unknown是未知,不能表示已证明纯函数。模型仅提供保守静态摘要。
9.5 v1/v2 与兼容策略
在首次正式对外稳定发布前,推荐创建 spec/analysis-v2.md 和 spec/schemas/analysis-v2.schema.json,显式把 schema_version: 2 用于上述破坏性 root_id、资源结构变化。是否保留 --emit-version 1 为兼容选项需另行决定,不要凭空增加新的顶层命令。由于本仓库尚无正式发布,允许直接明确宣布 v1 是实验协议,不强制长期维护两份写入器;但必须修改文档、所有消费者 fixtures 和错误提示。
如果维护者选择不升级 schema_version,也必须通过 ADR 证明字段变化符合现有 v1 合同;考虑 resources 从整数变数组,这通常不符合。推荐版本升级更安全。
9.6 H2-A 必需测试
- 相同项目检出到
/tmp/projA与/tmp/projB,导出的规范化 Analysis 字节相同(需将本机诊断路径从协议中剥离或独立标注),各 ModuleId 一致。 - 改一行真正的执行表达式,source digest、function body、analysis snapshot digest 按规则变化。
- 只改普通叙述,不改变程序执行结果;函数语义节点应按明确规范保持语义等价,SourceSpan 可以变化。
- 一个章节下两个公式和一个代码围栏,分别拥有唯一资源记录,
Span和摘要可反查源内容。 - 两个不同包实例里存在相同
src/index.mq.md,模块和资源身份不能冲突。 - 缺失/未支持的节点不能被投影器“假装支持”:显式
unsupported或稳定诊断。 - 导出过程中发生错误时不留下看似成功的新分析文件;已存在旧产物按现有规范正确清理。
check --emit过程中没有 Python/Node 进程、ABI 动态库加载和run副作用。
10. H2-B:Trace 的身份、源映射与容量边界
现有 Trace v1 已记录 call.enter / call.exit、branch.eval、loop.iteration、return 和 Host effect,默认不记录值和秘密,这个隐私立场应保留。需要修正:
- 根身份与 Analysis 一致:Trace 应绑定公开 Analysis 的逻辑身份和规范化摘要,不再依赖物理目录路径哈希。
- 事件来源完整:
effect已有module;其他语义事件的源位置必须可以通过function_id或显式module_id解析,跨模块不能误读入口文件;如果语义事件不能唯一定位,增加稳定来源字段。 - 有限预算:加入可复用的事件数量和字节预算,超限时要有明确
trace.truncated/resource.exhausted结尾;不能在无限循环里无限增长 Vec 和输出 JSON。 - 状态确定:运行失败仍应记录错误终态;外部工具不能把旧 Trace 误认成新执行。
- 机密性:坚持不记录参数值、文件内容、密钥、句柄;未来 View 想要局部变量时应通过显式、受权限约束的调试 API 单独设计,不能悄悄扩大 Trace 默认数据集。
run/call --trace-file 入口不变,若修改必需字段则采用 trace-v2,保持与 Analysis 协议独立版本。测试包含 10 万次循环触发上限、外部插件异常、跨模块事件关联、移动路径之后的源匹配及 secret 红action(搜索全量输出不得含测试密钥)。
11. H2-C:通用 CLI Tool v1 完整性与兼容性
11.1 继续坚持完全通用的工具名称
核心不能在代码中出现 knowledge / prove / view 的特殊命令分发。已有 crates/cli/src/tool.rs 使用未知命令回退与 tool.json 注册,这是正确方向。保留最小:
marqdo tool install path/to/tool.json
marqdo tool list
marqdo tool remove benchmark
marqdo benchmark run . # 测试工具名核心完全不认识
不能因为要管理三款官方工具就添加内置白名单或工具专用 Rust crate。
11.2 兼容性必须实际判断,而非仅记录字段
当前 compatibility.marqdo 已做版本校验;compatibility.analysis 与 .trace 虽可记录,但尚需在安装和分发前对用户请求的协议版本作严格协商。建议:
- 工具声明支持 Analysis/Trace 的版本列表;只有工具声明使用某协议时才校验该协议。
- CLI 的
SupportedProtocols {tool:1, analysis:[...], trace:[...]}是内核对外事实,不由官方工具决定。 - 安装或启动时交集为空 → 明确错误,不得尝试执行后靠 JSON 解析失败;没有声明则不强制工具使用该协议。
- 工具版本采用确定的版本语义;现有简化解析可能接受不完整表达式,要测试预发布号、边界和不合法范围。可引入小型可靠版本约束库,不需要新管理命令。
11.3 全工具包不可变完整性
当前安装记录主要保存入口文件 SHA-256。工具可能包含动态库、脚本和资产;只校验入口文件无法检测其余依赖资源变化。
最小安全可行方案:安装时计算包目录内的规范化文件清单(排除 record/staging/不随包发布资源),为每个文件记录相对路径、大小、SHA-256;分发前至少验证完整包摘要或每个条目。采用不可变用户工具目录,安装/卸载基于 staging + atomic rename,禁止 symlink、路径逃逸和重复覆盖。若确需可写运行数据,应放到独立 state/cache 目录而非安装包内部。
注意:这保护的是安装后完整性,不证明工具作者可信。来自网络的来源认证应由未来可信索引或签名解决,不应借本阶段强行添加内置官方工具市场。
11.4 Tool 进程安全说明
工具运行在用户权限下,不是 .mq.md 的 pure/project/strict 沙箱。继承环境变量可能泄漏调用者的密钥,默认应在规范里明确说明;若未来支持受限工具运行,则需新的显式权限模型,不得把 Tool 当成已沙箱化。
11.5 Tool 黑盒验收
- 与 CLI 完全无关的
benchmark、my-quantum-lab安装后正常转发 Unicode 参数、空格、stdin/stdout/stderr 与退出码。 - 工具只支持 Analysis v2,而 CLI 只支持 v1 → 安装/分发明确失败。
- 辅助脚本被篡改 → 拒绝启动,即使入口文件未变。
- 已安装注册文件中的
entrypoint被手工改成../outside→ 拒绝。 - 与内置命令冲突 → 安装拒绝;不同外部工具重名 → 不覆盖已安装内容。
- 工具不需要 Analysis/Trace → 不应被强迫支持它们。
- 删除工具后同名命令回到 unknown;移除不能删除安装根以外文件。
12. H3-A:ABI Capability Broker 的真正执行闭环
12.1 当前真实边界
CapabilityBroker::authorize() 会通过 decide() 判断 fs.read / fs.write / net.request 等能力,并为审计日志记录结果;对成功授权主要返回空字节。授权被允许与操作已经执行是两回事。Worker 目前主要通过独立进程实现插件调用/崩溃隔离,并没有自动获得可验证的 OS 级权限限制。
12.2 目标接口:Request → Authorize → Execute → Reply → Audit
Plugin process Host Broker Authorized Service
request ─────────► 解析/身份核验
│
├── deny ────────► 错误 + 审计
│
▼
grant intersection
│
▼
execute service
│
reply ◄──────┘
- 请求必须携带与 Worker 会话绑定的真实插件身份(不可由插件文本单独决定)、本次调用身份、操作名和结构化参数。
- 有效授权 = Host 当前策略 ∩ 用户显式授权 ∩ 当前任务/插件上限,manifest 只能请求不能授予。
- Broker 不只是返回
Ok(());真正实现的核心操作必须产生明确结果与结构化错误。尚未支持的能力返回capability.unavailable,不能用空字节冒充执行成功。 - Worker 内的 native 代码不能自动通过这种 Host API 获得 OS 沙箱;必须按 H3-B 的 OS 隔离要求同时限制其直接 syscall。
- Vendor capability 可以使用独立可信 Handler 注册,但不得通过名称猜测把未知能力提升为可用;其注册/调用均受权限和审计约束。
12.3 最小实现范围
建议先打通一个 fs.read 受限路径的端到端插件示例,返回受限测试文件内容。网络、任意进程、复杂设备操作暂不实现,留在 unavailable。不要求为了实现 Broker 而发明全部 Host API。
保留 PluginHandleTable 的 owner/run/generation 校验:任何从 wire JSON 重构的句柄不得自行成为授权凭据,跨运行、卸载后、跨 owner 的重放必须失败。插件 Worker IPC 应限制帧大小、请求速率、超时、总内存;崩溃后清理状态和子进程,不能残留可用句柄。
12.4 测试
- 已获授权插件读取
data/allowed.txt:Host 完成读取并返回真实内容与审计记录。 - 未授权读取
private/secret.txt:permission.denied,不返回任何内容。 - 插件请求尚未实现的
net.request:明确capability.unavailable(即使声明了名称)。 - 伪造
package_id、handle、会话代次:拒绝,无其他用户资源泄漏。 - Worker 崩溃、超时、发送超大 frame:受限失败、子进程清理、Host 正常存活。
13. H3-B:严格沙箱与 Foreign 环境
13.1 strict 的可执行定义
目前 marqdo-sandbox 在缺 OS 隔离实现时拒绝 strict,这是正确安全承诺。不可因为 Worker 已存在就把 strict 从 unavailable 改为 available。C ABI/Foreign 原生代码默认可使用其 OS 进程权限;一个子进程只能隔离地址空间和部分崩溃,不等于访问控制。
推荐先实现一个经测试的平台(优先 Linux),并清楚列出所需 OS 能力:文件系统可见范围、进程启动、网络访问、CPU/内存/文件数/进程数与墙钟预算、子进程树生命周期。优先基于成熟系统级机制(namespaces、seccomp、cgroups,或受支持的现成沙箱封装),不从零写容器平台。无法获得必要机制时拒绝 strict,并报告准确原因。macOS 和 Windows 没有等价适配前继续 fail closed。
13.2 路径与时间竞争
ProjectFs 的路径检查不能依靠一次 canonicalize 后再无限信任后续路径字符串。应使用支持目录句柄相对访问的安全路径方案,明确 symlink / rename TOCTOU 攻击的负面测试。尤其写操作在检查与创建之间需要维持目录边界,不允许通过切换链接写到项目外。
13.3 Foreign Kernel 运行环境
当前 KernelRegistry 已允许注册 mocklang 等外部执行器,不能为了 Python、Node、R 增加新的解释器分发 match。但 python/node 的包依赖、具体解释器版本与执行路径还未进入锁定环境模型。
最小路线: Kernel Provider descriptor 提供 provider_id、协议版本、入口二进制内容哈希、语言别名、可选 environment_id / 环境摘要;环境管理由 Foreign/Package 协作完成,不能在 CLI 中为每种语言写一套包管理器。Python 包可委托 uv、Node 依赖可委托成熟包管理器,但必须按固定 lock 和隔离目录运行,且绝不能把 Marqdo 程序翻译成 Python。本阶段仅须能将一个指定版本的 Foreign Provider 和它的依赖在两台机器一致恢复的测试用例闭环;不用自己开发 PyPI/npm 解析器。
对于扩展脚本、网络访问、进程树及资源耗尽,strict 要真正加 OS 限制;project 模式只能说明 Host 路径受到检查,不能宣称子进程的一切 syscall 都被能力 API 控制。
13.4 可信执行验收(G-C)
- Linux strict 下插件尝试读取未授权
/etc/...、写工作区外文件、建立网络连接、启动子进程,必须被真实 OS 策略拒绝。 - 异常退出、无限递归、海量输出、fork 子进程和超大内存分配受限,不留下孤儿进程。
- 没有必要 OS 特权或内核能力时,拒绝启动 strict,并输出稳定错误码而非静默退回 project。
- 另外两个平台如未实现,CI 明确测试
strict unavailable且拒绝执行;不要将“Windows/macOS cargo check 通过”写成隔离支持。
14. 测试总策略:协议与负例优于堆叠功能
14.1 测试金字塔
| 层级 | 目标 | 位置与形式 |
|---|---|---|
| 单元测试 | 解析、归一化路径、LockGraph、摘要、版本协商、Handle owner/generation | 各 crate 的 #[cfg(test)] 或 /tests |
| 属性测试 | 纯叙述变更不影响执行语义、顺序确定性、路径迁移稳定、可逆 wire roundtrip | crates/cli/tests/properties.rs、package / value tests |
| 集成测试 | CLI 原命令的真实 exit/status/stdout、包图物化、跨模块错误 | crates/cli/tests/ |
| 协议契约测试 | 对公开 Schema 检查真实 Analysis/Trace/Tool,未知字段和版本拒绝 | tests/consumers/,Python / JS / Go 非 Rust 消费者 |
| 系统负例 | 未授权 FS/Network、Worker 崩溃、超时、沙箱逃逸、tool package tampering | 独立 Linux job,必要时专用沙箱 CI Runner |
| 跨平台 | Win/macOS/Linux 的编译 和可执行 API 合同 | GitHub Actions matrix + artifact smoke |
| 生态端到端 | 不修改 CLI,分别安装第三方 Tool、Plugin、Kernel,消费 Analysis/Trace | examples/ + crates/cli/tests/ecosystem_contract.rs |
14.2 正反测试清单(最小发布集合)
| 类别 | 正例 | 负例 | 阻断门槛 |
|---|---|---|---|
| 文档 AST | 既有 150 AST 金样持续全绿 | 无效 Markdown 执行节点报结构化错误 | G-B |
| 执行语义 | 既有 36 语义样例持续全绿 | 叙述修改与非法函数调用负例 | G-B |
| 包图 | 多版本与传递 B→C 的 lock 闭包 | 未锁依赖、缓存污染、相异内容同 ID | G-B |
| 环境 | 同锁复现 identical logical graph | sync 中途失败事务回滚 | G-B |
| 源码定位 | 跨模块错误映射到正确文件与行号 | 两包同路径不混淆 | G-B |
| Analysis | 移动项目路径后规范化摘要一致、资源可定位 | 不支持协议/无效资源拒绝 | G-B |
| Trace | 正确语义事件序列、失败终态 | 已过期/溢出/秘密数据不泄漏 | G-B |
| Tool | 未知工具名、Unicode 参数、完整 bundle 验证 | 版本不兼容、资源篡改、冲突与路径逃逸 | G-B |
| Plugin | 多导出、不同包实例、合法 handle | 错误签名、跨 owner、Worker 崩溃 | G-B(基础);G-C(不可信) |
| Kernel | 外部 mock provider 通过 wire 协议调用 | 不存在标签、协议不符、超时、越权 | G-B(基础);G-C(不可信) |
| Host Broker | 授权 fs.read 返回真实结果 |
拒绝目录外及未知 vendor 能力 | G-C(如宣传完整受控扩展) |
| strict | Linux 限权执行在可用平台有效 | syscall 越权、孤儿进程及不可用平台拒绝 | G-C |
14.3 JSON Schema 验证必须是实例验证
目前 CI 有 json.loads(schema),只能证明 Schema 文件本身是合法 JSON,不能证明导出结果符合它。应使用真实 JSON Schema 2020-12 validator(Python jsonschema、Rust 对应库或等效工具)在 CI 上完成:
emit actual Analysis artifact
emit actual Trace artifact
read actual Tool manifest
validate each against the advertised matching schema
modify one required field to a wrong type -> validation must fail
modify schema_version to an unsupported value -> consumer must reject
此外,Schema 本身必须提供足够的约束;若只把 functions 写成 {type: array} 而不约束内部 id/signature/span,测试无法防止破坏性回归。需以真实公开消费者需要的字段为依据定义 required、enum、格式和 ID 关联检查,而不是机械复制私有 Rust 结构。跨记录一致性(资源 span 在源文件长度内、引用 target 存在等)需额外语义校验,Schema 无法替代。
14.4 完全独立的模拟消费者
至少维护三个与 CLI Rust workspace 无任何源码链接的消费脚本:
tests/consumers/analysis_consumer.py:从 Analysis 获得函数、签名、规范体、公式与代码资源及依赖,证明 Knowledge 不需内部 AST。tests/consumers/trace_consumer.py:读 Analysis + Trace,验证analysis_digest、按 ModuleId 定位运行事件,检测移动路径/旧数据。tests/consumers/tool_consumer.py或可执行 fixture:实现未知名称的 Tool,声明准确协议版本,直接调用 CLI 并解析结果,验证返回码和版本协商。
消费者不应包含对 crates/marqdo-* 的 use / import。应在 CI 中以真实二进制和文件运行,而非调用 CLI 内部 Rust 函数。
14.5 跨平台 CI 修改建议
当前 .github/workflows/ci.yml Linux 全量测试,Windows/macOS cargo check。G-B 前调整为:
linux: fmt + clippy + full tests + schemas + examples + C ABI + tool/kernel
windows: cargo test --workspace + tool/analysis/package portable smoke
macos: cargo test --workspace + tool/analysis/package portable smoke
linux-security: strict/worker/fs security negative tests (具备相应隔离条件时)
不能把“当前跨平台检查通过”误写成“运行时跨平台支持充分测试”。Windows/macOS 遇到只能 Unix 执行的 shell fixture,应使用 Rust 构建的小工具或跨平台脚本替代,不应静默 skip 对应合同测试。
14.6 可执行的基本命令清单
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p marqdo-cli --test properties
cargo test -p marqdo-cli --test package_env
cargo test -p marqdo-cli --test analysis_trace
cargo test -p marqdo-cli --test tool_protocol
cargo test -p marqdo-cli --test plugin_worker
cargo build -p marqdo-cli
./target/debug/marqdo check examples/multi-module/index.mq.md --refs --emit ./analysis.json
./target/debug/marqdo run examples/hello.mq.md --trace-file ./trace.json
以上既有命令按当前仓库确实存在的接口写出。后续新增协议版本参数应在 ADR 中明确,不得以本文示例伪装成已实现选项。
15. 分阶段交付与明确停机点
S0(立即):审计和 CI 基线
修改: properties.rs fixture 依赖、CI、STATUS.md。
完成条件: 完整新 clone 在 CI 通过;保留现有 AST、semantic、negative、Tool、ABI、Kernel 回归。此阶段不改语言语义、包协议、Tool 协议。
S1(G-B 前置):可复现锁图与包文件集
修改: marqdo-package, cli/src/commands.rs, spec/package-format.md, lock 迁移 fixtures。
实施顺序: 先设计 lock v3 ADR 和 fixtures → 实现统一文件集哈希 → 完成包闭包图 → 严格校验所有锁边 → 一致性 sync → 跨机器与错误注入测试。
完成条件: path/Git 双来源、A→B→C、多版本 A→B1/B2、缓存污染、生成文件、事务失败全部通过;run/check 不自动联网或改锁。
S2(G-B 前置):源码身份与公开语义协议
修改: marqdo-value/runtime 的源码身份、cli/src/{analysis,trace}.rs,spec/analysis-v2.md、Schema,外部消费者测试。
实施顺序: 定义逻辑身份与 digest → 修跨模块 RuntimeError → 资源级投影 → 版本化 Analysis/Trace → 独立消费脚本 → 跨目录与跨机器复现测试。
完成条件: 同一项目位置无关,资源可定位,Trace 能对上分析与源码,任何未知协议/资源类型不会被伪装为支持。
S3(G-B 前置):Tool 兼容性与完整包验证
修改: cli/src/tool.rs、spec/tool-v1.md(如破坏性变化则 v2)、bundle fixtures、schema/契约测试。
实施顺序: 定义 SupportedProtocols → 实装版本交集检查 → 统一 bundle 内容清单 → 注册/执行前完整性验证 → 黑盒未知工具测试。
完成条件: 任意名字工具安装调用无需修改核心;不兼容或被篡改工具被可靠拒绝;工具不受 Knowledge/Proof/View 特殊待遇。
S4(G-B 收尾):质量门槛、协议冻结、独立仓库启动
修改: CI 跨平台运行测试,公开 Schemas 的真实验证,STATUS.md、Release notes/兼容性表。
完成条件: 通过 G-B;发布 marqdo-cli 与公开协议版本;Knowledge、Proof、View 可在独立仓库仅依靠发布二进制和标准文件继续开发。
S5(G-C 可独立推进):安全执行闭环
修改: Host Broker 实际受控服务、Worker IPC/预算、Foreign 锁定环境、marqdo-sandbox Linux adapter、安全负例与 per-platform policy。
完成条件: 只在通过真实 OS 隔离测试的平台宣称 strict 可用;不支持平台 fail closed。该阶段不得要求 Knowledge、Proof、View 修改核心语义。
各阶段必须附有: 一份可复现的失败测试(先红)、最小实现、通过证据、协议/安全影响说明、明确不实现范围。若某阶段试图增加大量 CLI 命令或业务功能,应拒绝并拆到独立仓库。
16. 如何与现有规范、ADR、状态表协同
建议阅读顺序:
README.md、AGENTS.md:项目定位和开发原则。spec/markdown-profile.md、spec/mapping.md、spec/evaluation.md、spec/references.md:语言的权威行为。docs/adr/0008—0015:已接受的包身份、Callable、ABI、Broker、Provider、Tool、Handle、Analysis/Trace 决策。spec/package-format.md、spec/tool-v1.md、spec/analysis-v1.md、spec/trace-v1.md、spec/security.md:当前公开/候选协议。- 本文:当前基线上的缺口、修复设计、实施顺序与验收。
docs/STATUS.md:随每次合并同步的实现状态,不能以旧状态覆盖最新证据。
注意:仓库部分 spec/ 文件还带有旧阶段 Proposed 文案,与代码已实现状态冲突。每次规范变更都要做一次 spec ↔ code ↔ tests ↔ STATUS ↔ README 五方核对,不可让“完成”只出现在文档中。旧 docs/NEXT_PHASE_IMPLEMENTATION.md 是 M0.6 设计背景及前阶段实施计划,不能再将其中“尚未实现”作为新 HEAD 的现状。应由本文补充新的当前阶段权威基线,并在它们首页相互指向,避免维护两份冲突的“最新开发任务”清单。
16.1 PR 模板最低要求
## Problem
- 问题 ID:B-xx / Sx
- 当前失败的公开可运行测试(链接)
## Scope
- 改哪些 crate 和协议
- 明确哪些语言语义/CLI 命令不改变
## Why this design
- 为什么不在 Tool/Proof/View 内实现
- 备选方案和舍弃原因
## Verification
- 新增正向、负向、属性、跨平台/跨仓测试
- cargo fmt / clippy / test / Schema / CI 链接
## Compatibility & security
- 格式版本、迁移方式、拒绝降级行为
- 权限和可信边界是否变化
任何会改变用户可见行为的更改必须有 ADR;仅内部错误修复可只增加测试和状态记录。check --emit / run --trace-file 是对外协议的一部分,其字段变化不能以“内部重构”掩盖。
17. 新开发者第一周执行清单
- 克隆仓库、记录完整 HEAD 与 CI 状态;运行全工作区测试,复现并修复 B-01;不要先开发新功能。
- 阅读语言语义规范和 ADR-0008—0015,确认外部 CLI Tool / ABI Plugin / Foreign Kernel 的不同边界。
- 从
build_lockfile、resolve_alias_from、check_lock和hash_tree画出已有包解析数据流,先写 A→B→C 失败 fixture,再提出 lock v3 ADR。 - 在两份不同绝对路径下生成 Analysis v1,确认 root_id 的迁移不稳定问题;设计不依赖路径的逻辑身份和 source/analysis digest。
- 从
marqdo-ir::Resource和cli/src/analysis.rs::build对照实际资源种类,设计可定位资源数组;避免重新解析 Markdown 成执行语义。 - 用两个不同模块创建真实运行错误,先写失败测试,再让
RuntimeError携带模块身份。 - 使用陌生工具名制作第三方 Tool,验证不修改任何核心源码即可接入;对 Tool、Analysis、Trace 的版本不兼容写黑盒负例。
- 合并修正后更新对应
spec、ADR、STATUS、CI;每个版本门槛以真实 run URL 而非文字宣称为准。
18. 不在本阶段实现的内容(防止再次膨胀)
明确不作为 G-B 的阻断项:
- Marqdo 知识图谱构建、OKF 导入导出、向量检索、Agent 记忆(marqdo-knowledge)。
- Lean 证明义务、证明证书、数学/程序证明系统(marqdo-proof)。
- Markdown 前端、交互式编辑器、实时调试可视化、网站生成(marqdo-view)。
- bytecode VM、JIT、复杂 CAS、矩阵/微积分全套、完整 registry、自动更新器、包发布门户。
- 新的
marqdo graph、marqdo prove内置子命令枚举、marqdo view内置模块、marqdo kernel/env管理命令等。外部工具通过已实现的通用 Tool 协议自行注册。 - 任何需要“核心先知道官方扩展名字”才能工作的接入机制。
特别说明: G-B 并不要求所有潜在外部用例都已经实现,而要求公开数据模型没有已知错误,且能支持真实独立消费者。Proof 的全语言形式化验证范围仍应由它自己的仓库定义,不得借“为未来 Proof 预留”要求 CLI 公开一套未经验证的超大 IR。
19. 最终验收与准入判定模板
Commit: <full SHA>
Release/Profile: <core version> / <markdown profile>
CI Linux full test: <URL> PASS|FAIL
CI Windows runtime contract: <URL> PASS|FAIL
CI macOS runtime contract: <URL> PASS|FAIL
Lock graph tests: PASS|FAIL
Package integrity / transactional sync: PASS|FAIL
Cross-module diagnostic source: PASS|FAIL
Analysis identity / resources / digest: PASS|FAIL
Trace source / stale detection / quota: PASS|FAIL
Tool generic name / compat / bundle integrity: PASS|FAIL
Schema instance validation / external consumers: PASS|FAIL
G-A: PASS|FAIL
G-B: PASS|FAIL
Linux strict isolation negative tests: PASS|FAIL|UNAVAILABLE
macOS strict isolation: PASS|FAIL|UNAVAILABLE
Windows strict isolation: PASS|FAIL|UNAVAILABLE
G-C per-platform: <precise result>
Unresolved risks with owners: ...
G-B 的成功标准不是“功能菜单齐全”,而是 Marqdo 在不依赖外围仓库的条件下正确运行,依赖可重建,第三方工具无须改核心即可接入,知识/证明/View 可稳定消费同一套公开事实。G-C 才允许严格宣称“不可信代码受 OS 隔离执行”。若某项条件仍失败,应保持对应门槛未达成,不能用任务数量或测试通过百分比替代。
附录 A:本次审查源码入口(固定 HEAD)
- GitHub 当前核心仓库
- Linux CI 失败与 Windows/macOS cargo check 结果
- CLI 命令实现
- PackageResolver 与 hash_tree
- Analysis 导出
- Trace 导出
- CLI Tool 协议实现
- CapabilityBroker
- Worker 子进程
- 现有公开 Analysis v1
- 现有 Tool Protocol v1
附录 B:参考工程与使用边界
- Cargo:学习 lockfile 中 package instance、来源、完整依赖图与 CLI 外部子命令;不照搬 Cargo 的全部包发布和 registry 产品。
- uv:学习项目环境、依赖锁定、显式同步与可重复构建;只在需要 Python Foreign 环境时复用其能力,绝不将 Marqdo 作为 Python 翻译器。
- CommonMark / GFM:作为 Markdown AST 输入规范;不允许第三方随意重定义执行 AST 节点。
- JSON Schema 2020-12:外部消费者合同的结构验证,需搭配跨对象语义验证。
- Language Server Protocol / Debug Adapter Protocol:未来 View/IDE 的可选互操作参考;不要求 Core 在本轮实现 IDE 服务器。
- Lean 4:Proof 项目的可信证明内核;不能把外部形式模型自动等同于 Marqdo 真实执行语义。
本文件是开发与验证规范,不是已经实现上述功能的声明。所有建议都须以新增测试、ADR 和真实 CI 证据落实。
附录 C:修订包来源说明(原 marqdo-cli-stabilization/README.md)
以下保留整合前 docs/marqdo-cli-stabilization/README.md 的原文,作为来源与审查基线记录。该修订包现已合并入当前文档体系:主规范位于 docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md;原目录已删除。原文中的“放入仓库”表述保留为历史记录。
Marqdo CLI 下一阶段实施规范
请将
docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md放入cflmy/marqdo-cli仓库相同相对路径。
- 该文件是针对
master@0adebe42f14d72a2a275564d03ff9558f197766e的下一阶段工程设计与验收规范。- 不迁移旧
cflmy/marqdo仓库;不增加任何新的顶层命令;不将 Knowledge、Proof、View 的业务代码引入 CLI。- 实施前先刷新 HEAD/CI 基线,若仓库已发生改变,必须按最新源码修订问题状态。
- 文中拟议的 Lock v3、Analysis v2 与严格沙箱均非当前已实现功能。实现前应补充 ADR 和失败测试。