SEP-2577: 弃用 Roots、Sampling 和 Logging

​

摘要

• Roots (roots/list, notifications/roots/list_changed)
• Sampling (sampling/createMessage, ClientCapabilities.tasks.requests.sampling)
• Logging (logging/setLevel, notifications/message)

​

动机

​

Roots

• 采用率低：很少有客户端实现 roots 支持，也很少有服务端依赖它。特性支持矩阵 显示客户端覆盖率有限。
• 语义模糊：规范将 roots 描述为信息性内容——服务端并不要求必须遵守，这降低了它的实用性。
• 重叠的替代方案：工作目录上下文可以通过工具参数、资源 URI、服务端配置或环境变量提供——这些方式都更明确。

​

Sampling

• 实现复杂：正确实现 sampling 需要有人在环审批、模型选择逻辑、安全性考量，以及（自 SEP-1577 起）工具循环支持。这种复杂性导致客户端采用率较低。
• 采用率低：特性支持矩阵 显示，尽管该特性自 2024 年 11 月规范起就已可用，但支持 sampling 的客户端很少。
• 直接替代方案：需要 LLM 能力的服务端可以直接集成 LLM 提供商 API，从而完全掌控模型选择、参数和流式传输。

​

Logging

• 基础设施重叠：标准日志机制（stdio 传输使用 stderr，结构化可观测性使用 OpenTelemetry）已经成熟、被广泛采用，并且比应用协议通道更适合用于日志。
• 相对于复杂度价值较低：向核心规范添加日志消息类型、严重级别以及 logging/setLevel 请求，会增加所有客户端和服务端的实现面。

​

规范

​

变更概览

1. 在 schema 中使用 @deprecated 注解标记已弃用特性
2. 在特性文档页面中添加弃用说明
3. 在弃用期间不进行线上协议变更

​

Schema 变更

​

已弃用的能力

​

已弃用的类型 — Roots

​

已弃用的类型 — Sampling

​

已弃用的类型 — Logging

​

注解格式

/**
 * 如果客户端支持列出 roots，则存在。
 *
 * @deprecated 自本规范版本起已弃用。将在一年内发布的所有版本中包含，
 * 然后可能被移除。
 */
roots?: {
  listChanged?: boolean;
};

​

联合类型

• ClientNotification（包含 RootsListChangedNotification）
• ClientResult（包含 CreateMessageResult, ListRootsResult）
• ServerRequest（包含 CreateMessageRequest, ListRootsRequest）
• ServerNotification（包含 LoggingMessageNotification）

​

文档变更

<Warning>
**已弃用**：Roots 特性自本规范版本起已弃用。它将在 `<YYYY-MM-DD>` 发布后一年内发布的所有规范版本中保持完全可用。此后的每个版本都将继续在其发布后的一年内支持它。
</Warning>

<Warning>
**已弃用**：Sampling 特性自本规范版本起已弃用。它将在 `<YYYY-MM-DD>` 发布后一年内发布的所有规范版本中保持完全可用。此后的每个版本都将继续在其发布后的一年内支持它。
</Warning>

<Warning>
**已弃用**：Logging 特性自本规范版本起已弃用。它将在 `<YYYY-MM-DD>` 发布后一年内发布的所有规范版本中保持完全可用。此后的每个版本都将继续在其发布后的一年内支持它。
</Warning>

​

能力协商

• 支持已弃用特性的客户端和服务端 SHOULD 继续声明相应能力。
• 遇到已弃用能力的实现 MUST 仍然正确处理它们。
• 实现 SHOULD 在协商到已弃用能力时发出警告（例如在日志或开发者工具中）。
• 新实现 SHOULD NOT 添加对已弃用特性的支持，除非为了与现有对端保持向后兼容所必需。

​

时间线

• 已弃用：在下一次规范发布中（目前计划为 2026 年 6 月）。
• 包含在后续发布中：在本版本发布后一年内发布的所有规范版本 MUST 继续将这些特性作为已弃用特性包含在内。
• 按版本支持：每个包含这些特性的版本都将根据另一个 SEP 中提出的一年一版本支持策略，在该版本发布后支持它们一年。
• 移除：在本版本发布一年后发布的规范版本 MAY 完全移除这些特性。

​

理由

​

为什么要弃用，而不是迁移到扩展？

​

为什么要弃用，而不是立即移除？

​

为什么特别是这三个功能？

​

向后兼容性

• 协商较旧协议版本且包含这些功能的实现，仍可通过该版本的 schema 访问这些功能。
• 协商已移除这些功能的版本的实现，将不再能够访问这些功能。

​

安全影响

• Sampling 是这三个功能中最敏感的安全点。它允许服务器通过客户端请求 LLM completions，这会为提示注入和数据外泄创造攻击面。移除它可降低这种风险。
• Roots 会向服务器暴露客户端文件系统的信息。移除它可降低服务器利用 root 信息尝试目录遍历或访问意图边界之外文件的风险。
• Logging 的安全影响很小，但移除它可以简化协议表面面积。

​

参考实现