typescript-sdk 代码审查约定(Review Conventions):从设计判断到协议正确性的完整 PR 评审指南

原创2026-09-14 23:01:051,930 阅读
文章标签:后端MCP 服务MCP Clients人工智能WebSocketRPC框架

typescript-sdk 代码审查约定(Review Conventions):从设计判断到协议正确性的完整 PR 评审指南

本篇指南系统梳理 ty/typescript-sdk(Model Context Protocol 官方 TypeScript SDK)仓库的 PR 代码审查约定(REVIEW.md),涵盖 6 条稳定指导原则、审查优先级排序、四大类检查清单,以及从过往人工评审中沉淀出的 8 类高频问题(Recurring Catches)。读完本文,你将掌握一套可直接复用的评审流程:如何判断新抽象是否值得进入 SDK、如何核对协议与 schema 的正确性、如何排查异步生命周期缺陷,以及如何在 CI 审查中避免主观臆断。

总体定位:REVIEW.md 是什么

REVIEW.md 是面向该仓库评审者的工作规范文档。文档自述其结构特点:前三个章节(Guiding Principles、Review Ordering、Checklist)是稳定原则,而 Recurring Catches 一节由过往人工评审轮次自动维护、随仓库演进持续增长。这意味着评审者在提交新 PR 前,应当先扫描 Recurring Catches 中是否已有同类问题被标记过——这些条目都附带了实际 issue/PR 编号(如 #1707、#1770),可作为历史依据。

仓库的整体技术栈也决定了评审重点:核心协议实现位于 packages/core-internal/src(含 wire schema 生成、错误分类、类型系统),客户端与服务器分别在 packages/client/src/client 与 packages/server/src/server,测试统一使用 vitest(见各包的 vitest.config.js 与根目录 vitest.workspace.js)。

六条指导原则:评审的价值观底座

文档给出的 6 条原则决定了这个仓库"什么东西值得进 SDK"的基本盘:

  1. 极简主义(Minimalism)——SDK 应该做得更少而非更多。协议正确性、传输生命周期、类型、干净的处理上下文属于 SDK;中间件引擎、注册表管理器、builder 模式、内容辅助工具应留在用户侧(userland)。
  2. 新增举证责任(Burden of proof is on addition)——对"是否要加这个?"的默认答案是否。从公开 API 移除某物远比不添加它困难,因此新增必须自证价值。
  3. 用具体证据说话(Justify with concrete evidence)——每个新抽象必须有当下的真实消费者。评审者应要求真实 issue、基准测试、真实世界示例;评审自己的意见也要遵循同一标准:链接 spec 章节、链接代码、展示更简单的替代方案。
  4. 规范是锚点(Spec is the anchor)——SDK 实现的是协议规范。一个特性离规范越远,所需的论证力度就越大。
  5. 在最高层级"杀掉"(Kill at the highest level)——如果设计本身就是错的,就不要去评审实现细节。先抛最高层级的问题;具体 bug 只是支撑细节。
  6. 默认拆分(Decompose by default)——一个 PR 做多件事就应拆成多个 PR,除非有强烈理由打包。

从源码结构可以印证"极简主义"的落地方式:协议层被刻意收敛在 core-internal 包(如 packages/core-internal/src/protocol.ts、transport.ts),而中间件、builder 等更"应用层"的能力以独立包形式存在于 packages/middleware(express、fastify、hono、node 各自独立成包),形成"核心薄、外围多"的架构。

审查排序:先设计后细节

文档规定了评审的四个层级,评审者必须按此顺序推进,不得跳级:

  1. 设计论证——整体方法是否合理?复杂度是否值得?
  2. 结构性问题——架构是否正确?抽象是否有正当理由?
  3. 正确性——bug、回归、缺失功能。
  4. 风格与命名——小瑕疵、约定、文档。

这与第 5 条原则"Kill at the highest level"直接呼应:只有在设计层面通过后,才值得逐行检查正确性与命名。

检查清单:四大维度的逐项核对

Checklist 章节是评审者最直接的实操工具,按四个维度组织:

协议与规范(Protocol & spec)

  • 类型必须与官方规范 schema.ts 完全一致(optional vs required 字段)。规范原文可参考 MCP 官方文档与 LLM-friendly 全文(详见下文 Reference 一节)。
  • 使用正确的 ProtocolErrorCode 枚举值;HTTP 状态码须与规范匹配(例如 404 与 410 的区别)。
  • 同时适配 stdio 与 Streamable HTTP 两种传输,不得做出传输专属假设。
  • 跨 SDK 一致性:同一特性要对照 python-sdk 的实现。

关于错误码,packages/core-internal/src/types/enums.ts 给出了枚举的完整定义:标准 JSON-RPC 错误码(ParseError = -32700、InvalidRequest = -32600、MethodNotFound = -32601、InvalidParams = -32602、InternalError = -32603)以及 MCP 专属扩展(ResourceNotFound = -32002、MissingRequiredClientCapability = -32021、UnsupportedProtocolVersion = -32022、UrlElicitationRequired = -32042)。值得注意的是 ResourceNotFound 的注释明确说明:SDK 自身从不主动发出 -32002(2026-07-28 规范要求 resources/read 未命中时统一回答 -32602),保留该枚举值仅为识别早期版本对端,应当抛出 ResourceNotFoundError 而非直接使用该码——评审时若看到新代码 emit -32002 就应标记。

错误码到 HTTP 状态的映射在 packages/core-internal/src/shared/inboundClassification.ts 中可见(如 MethodNotFound → 404,ParseError/InvalidRequest/UnsupportedProtocolVersion → 400),评审可据此核对 PR 中新增的映射是否与既有矩阵一致。

ProtocolError 基类定义于 packages/core-internal/src/types/errors.ts,其构造器接收 code、message、可选 data,并通过 Symbol.hasInstance 的品牌匹配(brandedHasInstance)保证跨打包副本的 instanceof 判断有效。

API 表面(API surface)

  • 每个新导出都必须是有意为之(详见 CLAUDE.md 中 Public API Exports 一节);用户自己能写的小助手函数应放进 cookbook 而非 SDK。
  • 新抽象在 PR 内至少有一个具体调用点(callsite)。
  • 一件事只有一种做法——改进现有 API 优于新增一个平行的 API。

正确性(Correctness)

  • 异步:竞态条件、取消时的清理、未处理的 rejection、缺失的 await。
  • 错误传播:正确捕获/重抛、错误路径上的资源清理。
  • 类型安全:无无正当理由的 any、无不安全的 as 断言。
  • 向后兼容:公开接口变更、默认值变更、被移除的导出——必须标记并给出理由。

测试与文档(Tests & docs)

Reference:核对规范的正确姿势

文档明确要求:验证规范合规性时,直接查阅规范原文,不要凭记忆。给出的参考途径包括:

  • MCP 文档服务器:https://modelcontextprotocol.io/mcp
  • 规范全文(单文件、LLM 友好):https://modelcontextprotocol.io/llms-full.txt——建议抓取到临时文件后用 grep 定位相关章节
  • Schema 真源:官方仓库的 schema.ts

在仓库内部,规范的"镜像证据"同样可用:packages/core-internal/src/wire 下按协议版本(rev2025-11-25、rev2026-07-28)分目录存放构建出的 wire schema,而 packages/core-internal/test/corpus/schema-twins 存放从官方抓取的 schema twin 用于一致性校验。

Recurring Catches:8 类反复出现的高频问题

这是文档中"自动维护、随评审轮次增长"的部分,每一条都附有历史 issue/PR 编号。评审新 PR 时应当主动对照这些既往教训:

1. HTTP 传输(HTTP Transport)

校验 Mcp-Session-Id 时:缺失头返回 400,未知/过期 session 返回 404——绝不把 !sessionId || !transports[sessionId] 合并成一个 4xx 状态,因为客户端需要区分"修正你的请求"与"开启新会话"。凡是对 session-id 存在性/查找仅用一个 4xx 分支的 diff 都应标记(#1707、#1770)。

仓库实现印证了这一点:服务端在 packages/server/src/server/streamableHttp.ts 中对缺失的 Mcp-Session-Id 头返回 400 与 JSON-RPC 错误 -32000("Bad Request: Mcp-Session-Id header is required");客户端侧 packages/client/src/client/streamableHttp.ts 的文档注释也说明了对该头的处理语义,测试 packages/client/test/client/probeClassifier.test.ts 覆盖了"Mcp-Session-Id header is required"这一错误分支。

2. 错误处理(Error Handling)

宽泛的 catch 块不得把服务端内部失败(如流建立、任务存储未命中、轮询错误)映射成客户端过错类 JSON-RPC 错误码(-32700 ParseError、-32602 InvalidParams)——这些应映射为 -32603 InternalError,否则客户端会徒劳地重试或重排请求。凡是不区分抛出原因、硬编码 ParseError/InvalidParams 的 catch-all 都应标记(#1752、#1769)。

3. Schema 合规(Schema Compliance)

编辑 packages/core-internal/src/wire/rev2025-11-25/buildSchemas.ts 或 packages/core-internal/src/wire/rev2026-07-28/buildSchemas.ts 中的 Zod 协议 schema 时,须核对未知键处理与官方 spec schema.ts 一致:若 spec 类型没有 additionalProperties: false,SDK schema 就必须使用 z.looseObject() 或 .catchall(z.unknown()) 而非隐式严格——过度严格的 Zod(包括对 type 字段使用 z.literal('object'))会拒绝其他 SDK 发出的合法 payload。同时确认 spec.types.*.test.ts 的对比测试仍能双向通过(#1768、#1849、#1169)。

源码中可看到该约定被严格执行:rev2025-11-25/buildSchemas.ts 中大量使用 z.looseObject({ ... })(如 RequestMetaSchema、ResultSchema、ClientTasksCapabilitySchema、TaskCreationParamsSchema 等),并有 .catchall(z.unknown()) 兜底未知键;对应的对比测试位于 packages/core-internal/test/spec.types.2025-11-25.test.ts 与 packages/core-internal/test/spec.types.2026-07-28.test.ts(后者显式断言"只允许白名单内存在于 2026-07-28 schema 的类型"并跑全面兼容性测试)。

4. 异步 / 生命周期(Async / Lifecycle)

  • 在 close() / 关闭路径中,把用户提供的或链式回调(onclose?.()、取消函数)包进 try/finally,防止一次抛出跳过剩余清理(abort()、_onclose()、map 清空),否则传输会处于半开状态(#1735、#1763)。
  • 延迟回调(setTimeout、.finally()、重连闭包)在改动 this._* 或发起 I/O 前必须检查 closed/aborted 状态——close 前调度的回调可能在 close/重连之后触发,破坏新连接的状态(例如误删新请求的 AbortController)(#1735、#1763)。

5. 完整性(Completeness)

当 PR 替换某个模式(错误类、认证流步骤、catch 形态)时,要在包内 grep 是否还有旧形式的幸存实例——部分迁移会让兄弟代码路径保留 PR 声称要修复的那个 bug。每个遗留点都应标记(#1657、#1761、#1595)。

6. 文档与 Changesets(Documentation & Changesets)

阅读新增的 .changeset/*.md 文本与内联注释时,要与同一 diff 中的实现对照——文档承诺了代码实际不再提供的行为会误导使用者并与既定意图矛盾。凡是 diff 无法支撑的声明都应标记(#1718、#1838)。该仓库确实维护 .changeset 目录(见 .changeset/README.md 与 .changeset/config.json),并有 dpop-client-tokens、request-body-size-limit 等实际变更记录文件。

7. CI 与 GitHub Actions(CI & GitHub Actions)

不要在未核实第三方 GitHub Action 或发布工具链的文档/源码前,断言它会失败或需要额外权限/token——pnpm publish 会委托给系统 npm CLI(因此 npm OIDC 可用),而 changesets/action 在 publish 模式下没有需要 pull-requests: write 的 PR 评论步骤。对 .github/workflows/ 下的 diff,先在 action 的 README/源码中确认其声明的行为再标记(#1838、#1836)。

8. 从源码结构看:错误矩阵测试

除了上述七类,仓库的测试布局还隐含着第八类关注点:HTTP 状态码与错误类型的映射关系有专门的矩阵测试守护,例如 packages/core-internal/test/shared/errorHttpStatusMatrix.test.ts 与 packages/core-internal/test/shared/inboundLadderCellSheet.test.ts。评审任何改动错误码→HTTP 状态映射的 PR 时,都应确认这些矩阵测试同步更新。

一套可落地的评审工作流

综合文档内容,可以将评审流程收敛为以下步骤,供实际评审时直接套用:

  1. 先读设计:这个改动该不该存在?(对照 6 条原则,默认答案是"否")
  2. 再定层级:按"设计论证 → 结构 → 正确性 → 风格"的顺序推进,设计不对就到此为止。
  3. 逐条过 Checklist:协议/spec 对照官方 schema.ts;API 表面核对 CLAUDE.md 的导出约定;正确性重点查异步与错误路径;文档与 examples 必须同步。
  4. 扫描 Recurring Catches:确认 PR 是否触碰 session-id 状态码、错误码映射、Zod 宽松度、close 清理、延迟回调竞态、部分迁移、changeset 与实现不符、CI 断言无依据这 8 类既往高频问题。
  5. 用源码和测试说话:在评论中链接具体实现(如 packages/server/src/server/streamableHttp.ts、packages/core-internal/src/types/enums.ts)与测试文件(如 packages/core-internal/test/spec.types.2026-07-28.test.ts),让每条意见可验证、可追溯。

这套约定把"评审靠直觉"转化为"评审靠清单 + 证据 + 历史教训",既保证了 SDK 的协议正确性与 API 极简,也让新评审者能快速达到与资深维护者一致的判断标准。

登录后查看全文
typescript-sdk