一、用途
trpc-compat 用于在修改 tRPC 过程(procedure)的输入、输出、错误码、默认值或排序等契约前,判断该变更对已发布构建是否安全。CI 只能看到主干代码,无法覆盖仍在用户设备上运行的旧版本;该技能的核心目标是检查 CI 看不到的已发布调用方,避免旧客户端因响应结构变化而崩溃。
二、主要能力
-
检索已发布调用方:在发布标签而非 main 上搜索过程路径,覆盖桌面端(以 MINIMUM_DESKTOP_VERSION 为下限的所有 desktop-v* 标签)、CLI(所有 cli-v* 标签)、移动端(无标签,若 main 或提交历史中出现即视为活跃)以及通过字符串路径调用过程的 SDK。host-service 过程的调用方涵盖桌面端、CLI 和移动端,且宿主版本可能新于或旧于客户端。
-
核对用量数据:通过 PostHog 事件 api_procedure_called(API 按 1% 采样)查询近 30 天各产品与版本的调用量,作为辅助判断依据;并说明零行结果是弱证据,Web 端及缺少 x-superset-client 头的旧构建不会被记录。
-
选择兼容模式:针对输出结构变更、新增输入、接受新输入形状、重命名过程、删除输入、删除输出字段、删除或重命名数据库列、收紧输入校验、修改错误码/默认值/排序、客户端调用新过程等场景,给出应采用的模式与示例,例如新增过程并保留旧过程形状、新字段设为可选并在服务端提供默认值、旧名称保留为 @deprecated 别名、客户端在 API 上线后再合并等。
-
移除已弃用过程或字段的判定:需同时满足“步骤一未在任何活跃桌面标签及移动端、CLI、SDK 中发现调用”和“步骤二显示近 30 天无活跃版本调用”;若活跃桌面构建仍在调用,只能通过提升 MINIMUM_DESKTOP_VERSION 处理,且属于产品决策,需先询问而非在清理 PR 中直接执行,并将证据写入 PR 描述。
-
已发布客户端被破坏时的处置:先用 Sentry 确认问题始于 API 部署时间;若导致问题的 PR 不含已应用的生产迁移则回滚该 PR;若含已应用迁移则编写前向修复,恢复旧契约并把新形状迁移到新过程,不要回滚迁移;同时提示受影响用户刷新页面,部分场景需重启应用或终端守护进程。
三、使用方式
以技能文本中的命令与流程为操作指引:先在新克隆中执行 git fetch --tags,再用 git grep 在指定标签范围内搜索过程路径;随后通过 PostHog SQL 或 PostHog MCP 执行查询;最后按对照表选择兼容模式,并在 PR 中附上步骤一和步骤二的证据。
四、适用场景
适用于维护存在多端发布客户端(桌面端、移动端、CLI、SDK)的 tRPC 服务端,在修改过程契约、移除弃用接口、排查发布后崩溃时使用。
五、限制
trpc-compat 依赖标签命名、最低版本常量与 PostHog 采样数据,采样稀疏时数据可能不足;Web 端调用与旧头信息调用不被记录;提升最低支持版本属于产品决策,不能仅凭技能自动执行。