cloudcc-cli 2.2.2 → 2.2.4

package/src/mcp/tools/Component Creator/handler.js

@@ -0,0 +1,44 @@
+/**
+ * Plugin 工具处理器
+ * 提供 Vue 插件的创建、发布功能
+ * 同时作为 Component Creator 和 Component Publisher 的处理器
+ */
+
+const path = require('path');
+const createPluginModule = require('../../../plugin/create1');
+
+/**
+ * 创建插件/自定义组件
+ */
+async function createCustomComponent({ pluginName, projectPath = process.cwd() }) {
+    try {
+        // 临时改变工作目录以兼容原有模块
+        const originalCwd = process.cwd();
+        process.chdir(projectPath);
+
+        try {
+            await createPluginModule(['plugin', 'create', pluginName]);
+            const pluginPath = path.join(projectPath, `plugins/${pluginName}`);
+            return {
+                content: [{
+                    type: 'text',
+                    text: `✓ 自定义组件创建成功！\n\n组件路径: ${pluginPath}\n生成的文件:\n  - ${pluginName}.vue (主组件文件)\n  - components/HelloWorld.vue (示例子组件)\n  - config.json (配置文件)\n\n下一步:\n1. 编辑 ${pluginName}.vue 实现你的组件逻辑\n2. 在 componentInfo 中配置组件信息\n3. 确保所有 <style> 标签都有 scoped 属性\n4. 使用 publish_plugin 或 publish_component 发布到服务器`
+                }]
+            };
+        } finally {
+            process.chdir(originalCwd);
+        }
+    } catch (error) {
+        return {
+            content: [{
+                type: 'text',
+                text: `✗ 创建失败: ${error.message}\n\n可能的原因:\n- 组件名称已存在\n- 权限不足\n- 磁盘空间不足`
+            }]
+        };
+    }
+}
+
+
+module.exports = {
+    createCustomComponent
+};

package/src/mcp/tools/Component Detail Retriever/handler.js

@@ -0,0 +1,38 @@
+/**
+ * Component Detail Retriever 工具处理器
+ * 获取自定义组件的详细信息
+ */
+
+const detailModule = require('../../../plugin/detail');
+
+/**
+ * 获取自定义组件详细信息
+ * @param {Object} params - 参数对象
+ * @param {string} params.pluginName - 组件名称（可选，优先使用）
+ * @param {string} params.pluginId - 组件ID（可选，当没有pluginName时使用）
+ * @param {string} params.projectPath - 项目路径（可选，默认为当前工作目录）
+ */
+async function getCustomComponentDetail({ pluginName, pluginId, projectPath = process.cwd() }) {
+    try {
+        const originalCwd = process.cwd();
+        process.chdir(projectPath);
+
+        try {
+            const detail = await detailModule(['get', pluginName, pluginId, projectPath]);
+            return { content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }] };
+        } finally {
+            process.chdir(originalCwd);
+        }
+    } catch (error) {
+        return {
+            content: [{
+                type: 'text',
+                text: `✗ 获取失败: ${error.message}\n\n可能的原因:\n- 组件不存在\n- 组件名称或ID不正确\n- 网络连接问题`
+            }]
+        };
+    }
+}
+
+module.exports = {
+    getCustomComponentDetail
+};

package/src/mcp/tools/Component Editor Guide/handler.js

@@ -0,0 +1,76 @@
+/**
+ * Component Editor Guide 工具处理器
+ * 提供自定义组件编辑时的指导和知识库
+ * 
+ * 设计理念：
+ * 1. 默认返回规范、最佳实践、强制要求和API概要
+ * 2. 需要详细信息时再查询具体主题
+ */
+const prompt = require('./prompt');
+
+/**
+ * 获取编辑指南
+ * @param {Object} options - 参数对象
+ * @param {string} options.topic - 指南主题（可选，默认为 'overview'）
+ * @returns {Object} MCP 格式的响应对象
+ * 
+ * 主题说明：
+ * - overview (默认): 📋 规范、最佳实践、强制要求、API概要 - 智能体首先应该阅读
+ * - component-structure: 组件结构说明
+ * - config: 配置文件详解
+ * - data-structure: 数据结构规范
+ * - style-scoped: 样式作用域最佳实践
+ * - publish-workflow: 发布流程详解
+ * - dependency: 依赖收集机制
+ * - api: API 参考文档
+ * - bestpractices: 最佳实践
+ * - faq: 常见问题
+ */
+async function editComponent({ topic = 'overview' } = {}) {
+    try {
+        // 验证 topic 参数
+        const validTopics = [
+            'overview',
+            'component-structure',
+            'config',
+            'data-structure',
+            'style-scoped',
+            'publish-workflow',
+            'dependency',
+            'project-config',
+            'api',
+            'bestpractices',
+            'faq'
+        ];
+
+        if (topic && !validTopics.includes(topic)) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: `✗ 无效的主题: "${topic}"\n\n支持的主题:\n${validTopics.map(t => `- ${t}`).join('\n')}`
+                }]
+            };
+        }
+
+        // 获取指定主题的编辑指南
+        const result = prompt.getEditGuide(topic);
+
+        return {
+            content: [{
+                type: 'text',
+                text: result
+            }]
+        };
+    } catch (error) {
+        return {
+            content: [{
+                type: 'text',
+                text: `✗ 获取编辑指南失败: ${error.message}\n\n错误堆栈:\n${error.stack}`
+            }]
+        };
+    }
+}
+
+module.exports = {
+    editComponent
+};

package/src/mcp/tools/Component Editor Guide/prompt.js

@@ -0,0 +1,519 @@
+/**
+ * Plugin 工具知识库
+ * 提供 Vue 插件模板、配置结构和开发指南
+ */
+
+const { ccdkApiTree } = require('../ccdk/prompt');
+
+/**
+ * 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: '组件描述信息'
+        },
+        loadModel: {
+            type: 'string',
+            required: false,
+            description: '加载模式：lazy（懒加载）或 eager（立即加载）',
+            default: 'lazy'
+        }
+    },
+    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: '组件描述',
+                loadModel: '加载模式（可选，默认 lazy）'
+            }
+        },
+        propObj: {
+            description: '组件属性对象',
+            required: false,
+            example: {
+                title: '默认标题'
+            }
+        },
+        propOption: {
+            description: '属性配置选项',
+            required: false,
+            example: {
+                title: {
+                    label: '标题',
+                    type: 'input'
+                }
+            }
+        }
+    }
+};
+
+
+/**
+ * 样式作用域最佳实践
+ */
+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. 发布插件：cc plugin publish <pluginName>'
+    ],
+    bestPractices: [
+        '始终在 <style> 标签上添加 scoped 属性',
+        'componentInfo.component 必须唯一，建议使用 "component-" 前缀',
+        '合理设置 loadModel（lazy 适合大型组件，eager 适合小型组件）'
+    ]
+};
+
+/**
+ * 常见问题
+ */
+const faq = [
+    {
+        question: '为什么发布时提示 "style scoped 缺失"？',
+        answer: '这是警告信息，不会阻止发布。但强烈建议添加 scoped 属性避免样式污染。将 <style> 改为 <style scoped> 即可。'
+    },
+    {
+        question: 'componentInfo 和 config.json 的关系？',
+        answer: 'componentInfo 在 Vue 文件中定义（优先级更高），config.json 作为备选配置。发布时优先使用 componentInfo。'
+    },
+    {
+        question: 'loadModel 应该选 lazy 还是 eager？',
+        answer: 'lazy（懒加载）适合大型组件或不常用组件；eager（立即加载）适合核心组件或小型组件。默认推荐 lazy。'
+    }
+];
+
+/**
+ * 获取编辑指南
+ */
+function getEditGuide(topic = 'overview') {
+    const guides = {
+        overview: `## Vue 插件编辑指南概览
+
+${vuePluginTemplate.name}
+${vuePluginTemplate.description}
+
+### 快速导航
+- component-structure: 组件结构说明
+- config: 配置文件详解
+- data-structure: 数据结构规范
+- style-scoped: 样式作用域最佳实践
+- ccdk: CCDK API 使用文档
+
+### 核心概念
+1. **组件唯一标识**: componentInfo.component 必须全局唯一
+2. **样式隔离**: 所有样式必须使用 scoped 避免污染
+3. **加载模式**: lazy（懒加载）vs eager（立即加载）
+
+### UI 库和工具
+- **Element UI 2**: 全局已安装，可直接使用，无需额外引入
+- **ECharts**: 全局已安装，可直接使用，无需额外引入
+- **建议**: 优先使用 Vue2 相关的 UI 库进行开发，确保兼容性
+
+### CCDK API 使用
+CCDK 是 CloudCC 提供的全局 API 对象，可在组件中直接使用 \`window.$CCDK\` 或 \`$CCDK\` 访问。
+
+**常用 API 模块**:
+${Object.entries(ccdkApiTree).slice(0, 10).map(([key, module]) =>
+            `- **${module.name}** (\`$CCDK.${key}\`): ${module.description}`
+        ).join('\n')}
+
+**使用示例**:
+\`\`\`javascript
+// 获取用户信息
+const userInfo = $CCDK.CCUser.getUserInfo();
+
+// 消息提示
+$CCDK.CCMessage.showMessage('操作成功', 'success');
+
+// 打开详情页
+const pageId = $CCDK.CCPage.openDetailPage({
+  objectName: '客户',
+  objId: 'account',
+  prefix: '001'
+}, recordId);
+
+// 获取详情页数据
+const detail = $CCDK.CCDetail.getDetail();
+
+// 事件总线
+$CCDK.CCBus.$emit('customEvent', data);
+$CCDK.CCBus.$on('customEvent', (data) => {
+  console.error(data);
+});
+\`\`\`
+
+**更多 API**: 使用 \`ccdk\` 主题查看完整的 CCDK API 文档
+
+### 注意事项
+${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}
+\`\`\`
+`,
+        bestpractices: `## 最佳实践
+
+### ${usageGuide.name}
+
+### 工作流
+${usageGuide.workflow.map(step => step).join('\n')}
+
+### 最佳实践清单
+${usageGuide.bestPractices.map(practice => `- ${practice}`).join('\n')}
+`,
+        ccdk: `## CCDK API 使用文档
+
+CCDK 是 CloudCC 提供的全局 API 对象，可在组件中直接使用 \`window.$CCDK\` 或 \`$CCDK\` 访问。
+
+### 快速开始
+
+\`\`\`javascript
+// 在组件的 methods 或生命周期钩子中使用
+export default {
+  mounted() {
+    // 获取用户信息
+    const userInfo = $CCDK.CCUser.getUserInfo();
+    console.error(userInfo);
+    
+    // 消息提示
+    $CCDK.CCMessage.showMessage('组件加载完成', 'success');
+  }
+}
+\`\`\`
+
+### API 模块列表
+
+${Object.entries(ccdkApiTree).map(([key, module]) => `
+### ${module.name} (\`$CCDK.${key}\`)
+
+**描述**: ${module.description}
+
+**可用方法**:
+${Object.entries(module.apis).map(([apiKey, api]) =>
+            `- **${api.name}**: ${api.description} (${api.version})`
+        ).join('\n')}
+
+**使用示例**:
+${Object.entries(module.apis).slice(0, 1).map(([apiKey, api]) => {
+            // 提取代码示例
+            const content = api.content || '';
+            const codeMatch = content.match(/```js\n([\s\S]*?)```/);
+            if (codeMatch) {
+                return `\`\`\`javascript\n${codeMatch[1]}\n\`\`\``;
+            }
+            return '暂无示例';
+        }).join('\n')}
+`).join('\n')}
+
+### 常用场景示例
+
+**1. 获取和设置详情页数据**
+\`\`\`javascript
+// 获取详情页数据
+const detail = $CCDK.CCDetail.getDetail();
+const detailId = $CCDK.CCDetail.getDetailId();
+
+// 设置详情页数据
+$CCDK.CCDetail.setDetail({
+  id: detailId,
+  detail: updatedData
+});
+\`\`\`
+
+**2. 打开页面**
+\`\`\`javascript
+// 打开详情页
+const pageId = $CCDK.CCPage.openDetailPage({
+  objectName: '客户',
+  objId: 'account',
+  objectApi: 'Account',
+  prefix: '001'
+}, recordId, {
+  openPlace: 'dialog',
+  openMode: '_blank'
+});
+
+// 打开新建页
+const createPageId = $CCDK.CCPage.openCreatePage({
+  objectName: '客户',
+  objId: 'account',
+  prefix: '001'
+}, {
+  openPlace: 'dialog'
+});
+\`\`\`
+
+**3. 消息提示**
+\`\`\`javascript
+// 简单提示
+$CCDK.CCMessage.showMessage('操作成功', 'success');
+
+// 确认对话框
+$CCDK.CCMessage.showConfirm(
+  '确定要删除吗？',
+  '确认删除',
+  {},
+  () => {
+    // 确认回调
+    console.error('确认');
+  },
+  () => {
+    // 取消回调
+    console.error('取消');
+  }
+);
+
+// 通知
+$CCDK.CCMessage.showNotification({
+  title: '提示',
+  message: '这是一条通知消息',
+  type: 'success'
+});
+\`\`\`
+
+**4. 事件总线**
+\`\`\`javascript
+// 发布事件
+$CCDK.CCBus.$emit('dataUpdated', { id: '123', name: 'test' });
+
+// 订阅事件
+$CCDK.CCBus.$on('dataUpdated', (data) => {
+  console.error('数据已更新', data);
+});
+
+// 取消订阅（在组件销毁时）
+this.$once('hook:beforeDestroy', () => {
+  $CCDK.CCBus.$off('dataUpdated');
+});
+\`\`\`
+
+**5. 调用自定义类**
+\`\`\`javascript
+$CCDK.CCCommon.post('MyClass', 'myMethod', [
+  {
+    argType: 'java.lang.String',
+    argValue: 'hello'
+  }
+]).then((res) => {
+  console.error(res.data);
+}).catch((error) => {
+  console.error(error);
+});
+\`\`\`
+
+### 注意事项
+- CCDK API 在组件运行时环境中全局可用，无需导入
+- 使用事件总线时，记得在组件销毁时取消订阅，避免内存泄漏
+- 页面操作 API（如 openDetailPage）返回的 pageId 可用于后续的页面操作
+- 详情页相关 API 需要在详情页上下文中使用才能正常工作
+`,
+        faq: `## 常见问题
+
+${faq.map((item, index) => `
+### ${index + 1}. ${item.question}
+${item.answer}
+`).join('\n')}
+`
+    };
+
+    return guides[topic] || guides.overview;
+}
+
+module.exports = {
+    vuePluginTemplate,
+    configStructure,
+    componentDataStructure,
+    styleScopedBestPractices,
+    usageGuide,
+    faq,
+    getEditGuide
+};