core-smith

English | 中文

什么是 CoreSmith

CoreSmith 是一个 Agent Skill（智能体技能），能将 Vue3 + TypeScript 单体项目自动改造为 Monorepo 核心包架构。它将共享模块提取到 packages/core，脚手架生成 apps/base-app 完整 Vue3 应用，并支持创建从核心包导入的定制化应用项目。

整个工具运行 4 阶段流水线 —— 扫描、确认、提取、创建 —— 每个阶段都是独立的子技能，拥有专属斜杠命令，让你精确控制改造过程。

快速开始

第一步：安装

三种安装方式任选其一：

| 方式 | 命令 | 适用场景 | | --- | --- | --- | | 插件安装 (Claude Code) | npx agent-skill add core-smith | Claude Code 用户 | | NPM 全局安装 | npm install -g core-smith-skill | 跨平台，自动更新 | | 手动安装 | git clone + 复制 skills/ 到助手配置目录 | 自定义配置，离线环境 |

第二步：进入你的 Vue3 项目

cd /path/to/your-vue3-project

第三步：运行流水线

/cs:scan             # 阶段 1：扫描项目结构，检测配置
/cs:confirm          # 阶段 2：查看扫描结果，配置提取选项
/cs:extract          # 阶段 3：从项目中提取核心包
/cs:create my-app    # 阶段 4：创建从核心包导入的定制化应用
/cs:help             # 查看详细使用说明

也可以直接用自然语言说 "把我的 Vue3 项目提取为核心包" —— 智能体会自动串联所有阶段。

工作原理

CoreSmith 通过 4 阶段流水线改造你的 Vue3 单体项目：

阶段 1：扫描           阶段 2：确认             阶段 3：提取               阶段 4：创建
+----------------+    +------------------+    +--------------------+    +-------------------+
| 检测项目结构、   | -> | 展示检测结果，   | -> | 将确认的目录拷贝   | -> | 脚手架生成定制化  |
| UI 框架、路由、  |    | 选择要提取到     |    | 到 packages/core， |    | 应用，从核心包    |
| 别名等配置       |    | 核心包的目录     |    | 重写 import 路径   |    | 导入共享模块      |
+----------------+    +------------------+    +--------------------+    +-------------------+

阶段 1：扫描（/cs:scan）

分析项目并检测：

• 源码目录 —— composables/、stores/、utils/、types/、api/ 等
• UI 框架 —— Element Plus、Ant Design Vue、Naive UI、Vant、Arco Design
• 路由类型 —— 静态 / 动态 / 混合（基于关键词检测）
• 路径别名 —— @/、~/src 或 tsconfig/vite.config 中的自定义模式
• 包管理器 —— pnpm、npm 或 yarn

输出：包含所有扫描结果的 state.json。

阶段 2：确认（/cs:confirm）

纯对话交互 —— 不写入文件。你审查扫描结果并决定：

• 哪些目录纳入核心包
• 核心包名称（默认：@<项目名>/core）
• 确认路由类型

阶段 3：提取（/cs:extract）

创建 packages/core/，包含：

• 从 src/ 拷贝已确认的源文件（原始文件保留不动）
• 重写 import 路径（@/composables/foo → @my-core/composables/foo）
• 路由调整为导出 baseRoutes 数组（非 router 实例）
• package.json 含 peerDependencies，vite.config.ts 库模式构建（ESM+CJS）
• apps/base-app/ 完整 Vue3 应用，从 core 导入
• pnpm-workspace.yaml Monorepo 工作区配置

阶段 4：创建（/cs:create <名称>）

脚手架生成 apps/<名称>/，包含：

• 动态 package.json —— UI 框架和别名跟随基础版
• router/index.ts —— 从 core 导入 baseRoutes，预留 extraRoutes 占位
• main.ts —— 按需包含 Pinia
• App.vue —— 纯骨架，仅含 <router-view />
• 空 views/ 目录 + .gitkeep，用于放置定制页面

生成结果

改造前（单体项目）：

my-vue-app/
├── src/
│   ├── api/               API 模块
│   ├── composables/       共享组合式函数
│   ├── types/             TypeScript 类型定义
│   ├── utils/             工具函数
│   ├── router/            Vue Router 配置
│   ├── views/             页面组件
│   ├── components/        UI 组件
│   ├── App.vue
│   └── main.ts
├── vite.config.ts
└── package.json

改造后（Monorepo）：

my-vue-app/
├── packages/
│   └── core/                    提取的共享模块
│       ├── src/
│       │   ├── api/
│       │   ├── composables/
│       │   ├── types/
│       │   ├── utils/
│       │   ├── router/          导出 baseRoutes 数组
│       │   └── index.ts         聚合导出
│       ├── package.json         @my-vue-app/core
│       └── vite.config.ts       库模式（ESM+CJS）
├── apps/
│   ├── base-app/                原始应用，现从 core 导入
│   │   ├── src/
│   │   ├── package.json
│   │   └── vite.config.ts
│   └── my-app/                  通过 /cs:create 创建的定制应用
│       ├── src/
│       │   ├── views/           在此放置定制页面
│       │   ├── router/          导入 baseRoutes + extraRoutes
│       │   ├── App.vue
│       │   └── main.ts
│       ├── package.json         @my-vue-app/my-app
│       └── vite.config.ts
├── pnpm-workspace.yaml          packages/* + apps/*
└── package.json                 根工作区配置

架构

CoreSmith 遵循 三层架构：

第一层：插件清单（平台集成）
  .claude-plugin/plugin.json  →  Claude Code
  gemini-extension.json       →  Gemini
  package.json                →  NPM 分发

第二层：技能 + 命令路由
  skills/<name>/SKILL.md      →  规范技能（唯一真实来源）
  .claude/skills/<name>/      →  平台指针（@include → 规范技能）
  .claude/commands/cs/*.md    →  斜杠命令路由

第三层：CLI 执行引擎
  skills/scripts/cli.mjs      →  Node.js CLI（子命令模式）
    ├── lib/state.mjs          状态管理（state.json 读写）
    ├── lib/analyzer.mjs       阶段 1：项目扫描
    ├── lib/extractor.mjs      阶段 3：核心包提取
    └── lib/creator.mjs        阶段 4：定制应用脚手架

支持平台

| 平台 | 技能 | 命令 | 安装方式 | | --- | :----: | :------: | --- | | Claude Code | ✅ | ✅ /cs:* | 插件安装 | | Cursor | ✅ | ✅ /cs:* | 手动安装 | | Codex | ✅ | ✅ /cs:* | 手动安装 | | Qoder | ✅ | ✅ /cs:* | 手动安装 | | OpenCode | ✅ | ✅ /cs:* | 手动安装 | | Gemini CLI | ✅ | -- | 手动安装 | | Kimi | ✅ | -- | 手动安装 | | Trae | ✅ | -- | 手动安装 | | GitHub Copilot | ✅ | -- | 手动安装 |

环境要求

• Node.js >= 18
• pnpm（推荐）或 npm/yarn
• Vue 3 + TypeScript 项目作为输入
• AI 编程助手（Claude Code、Cursor、Codex 等）

常见问题

CoreSmith 会修改我的原始源文件吗？ 不会。提取阶段将文件拷贝到 packages/core/ 并创建 apps/base-app/。你的原始 src/ 目录会完整保留，直到你决定删除。

可以创建多个定制应用吗？ 可以。多次运行 /cs:create <名称> 即可。每个应用在 apps/<名称>/ 下，都从共享的 packages/core 导入。

如果项目用了 Pinia / Vue Router / Element Plus？ CoreSmith 在扫描阶段会自动检测，核心包配置和定制应用脚手架都会包含这些依赖。

必须用 pnpm 吗？ CoreSmith 生成 pnpm-workspace.yaml 作为 Monorepo 配置。推荐使用 pnpm，但 npm workspaces 也可以通过小幅调整使用。

会影响已有的 Git 历史吗？ 不会。CoreSmith 生成的文件都是新增，不会修改 Git 历史。你可以在提交前审查 diff。

能在已有的 Monorepo 上使用吗？ CoreSmith 设计用于改造单体 Vue3 项目，不建议在已有 Monorepo 上运行。

文档

• 使用指南 —— 详细用法、示例和 CLI 参考

许可证

MIT