@blocklet/component-studio-cli 0.5.45 → 0.5.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocklet/component-studio-cli",
-  "version": "0.5.45",
+  "version": "0.5.48",
   "description": "CLI for Component Studio",
   "publishConfig": {
     "access": "public"

package/templates/add/tools/cursor-rules/.cursor/rules/@metadata-json.mdc

@@ -42,6 +42,7 @@ alwaysApply: true
 | `name` | 组件显示名称 |
 | `description` | 组件描述 |
 | `properties` | 包含所有可配置属性的对象 |
+| `llmConfig` | AI 生成配置，用于描述 AI 如何处理各个属性字段，描述字段的配置用途 |
 
 ### 属性定义 (properties 内)
 每个属性都有一个唯一 ID 作为键，包含以下内容：
@@ -97,6 +98,67 @@ alwaysApply: true
 ### 嵌套属性 (subProperties)
 在 `yaml`, `json`, `array` 等复杂类型中可以定义子属性（subProperties）。子属性的结构与主属性列表结构相同，用于定义复杂数据类型的内部结构。
 
+### LLM 配置 (llmConfig)
+`llmConfig` 是必填的顶层字段，用于配置 AI 如何处理和生成组件属性的值。它主要用于 AI 生成内容的场景。
+
+#### 基本结构
+```json
+"llmConfig": {
+  "properties": {
+    "propertyId": {
+      "key": "propertyKey",
+      "isNeedGenerate": true,
+      "describe": "详细描述 AI 如何处理这个属性的值，描述字段的含义",
+      "displayName": "属性显示名称"
+    }
+  }
+}
+```
+
+#### 字段说明
+- `properties`: 包含需要 AI 处理的属性配置
+  - `key`: 对应 properties 中的属性 key，用于关联具体属性
+  - `isNeedGenerate`: 布尔值，标识该属性是否需要 AI 生成，大多数情况都是需要 AI 生成
+  - `describe`: 详细描述 AI 应该如何生成或处理这个属性的值，包括：
+    - 生成规则和约束
+    - 业务逻辑要求
+    - 数据格式要求
+    - TypeScript 接口定义
+  - `displayName`: 属性的显示名称，用于 AI 理解属性含义
+
+#### 使用场景
+- **内容生成**: 为文本、标题等内容属性提供生成指导
+- **结构化数据**: 为复杂对象、数组等结构化数据提供格式规范
+- **样式配置**: 为颜色、尺寸等样式属性提供选择指导
+- **业务逻辑**: 为具有特定业务含义的属性提供生成规则
+
+#### 最佳实践
+- 在 `describe` 中提供详细的 TypeScript 接口定义
+- 明确说明属性的业务含义和使用场景
+- 为复杂类型提供完整的数据结构说明
+- 设置合理的 `isNeedGenerate` 标识，避免不必要的 AI 处理
+- 保持 `displayName` 与 properties 中的多语言名称一致
+
+#### 示例
+```json
+"llmConfig": {
+  "properties": {
+    "gs1rn5jmxfvpxptx": {
+      "key": "title",
+      "isNeedGenerate": true,
+      "describe": "内容大标题，需要精炼",
+      "displayName": "标题"
+    },
+    "9ajrz12ik7esfk1z": {
+      "key": "description", 
+      "isNeedGenerate": true,
+      "describe": "组件的描述，尽可能详细一些，用于解释这一块的内容",
+      "displayName": "描述"
+    }
+  }
+}
+```
+
 
 ## 常见问题
 
@@ -109,6 +171,18 @@ A: 可以通过修改浏览器语言设置或使用开发工具中的语言切
 **Q: 修改属性类型后，原有的defaultValue不生效了？**
 A: 不同类型需要匹配相应格式的默认值，修改类型时需同步更新defaultValue。
 
+**Q: 为什么需要配置 llmConfig？**
+A: 通过 llmConfig 可以指导 AI 如何正确生成各个属性的值，特别是字段代表的意思和用途。
+
+**Q: llmConfig 中的 key 必须与 properties 中的 key 一致吗？**
+A: 是的，llmConfig 中的 key 必须与 properties 中对应属性的 key 完全一致，这样 AI 才能正确关联和处理属性。
+
+**Q: llmConfig 中的 describe 字段应该如何编写？**
+A: describe 字段应该包含详细的类型定义、格式要求和业务规则，让 AI 能够准确理解字段的含义。
+
+**Q: AI 是如何使用 llmConfig 的？**
+A: AI 系统会读取 llmConfig 中的配置，根据 isNeedGenerate 标识决定是否生成对应属性，并根据 describe 中的描述和 zod 定义生成符合要求的数据结构。
+
 ## `@metadata.json` 示例
 请仔细查看它的结构，其它 `@metadata.json` 的结构与其基本一致，只是其中 `properties` 中的差别
 请注意：所有 `id` 都是 16 位的 uuid，不需要语意化，需要乱序字母和数字组合（非常重要!）
@@ -544,6 +618,126 @@ A: 不同类型需要匹配相应格式的默认值，修改类型时需同步
         }
       }
     }
+  },
+  "llmConfig": {
+    "properties": {
+      "gs1rn5jmxfvpxptx": {
+        "key": "title",
+        "isNeedGenerate": true,
+        "describe": "内容大标题，需要精炼",
+        "displayName": "标题"
+      },
+      "9ajrz12ik7esfk1z": {
+        "key": "description",
+        "isNeedGenerate": true,
+        "describe": "组件的描述，尽可能详细一些，用于解释这一块的内容",
+        "displayName": "描述"
+      },
+      "3ckcfvf6b7zyskk8": {
+        "key": "logo",
+        "isNeedGenerate": false,
+        "describe": "Logo 图片配置，包含 URL 和尺寸信息",
+        "displayName": "Logo",
+        "subProperties": {
+          "ML-CDw7LvtlhM_cl": {
+            "key": "url",
+            "isNeedGenerate": false,
+            "describe": "Logo 图片的 URL 地址",
+            "displayName": "url"
+          },
+          "K-HYgPHtAsmO_mer": {
+            "key": "mediaKitUrl",
+            "isNeedGenerate": false,
+            "describe": "Logo 的媒体资源包 URL",
+            "displayName": "mediaKitUrl"
+          }
+        }
+      },
+      "x3lqht8ikble1itx": {
+        "key": "copyright",
+        "isNeedGenerate": false,
+        "describe": "版权信息文本",
+        "displayName": "版权信息"
+      },
+      "q0ezdj81v0m14y5m": {
+        "key": "number",
+        "isNeedGenerate": false,
+        "describe": "整数数值配置",
+        "displayName": "整数"
+      },
+      "yi1oj4rq1eziup1d": {
+        "key": "titleColor",
+        "isNeedGenerate": false,
+        "describe": "标题颜色，使用十六进制颜色值或 MUI 色板",
+        "displayName": "标题颜色"
+      },
+      "4f49q5uidkcp5ak4": {
+        "key": "json",
+        "isNeedGenerate": true,
+        "describe": "JSON 对象数据，包含 foo 和 bar 两个字段",
+        "displayName": "JSON 数据",
+        "subProperties": {
+          "gpy89bsxc6ovvlsp": {
+            "key": "foo",
+            "isNeedGenerate": true,
+            "describe": "JSON 对象中的 foo 字段值",
+            "displayName": "名称"
+          },
+          "1j34jdhdptp2xm5e": {
+            "key": "bar",
+            "isNeedGenerate": true,
+            "describe": "JSON 对象中的 bar 字段值",
+            "displayName": "属性"
+          }
+        }
+      },
+      "lbclpm6mxrp10w2k": {
+        "key": "array",
+        "isNeedGenerate": true,
+        "describe": "用户信息数组，每个元素包含 name 和 bio 字段",
+        "displayName": "数组数据",
+        "subProperties": {
+          "1c5vl2p9cn9ryvgh": {
+            "key": "name",
+            "isNeedGenerate": true,
+            "describe": "用户姓名",
+            "displayName": "姓名"
+          },
+          "c5whnccwzqqzaa0w": {
+            "key": "bio",
+            "isNeedGenerate": true,
+            "describe": "用户个人简介，支持多行文本",
+            "displayName": "简介"
+          }
+        }
+      },
+      "s0tund4p07bzizgv": {
+        "key": "yaml",
+        "isNeedGenerate": true,
+        "describe": "YAML 配置数据，包含 ya 和 ml 两个字段",
+        "displayName": "YAML 配置",
+        "subProperties": {
+          "1q8tsreh4k2mhbgs": {
+            "key": "ya",
+            "isNeedGenerate": true,
+            "describe": "YAML 配置中的 ya 字段值",
+            "displayName": "Ya"
+          },
+          "09w8sncxwrj6tldi": {
+            "key": "ml",
+            "isNeedGenerate": true,
+            "describe": "YAML 配置中的 ml 字段值",
+            "displayName": "Ml"
+          }
+        }
+      },
+      "8e7g6c61pxcy0q4w": {
+        "key": "children",
+        "isNeedGenerate": false,
+        "describe": "子组件配置，用于嵌套其他组件",
+        "displayName": "子组件"
+      }
+    }
   }
 }
 ```

package/templates/add/tools/cursor-rules/.cursor/rules/index-tsx.mdc

@@ -83,46 +83,158 @@ export const EditComponent: React.FC<BlockProps & { onChange?: (value: BlockProp
 - 考虑添加表单验证，确保用户输入的值有效
 - 提供即时反馈，让用户知道其操作已被接收
 - 保持编辑控件的样式与 Component Studio 整体风格一致
-- 并不是所有的 Component 都需要这个自定义空间，尤其是 `type: 'url' ｜ ‘yml’` 情况下，不建议替换
+- 并不是所有的 Component 都需要这个自定义 EditComponent，尤其是，尤其是 `type: 'url' ｜ ‘yml’` 情况下，不建议替换
 
-### 样式
-组件样式在 Component Studio 中通常通过内联样式对象实现，便于与属性值动态绑定。
+### MUI 5.x 最佳实践
+Component Studio 中推荐使用 Material-UI 5.x 组件系统，提供一致性和可访问性。便于快速使用定制的主题系统。 
 
+#### 优先使用 MUI 组件而非原生 HTML
 ```typescript
-// 样式对象分离示例
+// ❌ 避免使用原生 HTML 组件
+return (
+  <div>
+    <h1>Title</h1>
+    <p>Description</p>
+    <button onClick={handleClick}>Click me</button>
+  </div>
+);
+
+// ✅ 推荐使用 MUI 组件
+import { Box, Typography, Button } from '@mui/material';
+
+return (
+  <Box>
+    <Typography variant="h4" component="h1">
+      {title}
+    </Typography>
+    <Typography variant="body1">
+      {description}
+    </Typography>
+    <Button variant="contained" onClick={handleClick}>
+      Click me
+    </Button>
+  </Box>
+);
+```
+
+#### MUI 组件选择指南
+- **布局容器**: 使用 `Box`, `Container`, `Stack`, `Grid` 替代 `div`
+- **文本显示**: 使用 `Typography` 替代 `h1-h6`, `p`, `span`
+- **交互元素**: 使用 `Button`, `IconButton` 替代 `button`
+- **输入控件**: 使用 `TextField`, `Select`, `Checkbox` 等替代原生表单元素
+- **卡片布局**: 使用 `Card`, `CardContent`, `CardActions` 组织内容
+- **导航元素**: 使用 `AppBar`, `Tabs`, `Breadcrumbs` 等
+
+### 样式最佳实践
+Component Studio 中样式管理推荐使用 MUI 的 sx 属性和主题系统。
+
+#### sx 属性优先于内联样式
+```typescript
+import { Box, Typography } from '@mui/material';
+
+// ❌ 避免使用内联样式
 const cardStyle = {
   padding: '1.5rem',
   borderRadius: '12px',
   background: 'rgba(255, 255, 255, 0.7)',
   boxShadow: '0 10px 30px rgba(0, 0, 0, 0.08)'
 };
-
 return <div style={cardStyle}>...</div>;
+
+// ✅ 推荐使用 sx 属性
+return (
+  <Box
+    sx={{
+      p: 3, // padding: theme.spacing(3)
+      borderRadius: 2, // borderRadius: theme.shape.borderRadius * 2
+      bgcolor: 'background.paper',
+      boxShadow: 3, // theme.shadows[3]
+      '&:hover': {
+        boxShadow: 6,
+      }
+    }}
+  >
+    ...
+  </Box>
+);
 ```
 
-#### 样式最佳实践
-- **内联样式优先** - 使用内联样式（style对象）便于属性动态控制
-- **样式对象分离** - 对于复杂组件，将样式对象提取到组件函数外，提高可读性
-- **动态样式函数** - 创建函数生成依赖于属性的样式
-  ```typescript
-  const getTitleStyle = (color) => ({
-    color,
-    fontSize: '1.5rem',
-    fontWeight: 600
-  });
-  ```
-- **响应式设计** - 使用条件样式或媒体查询实现适配不同设备
-- **过渡动画** - 添加 transition 属性提升用户体验
-- **交互增强** - 为互动元素添加悬停状态
-- **性能优化** - 使用 useMemo 缓存样式对象，避免不必要的重新计算
+#### 使用主题系统避免硬编码
+```typescript
+// ❌ 避免硬编码颜色和尺寸
+sx={{
+  color: '#1976d2',
+  fontSize: '24px',
+  margin: '16px'
+}}
+
+// ✅ 使用主题令牌
+sx={{
+  color: 'primary.main',          // 主题主色
+  fontSize: 'h4.fontSize',        // 主题字体尺寸
+  m: 2,                          // theme.spacing(2)
+  bgcolor: 'background.paper',    // 主题背景色
+  borderColor: 'divider'         // 主题分割线颜色
+}}
+```
+
+#### 响应式设计最佳实践
+```typescript
+// 使用主题断点实现响应式
+sx={{
+  p: {
+    xs: 1,
+    sm: 2,
+    md: 3
+  }
+}}
+```
+
+#### 动态样式与属性绑定
+```typescript
+// 根据属性动态应用样式
+const getTitleSx = (titleColor?: string) => ({
+  color: titleColor || 'text.primary',
+  fontWeight: 'bold',
+  mb: 2
+});
+
+return (
+  <Typography 
+    variant="h4" 
+    sx={getTitleSx(titleColor)}
+  >
+    {title}
+  </Typography>
+);
+```
+
+#### 主题自定义最佳实践
+```typescript
+// 在组件中访问主题
+import { useTheme } from '@mui/material/styles';
+
+const theme = useTheme();
+
+// 使用主题值进行条件渲染
+sx={{
+  color: theme.palette.mode === 'dark' ? 'grey.300' : 'grey.700',
+  bgcolor: theme.palette.background.paper,
+  border: `1px solid ${theme.palette.divider}`
+}}
+```
+
+#### 性能优化建议
+- **缓存 sx 对象** - 使用 useMemo 缓存复杂的 sx 配置
   ```typescript
-  const buttonStyle = useMemo(() => ({
-    background: isActive ? activeColor : inactiveColor
-  }), [isActive, activeColor, inactiveColor]);
+  const cardSx = useMemo(() => ({
+    p: 3,
+    borderRadius: 2,
+    bgcolor: isActive ? 'primary.light' : 'background.paper'
+  }), [isActive]);
   ```
-- **避免硬编码** - 使用属性传入的样式值，避免硬编码颜色等固定值
-- **主题变量** - 考虑使用 CSS 变量实现主题定制
-- **使用语义化命名** - 如 containerStyle, headerStyle 等增强可读性
+- **避免复杂嵌套** - 将复杂样式拆分为多个组件
+- **使用主题缓存** - 相同的主题令牌会被 MUI 自动缓存
 
 ## 与 @metadata.json 的关系
 
@@ -169,18 +281,30 @@ json?: {
 对于需要特殊编辑体验的属性，可以通过 `EditComponent` 提供自定义编辑界面：
 
 ```typescript
+import { Box, TextField, FormLabel } from '@mui/material';
+
 export const EditComponent: React.FC<BlockProps & { onChange?: (value: BlockProps) => void }> = ({
   onChange,
   ...props
 }) => {
   return (
-    <div>
-      <label>自定义编辑器</label>
-      <input 
-        value={props.someProperty || ''} 
+    <Box sx={{ p: 2 }}>
+      <FormLabel sx={{ mb: 1, display: 'block' }}>
+        Custom Editor
+      </FormLabel>
+      <TextField
+        fullWidth
+        variant="outlined"
+        size="small"
+        value={props.someProperty || ''}
         onChange={(e) => onChange?.({...props, someProperty: e.target.value})}
+        sx={{ 
+          '& .MuiOutlinedInput-root': {
+            bgcolor: 'background.paper'
+          }
+        }}
       />
-    </div>
+    </Box>
   );
 }
 ```