Soybean Admin Skill

April 20, 2026 · View on GitHub

简介

这是一个用于在 soybean-admin-element-plus 项目，或其他 Vue 3 + Element Plus 项目中快速生成标准 CRUD 管理页面的 skill 包。

它不仅提供页面模板，还提供完整的跨项目迁移能力，可以把 Soybean 风格的 CRUD 模式迁移到任意 Vue 3 + Element Plus 项目中。目录同时兼容 SKILL.md、CLAUDE.md 和 agents/openai.yaml 三类入口。

核心能力

  • ✅ 标准 CRUD 页面生成（列表 + 搜索 + 新增 / 编辑 / 删除 / 批量删除）
  • ✅ 跨项目依赖补齐（hooks、组件、TSX、国际化、UnoCSS、图标原子类）
  • ✅ 完整的模板库（21 个模板文件）
  • ✅ 详细的参考文档（9 个规范文档）
  • ✅ 真实迁移案例（UserManage 完整演示）

文件结构

soybean-admin/
├── SKILL.md                    # 主 Skill 文件（AI 入口）
├── README.md                   # 本文件（人类阅读）
├── CLAUDE.md                   # Claude 侧固定记忆（AI 行为约束）
├── agents/
│   └── openai.yaml             # OpenAI / Codex 侧展示与默认提示
├── references/                 # 参考文档目录
│   ├── layout-and-theme.md                      # 布局与主题约束
│   ├── hooks-and-conventions.md                 # Hooks 与项目约定
│   ├── crud-page-pattern.md                     # 标准 CRUD 页面模式
│   ├── search-form-pattern.md                   # 搜索区模式
│   ├── drawer-form-pattern.md                   # 抽屉表单模式
│   ├── dependency-bootstrap.md                  # 依赖补齐策略
│   ├── engineering-capability-bootstrap.md      # 工程能力补齐指南
│   ├── cross-project-adoption-playbook.md       # 跨项目落地演练手册
│   └── user-manage-migration-case.md            # UserManage 真实迁移案例
└── assets/                     # 模板文件目录
    ├── list-page.vue.tpl                        # 列表页入口骨架
    ├── search-card.vue.tpl                      # 搜索卡片骨架
    ├── operate-drawer.vue.tpl                   # 新增/编辑抽屉骨架
    ├── table-support.ts.tpl                     # 表格 hooks 模板
    ├── form-support.ts.tpl                      # 表单 hooks 模板
    ├── table-header-operation.vue.tpl           # 表头操作组件模板
    ├── request-client.ts.tpl                    # 最小请求层模板
    ├── service-api-index.ts.tpl                 # 服务层统一出口模板
    ├── option-utils.ts.tpl                      # 选项翻译工具模板
    ├── business-constants.ts.tpl                # 业务常量模板
    ├── message-adapter.ts.tpl                   # 消息适配层模板
    ├── i18n-setup.ts.tpl                        # 国际化初始化模板
    ├── page-locale.zh-cn.ts.tpl                 # 中文 locale 模板
    ├── page-locale.en-us.ts.tpl                 # 英文 locale 模板
    ├── vite-vue-jsx.snippet.ts.tpl              # Vite JSX 配置片段（图标类由 Uno presetIcons 提供）
    ├── uno-config.ts.tpl                        # UnoCSS 配置模板
    ├── main-bootstrap.snippet.ts.tpl            # 入口文件引导代码片段
    ├── target-project-manifest.md.tpl           # 目标项目补件清单模板
    ├── route-record.snippet.ts.tpl              # 路由注册片段
    ├── system-manage-service.ts.tpl             # 系统管理服务层骨架
    └── system-manage-types.d.ts.tpl             # 系统管理类型骨架

快速开始

场景 1：在原生 Soybean 项目中使用

如果你的项目已经是 soybean-admin-element-plus，直接告诉 AI：

请按 soybean 风格创建一个用户管理页面

AI 会自动：

  1. 识别项目特征
  2. 复用现有 hooks 和组件
  3. 生成标准 CRUD 页面

场景 2：在其他 Vue 3 + Element Plus 项目中使用

如果你的项目只有 Vue 3 + Element Plus，告诉 AI：

我想在这个项目中按 soybean 风格创建用户管理页面，
项目目前只有 Vue 3 + Element Plus

AI 会自动：

  1. 检测缺失的依赖
  2. 按顺序补齐基础设施
  3. 生成业务页面

参考文档阅读指南

首次使用（原生 Soybean 项目）

推荐阅读顺序：

  1. layout-and-theme.md - 了解布局约束和主题系统
  2. hooks-and-conventions.md - 了解 hooks 用法和项目约定
  3. crud-page-pattern.md - 了解标准 CRUD 页面模式
  4. search-form-pattern.md - 了解搜索区的组织方式
  5. drawer-form-pattern.md - 了解抽屉表单的实现模式

跨项目迁移（非 Soybean 项目）

推荐阅读顺序：

  1. dependency-bootstrap.md - 了解依赖分级策略（必读）
  2. engineering-capability-bootstrap.md - 了解如何补齐 TSX/国际化/UnoCSS
  3. cross-project-adoption-playbook.md - 了解完整的 10 步落地流程
  4. user-manage-migration-case.md - 通过真实案例理解迁移过程
  5. 再回到"首次使用"的阅读顺序

核心设计理念

1. 不是让 AI 适应目标项目，而是让目标项目先具备承接能力

当目标项目缺少 Soybean 的基础设施时，默认策略是先补齐依赖，而不是降级实现。

2. 依赖分级：一类（页面结构）+ 二类（工程表达）

  • 一类依赖：表格 hooks、表单 hooks、公共组件（决定页面组织方式）
  • 二类依赖：TSX/JSX、国际化、UnoCSS（决定代码表达方式）

3. 按需读取参考文档，避免全量加载

AI 不会一次性加载所有文档，而是根据任务类型按需读取，节省 token。

4. 模板 + 参考文档双轨制

  • 模板：快速起页，提供可直接复制的代码骨架
  • 参考文档：深度理解，提供设计思路和最佳实践

使用限制

以下情况不适合使用这个 skill：

  1. 页面是营销官网、着陆页或强视觉设计页
  2. 页面不是 CRUD 管理台，而是图表大屏、流程编排器、复杂画布编辑器
  3. 用户明确要求使用新的组件体系或完全不同的交互范式
  4. 用户明确拒绝补齐依赖，且接受实现方式的差异

常见问题

Q1: 我的项目没有 UnoCSS，能用这个 skill 吗？

A: 可以。AI 会先补齐 UnoCSS、presetIcons 和 @iconify-json/ic 这一组能力，再生成页面。如果你明确拒绝接入这些依赖，AI 只能借鉴参考文档思路，不能直接复用模板代码。

Q2: 补齐依赖会不会改动很多文件？

A: 补齐依赖是增量式的，不会破坏现有代码。通常只需要：

  • 安装几个 npm 包
  • 新增几个配置文件
  • 修改入口文件（main.ts）挂载插件
  • 补一个统一请求层和公共组件

Q3: 我只想生成一个简单的列表页，不想补那么多东西

A: 如果你明确告诉 AI"不要补依赖，用最简单的方式实现"，AI 会尊重你的选择。但这样生成的代码可能与项目现有风格不一致。

Q4: 这个 skill 支持哪些 UI 框架？

A: 目前只支持 Element Plus。如果你使用其他 UI 框架（Ant Design Vue、Naive UI 等），可以借鉴参考文档的设计思路，但模板代码无法直接使用。

贡献指南

如果你发现文档或模板有问题，欢迎提出改进建议：

  1. 模板代码问题 → 修改 assets/*.tpl 文件
  2. 规范文档问题 → 修改 references/*.md 文件
  3. AI 行为问题 → 修改 SKILL.md 或 CLAUDE.md

说明

当前目录没有单独附带 LICENSE 文件。如需单独开源或分发，请按仓库整体许可策略补充许可证声明。