Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

草案流程
字段值
SEP2484
标题要求标准轨道 SEPs 在达到最终状态前通过一致性测试
状态草案
类型流程
创建于2026-03-27
作者Paul Carleton (@pcarleton)
赞助人无
PR#2484

​
概述

此 SEP 为标准轨道 SEPs 的 Accepted → Final 过渡增加了一项一致性测试要求。对于会改变可观察协议行为、并希望标记为 Final 的标准轨道 SEP，必须先将一个覆盖其规范性要求的一致性场景合并到一致性仓库中，并附带一个结构化的可追溯性文件，将每一项 MUST/MUST NOT 和 SHOULD/SHOULD NOT 映射到某个检查项或已文档化的排除项。这样可以让一致性套件随着规范演进而保持同步，为 SDK 维护者提供可执行的实现目标，并使 SEP-1730 的分层百分比成为对规范覆盖率有意义的衡量。流程类和信息类 SEPs 以及没有可观察协议行为的标准轨道 SEPs 免于此要求。

​
动机

​
规范与实现之间的差距

MCP 规范是用英文写成的。SDK 维护者会把这些英文翻译成代码，而每一次翻译都有可能产生偏移。SEP-1730（SDK 分层）已经依赖一致性测试（Tier 1 需要 100% 通过率，Tier 2 需要 80%），但没有任何机制能让测试套件与规范保持同步。当某个 SEP 达到 Final 时，SDK 维护者会根据文字说明来实现，并希望自己和其他所有 SDK 的理解一致。一致性测试通常会更晚才出现，如果最终出现，它们有时会揭示两个“合规”的 SDK 其实并不一致。

​
为什么现有的参考实现要求不够

参考实现 证明该功能能够被构建出来：即一种有效解释。一致性测试 则定义了每个实现必须如何表现：把规范性要求写成可执行断言。TypeScript 的参考实现并不能告诉 Rust 维护者他们的代码是否正确。一致性测试则能明确告诉他们；如果不能，分歧就会暴露出规范本身存在歧义。

​
让一致性测试套件持续更新

一致性套件是 SEP-1730 分层百分比所依据的标尺。如果它落后了，某个 SDK 可能会在遗漏大量规范特性的情况下仍被称为“100% 合规”。把测试与 SEP 生命周期绑定起来，就形成了一种推动力：套件会与规范一样快地增长。

​
规范

​
范围

此要求仅适用于引入或修改可观察协议行为的标准轨道 SEPs：即符合实现可以通过检查线上消息、传输层可观察的副作用（HTTP 状态码、头部、连接生命周期、OAuth 重定向），或本地传输的进程可观察副作用（stdio 流内容、退出码）来检测到的行为。 以下内容豁免：
  • 流程类 SEPs（治理、工作流、社区结构）
  • 信息类 SEPs（没有规范性约束力的指南、最佳实践）
  • 没有可观察协议行为的标准轨道 SEPs，例如：
    • 仅对现有行为进行文档性澄清
    • 不会改变校验或运行时行为的 schema 注释
    • 描述实现加固而非线级要求的安全建议
一致性套件本身并不局限于官方 SDK。任何实现（官方 SDK、社区 SDK 或自定义部署）都可以运行它并报告合规百分比。

​
要求

对于在适用范围内的标准轨道 SEP，要从 Accepted 过渡到 Final，必须满足：
  1. 一个带有 SEP 编号标签的一致性场景 已合并到一致性仓库中，并以即将发布版本的一致性仓库草案 spec-version 标签为目标。
  2. 一个可追溯性文件 与该场景一并提供。见下文。
  3. 该场景在 SEP 的参考实现上通过。
当该规范版本发布时，作为正常发布流程的一部分，该场景的 spec-version 标签会从草案标签更新为带日期的版本。一致性执行器和被测 SDK 都必须把草案标签识别为可协商的协议版本，这样新要求才能真正被执行。

​
可追溯性文件

可追溯性文件是一致性仓库中的一个结构化文件（sep-NNNN.yaml）。它将 SEP 的 Specification 部分中的每一条规范性要求映射到执行该要求的检查项，或者说明其被排除的原因： 
sep: 1234
spec_url: https://modelcontextprotocol.io/specification/draft/section#anchor
requirements:
  - check: sep-1234-foo-present
    text: "MUST include `foo` in the response"
  - check: sep-1234-bar-absent
    text: "MUST NOT send `bar` before initialization"
  - check: sep-1234-qux-present
    text: "SHOULD include `qux` when available"
  - check: sep-1234-baz-rejected
    text: "MUST reject requests with invalid `baz`"

  - text: "MUST retry on 503"
    excluded: "Requires fault injection; not currently supported by framework"
    issue: https://github.com/modelcontextprotocol/conformance/issues/N
  - text: "MUST be rendered in a monospace font"
    excluded: "Client rendering; not observable at the protocol level"
结构化数据使工具能够把检查失败链接回规范章节，并让一致性 CLI 按 SEP 报告覆盖率。 排除项有两种类型。框架缺口（该行为可观察，但框架暂时还不能表达）应链接到一个跟踪 issue。非协议可观察（该要求约束的是客户端渲染、实现内部，或类似内容）只需要 excluded 原因即可。若某个 SEP 的要求全部属于第二类，那么它本身就免于此要求，完全不需要场景。 赞助人负责核实可追溯性文件是否完整：SEP 的 Specification 部分中的每一项 MUST、MUST NOT、SHOULD 和 SHOULD NOT（以及 RFC 2119 的等价项：SHALL、REQUIRED、RECOMMENDED）都必须有一行对应。SHOULD 级别要求的检查项应报告为警告而不是失败。MAY 要求不需要对应行。赞助人不审查测试代码；测试代码审查是一致性仓库正常的 PR 审查流程。哪些内容算作规范性要求，由赞助人判断。

​
谁编写测试

赞助人 负责确保一致性场景被编写出来。场景使用 TypeScript 编写；不熟悉一致性仓库的贡献者应先阅读其 CONTRIBUTING 指南。实际上，SEP 作者通常最适合来做这件事，因为编写测试会暴露出规范性语言中的歧义，而在 Final 之前修正这些歧义要比之后便宜得多。

​
规范文本具有权威性

一致性测试源自规范文本，并且从属于规范文本。当测试与规范不一致时，以规范为准，而测试是错误的。

​
一致性测试争议

如果实现者认为某个已合并的一致性测试与规范相矛盾，他们应在一致性仓库中开 issue，并引用具体的规范文本。当一致性维护者加上 disputed 标签后，该测试即被视为存在争议；在争议解决之前，这类测试不会影响 SEP-1730 的分层评估。 大多数争议会通过正常的 issue 分流流程解决：要么修正测试，要么澄清规范，要么带着理由关闭争议。如果分歧是根本性的（争议方与一致性维护者无法就规范含义达成一致），任一方都可以单方面升级给 Core Maintainers 进行裁定，尽管更推荐双方共同升级，因为目标是消除歧义，而不是赢得争论。如果某个场景 PR 因非技术原因受阻，赞助人也可以走同样的升级路径。

​
测试稳定性与分层

SEP-1730 的分层评估是在一个固定的一致性发布版本上运行的，而不是仓库最新提交上。某个 SEP 达到 Final 之后，新增加到该 SEP 场景中的检查项（无论是额外边界情况，还是对先前排除要求的覆盖）会进入一致性仓库主分支，但只有在下一次分层评估采用更新的一致性发布时，才会影响分层百分比。 这意味着 SDK 维护者在两次分层评估之间拥有稳定目标，同时一致性套件可以持续演进，而不会在分层状态上带来意外回归。

​
赞助人职责

SEP-1850 规定，在将 SEP 标记为 Final 之前，赞助人需要负责跟踪参考实现的进展。此 SEP 扩展了这一职责：对于适用范围内的标准轨道 SEPs，赞助人还需确认：一个带有 SEP 编号标签的一致性场景已与完整的可追溯性文件一并合并，或者该 SEP 中已记录豁免。

​
与 SEP-1730（SDK 分层）的关系

此 SEP 在不改变 SEP-1730 的分层定义或阈值的前提下，加强了其基础。分层评估使用固定的一致性发布，因此新检查不会追溯性地影响分层状态。存在争议的测试在解决前不计入分层百分比。 涵盖现有规范行为的场景贡献（即未绑定到新的 SEP）仍然受欢迎，而且不要求附带可追溯性文件。

​
与 SEP-1627（一致性测试）的关系

此 SEP 通过接受一致性仓库作为一致性测试的规范归宿，并将其在 SEP 生命周期中的角色正式化，取代 了 SEP-1627。SEP-1627 的 golden-trace 方法未被延续；scenario-and-checks 模型以运行时表达能力换取了语言中立的夹具。SEP-1627 关于协议调试器的想法仍然是有价值的未来工作。

​
理由

​
为什么以 Final 作为门槛，而不是 Accepted？

如果以 Accepted 作为门槛，就需要在核心维护者尚未同意该特性应纳入规范之前先编写测试，这会把精力浪费在被拒绝的 SEP 上。 话虽如此，在 SEP 起草期间编写一个一致性测试通常很有价值：它会强迫人们在 MUST/MUST NOT 语言上保持精确，并暴露出正文中一笔带过的边界情况。作者被鼓励在核心维护者评审之前起草一个一致性场景，尤其是对于具有复杂行为要求的 SEP。这不是强制要求，因为较小的 SEP 可能不足以值得这份前期投入，而被拒绝的 SEP 的测试也会变成白费功夫。 以 Final 作为门槛，把硬性要求放在参考实现要求本来就所在的位置：SEP 已经达成共识，剩下的工作就是实现。

​
为什么需要一个可追踪性文件？

如果没有定义明确的覆盖标准，“有一个一致性测试”就会在每个 SEP 上被反复争论：一个检查是否足够，还是每一条 MUST 都必须覆盖？可追踪性文件使覆盖情况可审计：每条规范性陈述都有一行，而每一行要么是一个检查项，要么是一个有文档记录的排除项。“足够”就变成了“文件完整”。 这个文件还能让缺口显而易见。一个有十条 MUST、却有八条排除项的 SEP 会释放出一个信号：要么这个 SEP 确实很难测试（跟踪问题里会说明原因），要么测试作者提前停手了（赞助人应当提出异议）。

​
为什么把作者责任放在赞助人身上？

赞助人已经负责推动 SEP 通过评审、跟踪参考实现，并管理状态转换。增加“确保编写一致性测试”只是对现有职责的小幅扩展，而且责任归属清晰。

​
考虑过的替代方案

要求在 SEP PR 本身中就包含一致性测试。 被拒绝：这会把两个彼此独立、由不同维护者和 CI 处理的评审流程耦合在一起。 只对“重大” SEPs 设门槛。 被拒绝：“重大”是主观的。可观察行为的范围是客观的：一个符合规范的对等方要么能检测到这个变化，要么不能。 让一致性维护者来判断是否足够。 被拒绝：这会把否决权集中到一个并非经选举批准规范变更的群体手中。可追踪性文件模型让赞助人无需阅读测试代码即可验证完整性。

​
向后兼容性

本 SEP 不具有追溯性。在本 SEP 生效之前已经达到 Final 的 SEPs 不需要补充一致性测试，不过欢迎贡献。

​
安全影响

没有直接影响。运行会涉及安全相关行为（认证流程、输入验证、传输安全）的一致性测试，能够通过捕获回归来改善生态系统的安全态势，但本 SEP 除了底层 SEP 的 MUST 要求之外，并未强制任何特定的安全覆盖。

​
参考实现

一致性仓库已经展示了本 SEP 所形式化的场景标记模式： 结构化的可追踪性文件格式以及场景脚手架工具（npx @modelcontextprotocol/conformance new-scenario --sep <number>）将在本 SEP 达到 Final 之前添加到一致性仓库中。 流程变更通过更新 docs/community/sep-guidelines.mdx 来实现，以便在 Accepted → Final 的转换中加入一致性检查（参见本 PR 中随附的变更）。

​
进入 Final 状态的前置条件

在本 SEP 自身可以被标记为 Final 之前，以下一致性仓库工作必须完成：
  • 结构化可追踪性文件格式（sep-NNNN.yaml）及其 schema
  • 场景脚手架工具
  • 一致性测试框架支持将草案规范版本标记作为可协商的协议版本
  • MAINTAINERS.md 已发布，并且仓库已列入 MCP 治理文档
这些是本 SEP 自己的参考实现清单，而不是持续性的流程要求。