GaugeMesh

GaugeMesh

MCP 能力和模型路由的统一端点，同时保留协议间的身份、权限、预算、截止时间、副作用语义和因果证据。

GaugeMesh 是一款本地优先的 Rust 开发者预览版。它的范围刻意小于通用 AI 网关：每个适配器都必须保留已声明的不变量，否则必须在产生副作用前拒绝操作。路由选择采用定点运算，确定且可解释。基础部署仅需一个二进制文件，使用内存或 SQLite；无需托管控制平面、Redis、PostgreSQL、Docker 或 Kubernetes。

无需安装 Rust，即可从经过校验和验证并附带证明的 GitHub Release 安装，也可以运行多架构 GHCR 镜像。Crates.io 不是 GaugeMesh 的分发渠道。真正的 stdio MCP 服务是 gaugemesh mcp-stdio；其 Official MCP Registry 元数据已纳入版本控制，位于 server.json。

源码树还提供可选启用的有界持久化 Runs：调用方编写的计划，可基于现有 Tasks 执行，验证文件结果，明确恢复／取消，并离线验证证据。有关本地 Unix 边界及外部已安装二进制的资格验证命令，请参阅该契约。

可通过发布源码使用两种明确的首次体验路径：

• 中性、可恢复的 Run，包含可观测的工作进程效果、重启／拒绝案例和离线验证。
• 可选的教育性章节机制审查，使用相同的公共接口。原始公式保留在二进制文件之外；标准目录元数据并非获准的规则实现或审批。

运行本地验证

从发布存档开始：

gaugemesh demo

从源码开始，需使用 Rust 1.88 或更高版本：

cargo run --locked --release -- demo

此过程不会使用账户、凭据、提供商、网络目标、数据库、容器或现有 MCP 服务。该命令不会在调用方目录中写入文件。

以下是 0.1.0 发布版二进制文件的实际输出：

GaugeMesh demo

[ok] 2 MCP sources connected
[ok] 1 model route connected
[ok] colliding tool names isolated by capability identity: true
[ok] 2 capabilities leased
[ok] route selected under cost, deadline, and policy bounds
[ok] deterministic failure reproduced
[ok] recovery bounded to one attempt
[ok] duplicate effects: 0
[ok] invariants preserved or strengthened: 23/23
[ok] cleanup complete: no owned child or listener remains

Route: local-model -> docs-a__search
Decision: sha256:169a6315aa69eb7fa3e3b5aae70ede14d4c9ec71c0281d217fd84201414567f1
Evidence: sha256:9a9cdc8b673bab79ae96cf5aba5b7895d6e6e5f425407d1bd64da8701a1314e6

演示证明的内容

• 两个上游可以公开同名的原生 search，且不会共享授权身份。
• 租约会绑定精确的主体、租户、任务、架构、能力集、到期时间、范围、预算、副作用许可和清单摘要。
• 硬路由约束会先于整数操作评分和稳定的决胜规则执行。
• 一次注入的故障会耗尽唯一的重试预算；重试不会被放大。
• 经核查的转换保留或强化了 23 项不变量，没有造成语义损失。
• 只读案例未观察到任何重复效果，并且完成时没有由本进程管理的子进程或监听器。

该演示是确定性的固定测试证据，并非生产时长的耐久性测试，也不是安全认证。

可独立检查路由规划器及其版本化决策契约。最后一条命令使用内置固定测试，其中每个候选项都违反硬约束，因此输出的是与摘要绑定的 denied 决策，而不是不安全的回退方案：

gaugemesh route explain
gaugemesh route explain --decision-contract
gaugemesh route explain --deny-all
gaugemesh route schema
gaugemesh route validate decision.json

架构

MCP clients --------------------+  /mcp
                                |
OpenAI-compatible clients ------+--> GaugeMesh --> invariant + policy boundary
                                |         |             before execution
MCP servers needing models -----+  /v1/*  +--> MCP stdio / Streamable HTTP
                                          +--> OpenAI-compatible providers
                                          +--> official/private registries

ResiliReplay ---------------------- verification only; never a production hop

GaugeMesh 面向北向是 MCP 服务，面向南向是 MCP 客户端。它面向北向是兼容 OpenAI 的服务，面向南向则是已配置的兼容模型提供商的客户端。注册表记录属于发现元数据，不构成执行授权。

添加一个 MCP 服务

创建严格的回环配置：

gaugemesh init

检查并添加一个本地 stdio 服务。--command 必须解析为绝对可执行文件，并通过参数数组启动，绝不经由 shell：

gaugemesh add mcp docs \
  --command "$(command -v gaugemesh)" \
  --arg mcp-stdio \
  --protocol-revision 2025-11-25

add 会执行实时发现，并且仅在工具、资源、模板、提示词、服务身份和修订版本均可读取后才写入源配置。serve 会将经过审核的源加载到有界运行时中，固定能力快照，并拒绝架构漂移。即使可读别名发生冲突，工具、资源和提示词仍保留与源绑定的不透明身份。Streamable HTTP 源使用同一命令并搭配经过审核的 --url；Registry 搜索、检查和批准属于独立的信任路径，绝不会安装或执行发现到的包。

添加一个模型

提供方必须公开兼容的 /v1/models 端点。若要体验完整的免密钥配置，请在一个终端中保持 gaugemesh serve 运行，并在另一个终端中添加其内置的本地模型路由：

gaugemesh serve

gaugemesh add model local-provider \
  --base-url http://127.0.0.1:8090/v1/ \
  --provider-model-id local \
  --context-limit 8192 \
  --max-output-tokens 1024 \
  --cost-table-version local-2026-08-30

对于需要凭据的提供方，请传入环境变量名称，而不是其值：

gaugemesh add model hosted \
  --base-url https://provider.example.test/v1/ \
  --provider-model-id reviewed-model \
  --credential-env PROVIDER_API_KEY \
  --cost-table-version contract-2026-08

配置的路由会在选择前根据能力、上下文、截止时间、令牌、费用、重试、数据和副作用限制进行检查。费用表与版本绑定；估算值不会被表述为提供方的实际计费数据。

连接 MCP 客户端

启动数据监听器和单独绑定的健康检查监听器：

gaugemesh doctor
gaugemesh list
gaugemesh serve
gaugemesh connect generic-mcp

回环默认地址为：Streamable HTTP 使用 http://127.0.0.1:8090/mcp，模型 API 使用 http://127.0.0.1:8090/v1，健康检查使用 http://127.0.0.1:8092/healthz。官方 MCP 一致性客户端会分别连接 /mcp，以测试两个受支持的修订版本。GaugeMesh 还包含真实的 RMCP 集成测试，将其作为上游客户端通过 stdio 和 Streamable HTTP 进行测试。没有安装证据时，不会生成特定产品客户端的安装程序。

连接兼容 OpenAI 的客户端

将支持自定义基础 URL 的客户端指向 GaugeMesh：

gaugemesh connect openai-compatible
curl http://127.0.0.1:8090/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"local","messages":[{"role":"user","content":"hello"}]}'

发布门禁还会针对该基础 URL 执行 openai-python==3.6.0，以测试模型列表、聊天补全和 Responses。已实现的接口包括 GET /models、POST /chat/completions 和 POST /responses，并支持有界的 JSON 和 SSE 行为。未知请求字段会被拒绝。这是经过验证的子集，并非与 OpenAI API 完全兼容。

除非请求明确选择 GaugeMesh 模式并设置边界，否则工具执行处于关闭状态：

x-gaugemesh-tool-mode: lease
x-gaugemesh-max-tool-rounds: 1
x-gaugemesh-deadline-ms: 3000

这些扩展标头不是 OpenAI 字段。MCP 服务可以直接调用 /v1/* 来访问模型；已弃用的 MCP sampling 不会被静默转换。不受支持的 sampling 和 elicitation 路径会返回稳定错误，或进入显式审批后端。

五条不变量规则

1. 路由是有类型的信任图路径；显示别名绝不用于标识节点。
2. 主体、租户、能力、架构、因果根和来源信息均保持不变，除非经过检查的委派明确允许转换。
3. 范围、委派权限、截止时间、资金、令牌和重试次数只能减少；数据保护绝不降低。
4. 可选翻译损失具有有界整数评分；必需的语义损失会在目标执行前被拒绝。
5. 队列压力、重试消散和熔断器滞回均采用常规、可证伪的软件定义。任何物理学类比都不能凌驾于代码之上。

运行 gaugemesh route explain，查看原始 0.1.0 裸计划，其中包含已接受和已拒绝的候选项、整数评分项、稳定的平局裁定规则，以及策略／指标快照摘要。现有机器使用方仍会获得该格式。使用 --decision-contract 可选择启用带版本的 selected 包装格式。 gaugemesh route explain --deny-all 会返回新契约，其中包含 status: "denied"、稳定的 GM_ROUTE_NO_ELIGIBLE_CANDIDATE、每项约束拒绝原因，以及快照摘要。路由 ID 必须唯一；被拒绝的候选项必须带有非空原因；候选项／原因的顺序必须符合规范。selected 和 denied 契约均包含 decision_digest，这是对规范化决策字段（不含摘要本身）计算的 SHA-256 摘要。

随代码一同提供的路由决策 JSON Schema 描述了传输格式契约。保存一项决策，然后运行 gaugemesh route validate <file>，即可完全离线检查其架构、摘要，以及可推导出的选择／拒绝不变量。该摘要未签名，只提供可重新计算的完整性校验，并不能防止有能力重写整个决策的一方篡改内容。决策包含路由 ID 和约束原因；验证过程不会上传这些内容，分享前应先进行脱敏。类比的适用边界见 物理学模型。

安全边界

• 未认证模式仅限环回连接。远程模式要求 TLS、显式的 HTTPS 公共源、精确验证 OIDC issuer／audience／resource、必需的作用域、有界 JWKS 缓存、可信代理允许列表，以及默认拒绝策略。
• API 密钥基元使用随机材料（仅显示一次）、Argon2id 哈希、租户／作用域绑定和吊销机制；0.1.0 远程监听器通过 OIDC bearer token 进行认证，而非提供 API 密钥管理服务。
• 默认情况下，绝不会将下游 bearer token 传递至上游。提供方凭据保留为环境变量或受限文件引用，不作为普通 SQLite 值存储。
• 远程 URL 会拒绝不安全的方案／地址类别，固定经批准的 DNS 解析结果，绑定确切的主机／端口和对端 IP，禁用自动重定向，并限制响应正文大小。
• Stdio 使用精确 argv、kill_on_drop、启动／帧大小限制、重启预算，以及按安全边界分区的进程键。未知服务不可共享。
• 准入队列、请求正文、进程输出、SSE 输出、工具轮次和关机等待均有界。取消操作会沿自有资源传播。

请参阅 SECURITY.md、THREAT_MODEL.md 和 对抗性证据。有界的 持久化 MCP Tasks 路由介绍了其独立的故障和信任边界。GaugeMesh 不声称支持恰好执行一次、已达到生产就绪状态、普遍支持所有客户端／提供方、具有官方 MCP 身份、获得 MCP 认证或获得安全认证。

已验证的兼容性

接口	依据	结果
MCP 服务、Streamable HTTP、2025-11-25	官方一致性测试 0.2.0-alpha.11	70/70 项计分检查
MCP 服务、Streamable HTTP、2026-07-28	官方一致性测试 0.2.0-alpha.11	117/117 项计分检查
MCP 客户端、stdio 和 HTTP，两个修订版	RMCP 3.1.4 跨进程／集成测试	已验证子集
MCP Tasks 路由、2026-07-28	RMCP 任务生命周期测试，加上中立子进程资格测试；测试中仅路由器使用 SQLite 重新打开，并保留已绑定的上游会话	当前源码中已验证的有限子集
OpenAI 兼容 HTTP	原始 HTTP、提供方测试固件，以及 OpenAI Python SDK 3.6.0	已验证子集
特定产品的客户端安装	未执行	仅有文档说明或不支持

正常运行时不会提供仅用于一致性测试的合成能力。未完成或未计分的扩展检查不计入结果。记录的 0.1.0 一致性测试未声明 Tasks；当前源码仅在 2026-07-28 修订版中，于 SQLite 持久化存储可用且至少有一个经过审查、支持任务的上游时，才会声明 io.modelcontextprotocol/tasks。调用方也必须声明支持 Tasks。任务路由属于较早一致性测试计分之外的集成证据，且这些结果均不代表官方认证。请参阅 MCP 矩阵、Tasks 持久化指南、客户端级别和一致性测试清单。

无需 Rust 工具链、账户或提供方，即可从原生二进制文件显式测试持久化路由：

gaugemesh verify --durable-tasks

此内嵌资格测试会自行启动一个通过 MCP stdio 通信的合成 JSON 提供方；该提供方会将有限的 JSON 工作器作为独立的真实子进程启动。它会重新打开临时 SQLite 路由器状态，并分别报告执行结果和产物验证结果。这不是随附的通用执行器。GaugeMesh 没有后台任务调度器：上游确认后，只有在调用方之后再次轮询时，才会开始超时取消；收到取消确认并不表示已观察到任务终止。上游会话发生变化时，非终态路由可能只能进行协调；tasks/update 明确不支持持久化路由。

ResiliReplay 验证

ResiliReplay 是可选的外部工具：

gaugemesh verify --resilireplay

GaugeMesh 会使用经过清理的临时状态，通过参数数组调用精确指定的已发布 [email protected] 可执行文件。一次真实的无故障对照测试和十二条明确的故障测试记录，共产生三项通过和十项明确失败。两项通过的恢复测试是在 ResiliReplay 跟踪级别进行合成超时和确定性错误变异，随后执行真实的有限重试；0.7.0 不会将这些故障注入 MCP 线路或服务。清理已完成，故障测试报告的重复效果为零。准确的汇总结果为 PARTIAL。ResiliReplay 未为此命令生成 MCP-RES v0.2 配置文件／证据类别，因此 GaugeMesh 不作出任何 MCP-RES 声明。详情和证据摘要见验证记录。

开发

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo test --doc --workspace
cargo deny check advisories bans licenses sources
cargo audit --deny warnings

Rust 1.88 是 MSRV。托管门禁覆盖 Ubuntu 和 Windows 上的当前稳定版和 MSRV、macOS 上的稳定版、适用于 Linux x64/ARM64、Windows x64 和 macOS ARM64/x64 的原生发布归档，以及模糊测试、变异测试、Miri、AddressSanitizer、一致性测试、ResiliReplay、SPDX SBOM、校验和、证明、容器冒烟测试和干净归档执行。

贡献必须维护类型化不变量，并包含能够证伪更改的测试。请参阅 CONTRIBUTING.md。发现问题？请提交经过脱敏且可复现的错误报告，或通过问题选择器分享集成方案和使用场景。请通过 GitHub 私密漏洞报告功能报告漏洞，不要提交公开问题。

许可证

Apache-2.0。依赖项和源代码来源说明请参阅 docs/research/DEPENDENCIES.md。