SuperAPI AI 工具集

ub-ts

编程与开发

查看项目

更新于 10-28 17:10

技能介绍

用途

ub-ts 用于在应用和库代码库中推行最新稳定版 TypeScript 的现代默认配置与模式。它面向 Node、打包工具(bundler)、库、Vue、Nuxt 等 TypeScript 项目,处理类型系统写法与编译器配置。目标是:新代码只生成现代写法,遗留写法只作为有边界的迁移例外保留,设计上偏向向前兼容的迁移,而不是兼容层或旧式回退。

主要能力

  • 先识别项目原型(通过 package.json、lockfile、运行时目标、构建工具、现有 tsconfig*.json),再决定编译器选项。
  • 按运行时真实情况选择模块策略:Node 运行时用 module 为 node20 或 nodenext;打包工具运行时用 moduleResolution 为 bundler、module 为 esnext;库发布优先采用贴近 Node 的解析方式做兼容性检查;类型擦除运行时则强制可擦除的 TypeScript 子集。
  • 应用严格安全基线与模块卫生默认值:strict: true、noUncheckedIndexedAccess: true、exactOptionalPropertyTypes: true;在混合工具链仓库启用 isolatedModules;在声明密集型库工作流启用 isolatedDeclarations;存在副作用导入时使用 noUncheckedSideEffectImports。
  • 优先使用现代类型模式:satisfies、const 类型参数、内置 NoInfer、可辨识联合、显式边界类型;在信任边界使用 unknown 再经校验收窄。
  • 导入导出卫生:保持 verbatimModuleSyntax 启用,类型专用符号用 import type / export type,副作用导入显式且可解析。
  • 对既有代码按迁移映射改造,禁止为新代码生成遗留实验性装饰器模式、以命名空间为中心的架构、隐式类型专用导入消除、大量断言捷径(as any、链式断言)以及 ESM/CJS 模块歧义。
  • 迁移例外策略:仅因现有代码的明确兼容性约束而临时保留遗留写法,并记录保留了什么、为何保留、后续现代化步骤;例外范围要窄,不得新增对遗留行为的依赖。
  • 版本与调研:以最新稳定版 TypeScript 为目标,从 package.json 和 lockfile 检测实际版本;用网络检索对照官方 TypeScript 文档核实当前最佳实践、API 可用性和迁移指引;仓库实际情况作为当前项目可安全交付的基准。若官方指引与仓库现实在非平凡建议上实质分歧,标记 OFFICIAL_CONFLICT,实施仓库安全路径并说明迁移路径;若官方来源之间互相矛盾,同样标记 OFFICIAL_CONFLICT;无法在官方来源确认的非平凡主张标记 UNVERIFIED。
  • 不生成仅 beta 的语法(除非用户明确要求);当安装版本落后于最新稳定版时,指出差距并建议升级路径;不硬编码版本号,保持建议长期适用。
  • 存在宿主仓库 AGENTS.md 等说明时,查看其中的项目特定版本政策与工具,不假定其包含本技能的默认值。

使用方式

内置资产包括可复用的 tsconfig 起始脚手架和可选的 ESLint flat-config 起始模板(位于 assets/ 下),以及一个确定性辅助脚本(位于 scripts/ 下)。当仓库希望采用这套风格起点且自身尚无有效 TypeScript 配置时使用它们:用 scripts/scaffold_ts_baseline.py 配合 assets/tsconfig-template/ 与 assets/eslint-template/ 生成确定性起始配置,而不是临时手写配置。

按需加载参考文档:

  • references/ts-modern-patterns.md:原型选择、tsconfig 基线与现代类型模式。
  • references/ts-legacy-to-modern-migration.md:旧到新迁移、禁用模式与例外处理。
  • references/ts-config-resolution.md:本地 TypeScript 配置发现、起始脚手架或可选 ESLint 支持。
  • references/task-bundle.md:仅当目标仓库需要可选的基于 Task 的自动化叠加层时阅读。

配置解析以真实项目配置为准:存在 tsconfig*.json、eslint.config.*、package.json 和 lockfile 时先检查;选择起始模板前匹配本地运行时、打包工具和包管理器实际情况;ESLint 起始模板视为对 TS 仓库的可选强默认支持,而非通用 TypeScript 政策;脚手架过程中不得静默安装依赖或改动 CI。

当 TypeScript 问题出现在框架项目中时,可与 ub-vuejs 或 ub-nuxt 共同加载本技能;框架运行时、路由与应用结构决策交给负责它们的同级技能。

重大 TypeScript 决策使用共享的 ub-quality 决策分析基线:列出各选项在正确性、兼容性、开发体验和迁移成本上的利弊,除非用户约束另有要求,默认选择最安全的现代选项。

核心工作流

  1. 从 package.json、lockfile、运行时目标、构建工具和现有 tsconfig*.json 检测项目原型。
  2. 选择与运行时真实情况匹配的模块策略。
  3. 对非平凡或版本敏感的建议,比较官方指引、仓库现实与观察到的代码现实;必要时标记 OFFICIAL_CONFLICT 或 UNVERIFIED。
  4. 应用参考文档中的严格安全基线与模块卫生默认值。
  5. 先实现现代类型模式,新代码拒绝遗留输出,触及既有代码时应用迁移映射。
  6. 用目标项目可用的 typecheck、lint、测试和构建命令验证。
  7. 若仓库想要此基线但缺少 TypeScript 配置,生成内置起始脚手架并说明仍需的仓库本地适配。

输出要求

生成或审查代码时应包含:环境说明(检测到的原型、运行时目标与工具链上下文);来源事实说明(检测到的项目版本/工具链现实及与最新稳定指引的实质差距);版本说明(TypeScript 基线与有意偏离);决策说明(所选模块与编译器策略及一个备选方案);权衡说明(所选路径与被否决选项的简要利弊);遗留说明(移除的遗留模式或有界例外及理由);验证说明(运行了哪些检查及结果);相关时给出冲突说明(OFFICIAL_CONFLICT 或 UNVERIFIED 及简要解释与实施后果)。

当用本技能向另一仓库交付 TypeScript 配置脚手架时,还应说明:创建或跳过了哪些文件;选择了哪个原型及一个被否决的备选;哪些仓库本地设置或依赖仍需适配;下一步要运行的具体验证命令。

适用场景

需要在 TypeScript 项目中统一现代类型写法与编译器配置、将旧代码迁移到现代模式、为缺少 TS 配置的仓库建立确定性起始基线、或在 Vue/Nuxt 等框架项目中处理 TS 配置与类型问题时使用。

限制

  • 该技能为建议性质(advisory),新鲜度应影响审查优先级,而不是本身成为阻塞要求。
  • 起始脚手架报告为起始配置方案,而非静默成为仓库政策。
  • 不得静默安装依赖或改动 CI。
  • 不生成仅 beta 语法,除非用户明确要求。
  • 不硬编码版本号。