@es-plus/cli

@es-plus/cli

@es-plus/vue3 / @es-plus/vue2 官方命令行工具 —— 用自然语言生成 CRUD 页面，校验 JSON 配置，快速搭建页面脚手架。同一份配置可生成 Vue 3 或 Vue 2 版本代码。

安装

# 方式一：npx 直接运行（无需安装）
npx @es-plus/cli create user-management

# 方式二：全局安装
npm install -g @es-plus/cli

# 方式三：项目内安装
npm install -D @es-plus/cli

安装后，终端可直接使用 es-plus 命令。

环境要求： Node.js >= 18，npm >= 8

命令总览

create — 生成 CRUD 页面

从自然语言描述生成完整的 Vue 3 CRUD 页面（.vue SFC），包含查询表单、数据表格、新增/编辑弹窗、删除确认。

基本用法

# 交互式 — 引导选择预设或输入描述
es-plus create user-management

# 非交互式 — 直接传入描述
es-plus create user-management \
  -d "用户管理，查询姓名、手机号、状态，表格显示姓名、手机号、邮箱、状态、创建时间，支持新增编辑删除"

# 指定输出路径
es-plus create user-management \
  -d "用户管理，查询姓名、手机号、状态，表格显示姓名、手机号、邮箱、状态、创建时间，支持新增编辑删除" \
  -o ./src/views/system/UserManagement.vue

参数说明

生成路径（准确率从高到低）

1. --from-config <path> — 你已有结构化配置时，直接确定性生成，编译由构造保证。最稳。
2. --ai — 由 LLM 阅读自然语言、按类型逐字段推理出 StructuredCrudConfig（进程内 Zod 校验 + 自修复闭环 ≤2 次），再喂给同一个确定性生成器。需要 @anthropic-ai/sdk（可选依赖，npm i -D @anthropic-ai/sdk）与 ANTHROPIC_API_KEY。
3. 内置生成器（兜底） — 无 key / 未装 SDK / --no-ai 时的正则关键词解析，准确率受关键词覆盖度限制。当 --ai 路径不可用或失败时会自动降级到这里，并打印实际走了哪条路。

# 配置驱动（最稳）
es-plus create user-management --from-config ./user.config.json -o ./src/views/user

# LLM 推理（需要 key）；不可用时自动降级到内置生成器
ANTHROPIC_API_KEY=sk-... es-plus create user-management \
  -d "用户管理，查询姓名、手机号、状态，表格显示姓名、头像、状态、创建时间，支持新增编辑删除" --ai

# 强制走内置生成器（即使设置了 key）
es-plus create user-management -d "..." --no-ai

交互流程

$ es-plus create order-list

? 选择预设或自定义描述
  ❯ 自定义描述
    用户管理
    订单列表
    商品管理
    日志查询
    角色权限
    员工花名册
    文章管理
    系统配置

? 请描述页面功能: 订单列表，查询订单号、客户名称、日期范围、状态，
  表格显示订单号、客户、金额、状态、创建时间，支持查看详情和删除

? 输出路径: ./src/views/OrderList.vue

⏳ 正在生成...

✔ 已生成: ./src/views/OrderList.vue
  Generated CRUD page with:
  - 4 query form fields
  - 6 table columns (including actions)
  - Actions: view, delete
  - Dialog form with 5 fields and validation
  - Status column with ElTag render
  - Delete with confirmation dialog

描述技巧

描述越明确，生成代码越精确。格式：页面名称 + 查询字段 + 表格字段 + 操作类型

# ✅ 好 — 明确分段
"用户管理页面，
 查询条件有姓名、手机号、状态，
 表格显示姓名、手机号、邮箱、状态、创建时间，
 支持新增编辑删除"

# ✅ 好 — 简洁罗列（自动推断查询和表格共用）
"员工管理：姓名、部门、职位、手机号、状态"

# ✅ 好 — 只读列表
"操作日志查询，查询关键词、级别、日期范围，表格显示时间、级别、操作人、内容，只查看"

# ❌ 差 — 太模糊
"做一个管理页面"

关键词智能识别

引擎根据字段名自动推断控件类型：

操作类型识别

在描述中用"支持 XXX"指定操作：

8 个内置预设

validate — 校验配置

校验 JSON 配置文件是否符合 es-plus 组件的 Schema 规范（@es-plus/vue3 与 @es-plus/vue2 共用同一份 Schema）。

基本用法

# 指定 schema 类型
es-plus validate ./config/form-items.json --schema form-item

# 自动检测 schema 类型
es-plus validate ./config/table-options.json

参数说明

支持的 Schema 类型

自动检测规则

不指定 --schema 时，根据 JSON 内容自动判断：

输出示例

校验通过：

✔ 校验通过 (schema: form-item)

校验失败：

✗ 校验失败（2 个错误）:
  (root): must have required property 'prop'
  /formtype: must be equal to one of the allowed values

建议:
  - Add missing property "prop"
  - Valid values for /formtype: Input, Select, datePicker, timePicker,
    Slider, ColorPicker, Transfer, Cascader, Radio, Checkbox, Switch, Rate, Upload

可用 schema: form-item, table-column, table-options, dialog-options

配合 CI 使用

# .github/workflows/validate.yml
- name: Validate es-plus configs
  run: |
    npx @es-plus/cli validate ./src/configs/user-form.json --schema form-item
    npx @es-plus/cli validate ./src/configs/table-options.json --schema table-options

scaffold — 生成脚手架

生成最小化的 es-plus 页面模板，适合需要手动编写配置的场景。

基本用法

# 默认：查询 + 表格
es-plus scaffold user-list

# 查询 + 表格 + 弹窗
es-plus scaffold user-management --features query,table,dialog

# 只有表格
es-plus scaffold data-view --features table

# 指定输出路径
es-plus scaffold report -o ./src/views/report/Index.vue

参数说明

可用 features

生成结果

<template>
  <div class="user-list-page">
    <es-table ref="tableRef" :columns="columns" :options="options"
      v-model:data-source="tableData" v-model:pagination="pagination">
      <es-form :model="queryForm" :form-item-list="formItems" :config-btn="queryBtns" />
    </es-table>
  </div>
</template>

<script setup>
import { reactive, ref } from 'vue'

const queryForm = reactive({})
const formItems = []
const queryBtns = [
  { name: '查询', type: 'primary', key: 'query', triggerEvent: true },
  { name: '重置', key: 'rest', triggerEvent: true },
]

const tableRef = ref(null)
const tableData = ref([])
const pagination = ref({ current: 1, pageSize: 10, total: 0 })
const columns = []
const options = {
  border: true,
  stripe: true,
  highlightCurrentRow: true,
  headerCellStyle: { background: '#f5f7fa' },
  httpRequest: async (params) => {
    // TODO: 替换为实际接口调用
  },
  configTableOut: { total: 'total', tableData: 'data', pageSize: 'pageSize', current: 'pageIndex' },
}
</script>

生成代码说明

生成的代码是完整可运行的 Vue 3 SFC，通常只需修改以下部分：

1. 替换接口地址

// 修改 options 中的 httpRequest
const options = {
  httpRequest: async (params) => {
    const res = await axios.get('/api/user/list', { params: params.formParams })
    return res.data
  },
  configTableOut: {
    total: 'total',       // 总条数字段名
    tableData: 'records', // 列表数据字段名（根据实际接口调整）
    pageSize: 'pageSize',
    current: 'pageIndex'
  }
}

2. 替换删除接口

function handleDelete(row) {
  ElMessageBox.confirm('确定删除该条数据吗？', '提示', { type: 'warning' })
    .then(async () => {
      await axios.delete(`/api/user/${row.id}`)  // 替换为实际接口
      ElMessage.success('删除成功')
      tableRef.value?.httpRequestInstance()
    })
}

3. 替换保存接口

// openForm 函数中的确定按钮
click: async (_, { close, getRefs }) => {
  try {
    await getRefs('form')?.validate()
    await axios.post('/api/user/save', formData)  // 替换为实际接口
    close()
    tableRef.value?.httpRequestInstance()
  } catch { /* 表单验证失败 */ }
}

4. 调整 Select 选项数据

// 默认生成的是占位选项，替换为实际数据或从接口获取
{ prop: 'status', label: '状态', formtype: 'Select',
  dataOptions: [{ label: '启用', value: 1 }, { label: '禁用', value: 0 }] }

与 @es-plus/mcp-server 的区别

推荐组合： 项目初始化用 CLI 批量生成 → 日常迭代用 MCP Server 让 AI 辅助修改。

常见问题

Q: 支持 TypeScript 吗？

生成的是 <script setup> 格式（JavaScript）。如需 TypeScript，将 <script setup> 改为 <script setup lang="ts"> 并添加类型注解即可。

Q: 生成的代码依赖什么？

Vue 3 目标 (--target vue3，默认)：

• vue >= 3.3
• @es-plus/vue3 — 提供 EsForm、EsTable、useDialog
• element-plus — 提供 ElTag、ElMessageBox、ElMessage 等

Vue 2 目标 (--target vue2)：

• vue ^2.6.14（2.6 还需 @vue/composition-api）
• @es-plus/vue2 — 提供 EsForm、EsTable、useDialog
• element-ui — 提供 Tag、MessageBox、Message 等

Q: Windows 下 npx 报错？

确保使用 PowerShell 或 Git Bash，Node.js >= 18：

npx @es-plus/cli create user-management

相关链接

• @es-plus/vue3 组件库 (Vue 3 + Element Plus)
• @es-plus/vue2 组件库 (Vue 2 + Element UI)
• @es-plus/core 框架无关核心
• @es-plus/mcp-server AI 集成
• GitHub 仓库

License

MIT