extract

extract 技能概览

extract 是做什么的

extract 技能帮助你把反复出现的 UI 代码提炼成可复用的 Design System 资产。实际使用中，它会找出重复组件、硬编码的设计值以及不一致的实现模式，然后提出或直接创建共享组件与 design tokens。

extract 适合谁用

extract 技能最适合正在维护产品 UI、组件库或 Design System 的团队：代码里已经出现一定程度的重复，希望用更系统的方法来收敛和统一。它尤其适合前端工程师、Design System 维护者，以及依赖 AI 辅助重构的工作流。

它真正解决的核心问题

大多数用户想要的并不是一次泛泛的重构，而是回答这些更关键的问题：“哪些东西应该提炼成共享组件？”“哪些值应该升级为 tokens？”“怎样迁移才不会把应用搞坏？”
extract 技能围绕的正是这条决策路径，而不只是“把代码清理一下”。

这个 extract 技能有什么不同

和普通那种“把这段代码做成可复用”的提示不同，extract 是从发现阶段开始的：先找到现有 Design System，检查命名方式和 token 约定，识别重复模式，判断是否真的值得抽取，再规划迁移方案。相比临时性的组件生成，它更适合 Design Systems 场景。

什么情况下 extract 特别合适

当你需要以下工作时，可以使用 extract：

• 把重复的 UI 模式收敛为共享组件
• 识别 colors、spacing、typography 等 token 候选项
• 统一同一概念下彼此不一致的不同变体
• 在已有 Design System 基础上补强，而不是从零发明一套系统
• 在批量修改很多文件之前先规划抽取方案

安装前必须知道的边界

采用 extract 的最大限制在于：它默认你的项目里可能已经存在某种 Design System 或共享 UI 结构可供扩展。如果完全没有，这个技能会明确要求你先弄清楚应该在哪里、以什么方式建立它，再继续后续工作。
如果你的目标是从零开始做一套 greenfield Design System 架构，那这个技能只能部分匹配。

如何使用 extract 技能

安装 extract 技能

通过仓库执行以下命令安装：

npx skills add pbakaus/impeccable --skill extract

安装后，当你的任务重点是提炼可复用的 UI 模式或 tokens，而不是做一次性的页面实现时，再调用它最合适。

调用 extract 之前，先准备好理想输入

extract 技能在你提供以下信息时效果最好：

• 目标区域、功能目录，或一组有重复问题的文件
• 当前 Design System 或共享 UI 库所在位置
• 正在使用的 framework 和 styling stack
• 你具体想解决的复用问题
• 任何迁移限制，比如“不要重命名 public exports”

像“把这里清理一下”这种模糊请求，会留下太多猜测空间。更好的方式是明确指出：重复模式是什么、最终要落到哪个目标系统里。

把模糊需求改写成高质量的 extract 提示

弱提示：

• “Refactor these components.”

更好的 extract 用法：

• “Use the extract skill on src/features/billing and src/features/settings to find repeated form-row and card patterns. Our shared components live in src/ui. We use React, TypeScript, and CSS modules. Prefer extracting tokens for spacing and colors only if they appear in 3+ places. Propose a migration plan before editing.”

这个提示给了技能足够的信息去完成发现、评估价值，并避免过度抽取。

extract 一开始需要先检查什么

先把技能指向这些位置：

• 疑似存在重复 UI 的区域
• 共享组件目录
• 任何 token 或 theme 文件
• 已有文档或 stories（如果有）

原始技能说明特别强调：先找到 Design System 再开始抽取。这一点非常重要，因为抽取质量取决于你是否对齐了现有的命名、目录结构、import 约定和文档模式。

面向 Design Systems 的 extract 推荐工作流

一个实用的 extract 流程通常是这样：

1. 定位当前的 Design System 或共享 UI 目录
2. 扫描目标区域中的重复组件和硬编码值
3. 按“相似模式”分组，而不是见到视觉相似就全部抽取
4. 判断哪些应该成为共享 primitive、组合组件或 token
5. 提出抽取方案
6. 谨慎迁移消费方文件

这套顺序正是这个技能的核心价值：它能减少过早抽象。

仓库里应该先看什么

这个技能本身比较轻量。优先阅读 SKILL.md，把它当作主要操作指南。最值得重点看的章节是：

• Discover
• Plan Extraction
• Extract & Enrich
• Migrate

由于这个技能目录里没有 helper scripts 或额外参考文件，真正的价值主要体现在：你是否按它的决策顺序正确执行。

extract 如何判断某样东西该不该复用

是否安装 extract，很大程度上取决于你是否认同它的偏向：不是所有东西都应该被抽取。
它最擅长处理这类情况：模式已出现多次、未来大概率还会重复、语义相对稳定，而且集中维护确实值得。
如果你的代码库里大多是一次性的营销页面布局，那这个技能的帮助会小很多。

你应该期待什么样的输出

一次表现良好的 extract 运行，通常会产出以下几类结果中的一部分或组合：

• 识别出的组件候选项
• token 候选项
• 为什么要收敛的理由
• 建议的目标 API 或命名方案
• 迁移顺序

如果输出一上来就直接改代码，却没有先确认共享资产应该放在哪里，那通常说明你的提示上下文还不够。

能显著提升 extract 效果的实用技巧

想让结果更好，可以这样做：

• 明确复用阈值，比如“只抽取使用了 3 次以上的模式”
• 指定标准目标目录
• 说明是否要保留当前 public APIs
• 要求先出方案，再动代码
• 如果代码库比较混乱，把 token 抽取和组件抽取拆开处理

这些细节会直接影响抽取方案的质量。

extract 技能的常见误用

避免把 extract 用在以下场景：

• 没有重复来源模式的全新组件发明
• 大范围视觉改版
• 在没有 stakeholder 指引的前提下，从零搭整套 Design System 架构
• 只是单文件里很小的清理，实际上不需要共享抽象

在这些情况下，普通的实现型提示往往比 extract 更快。

extract 技能 FAQ

extract 比普通提示更好吗？

在 Design Systems 场景里，很多时候是的。普通提示很容易过快走向过度抽象，或者忽略现有系统结构。真正的任务如果是找出哪些东西该集中、该怎么迁移进现有 UI 系统，那 extract 会更合适。

extract 对新手友好吗？

算是中等友好。它的工作流本身很清晰，但如果你无法识别 Design System 所在位置、token 文件或命名约定，上手会比较吃力。
如果你对前端架构还不够熟，最好直接提供明确路径，并要求技能在修改前先解释取舍。

我一定需要现有的 Design System 吗？

不一定，但 extract 技能明显是假设“它可能已经存在”，并且会要求你在创建新系统之前先确认这一点。
如果你的 repo 里没有共享 UI 层，那更适合把 extract 用在发现和规划上，而不是让它自主做架构决策。

extract 最擅长处理哪些模式？

它最擅长处理重复组件、硬编码设计值、同一 UI 概念下不一致的实现，以及可复用的组合模式。
对于那些和可复用 UI 结构无关的 business logic 重构，它的说服力就没那么强。

什么情况下不该用 extract？

如果重复代码只是表面相似、复用后反而会产生更糟糕的 API，或者模式本身还不稳定、不适合集中管理，就应该跳过 extract。
抽取会引入维护成本，所以它最适合那些复用价值长期存在的场景。

extract 只适用于组件吗？

不是。原始说明明确包括 design tokens 和可复用模式，不只是组件。也正因为如此，面向 Design Systems 的 extract 比那些只会盯着 JSX 重复的提示更实用。

如何改进 extract 技能的使用效果

给 extract 更强的架构上下文

提升 extract 输出质量最快的方法，就是补充这些信息：

• 组件库路径
• token/theme 路径
• framework 和 styling stack
• 需要保留的命名约定
• 迁移限制

没有这些上下文时，技能仍然可以识别重复，但很难把结果自然地落进你的现有系统里。

先要求发现，再进入实现

如果你想得到质量更高的结果，可以明确要求模型把 extract 分成两个阶段：

1. discovery 和 recommendation
2. approval 之后再 implementation

这样可以降低最常见的失败模式：过早抽取到错误的抽象层级。

明确设置复用阈值

最有效的改进方式之一，就是加上这类规则：

• “Only extract patterns used in 3 or more places”
• “Only create tokens for values repeated across features”
• “Do not centralize one-off layout wrappers”

这能让 extract 对齐“可维护性”目标，而不是只追求 DRY 理论上的整洁。

把组件抽取和 token 抽取分开

这两类任务相关，但并不完全相同。如果你在一个混乱的代码库里让 extract 一次同时处理两者，结果往往会混在一起。更好的提示方式是：

• 先识别共享组件
• 再识别 token 候选项
• 最后规划迁移

这样通常能得到更干净的输出，也能减少无谓的 churn。

留意 API 是否被过度泛化

extract 使用中的常见失败模式之一，是为了统一几个“差不多”的实现，造出一个 props 过多的共享组件。
如果提议出来的 API 看上去比原本那些重复代码还复杂，就应该要求技能缩小范围，或者让不同变体继续分开保留。

第一轮之后，继续提升迁移质量

拿到第一版输出后，可以继续追问这些问题：

• “Which consumers should migrate first?”
• “What breaks if we replace the old implementations?”
• “Which props or styles should stay local?”
• “Can you propose a compatibility layer?”

这一步会让 extract 不只是“发现模式”，而是真正开始帮你控制落地和采用风险。

让 extract 基于具体目标目录工作

不要只说“扫描整个 app”，而应直接指定范围，例如：

• “Use extract on src/features/checkout against src/components”
• “Review apps/web/src/account for token extraction into packages/ui/tokens”

具体的范围能提升信号质量、控制分析成本，也会让最终的 extract 方案更容易执行。

验证抽取是否真的有帮助

任何 extract 工作流里，最值得加入的一步，就是要求技能为每个提议的抽象给出理由：

• 它消除了什么重复
• 它出现了多少次
• 为什么共享 API 是稳定的
• 为什么保留本地实现会更差

这个简单检查能过滤掉那些看起来聪明、实际价值却不高的抽取方案。