用途
该技能面向 TypeScript 代码的阅读与编辑场景,在接触任何 .ts 或 .tsx 文件时应用,目标是借助类型系统降低运行时错误、表达更精确的领域模型。
使用前提
每个会话先读取一次宿主适配器。它把上游 Cursor 特有的工具、模型、路径与权限说明映射到当前宿主,并设定权限边界。随后先应用 type-system-discipline 原则技能。
主要能力与规则
- 可辨识联合:以 kind 字面量判别变体,使不可能状态无法被表示,不采用可选字段堆叠的方式。
- 品牌类型:用 & { readonly __brand: "X" } 标记原始类型以防混用;在边界处校验一次;品牌应来自经验证的类型守卫(如参数为 AgentId),绝不来自 as。
- 构造性建模:让非法值无法被构造,例如用 [T, ...T[]] 表示非空、[T, T][] 表示偶数长度、以起点加时长表示区间;这属于类型建模而非运行时守卫。
- 最简全类型:只要对 T[] 的每个操作都保持全函数性,就保留 T[];仅在宽松类型迫使使用 !、强制转换或“不应发生”的抛错时,才收紧为 NonEmpty<T>。
- 外部数据使用 unknown 而非 any。
- 先 schema 后守卫:在手工逐属性编写类型守卫之前,使用仓库既有的运行时 schema 库,并由 schema 推断类型,例如 z.infer。
- 禁止 as 强制转换:每次 as 都是潜在的运行时崩溃,仅在验证之后才能转换。
- 收窄层次:可辨识联合 switch > in 运算符 > typeof/instanceof > 用户自定义类型守卫 > as。
- 类型守卫必须真正验证其断言;虚假的守卫比 as 更糟,因为缺陷藏在宣称安全的名称之下;命名采用 isX 或 hasX。
- 穷尽性:在 default 分支内联 const _exhaustive: never = x;,使新增变体时编译器报错。
- 用 satisfies 替代 as:在不拓宽字面量类型的前提下校验值。
- 边界校验:在数据进入处解析为命名领域类型;Record<string, unknown>(无论何种写法)止于该解析处,内部信任类型。
- schema 派生类型:在声明新接口之前,优先考虑 Pick/Omit/Parameters/ReturnType/Awaited/typeof。
- 对象参数:传对象而非位置参数,使参数顺序自解释;在热路径(逐帧渲染、分词器、解析器)上可跳过。
- 真实测试:不要 mock 可以实际运行的东西;优先使用框架的真实测试原语,配合泄漏/可释放性检查,并在运行中的构建里验证 UI;仅对本地无法运行的部分使用 mock。
- 结构化遥测:优先使用带足够上下文、可凭 id 调试的结构化日志;交付代码中不使用 console.log。
使用方式
在编辑 .ts/.tsx 文件时按上述规则约束代码;规则示例见 references/patterns.md。
适用场景
TypeScript 项目的日常编码、类型建模、边界数据处理与测试编写。
限制
该技能以规则与原则形式呈现,具体宿主适配与权限设定依赖宿主适配器;未提供收费、平台支持范围或具体工具链要求的说明。