Agent Skills
返回列表
💻

TypeScript 开发指南

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请在 AI 助手中安装 @org-eyw2ohcx/siviter-xyz-dot-agent-typescript 技能,安装指南详见 https://skillhub.cn/install/skillhub.md

技能介绍

当 TypeScript 项目从原型走向长期维护时,最先失控的往往不是业务逻辑本身,而是类型契约。隐式 any 顺着 any 扩散,循环依赖经由 barrel exports 悄悄传入,测试与构建配置越来越像是临时拼出来的。这些细节在代码审查里偶尔被放过,最终会在重构或错误处理时连本带利地讨回来。TypeScript Guidelines 就是为这一类工程师日常工作准备的约束清单——它不是模板,不是脚手架,而是一套可以放进审查流程和 IDE 提示里的判断标准。

这套组合解决什么

它首先定义了代码应该做什么,而不是项目长什么样。设计原则部分要求团队持续应用 DRY、KISS 和 SOLID,同时在“何时用函数式风格、何时保留类管理有状态行为”之间划清界线:纯计算、输入到输出的映射优先走函数组合;涉及生命周期、共享状态或外部副作用时,才使用以依赖注入管理的类。这样的区分能把类型推断的复杂度压到可控范围内,让接口签名更接近真实执行路径。

技能如何工作

技能分成三个核心工作流:设计原则、类型安全和模块化架构。在类型层面,指南要求默认启用严格模式,把 unknown 作为未知值的入口,通过类型收窄拿到具体类型;需要枚举语义时,用联合类型覆盖允许值,用可辨识联合表达状态机分支,并用泛型约束阻止无意义的泛型堆叠。调用内置的 Pick、Omit、Partial 抽取公共形状;导入被指定为直连路径,避免 barrel 造成的循环依赖。在模块划分上,职责单一、类型与使用共存、依赖倒置与注入等约定,让每个文件夹都能被独立理解或索引。

它在工程规范上同样具有约束力。测试用 Vitest 承担 Unit 与 Integration,辅以 @vitest/coverage-v8 收集覆盖率,需要 DOM 时切换到 jsdom,并保持 AAA 结构。行为级验收由 Playwright 接管,避免用单测覆盖太厚的浏览器行为,从而保持两套测试的目标清晰。在格式化与静态检查上,Prettier(printWidth 120、singleQuote 和 jsxSingleQuote)负责排版,ESLint(@typescript-eslint/parser、@typescript-eslint/eslint-plugin)负责发现共存问题,再配合 pnpm 固定统一工具链——pnpm format、pnpm format:check、pnpm lint、pnpm lint:fix 承担 CI 卡点。

适用边界与注意点

指南并不规定应用类型属于哪个领域。把后端 API、CLI 工具和包管理器作为交付目标的团队会更容易按它的节奏前进:严格类型、少依赖、独立模块,以及「不能被自动化覆盖的代码不承认已经写完」的底线。如果项目是极度偏向前端 UI、重型客户端交互,指南中提到的 React、Svelte、Solid 等框架选项更适宜作为决策起点,而工具链上的取舍(Vite、Rolldown、pnpm)仍可视团队现状按需替换。重要的是先把默认规则跑进 CI,再逐步补齐测试用例,并且不要为了统一风格而强行重写既有模块。

使用场景

  • 用 Zod schema 校验 HTTP 请求体,让编译期类型与运行时校验保持一致
  • 重构状态管理模块,用可辨识联合类型表达 loading/error/success 状态机
  • 在 monorepo 中用 pnpm workspaces 统一包管理,配合 Vitest 跑单元测试
  • 迁移遗留代码库,用直接导入替换 barrel exports 以消除循环依赖

适合人员

  • TypeScript 后端工程师,需要为团队 API 定义类型契约并统一测试方案
  • 负责维护大型前端项目的架构师,需要统一 monorepo 工具链和 CI 检查
  • 长期维护 TypeScript 代码库的开发者,需要重构遗留类型定义与 barrel 导入
  • 需要将 DOM 操作封装为类型安全工具的前端工程师,希望减少 inline any