migrate-to-shoehorn

migrate-to-shoehorn skill 概览

migrate-to-shoehorn skill 用来把 TypeScript 测试代码 中脆弱的 as 断言，重构为基于 @total-typescript/shoehorn 的写法。它尤其适合这样的场景：现有测试里已经堆满了 as Type 或 as unknown as Type，而且对象类型一大，测试数据准备就会变得又吵又乱，还容易误导阅读者。

migrate-to-shoehorn 主要解决什么问题

当你的真实诉求不是“学一个新库”，而是在不重写整套测试的前提下，把不安全的测试 fixture 清理干净时，就该用 migrate-to-shoehorn。这个 skill 聚焦的是一个很明确的重构任务：

• 用 fromPartial() 替换 as Type
• 用 fromAny() 替换 as unknown as Type
• 减少测试里为大对象硬凑出来的假数据样板代码

哪些人适合安装这个 skill

如果你符合下面这些情况，migrate-to-shoehorn skill 会很适合你：

• 在维护大量带 casting 的 TypeScript 测试
• 希望用更安全的方式处理 partial fixture
• 需要明确判断不同断言写法该映射到哪个 shoehorn helper
• 想让 agent 执行或引导一次有针对性的重构，而不是给一堆泛泛的 TypeScript 建议

采用前最该先想清楚的事

最关键的决策点是适用范围：这个 skill 明确只面向测试，不是生产代码。这一点很重要，因为 shoehorn 的价值在于：当你为了覆盖测试场景，故意传入不完整甚至不合法的数据时，依然可以比裸写断言获得更清晰、更有意图的类型表达。

为什么用 migrate-to-shoehorn，而不是随便写个通用重构提示词

通用提示词往往只是机械地删除 as，却抓不住原本的测试意图。migrate-to-shoehorn 更实用，是因为它针对的是开发者在真实迁移里最常遇到的几类模式：

• 大对象类型下的 partial 测试输入
• 负向测试里故意传入的错误数据
• 去掉那些与测试无关、只是为了“凑类型”而加上的假属性

这种更窄、更明确的聚焦，通常意味着更少猜测，也更少不安全的替换。

如何使用 migrate-to-shoehorn skill

migrate-to-shoehorn skill 的安装背景

如果你要在项目里使用底层库，先安装：

npm i @total-typescript/shoehorn

如果你是在支持 skills 的环境中安装这个 skill，就按你所在平台的常规 skill 安装流程来，然后在处理测试重构时调用 migrate-to-shoehorn。

先看这个文件

先从 migrate-to-shoehorn 目录下的 SKILL.md 开始。在这个仓库里，它是最主要的事实来源，里面包含了驱动这个 skill 的迁移模式。

建议阅读顺序：

1. migrate-to-shoehorn/SKILL.md
2. 你准备修改的测试文件
3. 你本地代码中所有 as Type 和 as unknown as Type 的使用点

这个 skill 需要什么输入

当你提供下面这些信息时，这个 skill 的效果最好：

• 当前的测试代码片段
• 被调用的目标函数或组件
• 相关类型名（如果已知）
• 测试数据应该是合法数据，还是故意构造的非法数据
• 你要的是一次性修复，还是可复用的迁移模式

如果没有这些上下文，agent 仍然可以建议 fromPartial() 或 fromAny()，但很可能会选错 helper。

应该明确提出的核心迁移模式

常见的 migrate-to-shoehorn usage 其实很直接：

• as Type → 通常对应 fromPartial()
• as unknown as Type → 通常对应 fromAny()
• 假对象特别大、但测试里只关心少数字段 → fromPartial()

这正是这个 skill 的核心价值：把“帮我清理这些测试里的 cast”这种模糊请求，收敛成一套一致、可执行的重构方式。

如何写出高质量的 migrate-to-shoehorn 提示词

一个较弱的提示词：

Replace as with shoehorn.

一个更强的提示词：

Use the migrate-to-shoehorn skill to refactor this test file. Replace plain as Request casts with fromPartial() where the object is just a partial fixture. Replace as unknown as Request with fromAny() only where the test intentionally passes invalid data. Keep the test behavior unchanged and add imports if needed.

这种写法给了 agent 明确的意图、边界和决策规则。

示例：partial fixture 迁移

修改前：

getUser({ body: { id: "123" } } as Request);

修改后：

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

当 fixture 在结构上不完整，但在测试语义上仍然是“合理输入”时，用这种方式最合适。

示例：故意传错数据的迁移

修改前：

getUser({ body: { id: 123 } } as unknown as Request);

修改后：

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

当测试本来就是为了覆盖校验逻辑或失败路径，故意传入非法数据时，就该用这种方式。

大规模重构时的最佳 workflow

如果你要做一份仓库级别的 migrate-to-shoehorn guide，不要一上来就盲目批量改全仓。更稳妥的流程是：

1. 在测试文件里搜索 as 和 as unknown as
2. 先把这些 cast 分类为 partial-valid 和 intentionally-invalid
3. 先迁移一个测试目录
4. 跑测试和 typecheck
5. 统一 import 风格和 helper 选择
6. 再扩展到整套测试

这样可以避免把本来属于负向测试的 cast，和普通 fixture 清理混在一起处理。

能明显提升输出质量的实用建议

你可以明确要求 agent 保留这些细节：

• 现有测试名称和断言
• 非法输入测试的语义意图
• 保持 fixture 形状最小化，而不是展开成完整假对象
• 如果多个 helper 同时使用，要去重并整理 import

另外，如果你希望 skill 优先生成尽可能小的 fixture，也请直接说清楚。这样通常会得到最干净的 shoehorn 重构结果。

哪些情况下 migrate-to-shoehorn 不适合用

如果你的核心问题是生产环境类型安全、领域建模，或者 API contract 的正确性，就不要把 migrate-to-shoehorn for Refactoring 当成解决方案。这个 skill 不是用来“把所有类型问题都修好”的，它只是一个聚焦在测试重构上的辅助工具。

migrate-to-shoehorn skill 常见问题

migrate-to-shoehorn 只适用于测试吗？

是的。这是最重要的边界。这个 skill 围绕的是测试的人体工学和测试意图，而不是生产代码里的类型设计模式。

如果我的测试本来就能通过，还需要 shoehorn 吗？

不一定。只有当你当前的测试难读、充满噪音很大的假对象，或者依赖不安全的 cast 来掩盖真实意图时，安装 migrate-to-shoehorn 才更有价值。如果你的测试准备本来就很干净，这次迁移可能并不值得。

fromPartial 和 fromAny 有什么区别？

fromPartial() 适合不完整、但整体上仍然合理的 fixture 数据。
fromAny() 适合故意传入的非法数据，也就是测试需要绕过更严格的类型约束，去模拟运行时坏输入的场景。

这也是为什么比起宽泛的“去掉断言”提示词，这个 skill 更值得用的主要原因之一。

migrate-to-shoehorn 对新手友好吗？

友好，前提是你已经理解基本的 TypeScript 测试。它的范围很小，迁移规则也容易掌握。新手最常见的风险不是不会用，而是把 shoehorn 过度用到测试之外。

我能用这个 skill 做整个仓库的迁移吗？

可以，但前提是你要按类别逐步审查。大规模迁移里最容易出错的地方，就是把所有 cast 都当成同一种东西处理。实际上，有的是 partial fixture，有的是故意构造的错误 payload，还有一些可能属于生产代码，根本不该按这套模式迁移。

这比普通提示词更好吗？

通常是的，尤其当任务非常明确，就是“把测试里的断言迁移到 shoehorn”时。普通提示词也许知道这个库，但当你想把旧 cast 风格稳定地映射到正确的 helper 时，migrate-to-shoehorn usage 会更可靠。

如何改进 migrate-to-shoehorn skill 的使用效果

给 agent 的不是代码本身，而是测试意图

想提升 migrate-to-shoehorn 的效果，最快的方法就是明确说明每个测试到底在验证什么：

• 使用 partial setup 的 happy path 行为
• 使用故意错误输入触发的校验失败
• 只需要少数字段的边界情况

这一个上下文信息，往往就足以决定该用 fromPartial() 还是 fromAny()。

一开始就标明哪些文件是 test-only

如果某个文件同时混有 helper 代码和生产代码，一定要提前说明。只要你明确告诉 agent：

Only apply migrate-to-shoehorn changes inside test files and test fixtures.

这个 skill 就会安全得多。

这样可以避免改动意外扩散到非测试路径。

先让它盘点 cast，再动手改

面对比较乱的测试集，可以先这样开始：

Using the migrate-to-shoehorn skill, classify each cast in this file as fromPartial, fromAny, or leave unchanged, then explain why.

先审查、后改写，这一步能在真正重构前先把边缘情况筛出来。

类型推断不清楚时，把附近类型也一起提供

如果单看代码片段看不出预期类型，就把函数签名或相关类型定义一并贴出来。类型上下文越完整，agent 在 import 选择和重构落地上就越准确，也越不容易写出别扭的改法。

留意这些常见失败模式

migrate-to-shoehorn install 和落地采用过程中，常见问题包括：

• 把 shoehorn 用到生产代码里
• 把本应表示“故意非法数据”的场景错误地改成 fromPartial()
• 不去简化 fixture，反而把对象越展开越大
• 在“清理”类型时，顺手改掉了测试原本的语义

这些都不是库本身的问题，而是提示词和审查流程的问题。

对第一版结果继续迭代

第一轮改完后，可以继续提出第二轮 refinement，比如：

• 把每个 fixture 缩减到只保留测试真正需要的字段
• 合并并整理 imports
• 解释为什么某些剩余 cast 应该保留
• 把合法的 partial 数据和非法测试数据明确分开

这样你得到的就不只是一次基础迁移，而是一套更干净、也更适合长期维护的测试模式。