用途
Core TypeScript 是一套语言级的 TypeScript 约定,适用于每一个项目,无论是否使用框架。React、Angular、Vue 在其之上扩展,架构与设计与其组合使用。所有规则都假定编译器运行在 strict 模式(见 compiler-config)。示例均为纯 TypeScript,不涉及框架。
该技能是基础技能,不构建于其他技能之上。其 SKILL.md 是自足的:下方规则集即为完整、可执行的清单。每个 references/<topic>.md 保存该组的推理与 ❌ / ✅ 代码,references/worked-example.md 提供一次完整审查过程;在运行时允许时可打开它们以获取更深入的内容。
主要能力
规则集按主题组织,每个主题对应一个引用文件:
- compiler-config:strict 开启,外加 noUncheckedIndexedAccess、exactOptionalPropertyTypes、noImplicitOverride、noFallthroughCasesInSwitch、noImplicitReturns、noUnusedLocals、noUnusedParameters、verbatimModuleSyntax、erasableSyntaxOnly。绝不为了消除错误而放宽标志,而是修复代码。
- unsafe-types:禁止 any,未知输入应类型为 unknown 并收窄;禁止 as any、as unknown as T;禁止用 as 强制类型,禁止 !,除非上一行已证明值存在;禁止将 Function、Object 或 {} 用作类型(object 用于非原始类型可以);禁止 @ts-ignore,改用带注释的 @ts-expect-error。
- inference:不添加仅重复编译器已精确推断的注解(例外:导出的 API 边界);satisfies 用于在不拓宽值类型的前提下检查字面量是否符合某个形状。
- data-modeling:字符串集合使用字符串字面量联合或冻结的 as const 对象,绝不用 TypeScript enum 或 const enum;不变数据为 readonly(列表用 readonly T[]);互斥状态使用带共享判别字段的可辨识联合;领域 id 拥有自己的品牌类型,在边界处用一次受认可的转换铸造。
- narrowing:unknown 与联合用类型守卫(v is T)或断言函数(asserts v is T)收窄,而非转换;对联合的每个 switch 以 assertNever 默认分支结束。
- generics:仅当两个类型一起移动(一个输入与一个返回类型)时才添加类型参数,不使用单次使用的类型参数;类型参数用 extends 约束,常见的带默认值,调用方传入字面量时用 const 类型参数。
- utility-types:相关类型用 Pick / Omit / Partial / Required / Record / ReturnType / Parameters / Awaited / NonNullable / keyof / typeof / 索引访问 / 模板字面量类型派生,而非手工复制。
- nullability:undefined 是唯一的空值,null 仅用于发送 null 的外部契约;array[i] 与 record[key] 按可能为 undefined 读取(需要 noUncheckedIndexedAccess);用 ?. 与 ?? 提供默认值,仅当 0、''、false 不是有效值时才用 ||。
- functions:每个导出函数注解返回类型,本地非导出函数可推断;超过三个参数使用一个选项对象,避免一长串依赖顺序、尤其是布尔参数;当函数体相同时,用联合参数替代重载集。
- async:禁止浮动 promise,每个 promise 都被 await 或显式标记为 void;独立的异步工作用 Promise.all 运行,仅当某步骤需要前一步结果时才串行 await;可释放资源(定时器、订阅、锁或句柄)在目标支持显式资源管理时用 using / await using 释放。
- errors:catch 绑定为 unknown(来自 useUnknownInCatchVariables),读取任何字段前先收窄;抛出的值始终是 Error,自定义类型继承 Error 并设置 name,绝不用字符串或普通对象。
- modules:类型引用使用 import type / export type 或名称上的内联类型;优先命名导出而非默认导出;两个模块之间无循环导入;无项目级 barrel(功能级 index.ts 可以)。
- language-hygiene:仅用 === / !==,唯一例外是 x == null,它同时测试 null 与 undefined;用 Number.isNaN / Number.isFinite,而非会强制转换的全局函数;默认 const,仅在重新赋值时用 let,绝不用 var;函数参数不重新赋值;真正的位标志是二的幂的 const 对象加派生类型,而非字符串字面量联合。
- lint:typescript-eslint 以 strict-type-checked(或至少 recommended-type-checked)运行,开启 no-floating-promises、no-explicit-any、consistent-type-imports、switch-exhaustiveness-check;Prettier 负责格式化,因此风格不是审查主题。
使用方式
选择与任务匹配的模式,按顺序执行步骤。
生成——编写新的 TypeScript:1. 假定 strict 已开启(compiler-config)。2. 编写代码,边写边应用规则集。3. 注解每个导出函数的返回类型(functions)。4. 将规则集作为清单运行,交付前修复每个失败项。
审查——检查 diff:1. 对 diff 运行规则集。2. 每个失败项按下述输出格式写一条发现。3. 排序发现:must-fix 在前,然后 consider。4. 若无失败,用一行说明。不要编造发现。
配置——设置或审计 tsconfig.json 与 ESLint:1. 从 assets/tsconfig.base.json 与 assets/eslint.config.js 开始。2. 开启 compiler-config 中的每个标志与 lint 中的每条规则。3. 对暂时无法开启的标志,添加带原因的 // TODO。4. 不要为了消除错误而放宽标志或禁用规则,修复代码。
输出格式:每行一条发现:<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>. 其中 <severity> 为 must-fix(违反本技能规则或构建)或 consider(安全,但规则偏好另一种形式);<topic> 为规则集主题 slug(unsafe-types、narrowing、async 等)。
所有模式的规则:执行规则时指明规则集主题;优先选择保持精确的最简单类型,更宽的类型会隐藏 bug,过于聪明的类型会拖慢下一位读者;需要注释解释的类型是坏味道,给它命名或使其更简单。
适用场景
适用于任何 TypeScript 项目的语言级约定:编写新代码、审查 diff、配置或审计 tsconfig.json 与 ESLint。可作为基础技能,被 React、Angular、Vue 等框架技能扩展,并与架构与设计技能组合使用。
限制
本技能是语言级 TypeScript,不覆盖:架构、分层、状态管理与组件设计(见 architecture-and-design);框架 API 与模式(见 react、angular、vue);compiler-config 中 tsconfig 基线之外的构建工具、打包器与 monorepo 设置;运行时 schema 库(Zod、Valibot)——仅在相关处提及,不在此教授。本技能决定语法,不替代阅读代码与理解领域。
组合关系
与 architecture-and-design 组合:后者是设计层,在共享主题(可辨识联合、品牌 id)上由它决定设计,本技能决定语法。与 react / angular / vue 组合:它们用各自框架的具体内容扩展本技能;在语言点冲突时,本技能优先。