Typescript Toolkit Free

Provides TypeScript type safety guidance for personal projects, including type narrowing, literal traps, and strict null handling practices.

TypeScript 工具集(免费版)

概述

typescript-toolkit-free 是面向个人开发者的 TypeScript 类型安全辅助工具。它聚焦日常编码中最常见的类型陷阱与最佳实践,帮助你写出类型安全、易于维护的代码。免费版覆盖核心场景,适合独立项目、学习实践与小型应用开发。

本版本不依赖任何外部脚本或私有 API,完全通过 Markdown 指令驱动 AI Agent 输出建议与代码片段。

核心能力

能力	说明
类型收窄指导	typeof、in、Array.isArray 等收窄技巧与陷阱识别
any 替代方案	用 unknown、泛型、类型守卫替换 any 的实战方法
字面量陷阱修复	let vs const、对象属性拓宽、函数返回类型拓宽
严格空值处理	可选链 ?.、空值合并 ??、非空断言 ! 的使用边界
模块边界规范	import type、export type 与 .d.ts 增强基本用法
技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置。

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

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

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

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

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：面向个人开发者的、TypeScript、类型安全辅助工具、覆盖基础类型收窄、推断与严格模式实、工具集免费版为个、人开发者提供日常、类型安全辅助、涵盖类型收窄、严格空值处理等核、心主题、基础类型安全指导、与代码审查、的替代方案与收窄、字面量类型陷阱识、别与修复建议、严格空值处理与可、选链最佳实践等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景 1:API 响应类型化

当你需要为 API 响应定义类型时,本工具会建议用 unknown 替代 any,并通过类型守卫收窄。

typescript

// 不推荐:用 any 静默破坏类型安全
async function fetchUser(): Promise<any> {
  const res = await fetch('/api/user');
  return res.json();
}
// ...
// 推荐:用 unknown 强制收窄
async function fetchUser(): Promise<User> {
  const res = await fetch('/api/user');
  const data: unknown = await res.json();
  if (isValidUser(data)) {
    return data;
  }
  throw new Error('Invalid user payload');
}
// ...
function isValidUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'name' in value
  );
}

场景 2:过滤数组时保留类型

filter(Boolean) 不会收窄类型,本工具会提示你使用类型谓词函数。

typescript

// 不推荐:filtered 仍是 (string | null)[]
const filtered = list.filter(Boolean);
// ...
// 推荐:显式类型谓词,filtered 收窄为 string[]
const filtered = list.filter((x): x is string => Boolean(x));

场景 3:配置对象的字面量保留

为配置对象定义类型时,使用 satisfies 保留字面量信息。

typescript

const palette = {
  primary: '#0066ff',
  danger: '#cc0000',
} satisfies Record<string, string>;
// palette.primary 类型为字面量 '#0066ff',而非 string

不适用场景

以下场景TypeScript工具集(免费版)不适合处理：

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

触发条件

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

快速开始

第一步:提出问题

直接在对话中描述你的 TypeScript 问题,例如:

text

我在用 filter(Boolean) 后类型没有收窄,该怎么修?

text

帮我看看这段 API 响应类型定义是否安全。

第二步:获取建议

工具会输出问题分析、修复代码与简要解释,并标注是否符合严格模式要求。

第三步:应用并验证

将建议代码复制到你的项目中,运行 tsc --noEmit 验证类型是否通过。

bash

npx tsc --noEmit

示例

推荐 tsconfig.json(个人项目基线)

jsonc

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022", "DOM"],
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

推荐 ESLint 规则(个人项目)

jsonc

{
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/no-unused-vars": "warn",
    "@typescript-eslint/consistent-type-imports": "error",
    "@typescript-eslint/prefer-optional-chain": "error"
  }
}

最佳实践

1. 永远不要在生产代码中使用 any。改用 unknown 并显式收窄,或用泛型表达意图。
2. 优先使用 satisfies 而非类型注解 来保留字面量信息,尤其适用于配置对象。
3. 为可辨识联合添加 type 字段,启用穷举 switch 检查,避免漏掉分支。
4. Object.keys(obj) 返回 string[],不要假设它是 keyof typeof obj,因为对象可能有额外键。
5. Array.isArray() 收窄为 any[],如需更精确的元素类型,需要额外断言或类型守卫。
6. import type 仅用于类型导入,避免打包器产生运行时依赖。
7. 非空断言 ! 应作为最后手段,优先用收窄或提前返回。

常见问题

Q1: filter(Boolean) 为什么不收窄类型?

JavaScript 的 Boolean 函数签名返回 boolean,TypeScript 无法据此推断元素类型已收窄。需要用类型谓词函数显式声明:.filter((x): x is T => Boolean(x))。

Q2: let x = "hello" 为什么类型是 string 而不是 "hello"?

let 声明的变量会被拓宽为更宽的类型,因为它们可被重新赋值。用 const 或 as const 可保留字面量类型。

Q3: 可选链 ?. 返回 undefined,但 API 需要 null,怎么办?

显式处理:const value = obj?.field ?? null;,或在收窄阶段统一为 null。

Q4: import type 和普通 import 有什么区别?

import type 仅在编译期存在,运行时会被完全移除,适合只引用类型的场景,有助于打包器 tree-shaking。

Q5: 免费版与 Pro 版的主要区别是什么?

免费版聚焦个人日常类型安全指导;Pro 版在此基础上提供团队规范、批量 JS→TS 迁移、CI 集成与企业级代码审查能力。

依赖说明

运行环境

• Agent 平台:支持 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等)
• 操作系统:Windows / macOS / Linux
• Node.js:建议 18+ 用于本地 tsc 验证
• TypeScript:建议 5.0+(支持 satisfies 关键字)

依赖详情

依赖项	类型	是否必需	获取方式
TypeScript	npm 包	推荐	npm i -D typescript
ESLint + @typescript-eslint	npm 包	可选	npm i -D eslint @typescript-eslint/eslint-plugin
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

• 本 Skill 完全基于 Markdown 指令,无需额外 API Key
• 本地 tsc 验证使用本地 TypeScript 编译器,不涉及任何外部 API

可用性分类

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

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

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

输出格式

json

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