typescript-magician

typescript-magician 技能概览

typescript-magician 能做什么

typescript-magician 技能专门帮你解决普通 prompt 很难处理的 TypeScript 难题：深层泛型设计、严格类型清理、编译错误、类型守卫，以及高级类型转换。它最适合的场景不是“写一些 TS”，而是“在不破坏现有调用方的前提下，让这个 API 或代码库变得类型安全”。

最适合的使用场景

当你需要处理 any 清理、infer、extends、条件类型、映射类型、模板字面量类型、branded 或 opaque types、utility types，或者推断 bug 时，适合使用 typescript-magician 技能。对于代码生成任务，如果你的目标不仅是语法正确，还要兼顾易用性和类型正确性，它会非常合适。

这个技能有什么不同

这个技能围绕“先看编译器，再做修复”的流程组织：先捕获 tsc 输出，定位根本的类型问题，再做精确修复，最后验证是否重新通过编译。这让 typescript-magician 比通用 TypeScript prompt 更适合重视安全性、重构信心和高级类型行为的团队。

如何使用 typescript-magician 技能

安装并激活它

通过你的 skill manager 使用 typescript-magician install 流程，然后把它指向 TypeScript 问题所在的仓库。上游技能里的参考安装命令是：

npx skills add mcollina/skills --skill typescript-magician

如果你的环境使用的是不同的安装器或工作区结构，保持同样的目标即可：先加载技能，再让它去修改类型或诊断编译错误。

给它一个“编译器风格”的任务

最好的 typescript-magician usage 都是从一个具体失败或一个明确目标开始。高质量输入包括：

• 完整的 tsc --noEmit 报错块
• 出问题的函数、类型或文件
• 你希望的运行时行为和类型行为
• 任何限制条件，比如“不要用 as any”、“保留 public API”、“需要支持 TS 5.x”

一个强 prompt 可以这样写：
“修复这个 tsc --noEmit 报错，不要改变运行时行为。保留 public API，移除 any，并保持调用方的推断能力。”

先看这些文件

如果你要写一个实用的 typescript-magician guide，先从 SKILL.md 开始，然后查看 rules/ 里最接近你问题的模式。最有用的入口通常是：

• rules/error-diagnosis.md
• rules/generics-basics.md
• rules/conditional-types.md
• rules/type-narrowing.md
• rules/utility-types.md

如果你的问题涉及运行时值如何喂给类型系统，也要看看 rules/as-const-typeof.md 和 rules/deep-inference.md。

更容易产出好结果的工作流

先拿到准确的错误信息，再把问题缩小到最小的失败类型或函数，然后要求一个既类型安全又能保持现有调用方可用的修复方案。对于 typescript-magician for Code Generation，一开始就把目标形状说清楚：期望的泛型、可接受输入、返回类型，以及联合类型、可空值、数组索引或 overloads 这类边界情况。

typescript-magician 技能 FAQ

typescript-magician 只适合编译错误吗？

不是。typescript-magician 技能也很适合为新代码设计类型，尤其是在你需要高级推断或可复用 utility types 的时候。当类型已经是产品契约的一部分，而不只是注释时，它的价值最大。

什么时候不该用它？

如果任务主要是运行时逻辑、格式化，或者没有类型系统复杂度的普通应用代码，就不必用 typescript-magician。如果你没法提供真实的 TypeScript 报错、文件上下文或验收标准，它也会少很多帮助。

它适合初学者吗？

适合——前提是你给它一个足够聚焦的问题，并让它用通俗语言解释类型推理过程。若任务依赖高级条件类型或推断规则，却没有示例代码，它对初学者就没那么友好。

它和普通 TypeScript prompt 有什么区别？

普通 prompt 往往只能给出一个“看起来可行”的修复；而 typescript-magician 的优化目标，是给出一个能通过 tsc、保留调用方推断、并且用对 TypeScript 特性的修复方案。这一点在共享库、SDK 和重构场景里尤其重要，因为“看起来对”远远不够。

如何改进 typescript-magician 技能

提供最小可复现失败示例

提升效果最大的方式，是把问题压缩成最小可复现的 TypeScript 片段。请包含类型、函数签名、失败的调用方式，以及编译器报错。输入越小，typescript-magician 技能越容易选对约束、overload 或条件类型。

说清楚必须保留的约束

告诉技能必须保留什么：运行时行为、API 形状、向后兼容性、strict mode，或者对旧版 TS 的支持。如果你在做 typescript-magician for Code Generation，还要说明输出更偏好显式 helper、推断返回类型，还是可复用的泛型工具。

注意常见失败模式

最常见的问题是修复范围过大、把错误藏起来的方案，以及基于 any 的权宜之计；还有一种是类型定义只对一个示例有效，却会在联合类型、数组或可选属性上失效。如果第一版答案太宽松，就要求一个更严格的版本，并附上一两个必须仍然能通过编译的反例。

用真实调用点反复验证

第一次修复后，用有代表性的用法来测试：联合类型输入、可空输入、数组或 tuple，以及一个应该失败的“坏”输入。把这些结果反馈回 typescript-magician guide prompt，这样下一轮就能收紧推断，而不是只修补原始报错。