typescript-magician

typescript-magician 技能概覽

typescript-magician 的用途

typescript-magician 技能專門用來處理一般提示詞常常搞不定的 TypeScript 難題：深層泛型設計、嚴格型別清理、編譯器錯誤、type guard，以及進階型別轉換。當真正的工作不是「寫一些 TS」，而是「在不破壞既有呼叫端的前提下，讓這個 API 或 codebase 變成 type-safe」時，它最有用。

最適合的使用情境

當你需要協助處理 any 移除、infer、extends、conditional types、mapped types、template literal types、branded 或 opaque types、utility types，或 inference bug 時，typescript-magician 技能都很合適。它也很適合用在 code generation 任務中，輸出不只要語法正確，還必須符合型別，並且保有良好的使用體驗。

這個技能有什麼不同

這個技能是以 compiler-first 的修復流程來組織：先抓 tsc 輸出、找出根本的型別問題、套用精準修正，最後再確認可以重新編譯。對重視安全性、重構信心，以及進階型別行為的團隊來說，typescript-magician 比一般的 TypeScript 提示詞更實用。

如何使用 typescript-magician 技能

安裝並啟用它

先透過你的 skill manager 跑 typescript-magician install 流程，然後把它指向發生 TypeScript 問題的 repository。上游技能中的參考安裝指令是：

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

如果你的環境使用的是不同的 installer 或 workspace 佈局，重點仍然一樣：在要求它修改型別或診斷編譯器錯誤之前，先把這個技能載入。

給它一個編譯器會在意的任務

最好的 typescript-magician usage 會從具體失敗或明確目標開始。好的輸入包括：

• 完整的 tsc --noEmit 錯誤區塊
• 正在失敗的 function、type 或 file
• 想要的 runtime 行為與 type 行為
• 任何限制，例如「避免 as any」、「保留 public API」、「支援 TS 5.x」

一個強而有力的提示詞會像這樣：
“在不改變 runtime 行為的前提下修正這個 tsc --noEmit 錯誤。保留 public API、移除 any，並維持呼叫端的 inference。”

先讀這些檔案

如果你要找實用的 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

如果你的問題是 runtime value 影響 type，還要再看 rules/as-const-typeof.md 和 rules/deep-inference.md。

產出品質更好的工作流程

先蒐集完整錯誤，再把問題縮減成最小會失敗的 type 或 function，接著要求一個不破壞既有呼叫端的 type-safe 修正。若是 typescript-magician for Code Generation，一開始就把目標形狀寫清楚：預期的 generics、可接受的輸入、回傳型別，以及像 union、nullable values、array indexing 或 overloads 這類邊界情況。

typescript-magician 技能 FAQ

typescript-magician 只適合編譯器錯誤嗎？

不是。typescript-magician 技能也很適合用來為新程式碼設計型別，尤其是當你需要進階 inference 或可重用的 utility types 時。當型別本身就是產品契約的一部分，而不只是註解時，它的價值最大。

什麼時候不該用它？

如果任務主要是 runtime 邏輯、格式處理，或完全沒有型別系統複雜度的一般應用程式碼，就可以先跳過 typescript-magician。如果你無法提供真實的 TypeScript 錯誤、檔案上下文或驗收條件，它也不會那麼有幫助。

對初學者友善嗎？

可以，只要你給它明確而狹窄的問題，並讓它用白話說明型別推理。若任務需要進階 conditional types 或 inference 規則，卻沒有任何範例程式碼，它就會比較不適合初學者。

它和一般 TypeScript 提示詞有什麼不同？

一般提示詞常常只能產生看起來合理的修正；typescript-magician 則是針對能通過 tsc、保住呼叫端 inference，並使用正確 TypeScript 特性的修正而優化。這在 shared libraries、SDK，以及那些「看起來對」還不夠的重構情境中特別重要。

如何改善 typescript-magician 技能

提供最小的失敗範例

提升品質最大的一步，就是把問題縮到最小、可重現的 TypeScript snippet。請包含 type、function signature、失敗的呼叫，以及 compiler error。輸入越精簡，typescript-magician 技能越容易選對 constraint、overload 或 conditional type。

說明真正重要的限制

告訴技能哪些東西一定要保留：runtime 行為、API 形狀、向下相容性、strict mode，或支援舊版 TS。如果你要做 typescript-magician for Code Generation，也要明確指定輸出偏好：要用顯式 helper、推斷式 return type，還是可重用的 generic utilities。

留意常見失誤模式

最常見的問題，是過度寬鬆的修正把錯誤蓋掉、用 any 取巧，或是型別定義只對單一範例有效，卻會在 union、陣列或 optional properties 上失效。若第一次的答案太鬆，請它提供更嚴格的版本，並附上一兩個一定也要能通過編譯的反例。

用真實呼叫端反覆驗證

第一次修正後，拿代表性的用法測試它：union input、nullable input、array 或 tuple，以及一個應該失敗的「錯誤」輸入。把這些結果回饋到 typescript-magician guide 的提示詞裡，讓下一輪不是只修補原本的錯誤，而是能進一步收緊 inference。