@lovrabet/cli 1.2.4 → 1.2.5-beta.2

package/templates/skills/.shared/guides/01-filter-query/guide.md

@@ -0,0 +1,300 @@
+# Filter 查询构建规范
+
+> **目标**：学会正确使用 SDK `filter()` 方法，避免常见错误
+
+## 🎯 为什么这个技能重要？
+
+`filter()` 是 Lovrabet SDK 中最常用的查询方法，但也是最容易出错的地方。根据统计，**80% 的 API 错误都与 filter 使用不当有关**。
+
+### 常见错误现象
+- 查询没有结果，但数据明明存在
+- 报错 "参数格式不正确"
+- 分页不生效
+- 排序没有效果
+
+---
+
+## 📖 基本结构
+
+### 最简单的 filter 调用
+
+```typescript
+// 数据集: 用户信息 | 数据表: users
+const result = await client.models.users.filter({
+  currentPage: 1,
+  pageSize: 20,
+});
+
+console.log(result.tableData); // 数据列表
+console.log(result.total);     // 总数
+```
+
+### 完整的 filter 调用
+
+```typescript
+const result = await client.models.users.filter({
+  where: { /* 查询条件 */ },
+  select: ['id', 'name', 'email'],  // 返回哪些字段
+  orderBy: [{ createTime: 'desc' }], // 排序
+  currentPage: 1,
+  pageSize: 20,
+});
+```
+
+---
+
+## 🔑 关键操作符
+
+### 比较操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ status: { $eq: 'active' } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
+| `$gte` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lte` | 小于等于 | `{ age: { $lte: 65 } }` |
+| `$gt` | 大于 | `{ price: { $gt: 100 } }` |
+| `$lt` | 小于 | `{ price: { $lt: 1000 } }` |
+
+### 字符串操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$contain` | 包含 | `{ name: { $contain: 'keyword' } }` |
+| `$startWith` | 开头匹配 | `{ email: { $startWith: 'admin' } }` |
+| `$endWith` | 结尾匹配 | `{ domain: { $endWith: '.com' } }` |
+
+### 集合操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$in` | 包含于 | `{ type: { $in: ['A', 'B', 'C'] } }` |
+
+### 逻辑操作符
+
+```typescript
+// $and - 所有条件都要满足
+where: {
+  $and: [
+    { age: { $gte: 18 } },
+    { status: { $eq: 'active' } }
+  ]
+}
+
+// $or - 任一条件满足即可
+where: {
+  $or: [
+    { status: { $eq: 'pending' } },
+    { status: { $eq: 'processing' } }
+  ]
+}
+
+// 嵌套组合
+where: {
+  $and: [
+    { age: { $gte: 18 } },
+    {
+      $or: [
+        { country: { $eq: '中国' } },
+        { country: { $eq: '美国' } }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## ⚠️ 10 个常见错误
+
+### 错误 1：忘记使用操作符
+
+```typescript
+// ❌ 错误：直接写值
+where: { status: 'active' }
+
+// ✅ 正确：使用 $eq 操作符
+where: { status: { $eq: 'active' } }
+```
+
+### 错误 2：参数名错误
+
+```typescript
+// ❌ 错误：使用 fields
+fields: ['id', 'name']
+
+// ✅ 正确：使用 select
+select: ['id', 'name']
+```
+
+### 错误 3：排序参数名错误
+
+```typescript
+// ❌ 错误：使用 sort 或 sortList
+sort: [{ createTime: 'desc' }]
+
+// ✅ 正确：使用 orderBy
+orderBy: [{ createTime: 'desc' }]
+```
+
+### 错误 4：使用 SQL 语法
+
+```typescript
+// ❌ 错误：使用 LIKE
+where: { name: { LIKE: '%keyword%' } }
+
+// ✅ 正确：使用 $contain
+where: { name: { $contain: 'keyword' } }
+```
+
+### 错误 5：使用字符串比较
+
+```typescript
+// ❌ 错误：字符串形式的比较
+where: { age: '>= 18' }
+
+// ✅ 正确：使用操作符
+where: { age: { $gte: 18 } }
+```
+
+### 错误 6：区间查询操作符错误
+
+```typescript
+// ❌ 错误：使用 $gt 和 $lt
+where: { age: { $gt: 18, $lt: 65 } }
+
+// ✅ 正确：使用 $gte 和 $lte
+where: { age: { $gte: 18, $lte: 65 } }
+```
+
+### 错误 7：orderBy 不是数组
+
+```typescript
+// ❌ 错误：字符串格式
+orderBy: 'createTime desc'
+
+// ✅ 正确：数组格式
+orderBy: [{ createTime: 'desc' }]
+```
+
+### 错误 8：select 不是数组
+
+```typescript
+// ❌ 错误：字符串格式
+select: 'id,name,status'
+
+// ✅ 正确：数组格式
+select: ['id', 'name', 'status']
+```
+
+### 错误 9：$or 值不是数组
+
+```typescript
+// ❌ 错误：对象格式
+where: { $or: { status: 'A', type: 'X' } }
+
+// ✅ 正确：数组格式
+where: { $or: [
+  { status: { $eq: 'A' } },
+  { type: { $eq: 'X' } }
+]}
+```
+
+### 错误 10：分页参数名错误
+
+```typescript
+// ❌ 错误：使用 page/limit
+page: 1,
+limit: 20
+
+// ✅ 正确：使用 currentPage/pageSize
+currentPage: 1,
+pageSize: 20
+```
+
+---
+
+## 📝 实战示例
+
+### 场景 1：带搜索的用户列表
+
+```typescript
+// 数据集: 用户信息 | 数据表: users
+async function searchUsers(keyword: string, page: number = 1) {
+  const result = await client.models.users.filter({
+    where: keyword ? {
+      $or: [
+        { name: { $contain: keyword } },
+        { email: { $contain: keyword } },
+        { phone: { $contain: keyword } },
+      ]
+    } : undefined,
+    select: ['id', 'name', 'email', 'phone', 'status'],
+    orderBy: [{ createTime: 'desc' }],
+    currentPage: page,
+    pageSize: 20,
+  });
+
+  return {
+    list: result.tableData,
+    total: result.total,
+    hasMore: page * 20 < result.total,
+  };
+}
+```
+
+### 场景 2：筛选订单列表
+
+```typescript
+// 数据集: 订单 | 数据表: orders
+async function getOrders(filters: {
+  status?: string;
+  dateStart?: string;
+  dateEnd?: string;
+  minAmount?: number;
+}) {
+  const conditions = [];
+
+  if (filters.status) {
+    conditions.push({ status: { $eq: filters.status } });
+  }
+  if (filters.dateStart) {
+    conditions.push({ createTime: { $gte: filters.dateStart } });
+  }
+  if (filters.dateEnd) {
+    conditions.push({ createTime: { $lte: filters.dateEnd } });
+  }
+  if (filters.minAmount) {
+    conditions.push({ amount: { $gte: filters.minAmount } });
+  }
+
+  const result = await client.models.orders.filter({
+    where: conditions.length > 0 ? { $and: conditions } : undefined,
+    orderBy: [{ createTime: 'desc' }],
+    currentPage: 1,
+    pageSize: 50,
+  });
+
+  return result.tableData;
+}
+```
+
+---
+
+## ✅ 自检清单
+
+使用 filter 时，检查：
+
+- [ ] where 条件使用了操作符（`$eq`、`$gte` 等）
+- [ ] 参数名正确（`select` 不是 `fields`）
+- [ ] `orderBy` 和 `select` 是数组格式
+- [ ] 分页参数名是 `currentPage`/`pageSize`
+- [ ] 添加了数据集和数据表注释
+
+---
+
+## 🔗 相关资源
+
+- [常见场景示例](./examples.md) - 更多实际开发中的示例
+- [错误对照](./errors.md) - 完整的错误 vs 正确写法对照表
+- [自检清单](./checklist.md) - 详细的代码检查清单

package/templates/skills/.shared/guides/02-mcp-sql-workflow/guide.md

@@ -0,0 +1,272 @@
+# MCP SQL 创建工作流
+
+> **目标**：掌握创建自定义 SQL 的正确流程，避免因 SQL 错误导致的问题
+
+## 🎯 为什么这个技能重要？
+
+很多开发者在创建自定义 SQL 时跳过验证步骤，导致：
+- SQL 中的表名或字段名错误
+- 保存后才发现语法错误
+- 不确定 SQL 是否正确执行
+
+**按照正确的流程操作，可以避免 90% 的 SQL 相关问题。**
+
+---
+
+## 📋 5 步工作流（强制顺序）
+
+```
+第1步 → 第2步 → 第3步 → 第4步 → 第5步
+  ↓        ↓        ↓        ↓        ↓
+查询    生成      验证      保存      测试
+```
+
+---
+
+## 步骤详解
+
+### 第 1 步：查询现有 SQL
+
+**目标**：确认 SQL 是否已存在，避免重复创建。
+
+在 IDE 中使用 MCP 工具：
+
+```
+请使用 list_sql_queries 查询所有 SQL，查找包含 "用户统计" 的 SQL
+```
+
+或者在代码中：
+
+```typescript
+// 使用 MCP 工具查询
+const sqlList = await list_sql_queries({
+  keyword: '用户统计',
+});
+
+// 检查是否已存在
+const existingSql = sqlList.sqls.find(s => s.sqlName.includes('用户统计'));
+if (existingSql) {
+  console.log('SQL 已存在:', existingSql.sqlCode);
+  // 可以直接使用，或进入第3步验证
+}
+```
+
+### 第 2 步：获取表结构
+
+**目标**：先获取表结构，确保 SQL 中的字段名正确。
+
+在 IDE 中使用 MCP 工具：
+
+```
+请使用 get_dataset_detail 获取数据集 "customer" 的详情
+```
+
+或者在代码中：
+
+```typescript
+// 获取数据集详情
+const detail = await get_dataset_detail({
+  datasetCode: 'customer',
+});
+
+// 确认字段存在
+const fieldCodes = detail.fields.map(f => f.code);
+console.log('可用字段:', fieldCodes);
+
+// 检查字段
+if (!fieldCodes.includes('customerName')) {
+  throw new Error('字段 customerName 不存在');
+}
+```
+
+**重要**：获取表结构后，查看实际的字段名，不要凭记忆编写 SQL。
+
+### 第 3 步：验证 SQL 内容
+
+**目标**：在保存前验证 SQL 语法正确性。
+
+在 IDE 中使用 MCP 工具：
+
+```
+请使用 validate_sql_content 验证以下 SQL:
+SELECT id, customer_name, create_time
+FROM customer
+WHERE status = 1
+```
+
+或者在代码中：
+
+```typescript
+const validation = await validate_sql_content({
+  sqlContent: `
+    SELECT id, customer_name, create_time
+    FROM customer
+    WHERE status = 1
+  `,
+  dbId: detail.basic.database.dbId,
+});
+
+if (!validation.validation.valid) {
+  console.error('SQL 验证失败:', validation.validation.errors);
+  // 根据错误信息修改 SQL
+  return;
+}
+```
+
+### 第 4 步：保存 SQL
+
+**目标**：将验证通过的 SQL 保存到平台。
+
+在 IDE 中使用 MCP 工具：
+
+```
+请使用 save_or_update_custom_sql 保存以下 SQL:
+- SQL 名称: 客户统计查询
+- SQL 代码: customer_stats
+- SQL 内容: SELECT id, customer_name, create_time FROM customer WHERE status = 1
+```
+
+或者在代码中：
+
+```typescript
+const result = await save_or_update_custom_sql({
+  sqlName: '客户统计查询',
+  sqlCode: 'customer_stats',
+  sqlContent: `
+    SELECT id, customer_name, create_time
+    FROM customer
+    WHERE status = 1
+  `,
+  dbId: detail.basic.database.dbId,
+  verifyAfterSave: true,  // 保存后自动验证
+});
+
+console.log('SQL 保存成功:', result.sqlId);
+```
+
+### 第 5 步：测试执行
+
+**目标**：验证 SQL 能正确执行并返回预期数据。
+
+在 IDE 中使用 MCP 工具：
+
+```
+请使用 execute_custom_sql 执行 SQL "customer_stats"，测试是否正确
+```
+
+或者在代码中：
+
+```typescript
+const execResult = await execute_custom_sql({
+  sqlCode: 'customer_stats',
+  params: {}, // 如果有参数，在这里传入
+});
+
+if (!execResult.execSuccess) {
+  console.error('SQL 执行失败:', execResult.execError);
+} else {
+  console.log('SQL 执行成功，返回', execResult.rowCount, '行');
+  console.log('数据预览:', execResult.execResult?.slice(0, 3));
+}
+```
+
+---
+
+## ⚠️ 禁止行为
+
+| 禁止行为 | 后果 | 正确做法 |
+|---------|------|---------|
+| 跳过第1步，直接创建 | 可能创建重复的 SQL | 先查询现有 SQL |
+| 跳过第2步，直接写 SQL | 字段名可能错误 | 先获取表结构 |
+| 跳过第3步，直接保存 | 语法错误导致保存失败 | 先验证 SQL |
+| 保存后不测试 | 运行时才发现错误 | 必须测试执行 |
+| 假设 SQL code 存在 = SQL 正确 | SQL 内容可能有错误 | 必须验证 SQL 内容 |
+
+---
+
+## 📝 完整示例
+
+### 场景：创建客户月度统计 SQL
+
+```typescript
+// 第1步：查询现有 SQL
+const sqlList = await list_sql_queries({
+  keyword: '客户月度统计',
+});
+
+if (sqlList.sqls.length > 0) {
+  console.log('找到相关 SQL:', sqlList.sqls.map(s => s.sqlName));
+  // 如果已有合适的 SQL，直接使用
+}
+
+// 第2步：获取表结构
+const detail = await get_dataset_detail({
+  datasetCode: 'customer',
+});
+
+const tableName = detail.basic.tableName; // 实际表名
+const fields = detail.fields.map(f => f.code); // 实际字段名
+
+// 第3步：编写并验证 SQL
+const sqlContent = `
+  SELECT
+    DATE_FORMAT(create_time, '%Y-%m') as month,
+    COUNT(*) as customer_count,
+    COUNT(DISTINCT city) as city_count
+  FROM ${tableName}
+  WHERE status = 1
+  GROUP BY DATE_FORMAT(create_time, '%Y-%m')
+  ORDER BY month DESC
+`;
+
+const validation = await validate_sql_content({
+  sqlContent,
+  dbId: detail.basic.database.dbId,
+});
+
+if (!validation.validation.valid) {
+  console.error('SQL 验证失败:', validation.validation.errors);
+  return;
+}
+
+// 第4步：保存 SQL
+const saveResult = await save_or_update_custom_sql({
+  sqlName: '客户月度统计',
+  sqlCode: 'customer_monthly_stats',
+  sqlContent,
+  dbId: detail.basic.database.dbId,
+  verifyAfterSave: true,
+});
+
+// 第5步：测试执行
+const testResult = await execute_custom_sql({
+  sqlCode: 'customer_monthly_stats',
+});
+
+if (testResult.execSuccess) {
+  console.log('✓ SQL 创建成功！');
+  console.log('返回行数:', testResult.rowCount);
+} else {
+  console.error('✗ SQL 执行失败:', testResult.execError);
+}
+```
+
+---
+
+## ✅ 自检清单
+
+创建自定义 SQL 时，确认：
+
+- [ ] 第1步：查询了现有 SQL，避免重复
+- [ ] 第2步：获取了表结构，确认字段名
+- [ ] 第3步：验证了 SQL 语法
+- [ ] 第4步：保存成功
+- [ ] 第5步：测试执行成功
+- [ ] SQL 只包含 SELECT 查询（没有 INSERT/UPDATE/DELETE）
+
+---
+
+## 🔗 相关资源
+
+- [步骤详解](./step-by-step.md) - 每一步的详细说明和注意事项
+- [自检清单](./checklist.md) - 详细的检查清单