ai-engineering-init 1.7.0 → 1.10.0

package/CLAUDE.md

@@ -1,4 +1,7 @@
-# CLAUDE.md - leniu-tengyun-core 云食堂项目
+# CLAUDE.md - [你的项目名称]
+
+> **这是示例模板**。安装后请将 `[你的xxx]` 占位符替换为你的项目实际信息。
+> 如果项目有专属技能（如 `leniu-*`），它们会覆盖同名通用技能的规范。
 
 ## Workflow Orchestration
 
@@ -63,30 +66,26 @@
 
 ## 术语约定
 
+> 根据你的项目实际情况填写术语表。
+
 | 术语 | 含义 | 路径 |
 |------|------|------|
-| **后端** | Java 服务 | `leniu-tengyun-core/` |
-| **前端** | PC 管理端 | `/Users/xujiajun/Developer/frontProj/web`（Vue 2） |
-| **食堂模块** | 食堂业务 | `sys-canteen/` |
-| **后场模块** | 后场厨房 | `sys-kitchen/` |
-| **供应链模块** | 供应链 | `sys-drp/` |
-| **公共模块** | 基础公共 | `core-base/`、`sys-common/` |
+| **后端** | Java 服务 | `[你的后端根目录]/` |
+| **前端** | 管理端 | `[你的前端目录]/` |
+| **模块A** | 核心业务 | `[你的模块A路径]/` |
+| **模块B** | 辅助业务 | `[你的模块B路径]/` |
+| **公共模块** | 基础公共 | `[你的公共模块路径]/` |
 
 ## 前端技术栈
 
+> 根据你的项目前端技术栈填写。
+
 | 技术 | 版本 | 说明 |
 |------|------|------|
-| Vue | 2.7.16 | Options API |
-| Element UI | 2.15.9 | `el-` 前缀组件 |
-| Vuex | 3.4.0 | namespaced:true |
-| Vue Router | 3.2.0 | Hash 路由 |
-| vue-i18n | 7.3.2 | `$t('key')` |
-
-**前端关键机制**：Token=`Admin-Token`（localStorage）、租户=`MERCHANT-ID`（请求头）、成功码=`10000`、金额=分（`money()` 转元）、权限=`v-hasPerm`、加密=SM4
-
-**前端 src 结构**：`api/`(65个接口) | `leniuview/`(35个业务模块) | `leniu-components/`(业务组件) | `components/`(~87) | `store/`(30个模块)
-
-> **前端技能**：`ui-pc`（组件/API/权限）、`store-pc`（Vuex）
+| [框架] | [版本] | [API 风格] |
+| [UI 库] | [版本] | [组件前缀] |
+| [状态管理] | [版本] | [配置说明] |
+| [路由] | [版本] | [路由模式] |
 
 ## MCP 工具触发
 
@@ -110,149 +109,136 @@
 
 ## 核心规范速查
 
+> 根据你的项目规范填写。
+
 | 项目 | 规范 |
 |------|------|
-| **包名** | `net.xnzn.core.*` |
-| **JDK** | 21 |
-| **框架** | pigx-framework 3.4.7 + Spring Boot 3.x |
-| **架构** | Controller → Business → Service → Mapper |
-| **请求封装** | `LeRequest<T>` |
-| **分页** | `PageDTO` + `PageVO` + PageHelper |
-| **异常** | `LeException` |
-| **国际化** | `I18n.getMessage()` |
-| **对象转换** | `BeanUtil.copyProperties()`（Hutool） |
-| **权限** | `@RequiresAuthentication` |
-| **ID** | `Id.next()`（雪花ID） |
-| **验证** | `jakarta.validation.*`（JDK 21） |
-
-## 双库架构
-
-物理分离双库，**无 tenant_id 字段**：
-
-| 库 | 说明 | 切换方式 |
-|----|------|---------|
-| 系统库 | 全局数据（商户配置、字典） | `Executors.doInSystem()` |
-| 商户库 | 租户业务数据（订单、菜品） | 默认（请求头 `MERCHANT-ID`） |
+| **包名** | `[你的包名]` |
+| **JDK** | [版本] |
+| **框架** | [框架名称 + 版本] |
+| **架构** | [你的分层架构] |
+| **异常** | `[你的业务异常类]` |
+| **对象转换** | `[你的对象转换工具]` |
+| **权限** | `[你的权限注解]` |
+| **ID 生成** | `[你的ID生成策略]` |
+| **验证** | `jakarta.validation.*` |
 
-```java
-Executors.doInTenant(tenantId, () -> { /* 商户库 */ });
-Executors.doInSystem(() -> { /* 系统库 */ });
-Executors.doInAllTenant(tenantId -> { /* 遍历所有租户 */ });
-```
+## 分层架构说明
 
-## 四层架构说明
+> 根据你的项目选择三层或四层架构。
 
 | 层 | 职责 | 命名示例 |
 |----|------|---------|
-| Controller | 接收请求、参数校验、路由 | `OrderInfoWebController` |
-| **Business** | 业务编排、跨 Service 协调 | `OrderWebBusiness` |
-| Service | 单表 CRUD、事务 | `OrderInfoService` |
-| Mapper | ORM 映射（含 XML 同目录） | `OrderInfoMapper` |
-
-> Business 层是本项目核心特色，复杂逻辑在此处编排。
+| Controller | 接收请求、参数校验、路由 | `OrderController` |
+| Service | 业务逻辑、事务管理 | `OrderService` |
+| Mapper | ORM 映射 | `OrderMapper` |
 
 ## 标准包结构
 
 ```
-net.xnzn.core.[module]/
-├── controller/         # 按端分：web/mobile/android
-├── business/impl/      # 业务编排
+[你的包名].[module]/
+├── controller/         # 接口层
 ├── service/impl/       # 服务层
-├── mapper/             # Mapper + XML（同目录！）
+├── mapper/             # 数据访问层
 ├── model/              # Entity
 ├── vo/                 # 响应对象
 ├── dto/                # 请求参数
 ├── constants/          # 枚举和常量
-├── mq/                 # 消息队列
-└── task/               # 定时任务
+└── config/             # 配置类
 ```
 
-> **XML 与 Mapper 同目录**（非 `resources/mapper/`），需在 pom.xml 配置资源过滤。
-
-## 多端 Controller 路由
-
-| 端 | 路由前缀 |
-|----|---------|
-| Web 管理端 | `/api/v2/web/{module}` |
-| 移动端 | `/api/v2/mobile/{module}` |
-| 设备端 | `/api/v2/android/{module}` |
-| 开放接口 | `/api/v2/open/{module}` |
-
 ## Entity 审计字段
 
-| leniu 字段 | 含义 | 填充时机 |
-|-----------|------|---------|
-| `crby` | 创建人 | INSERT |
-| `crtime` | 创建时间 | INSERT |
-| `upby` | 更新人 | INSERT_UPDATE |
-| `uptime` | 更新时间 | INSERT_UPDATE |
-| `delFlag` | **1=删除，2=正常** | 手动 |
+> 根据你的项目审计字段命名填写。
+
+| 字段 | 含义 | 填充时机 |
+|------|------|---------|
+| `create_by` | 创建人 | INSERT |
+| `create_time` | 创建时间 | INSERT |
+| `update_by` | 更新人 | INSERT_UPDATE |
+| `update_time` | 更新时间 | INSERT_UPDATE |
+| `deleted` | 逻辑删除（0=正常，1=删除） | 手动 |
 
 ## 工具类速查
 
+> 根据你的项目使用的工具类填写。
+
 | 工具 | 用途 |
 |------|------|
-| `BeanUtil.copyProperties()` | 对象转换 |
-| `CollUtil.isEmpty()` | 集合判空 |
-| `ObjectUtil.isNull()` | 对象判空 |
-| `StrUtil.isBlank()` | 字符串判空 |
-| `Id.next()` | 雪花ID |
-| `LeException` | 业务异常 |
-| `I18n.getMessage()` | 国际化 |
-| `TenantContextHolder.getTenantId()` | 租户上下文 |
-| `PageMethod.startPage()` | 分页拦截 |
+| `[对象转换工具]` | 对象转换 |
+| `[集合工具]` | 集合判空/操作 |
+| `[字符串工具]` | 字符串处理 |
+| `[业务异常类]` | 抛出业务异常 |
+| `[分页工具]` | 分页查询 |
 
 ## 绝对禁止
 
 ```java
-// ❌ 错误包名
-package org.dromara.xxx;           // 必须 net.xnzn.core.xxx
-
-// ❌ 旧验证包（JDK 21 必须用 jakarta）
+// ❌ 旧验证包（JDK 17+ 必须用 jakarta）
 import javax.validation.constraints.*;
+// ✅ 使用 jakarta
+import jakarta.validation.constraints.*;
 
-// ❌ RuoYi 工具类
-MapstructUtils.convert();          // 用 BeanUtil.copyProperties()
-throw new ServiceException("msg"); // 用 throw new LeException("msg")
-
-// ❌ 错误审计字段名
-private String createBy;           // 必须 crby
-private LocalDateTime createTime;  // 必须 crtime
-
-// ❌ Entity 加 tenant_id（双库物理隔离，不需要）
+// ❌ Map 传递业务数据
+Map<String, Object> result = new HashMap<>();
+// ✅ 使用 VO/DTO
+return new OrderVO(order);
 
-// ❌ del_flag: 0=正常（leniu 是 2=正常）
+// ❌ 在 Controller 直接操作数据库
+// ✅ 通过 Service 层
 
-// ❌ Map 传递业务数据（必须用 VO/DTO）
+// ❌ 硬编码配置值
+String url = "http://localhost:8080";
+// ✅ 使用配置文件
+@Value("${app.url}") String url;
 ```
 
 ## 数据库规范
 
 ```sql
-CREATE TABLE xxx (
-    id       BIGINT    NOT NULL COMMENT '主键（雪花ID）',
+CREATE TABLE [表名] (
+    id          BIGINT       NOT NULL COMMENT '主键',
     -- 业务字段...
-    crby     VARCHAR(64) COMMENT '创建人',
-    crtime   DATETIME    COMMENT '创建时间',
-    upby     VARCHAR(64) COMMENT '更新人',
-    uptime   DATETIME    COMMENT '更新时间',
-    del_flag INT DEFAULT 2 COMMENT '删除标识(1-删除,2-正常)',
+    create_by   VARCHAR(64)  COMMENT '创建人',
+    create_time DATETIME     COMMENT '创建时间',
+    update_by   VARCHAR(64)  COMMENT '更新人',
+    update_time DATETIME     COMMENT '更新时间',
+    deleted     INT DEFAULT 0 COMMENT '逻辑删除(0-正常,1-删除)',
     PRIMARY KEY (id)
 );
--- ⚠️ 无需 tenant_id（双库物理隔离）
 ```
 
-## 参考代码位置
+## 开发模式选择指南
 
-| 类型 | 路径 |
-|------|------|
-| 订单 Controller | `sys-canteen/.../order/web/controller/OrderInfoWebController.java` |
-| 订单 Business | `sys-canteen/.../order/web/business/impl/OrderWebBusiness.java` |
-| 订单 Service | `sys-canteen/.../order/common/service/impl/OrderInfoService.java` |
-| 订单 Entity | `sys-canteen/.../order/common/model/OrderInfo.java` |
-| 订单枚举 | `sys-canteen/.../order/common/constants/OrderStateEnum.java` |
-| 排班 Controller | `sys-kitchen/.../attendance/scheduling/controller/BackAttendanceWorkShiftController.java` |
-| Bootstrap 配置 | `core-base/src/main/resources/bootstrap.yml` |
+根据功能复杂度和开发类型，选择合适的工作流：
+
+### 复杂度路由表
+
+| 复杂度 | 判断标准 | 推荐工作流 | 说明 |
+|--------|---------|-----------|------|
+| **轻量** | 单表 CRUD、字段增删、简单查询 | `/dev` 或 `/crud` 直接开发 | 无需需求拆解 |
+| **中等** | 2-3 张表联动、跨 Service 调用、状态流转 | `/dev` 开发（可选 OpenSpec） | 建议先理清逻辑再编码 |
+| **复杂** | 多模块协作、复杂业务流程、需要设计评审 | OpenSpec → `/dev` | 先用 `/opsx:ff` 生成制品，再按 tasks 逐步实现 |
+
+### 开发类型路由
+
+| 类型 | 特征 | 工作流 |
+|------|------|--------|
+| **产品开发（core 迭代）** | 改 core 代码、会有后续迭代 | 复杂功能用 OpenSpec 拆解，简单功能直接 `/dev` |
+| **项目定制（一次性）** | Dz 前缀类、dz_ 表、@Primary 覆盖 | 直接 `/dev`，参考 `leniu-customization-location` 技能 |
+
+### OpenSpec 与 Commands 的关系
+
+```
+OpenSpec（思考）          Commands（执行）
+───────────────          ──────────────
+proposal.md    ────→    /dev（按 task 逐个开发）
+specs/*.md     ────→    /crud（快速生成 CRUD）
+design.md      ────→    /check（验证规范）
+tasks.md       ────→    /progress（跟踪进度）
+```
+
+> **原则**：OpenSpec 负责需求拆解和设计决策，Commands 负责代码生成和质量管控。简单任务跳过 OpenSpec，直接用 Commands。
 
 ## 快速命令
 
@@ -261,3 +247,5 @@ CREATE TABLE xxx (
 | `/dev` | 开发新功能 |
 | `/crud` | 快速生成 CRUD |
 | `/check` | 代码规范检查 |
+| `/next` | 下一步建议（含 OpenSpec 变更扫描） |
+| `/progress` | 项目进度（含 OpenSpec 状态） |

package/README.md

@@ -31,28 +31,59 @@ npx ai-engineering-init --tool all      # 全部
 
 > 所有命令均支持 `--tool <claude|cursor|codex|all>` 指定工具。运行 `--help` 查看全部选项。
 
+## 3 分钟上手
+
+```bash
+# 第一步：安装
+npx ai-engineering-init --tool claude
+
+# 第二步：修改配置（⚠️ 必做！）
+# CLAUDE.md 和 AGENTS.md 是示例模板，包含 [你的xxx] 占位符
+# 把它们替换为你的项目实际信息（包名、技术栈、架构规范等）
+
+# 第三步：验证
+# 在 Claude Code 中输入 /start，AI 会扫描并介绍你的项目
+```
+
+**核心命令**（第一天用这 3 个就够了）：
+
+| 命令 | 作用 |
+|------|------|
+| `/start` | AI 扫描项目，给出概览 |
+| `/dev` | 从需求到代码的完整开发流程 |
+| `/check` | 检查代码是否符合规范 |
+
+**更多命令**：`/crud`（生成增删改查）、`/progress`（项目进度）、`/sync`（代码状态同步）
+
+> **包含内容**：88 个 Skills 技能 + 10 个快捷命令 + 自动化 Hooks。详见 [参考文档](./docs/reference.md)。
+
 ## 初始化后使用
 
 ### Claude Code
 
-1. 按需修改 `CLAUDE.md` 中的项目信息
-2. 输入 `/start` 快速了解项目，`/dev` 开发新功能，`/crud` 生成 CRUD，`/check` 检查规范
+1. **必做**：修改 `CLAUDE.md` — 将 `[你的xxx]` 占位符替换为项目实际信息
+2. 输入 `/start` 验证 AI 是否正确理解你的项目
+3. MCP 工具已自动配置（`sequential-thinking`、`context7`），无需额外设置
 
 ### Cursor
 
-1. 在 Chat 中输入 `/` 查看可用 Skills，或 `@技能名` 手动调用
-2. 在 Settings → MCP 中确认 MCP 服务器已连接
+1. **必做**：检查 `.cursor/mcp.json` 中的 MCP 服务器配置
+2. 在 Chat 中输入 `/` 查看可用 Skills，或 `@技能名` 手动调用
+3. 在 Settings → MCP 中确认 MCP 服务器已连接
 
 ### OpenAI Codex
 
-1. 按需修改 `AGENTS.md`，使用 `.codex/skills/` 下的技能辅助开发
+1. **必做**：修改 `AGENTS.md` — 将模板内容替换为你的项目规范
+2. 使用 `.codex/skills/` 下的技能辅助开发
 
 ## 更多信息
 
-[参考文档](./docs/reference.md) — Skills 列表（69个）、包含内容、命令详情、其他安装方式、全部选项
+[参考文档](./docs/reference.md) — Skills 列表、包含内容、命令详情、其他安装方式、全部选项
 
 [更新日志](./CHANGELOG.md) — 完整版本变更记录
 
+[贡献指南](./CONTRIBUTING.md) — 如何维护和更新 Skills，团队协作工作流
+
 ## License
 
 MIT

package/bin/index.js

@@ -525,16 +525,20 @@ function showDoneHint(toolKey) {
   console.log('');
   if (toolKey === 'claude' || toolKey === 'all') {
     console.log(fmt('cyan', 'Claude Code 使用：'));
-    console.log(`  1. 按需修改 ${fmt('bold', 'CLAUDE.md')} 中的项目信息`);
+    console.log(`  1. ${fmt('bold', '必做')}：修改 ${fmt('bold', 'CLAUDE.md')} — 把 [你的xxx] 占位符替换为项目实际信息`);
     console.log(`  2. 在 Claude Code 中输入 ${fmt('bold', '/start')} 快速了解项目`);
     console.log(`  3. 输入 ${fmt('bold', '/dev')} 开始开发新功能`);
     console.log('');
+    console.log(fmt('yellow', '  💡 CLAUDE.md 和 AGENTS.md 是示例模板，务必替换占位符后使用'));
+    console.log(fmt('yellow', `  💡 运行 ${fmt('bold', hintCmd('mcp'))} 管理 MCP 服务器（云效、语雀等）`));
+    console.log('');
   }
   if (toolKey === 'cursor' || toolKey === 'all') {
     console.log(fmt('cyan', 'Cursor 使用：'));
     console.log(`  1. 在 Cursor Chat 中输入 ${fmt('bold', '/')} 查看所有可用 Skills`);
     console.log(`  2. 输入 ${fmt('bold', '@技能名')} 手动调用指定技能`);
     console.log(`  3. 在 Settings → MCP 中确认 MCP 服务器已连接`);
+    console.log(fmt('yellow', `  💡 运行 ${fmt('bold', hintCmd('mcp'))} 管理 MCP 服务器（云效、语雀等）`));
     console.log('');
   }
   if (toolKey === 'codex' || toolKey === 'all') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-init",
-  "version": "1.7.0",
+  "version": "1.10.0",
   "description": "AI 工程化配置初始化工具 — 一键为 Claude Code、OpenAI Codex 等 AI 工具初始化 Skills 和项目规范",
   "keywords": [
     "claude-code",