适用场景

用户需要 TypeScript 专业知识——涵盖基础类型标注到高级泛型。Agent 可处理类型收窄（narrowing）、类型推断、可辨识联合（discriminated unions）以及严格模式（strict mode）下的常见模式。

速查表

停止使用 any

• unknown 强制你在使用前进行类型收窄；而 any 会静默破坏类型安全性
• 对于 API 响应：务必为其定义类型，或使用 unknown，切勿使用 any
• 当你不确定类型时，该用的是 unknown，而不是 any

类型收窄失败的常见情况

• filter(Boolean) 不会触发类型收窄 — 应改用 .filter((x): x is T => Boolean(x))
• Object.keys(obj) 返回 string[]，而非 keyof typeof obj — 这是设计使然，因为对象可能包含额外属性
• Array.isArray() 将类型收窄为 any[] — 若需精确元素类型，可能需手动类型断言
• in 操作符可实现收窄，但仅当目标属性**恰好只存在于联合类型的某一个分支中**时才有效

字面量类型陷阱

• let x = "hello" 的类型是 string — 如需字面量类型，请使用 const 声明或后缀 as const
• 对象属性默认会拓宽（widen）：{ status: "ok" } 中的 status 类型为 string — 请使用 as const 或显式类型注解
• 函数返回类型也会被拓宽 — 若需字面量返回类型，请显式标注返回类型

类型推断的局限性

• 部分数组方法中的回调函数会丢失类型推断 — 当 TypeScript 推断错误时，请显式标注参数类型
• 泛型函数需依赖实际调用才能推断类型 — 单独写 fn() 无法推断，应传入具体值或显式标注类型
• 嵌套泛型常导致推断失败 — 建议拆分为多个步骤，并配合显式类型标注

可辨识联合（Discriminated Unions）

• 为每个变体（variant）添加一个字面量类型的 type 或 kind 字段 — 以支持穷尽性 switch 检查
• 实现穷尽性检查：default: const _never: never = x — 若遗漏任一 case，将触发编译错误
• 避免将可辨识联合与可选属性混用 — 否则会导致类型收窄失效

satisfies 与类型注解的区别

• const x: Type = val 会将 val 宽展（widen）为 Type — 丢失字面量信息
• const x = val satisfies Type 在保留字面量类型的同时验证兼容性 — 配置对象等场景下推荐使用

严格空值处理

• 可选链操作符 ?. 返回 undefined，而非 null — 这在对接期望 null 的 API 时尤为关键
• ?? 仅捕获 null 和 undefined；而 || 会捕获所有 falsy 值（包括 0 和 ""）
• 非空断言操作符 ! 应作为最后手段 — 优先考虑类型收窄或提前返回

模块边界管理

• 仅用于类型导入时，请使用 import type — 该语法在运行时被完全移除，可规避打包器相关问题
• 重新导出类型时，请使用 export type { X } — 防止意外引入运行时依赖
• 对 .d.ts 文件做模块增强时，请使用 declare module 并指定**精确的模块路径**