vue-harvest

vue-harvest

将它指向一个 Vue 项目。它会查找所有组件，判断哪些组件可以复用，并将其提取出来。它还会提取设计令牌（颜色、间距、字体排版），并提供可视化报告。

对于需要判断的复杂情况（与状态库耦合的组件、依赖关系不明确的组件），由 MCP 服务处理，并向大模型提供结构化分析数据。

功能

组件提取。 使用 @vue/compiler-sfc 解析项目中的每个 .vue 文件。对于每个组件，它都会提取完整接口（props、emits、slots）、梳理依赖关系图、检测耦合问题，并评估安全提取的置信度。置信度高于阈值的组件会自动提取为独立包，其中包含重写后的导入语句和对等依赖清单。

设计令牌提取。 扫描所有 CSS（scoped 样式、独立样式表），并提取颜色、字体系列、字号、字重、间距值、边框圆角和阴影。输出 CSS 自定义属性文件、JSON 数据，以及展示色板和比例的可视化 HTML 浏览器。

MCP 服务。 提供 12 个工具，为大模型提供结构化数据，以便分析更复杂的情况：置信度为 30% 至 70%、经过一些重构后可能可以提取的组件。大模型可以深入分析耦合情况、生成包含修改前后代码的解耦建议、为绑定状态库的组件创建组合式封装，并一次性完成完整的重写和提取。

安装

npm install -g vue-harvest

# or run directly
npx vue-harvest analyze ./my-app

安装 MCP 服务：

npm install -g vue-harvest-mcp

命令行界面

vue-harvest analyze [path]

完整的分析流程。查找 .vue 文件、解析接口、构建依赖关系图、对每个组件进行分类、自动提取安全的组件，并生成注册表和目录。

vue-harvest analyze
vue-harvest analyze ./path/to/project
vue-harvest analyze --threshold 60
vue-harvest analyze --output ./harvested
vue-harvest analyze --json | jq '.summary'

默认将输出写入 .vue-harvest/：

.vue-harvest/
  registry.json       Component registry (shadcn-compatible format)
  catalog.html        Browsable catalog with tier filters
  analysis.json       Full analysis dump for the MCP server
  SUMMARY.md          Human-readable report
  components/         Extracted component bundles
    Button/
      Button.vue
      manifest.json
    Card/
      Card.vue
      manifest.json

vue-harvest list [path]

按提取置信度排序，列出所有组件。

vue-harvest list
vue-harvest list --tier primitive
vue-harvest list --json

vue-harvest inspect <name>

全面分析单个组件：props、事件、插槽、依赖关系、耦合问题和样式分析。

vue-harvest inspect Button
vue-harvest inspect UserProfileCard --json

vue-harvest extract <name>

将指定组件及其所有本地依赖提取为独立包。

vue-harvest extract Button
vue-harvest extract UserProfileCard --force
vue-harvest extract Card --output ./my-components

vue-harvest tokens [path]

从项目中提取设计系统令牌。

vue-harvest tokens
vue-harvest tokens --json
vue-harvest tokens --output ./design-system

输出：

• 包含 CSS 自定义属性的 tokens.css
• 包含完整令牌数据集的 tokens.json
• 包含可视化浏览器（颜色色板、字体比例、间距可视化）的 design-system.html

vue-harvest init

创建包含检测到的项目设置的 harvest.config.json。

配置

可选。在项目根目录中放置 harvest.config.json：

{
  "include": ["**/*.vue"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "**/*.test.*",
    "**/*.story.*"
  ],
  "extractionThreshold": 70,
  "outDir": ".vue-harvest",
  "registry": "json"
}

会自动从 tsconfig.json 检测路径别名。如果项目将 @ 映射到 ./src，vue-harvest 会自动识别。

组件分类

系统会根据每个组件的接口、依赖关系和耦合情况，将其归类到一个可复用性层级：

层级	置信度	含义
基础组件	85-100%	纯 UI，不含业务逻辑。例如 Button、Input、Card。
复合组件	70-85%	由基础组件构建，逻辑很少。例如 FormField、DataTable。
功能组件	50-70%	包含业务逻辑，但可能可以复用。例如 UserAvatar、SearchBar。
页面绑定组件	30-50%	与特定页面或路由紧密耦合。
应用专属组件	0-30%	与应用状态深度耦合，无法直接复用。

置信度达到或超过提取阈值（默认为 70%）的组件会自动提取。MCP 服务主要处理 30% 至 70% 的组件。

耦合问题

分析器会检测以下耦合模式：

问题	严重程度	描述
direct-store-access	warning	直接导入 Pinia/Vuex store
hardcoded-api	warning	包含硬编码的 API 端点 URL
router-dependency	info	使用 vue-router
i18n-dependency	warning	使用 vue-i18n
global-inject	warning	使用 inject() 获取应用级 provide
env-variable	warning	引用了 import.meta.env
unscoped-css	warning	包含会泄漏到全局的非作用域样式
deep-provide-chain	warning	依赖 provide/inject 链
implicit-global	warning	使用了全局注册但未导入的组件
side-effect-import	warning	包含会执行副作用的导入

MCP 服务

使用 Claude Desktop 设置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "vue-harvest": {
      "command": "vue-harvest-mcp"
    }
  }
}

使用 Claude Code 设置

claude mcp add vue-harvest vue-harvest-mcp

可用工具

工具	功能
analyze-project	对项目路径运行完整流程
list-components	按筛选条件（层级、置信度范围）列出组件
inspect-component	使用源代码进行完整分析
extract-component	提取组件，可强制执行
deep-analyze	为大模型推理提供结构化耦合分析
suggest-refactor	提供解耦前后的代码
generate-wrapper	为绑定 store 的组件创建组合式包装器
adapt-and-extract	一步完成完整重写和提取
batch-triage	对所有可审查组件排序并估算工作量
coupling-report	汇总项目范围内的耦合模式
analyze-design-system	提取设计令牌
get-design-tokens	返回按类型筛选的设计令牌

资源

分析后，服务会将以下内容作为 MCP 资源公开：

• harvest://registry：完整的注册表 JSON
• harvest://graph：依赖关系图
• harvest://summary：分析摘要
• harvest://component/{name}：单个组件的分析结果
• harvest://design-system：提取的设计令牌

提示词

• analyze-new-project：引导首次分析
• extraction-sprint：批量重构和提取会话
• refactor-component：对单个组件进行深度重构
• extract-design-system：设计令牌提取和分析

对话示例

“分析我位于 /Users/me/projects/my-app 的 Vue 项目”

“显示所有需要审查的组件”

“深入分析 UserProfileCard 组件，并建议如何将它与 auth store 解耦”

“进行一次提取冲刺，逐一检查所有可审查组件，并提取可提取的内容”

“提取设计系统令牌，并推荐一种命名规范”

编程 API

vue-harvest 导出其分析引擎，供其他工具使用：

import { analyze, writeOutput, analyzeTokens } from 'vue-harvest'

const report = await analyze('./my-vue-app', {
  extractionThreshold: 0.6,
})

console.log(report.summary)
// { totalFiles: 42, analyzed: 40, autoExtracted: 12, needsMCP: 8, ... }

await writeOutput(report)

// Design tokens
const tokens = await analyzeTokens('./my-vue-app')
console.log(tokens.palette)    // [{ hex: '#3b82f6', usageCount: 14 }, ...]
console.log(tokens.spacing)    // ['4px', '8px', '12px', '16px', '24px']

架构

vue-harvest (monorepo)
  packages/
    cli/                        Published as "vue-harvest" on npm
      src/
        types.ts                Type system shared across the whole project
        index.ts                Pipeline orchestrator
        cli.ts                  CLI entry point (citty)
        analyzers/
          sfc-analyzer.ts       SFC parsing, interface extraction, coupling detection
          graph-builder.ts      Dependency graph with Tarjan's SCC for cycle detection
          design-system-analyzer.ts   Token extraction from CSS
        extractors/
          component-extractor.ts   Import rewriting, file bundling, manifest generation
        generators/
          registry.ts           Registry JSON + catalog HTML generation
        commands/               CLI command definitions
        utils/
          config.ts             Config resolution, alias detection from tsconfig
      tests/
        fixtures/               A real mini Vue project used as test input
        unit/                   66 tests across 5 suites

    mcp/                        Published as "vue-harvest-mcp" on npm
      src/
        index.ts                MCP server (12 tools, resources, prompts)

将 CLI 与 MCP 分开是有意为之。CLI 负责所有确定性的工作：解析、构建图、分类和提取。MCP 负责需要推理的 20% 工作：解耦建议、重构代码生成和歧义消解。

开发

git clone https://github.com/virgilvox/vue-harvest.git
cd vue-harvest
pnpm install
pnpm build
pnpm test

CLI 的监视模式：

pnpm --filter vue-harvest dev

运行指定的测试文件：

npx vitest run packages/cli/tests/unit/sfc-analyzer.test.ts

内部工作原理

1. 发现。 使用 glob 查找 .vue 文件，并读取 tsconfig.json 中的路径别名。
2. SFC 解析。 @vue/compiler-sfc 将每个文件拆分为模板、脚本和样式块。
3. 接口提取。 基于正则表达式提取 defineProps、defineEmits 和 <slot> 标签。支持泛型类型语法、withDefaults 以及包含嵌套选项的对象语法。
4. 依赖分析。 es-module-lexer 解析导入语句。每个导入项都会按类型分类（内部组件、组合式函数、store、工具、外部包等）。
5. 耦合检测。 对脚本和模板 AST 进行模式匹配，以检测 store 访问、硬编码 API、路由器使用、i18n、inject、环境变量和未限定作用域的 CSS。
6. 分类。 置信度评分从 1.0 开始，并根据耦合问题、store 访问和页面路径模式扣分。存在 props/插槽接口和 UI 路径模式时则加分。
7. 构建图。 解析导入路径、构建邻接表、运行 Tarjan 强连通分量算法来检测循环，并计算传递依赖闭包。
8. 提取。 对于分数高于阈值的组件：收集组件及其所有本地依赖（组合式函数、工具、类型、样式），将导入路径改写为提取后的包内相对路径，并生成列出对等依赖和所需全局项的清单。
9. Token 提取。 PostCSS 值解析器从 CSS 声明中识别颜色（hex、rgb、hsl）、字体属性、间距值、圆角和阴影。对结果去重、规范化 hex 值，并按类型分组。

许可证

MIT