Files
cflmy 9bceac910b feat(tool): negotiate protocols and verify the whole tool bundle (B-09 B-10)
- replace the hand-rolled version matcher with semver; require valid tool
  versions and marqdo ranges
- declare SupportedProtocols (tool 1, analysis 2, trace 2) and negotiate tool
  Analysis/Trace declarations at install and dispatch; disjoint/empty sets fail
  closed with tool.protocol_incompatible
- record a v2 whole-bundle manifest (path/size/sha256 + deterministic bundle
  digest), copy exactly that bundle into staging, re-verify it, and recompute it
  before every dispatch
- reject auxiliary-file, extra-file, missing-file and entrypoint tampering,
  record/command mismatches, traversal and a source root record.json
- remove tools by detaching with rename before deletion
- expose negotiated protocol environment variables to declared tools
- update tool-v1 and STATUS; add negotiation/bundle tests
2026-11-20 13:02:55 +08:00

89 lines
8.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Marqdo CLI Tool Protocol v1 — 通用外部工具协议
> 状态:Proposed,配套 `docs/NEXT_PHASE_IMPLEMENTATION.md` §5 修订 v2。任何官方/第三方工具一视同仁;该协议**不是** C ABI 插件协议。本文不声称现有 CLI 已实现此协议。
## 1. 范围与不变量
- Core 不含具体 Tool `command` 名的注册、适配、白名单、下载地址;仅维护自身原生命令集合与用户安装的工具注册记录。
- 任何语言写成的**独立可执行工具**均可安装;CLI 不链接其 Rust crate、不解释其业务子命令。
- 最小实现只支持 `marqdo tool install /path/to/tool.json`、`marqdo tool list`、`marqdo tool remove <command>`,以及未知顶层命令的已注册工具回退。
- 无索引服务、无网络时一样能够本地安装;`marqdo tool install <name>` 的远程名称解析是以后独立的可选索引能力,不要求 core 自带官方/社区工具列表。
- 工具仅能调用公开的 `marqdo` 命令/Analysis/Trace 文件协议;不得依赖私有 `marqdo-ir` 序列化、宿主内存指针或“已知官方工具名”。
## 2. 安装清单
`tool.json` 使用 UTF-8 JSON,v1 的最小规范清单示例:
```json
{
"schema": "marqdo.cli-tool",
"schema_version": 1,
"name": "benchmark",
"version": "0.1.0",
"command": "benchmark",
"entrypoint": "bin/marqdo-benchmark",
"compatibility": {
"marqdo": ">=0.1,<1",
"analysis": [2]
}
}
```
类型:`schema` 固定字符串,`schema_version` 正整数(首版仅 1),`name`/`version`/`command`/`entrypoint` 非空字符串,`version` 必须是合法 SemVer,`compatibility.marqdo` 必须是可解析的 SemVer 范围,`analysis`、`trace` 为可选的非空正整数数组;仅当工具使用该数据协议时声明。当前核心提供 Analysis v2 与 Trace v2,因此声明 `[1]`(或与 `[2]` 无交集)会在安装/分发时被拒绝。未来可以增加可选字段,但不得改变现有字段含义。
`command`:建议 `^[a-z][a-z0-9-]*$`,不得与任何内置命令或保留参数冲突;同一注册表中命令唯一,名字冲突拒绝且不覆盖。`entrypoint`:包内受控相对路径,不能是绝对路径、`.`/`..` 跳出根目录、符号链接逃逸或可直接解释的任意 shell 片段。真实文件应可执行并与目标平台匹配;若扩展名或平台格式与 OS 不兼容应显式失败。
## 3. 注册与验证
本地安装流程:读取用户指定的 `tool.json` → 校验 schema、SemVer 与协议交集 → 校验 entrypoint 不越界 → 检查内置/已注册命令冲突 → 收集**整包**规范化文件清单(相对路径、大小、SHA-256,拒绝符号链接/特殊文件/非 UTF-8 路径,限制文件数与总字节)→ 以临时目录按同一清单复制 → 对 staging 重新计算清单并要求逐项一致 → 写入记录并原子 rename 发布。失败时清理 staging,不留下半安装。
注册记录(`record_version: 2`)包含 `command`、`name`、`version`、`entrypoint`(包内相对路径)、`bundle[]`(每文件 path/size/sha256)、`bundle_sha256`、`source`、`schema_version`、`compatibility`。`bundle_sha256` 是排序后 `path\0size\0sha256\n` 的 SHA-256。注册不是来源认证;摘要只能检查安装后未被改变。对互联网下载必须额外有可信索引给出的摘要/签名;禁止在用户未同意前自动从网络下载。
运行时在启动前重新计算磁盘上的整包清单,与记录逐项比较(排除根 `record.json`),并验证 entrypoint 属于该清单、记录命令与请求命令一致、版本/协议仍兼容。任何不一致拒绝而非降低校验强度。旧记录版本不复用,提示重新安装。实现优先使用正确的跨平台配置目录 API,不要把 `~` 当成可移植的用户目录。多个用户/多个版本并存属于独立目录隔离;同一个命令只能解析到一个注册项,除非未来另有显式版本选择规范。
## 4. 分发算法
输入 `marqdo <first> <args...>`,先检查内置命令,内置优先;否则从已安装的只读注册映射查找 `<first>`。找到则重新协商 Tool/分析/追踪协议,验证整包清单与 entrypoint,使用 `Command::new(entrypoint).args(args)` **直接启动**,从调用者原样保留 `cwd`、`stdin/stdout/stderr` 和可保留的环境(敏感环境变量策略另行安全审计),原样传播退出状态;绝不调用 `sh -c`、不拼接命令字符串。
工具负责自己的命令层级与帮助,如 `marqdo benchmark run .`、`marqdo benchmark --help`。CLI 不读取或修改工具业务选项。Rust `clap` 可通过单一 `external_subcommand` 捕获未知子命令,但必须保留 `OsString` 原样传参;不能让工具要求 CLI 添加 `Command::View` 等专门枚举项。不要求工具在处理 `--help` 时调用核心。未知命令时报错;即使 PATH 中存在 `marqdo-<first>`,**没有显式注册也不能执行它**。
可选辅助环境:`MARQDO_BIN`(当前核心 CLI 的绝对路径),`MARQDO_TOOL_PROTOCOL=1`;仅当工具声明并协商了对应协议时,额外设置 `MARQDO_PROTOCOL_ANALYSIS=2` 与/或 `MARQDO_PROTOCOL_TRACE=2`。工具通过此路径运行 `marqdo check ... --emit ...` 和 `marqdo run ... --trace-file ...`,不拥有额外宿主内部 API。不得自动将密钥、项目能力授予记录、ABI 插件加载句柄或用户外联会话传给工具。
## 5. 三个独立安全域
1. **Tool CLI 进程**:用户主动安装并运行的原生程序,按当前用户身份执行。它**不受** Marqdo 的 `pure/project/strict` `.mq.md` 语言沙箱自动约束;工具执行不是安装后自动执行。
2. **Marqdo 程序**:通过 `marqdo run/call` 和 `CapabilityHost` 执行,严格隔离需受支持的 OS adapter。
3. **运行时 ABI 插件**:扩展可调用函数,必须有自己版本化 C ABI、显式信任或 isolated worker,和 Tool 注册表严格区分。
## 6. 向后兼容
`schema_version` 不支持、`marqdo` 范围不匹配、工具版本不是合法 SemVer,或声明的 Analysis/Trace 列表与核心支持集(当前 `analysis: [2]`、`trace: [2]`)无交集时,安装与分发都必须以稳定错误拒绝;错误信息包含 `tool.protocol_incompatible`。可忽略的未知扩展字段允许透传,但不能被视为隐含授权。没有声明数据协议的工具不受该检查约束,也不会收到协议环境变量。
原生命令集合是保留命名空间;未来新增与社区工具冲突的新核心顶层命令属于破坏性变化,必须经过 ADR、迁移期诊断和工具冲突统计,不能静默覆盖已有已注册工具。
## 7. 正反向黑盒测试(完成标准)
| 用例 | 期望 |
|---|---|
| `tool install` 本地清单 `benchmark` 后调用 `marqdo benchmark run .` | 无需 CLI 源码改动,可原样传参并传播退出码 |
| 将工具名改成 `lintx`,重建外部程序但不重建 CLI | 能直接注册和调用 |
| 工具没有 `analysis/trace` 兼容字段 | 可以独立使用;不强制创建分析或运行记录 |
| 工具声明 `analysis:[2]`/`trace:[2]` | 安装并分发,环境变量反映协商结果 |
| 工具声明 `analysis:[1]`、`[]` 或与支持集无交集 | 安装/分发拒绝,错误含 `tool.protocol_incompatible`,不回退猜测 |
| 工具注册名冲突 `run` 或另一已安装工具 | 拒绝,不覆盖 |
| PATH 中存在同名 `marqdo-benchmark` 但未注册 | 未知命令错误,不执行 PATH 程序 |
| 篡改已安装二进制的一个字节 | 拒绝启动,指明整包摘要不匹配 |
| 仅篡改辅助脚本、增加未列文件或删除文件 | 拒绝启动,整包清单不一致 |
| 源包包含根 `record.json` | 安装拒绝(记录文件由核心保留) |
| `entrypoint` 是 `../outside`、绝对路径或越界符号链接 | 安装失败,无残留注册 |
| 安装时被杀/写盘失败/并发安装 | 不留下半安装或不一致的注册 |
| `marqdo tool remove benchmark` | 注册与受控安装制品删除;其他工具正常 |
| `--help`、复杂 Unicode 参数和 stdin/stdout | 工具获得原样参数/流,核心不解释私有业务语义 |
验收同时要求 `marqdo-cli` **不包含** `view/knowledge/prove/benchmark` 的特殊分发匹配、下载 URL、业务参数类型及平台分支。把测试工具迁移至新的仓库,并在不同机器上单独编译安装后仍可通过本协议。
## 8. 参考
- Cargo External Tools: https://doc.rust-lang.org/cargo/reference/external-tools.html —— 可扩展子命令而无需修改核心。
- kubectl plugins: https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/ —— 独立可执行文件、自动分发的经验;其默认 PATH 信任模型不直接沿用。