@lovrabet/cli 1.2.5-beta.1 → 1.2.5-beta.3

package/templates/skills/.trae/skills/lovrabet/SKILL.md

@@ -0,0 +1,258 @@
+# Lovrabet 开发工作流
+
+当用户请求与 Lovrabet 平台相关的开发任务时，使用此工作流。
+
+## 前置条件
+
+此工作流假设 Lovrabet MCP 服务器已在 claude code 的 MCP 设置中配置完成。MCP 工具**直接可用**，需要时请使用。
+
+## 重要规则
+
+1. **直接使用 MCP 工具**：当用户请求创建/验证 SQL 或查询数据集时，**直接调用 MCP 工具**。不要生成脚本或让用户切换到其他工具。
+2. **5步 SQL 工作流**：创建自定义 SQL 时必须严格遵循以下顺序。
+3. **禁止生成脚本**：不要为 MCP 操作生成脚本 - 直接使用工具。
+4. **禁止命令行调用 MCP**：禁止运行 `npx @lovrabet/dataset-mcp-server` 等命令。MCP 工具只能通过 MCP 协议调用。
+5. **MCP 未配置提示**：如果尝试调用 Lovrabet MCP 工具但发现工具不可用，主动告知用户 MCP 未配置并提供配置方法。
+6. **完全自动执行**：创建自定义 SQL 时，**自动执行全部 5 步，不要询问用户任何输入**（sqlCode、sqlName、描述等）。根据 SQL 功能自动生成合适的名称。
+
+## 工作流步骤
+
+### 步骤 1: 了解需求
+分析用户请求，提取关键信息：
+- 需要操作哪个数据集？
+- 需要做什么操作（CRUD、自定义 SQL）？
+- 是否需要生成代码？
+
+### 步骤 2: 探索数据集（使用 MCP）
+
+如果不确定数据集信息，先探索：
+
+```
+请使用 list_datasets 列出所有可用的数据集
+```
+
+或搜索：
+
+```
+请使用 searchDatasets 搜索包含 "用户" 的数据集
+```
+
+### 步骤 3: 获取数据集详情
+
+```
+请使用 get_dataset_detail 获取数据集详情
+datasetCode: <数据集代码>
+```
+
+重点关注：
+- `fields` - 字段列表及其元数据
+- `operations` - 支持的操作列表
+- `basic.tableName` - 实际表名
+
+### 步骤 4: 生成 SDK 代码（可选）
+
+如果需要生成代码：
+
+```
+请使用 generate_sdk_code 生成 SDK 调用代码
+datasetCode: <数据集代码>
+operationName: <操作名称>
+includeImports: true
+```
+
+### 步骤 5: 执行操作
+
+根据需求调用相应方法：
+
+**列表查询 (CRUD)**
+```typescript
+// 数据集: {datasetName} | 数据表: {tableName}
+const result = await client.models.{modelName}.filter({
+  where: { status: { $eq: "active" } },
+  select: ["id", "name"],
+  currentPage: 1,
+  pageSize: 20,
+});
+```
+
+**自定义 SQL**
+```
+请使用 list_sql_queries 列出可用的 SQL 查询
+```
+
+**执行 SQL**
+```
+请使用 execute_custom_sql 执行 SQL 查询
+sqlCode: <SQL 代码>
+```
+
+## 常见工作流
+
+### 工作流 1: 创建列表查询页面
+
+用户说："创建用户列表页面"
+
+**直接调用：**
+1. `list_datasets` - 查找用户数据集
+2. `get_dataset_detail(datasetCode: "users")` - 获取字段
+3. `generate_sdk_code(datasetCode: "users", operationName: "filter")` - 生成代码
+4. 然后结合 AntD Table 组件实现页面
+
+### 工作流 2: 创建自定义 SQL 报表
+
+用户说："创建一个按月统计的订单报表"
+
+**直接调用：**
+1. `list_sql_queries` - 检查 SQL 是否存在
+2. `get_dataset_detail(datasetCode: "orders")` - 获取表结构
+3. `validate_sql_content(sqlContent: "SELECT DATE_FORMAT(...)")` - 验证 SQL
+4. `save_or_update_custom_sql(...)` - 保存 SQL
+5. `execute_custom_sql(sqlCode: "monthly_orders")` - 测试执行
+6. 然后生成代码并使用 AntD Charts 展示报表
+
+## Filter 查询规范（关键）
+
+### 基本结构
+
+```typescript
+const result = await client.models.<modelName>.filter({
+  where: {
+    status: { $eq: "active" },      // 必须使用操作符
+    age: { $gte: 18, $lte: 65 },
+  },
+  select: ["id", "name", "email"],     // NOT "fields"
+  orderBy: [{ createTime: "desc" }],     // NOT "sort"
+  currentPage: 1,                     // NOT "page"
+  pageSize: 20,                       // NOT "limit"
+});
+```
+
+### 操作符速查
+
+| 场景 | 操作符 | 示例 |
+|------|-------|------|
+| 等于 | `$eq` | `{ status: { $eq: "active" } }` |
+| 不等于 | `$ne` | `{ status: { $ne: "deleted" } }` |
+| 大于等于 | `$gte` | `{ age: { $gte: 18 } }` |
+| 小于等于 | `$lte` | `{ age: { $lte: 65 } }` |
+| 大于 | `$gt` | `{ price: { $gt: 100 } }` |
+| 小于 | `$lt` | `{ price: { $lt: 1000 } }` |
+| 在数组中 | `$in` | `{ type: { $in: ["A", "B"] } }` |
+| 包含 | `$contain` | `{ name: { $contain: "keyword" } }` |
+| 开头是 | `$startWith` | `{ email: { $startWith: "admin" } }` |
+| 结尾是 | `$endWith` | `{ domain: { $endWith: ".com" } }` |
+| 并且 | `$and` | `{ $and: [{ age: { $gte: 18 } }, { status: { $eq: "active" } }] }` |
+| 或者 | `$or` | `{ $or: [{ status: { $eq: "pending" } }, { status: { $eq: "processing" } }] }` |
+
+## SQL 创建规范（关键）
+
+### 5 步强制流程
+
+```
+查询 → 生成 → 验证 → 保存 → 测试
+```
+
+1. **查询**: `list_sql_queries` - 检查 SQL 是否已存在
+2. **生成**: `get_dataset_detail` - 先获取表结构，确保字段名正确
+3. **验证**: `validate_sql_content` - 验证 SQL 语法和结构
+4. **保存**: `save_or_update_custom_sql` - 保存到平台
+5. **测试**: `execute_custom_sql` - 测试执行
+
+**禁止跳过任何步骤！**
+
+**SQL 命名规范（自动生成）：**
+- `sqlCode`：snake_case，描述性（如 `monthly_order_stats`、`user_activity_report`）
+- `sqlName`：中文名称描述功能（如 "月度订单统计"、"用户活跃度报表"）
+- `description`：简要描述 SQL 的功能
+
+**重要**：禁止询问用户 sqlCode、sqlName 或 description。根据上下文自动生成。
+
+## AntD UI 规范（关键）
+
+### 禁止项（强制）
+
+- ❌ 禁止 emoji
+- ❌ 禁止感叹号
+- ❌ 禁止 AI 味道的文案（"太棒了！"）
+- ❌ 禁止花哨颜色（#FF00FF，渐变）
+- ❌ 禁止使用 emoji 作为图标
+
+### 必需项
+
+- ✅ 使用 AntD token 颜色
+- ✅ 专业文案："保存"、"取消"、"操作成功"
+- ✅ 使用 @ant-design/icons
+
+```typescript
+// ✅ 正确
+<Button type="primary">保存</Button>
+<message.success("操作成功" />
+
+// ❌ 错误
+<Button>保存！</Button>
+<message.success="🎉 操作成功！" />
+```
+
+## 返回格式
+
+### Filter 返回
+
+```typescript
+{
+  tableData: Array<{           // 数据列表
+  total: number,              // 总数
+}>
+```
+
+### Execute SQL 返回
+
+```typescript
+{
+  execSuccess: boolean,        // SQL 是否执行成功
+  execResult?: Array<any>,      // 查询结果（成功时）
+  execError?: string,         // 错误信息（失败时）
+  rowCount?: number,         // 返回的行数
+  message: string,           // 可读消息
+  fixSuggestions?: Array<SqlFixSuggestion>  // 错误修复建议
+}
+```
+
+## CLI 命令参考
+
+```bash
+lovrabet api pull              # 拉取并生成 API 定义
+lovrabet menu sync             # 同步菜单到平台
+lovrabet menu update           # 更新菜单 CDN 资源
+lovrabet skill --help          # 显示技能包帮助
+lovrabet skill install <ide>   # 安装技能包到项目
+```
+
+## 开发者指南位置
+
+安装后，详细指南位于：
+- `.lovrabet/skill/.shared/guides/01-filter-query/guide.md`
+- `.lovrabet/skill/.shared/guides/02-mcp-sql-workflow/guide.md`
+- `.lovrabet/skill/.shared/guides/03-antd-style/guide.md`
+- `.lovrabet/skill/.shared/guides/04-troubleshooting/guide.md`
+- `.lovrabet/skill/.shared/guides/05-api-integration/guide.md`
+- `.lovrabet/skill/.shared/guides/06-menu-management/guide.md`
+- `.lovrabet/skill/.shared/guides/07-backend-function/guide.md`
+
+## MCP 配置说明
+
+当 MCP 工具不可用时，主动告知用户：
+
+```
+Lovrabet MCP 服务器未配置，请先配置：
+
+运行: lovrabet mcp install claude
+
+这将输出 claude mcp add 命令供您手动执行。
+```
+
+## 注意事项
+
+- 每次调用 SDK 前添加注释：`// 数据集: <数据集名称> | 数据表: <表名>`
+- 所有 SDK 调用必须用 try-catch 包裹
+- filter 查询必须使用 filter() 方法，不要用 getList()
+- 自定义 SQL 必须先验证字段名与实际表结构匹配

package/templates/skills/.windsurf/workflows/lovrabet.md

@@ -234,6 +234,7 @@ lovrabet skill install <ide>   # 安装技能包到项目
 - `.lovrabet/skill/.shared/guides/04-troubleshooting/guide.md`
 - `.lovrabet/skill/.shared/guides/05-api-integration/guide.md`
 - `.lovrabet/skill/.shared/guides/06-menu-management/guide.md`
+- `.lovrabet/skill/.shared/guides/07-backend-function/guide.md`
 
 ## MCP 配置说明