diff --git a/AGENTS.md b/AGENTS.md index 2039b96..99dacdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ **Start here:** read `docs/DEVELOPMENT_BLUEPRINT.md` before proposing code. It is the project architecture baseline. Then read `docs/STATUS.md` (what is actually implemented), the relevant `spec/` files, `docs/adr/` for frozen decisions, `docs/contributor-guide.md` for the workflow, and `tests/README.md` plus the conformance fixtures. Do not assume any current implementation or legacy Marqdo syntax is authoritative. -For next-phase planning, also read `docs/NEXT_PHASE_IMPLEMENTATION.md` (M0.6 plan) and `docs/EXTENSIBILITY_AUDIT.md` (source-backed issues E01–E16). Both are **Proposed** design input: the M0.6 plan supersedes the blueprint on command-surface scope, extension registration, plugin addressing, package identity, repository decoupling and release gates, but it does not describe implemented behavior. `spec/tool-v1.md` is likewise a candidate protocol until an Accepted ADR and tests land. +For next-phase work, also read `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` (current stabilization spec, baseline `0adebe4`, defining gaps B-01–B-18 and the G-A/G-B/G-C gates), `docs/NEXT_PHASE_IMPLEMENTATION.md` (M0.6 plan) and `docs/EXTENSIBILITY_AUDIT.md` (source-backed issues E01–E16). All are **Proposed** design input: the newer stabilization spec supersedes the earlier plans on the current baseline, gap list and release gates, while the M0.6 plan supersedes the blueprint on command-surface scope, extension registration, plugin addressing, package identity, repository decoupling and release gates. None describes implemented behavior, and each must be re-checked against current HEAD. `spec/tool-v1.md` is likewise a candidate protocol until an Accepted ADR and tests land. ## Non-negotiable architectural constraints diff --git a/README.md b/README.md index c71b3ac..1254d32 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,11 @@ plugin ABI v2 are not claimed to work here. > documented Math/Foreign subset are implemented and tested; modules/package/ > security/plugin support is functional but partial; strict isolation, worker > plugins, git packages and performance/release work are not done. See -> [`docs/STATUS.md`](docs/STATUS.md) and "Deliberate limits" below. The M0.6 -> extensibility plan in -> [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) is a -> **Proposed** next-phase design, not an implemented feature list. +> [`docs/STATUS.md`](docs/STATUS.md) and "Deliberate limits" below. The +> [stabilization and ecosystem-gate spec](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md) +> and the M0.6 extensibility plan in +> [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) are +> **Proposed** next-phase designs, not implemented feature lists. ## Build @@ -167,6 +168,10 @@ tests/ conformance/negative corpus (see tests/README.md) baseline (Chinese; the M0.6 plan below supersedes it on command-surface scope, extension registration, plugin addressing, package identity, repository decoupling and release gates). +* [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md) + — proposed current-stage spec (Chinese, baseline `0adebe4`): CI/lock/source + identity/Tool/sandbox gaps B-01–B-18, H0–H3 workstreams, and the G-A/G-B/G-C + release gates. Newer than the M0.6 plan; still design input, not implemented. * [`docs/NEXT_PHASE_IMPLEMENTATION.md`](docs/NEXT_PHASE_IMPLEMENTATION.md) — proposed M0.6 plan (Chinese): extensibility fixes, callable/package/kernel registration, `marqdo tool`, Analysis/Trace v1, safety and release gates. diff --git a/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md b/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md new file mode 100644 index 0000000..4422a03 --- /dev/null +++ b/docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md @@ -0,0 +1,841 @@ +# Marqdo CLI 核心稳定化、协议冻结与独立生态准入实施规范 + +> **文档状态:Proposed / 可直接用作下一阶段工程实施基线** +> **源码审查基线:** [`cflmy/marqdo-cli@0adebe42f14d72a2a275564d03ff9558f197766e`](https://github.com/cflmy/marqdo-cli/commit/0adebe42f14d72a2a275564d03ff9558f197766e),`master`,2026-11-20。 +> **验证来源:** 对上述提交的 GitHub 源码、规范、测试、CI workflow 和 [CI run #44671025763](https://github.com/cflmy/marqdo-cli/actions/runs/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 放入本仓库。 + +本阶段执行三条主线: + +1. **H0/H1 — 正确性与可复现性**:修复当前 CI,完成全依赖图锁定、包内容标准化、`sync` 一致性、跨模块错误定位。 +2. **H2 — 外部协议可以真正被消费**:修正 Analysis 身份/资源投影,完成 Tool 版本协商、安装包完整性和跨仓黑盒消费测试;冻结公开 Analysis/Trace/Tool 的兼容规则。 +3. **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 解释器运行。 + +语言规范权威入口:`spec/markdown-profile.md`、`spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`。修改这些文件规定的语义属于**语言版本变更**,必须单独提出 ADR 和金样测试;本文件不会擅自改变它们。 + +语言核心应独立完成 Markdown AST 解析、函数和参数推断、表达式与控制流、模块/显式导入、静态检查、确定的值及错误语义、Rust 原生执行、能力检查、依赖环境。编译/运行 **不需要** Knowledge、Proof 或 View。 + +### 1.2 四个仓库如何合作 + +```text + 用户终端 + │ + ▼ + 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](https://github.com/cflmy/marqdo-cli/actions/runs/44671025763) 为 **failure**:Linux 上 fmt 和 Clippy 成功,工作区测试失败于 `crates/cli/tests/properties.rs:328`: + +```text +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. 稳定内核的工程约束 + +1. **最小语义核心**。Markdown AST 映射、表达式、函数作用域、值类型和授权的最终裁决属于核心,不能让第三方 Tool 或任意 ABI 插件覆盖。 +2. **不增加新的顶层命令**。新的功能优先通过原命令参数、现有 `tool` 协议或独立仓库实现;不要为了每个协议新增 `analyze`、`graph`、`env`、`kernel` 等新一级命令。 +3. **无二次解析与双运行时**。Knowledge、Proof、View 只消费公开的标准分析/追踪或源码,不链接和序列化私有 Rust `marqdo-ir`,不重新决定何为执行节点。 +4. **工具开放不代表语言可任意扩语法**。ABI/Kernel/Tool 的名称和实现由外部声明注册,但 Markdown 结构语义仍由核心规范控制。 +5. **构建和检查不执行**。`check` 与 Analysis 导出不得运行文档、加载动态库或启动 Foreign;依赖安装/锁定不得执行安装脚本。 +6. **来源声明不授予权限**。`marqdo.yaml`/`plugin.yaml`/`kernel.json` 的请求不是用户授权;实际能力在每次使用时受 Host 或 OS 限制。 +7. **无隐式降级**。缺少 strict 隔离、缺少已锁版本、缺少契约支持时要用稳定错误码拒绝,不能悄悄恢复为不安全/不确定模式。 +8. **允许破坏性内部重构,但对外协议必须显式版本化**。目前暂无正式稳定发布,推荐在首次 G-B 冻结前修正身份和锁文件格式;采用 ADR、迁移 fixture、Schema 版本和清楚的诊断,不要靠旧设计包袱维持错误。 + +## 4. 目标架构:改职责,不制造更多 crate + +保留仓库现有 Rust workspace,以有限模块重构职责,而不是增加一串微型 crate。建议职责如下: + +```text +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` 掩盖依赖不成立的设计。 + +修改之后固定基线: + +```bash +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 中最终冻结。应采用有约束的最小模型,避免提前开发复杂依赖求解器: + +```yaml +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#... +``` + +**关键约束:** + +1. `id` 唯一代表一个确定包实例;根名、`name`、`version` 不能作为唯一 ID,同名多版本可以并存。ID 的摘要不能仅靠未经碰撞检测的短前缀作为安全唯一性依据。若人类可读短名则必须有完整摘要消歧校验。 +2. 依赖边由“包实例 + alias → 目标实例”表示,相同 alias 在不同包的含义不必相同。 +3. 每个包实例有来源、固定 Git commit 或项目相对路径、规范化内容摘要、自己的依赖边。无锁包一律拒绝,除非处于显式生成锁定图的操作中。 +4. 锁文件记录 root manifest digest;`run/check` 默认不从网络补充依赖,也不静默改写锁。 +5. 本阶段只支持**path + pinned Git**;不要求 Registry、SemVer 求解器、依赖脚本、自动更新或签名服务。 + +### 7.3 解析流程(伪代码) + +```rust +fn resolve_lock_graph(root_manifest: Manifest) -> Result { + // 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): + +```text +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 目标模型 + +将源码位置当成不可分割的二元组: + +```rust +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: ` 改为资源数组,必要时另设 `resource_count`。资源目录内容读取仍通过源码路径/偏移而不是强行将所有文档内容复制到 Analysis。示例仅展示结构: + +```json +{ + "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 必需测试 + +1. 相同项目检出到 `/tmp/projA` 与 `/tmp/projB`,导出的**规范化 Analysis 字节**相同(需将本机诊断路径从协议中剥离或独立标注),各 ModuleId 一致。 +2. 改一行真正的执行表达式,source digest、function body、analysis snapshot digest 按规则变化。 +3. 只改普通叙述,不改变程序执行结果;函数语义节点应按明确规范保持语义等价,SourceSpan 可以变化。 +4. 一个章节下两个公式和一个代码围栏,分别拥有唯一资源记录,`Span` 和摘要可反查源内容。 +5. 两个不同包实例里存在相同 `src/index.mq.md`,模块和资源身份不能冲突。 +6. 缺失/未支持的节点不能被投影器“假装支持”:显式 `unsupported` 或稳定诊断。 +7. 导出过程中发生错误时不留下看似成功的新分析文件;已存在旧产物按现有规范正确清理。 +8. `check --emit` 过程中没有 Python/Node 进程、ABI 动态库加载和 `run` 副作用。 + +## 10. H2-B:Trace 的身份、源映射与容量边界 + +现有 Trace v1 已记录 `call.enter` / `call.exit`、`branch.eval`、`loop.iteration`、`return` 和 Host effect,默认不记录值和秘密,这个隐私立场应保留。需要修正: + +1. **根身份与 Analysis 一致**:Trace 应绑定公开 Analysis 的逻辑身份和规范化摘要,不再依赖物理目录路径哈希。 +2. **事件来源完整**:`effect` 已有 `module`;其他语义事件的源位置必须可以通过 `function_id` 或显式 `module_id` 解析,跨模块不能误读入口文件;如果语义事件不能唯一定位,增加稳定来源字段。 +3. **有限预算**:加入可复用的事件数量和字节预算,超限时要有明确 `trace.truncated` / `resource.exhausted` 结尾;不能在无限循环里无限增长 Vec 和输出 JSON。 +4. **状态确定**:运行失败仍应记录错误终态;外部工具不能把旧 Trace 误认成新执行。 +5. **机密性**:坚持不记录参数值、文件内容、密钥、句柄;未来 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` 注册,这是正确方向。保留最小: + +```bash +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 + +```text +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 测试 + +1. 已获授权插件读取 `data/allowed.txt`:Host 完成读取并返回真实内容与审计记录。 +2. 未授权读取 `private/secret.txt`:`permission.denied`,不返回任何内容。 +3. 插件请求尚未实现的 `net.request`:明确 `capability.unavailable`(即使声明了名称)。 +4. 伪造 `package_id`、handle、会话代次:拒绝,无其他用户资源泄漏。 +5. 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 上完成: + +```text +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 无任何源码链接的消费脚本: + +1. `tests/consumers/analysis_consumer.py`:从 Analysis 获得函数、签名、规范体、公式与代码资源及依赖,证明 Knowledge 不需内部 AST。 +2. `tests/consumers/trace_consumer.py`:读 Analysis + Trace,验证 `analysis_digest`、按 ModuleId 定位运行事件,检测移动路径/旧数据。 +3. `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 前调整为: + +```text +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 可执行的基本命令清单 + +```bash +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、状态表协同 + +建议阅读顺序: + +1. `README.md`、`AGENTS.md`:项目定位和开发原则。 +2. `spec/markdown-profile.md`、`spec/mapping.md`、`spec/evaluation.md`、`spec/references.md`:语言的权威行为。 +3. `docs/adr/0008`—`0015`:已接受的包身份、Callable、ABI、Broker、Provider、Tool、Handle、Analysis/Trace 决策。 +4. `spec/package-format.md`、`spec/tool-v1.md`、`spec/analysis-v1.md`、`spec/trace-v1.md`、`spec/security.md`:当前公开/候选协议。 +5. **本文**:当前基线上的缺口、修复设计、实施顺序与验收。 +6. `docs/STATUS.md`:随每次合并同步的实现状态,不能以旧状态覆盖最新证据。 + +注意:仓库部分 `spec/` 文件还带有旧阶段 `Proposed` 文案,与代码已实现状态冲突。每次规范变更都要做一次 **spec ↔ code ↔ tests ↔ STATUS ↔ README** 五方核对,不可让“完成”只出现在文档中。旧 `docs/NEXT_PHASE_IMPLEMENTATION.md` 是 M0.6 设计背景及前阶段实施计划,不能再将其中“尚未实现”作为新 HEAD 的现状。应由本文补充新的当前阶段权威基线,并在它们首页相互指向,避免维护两份冲突的“最新开发任务”清单。 + +### 16.1 PR 模板最低要求 + +```markdown +## 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. 新开发者第一周执行清单 + +1. 克隆仓库、记录完整 HEAD 与 CI 状态;运行全工作区测试,**复现并修复 B-01**;不要先开发新功能。 +2. 阅读语言语义规范和 ADR-0008—0015,确认外部 CLI Tool / ABI Plugin / Foreign Kernel 的不同边界。 +3. 从 `build_lockfile`、`resolve_alias_from`、`check_lock` 和 `hash_tree` 画出已有包解析数据流,先写 A→B→C 失败 fixture,再提出 lock v3 ADR。 +4. 在两份不同绝对路径下生成 Analysis v1,确认 root_id 的迁移不稳定问题;设计不依赖路径的逻辑身份和 source/analysis digest。 +5. 从 `marqdo-ir::Resource` 和 `cli/src/analysis.rs::build` 对照实际资源种类,设计可定位资源数组;避免重新解析 Markdown 成执行语义。 +6. 用两个不同模块创建真实运行错误,先写失败测试,再让 `RuntimeError` 携带模块身份。 +7. 使用**陌生工具名**制作第三方 Tool,验证不修改任何核心源码即可接入;对 Tool、Analysis、Trace 的版本不兼容写黑盒负例。 +8. 合并修正后更新对应 `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. 最终验收与准入判定模板 + +```text +Commit: +Release/Profile: / +CI Linux full test: PASS|FAIL +CI Windows runtime contract: PASS|FAIL +CI macOS runtime contract: 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: + +Unresolved risks with owners: ... +``` + +G-B 的成功标准不是“功能菜单齐全”,而是 **Marqdo 在不依赖外围仓库的条件下正确运行,依赖可重建,第三方工具无须改核心即可接入,知识/证明/View 可稳定消费同一套公开事实**。G-C 才允许严格宣称“不可信代码受 OS 隔离执行”。若某项条件仍失败,应保持对应门槛未达成,不能用任务数量或测试通过百分比替代。 + +--- + +## 附录 A:本次审查源码入口(固定 HEAD) + +- [GitHub 当前核心仓库](https://github.com/cflmy/marqdo-cli/tree/0adebe42f14d72a2a275564d03ff9558f197766e) +- [Linux CI 失败与 Windows/macOS cargo check 结果](https://github.com/cflmy/marqdo-cli/actions/runs/44671025763) +- [CLI 命令实现](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/cli/src/commands.rs) +- [PackageResolver 与 hash_tree](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/marqdo-package/src/lib.rs) +- [Analysis 导出](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/cli/src/analysis.rs) +- [Trace 导出](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/cli/src/trace.rs) +- [CLI Tool 协议实现](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/cli/src/tool.rs) +- [CapabilityBroker](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/marqdo-host/src/capability.rs) +- [Worker 子进程](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/crates/marqdo-host/src/plugin_worker.rs) +- [现有公开 Analysis v1](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/spec/analysis-v1.md) +- [现有 Tool Protocol v1](https://github.com/cflmy/marqdo-cli/blob/0adebe42f14d72a2a275564d03ff9558f197766e/spec/tool-v1.md) + +## 附录 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 和失败测试。 diff --git a/docs/DEVELOPMENT_BLUEPRINT.md b/docs/DEVELOPMENT_BLUEPRINT.md index 22e94ed..a84ab7f 100644 --- a/docs/DEVELOPMENT_BLUEPRINT.md +++ b/docs/DEVELOPMENT_BLUEPRINT.md @@ -10,6 +10,8 @@ **这不是对 `cflmy/marqdo` 的兼容性重构。本项目必须从语言目标出发,独立建立 Marqdo 工具链。** 旧仓库只作为经验、算法、测试和可能的代码复用来源;旧语法、旧 ABI、旧插件体系不因名称相同而自动成为新版本的兼容契约。 > **M0.6 规划说明**:`docs/NEXT_PHASE_IMPLEMENTATION.md`(Proposed)与 `docs/EXTENSIBILITY_AUDIT.md` 已在命令规模、能力注册、插件寻址、包身份、仓库解耦和发布门槛上提出新的目标方案;发生冲突时以该 M0.6 计划为准。`spec/`、已接受 ADR 与测试仍是已实现语言行为的规范来源,Proposed 内容不表示已实现。 +> +> **当前阶段基线**:`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`(Proposed,审查基线 `0adebe4`)基于 M0.6 计划之后的提交重新审查 CI、锁图、源码身份、Analysis/Trace、Tool 与安全隔离,并定义 G-A/G-B/G-C 发布门槛。该文在**当前基线、问题清单和发布门槛**上取代上述两份文档;冲突时以其为准,但同样不表示已实现。 --- diff --git a/docs/EXTENSIBILITY_AUDIT.md b/docs/EXTENSIBILITY_AUDIT.md index 08d257a..cb96e3a 100644 --- a/docs/EXTENSIBILITY_AUDIT.md +++ b/docs/EXTENSIBILITY_AUDIT.md @@ -1,6 +1,6 @@ # M0.6 扩展性审计:源码问题、改造路径与测试契约 -> 源文档 `docs/NEXT_PHASE_IMPLEMENTATION.md` §1A 的审计摘录,供开发者按问题创建 PR;具体开发次序和发布门槛请看主文档。 +> 源文档 `docs/NEXT_PHASE_IMPLEMENTATION.md` §1A 的审计摘录,供开发者按问题创建 PR;具体开发次序和发布门槛请看主文档。该审计之后的稳定化基线与 G-A/G-B/G-C 门槛见 `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`。 ## 1A. **扩展性审计(v3 增补,优先级高于后续阶段)** diff --git a/docs/NEXT_PHASE_IMPLEMENTATION.md b/docs/NEXT_PHASE_IMPLEMENTATION.md index d130530..d24045c 100644 --- a/docs/NEXT_PHASE_IMPLEMENTATION.md +++ b/docs/NEXT_PHASE_IMPLEMENTATION.md @@ -6,19 +6,21 @@ > **仓库与审查基线**:[`cflmy/marqdo-cli`](https://github.com/cflmy/marqdo-cli),`master`,commit [`0116160399fda6df69a72da438e04b0072566b0f`](https://github.com/cflmy/marqdo-cli/commit/0116160399fda6df69a72da438e04b0072566b0f),检查日 2026-11-20。 > **语言身份**:独立 Rust 解释执行的 Markdown 原生语言,`.mq.md`;新项目不从旧 `cflmy/marqdo` 仓库迁移代码或承诺旧语法/API/ABI 兼容。 > **交付目标**:在**不扩张 CLI 顶层命令面**的前提下,先消除 M0.5 中阻碍第三方扩展与多版本依赖的结构性瓶颈,再将工具链整理为轻量稳定核心;提供足够小的、版本化的公共分析与执行接口,以及 `marqdo tool` 外部工具分发机制,从而允许 Knowledge、Proof、View 三个独立仓库和第三方工具开始独立开发。 -> **判定用语**:`MUST/必须` 为本阶段规范;`SHOULD/建议` 为可经 ADR 调整的默认方案;`DEFER/后置` 不属于本轮完成门槛;`EXISTING/现有` 为仓库已有实现,不代表经本次现场构建验证。 +> **判定用语**:`MUST/必须` 为本阶段规范;`SHOULD/建议` 为可经 ADR 调整的默认方案;`DEFER/后置` 不属于本轮完成门槛;`EXISTING/现有` 为仓库已有实现,不代表经本次现场构建验证。 +> **后续阶段基线**:`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`(Proposed,审查基线 `0adebe4`)基于本计划之后的提交,重新审查 CI、锁图、源码身份、Analysis/Trace、Tool 与安全隔离,并定义 G-A/G-B/G-C 发布门槛。两者冲突时以该文为当前阶段基线;本文保留 M0.6 的设计与审计来源。 ## 0. 阅读顺序、权威性与禁止误解 本文件用于告诉陌生开发者“下一步为什么做、具体做什么、哪些不要做、怎样验收”,**不是**另起一套取代现有实现的语言规范。建议依次阅读: -1. 本文件:产品边界、M0.6 实施次序与发布条件。 -2. `docs/STATUS.md`:M0.5 当前实现的阶段性记录;该文件可能因后续修复提交而局部滞后,存在冲突时以当前源码和回归测试为准,并同步修正状态表。 -3. `spec/markdown-profile.md`、`spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`:**现有语言行为的规范来源**。 -4. `spec/package-format.md`、`spec/value-wire.md`、`spec/security.md`、`spec/foreign.md`、`spec/math.md`、`spec/plugin-abi.md`:工程协议与边界。 -5. `docs/adr/0001-*.md` 至 `0007-*.md`:已经接受的决策;若本文件要求改变其行为,先提新 ADR,不能静默覆盖。 -6. `tests/README.md`、`tests/conformance/`、`tests/negative/`、`crates/cli/tests/`:通过测试展示真实行为。 -7. `docs/DEVELOPMENT_BLUEPRINT.md`:历史 M0.5 全量设想与设计依据;**在命令规模、能力注册、插件寻址、包身份、仓库解耦和发布门槛上以本文件为新的目标方案**,已接受的具体语义规范仍以 `spec/`、ADR 和测试为准。 +1. `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`:后续稳定化、协议冻结与独立生态准入的当前阶段规范(Proposed);先用它刷新基线与发布门槛。 +2. 本文件:产品边界、M0.6 实施次序与发布条件。 +3. `docs/STATUS.md`:M0.5 当前实现的阶段性记录;该文件可能因后续修复提交而局部滞后,存在冲突时以当前源码和回归测试为准,并同步修正状态表。 +4. `spec/markdown-profile.md`、`spec/mapping.md`、`spec/expression.ebnf`、`spec/evaluation.md`、`spec/references.md`:**现有语言行为的规范来源**。 +5. `spec/package-format.md`、`spec/value-wire.md`、`spec/security.md`、`spec/foreign.md`、`spec/math.md`、`spec/plugin-abi.md`:工程协议与边界。 +6. `docs/adr/0001-*.md` 至 `0007-*.md`:已经接受的决策;若本文件要求改变其行为,先提新 ADR,不能静默覆盖。 +7. `tests/README.md`、`tests/conformance/`、`tests/negative/`、`crates/cli/tests/`:通过测试展示真实行为。 +8. `docs/DEVELOPMENT_BLUEPRINT.md`:历史 M0.5 全量设想与设计依据;**在命令规模、能力注册、插件寻址、包身份、仓库解耦和发布门槛上以本文件为新的目标方案**,已接受的具体语义规范仍以 `spec/`、ADR 和测试为准。 **不要混淆四个不同的名称**:`marqdo-cli` 是本仓库和核心工具链;`marqdo` 是用户使用的命令;`marqdo tool` 通过统一清单管理**任意**独立 CLI 工具;运行时 C ABI 插件用于扩展程序函数,**不是**外部 CLI 工具。 diff --git a/docs/STATUS.md b/docs/STATUS.md index 391d8ac..e79dd70 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -11,9 +11,13 @@ complete. > **M0.6 planning cross-reference (2026-11-20)**: this file is the M0.5 evidence > snapshot that the M0.6 audit was based on. Read +> [`docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`](CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md) +> (current-stage stabilization spec, baseline `0adebe4`), > [`docs/EXTENSIBILITY_AUDIT.md`](EXTENSIBILITY_AUDIT.md) (issues E01–E16) and > the proposed [`docs/NEXT_PHASE_IMPLEMENTATION.md`](NEXT_PHASE_IMPLEMENTATION.md) -> alongside it. The plan does not claim any gap below is fixed. Per audit item +> alongside it. The stabilization spec supersedes the earlier plans on the +> current baseline, gap list and G-A/G-B/G-C release gates; none of these plans +> claims any gap below is fixed. Per audit item > E14, where this snapshot conflicts with the current tree (for example the CI > workflow, console capability or `check --refs`), verify the source/tests at > the current HEAD and update this table rather than trusting stale prose. diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md index f34d5ee..6906413 100644 --- a/docs/contributor-guide.md +++ b/docs/contributor-guide.md @@ -14,6 +14,7 @@ marqdo-cli/ ├── README.md user-facing quickstart and limits ├── docs/ │ ├── DEVELOPMENT_BLUEPRINT.md architecture baseline +│ ├── CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md current-stage stabilization spec (Proposed) │ ├── NEXT_PHASE_IMPLEMENTATION.md proposed M0.6 plan (Proposed, not implemented) │ ├── EXTENSIBILITY_AUDIT.md source-backed E01–E16 audit for M0.6 │ ├── STATUS.md implementation matrix (P0–P7) @@ -256,10 +257,14 @@ file and function; root-only examples (for example `math.mq.md`) define no * `spec/` = normative contracts; `docs/` = architecture/decisions/status; `README.md` = user quickstart; `AGENTS.md` = contributor rules. -* `docs/NEXT_PHASE_IMPLEMENTATION.md` and `docs/EXTENSIBILITY_AUDIT.md` are the - M0.6 planning/evidence pair. The plan is **Proposed**: it supersedes the - blueprint only on command-surface scope, extension registration, plugin - addressing, package identity, repository decoupling and release gates. +* `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md` is the current-stage + stabilization spec (baseline `0adebe4`). It supersedes the M0.6 planning pair + on the current baseline, gap list (B-01–B-18) and the G-A/G-B/G-C release + gates. `docs/NEXT_PHASE_IMPLEMENTATION.md` and + `docs/EXTENSIBILITY_AUDIT.md` remain the M0.6 planning/evidence pair. All are + **Proposed**: the M0.6 plan supersedes the blueprint only on command-surface + scope, extension registration, plugin addressing, package identity, repository + decoupling and release gates. Language semantics remain normative in `spec/` + Accepted ADRs + tests, and `spec/tool-v1.md` is a candidate protocol until an ADR and implementation tests land. Never cite these proposed documents as evidence that a feature