cloudcc-cli 2.2.2 → 2.2.4

package/src/mcp/tools/Component Publisher/prompt.js

@@ -0,0 +1,659 @@
+/**
+ * Plugin 工具知识库
+ * 提供 Vue 插件模板、配置结构、API 文档和错误信息
+ */
+
+/**
+ * Vue 插件模板示例
+ */
+const vuePluginTemplate = {
+    name: 'Vue插件组件模板',
+    description: 'CloudCC Vue 自定义组件的标准结构，支持自定义元素和组件注册',
+    mainComponent: `<template>
+  <div class="cc-container">
+     <HelloWorld />
+  </div>
+</template>
+
+<script>
+import HelloWorld from "./components/HelloWorld.vue";
+export default {
+  components: {
+    HelloWorld,
+  },
+  data() {
+    return {
+      componentInfo: {
+        // 组件唯一标识符
+        component: "component-{pluginName}",
+        // 组件显示名称
+        compName: "compName-{pluginName}",
+        // 组件描述信息
+        compDesc: "Component description information",
+        // 业务类型（可选）
+        bizType: "",
+        // 分类（可选）
+        category: "",
+        // 加载模式：lazy（懒加载）或 eager（立即加载）
+        loadModel: "lazy",
+        // 所属组织标识
+        belongOrgFlag: "custom"
+      }
+    };
+  },
+};
+</script>
+<style lang="scss" scoped>
+.cc-container {
+  text-align: center;
+  padding: 8px;
+}
+</style>`,
+    subComponent: `<template>
+  <div>Hello world</div>
+</template>
+
+<script>
+export default {};
+</script>
+
+<style lang="scss" scoped>
+</style>`,
+    notes: [
+        '所有 <style> 标签必须包含 scoped 属性，避免样式全局污染',
+        'componentInfo.component 必须唯一，建议使用 "component-" 前缀',
+        'componentInfo.compName 是在界面上显示的名称，支持国际化',
+        'loadModel 为 "lazy" 时组件按需加载，为 "eager" 时立即加载',
+        'belongOrgFlag 默认为 "custom"，表示自定义组件'
+    ]
+};
+
+/**
+ * config.json 配置文件结构
+ */
+const configStructure = {
+    name: 'config.json配置结构',
+    description: '每个插件目录下的配置文件',
+    fields: {
+        component: {
+            type: 'string',
+            required: true,
+            description: '组件唯一标识符，必须以 "component-" 开头'
+        },
+        compName: {
+            type: 'string',
+            required: true,
+            description: '组件显示名称'
+        },
+        compDesc: {
+            type: 'string',
+            required: true,
+            description: '组件描述信息'
+        },
+        bizType: {
+            type: 'string',
+            required: false,
+            description: '业务类型标识'
+        },
+        category: {
+            type: 'string',
+            required: false,
+            description: '组件分类'
+        },
+        loadModel: {
+            type: 'string',
+            required: false,
+            description: '加载模式：lazy（懒加载）或 eager（立即加载）',
+            default: 'lazy'
+        },
+        belongOrgFlag: {
+            type: 'string',
+            required: false,
+            description: '所属组织标识',
+            default: 'custom'
+        },
+        destroyTimeout: {
+            type: 'number',
+            required: false,
+            description: '组件销毁超时时间（毫秒）',
+            default: 1200000
+        }
+    },
+    example: {
+        component: 'component-MyPlugin',
+        compName: 'compName-MyPlugin',
+        compDesc: 'Component description information'
+    }
+};
+
+/**
+ * CloudCC 组件数据结构
+ */
+const componentDataStructure = {
+    name: '组件数据结构',
+    description: 'Vue 组件 data() 中返回的 CloudCC 标准结构',
+    fields: {
+        componentInfo: {
+            description: '组件基本信息（必需）',
+            required: true,
+            fields: {
+                component: '组件唯一标识',
+                compName: '组件名称',
+                compDesc: '组件描述',
+                bizType: '业务类型（可选）',
+                category: '分类（可选）',
+                loadModel: '加载模式（可选）',
+                belongOrgFlag: '组织标识（可选）'
+            }
+        },
+        propObj: {
+            description: '组件属性对象',
+            required: false,
+            example: {
+                title: '默认标题',
+                size: 'medium'
+            }
+        },
+        propOption: {
+            description: '属性配置选项',
+            required: false,
+            example: {
+                title: {
+                    label: '标题',
+                    type: 'input'
+                },
+                size: {
+                    label: '尺寸',
+                    type: 'option',
+                    options: [
+                        { value: 'small', label: '小' },
+                        { value: 'medium', label: '中' },
+                        { value: 'large', label: '大' }
+                    ]
+                }
+            }
+        },
+        events: {
+            description: '组件事件对象',
+            required: false
+        },
+        eventsOption: {
+            description: '事件配置选项',
+            required: false
+        },
+        style: {
+            description: '组件样式配置',
+            required: false,
+            default: {
+                unit: 'px',
+                width: 72,
+                height: 38,
+                top: 0,
+                left: 0,
+                rotate: 0,
+                opacity: 1
+            }
+        },
+        styleOption: {
+            description: '样式配置选项',
+            required: false
+        }
+    }
+};
+
+/**
+ * 插件发布流程
+ */
+const publishWorkflow = {
+    name: '插件发布工作流',
+    steps: [
+        '1. 收集组件信息（从 Vue 文件的 data() 函数中提取 componentInfo）',
+        '2. 收集所有依赖文件（递归分析 import 语句）',
+        '3. 编译构建（使用 vue-cli-service 构建为 UMD 格式）',
+        '4. 上传到服务器（包含编译后的 JS 和所有依赖源码）'
+    ],
+    buildCommand: 'npx vue-cli-service build --target lib --name {component} --dest build plugins/{tempEntry}.js',
+    uploadEndpoint: '/devconsole/custom/pc/1.0/post/insertCustomComp',
+    uploadData: {
+        compLabel: '组件名称',
+        compUniName: '组件唯一标识',
+        compContentJs: '编译后的 UMD JS 内容',
+        compContentVue: '已废弃，现在用 dependencies 字段',
+        vueData: '组件 data() 的 JSON 字符串',
+        bizType: '业务类型',
+        compDesc: '组件描述',
+        category: '分类',
+        loadModel: '加载模式',
+        belongOrgFlag: '组织标识',
+        dependencies: '所有依赖文件的 JSON 字符串（key: 相对路径, value: 文件内容）'
+    }
+};
+
+/**
+ * 项目配置文件
+ */
+const projectConfigFiles = {
+    name: '项目配置文件',
+    description: '插件发布时需要的项目级配置文件',
+    files: {
+        'package.json': {
+            description: 'NPM 包配置文件',
+            requiredFields: {
+                username: '开发者用户名',
+                secretKey: '开发者密钥',
+                baseUrl: 'CloudCC API 基础 URL（可选，默认 https://developer.apis.cloudcc.cn）',
+                version: '版本类型（private 表示私有部署）',
+                pluginToken: '插件令牌（优先使用）',
+                source: '来源标识（默认 cloudcc_cli）',
+                devSvcDispatch: '开发服务路径（默认 /devconsole）',
+                belongOrgFlag: '组织标识（默认 custom）',
+                destroyTimeout: '销毁超时时间（默认 1200000ms）'
+            },
+            example: {
+                name: 'my-plugin-project',
+                version: '1.0.0',
+                username: 'developer@example.com',
+                secretKey: 'your-secret-key',
+                baseUrl: 'https://developer.apis.cloudcc.cn'
+            }
+        },
+        'cloudcc-cli.config.js': {
+            description: 'CloudCC CLI 配置文件',
+            optional: true,
+            note: '发布时会自动收集此文件（如果存在）'
+        }
+    }
+};
+
+/**
+ * 依赖收集机制
+ */
+const dependencyCollection = {
+    name: '依赖收集机制',
+    description: '自动分析和收集组件的所有依赖文件',
+    process: [
+        '1. 从入口文件（{pluginName}.vue）开始',
+        '2. 使用正则表达式解析 import/require 语句',
+        '3. 递归处理每个依赖文件',
+        '4. 构建依赖树，避免重复收集',
+        '5. 收集项目根目录的配置文件（package.json、cloudcc-cli.config.js）',
+        '6. 将所有文件内容打包为 JSON 对象'
+    ],
+    importPatterns: [
+        'import ... from "..."',
+        'import("...")',
+        'require("...")'
+    ],
+    supportedExtensions: ['.vue', '.js', '.ts', '.json', '.css', '.scss', '.sass', '.less'],
+    output: {
+        format: 'JSON 对象',
+        structure: {
+            'relative/path/to/file.vue': '文件内容字符串',
+            'relative/path/to/component.js': '文件内容字符串',
+            'package.json': '根目录配置文件内容',
+            'cloudcc-cli.config.js': '根目录配置文件内容（如果存在）'
+        }
+    }
+};
+
+/**
+ * 样式作用域最佳实践
+ */
+const styleScopedBestPractices = {
+    name: '样式作用域最佳实践',
+    description: '避免样式污染的关键规则',
+    rules: [
+        '✓ 必须：所有 <style> 标签都要加 scoped 属性',
+        '✓ 推荐：使用 BEM 命名规范（Block__Element--Modifier）',
+        '✓ 推荐：使用唯一的类名前缀（如组件名）',
+        '✗ 避免：直接修改全局标签样式（如 div、span）',
+        '✗ 避免：使用 !important 强制覆盖样式'
+    ],
+    goodExample: `<style lang="scss" scoped>
+.my-component {
+  padding: 8px;
+  
+  &__header {
+    font-size: 16px;
+  }
+  
+  &__content {
+    margin-top: 10px;
+  }
+}
+</style>`,
+    badExample: `<style lang="scss">
+/* 没有 scoped，会污染全局 */
+div {
+  padding: 8px;
+}
+</style>`
+};
+
+/**
+ * 使用指南
+ */
+const usageGuide = {
+    name: '插件开发使用指南',
+    workflow: [
+        '1. 创建插件：cc plugin create <pluginName>',
+        '2. 开发组件：编辑 plugins/<pluginName>/<pluginName>.vue',
+        '3. 测试组件：在本地开发环境中测试',
+        '4. 发布插件：cc plugin publish <pluginName>',
+        '5. 验证发布：登录 CloudCC 开发者控制台查看'
+    ],
+    bestPractices: [
+        '始终在 <style> 标签上添加 scoped 属性',
+        '在 componentInfo 中提供清晰的组件描述',
+        '使用有意义的组件标识符（component 字段）',
+        '合理设置 loadModel（页面加载性能相关）',
+        '在发布前确保配置了正确的 username 和 secretKey',
+        '使用 propObj 和 propOption 让组件可配置',
+        '为组件添加适当的事件支持（events/eventsOption）'
+    ]
+};
+
+/**
+ * 常见问题
+ */
+const faq = [
+    {
+        question: '为什么发布时提示 "style scoped 缺失"？',
+        answer: '这是警告信息，不会阻止发布。但强烈建议添加 scoped 属性避免样式污染。将 <style> 改为 <style scoped> 即可。'
+    },
+    {
+        question: '如何配置开发者密钥？',
+        answer: '在项目根目录的 package.json 中添加 username 和 secretKey 字段。这些信息用于身份认证和插件发布。'
+    },
+    {
+        question: '插件创建后在哪里？',
+        answer: '插件会创建在项目根目录下的 plugins/<pluginName>/ 目录中，包含主组件文件、子组件目录和配置文件。'
+    },
+    {
+        question: 'componentInfo 和 config.json 的关系？',
+        answer: 'componentInfo 在 Vue 文件中定义（优先级更高），config.json 作为备选配置。发布时优先使用 componentInfo。'
+    },
+    {
+        question: '如何引入第三方库？',
+        answer: '正常使用 npm install 安装，然后在组件中 import 即可。依赖收集机制会自动处理 node_modules 中的依赖。'
+    },
+    {
+        question: 'loadModel 应该选 lazy 还是 eager？',
+        answer: 'lazy（懒加载）适合大型组件或不常用组件；eager（立即加载）适合核心组件或小型组件。默认推荐 lazy。'
+    }
+];
+
+/**
+ * 错误信息和解决方案
+ */
+const errorMessages = {
+    MISSING_CONFIG: {
+        message: '缺少配置文件或配置不完整',
+        solution: '检查 package.json 中是否配置了 username 和 secretKey，或者 config.json 是否存在且格式正确'
+    },
+    COMPILATION_FAILED: {
+        message: '编译失败',
+        solution: '检查 Vue 组件语法是否正确，确保所有依赖都已安装（npm install）。查看详细错误信息定位问题'
+    },
+    UPLOAD_FAILED: {
+        message: '上传到服务器失败',
+        solution: '检查网络连接、验证 baseUrl 是否正确、确认 username 和 secretKey 是否有效、查看返回的错误信息'
+    },
+    AUTH_FAILED: {
+        message: '身份认证失败',
+        solution: '验证 username 和 secretKey 是否正确，或者检查 pluginToken 是否过期'
+    },
+    INVALID_COMPONENT_NAME: {
+        message: '组件名称不合法',
+        solution: 'component 字段必须唯一，建议使用 "component-" 前缀加上有意义的名称'
+    },
+    MISSING_SCOPED: {
+        message: 'style 标签缺少 scoped 属性',
+        solution: '这是警告而非错误。建议在所有 <style> 标签上添加 scoped 属性：<style lang="scss" scoped>'
+    }
+};
+
+/**
+ * API 参考
+ */
+const apiReference = {
+    name: 'CloudCC 插件 API 参考',
+    description: '插件开发过程中可用的 CloudCC 特定 API',
+    note: '插件运行在浏览器环境中，可以使用所有标准的 Vue API 和浏览器 API。以下是 CloudCC 平台特有的扩展。',
+    platformApis: {
+        componentInfo: {
+            description: '组件元信息配置',
+            usage: '在 data() 中定义 componentInfo 对象',
+            fields: [
+                'component: 组件唯一标识（必需）',
+                'compName: 组件显示名称（必需）',
+                'compDesc: 组件描述（必需）',
+                'bizType: 业务类型（可选）',
+                'category: 分类（可选）',
+                'loadModel: 加载模式（可选，默认 lazy）',
+                'belongOrgFlag: 组织标识（可选，默认 custom）'
+            ]
+        },
+        propObj: {
+            description: '组件可配置属性',
+            usage: '在 data() 中定义 propObj 对象，用户可在配置界面修改这些属性'
+        },
+        propOption: {
+            description: '属性配置界面定义',
+            usage: '在 data() 中定义 propOption 对象，定义 propObj 中每个属性的配置界面'
+        },
+        events: {
+            description: '组件事件定义',
+            usage: '在 data() 中定义 events 对象，定义组件可触发的事件'
+        },
+        style: {
+            description: '组件样式配置',
+            usage: '在 data() 中定义 style 对象，控制组件的尺寸、位置等'
+        }
+    }
+};
+
+/**
+ * 获取编辑指南
+ */
+function getEditGuide(topic = 'overview') {
+    const guides = {
+        overview: `## Vue 插件编辑指南概览
+
+${vuePluginTemplate.name}
+${vuePluginTemplate.description}
+
+### 快速导航
+- component-structure: 组件结构说明
+- config: 配置文件详解
+- data-structure: 数据结构规范
+- style-scoped: 样式作用域最佳实践
+- publish-workflow: 发布流程详解
+- dependency: 依赖收集机制
+- api: API 参考文档
+
+### 核心概念
+1. **组件唯一标识**: componentInfo.component 必须全局唯一
+2. **样式隔离**: 所有样式必须使用 scoped 避免污染
+3. **依赖收集**: 发布时自动收集所有依赖文件
+4. **加载模式**: lazy（懒加载）vs eager（立即加载）
+
+### 注意事项
+${vuePluginTemplate.notes.map(note => `- ${note}`).join('\n')}
+`,
+        'component-structure': `## 组件结构详解
+
+### 主组件模板
+\`\`\`vue
+${vuePluginTemplate.mainComponent}
+\`\`\`
+
+### 子组件模板
+\`\`\`vue
+${vuePluginTemplate.subComponent}
+\`\`\`
+
+### 关键点说明
+${vuePluginTemplate.notes.map(note => `- ${note}`).join('\n')}
+`,
+        config: `## 配置文件详解
+
+### ${configStructure.name}
+${configStructure.description}
+
+### 配置字段
+${Object.entries(configStructure.fields).map(([key, field]) =>
+            `- **${key}** (${field.type}${field.required ? ', 必需' : ', 可选'}): ${field.description}${field.default ? `\n  默认值: ${field.default}` : ''}`
+        ).join('\n')}
+
+### 示例
+\`\`\`json
+${JSON.stringify(configStructure.example, null, 2)}
+\`\`\`
+`,
+        'data-structure': `## 数据结构规范
+
+### ${componentDataStructure.name}
+${componentDataStructure.description}
+
+${Object.entries(componentDataStructure.fields).map(([key, field]) => `
+### ${key}
+**描述**: ${field.description}
+**必需**: ${field.required ? '是' : '否'}
+${field.example ? `**示例**:\n\`\`\`json\n${JSON.stringify(field.example, null, 2)}\n\`\`\`` : ''}
+${field.default ? `**默认值**:\n\`\`\`json\n${JSON.stringify(field.default, null, 2)}\n\`\`\`` : ''}
+${field.fields ? `**字段**:\n${Object.entries(field.fields).map(([k, v]) => `- ${k}: ${v}`).join('\n')}` : ''}
+`).join('\n')}
+`,
+        'style-scoped': `## 样式作用域最佳实践
+
+### ${styleScopedBestPractices.name}
+${styleScopedBestPractices.description}
+
+### 规则清单
+${styleScopedBestPractices.rules.map(rule => rule).join('\n')}
+
+### ✓ 正确示例
+\`\`\`vue
+${styleScopedBestPractices.goodExample}
+\`\`\`
+
+### ✗ 错误示例
+\`\`\`vue
+${styleScopedBestPractices.badExample}
+\`\`\`
+`,
+        'publish-workflow': `## 发布流程详解
+
+### ${publishWorkflow.name}
+
+${publishWorkflow.steps.map(step => step).join('\n')}
+
+### 构建命令
+\`\`\`bash
+${publishWorkflow.buildCommand}
+\`\`\`
+
+### 上传接口
+- **端点**: ${publishWorkflow.uploadEndpoint}
+- **方法**: POST
+
+### 上传数据字段
+${Object.entries(publishWorkflow.uploadData).map(([key, desc]) => `- **${key}**: ${desc}`).join('\n')}
+`,
+        dependency: `## 依赖收集机制
+
+### ${dependencyCollection.name}
+${dependencyCollection.description}
+
+### 收集流程
+${dependencyCollection.process.map(step => step).join('\n')}
+
+### 支持的 Import 模式
+${dependencyCollection.importPatterns.map(pattern => `- ${pattern}`).join('\n')}
+
+### 支持的文件扩展名
+${dependencyCollection.supportedExtensions.map(ext => `- ${ext}`).join('\n')}
+
+### 输出格式
+**格式**: ${dependencyCollection.output.format}
+
+**结构示例**:
+\`\`\`json
+${JSON.stringify(dependencyCollection.output.structure, null, 2)}
+\`\`\`
+`,
+        'project-config': `## 项目配置文件
+
+### ${projectConfigFiles.name}
+${projectConfigFiles.description}
+
+${Object.entries(projectConfigFiles.files).map(([filename, config]) => `
+### ${filename}
+**描述**: ${config.description}
+${config.optional ? '**可选**: 是' : '**必需**: 是'}
+${config.note ? `**注意**: ${config.note}` : ''}
+
+${config.requiredFields ? `**必需字段**:\n${Object.entries(config.requiredFields).map(([key, desc]) => `- **${key}**: ${desc}`).join('\n')}` : ''}
+
+${config.example ? `**示例**:\n\`\`\`json\n${JSON.stringify(config.example, null, 2)}\n\`\`\`` : ''}
+`).join('\n')}
+`,
+        api: `## API 参考文档
+
+### ${apiReference.name}
+${apiReference.description}
+
+**注意**: ${apiReference.note}
+
+${Object.entries(apiReference.platformApis).map(([name, api]) => `
+### ${name}
+**描述**: ${api.description}
+**用法**: ${api.usage}
+${api.fields ? `\n**字段**:\n${api.fields.map(field => `- ${field}`).join('\n')}` : ''}
+`).join('\n')}
+`,
+        bestpractices: `## 最佳实践
+
+### ${usageGuide.name}
+
+### 工作流
+${usageGuide.workflow.map(step => step).join('\n')}
+
+### 最佳实践清单
+${usageGuide.bestPractices.map(practice => `- ${practice}`).join('\n')}
+`,
+        faq: `## 常见问题
+
+${faq.map((item, index) => `
+### ${index + 1}. ${item.question}
+${item.answer}
+`).join('\n')}
+
+## 错误信息参考
+
+${Object.entries(errorMessages).map(([code, error]) => `
+### ${code}
+**错误**: ${error.message}
+**解决方案**: ${error.solution}
+`).join('\n')}
+`
+    };
+
+    return guides[topic] || guides.overview;
+}
+
+module.exports = {
+    vuePluginTemplate,
+    configStructure,
+    componentDataStructure,
+    publishWorkflow,
+    projectConfigFiles,
+    dependencyCollection,
+    styleScopedBestPractices,
+    usageGuide,
+    apiReference,
+    faq,
+    errorMessages,
+    getEditGuide
+};