@lovrabet/cli 1.2.3 → 1.2.5-beta.1

package/templates/skills/.shared/guides/03-antd-style/guide.md

@@ -0,0 +1,227 @@
+# AntD UI 开发规范
+
+> **目标**：统一 AntD 组件使用风格，避免代码充满 AI 味道
+
+## 🎯 为什么这个技能重要？
+
+ToB 企业应用需要**专业、简洁**的界面风格。但 AI 生成的代码往往充满：
+- emoji：✨ 🚀 💡 🎯 📊
+- 花哨的文案："太棒了！"、"让我们开始吧！"
+- 过度的动画和渐变
+
+这会让应用看起来不专业，用户会质疑系统的可靠性。
+
+---
+
+## 🚫 7 条禁止规则
+
+### 1. 禁止 emoji
+
+```tsx
+// ❌ 错误
+<Button>🚀 开始使用</Button>
+<message.success="🎉 操作成功！" />
+
+// ✅ 正确
+<Button>开始使用</Button>
+<message.success="操作成功" />
+```
+
+### 2. 禁止 AI 味道的文案
+
+```tsx
+// ❌ 错误
+const messages = {
+  success: '太棒了！操作成功！',
+  confirm: '你确定要删除吗？',
+  cancel: '再想想吧~',
+};
+
+// ✅ 正确
+const messages = {
+  success: '操作成功',
+  confirm: '确定要删除吗？',
+  cancel: '取消',
+};
+```
+
+### 3. 禁止花哨的颜色
+
+```tsx
+// ❌ 错误
+const colors = {
+  primary: '#FF00FF',  // 霓虹粉
+  success: '#00FF00',  // 亮绿色
+};
+
+// ✅ 正确
+import { theme } from 'antd';
+const { token } = theme.useToken();
+const colors = {
+  primary: token.colorPrimary,
+  success: token.colorSuccess,
+};
+```
+
+### 4. 禁止感叹号
+
+```tsx
+// ❌ 错误
+<Button type="primary">保存！</Button>
+<Modal title="确认删除！">
+
+// ✅ 正确
+<Button type="primary">保存</Button>
+<Modal title="确认删除">
+```
+
+### 5. 禁止非专业称呼
+
+```tsx
+// ❌ 错误
+console.log('你好，小伙伴！');
+alert('亲，请填写完整信息哦');
+
+// ✅ 正确
+console.log('操作完成');
+alert('请填写完整信息');
+```
+
+### 6. 禁止过度动画
+
+```tsx
+// ❌ 错误：自定义花哨动画
+const customAnimation = keyframes`
+  0% { transform: scale(0) rotate(0deg); }
+  50% { transform: scale(1.2) rotate(180deg); }
+  100% { transform: scale(1) rotate(360deg); }
+`;
+
+// ✅ 正确：使用 AntD 内置动画
+import { fade-in } from 'antd/es/_util/motion';
+```
+
+### 7. 禁止自定义可爱图标
+
+```tsx
+// ❌ 错误：使用 emoji 作为图标
+<Button>🆕 新建</Button>
+<Button>✏️ 编辑</Button>
+
+// ✅ 正确：使用 @ant-design/icons
+import { PlusOutlined, EditOutlined } from '@ant-design/icons';
+<Button icon={<PlusOutlined />}>新建</Button>
+```
+
+---
+
+## 📝 组件规范
+
+### Button 按钮
+
+```tsx
+// ✅ 正确
+<Button type="primary" onClick={handleSave}>
+  保存
+</Button>
+<Button onClick={handleCancel}>取消</Button>
+<Button danger onClick={handleDelete}>删除</Button>
+
+// 带图标（可选）
+<Button icon={<PlusOutlined />} type="primary">
+  新建
+</Button>
+```
+
+### Modal 确认弹窗
+
+```tsx
+// ✅ 正确
+Modal.confirm({
+  title: '确认删除',
+  content: '确定要删除这条记录吗？',
+  okText: '确定',
+  cancelText: '取消',
+  onOk: handleDelete,
+});
+```
+
+### message 消息提示
+
+```tsx
+// ✅ 正确
+import { message } from 'antd';
+
+message.success('保存成功');
+message.error('操作失败，请重试');
+message.warning('请填写必填项');
+message.info('正在处理...');
+```
+
+### Form 表单
+
+```tsx
+// ✅ 正确
+<Form.Item
+  name="username"
+  label="用户名"
+  rules={[
+    { required: true, message: '请输入用户名' },
+    { min: 3, message: '用户名至少3个字符' },
+  ]}
+>
+  <Input placeholder="请输入用户名" />
+</Form.Item>
+```
+
+### Empty 空状态
+
+```tsx
+// ✅ 正确
+<Empty
+  description="暂无数据"
+  image={Empty.PRESENTED_IMAGE_SIMPLE}
+/>
+
+// 带操作按钮
+<Empty description="暂无数据">
+  <Button type="primary">创建数据</Button>
+</Empty>
+```
+
+---
+
+## 📋 文案规范对照表
+
+| 场景 | 正确 ✅ | 错误 ❌ |
+|------|--------|--------|
+| 按钮保存 | 保存 | 保存吧！ / 好的 / 确定 |
+| 按钮取消 | 取消 | 再想想 / 算了吧 |
+| 按钮删除 | 删除 | 删除掉 / 哎呀删除 |
+| 成功提示 | 操作成功 | 太棒了！ / 成功啦！ |
+| 失败提示 | 操作失败 | 哎呀出错了 / 失败了 |
+| 加载中 | 加载中... | 马上就好~ / 请稍等哦 |
+| 空状态 | 暂无数据 | 还没有数据哦~ / 空空如也 |
+| 确认删除 | 确定要删除吗？ | 你真的要删除吗？/ 三思而后行！ |
+
+---
+
+## ✅ 自检清单
+
+提交代码前，检查：
+
+- [ ] 没有 emoji（✨🚀💡等）
+- [ ] 没有感叹号（！）
+- [ ] 文案简洁专业（"保存"不是"保存吧"）
+- [ ] 使用 AntD token 颜色
+- [ ] 使用 @ant-design/icons 而非 emoji
+- [ ] 按钮文案为动词（保存/删除/编辑）
+- [ ] 提示文案中性（操作成功/操作失败）
+- [ ] 没有过度动画效果
+
+---
+
+## 🔗 相关资源
+
+- [组件规范](./components.md) - 各组件的详细规范
+- [自检清单](./checklist.md) - 详细的代码检查清单

package/templates/skills/.shared/guides/04-troubleshooting/guide.md

@@ -0,0 +1,426 @@
+# 问题排查指南
+
+> 遇到 Lovrabet 开发问题时，按照本指南快速定位和解决问题。
+
+## 🔍 快速诊断流程
+
+```
+1. 确认问题类型
+   ↓
+2. 查看错误信息
+   ↓
+3. 定位问题根源
+   ↓
+4. 应用解决方案
+   ↓
+5. 验证问题已解决
+```
+
+---
+
+## 常见问题
+
+### 问题 1: Filter 查询没有结果
+
+**现象**：
+```typescript
+const result = await client.models.users.filter({
+  where: { status: "active" },  // ❌ 忘记操作符！
+});
+console.log(result.tableData); // 空数组
+console.log(result.total);      // 0
+```
+
+**原因**：忘记使用操作符
+
+**解决方案**：
+```typescript
+// ✅ 正确：使用 $eq 操作符
+const result = await client.models.users.filter({
+  where: { status: { $eq: "active" } },
+});
+
+console.log(result.tableData); // 正确获取数据
+```
+
+---
+
+### 问题 2: 报错 "参数格式不正确"
+
+**现象**：
+```typescript
+const result = await client.models.users.filter({
+  fields: ["id", "name"],  // ❌ 错误：应该是 select
+  sort: [{ id: "desc" }],  // ❌ 错误：应该是 orderBy
+});
+```
+
+**原因**：参数名错误
+
+**解决方案**：
+```typescript
+// ✅ 正确的参数名
+const result = await client.models.users.filter({
+  select: ["id", "name"],     // 正确
+  orderBy: [{ id: "desc" }], // 正确
+  currentPage: 1,
+  参数名错误：fields → select
+  参数名错误：sort → orderBy
+  参数名错误：page → currentPage
+  参数名：limit → pageSize
+```
+
+---
+
+### 问题 3: MCP 工具调用失败
+
+**现象**：
+```
+使用 MCP 工具时返回错误：Error: Dataset not found
+```
+
+**原因**：
+1. appcode 配置错误
+2. 数据集代码错误
+3. 未登录或 Cookie 过期
+
+**解决方案**：
+
+1. 检查配置文件
+   ```typescript
+   // .lovrabetrc
+   {
+     "appcode": "app-xxx",
+     "env": "online"
+   }
+   ```
+
+2. 使用 list_datasets 验证
+   ```typescript
+   // 先验证数据集是否存在
+   const datasets = await list_datasets();
+   console.log(datasets.datasets.map(d => d.code)); // 查看所有数据集代码
+   ```
+
+3. 检查登录状态
+   ```bash
+   # 检查是否已登录
+   lovrabet auth
+   ```
+
+---
+
+### 问题 4: SQL 执行错误
+
+**现象**：
+```
+execSuccess: false
+execError: Table 'wrong_table' doesn't exist
+```
+
+**原因**：SQL 中的表名或字段名与实际不符
+
+**解决方案**：
+
+1. **先验证表结构**
+   ```typescript
+   // 必须先获取表结构
+   const detail = await get_dataset_detail({
+     datasetCode: "users",
+   });
+
+   // 检查实际表名
+   console.log("表名:", detail.basic.tableName); // 使用实际的表名
+
+   // 检查字段名
+   const fieldCodes = detail.fields.map(f => f.code);
+   console.log可用字段:", fieldCodes);
+   ```
+
+2. **验证 SQL 内容**
+   ```typescript
+   // 验证 SQL 语法
+   const validation = await validate_sql_content({
+     sqlContent: `
+       SELECT id, name
+       FROM correct_table_name  -- 使用实际的表名
+       WHERE status = 1
+     `,
+     dbId: detail.basic.database.dbId,
+   });
+
+   if (!validation.validation.valid) {
+     console.log("SQL 错误:", validation.validation.errors);
+   }
+   ```
+
+3. **修复并保存**
+   ```typescript
+   // 使用正确的表名和字段名
+   const sqlContent = `
+     SELECT id, name
+     FROM users            -- 实际表名
+     WHERE status = 1
+   `;
+
+   await save_or_update_custom_sql({
+     sqlContent,
+     sqlCode: "user_list",
+     sqlName: "用户列表",
+     dbId: detail.basic.database.dbId,
+   });
+   ```
+
+---
+
+### 问题 5: SDK 返回错误
+
+**现象**：
+```typescript
+try {
+  const user = await client.models.users.getOne(userId);
+} catch (error) {
+  console.log(error); // LovrabetError 对象
+}
+```
+
+**解决方案**：
+
+1. **查看错误信息**
+   ```typescript
+   if (error instanceof LovrabetError) {
+     console.error("业务错误:", error.message);      // 业务错误信息
+     console.error("错误代码:", error.code);        // 错误代码
+     console.error("HTTP状态:", error.status);      // HTTP 状态码
+     console.error("服务端响应:", error.response); // 完整响应
+   }
+ }
+   ```
+
+2. **常见错误代码**
+   ```
+   - "0000": 成功
+   - "API_ERROR": API 处理错误
+   - "AUTH_FAILED": 认证失败
+   - "PARAMETER_ERROR": 参数错误
+   - "PERMISSION_DENIED": 权限不足
+   ```
+
+---
+
+### 问题 6: 类型定义错误
+
+**现象**：
+```typescript
+import { createClient } from '@lovrabet/sdk';
+
+// 类型错误
+const client = createClient({
+  appCode: "app-xxx",
+  models: {
+    users: {
+      tableName: "users",
+      datasetCode: "xxx",
+    },
+  },
+});
+
+// ❌ 类型错误：类型不匹配
+const user: User = await client.models.users.getOne(id);
+```
+
+**解决方案**：
+
+1. **定义正确的类型**
+   ```typescript
+   // 定义与返回值匹配的类型
+   interface User {
+     id: string;
+     name: string;
+     email: string;
+     createdAt: string;
+   }
+
+   // 使用泛型
+   const user = await client.models.users.getOne<User>(id);
+   ```
+
+2. **使用 MCP 获取元数据**
+   ```typescript
+   // 先获取数据集详情，确保类型正确
+   const detail = await get_dataset_detail({
+     datasetCode: "users",
+   });
+
+   // 基于 fields 生成类型
+   interface User {
+     // 从 MCP 获取的字段动态生成类型
+   }
+
+   const user = await client.models.users.getOne<User>(id);
+   ```
+
+---
+
+### 问题 7: AntD 样式问题
+
+**现象**：
+- 团队反馈：界面看起来不专业
+- 需求文档中提到 "不要 AI 味道"
+
+**解决方案**：
+
+1. **检查清单**
+   - [ ] 没有 emoji
+   - [ ] 没有感叹号
+   - [ ] 文案简洁专业（"保存"不是"保存吧！"）
+   - [ ] 使用 AntD token 颜色
+   - [ ] 使用 @ant-design/icons
+
+2. **代码示例**
+   ```typescript
+   // ✅ 正确
+   <Button type="primary">保存</Button>
+   <Button danger>删除</Button>
+   <Message success>操作成功</Message>
+   <Modal title="确认删除">...</Modal>
+   <Empty description="暂无数据" />
+
+   // ❌ 错误（AI 常见错误）
+   <Button>保存！</Button>
+   <Message success="🎉 操作成功！"></Message>
+   <Modal title="确认删除？"><Icon type="question-circle" /></Modal>
+   <Empty description="还没有数据哦~"></Empty>
+   ```
+
+---
+
+## 🔧 排查工具
+
+### 1. 检查 SDK 配置
+
+```bash
+# 查看 SDK 初始化代码
+cat src/api/client.ts
+
+# 检查 appcode 配置
+cat .lovrabetrc
+
+# 检查 MCP 配置（IDE 不同，配置文件位置不同）
+cat .cursor/mcp.json       # Cursor
+# 或
+cat .claude/config.json    # claude code
+```
+
+### 2. 查看日志
+
+```bash
+# 查看 Lovrabet 日志
+lovrabet logs
+
+# 清空日志
+lovrabet logs --clear
+```
+
+### 3. 使用 MCP 工具验证
+
+```typescript
+// 验证数据集是否存在
+const datasets = await list_datasets();
+const exists = datasets.datasets.some(d => d.code === "users");
+
+// 验证字段是否存在
+const detail = await get_dataset_detail({
+  datasetCode: "users",
+});
+const hasField = detail.fields.some(f => f.code === "email");
+```
+
+### 4. 检查类型定义
+
+```typescript
+// 打印实际返回的数据结构
+const user = await client.models.users.getOne("test-id");
+console.log("实际返回:", JSON.stringify(user, null, 2));
+```
+
+---
+
+## 📋 检查清单
+
+在提交代码前，确认：
+
+### SDK 部分
+- [ ] Filter 查询使用了操作符 (`$eq`, `$gte` 等)
+- [ ] 参数名正确（`select` 不是 `fields`）
+- [ ] 排序参数名正确（`orderBy` 不是 `sort`）
+- [ ] 分页参数名正确（`currentPage`/`pageSize` 不是 `page`/`limit`）
+- [ ] 添加了数据集和数据表注释
+- [ ] 所有 SDK 调用都包含在 try-catch 中
+
+### MCP 部分
+- [ ] 创建 SQL 前验证表名和字段名
+-   - 使用 `get_dataset_detail` 获取表结构
+-   - 对比 SQL 内容与实际表结构
+- [ ] 创建 SQL 时执行了所有 5 个步骤
+-   - 查询 → 生成 → 验证 → 保存 → 测试
+- [ ] SQL 中只使用 SELECT 查询
+-   - 没有 INSERT/UPDATE/DELETE
+
+### UI 部分
+- [ ] 没有 emoji
+- [ ] 没有感叹号
+- [ ] 文案简洁专业
+- [ ] 使用 AntD token 颜色
+- [ ] 使用 @ant-design/icons（不是 emoji）
+
+---
+
+## 🚨 常见错误速查表
+
+| 错误现象 | 可能原因 | 解决方案 |
+|---------|---------|---------|
+| 查询无结果 | 忘记使用操作符 | `where: { status: { $eq: "active" } }` |
+| 参数不正确 | 参数名错误 | `fields` → `select`，`sort` → `orderBy` |
+| SQL 表不存在 | 表名或字段名错误 | 先用 `get_dataset_detail` 验证 |
+| 认证失败 | Cookie 过期或 appcode 错误 | 运行 `lovrabet auth` 重新登录 |
+| 类型错误 | 类型定义与实际返回值不匹配 | 使用 `getOne<类型>()` 泛型 |
+| MCP 调用失败 | MCP 服务未配置 | 运行 `lovrabet mcp install <ide>` 配置 |
+
+---
+
+## 🔗 获取帮助
+
+### CLI 命令
+```bash
+lovrabet logs          # 查看日志
+lovrabet logs --clear    # 清空日志
+lovrabet auth           # 重新登录
+```
+
+### MCP 工具
+```typescript
+// 验证配置和数据集
+const datasets = await list_datasets();
+const detail = await get_dataset_detail({ datasetCode: "users" });
+```
+
+### 开发者指南
+```bash
+# 查看 Filter 查询指南
+cat .lovrabet/skill/.shared/guides/01-filter-query/guide.md
+
+# 查看 MCP SQL 工作流指南
+cat .lovrabet/skill/.shared/guides/02-mcp-sql-workflow/guide.md
+
+# 查看 AntD 样式指南
+cat .lovrabet/skill/.shared/guides/03-antd-style/guide.md
+```
+
+---
+
+**记住**：
+- 遇到问题先看日志：`lovrabet logs`
+- 验证 SQL 前先验证表结构：`get_dataset_detail`
+- 检查错误代码：`error.code`
+- 使用 MCP 工具验证：`list_datasets`