ub-ts

UB TS

概述

使用此技能，在应用和库代码库中贯彻最新稳定版 TypeScript 的现代默认配置和模式。新代码只生成现代写法；仅在有明确范围的迁移例外中保留旧写法。

根据检测到的项目 TypeScript 配置和运行时实际情况进行实现，但设计上应侧重于向前兼容的迁移，而非兼容层或旧版回退方案。

捆绑资源

此技能附带可复用的 tsconfig 起始脚手架，以及位于 assets/ 下的可选 ESLint 扁平配置起始模板，还附带位于 scripts/ 下的确定性辅助脚本。

当代码库希望采用此套风格作为起点，且尚无自己的 TypeScript 配置时，请使用这些资源。

按需加载参考资料

• 阅读 references/ts-modern-patterns.md，了解项目类型选择、tsconfig 基线和现代类型模式。
• 阅读 references/ts-legacy-to-modern-migration.md，了解旧版到新版的迁移、禁止使用的模式和例外处理。
• 当需要了解本地 TypeScript 配置发现、起始脚手架或可选 ESLint 支持时，阅读 references/ts-config-resolution.md。
• 仅当目标代码库需要为此技能的起始配置添加可选的 Task 自动化层时，才阅读 references/task-bundle.md。
• 当目标代码库需要确定性起始配置，而非临时创建配置时，使用 scripts/scaffold_ts_baseline.py、assets/tsconfig-template/ 和 assets/eslint-template/。

技能协同

• 当 TypeScript 问题出现在框架项目中时，将此技能与 ub-vuejs 或 ub-nuxt 一起加载。
• 框架运行时、路由和应用结构的决策，应交由负责这些内容的关联技能处理。

核心工作流

1. 根据 package.json、锁文件、运行时目标、构建工具和现有的 tsconfig*.json 文件，判断项目类型。
2. 选择符合运行时实际情况的模块策略：
   • Node 运行时：module 设为 node20 或 nodenext
   • 打包器运行时：moduleResolution 设为 bundler，module 设为 esnext
   • 库发布：兼容性检查优先采用符合 Node 实际行为的模块解析方式
   • 类型剥离运行时：限制为可擦除的 TypeScript 子集
3. 对于非平凡或依赖特定版本的建议，对照官方指南、代码库实际情况和观察到的代码现状。
4. 当权威来源、代码库实际情况或当前代码现状在非平凡建议上存在实质性分歧时，标记 OFFICIAL_CONFLICT。
5. 对于经过针对性调查后仍无法从官方来源确认的非平凡声明，标记 UNVERIFIED。
6. 按照 references/ts-modern-patterns.md 应用严格的安全基线和模块规范默认值。
7. 优先采用现代类型模式（satisfies、const 类型参数、NoInfer、可辨识联合、边界显式类型标注）。
8. 拒绝为新代码生成旧版写法；修改现有代码时，按照 references/ts-legacy-to-modern-migration.md 中的映射进行迁移。
9. 使用目标项目中可用的类型检查、代码检查、测试和构建命令进行验证。
10. 如果代码库希望采用此基线但缺少 TypeScript 配置，则生成捆绑的起始配置，并说明仍需进行哪些代码库本地的适配。

版本与研究政策

• 以最新稳定版 TypeScript 为目标。
• 从 package.json 和锁文件中检测项目实际使用的 TypeScript 版本。
• 使用网络搜索，根据官方 TypeScript 文档核实当前最佳实践、API 可用性和迁移指南。
• 在判断哪些方案能在当前项目中安全落地时，以仓库实际情况作为实现标准。
• 将官方 TypeScript 文档作为面向未来的设计和便于迁移的模式的首选指导基线。
• 如果官方指导与仓库实际情况在重要建议上存在实质性分歧，则标记为 OFFICIAL_CONFLICT，采用对仓库安全的方案，并说明迁移路径。
• 如果官方来源之间对重要建议也存在分歧，同样标记为 OFFICIAL_CONFLICT，不要默默消除分歧。
• 如果经过有针对性的研究后仍无法从官方来源确认某项重要主张，则将其标记为 UNVERIFIED，或避免将其作为定论性指导。
• 仅针对重要、与版本相关或存在争议的指导披露冲突与不确定性，不要用于琐碎修改。
• 除非用户明确要求，否则不要使用仅适用于 beta 版的语法。
• 如果项目安装的版本落后于最新稳定版，请说明版本差距并建议升级路径。
• 如有 AGENTS.md 或同等说明文件，请检查宿主仓库中的项目特定版本政策和工具配置；不要假设其中包含本目录的默认设置。
• 不要在生成的指导中硬编码版本号，让建议保持长效适用。

时效性审查

• 变化频率：高
• 审查建议：修改相关内容时进行审查；条件允许时按季度定期维护。
• 触发信号：TypeScript 发布新版本、编译器标志行为变化、模块解析指导更新，或影响 tsconfig 策略的运行时平台更新。
• 执行方式：仅供参考；时效性应影响审查优先级，但本身不应成为阻断条件。
• 稳定核心：忠实于运行时的模块策略、严格类型检查和显式边界建模，是即使编译器默认值发生变化也依然适用的持久指导。

实施规则

项目类型与模块

• 更改编译器选项前，先确定项目类型。
• 模块设置应忠实于运行时，不应由个人偏好决定。
• 将 moduleDetection 保持为 force，除非已知存在兼容性约束。

导入与导出规范

• 保持启用 verbatimModuleSyntax。
• 类型专用符号使用 import type 和 export type。
• 保持副作用导入明确且可解析。

类型系统模式

• 优先使用 satisfies，在验证结构的同时避免字面量类型扩大。
• 对能从字面量保留中受益的可复用 API，优先使用 const 类型参数。
• 需要限制类型推断时，使用内置的 NoInfer。
• 当行为取决于不同变体时，使用可辨识联合建模状态。
• 在信任边界使用 unknown，然后通过验证收窄类型。

编译器基线

• 保持 strict: true。
• 保持 noUncheckedIndexedAccess: true。
• 保持 exactOptionalPropertyTypes: true。
• 在工具链混合的仓库中启用 isolatedModules。
• 对声明文件占比较高的库项目启用 isolatedDeclarations。
• 存在副作用导入时，使用 noUncheckedSideEffectImports。

配置解析与脚手架

将实际项目配置视为事实来源：

1. 如果存在，请先检查 tsconfig*.json、eslint.config.*、package.json 和锁文件
2. 选择脚手架前，先匹配本地运行时、打包工具和包管理器的实际情况
3. 仅当仓库缺少有效配置，且需要采用本项目风格的基线时，才使用随附的 tsconfig 脚手架
4. 将 ESLint 起始配置视为对 TS 仓库的可选强默认支持，而非普适的 TypeScript 策略
5. 脚手架搭建过程中，不要擅自安装依赖或更改 CI

权衡处理

• 对重要的 TypeScript 决策，使用共享的 ub-quality 决策分析基线。
• 针对每个选项说明 TypeScript 特有的优缺点，尤其是正确性、兼容性、开发体验和迁移成本方面。
• 除非用户约束另有要求，否则默认选择最安全的现代方案。

避免遗留模式的防护措施

• 新代码中不要生成旧式实验性装饰器模式。
• 新代码中不要生成以 namespace 为核心的架构。
• 不要依赖隐式的仅类型导入擦除。
• 在可以通过类型收窄实现时，不要使用大量类型断言作为捷径（as any、链式断言）。
• 不要引入 ESM 与 CJS 之间的旧式模块歧义。

迁移感知例外策略：

• 仅在现有代码有明确的兼容性约束时，才允许暂时保留旧式模式。
• 明确记录保留的内容、保留原因，以及具体的后续现代化步骤。
• 严格限定每个例外的范围，避免引入对保留的旧式行为的新依赖。

输出要求

生成或审查代码时，请包含：

1. 环境说明：检测到的项目类型、运行时目标和工具链上下文。
2. 事实来源说明：检测到的项目版本／工具链实际情况，以及与最新稳定版指导原则之间的任何重大差距。
3. 版本说明：TypeScript 基线及任何有意的偏离。
4. 决策说明：选定的模块和编译器策略，以及一个备选方案。
5. 权衡说明：简要说明选定方案和被否决方案的优缺点。
6. 遗留模式说明：已移除的遗留模式，或有明确界限的例外及其理由。
7. 验证说明：已运行的检查及结果。
8. 冲突说明（如适用）：OFFICIAL_CONFLICT 或 UNVERIFIED，并简要说明及指出对实现的影响。

当使用此技能为其他仓库搭建 TypeScript 配置时，还需包含：

1. 创建或跳过了哪些文件
2. 选择了哪种项目类型，以及一个被否决的备选方案
3. 仍需调整哪些仓库本地设置或依赖
4. 接下来要运行的确切验证命令

完成检查清单

• 已强制采用最新稳定版 TypeScript 现代基线。
• 在更改配置或代码前，已检测项目类型。
• 模块策略与运行时行为一致。
• 已有意启用严格安全标志。
• 新代码避免使用遗留模式。
• 任何保留的遗留模式均已记录迁移路径。
• 在可用情况下，已执行类型检查和相关项目验证。
• 相关时，已明确披露任何重大的官方来源冲突或未经验证的非平凡指导。
• 任何搭建的基线均已报告为起始配置，而非悄然设定的仓库策略。