该技能是一份 TypeScript 编码规范清单,定位为在阅读或编辑任意 .ts / .tsx 文件时使用的技能。资料中说明,技能内以粗体或反引号标注的名称、或以 /<name> 形式运行的条目,指向同级目录旁的 ../<name>/SKILL.md 文件;不带前缀的原则名指向 ../principle-<name>/SKILL.md,需读取并遵循。多数 pstack 技能仅供用户使用,技能工具无法加载它们。要求先应用 type-system-discipline 原则技能。
主要规则:可辨识联合类型,用 kind 字面量判别符建模变体,使非法状态无法表达,不使用可选字段堆砌;品牌类型,用 & { readonly __brand: "X" } 标记原始类型避免混用,在边界处校验一次,品牌须来自验证型类型守卫(input is AgentId),不得来自 as;构造式建模,通过结构设计使非法值无法构造,如用 [T, ...T[]] 表示非空、[T, T][] 表示偶数长度、以起点加时长表示区间,而非依赖运行时守卫或细化类型;最简全量类型,只要对 T[] 的所有操作保持全量就保留 T[],仅当宽松类型迫使使用 !、类型转换或“不应发生”抛错时才收紧为 NonEmpty<T>;外部数据用 unknown 而非 any;在属性逐一编写类型守卫前,优先使用仓库的运行时 schema 库并从 schema 推导类型(如 z.infer);禁止 as 类型转换,每次 as 都可能是运行时崩溃隐患,仅在验证后转换;类型收窄按判别符 switch > in 运算符 > typeof/instanceof > 用户定义类型守卫 > as 的层级选择;类型守卫必须真正验证其声明,命名用 isX 或 hasX;穷尽性检查,在 default 分支写内联的 const _exhaustive: never = x,使新增变体时编译报错;用 satisfies 而非 as,在不拓宽字面量类型的前提下校验值;边界校验,在数据进入处解析为具名领域类型,Record<string, unknown> 止于该解析点,内部信任类型;schema 推导类型,声明新 interface 前先用 Pick/Omit/Parameters/ReturnType/Awaited/typeof;对象参数,传对象而非位置参数以使参数顺序自解释,热路径(逐帧渲染、分词器、解析器)可跳过;真实测试,能不 mock 就跑的就不 mock,优先使用框架真实测试原语并检查泄漏/可释放性,UI 在运行构建中验证,仅对本地无法运行的才 mock;结构化遥测,优先使用带足够上下文、可从 id 调试的结构化日志诊断,发布代码中不使用 console.log。示例见 references/patterns.md。
适用场景:阅读或修改 TypeScript/TSX 代码时的类型设计与校验规范。限制:资料未说明支持的平台、版本、安装方式、收费情况或具体集成步骤,这些暂未提供。