TypeScript 类型系统专家

问题

在一个 TypeScript 项目里，类型层面的错误往往不在编译时暴露，而是在运行时以 undefined、错位字段或意料之外联合分支的形式出现。更常见的是：

• 手写类型在迭代中漂移：接口改了，调用方仍然按旧形状写；
• 运行时断言不可靠：到处写 as，却没人真正验证数据形状；
• 前后端契约脆弱：后端返回结构变化时，前端经常要到联调阶段才发现。

这个技能面向的正是这类“类型看似安全、运行时仍会翻车”的工程问题，而不是替你写业务逻辑。

技能如何工作

它以 TypeScript 专家的角色介入，核心能力包括：

• 设计高级类型与工具类型，例如判别联合、泛型边界、品牌类型（branded types）来区分同名但语义不同的值；
• 实现自定义类型守卫，让类型收窄在运行时真正生效，而不是停留在注释里；
• 配置 tRPC 打通前后端，使前端直接复用后端类型，或共享 zod schema 做运行时校验。

工作流分为五个步骤：

1. 确认目标：TS 版本、是否开启严格模式、是否需要端到端类型安全；
2. 类型设计：规划领域模型、判别联合与泛型边界；
3. 实现：产出类型定义、类型守卫与 tRPC router；
4. 自检：核对 any 泄漏、类型收窄路径、是否符合 strict；
5. 输出工件：返回结构化的 TsModuleSpec。

TsModuleSpec 的字段固定为：

{ module, strict, types: [string], guards: [string], notes: string }

输出分为两部分：完整的结构化工件，以及一段自然语言摘要，说明质量自检结果和最值得修正的 2～3 个点。该工件可以交给 code-reviewer 做后续评审，形成闭环。

适用边界与注意点

• 纯 JavaScript 项目应改用 javascript-pro，这个技能不会替你假装有类型；
• 不涉及 TypeScript 编译器源码修改，只处理应用层类型设计；
• 输出质量取决于输入约束的明确程度，建议在第一步就讲清 TS 版本与严格模式要求；
• 自检阶段会重点排查 any 泄漏与判别联合的完整性，避免“看起来有类型、实际没收窄”的假安全。