create-kepo-plugin 1.0.2 → 1.0.3

package/index.js

@@ -22,6 +22,25 @@ function formatPackageName(alias) {
 }
 
 async function init() {
+  // 检查帮助参数
+  if (argv.help || argv.h) {
+    console.log(`
+使用方法: create-kepo-plugin [目录名] [选项]
+
+选项:
+  --name <name>           插件名称（必须为英文）
+  --description <desc>    插件描述
+  -h, --help             显示此帮助信息
+
+示例:
+  create-kepo-plugin                          # 交互式创建
+  create-kepo-plugin my-plugin                # 指定目录，交互式输入
+  create-kepo-plugin --name weather-widget    # 使用参数直接创建
+  create-kepo-plugin --name weather --description "天气插件"
+`)
+    process.exit(0)
+  }
+
   // 横幅：KEPO.AI （淡橘色、立体字体）
   try {
     // 优先使用 cfonts，风格更接近 Gemini CLI
@@ -60,36 +79,65 @@ async function init() {
   }
 
   let targetDir = argv._[0] || defaultTargetDir
-  let root = path.join(cwd, targetDir)
+  let pluginName = argv.name
+  let description = argv.description
+
+  // 验证通过参数提供的插件名称
+  if (pluginName) {
+    if (!validatePluginName(pluginName)) {
+      console.log(red('✖') + ' 插件名称必须以英文字母开头，只能包含英文字母、数字和连字符')
+      process.exit(1)
+    }
+    if (fs.existsSync(path.join(cwd, pluginName))) {
+      console.log(red('✖') + ' 目录已存在')
+      process.exit(1)
+    }
+    targetDir = pluginName
+  } else {
+    // 交互式输入插件名称
+    const result = await prompts({
+      type: 'text',
+      name: 'pluginName',
+      message: '插件名称 (必须为英文):',
+      initial: targetDir,
+      validate: (name) => {
+        if (!name) return '插件名称不能为空'
+        if (fs.existsSync(path.join(cwd, name))) return '目录已存在'
+        if (!validatePluginName(name)) return '插件名称必须以英文字母开头，只能包含英文字母、数字和连字符'
+        return true
+      }
+    })
+
+    pluginName = result.pluginName
 
-  const { pluginName } = await prompts({
-    type: 'text',
-    name: 'pluginName',
-    message: '插件名称 (必须为英文):',
-    initial: targetDir,
-    validate: (name) => {
-      if (!name) return '插件名称不能为空'
-      if (fs.existsSync(path.join(cwd, name))) return '目录已存在'
-      if (!validatePluginName(name)) return '插件名称必须以英文字母开头，只能包含英文字母、数字和连字符'
-      return true
+    if (!pluginName) {
+      console.log(red('✖') + ' 操作已取消')
+      process.exit(1)
     }
-  })
 
-  if (!pluginName) {
-    console.log(red('✖') + ' 操作已取消')
-    process.exit(1)
+    // 更新目标目录为用户输入的插件名
+    targetDir = pluginName
   }
 
-  // 更新目标目录为用户输入的插件名
-  targetDir = pluginName
-  root = path.join(cwd, targetDir)
+  let root = path.join(cwd, targetDir)
 
-  const { description } = await prompts({
-    type: 'text',
-    name: 'description',
-    message: '插件描述 (选填):',
-    initial: `A Kepo plugin named ${pluginName}`
-  })
+  // 如果没有通过参数提供描述，且也没有提供name参数，则交互式输入
+  // 如果提供了name参数但没有提供description参数，使用默认值
+  if (!description) {
+    if (argv.name) {
+      // 通过参数提供了name，使用默认描述，不进行交互
+      description = `A Kepo plugin named ${pluginName}`
+    } else {
+      // 交互式模式，询问描述
+      const result = await prompts({
+        type: 'text',
+        name: 'description',
+        message: '插件描述 (选填):',
+        initial: `A Kepo plugin named ${pluginName}`
+      })
+      description = result.description
+    }
+  }
 
   // 创建项目目录
   fs.mkdirSync(root, { recursive: true })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kepo-plugin",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "CLI tool for creating Kepo plugins",
   "type": "module",
   "bin": {

package/template/.cursorrules

@@ -1,6 +1,6 @@
 {
   "promptName": "Kepo 小组件平台开发专家提示词",
-  "description": "一个用于指导 AI 或开发者为 Kepo 小组件平台进行插件开发的综合性提示词。它包含了完整的技术栈、API 参考、开发规范以及一套基于参考图的详细设计系统，旨在确保最终产出的组件功能完善、性能卓越且严格遵循视觉统一性。",
+  "description": "一个用于指导 AI 或开发者为 Kepo 小组件平台进行插件开发的综合性提示词。它包含了完整的技术栈、API 参考、开发规范以及一套以文字描述的设计系统，旨在确保最终产出的组件功能完善、性能卓越且严格遵循视觉统一性。",
   "persona": {
     "role": "Kepo 平台小组件开发专家",
     "goal": "我的核心任务是协助开发者，根据 Kepo 平台的技术规范和设计准则，一步步地创建高质量的小组件。我会提供从项目结构搭建、数据逻辑（Provider）实现，到前端视图（Viewer）开发的全流程指导，并确保最终成品在不同尺寸和主题（亮色/暗色）下都能完美呈现，无内容溢出或布局错乱问题。"
@@ -51,12 +51,34 @@
           {
             "name": "Storage",
             "description": "提供持久化的键值对本地存储能力。",
-            "methods": ["get<T>", "set", "del", "clear"]
+            "methods": ["get<T>", "set", "del", "clear"],
+            "methodSignatures": [
+              "get<T>(key: string): Promise<T | null>",
+              "get<T>(key: string, defaultValue: T): Promise<T>",
+              "set(key: string, value: any): Promise<void>",
+              "del(key: string): Promise<void>",
+              "clear(): Promise<boolean>"
+            ],
+            "genericNotes": "Storage 的泛型参数 T 无约束，仅用于指明返回值的数据类型。"
           },
           {
             "name": "Config",
             "description": "用于管理和操作用户为组件设置的配置项。",
-            "methods": ["get<T>", "set<T>", "updateStruct<T>", "getStruct<T>", "setError"]
+            "methods": ["get<T>", "set<T>", "updateStruct<T>", "getStruct<T>", "setError"],
+            "methodSignatures": [
+              "get<T extends Options>(key: string): Promise<ExcludeUndefined<T['value']> | null>",
+              "get<T extends Options>(key: string, defaultValue: T['value']): Promise<ExcludeUndefined<T['value']>>",
+              "set<T extends Options>(key: string, value: T['value']): Promise<boolean>",
+              "updateStruct<T extends Options>(key: string, value: ConfigWithExcludeKeys<T>): Promise<boolean>",
+              "getStruct<T extends Options>(key: string): Promise<T>",
+              "setError(key: string, error: string): Promise<void>"
+            ],
+            "genericNotes": "Config 的泛型参数写作 T extends Options，T 必须是某个具体的配置项类型（如 InputOption、SelectOption 等）。所有以 T 为参数的方法都会基于 T['value'] 推导出读写的值类型。",
+            "relatedTypes": {
+              "configExcludeKeys": "type configExcludeKeys = 'event' | 'type' | 'title' | 'key';",
+              "ConfigWithExcludeKeys": "type ConfigWithExcludeKeys<T extends Options> = Partial<Omit<T, configExcludeKeys>>;",
+              "ExcludeUndefined": "type ExcludeUndefined<T> = T extends undefined ? never : T;"
+            }
           }
         ],
         "objects": [
@@ -79,7 +101,49 @@
             }
           }
         ],
-        "optionTypes": ["InputOption", "SelectOption", "SwitchOption", "ButtonOption"]
+        "optionTypes": ["InputOption", "SelectOption", "SwitchOption", "ButtonOption"],
+        "optionTypeDefinitions": {
+          "OptionEvent": {
+            "definition": "interface OptionEvent { key: string; type: string; currentTarget: Options }",
+            "description": "配置项事件回调的参数对象，包含变更键、类型与当前配置项结构本身。"
+          },
+          "OptionBase<T>": {
+            "definition": "interface OptionBase<T> { key: string; title: string; description?: string; placeholder?: string; disable?: boolean; error?: string; value?: T; defaultValue?: T }",
+            "genericNotes": "T 表示该配置项的值类型。例如输入框为 string，开关为 boolean，选择器为 string[]。"
+          },
+          "InputOption": {
+            "definition": "interface InputOption extends OptionBase<string> { type: 'input'; event?: { onLoad?: (e: OptionEvent) => void; onChange?: (e: OptionEvent) => void; onFocus?: (e: OptionEvent) => void; onBlur?: (e: OptionEvent) => void } }",
+            "extends": "OptionBase<string>",
+            "valueType": "string"
+          },
+          "SelectOption": {
+            "definition": "interface SelectOption extends OptionBase<string[]> { type: 'select'; options: Array<{ label: string; value: string; description?: string; icon?: string }>; multiple: boolean; search?: string; event?: { onLoad?: (e: OptionEvent) => void; onSearch?: (e: OptionEvent) => void; onChange?: (e: OptionEvent) => void } }",
+            "extends": "OptionBase<string[]>",
+            "valueType": "string[]",
+            "notes": "multiple=true 时可多选，value 为字符串数组；提供可选搜索与变更事件。"
+          },
+          "SwitchOption": {
+            "definition": "interface SwitchOption extends OptionBase<boolean> { type: 'switch'; event?: { onLoad?: (e: OptionEvent) => void; onChange?: (e: OptionEvent) => void } }",
+            "extends": "OptionBase<boolean>",
+            "valueType": "boolean"
+          },
+          "ButtonOption": {
+            "definition": "interface ButtonOption extends OptionBase<string> { type: 'button'; event?: { onLoad?: (e: OptionEvent) => void; onClick: (e: OptionEvent) => void } }",
+            "extends": "OptionBase<string>",
+            "valueType": "string",
+            "notes": "按钮支持 onClick 必填（在 event 存在时），可选 onLoad。"
+          },
+          "Options": {
+            "definition": "type Options = | InputOption | SelectOption | SwitchOption | ButtonOption",
+            "description": "所有配置项类型的联合体，作为 Config 读写与结构更新的通用泛型约束。"
+          }
+        },
+        "valueTypeMapping": {
+          "InputOption": "string",
+          "SelectOption": "string[]",
+          "SwitchOption": "boolean",
+          "ButtonOption": "string"
+        }
       },
       "sharedTypes": {
         "module": "@kepoai/types",
@@ -106,7 +170,12 @@
         "hooks": [
           {
             "name": "useStorage<T>",
-            "description": "响应式地读写本地存储。"
+            "description": "响应式地读写本地存储。",
+            "signatures": [
+              "useStorage<T>(key: string): [T | null, (value: T) => void]",
+              "useStorage<T>(key: string, initialValue: T): [T, (value: T) => void]"
+            ],
+            "genericNotes": "T 无约束，用于指示存储值的类型。未提供 initialValue 时，返回的当前值可能为 null。"
           },
           {
             "name": "useSizeType",
@@ -118,7 +187,12 @@
           },
           {
             "name": "useConfig<T>",
-            "description": "获取用户设置的配置项值。"
+            "description": "获取用户设置的配置项值。",
+            "signatures": [
+              "useConfig<T>(key: string): T | undefined",
+              "useConfig<T>(key: string, defaultValue: T): T"
+            ],
+            "genericNotes": "T 通常对应 Provider 侧配置项的值类型（即某个具体 Options 的 T['value']）。未提供 defaultValue 时，返回值可能为 undefined。"
           },
           {
             "name": "useDarkMode",
@@ -145,12 +219,17 @@
         "contrast": "正文文字与背景对比度 ≥ 4.5:1；大字或图形 ≥ 3:1。"
       },
       "cardBackground": {
-        "requirement": "卡片背景必须采用扁平化渐变（Flat Gradient），以提升质感。",
+        "requirement": "卡片背景必须采用扁平化渐变（Flat Gradient），以提升质感；卡片外层禁止添加边框（border）。",
         "principles": [
           "使用 2-3 个同色系或邻近色 Stop，避免强对比、高饱和的炫彩渐变。",
           "渐变角度建议在 120°–160°；过渡平滑、无噪点纹理。",
           "亮色模式：较明亮但不过曝；暗色模式：降低亮度并适度提高层级对比。"
         ],
+        "borderPolicy": {
+          "outerBorder": "禁止在卡片外围添加任何边框（border: none）",
+          "separators": "如需区分内容区块，仅在卡片内部使用极细分隔线（例如 1px、低对比度）或内阴影，且必须保证无视觉噪点与不过度抢眼",
+          "rationale": "外边框会与平台卡片容器产生冲突，破坏层级与统一的视觉节奏，使用渐变+阴影即可建立层级"
+        },
         "implementation": {
           "cssVariables": {
             "--card-gradient": "linear-gradient(150deg, var(--card-start), var(--card-end))"
@@ -219,12 +298,12 @@
         {
           "size": "wide ([4, 2])",
           "guideline": "【列表/多指标型】适合展示一个水平列表或 3-4 个并排的指标。列表最多展示 3-4 个条目，每个条目包含图标、主标题和副标题。所有文本都应有长度限制，防止换行。",
-          "example": "如参考图中的 `Reading List`，展示了标题、总数和 3 个带图标的文章条目。"
+          "example": "例如“阅读清单”类组件：卡片顶部展示模块标题与总计数，主体为 3 个条目构成的水平列表；每个条目包含小图标、主标题（单行截断）和副标题（单行截断），整体在两行高度内完成信息扫读。"
         },
         {
           "size": "large ([4, 4])",
           "guideline": "【详情型】可展示更丰富的信息，如图文混排、更详细的列表（最多 5-6 项）或一个基本图表。文章摘要的描述文本应限制在 3-4 行内。",
-          "example": "如参考图中的 `Coda 3.0`，包含图片、标签、标题和一段被截断的描述文字。"
+          "example": "例如“产品卡片”类组件：左侧或顶部展示较大尺寸配图，旁侧依次为标签（小型胶囊）、主标题（单行截断）以及 3-4 行内的描述性文字（多行截断）；底部可放置一行次要指标或操作按钮，在不拥挤的前提下提供更多上下文。"
         },
         {
           "size": "giant ([6, 6])",