AI 编程 Skill 使用教程

本教程介绍 Forge Admin 项目内置的 AI 编程 Skill 体系，帮助你利用 AI 编程助手（如 Claude Code、Cursor、OpenClaw 等）高效完成业务开发。涵盖 CRUD 代码生成和业务流程开发两大核心 Skill。

一、Skill 体系总览

Forge Admin 在 .agents/skills/ 目录下内置了三个 AI 编程 Skill，为 AI 编程助手提供项目特定的开发规范和代码生成模板：

.agents/skills/
├── forge-codegen-crud/              ← 简单业务 CRUD 代码生成
│   ├── SKILL.md                     ← Skill 主文件（规范+流程）
│   └── references/                  ← 详细参考文档
│       ├── single-table-crud.md     ← 单表 CRUD 代码模板
│       ├── sql-seeds.md             ← SQL 种子数据模板
│       └── validation-checklist.md  ← 验证清单
├── forge-business-flow-development/ ← 业务流程开发
│   ├── SKILL.md                     ← Skill 主文件（规范+流程）
│   └── references/                  ← 详细参考文档
│       ├── code-first-workflow.md   ← 代码优先工作流
│       ├── lowcode-workflow.md      ← 低代码工作流
│       ├── purchase-order-reference.md ← 采购单示例
│       ├── status-and-callbacks.md  ← 状态机与回调
│       ├── bpmn-configuration.md    ← BPMN 节点配置
│       ├── sql-templates.md         ← SQL 模板
│       └── validation-checklist.md  ← 验证清单
└── ui-ux-pro-max/                   ← UI/UX 设计智能
    ├── SKILL.md                     ← Skill 主文件
    └── scripts/                     ← 设计系统搜索工具

什么是 Skill？

Skill 是一组结构化的开发规范文档，告诉 AI 编程助手：

项目约定：包名结构、命名规范、技术选型
代码模板：Entity、Controller、Service、Mapper、Vue 页面的标准写法
SQL 规范：Flyway 迁移脚本、字典种子、菜单权限种子
验证清单：生成代码后的检查项
禁止事项：不可违反的红线规则

Skill vs 普通文档

对比项	普通文档	Skill
阅读对象	人类开发者	AI 编程助手
结构	自由格式	YAML front matter + 结构化 Markdown
触发方式	手动查阅	AI 根据任务自动匹配
内容	概念说明	规范 + 模板 + 红线 + 验证清单
引用	链接跳转	AI 按需加载 references 子文档

支持的 AI 编程助手

工具	兼容性	说明
Claude Code (Anthropic)	✅ 原生支持	自动读取 `.agents/skills/` 目录
Cursor	✅ 支持	通过 `.cursorrules` 或手动引用
OpenClaw	✅ 支持	自动读取 skill 列表
GitHub Copilot Chat	⚠️ 需手动引用	在对话中粘贴 SKILL.md 内容
Windsurf / 其他	⚠️ 需手动引用	将 SKILL.md 作为上下文提供

二、forge-codegen-crud — 简单业务 CRUD 代码生成

2.1 适用场景

当你需要开发一个不涉及审批流程的简单业务管理页面时使用，例如：

物料管理（单表增删改查）
供应商管理（主子表）
仓库管理（单表 + 树形）
任何标准 CRUD 模块

2.2 Skill 核心规范

红线规则（Non-Negotiables）

规则	说明	原因
使用 Flyway 脚本	所有 DDL 和内置数据通过 `forge/db/migration/`	保证数据库版本可控
租户 ID = 1	所有内置数据使用 `tenant_id = 1`	项目不支持 tenant_id=0
查询 SQL 放 Mapper XML	禁止 Service 层 LambdaQueryWrapper 查询链	项目规范，便于 SQL 优化
POST 安全路由	detail/create/update/delete 全部用 POST	网关和安全策略要求
使用字典组件	`DictSelect`、`DictTag`、`useDict()`	禁止前端硬编码选项
AiCrudPage	前端页面使用 AiCrudPage 组件	配置式开发，不手写 CRUD

生成的 CRUD 接口契约

操作	HTTP 方法	路径	说明
分页查询	GET	`/page`	列表分页
详情查询	POST	`/getById`	用 @RequestParam 接收 id
新增	POST	`/add`	@RequestBody DTO
修改	POST	`/edit`	@RequestBody DTO
删除	POST	`/remove/{id}`	@PathVariable
批量删除	POST	`/removeBatch`	@RequestBody Long[]

⚠️ 禁止生成 PUT 或 DELETE 接口。

2.3 使用步骤

第一步：确认需求

在向 AI 提需求前，先整理好以下信息：

模块名称：物料管理
业务表名：biz_material
路由路径：/biz/material
菜单父级：/biz
权限前缀：biz:material

字段清单：
| 字段名 | 中文名 | 数据库类型 | Java类型 | 前端组件 | 必填 | 可搜 | 可列 | 可编 | 可导 |
|--------|--------|-----------|---------|---------|------|------|------|------|------|
| material_name | 物料名称 | varchar(128) | String | Input | ✅ | ✅ | ✅ | ✅ | ✅ |
| material_code | 物料编码 | varchar(64) | String | Input | ✅ | ✅ | ✅ | ✅ | ✅ |
| category | 类别 | varchar(32) | String | DictSelect | ✅ | ✅ | ✅ | ✅ | ✅ |
| specification | 规格型号 | varchar(128) | String | Input | | | ✅ | ✅ | ✅ |
| unit | 单位 | varchar(16) | String | Input | ✅ | | ✅ | ✅ | ✅ |
| status | 状态 | varchar(16) | String | DictSelect | ✅ | ✅ | ✅ | ✅ | ✅ |
| remark | 备注 | varchar(500) | String | Textarea | | | | ✅ | |

字典：
- biz_material_category（物料类别）：原材料、半成品、成品
- 复用 sys_enable_disable（启用/禁用）

导入导出：需要

第二步：向 AI 提需求

在 AI 编程助手中输入：

请使用 forge-codegen-crud skill 生成物料管理模块的完整代码。

模块信息：
- 模块名称：物料管理
- 业务表名：biz_material
- 路由路径：/biz/material
- 菜单父级：/biz
- 权限前缀：biz:material

字段清单：
（粘贴上面的字段表）

字典：
- biz_material_category：原材料、半成品、成品
- 复用 sys_enable_disable

需要导入导出功能。

AI 会自动读取 .agents/skills/forge-codegen-crud/SKILL.md 及其 references，按项目规范生成代码。

第三步：确认生成产物

AI 应生成以下文件：

后端 Java：

forge-framework/forge-plugin-parent/forge-plugin-<module>/
├── src/main/java/com/mdframe/forge/plugin/<module>/
│   ├── controller/BizMaterialController.java
│   ├── domain/entity/BizMaterial.java
│   ├── dto/BizMaterialDTO.java
│   ├── dto/BizMaterialQuery.java
│   ├── mapper/BizMaterialMapper.java
│   ├── service/BizMaterialService.java
│   ├── service/impl/BizMaterialServiceImpl.java
│   └── vo/BizMaterialVO.java
└── src/main/resources/mapper/BizMaterialMapper.xml

前端 Vue：

forge-admin-ui/src/views/biz/material/index.vue

Flyway SQL：

forge-server/db/migration/V1.0.XX__add_biz_material.sql

包含：

建表 DDL（含索引）
字典种子（sys_dict_type + sys_dict_data）
Excel 导入导出配置（sys_excel_export_config + sys_excel_column_config）
菜单和按钮权限（sys_resource）

第四步：验证

对照 validation-checklist.md 检查：

Flyway 文件名使用下一个未用版本号
业务表包含 id、tenant_id、create_by、create_time 等系统字段
内置数据使用 tenant_id = 1
每条 INSERT 有 NOT EXISTS 保护
Controller 使用 POST 安全路由
分页参数使用 pageNum + pageSize
查询 SQL 在 Mapper XML 中
前端使用 AiCrudPage
字典字段使用 useDict() + DictTag
api-config 使用 :id 占位符

2.4 实战示例：生成供应商管理模块

请使用 forge-codegen-crud skill 生成供应商管理模块。

模块信息：
- 模块名称：供应商管理
- 业务表名：biz_supplier
- 路由路径：/biz/supplier
- 菜单父级：/biz
- 权限前缀：biz:supplier
- 页面模式：主子表（供应商主表 + 供应商品报价子表）

主表字段：
- supplier_name 供应商名称 varchar(128) String Input 必填 可搜 可列 可编 可导
- supplier_code 供应商编码 varchar(64) String Input 必填 可搜 可列 可编 可导
- contact_name 联系人 varchar(64) String Input 可列 可编 可导
- contact_phone 联系电话 varchar(20) String Input 可列 可编 可导
- status 状态 varchar(16) String DictSelect 必填 可搜 可列 可编 可导（复用 sys_enable_disable）
- remark 备注 varchar(500) String Textarea 可编 可导

子表字段（biz_supplier_quote）：
- material_id 物料ID bigint Long RecordSelector 必填 可列 可编
- quote_price 报价(分) bigint Long InputNumber 必填 可列 可编
- effective_date 有效日期 date LocalDate DatePicker 必填 可列 可编
- status 状态 varchar(16) String DictSelect 必填 可列 可编（复用 sys_enable_disable）

字典：复用 sys_enable_disable
导入导出：仅主表需要

三、forge-business-flow-development — 业务流程开发

3.1 适用场景

当你需要开发一个涉及审批流程的业务模块时使用，例如：

采购审批（代码优先模式）
合同审批（代码优先模式）
请假审批（低代码模式）
报销审批（低代码模式）

3.2 两种开发模式

Skill 提供两种工作流路径，根据业务复杂度选择：

模式	适用场景	特点	参考文档
代码优先（Code-First）	复杂业务逻辑、自定义表单、多节点审批	编写 Java Service、自定义 Controller、FlowDefinition	`references/code-first-workflow.md`
低代码（Low-Code）	简单审批、标准 CRUD + 流程	配置驱动、无自定义 Java、使用 AiCrudPage	`references/lowcode-workflow.md`

选择建议：

是否需要自定义 Java Service 逻辑？
  ├── 是 → 代码优先模式
  └── 否 → 低代码模式

是否需要自定义业务表和复杂查询？
  ├── 是 → 代码优先模式
  └── 否 → 低代码模式

是否需要多级审批、会签、驳回修改等复杂流程？
  ├── 是 → 代码优先模式
  └── 否 → 低代码模式（简单直线审批）

3.3 代码优先模式

核心概念

概念	说明	示例
Object Code	业务对象编码	`sample_purchase_order`
Model Key	流程模型 Key	`sample_purchase_order_approval`
Business Key	业务键（对象编码:记录ID）	`sample_purchase_order:123456`
Provider Key	表单提供者 Key	`samplePurchaseOrder`
Form Key	表单资产 Key	`sample_purchase_order_approval_form`

状态机

                  ┌──────────────┐
                  │    DRAFT     │ ← 新建/草稿
                  └──────┬───────┘
                         │ submit
                         ▼
                  ┌──────────────┐
           ┌─────→│  IN_PROCESS  │←─────────┐
           │      └──────┬───────┘          │
           │             │                  │
           │     ┌───────┴───────┐          │ resubmit
           │     │               │          │
           │     ▼ approve       ▼ reject   │
           │  ┌──────┐    ┌──────────────┐  │
           │  │APPROVED│   │ NEED_MODIFY  │──┘
           │  └──────┘    └──────┬───────┘
           │                      │ terminate
           │                      ▼
           │               ┌──────────────┐
           │               │  REJECTED    │
           │               └──────────────┘
           │
           └ cancel/withdraw
                  ▼
           ┌──────────────┐
           │   CANCELED   │
           └──────────────┘

生成的文件清单

forge-server/forge-business/forge-business-core/
├── src/main/java/.../<domain>/
│   ├── controller/<Business>Controller.java        ← REST 接口
│   ├── domain/<Business>.java                       ← 实体类（含流程字段）
│   ├── dto/<Business>DTO.java                       ← 数据传输对象
│   ├── dto/<Business>Query.java                     ← 查询条件
│   ├── dto/<Business>SubmitDTO.java                 ← 提交审批 DTO
│   ├── dto/<Business>TaskSaveDTO.java               ← 任务保存 DTO
│   ├── mapper/<Business>Mapper.java                 ← Mapper 接口
│   ├── provider/<Business>CodeFormProvider.java     ← 表单提供者
│   ├── service/<Business>Service.java               ← Service 接口
│   ├── service/impl/<Business>ServiceImpl.java      ← Service 实现（含回调）
│   ├── support/<Business>FlowDefinition.java        ← 流程常量定义
│   ├── support/<Business>FlowBpmn.java              ← BPMN 模型构建
│   └── vo/<Business>VO.java                         ← 视图对象
├── src/main/resources/mapper/business/
│   └── <Business>Mapper.xml                         ← Mapper XML
└── forge-server/db/migration/
    └── V1.0.XX__add_<business>_flow.sql             ← 建表+字典+菜单+流程绑定

向 AI 提需求示例

请使用 forge-business-flow-development skill，采用代码优先模式开发合同审批模块。

业务需求：
- 模块名称：合同审批
- Object Code：contract_approval
- 业务表：biz_contract
- 审批流程：部门负责人 → 法务审核 → 总经理审批
- 驳回：法务审核可驳回给申请人修改
- 会签：无
- 字段：合同编号、合同名称、合同金额(分)、对方单位、合同类型、附件、备注
- 审批人：部门负责人（发起人所在部门）、法务负责人（固定角色）、总经理（固定角色）

请生成完整的后端代码、SQL 迁移脚本和前端页面。

关键实现要点

1. FlowDefinition 常量类

public class ContractFlowDefinition {
    public static final String OBJECT_CODE = "contract_approval";
    public static final String MODEL_KEY = "contract_approval_flow";
    public static final String BUSINESS_TYPE = "contract_approval";
    public static final String PROVIDER_KEY = "contractApproval";
    public static final String FORM_KEY = "contract_approval_form";

    // 节点 Key
    public static final String NODE_DEPT_LEADER = "dept_leader_approve";
    public static final String NODE_LEGAL_REVIEW = "legal_review";
    public static final String NODE_GM_APPROVE = "gm_approve";
    public static final String NODE_APPLICANT_MODIFY = "applicant_modify";

    // 状态
    public static final String STATUS_DRAFT = "DRAFT";
    public static final String STATUS_IN_PROCESS = "IN_PROCESS";
    public static final String STATUS_NEED_MODIFY = "NEED_MODIFY";
    public static final String STATUS_APPROVED = "APPROVED";
    public static final String STATUS_REJECTED = "REJECTED";
    public static final String STATUS_CANCELED = "CANCELED";
}

2. 流程回调

@FlowBind(modelKey = MODEL_KEY, businessType = BUSINESS_TYPE)
public class ContractServiceImpl implements ContractService {

    @FlowCallback(on = {
        FlowCallback.ON_TASK_CREATED,
        FlowCallback.ON_TASK_COMPLETED,
        FlowCallback.ON_COMPLETED,
        FlowCallback.ON_REJECTED,
        FlowCallback.ON_CANCELED
    })
    @Transactional(rollbackFor = Exception.class)
    public void handleFlowEvent(FlowEventContext context) {
        // 根据 context 的事件类型，幂等更新业务状态
    }
}

3. 状态修复

状态修复在三个点执行，防止事件时序漂移：

修复点	说明
`ON_TASK_CREATED` 回调	申请人修改节点：`IN_PROCESS → NEED_MODIFY`；审批节点：`NEED_MODIFY → IN_PROCESS`
任务表单保存	保存前检查并修复状态
页面/详情查询	查询时比对活跃任务节点，修复漂移状态

3.4 低代码模式

低代码模式不需要编写 Java 代码，通过配置实现审批流程：

创建业务对象：在应用中心创建业务对象（参考低代码应用管理教程）
配置单据流程：在设计器中绑定流程模型
配置自动化动作：在业务处理面板配置审批回调动作
发布：通过发布检查后发布

低代码模式的详细操作请参考低代码应用管理实战教程。

3.5 参考文档说明

Skill 包含 7 个参考文档，AI 会根据任务按需加载：

参考文档	何时读取	内容
`code-first-workflow.md`	代码优先模式	文件布局、开发流程、状态门控
`lowcode-workflow.md`	低代码模式	配置流程、平台 API、检查项
`purchase-order-reference.md`	需要查看完整示例	采购单模块的文件清单和行为说明
`status-and-callbacks.md`	编写回调逻辑	状态机、回调契约、修复规则
`bpmn-configuration.md`	配置 BPMN 节点	节点属性、表单权限、变量表达式
`sql-templates.md`	编写 Flyway 脚本	建表、字典、菜单、流程绑定完整模板
`validation-checklist.md`	测试和最终检查	静态检查、编译、流程运行时验证

四、ui-ux-pro-max — UI/UX 设计智能

4.1 适用场景

当前端页面需要专业的 UI/UX 设计指导时使用：

新建前端页面或组件
选择配色方案和字体
优化现有页面视觉体验
无障碍设计检查

4.2 使用方式

# 生成完整设计系统（必须的第一步）
python3 .agents/skills/ui-ux-pro-max/scripts/search.py "enterprise admin dashboard" --design-system -p "Forge Admin"

# 搜索特定领域
python3 .agents/skills/ui-ux-pro-max/scripts/search.py "data table" --domain ux
python3 .agents/skills/ui-ux-pro-max/scripts/search.py "dark mode" --domain style

4.3 包含的设计数据库

数据库	条目数	说明
风格库	67 种	玻璃态、新拟态、极简主义等
配色库	96 套	按产品类型分类
字体库	57 组	标题+正文字体配对
图表库	25 种	图表类型选择
UX 准则	99 条	无障碍、交互、性能

五、Skill 文件结构详解

5.1 SKILL.md 格式

每个 Skill 的主文件使用 YAML front matter + Markdown 结构：

---
name: skill-name                    # Skill 标识（与目录名一致）
description: 一段描述文字            # AI 根据这段描述判断是否匹配任务
---

# Skill 标题

## Overview
概述...

## Workflow
工作流程...

## Non-Negotiable Rules
红线规则...

## Required References
参考文档列表...

5.2 description 的作用

description 字段是 AI 编程助手判断是否激活该 Skill 的关键。AI 会将用户需求与所有 Skill 的 description 进行语义匹配：

用户说："帮我生成一个物料管理的 CRUD 模块"
AI 匹配到 forge-codegen-crud 的 description 中的 "CRUD modules"
自动读取 SKILL.md 及相关 references

5.3 references 子文档

references 目录存放详细参考文档，AI 按需加载，避免一次性加载过多内容：

SKILL.md：主文件，包含核心规范和红线（AI 总是先读这个）
references/*.md：详细参考（AI 根据任务需要选择读取）

这种设计确保：

AI 上下文窗口不被撑爆
不同复杂度的任务只加载必要的文档
文档可以独立维护和更新

六、最佳实践

6.1 提需求的模板

向 AI 提需求时，使用以下模板可以让 Skill 发挥最大效果：

请使用 [skill-name] skill 完成 [任务描述]。

模块信息：
- 模块名称：xxx
- 业务表名：xxx
- 路由路径：xxx
- 菜单父级：xxx
- 权限前缀：xxx

字段清单：
| 字段名 | 中文名 | 数据库类型 | Java类型 | 前端组件 | 必填 | 可搜 | 可列 | 可编 | 可导 |
|...|...|...|...|...|...|...|...|...|...|

字典：
- xxx（新增）：值1、值2、值3
- xxx（复用已有）

[流程相关]
- 审批节点：节点1 → 节点2 → 节点3
- 驳回规则：...
- 会签：无/有

[其他]
导入导出：需要/不需要

6.2 验证生成代码

生成代码后，让 AI 自动执行验证清单：

请按照 .agents/skills/forge-codegen-crud/references/validation-checklist.md
对生成的代码进行验证，列出所有通过和未通过的检查项。

6.3 自定义和扩展 Skill

你可以根据项目需要自定义 Skill：

修改现有 Skill：直接编辑 .agents/skills/*/SKILL.md 或 references 文件
新增 Skill：在 .agents/skills/ 下新建目录，创建 SKILL.md
新增参考文档：在 references/ 下新增 .md 文件，并在 SKILL.md 的引用列表中注册

示例：新增一个"报表开发" Skill

.agents/skills/forge-report-development/
├── SKILL.md
└── references/
    ├── report-template.md
    └── sql-patterns.md

SKILL.md 的 description 写清楚触发关键词：

---
name: forge-report-development
description: Generate Forge report modules with chart integration, data aggregation, and export. Use when creating statistical reports, dashboards, data visualization pages, or analytical summaries.
---

6.4 团队协作

Skill 文件纳入 Git 版本控制，团队共享
修改 Skill 前先通知团队，避免规范频繁变动
新成员加入时，让 AI 助手读取 Skill 即可快速上手项目规范
Code Review 时可对照 Skill 的 validation-checklist 检查

七、常见问题

Q1: AI 没有自动激活 Skill？

检查 SKILL.md 的 description 是否包含任务相关关键词
在需求中明确指定 skill 名称（如"请使用 forge-codegen-crud skill"）
确认 AI 编程助手支持 .agents/skills/ 目录读取

Q2: 生成的代码不符合项目规范？

检查 Skill 的 Non-Negotiable Rules 是否覆盖了该规范
在需求中强调必须遵守的规则
更新 SKILL.md 补充缺失的规范

Q3: Skill 和 AGENTS.md 的关系？

AGENTS.md 是项目级总纲，包含全局规范
Skill 是专项指南，针对特定任务类型（CRUD、流程开发等）
Skill 中的规则不能与 AGENTS.md 冲突
AI 会先读 AGENTS.md，再根据任务读取对应 Skill

Q4: 两个 Skill 可以组合使用吗？

可以。例如开发一个"采购审批模块"，既需要流程审批又需要 CRUD 管理：

请使用 forge-business-flow-development skill（代码优先模式）
和 forge-codegen-crud skill，开发采购审批模块。

CRUD 部分：
（字段清单...）

流程部分：
- 审批节点：部门负责人 → 采购经理 → 总经理
- 驳回：采购经理可驳回给申请人修改

AI 会同时读取两个 Skill 的规范，生成符合双方要求的代码。

Q5: 如何更新 Skill 以适配项目变化？

修改 SKILL.md 中的规范和红线
更新 references 中受影响的参考文档
在 Git 提交消息中说明变更原因（如 "更新 Skill：适配新的分页参数规范"）
通知团队成员重新加载或重启 AI 编程助手

skill-usage-tutorial.md 24 KB Riwayat Mentahan