TypeScript 编码规范工具(免费版)

概述

typescript-skills-tool-free 为个人开发者提供符合行业惯例的 TypeScript 编码规范指导。它覆盖命名、类型、函数、类、模块等基础约定,帮助你在个人项目中写出风格一致、可读性强的代码。免费版聚焦核心规范,适合中小型项目与学习实践. 当你在对话中提及 TypeScript 相关话题时,本工具会自动激活并输出符合规范的代码示例与解释.

核心能力

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：面向个人开发者的、TypeScript、编码规范指导、覆盖命名、模块等基础约定、编码规范工具免费、版为个人开发者提、供符合行业惯例的、编码约定、涵盖命名规范、函数与类、模块与导入等基础、核心能力、命名规范指导、类型与接口选择策、函数与类的最佳实、模块与导入顺序约、错误处理与空值处、理基础等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景 1:命名规范快速参考

当你不确定某个构造的命名约定时,直接询问即可获得表格化参考.

问:TypeScript 中常量、类、接口、枚举成员分别用什么命名风格?

场景 2:类型与接口选择

当你需要为对象形状定义类型时,本工具会指导你选择 interface 还是 type.

// 推荐:对象形状用 interface
interface User {
  readonly id: string;
  name: string;
  email: string;
}
// ...
// 推荐:联合、交叉、映射类型用 type
type Status = 'active' | 'inactive' | 'suspended';
type Result<T> = Success<T> | Failure;

场景 3:函数参数过多时的重构

当函数参数超过 3 个时,本工具会建议你使用选项对象.

// 不推荐:位置参数过多
function createUser(name: string, email: string, role: Role, dept: string): User { ... }
// ...
// 推荐:使用选项对象
interface CreateUserOptions {
  name: string;
  email: string;
  role?: Role;
  department?: string;
}
function createUser(options: CreateUserOptions): User { ... }

不适用场景

以下场景TS编码规范工具(免费版)不适合处理：

• 无明确技术栈的模糊需求
• 纯架构设计决策
• 运维部署管理

触发条件

需要代码生成、编程辅助、调试测试、开发部署时使用。不适用于非本工具能力范围的需求.

快速开始

第一步:激活工具

在对话中提及 TypeScript,本工具会自动激活。例如:

帮我写一个 TypeScript 函数,合并两个对象.

审查这段 TypeScript 代码的风格问题.

第二步:获取规范代码

工具会输出符合规范的代码、解释与可选的 ESLint 规则提示.

第三步:本地验证

npx tsc --noEmit
npx eslint . --fix

示例

个人项目 tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

个人项目 ESLint 基线

{
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/consistent-type-imports": "error",
    "@typescript-eslint/no-non-null-assertion": "warn"
  }
}

最佳实践

1. 始终启用 strict: true:这会开启 noImplicitAny、strictNullChecks、strictFunctionTypes 等关键检查.
2. 优先具名导出:具名导出利于重构与自动导入,默认导出仅用于 React 组件(若项目约定要求).
3. import type 用于类型导入:帮助打包器 tree-shaking,避免运行时依赖.
4. const 优先,let 仅在需要重新赋值时使用,永不使用 var.
5. 函数参数最多 3 个,超出则用选项对象.
6. 错误处理使用自定义错误类,catch 变量类型为 unknown,收窄后再使用.
7. 使用 TSDoc 注释公共 API,包含 @param、@returns、@example 标签.
8. 缩进 2 空格,分号必加,单引号,多行结构尾逗号:配合 Prettier 自动格式化.

常见问题

Q1: 接口要不要加 I 前缀?

不要。IUser 是 .NET 风格,TypeScript 社区普遍使用 User。也不要加 Type 或 Interface 后缀.

Q2: 枚举用字符串枚举还是字符串字面量联合?

小集合且不需要命名空间特性时,优先字符串字面量联合(更简单、可 tree-shaking)。需要反向映射或命名空间时用字符串枚举。避免数字枚举,自动递增易出错.

Q3: async/await 还是 .then() 链?

优先 async/await,可读性更好。并行独立操作用 Promise.all()。避免 async void 函数(无法 await 且吞错误).

Q4: 私有成员要不要加 _ 前缀?

不要。TypeScript 的 private 关键字已足够。需要真正运行时私有性时用 # ES 私有字段.

Q5: 免费版与 Pro 版的区别?

免费版提供个人项目所需的基础规范与示例;Pro 版扩展团队规范、自动化审查脚本、企业级 ESLint 规则集与 CI 集成能力.

依赖说明

运行环境

• Agent 平台:支持 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等)
• 操作系统:Windows / macOS / Linux
• Node.js:建议 18+
• TypeScript:建议 5.0+

依赖详情

API Key 配置

• 本 Skill 完全基于 Markdown 指令,无需额外 API Key
• 本地 tsc 与 eslint 使用本地工具链,不涉及外部 API

可用性分类

• 分类: MD+EXEC(纯 Markdown 指令,部分功能需要 exec 命令行执行能力)
• 说明: 基于自然语言指令驱动 Agent 输出规范代码与解释;用户可通过 tsc --noEmit 与 eslint 在本地验证

错误处理

已知限制

• 需LLM支持,无LLM环境不可用
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响
• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

输出格式

{
  "success": true,
  "data": {
    "result": "TS编码规范工具(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "typescript skills"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}