@fastcar/cli 0.1.0 → 0.1.2

package/bin/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const init = require("../src/init");
 const setModules = require("../src/setModules");
@@ -26,7 +26,7 @@ Commands:
   clean node_modules       删除冗余的 node_modules 目录
   compress node_modules    压缩 node_modules 目录
   reverse                  数据库表逆向生成
-  reverse:init             生成 reverse.config.json 配置文件
+  reverse:init             生成 reverse.config.yml/json 配置文件
   pack [pm]                打包项目（排除 devDependencies）
                            pm: 包管理器 (npm/yarn/pnpm)，可选，默认自动检测
 
@@ -54,7 +54,7 @@ Examples:
   $ fastcar-cli init web my-project   # 使用 web 模板创建 my-project
   $ fastcar-cli clean node_modules
   $ fastcar-cli reverse        # 数据库表逆向生成
-  $ fastcar-cli reverse:init   # 生成默认配置文件
+  $ fastcar-cli reverse:init   # 生成默认配置文件（默认 YAML 格式）
   $ fastcar-cli pack           # 打包项目（自动检测包管理器）
   $ fastcar-cli pack yarn      # 使用 yarn 安装依赖
   $ fastcar-cli pack pnpm      # 使用 pnpm 安装依赖
@@ -67,7 +67,7 @@ Examples:
   $ fastcar-cli skill targets                         # 列出支持的 agents
 
 Reverse 命令参数说明:
-  通过配置文件传入参数，在项目根目录创建 reverse.config.json：
+  通过配置文件传入参数，在项目根目录创建 reverse.config.yml 或 reverse.config.json：
 
   {
     "tables": ["test"],               // 要逆向生成的表名数组（必填）
@@ -100,7 +100,7 @@ function showVersion() {
   console.log(`fastcar-cli version ${packageINFO.version}`);
 }
 
-function run(argv) {
+async function run(argv) {
   // 命令入口
   if (!argv || argv.length === 0) {
     showHelp();
@@ -122,7 +122,7 @@ function run(argv) {
       break;
     }
     case "init": {
-      init(body);
+      await init(body);
       break;
     }
     case "clean":
@@ -139,11 +139,11 @@ function run(argv) {
       break;
     }
     case "reverse": {
-      reverseGenerate(body);
+      await reverseGenerate(body);
       break;
     }
     case "reverse:init": {
-      initReverseConfig();
+      await initReverseConfig();
       break;
     }
     case "pack": {
@@ -220,4 +220,7 @@ function run(argv) {
   }
 }
 
-run(process.argv.slice(2));
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastcar/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "homepage": "https://william_zhong.coding.net/public/fast-car/fastcar-cli/git/files",
   "description": "fastcar-cli 脚手架快速搭建",
   "bin": {
@@ -24,7 +24,7 @@
     "commander": "^8.3.0",
     "compressing": "^1.5.1",
     "inquirer": "^8.2.0",
-    "yaml": "^1.10.2"
+    "yaml": "^2.8.3"
   },
   "repository": {
     "type": "git",

package/skills/fastcar-database/SKILL.md

@@ -26,7 +26,7 @@ export default new APP();
 #### 定义实体模型
 
 ```typescript
-import { Table, Field, DBType, PrimaryKey, NotNull, Size, CustomType } from "@fastcar/core/annotation";
+import { Table, Field, DBType, PrimaryKey, NotNull, Size } from "@fastcar/core/annotation";
 
 @Table("users")
 class User {
@@ -43,11 +43,25 @@ class User {
 
   @Field("profile")
   @DBType("json")
-  @CustomType("json")
-  profile: any;
+  profile!: any;
 
-  constructor(...args: any) {
-    Object.assign(this, ...args);
+  @Field("created_at")
+  @DBType("datetime")
+  createdAt!: Date;
+
+  constructor(args?: Partial<User>) {
+    if (args) {
+      Object.assign(this, args);
+    }
+  }
+
+  toObject() {
+    return {
+      id: this.id,
+      name: this.name,
+      profile: this.profile,
+      createdAt: this.createdAt,
+    };
   }
 }
 ```
@@ -66,11 +80,11 @@ class UserMapper extends MysqlMapper<User> {}
 export default UserMapper;
 ```
 
-#### Service 中使用
+#### MysqlMapper 完整 API 参考
 
 ```typescript
 import { Service, Autowired } from "@fastcar/core/annotation";
-import { OrderEnum } from "@fastcar/core/db";
+import { OrderEnum, OperatorEnum } from "@fastcar/core/db";
 import UserMapper from "./UserMapper";
 import User from "./User";
 
@@ -79,73 +93,232 @@ class UserService {
   @Autowired
   private userMapper!: UserMapper;
 
-  // 查询单条
-  async getUser(id: number) {
-    return this.userMapper.selectOne({ where: { id } });
+  // ==================== 查询方法 ====================
+
+  // 1. select(conditions) - 查询列表
+  // 返回: T[] - 实体对象数组
+  async getAllUsers() {
+    return this.userMapper.select({});
+  }
+
+  // 2. selectOne(conditions) - 查询单个
+  // 返回: T | null
+  async getUserById(id: number) {
+    return this.userMapper.selectOne({
+      where: { id }
+    });
+  }
+
+  // 3. selectByPrimaryKey(row) - 根据主键查询
+  // 参数: 包含主键字段的对象
+  // 返回: T | null
+  async getUserByPK(id: number) {
+    return this.userMapper.selectByPrimaryKey({ id } as User);
+  }
+
+  // 4. count(where) - 统计记录数
+  // 返回: number
+  async countUsers() {
+    return this.userMapper.count({ status: 1 });
+  }
+
+  // 5. exist(where) - 判断是否存在
+  // 返回: boolean
+  async checkUserExists(name: string) {
+    return this.userMapper.exist({ name });
+  }
+
+  // ==================== 条件查询详解 ====================
+
+  // 简单等于条件
+  async queryByStatus(status: number) {
+    return this.userMapper.select({
+      where: { status }
+    });
+  }
+
+  // 多条件 AND
+  async queryByConditions(name: string, status: number) {
+    return this.userMapper.select({
+      where: {
+        name,
+        status,
+        delStatus: false
+      }
+    });
   }
 
-  // 条件查询
-  async queryUsers(name: string) {
+  // 比较运算符
+  async queryByAgeRange(minAge: number, maxAge: number) {
     return this.userMapper.select({
       where: {
-        name: { value: name },
-        createdAt: { ">=": "2024-01-01", "<=": "2024-12-31" },
-      },
-      orders: { createdAt: OrderEnum.desc },
-      limit: 10,
+        age: { $gte: minAge, $lte: maxAge }
+      }
     });
   }
 
-  // 数组 IN 查询
+  // 支持的运算符:
+  // $eq - 等于 (默认)
+  // $gt / $gte - 大于 / 大于等于
+  // $lt / $lte - 小于 / 小于等于
+  // $ne - 不等于
+  // $in - IN 查询 (数组)
+  // $nin - NOT IN 查询
+  // $isNull - IS NULL
+  // $isNotNull - IS NOT NULL
+
+  // IN 查询
   async queryByIds(ids: number[]) {
     return this.userMapper.select({
-      where: { id: { IN: ids } },
+      where: { id: { $in: ids } }
+    });
+  }
+
+  // IS NULL 查询
+  async queryDeletedUsers() {
+    return this.userMapper.select({
+      where: { deletedAt: { $isNull: true } }
+    });
+  }
+
+  // ==================== 排序和分页 ====================
+
+  // 排序 - 必须使用 OrderEnum
+  async getUsersOrdered() {
+    return this.userMapper.select({
+      where: { status: 1 },
+      orders: { createdAt: OrderEnum.desc }  // 正确: 使用 OrderEnum.desc
+      // 错误: orders: { createdAt: "DESC" }
+    });
+  }
+
+  // OrderEnum 定义:
+  // OrderEnum.asc = "ASC"
+  // OrderEnum.desc = "DESC"
+
+  // 多字段排序
+  async getUsersMultiOrder() {
+    return this.userMapper.select({
+      orders: {
+        status: OrderEnum.asc,
+        createdAt: OrderEnum.desc
+      }
+    });
+  }
+
+  // 分页
+  async getUsersPaged(page: number, pageSize: number) {
+    return this.userMapper.select({
+      orders: { id: OrderEnum.desc },
+      offest: (page - 1) * pageSize,
+      limit: pageSize
     });
   }
 
-  // 新增
+  // 只取前N条
+  async getTopUsers(limit: number) {
+    return this.userMapper.select({
+      orders: { score: OrderEnum.desc },
+      limit
+    });
+  }
+
+  // ==================== 插入方法 ====================
+
+  // 1. saveOne(row) - 插入单条
+  // 返回: number - 插入的主键ID
   async createUser(name: string) {
     const user = new User({ name, createdAt: new Date() });
-    return this.userMapper.saveOne(user);
+    const insertId = await this.userMapper.saveOne(user);
+    return insertId;
   }
 
-  // 批量新增
+  // 2. saveList(rows) - 批量插入
+  // 返回: boolean
   async createUsers(users: User[]) {
     return this.userMapper.saveList(users);
   }
 
-  // 更新
-  async updateName(id: number, name: string) {
-    return this.userMapper.update({ where: { id }, row: { name } });
+  // 3. saveORUpdate(rows) - 插入或更新 (UPSERT)
+  // 主键冲突时更新，否则插入
+  // 返回: number - 主键ID
+  async saveOrUpdateUser(user: User) {
+    return this.userMapper.saveORUpdate(user);
+  }
+
+  // ==================== 更新方法 ====================
+
+  // 1. update({ row, where, limit }) - 条件更新
+  // 返回: boolean
+  async updateUserName(id: number, name: string) {
+    return this.userMapper.update({
+      where: { id },
+      row: { name, updatedAt: new Date() }
+    });
   }
 
-  // 按主键更新
+  // 2. updateOne({ row, where }) - 更新单条
+  // 自动限制 limit: 1
+  async updateOneUser(where: any, row: any) {
+    return this.userMapper.updateOne({ where, row });
+  }
+
+  // 3. updateByPrimaryKey(row) - 根据主键更新
+  // 根据实体对象的主键字段更新
+  // 返回: boolean
   async updateById(user: User) {
     return this.userMapper.updateByPrimaryKey(user);
   }
 
-  // 删除
+  // 更新示例：软删除
+  async softDeleteUser(id: number) {
+    return this.userMapper.update({
+      where: { id },
+      row: { delStatus: true, deletedAt: new Date() }
+    });
+  }
+
+  // ==================== 删除方法 ====================
+
+  // 1. delete({ where, limit }) - 条件删除
+  // 返回: boolean
   async deleteUser(id: number) {
-    return this.userMapper.delete({ where: { id } });
+    return this.userMapper.delete({
+      where: { id }
+    });
   }
 
-  // 判断存在
-  async exists(name: string) {
-    return this.userMapper.exist({ name });
+  // 2. deleteOne(where) - 删除单条
+  async deleteOneUser(where: any) {
+    return this.userMapper.deleteOne(where);
   }
 
-  // 统计
-  async count() {
-    return this.userMapper.count({});
+  // 3. deleteByPrimaryKey(row) - 根据主键删除
+  async deleteById(id: number) {
+    return this.userMapper.deleteByPrimaryKey({ id } as User);
+  }
+
+  // ==================== 高级查询 ====================
+
+  // 自定义 SQL 查询
+  // query(sql, args) - 执行查询 SQL
+  async customQuery() {
+    return this.userMapper.query(
+      "SELECT * FROM users WHERE status = ? AND created_at > ?",
+      [1, "2024-01-01"]
+    );
   }
 
-  // 执行原生 SQL
-  async executeSql() {
-    return this.userMapper.execute("SELECT * FROM users WHERE id = 1");
+  // execute(sql, args) - 执行任意 SQL
+  async customExecute() {
+    return this.userMapper.execute(
+      "UPDATE users SET login_count = login_count + 1 WHERE id = ?",
+      [1]
+    );
   }
 
-  // 左连接查询
-  async leftJoin() {
+  // 左连接查询 - 使用 selectByCustom
+  async leftJoinQuery() {
     return this.userMapper.selectByCustom({
       join: [
         {
@@ -155,34 +328,133 @@ class UserService {
         },
       ],
       tableAlias: "t",
+      where: { "t.status": 1 }
     });
   }
 
   // 强制索引
-  async forceIndex() {
+  async forceIndexQuery() {
     return this.userMapper.select({
       forceIndex: ["idx_name"],
-      orders: { name: OrderEnum.desc },
-      limit: 1,
+      where: { status: 1 }
     });
   }
 
-  // 使用函数
-  async formatDate() {
+  // 指定查询字段
+  async selectFields() {
     return this.userMapper.select({
-      fields: ['DATE_FORMAT(created_at, "%Y-%m-%d %H:%i:%s") as createdAt'],
+      fields: ["id", "name", "email"],
+      where: { status: 1 }
+    });
+  }
+
+  // 分组查询
+  async groupByStatus() {
+    return this.userMapper.selectByCustom({
+      fields: ["status", "COUNT(*) as count"],
+      groups: ["status"]
+    });
+  }
+
+  // 使用数据库函数
+  async useDbFunction() {
+    return this.userMapper.selectByCustom({
+      fields: [
+        'id',
+        'name',
+        'DATE_FORMAT(created_at, "%Y-%m-%d") as createdDate'
+      ]
     });
   }
 }
 ```
 
-#### 多数据源
+#### 常用查询条件速查表
+
+```typescript
+// 等于 (默认)
+{ where: { status: 1 } }
+
+// 不等于
+{ where: { status: { $ne: 1 } } }
+
+// 大于 / 大于等于
+{ where: { age: { $gt: 18 } } }
+{ where: { age: { $gte: 18 } } }
+
+// 小于 / 小于等于
+{ where: { age: { $lt: 60 } } }
+{ where: { age: { $lte: 60 } } }
+
+// 范围查询
+{ where: { age: { $gte: 18, $lte: 60 } } }
+
+// IN 查询
+{ where: { id: { $in: [1, 2, 3] } } }
+
+// NOT IN 查询
+{ where: { id: { $nin: [1, 2, 3] } } }
+
+// IS NULL
+{ where: { deletedAt: { $isNull: true } } }
+
+// IS NOT NULL
+{ where: { deletedAt: { $isNotNull: true } } }
+
+// 多条件 AND (默认)
+{ where: { status: 1, delStatus: false } }
+
+// 排序 (必须使用 OrderEnum)
+import { OrderEnum } from "@fastcar/core/db";
+{ orders: { createdAt: OrderEnum.desc } }
+{ orders: { createdAt: OrderEnum.asc } }
+
+// 分页
+{ offest: 0, limit: 10 }
+```
+
+#### 事务处理
 
-在 `application.yml` 中配置多个数据源，Service 中通过指定数据源名称切换。
+```typescript
+import { SqlSession } from "@fastcar/core/annotation";
+import { MysqlDataSourceManager } from "@fastcar/mysql";
+
+@Service
+class OrderService {
+  @Autowired
+  private dsm!: MysqlDataSourceManager;
 
-#### 事务
+  @Autowired
+  private orderMapper!: OrderMapper;
 
-使用 `@Transactional`（如果框架提供）或手动通过 `SqlSession` 控制事务边界。
+  @Autowired
+  private inventoryMapper!: InventoryMapper;
+
+  async createOrderWithTransaction(order: Order, inventoryUpdate: any) {
+    const sessionId = await this.dsm.beginTransaction();
+    
+    try {
+      // 插入订单
+      await this.orderMapper.saveOne(order, undefined, sessionId);
+      
+      // 更新库存
+      await this.inventoryMapper.update({
+        where: { id: inventoryUpdate.id },
+        row: { quantity: inventoryUpdate.quantity }
+      }, undefined, sessionId);
+      
+      // 提交事务
+      await this.dsm.commit(sessionId);
+      
+      return true;
+    } catch (error) {
+      // 回滚事务
+      await this.dsm.rollback(sessionId);
+      throw error;
+    }
+  }
+}
+```
 
 ### PostgreSQL (@fastcar/pgsql)
 
@@ -208,6 +480,8 @@ import User from "./User";
 @Entity(User)
 @Repository
 class UserMapper extends PgsqlMapper<User> {}
+
+export default UserMapper;
 ```
 
 用法与 `MysqlMapper` 基本一致，支持相同的查询条件和 CRUD 操作。
@@ -236,6 +510,8 @@ import User from "./User";
 @Entity(User)
 @Repository
 class UserMapper extends MongoMapper<User> {}
+
+export default UserMapper;
 ```
 
 ### Redis (@fastcar/redis)
@@ -252,7 +528,7 @@ class APP {}
 export default new APP();
 ```
 
-#### 使用 RedisTemplate
+#### 使用 RedisClient
 
 ```typescript
 import { Service, Autowired } from "@fastcar/core/annotation";
@@ -274,6 +550,28 @@ class CacheService {
   async del(key: string) {
     await this.redis.del(key);
   }
+
+  async expire(key: string, seconds: number) {
+    await this.redis.expire(key, seconds);
+  }
+
+  // Hash 操作
+  async hset(key: string, field: string, value: string) {
+    await this.redis.hset(key, field, value);
+  }
+
+  async hget(key: string, field: string) {
+    return this.redis.hget(key, field);
+  }
+
+  // List 操作
+  async lpush(key: string, value: string) {
+    await this.redis.lpush(key, value);
+  }
+
+  async rpop(key: string) {
+    return this.redis.rpop(key);
+  }
 }
 ```
 
@@ -329,6 +627,10 @@ mysql:
   database: mydb
   username: root
   password: password
+  # 连接池配置
+  connectionLimit: 10
+  # 是否使用预处理语句
+  useServerPrepStmts: true
 
 pgsql:
   host: localhost
@@ -372,3 +674,11 @@ npm i @fastcar/core @fastcar/mysql @fastcar/redis
 # 4. 启动应用
 npm run debug
 ```
+
+## 注意事项
+
+1. **排序必须使用 OrderEnum**：`orders: { createdAt: OrderEnum.desc }`，不能使用字符串 `"DESC"`
+2. **主键查询**：`selectByPrimaryKey` 和 `updateByPrimaryKey` 需要传入包含主键字段的对象
+3. **时间范围查询**：使用 `$gte` 和 `$lte` 运算符
+4. **批量插入**：`saveList` 会自动分批处理（每批1000条）
+5. **软删除**：建议使用 `update` 方法更新 `delStatus` 字段，而不是物理删除

package/skills/fastcar-framework/SKILL.md

@@ -64,58 +64,210 @@ app.start();
 
 ### Web 开发 (@fastcar/koa)
 
+**正确的路由装饰器使用方式：**
+
 ```typescript
-import { GET, POST, REQUEST, Body, Param } from "@fastcar/koa/annotation";
+import { GET, POST, REQUEST } from "@fastcar/koa/annotation";
 
 @Controller
 @REQUEST("/api/users")
 class UserController {
-  @GET
+  // GET 请求 - 无路径参数时必须有括号
+  @GET()
   async list() {
     return { data: [] };
   }
   
+  // GET 请求 - 有路径参数
   @GET("/:id")
-  async getById(@Param("id") id: string) {
+  async getById(id: string) {
     return { id };
   }
   
-  @POST
-  async create(@Body user: UserDTO) {
+  // POST 请求
+  @POST()
+  async create(body: UserDTO) {
     return { created: true };
   }
 }
 ```
 
+**⚠️ 重要：FastCar 没有 `@Body`, `@Param`, `@Query` 装饰器**
+
+- 请求参数直接作为方法参数传入
+- GET 请求参数通过方法参数直接获取
+- POST 请求体通过 `body` 参数获取
+- 路径参数通过方法参数直接获取
+
 ### 数据库 (@fastcar/mysql)
 
+**实体定义：**
+
 ```typescript
-import { Repository, Table, Field, PrimaryKey, SqlSession } from "@fastcar/mysql/annotation";
+import { Table, Field, DBType, PrimaryKey, NotNull, Size } from "@fastcar/core/annotation";
 
 @Table("users")
 class User {
-  @PrimaryKey
   @Field("id")
+  @DBType("int")
+  @PrimaryKey
   id!: number;
   
   @Field("name")
+  @DBType("varchar")
+  @NotNull
+  @Size({ maxSize: 50 })
   name!: string;
 }
+```
 
+**Mapper 定义：**
+
+```typescript
+import { Entity, Repository } from "@fastcar/core/annotation";
+import { MysqlMapper } from "@fastcar/mysql";
+
+@Entity(User)
 @Repository
-class UserRepository {
-  @SqlSession
-  private session!: SqlSession;
+class UserMapper extends MysqlMapper<User> {}
+
+export default UserMapper;
+```
+
+**Service 中使用：**
+
+```typescript
+import { Service, Autowired } from "@fastcar/core/annotation";
+import { OrderEnum } from "@fastcar/core/db";
+import UserMapper from "./UserMapper";
+
+@Service
+class UserService {
+  @Autowired
+  private userMapper!: UserMapper;
+
+  // 查询列表
+  async getUsers() {
+    return this.userMapper.select({
+      where: { status: 1 },
+      orders: { createTime: OrderEnum.desc },
+      limit: 10
+    });
+  }
+
+  // 查询单个
+  async getUser(id: number) {
+    return this.userMapper.selectOne({ where: { id } });
+  }
+
+  // 根据主键查询
+  async getUserById(id: number) {
+    return this.userMapper.selectByPrimaryKey({ id } as User);
+  }
+
+  // 插入
+  async createUser(user: User) {
+    return this.userMapper.saveOne(user);
+  }
+
+  // 更新
+  async updateUser(id: number, data: Partial<User>) {
+    return this.userMapper.update({ where: { id }, row: data });
+  }
+
+  // 根据主键更新
+  async updateById(user: User) {
+    return this.userMapper.updateByPrimaryKey(user);
+  }
+
+  // 删除
+  async deleteUser(id: number) {
+    return this.userMapper.delete({ where: { id } });
+  }
+
+  // 统计
+  async count() {
+    return this.userMapper.count({});
+  }
+}
+```
+
+### 表单验证 (@fastcar/core)
+
+**正确的表单验证方式：**
+
+```typescript
+import { ValidForm, NotNull, Size, Rule } from "@fastcar/core/annotation";
+
+// DTO 类定义在单独的文件中，如 dto/UserDTO.ts
+class UserDTO {
+  @NotNull
+  name!: string;
   
-  async findById(id: number) {
-    return this.session.findById(User, id);
+  @Size({ minSize: 1, maxSize: 150 })
+  age!: number;
+}
+
+@Controller
+@REQUEST("/api/users")
+class UserController {
+  
+  // GET 请求 - 无需表单验证
+  @GET()
+  async list(page: number = 1, pageSize: number = 10) {
+    return { page, pageSize, data: [] };
+  }
+
+  // POST 请求 - 使用 @ValidForm + @Rule 进行表单验证
+  @ValidForm
+  @POST()
+  async create(@Rule() body: UserDTO) {
+    // 参数会自动校验，如果校验失败会抛出异常
+    const { name, age } = body;
+    return this.userService.create({ name, age });
   }
 }
 ```
 
+**表单验证规则：**
+
+| 装饰器 | 用途 | 示例 |
+|--------|------|------|
+| `@ValidForm` | 开启方法参数校验 | 放在方法上 |
+| `@Rule()` | 标记校验对象 | 放在 DTO 参数前 |
+| `@NotNull` | 参数不能为空 | 放在 DTO 字段上 |
+| `@Size({min, max})` | 大小限制 | 放在 DTO 字段上 |
+
+**⚠️ 常见错误：**
+
+❌ **错误** - 使用不存在的装饰器：
+```typescript
+// 这些装饰器在 FastCar 中不存在！
+import { Body, Param, Query } from "@fastcar/koa/annotation"; // ❌ 错误
+
+@GET("/:id")
+async getById(@Param("id") id: string) { ... } // ❌ 错误
+
+@POST()
+async create(@Body body: UserDTO) { ... } // ❌ 错误
+```
+
+✅ **正确** - 直接使用方法参数：
+```typescript
+@GET("/:id")
+async getById(id: string) { ... } // ✅ 正确
+
+@POST()
+async create(body: UserDTO) { ... } // ✅ 正确
+
+@GET()
+async list(page: number = 1) { ... } // ✅ 正确
+```
+
 ### Redis (@fastcar/redis)
 
 ```typescript
+import { Service, Autowired } from "@fastcar/core/annotation";
 import { RedisClient } from "@fastcar/redis/annotation";
 
 @Service
@@ -262,6 +414,7 @@ export default new APP();
 template/
 ├── src/
 │   ├── controller/       # 控制器（web/cos）
+│   ├── dto/              # DTO 类（表单验证）
 │   ├── middleware/       # 中间件（web/cos）
 │   ├── model/            # 数据模型
 │   └── app.ts            # 应用入口
@@ -533,29 +686,6 @@ class LifecycleService {
 }
 ```
 
-## 表单验证
-
-```typescript
-import { ValidForm, NotNull, Size, Rule } from "@fastcar/core/annotation";
-
-class UserDTO {
-  @NotNull
-  name!: string;
-  
-  @Size({ minSize: 1, maxSize: 150 })
-  age!: number;
-}
-
-@Controller
-class UserController {
-  @ValidForm
-  createUser(@Rule() @NotNull user: UserDTO) {
-    // 参数自动校验
-    return this.userService.create(user);
-  }
-}
-```
-
 ## 工具类
 
 ```typescript
@@ -655,6 +785,71 @@ npx tsc --init
 # 5. 创建入口文件和配置文件，开始开发
 ```
 
+## 常见错误与注意事项
+
+### 1. 路由装饰器必须有括号
+
+❌ **错误：**
+```typescript
+@GET
+async list() { }
+```
+
+✅ **正确：**
+```typescript
+@GET()
+async list() { }
+```
+
+### 2. 不要使用不存在的装饰器
+
+❌ **错误：**
+```typescript
+import { Body, Param, Query } from "@fastcar/koa/annotation";
+
+@GET("/:id")
+async getById(@Param("id") id: string) { }
+
+@POST()
+async create(@Body body: UserDTO) { }
+```
+
+✅ **正确：**
+```typescript
+@GET("/:id")
+async getById(id: string) { }
+
+@POST()
+async create(body: UserDTO) { }
+```
+
+### 3. 表单验证使用 @ValidForm + @Rule
+
+❌ **错误：**
+```typescript
+@POST()
+async create(@Body body: UserDTO) { }
+```
+
+✅ **正确：**
+```typescript
+@ValidForm
+@POST()
+async create(@Rule() body: UserDTO) { }
+```
+
+### 4. DTO 类放在单独文件夹
+
+推荐项目结构：
+```
+src/
+├── controller/     # 控制器
+├── dto/            # DTO 类（表单验证）
+├── service/        # 服务层
+├── model/          # 数据模型
+└── app.ts
+```
+
 ## 参考资源
 
 - 详细 API 文档：[references/api-reference.md](references/api-reference.md)

package/src/reverse.js

@@ -1,6 +1,8 @@
 const path = require("path");
 const fs = require("fs");
 const process = require("process");
+const yaml = require("yaml");
+const inquirer = require("inquirer");
 
 // 默认配置文件模板
 const defaultConfig = {
@@ -25,18 +27,70 @@ const defaultConfig = {
   ignoreCamelcase: false,
 };
 
+// 支持的配置文件名
+const CONFIG_FILES = {
+  json: "reverse.config.json",
+  yml: "reverse.config.yml",
+};
+
+// 查找已存在的配置文件
+function findExistingConfig(cwd) {
+  for (const ext of ["yml", "json"]) {
+    const configPath = path.join(cwd, CONFIG_FILES[ext]);
+    if (fs.existsSync(configPath)) {
+      return { ext, configPath };
+    }
+  }
+  return null;
+}
+
+// 读取配置文件
+function readConfig(configPath, ext) {
+  const content = fs.readFileSync(configPath, "utf-8");
+  if (ext === "yml") {
+    return yaml.parse(content);
+  }
+  return JSON.parse(content);
+}
+
+// 写入配置文件
+function writeConfig(configPath, ext, config) {
+  if (ext === "yml") {
+    fs.writeFileSync(configPath, yaml.stringify(config));
+  } else {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  }
+}
+
 // 生成默认配置文件
-function initReverseConfig() {
+async function initReverseConfig() {
   const cwd = process.cwd();
-  const configPath = path.join(cwd, "reverse.config.json");
 
-  // 检查是否已存在
-  if (fs.existsSync(configPath)) {
-    console.log("⚠️  reverse.config.json 配置文件已存在");
+  // 检查是否已存在任何格式的配置文件
+  const existing = findExistingConfig(cwd);
+  if (existing) {
+    console.log(`⚠️  ${path.basename(existing.configPath)} 配置文件已存在`);
     console.log("   如需重新生成，请先删除现有文件");
     return;
   }
 
+  // 交互式选择配置格式
+  const answer = await inquirer.prompt([
+    {
+      type: "list",
+      name: "format",
+      message: "选择配置文件格式:",
+      choices: [
+        { name: "YAML (reverse.config.yml)", value: "yml" },
+        { name: "JSON (reverse.config.json)", value: "json" },
+      ],
+      default: "yml",
+    },
+  ]);
+
+  const ext = answer.format;
+  const configPath = path.join(cwd, CONFIG_FILES[ext]);
+
   // 填充默认路径
   const config = {
     ...defaultConfig,
@@ -45,8 +99,8 @@ function initReverseConfig() {
   };
 
   try {
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-    console.log("✅ 已生成 reverse.config.json 配置文件");
+    writeConfig(configPath, ext, config);
+    console.log(`✅ 已生成 ${CONFIG_FILES[ext]} 配置文件`);
     console.log("📁 文件路径:", configPath);
     console.log("\n💡 请根据需要修改以下配置:");
     console.log("   • tables: 要逆向生成的表名数组");
@@ -72,11 +126,31 @@ async function reverseGenerate(args = []) {
   }
 
   // 读取配置文件
-  const configPath = path.join(cwd, "reverse.config.json");
-  if (!fs.existsSync(configPath)) {
-    console.log("❌ 未找到 reverse.config.json 配置文件");
+  const existing = findExistingConfig(cwd);
+  if (!existing) {
+    console.log("❌ 未找到 reverse.config.yml 或 reverse.config.json 配置文件");
     console.log("   请在项目根目录创建该文件，格式如下：");
     console.log(`
+YAML 格式 (reverse.config.yml):
+  tables: [test]
+  modelDir: ${cwd.replace(/\\/g, "/")}/src/models
+  mapperDir: ${cwd.replace(/\\/g, "/")}/src/mappers
+  dbConfig:
+    host: localhost
+    port: 3306
+    user: root
+    password: password
+    database: test_db
+  style:
+    tabWidth: 4
+    printWidth: 200
+    trailingComma: es5
+    useTabs: true
+    parser: typescript
+    endOfLine: crlf
+  ignoreCamelcase: false
+
+JSON 格式 (reverse.config.json):
 {
   "tables": ["test"],
   "modelDir": "${cwd.replace(/\\/g, "/")}/src/models",
@@ -104,9 +178,9 @@ async function reverseGenerate(args = []) {
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    config = readConfig(existing.configPath, existing.ext);
   } catch (error) {
-    console.log("❌ 配置文件解析失败:", error.message);
+    console.log(`❌ 配置文件 ${path.basename(existing.configPath)} 解析失败:`, error.message);
     return;
   }
 

package/src/skill-targets.js

@@ -9,9 +9,9 @@ const TARGETS = {
     name: 'Kimi Code CLI',
     description: 'Kimi Code extension for VS Code',
     globalPaths: {
-      win32: path.join(os.homedir(), 'AppData/Roaming/Code/User/globalStorage/moonshot-ai.kimi-code/skills'),
-      darwin: path.join(os.homedir(), '.config/agents/skills'),
-      linux: path.join(os.homedir(), '.config/agents/skills')
+      win32: path.join(os.homedir(), '.kimi/skills'),
+      darwin: path.join(os.homedir(), '.kimi/skills'),
+      linux: path.join(os.homedir(), '.kimi/skills')
     },
     localPath: '.agents/skills'
   },

package/src/skill.js

@@ -197,9 +197,11 @@ async function installSkill(skillName, options = {}) {
       console.log(`✅ 成功 ${modeText} 安装 ${skillName}`);
       console.log(`   位置: ${destPath}`);
       console.log();
-      console.log('提示:');
-      console.log('  1. 重启你的 AI agent 以使用 skill');
-      console.log(`  2. 在对话中询问关于 "${skillName}" 的内容`);
+      console.log('⚠️  重要: 请重启你的 AI agent 以加载新安装的 skill！');
+      console.log();
+      console.log('重启后，你可以在对话中:');
+      console.log(`  • 直接询问关于 "${skillName}" 的内容`);
+      console.log(`  • 使用 /skill:${skillName} 强制加载该 skill`);
     } else {
       console.log('❌ 安装验证失败');
     }