core-typescript

TypeScript 核心约定 — 基础工程技能

适用于所有项目的语言级 TypeScript 规则，无论是否使用框架。react、angular 和 vue 会在此基础上扩展；architecture-and-design 会与之组合。所有规则都假设编译器以 strict 模式运行（compiler-config）。示例均为纯 TypeScript，不使用框架。

构建基础。 无 — 这是一项基础技能。

此 SKILL.md 内容完整自足：下方的 规则集 是完整且可执行的规则列表。每个 references/<topic>.md 都包含该组规则的原理和 ❌ / ✅ 代码示例，另有 references/worked-example.md 提供完整的审查过程；运行环境允许时，可打开这些文件了解详情。

---

如何使用此技能

选择与任务相符的模式，并按顺序执行步骤。

模式	步骤
生成 — 编写新的 TypeScript	1. 假设已启用 strict（compiler-config）。2. 编写代码，并在编写过程中应用规则集。3. 为每个导出的函数标注返回类型（functions）。4. 按清单逐项检查规则集。交付前修复每项不合规之处。
审查 — 检查差异	1. 根据差异检查规则集。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……）。

所有模式均适用的规则

• 强制执行规则时，注明规则集主题。
• 尽量使用简单且精确的类型。较宽泛的类型会掩盖错误；过于巧妙的类型会拖慢后续读者的理解。
• 如果某个类型需要注释来解释，就说明它不够理想。为它命名，或将其简化。

---

规则集

compiler-config → references/compiler-config.md

• 启用 strict，以及 noUncheckedIndexedAccess、exactOptionalPropertyTypes、noImplicitOverride、noFallthroughCasesInSwitch、noImplicitReturns、 noUnusedLocals、noUnusedParameters、verbatimModuleSyntax 和 erasableSyntaxOnly。
• 绝不为消除错误而放宽标志 — 应修复代码。

unsafe-types → references/unsafe-types.md

• 不使用 any：未知输入应标注为 unknown，并进行收窄。不得使用 as any 或 as unknown as T。
• 不使用 as 强制转换类型，也不使用 !，除非已在上一行证明该值存在 — 每次此类用法都必须有保护条件或注释证明其安全。
• 不得将 Function、Object 或 {} 用作类型（表示非基本类型时可以使用 object）。
• 不使用 @ts-ignore — 使用带注释的 @ts-expect-error。

inference → references/inference.md

• 不添加仅重复编译器已能精确推断结果的类型标注（导出的 API 边界除外 — 参见 functions）。
• 使用 satisfies 检查字面量是否符合某个形状，同时不拓宽该值的类型。

data-modeling → references/data-modeling.md

• 字符串集合应使用字符串字面量联合类型或冻结的 as const 对象 — 绝不使用 TypeScript enum 或 const enum。
• 不变数据应标记为 readonly（列表使用 readonly T[]）。
• 互斥状态应使用带有共同判别字段的判别联合类型。设计原理：architecture-and-design、patterns。
• 领域 ID 应使用独立的品牌类型，并在边界处通过唯一许可的类型断言创建。设计原理：architecture-and-design、type-safety。

narrowing → references/narrowing.md

• 使用类型守卫（v is T）或断言函数（asserts v is T）收窄 unknown 和联合类型，而不是使用类型转换。
• 对联合类型执行的每个 switch 都以 assertNever 默认分支结束。

generics → references/generics.md

• 仅当两种类型需要同步变化时（输入类型和返回类型）才添加类型参数；不要添加只使用一次的类型参数。
• 使用 extends 约束类型参数；常见的类型参数应设置默认值；调用方传入字面量时使用 const 类型参数。

utility-types → references/utility-types.md

• 使用 Pick / Omit / Partial / Required / Record / ReturnType / Parameters / Awaited / NonNullable / keyof / typeof / 索引访问 / 模板字面量类型派生相关类型，而不是手动复制。

nullability → references/nullability.md

• 使用 undefined 表示唯一的空值；仅当外部契约会发送 null 时才使用 null。
• 读取 array[i] 和 record[key] 时，将其视为可能是 undefined（需要启用 noUncheckedIndexedAccess）。
• 使用 ?. 和 ?? 提供默认值；只有当 0、'' 和 false 都不是有效值时才使用 ||。

functions → references/functions.md

• 每个导出的函数都标注返回类型；本地的非导出函数则推断返回类型。
• 参数超过 3 个时使用一个选项对象；不要使用顺序依赖的长参数列表，尤其避免布尔参数。
• 函数体相同时，优先使用联合类型参数，而不是重载集合。

async → references/async.md

• 不要留下未处理的 Promise——每个 Promise 都必须 await，或显式标记为 void。
• 使用 Promise.all 并行执行互不依赖的异步工作；只有当某一步需要前一步的结果时才串行 await。
• 当目标环境支持显式资源管理时，使用 using / await using 释放一次性资源（计时器、订阅、锁或句柄）。

errors → references/errors.md

• catch 绑定的类型为 unknown（来自 useUnknownInCatchVariables），读取任何字段之前都必须先收窄类型。
• 抛出的值始终为 Error——自定义类型应继承 Error 并设置 name；绝不要抛出字符串或普通对象。

modules → references/modules.md

• 类型引用使用 import type / export type，或在名称上使用内联 type。
• 优先使用命名导出，而非默认导出；两个模块之间不得循环导入；不要创建全项目范围的 barrel（功能级 index.ts 可以）。

language-hygiene → references/language-hygiene.md

• 仅使用 === / !==——唯一例外是 x == null，它会同时检查 null 和 undefined。
• 使用 Number.isNaN / Number.isFinite，而不是会进行类型强制转换的全局函数。
• 默认使用 const，仅在需要重新赋值时使用 let，绝不使用 var；不要重新赋值函数参数。
• 真正的位标志应使用由 2 的幂构成的 const 对象及其派生类型，而不是字符串字面量联合类型。

lint → references/lint.md

• typescript-eslint 使用 strict-type-checked（或至少使用 recommended-type-checked），并启用 no-floating-promises、no-explicit-any、 consistent-type-imports 和 switch-exhaustiveness-check。
• 使用 Prettier 格式化代码，避免将代码风格作为评审议题。

---

限制

此技能仅涉及 TypeScript 语言层面，不涵盖：

• 架构、分层、状态管理和组件设计——请参阅 architecture-and-design。
• 框架 API 和模式——请参阅 react、angular 和 vue。
• 构建工具、打包器，以及超出 compiler-config 中 tsconfig 基线范围的 monorepo 配置。
• 运行时模式库（Zod、Valibot）——在相关处会提及，但不会在此讲解。

此技能用于确定语法，不会取代阅读代码和理解领域知识。

---

参考资料

此技能可与以下内容配合使用：

• architecture-and-design — 设计层。对于共同涉及的主题（判别联合类型、品牌化 ID），它决定设计，而此技能决定语法。
• react / angular / vue — 通过各自框架的特定内容扩展此技能。若在语言要点上存在冲突，以此技能为准。