cloudcc-cli 2.2.3 → 2.2.4

package/src/mcp/tools/Client Script Editor Guide/handler.js

@@ -0,0 +1,633 @@
+/**
+ * Client Script Editor Guide 工具处理器
+ * 提供客户端脚本编辑时的指导和知识库
+ * 
+ * 设计理念：
+ * 1. 默认返回规范、最佳实践、强制要求和API概要
+ * 2. 需要详细信息时再查询具体主题
+ * 3. 使用 CCDK 知识库提供 API 参考
+ */
+const { ccdkApiTree } = require('../ccdk/prompt');
+
+/**
+ * 获取编辑指南
+ * @param {Object} options - 参数对象
+ * @param {string} options.topic - 指南主题（可选，默认为 'overview'）
+ * @returns {Object} MCP 格式的响应对象
+ * 
+ * 主题说明：
+ * - overview (默认): 📋 规范、最佳实践、强制要求、API概要 - 智能体首先应该阅读
+ * - structure: 脚本结构说明
+ * - config: 配置文件详解
+ * - ccdk-api: CCDK API 参考文档
+ * - bestpractices: 最佳实践
+ * - faq: 常见问题
+ */
+async function editClientScript({ topic = 'overview' } = {}) {
+    try {
+        // 验证 topic 参数
+        const validTopics = [
+            'overview',
+            'structure',
+            'config',
+            'ccdk-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 = getEditGuide(topic);
+
+        return {
+            content: [{
+                type: 'text',
+                text: result
+            }]
+        };
+    } catch (error) {
+        return {
+            content: [{
+                type: 'text',
+                text: `✗ 获取编辑指南失败: ${error.message}\n\n错误堆栈:\n${error.stack}`
+            }]
+        };
+    }
+}
+
+/**
+ * 获取编辑指南内容
+ */
+function getEditGuide(topic) {
+    switch (topic) {
+        case 'overview':
+            return getOverviewGuide();
+        case 'structure':
+            return getStructureGuide();
+        case 'config':
+            return getConfigGuide();
+        case 'ccdk-api':
+            return getCcdkApiGuide();
+        case 'bestpractices':
+            return getBestPracticesGuide();
+        case 'faq':
+            return getFaqGuide();
+        default:
+            return getOverviewGuide();
+    }
+}
+
+/**
+ * 概览指南
+ */
+function getOverviewGuide() {
+    return `# CloudCC 客户端脚本编辑指南 - 概览
+
+## 📋 规范与强制要求
+
+### 1. 脚本结构规范
+- **必须**包含 \`function main($CCDK, obj)\` 函数
+- 函数签名必须完全匹配：\`function main($CCDK, obj)\`
+- 脚本内容会被提取并上传到服务器（只提取函数体内容）
+
+### 2. 文件结构
+\`\`\`
+script/
+  {objName}/
+    {scriptName}/
+      {scriptName}.js    # 脚本文件
+      config.json        # 配置文件
+\`\`\`
+
+### 3. 配置文件要求
+- \`config.json\` 必须包含以下字段：
+  - \`scriptName\`: 脚本名称
+  - \`objName\`: 对象名称
+  - \`id\`: 脚本ID（发布后自动生成）
+  - 其他配置字段根据使用场景设置
+
+## 🎯 最佳实践
+
+### 1. 脚本编写
+- 使用 \`$CCDK\` 对象访问 CloudCC API
+- 使用 \`obj\` 参数获取上下文信息
+- 添加适当的错误处理
+- 使用 \`console.error\` 进行调试（开发环境）
+
+### 2. 代码组织
+- 保持函数简洁，单一职责
+- 使用有意义的变量名
+- 添加必要的注释
+
+### 3. 性能优化
+- 避免在循环中进行大量操作
+- 合理使用异步操作
+- 避免不必要的 DOM 操作
+
+## 📖 API 概要
+
+### $CCDK 对象
+CloudCC 提供的全局对象，包含以下主要模块：
+
+${Object.keys(ccdkApiTree).map(module => {
+    const moduleInfo = ccdkApiTree[module];
+    const apiCount = Object.keys(moduleInfo.apis).length;
+    return `- **${module}** (${moduleInfo.name}): ${moduleInfo.description} - ${apiCount} 个 API`;
+}).join('\n')}
+
+### obj 参数
+客户端脚本执行时的上下文对象，包含：
+- \`formId\`: 表单ID（新建/编辑页面）
+- \`fieldKey\`: 字段标识（onChange 事件）
+- \`recordId\`: 记录ID（详情页）
+- 其他上下文相关信息
+
+## 🔧 常用场景
+
+### 1. 表单字段联动
+\`\`\`javascript
+function main($CCDK, obj) {
+    const formId = obj.formId;
+    const fieldValue = obj.fieldValue;
+    
+    // 根据字段值设置其他字段
+    $CCDK.CCUtils.setFormFieldValue({
+        formId: formId,
+        list: [{
+            fieldKey: 'targetField',
+            value: fieldValue
+        }]
+    });
+}
+\`\`\`
+
+### 2. 页面跳转
+\`\`\`javascript
+function main($CCDK, obj) {
+    const recordId = obj.recordId;
+    
+    // 打开详情页
+    $CCDK.CCPage.openDetailPage({
+        objectName: '客户',
+        objId: 'account',
+        prefix: '001'
+    }, recordId);
+}
+\`\`\`
+
+### 3. 消息提示
+\`\`\`javascript
+function main($CCDK, obj) {
+    $CCDK.CCMessage.showMessage('操作成功', 'success');
+}
+\`\`\`
+
+## 📚 下一步
+
+- 查看 \`structure\` 主题了解脚本结构详情
+- 查看 \`config\` 主题了解配置文件详解
+- 查看 \`ccdk-api\` 主题获取完整的 CCDK API 文档
+- 查看 \`bestpractices\` 主题了解最佳实践
+- 查看 \`faq\` 主题查看常见问题
+
+💡 **提示**: 使用 \`get_client_script_editor_guide\` 工具并指定 \`topic\` 参数获取详细文档`;
+}
+
+/**
+ * 脚本结构指南
+ */
+function getStructureGuide() {
+    return `# 客户端脚本结构说明
+
+## 基本结构
+
+客户端脚本必须遵循以下结构：
+
+\`\`\`javascript
+function main($CCDK, obj) {
+    // 你的脚本代码
+}
+\`\`\`
+
+## 函数签名
+
+### function main($CCDK, obj)
+
+- **$CCDK**: CloudCC 提供的全局 API 对象
+- **obj**: 执行上下文对象，包含当前页面/字段/记录等信息
+
+## obj 对象结构
+
+根据不同的执行场景，obj 对象包含不同的属性：
+
+### 新建/编辑页面 (onLoad)
+\`\`\`javascript
+{
+    formId: "form_123",      // 表单ID
+    recordId: null,          // 新建时为 null，编辑时有值
+    // ... 其他上下文信息
+}
+\`\`\`
+
+### 字段变更 (onChange)
+\`\`\`javascript
+{
+    formId: "form_123",      // 表单ID
+    fieldKey: "field_apiname", // 字段标识
+    fieldValue: "新值",      // 字段新值
+    // ... 其他上下文信息
+}
+\`\`\`
+
+### 详情页
+\`\`\`javascript
+{
+    recordId: "00120227805836AlIEL4", // 记录ID
+    // ... 其他上下文信息
+}
+\`\`\`
+
+## 脚本内容提取
+
+发布时，系统会：
+1. 检查是否存在 \`function main($CCDK, obj)\` 函数
+2. 提取函数体内容（大括号内的代码）
+3. 上传到服务器
+
+**注意**: 只有函数体内的代码会被上传，函数签名不会上传。`;
+}
+
+/**
+ * 配置文件指南
+ */
+function getConfigGuide() {
+    return `# 客户端脚本配置文件说明
+
+## config.json 结构
+
+\`\`\`json
+{
+    "scriptName": "脚本名称",
+    "scriptDesc": "脚本描述",
+    "objId": "对象ID",
+    "objName": "对象名称",
+    "recordTypeId": "记录类型ID",
+    "recordTypeName": "记录类型名称",
+    "pageId": "页面ID",
+    "eventType": "事件类型",
+    "event": "事件",
+    "fieldId": "字段ID",
+    "schemetableName": "对象表名",
+    "usageScenario": "使用场景",
+    "id": "脚本ID（发布后自动生成）"
+}
+\`\`\`
+
+## 字段说明
+
+### 必填字段
+- \`scriptName\`: 脚本名称，必须与目录名和文件名一致
+- \`objName\`: 对象名称
+
+### 可选字段
+- \`scriptDesc\`: 脚本描述
+- \`objId\`: 对象ID
+- \`recordTypeId\`: 记录类型ID
+- \`pageId\`: 页面ID
+- \`eventType\`: 事件类型（如：onLoad, onChange）
+- \`event\`: 事件名称
+- \`fieldId\`: 字段ID
+- \`schemetableName\`: 对象表名
+- \`usageScenario\`: 使用场景
+
+### 自动生成字段
+- \`id\`: 脚本ID，首次发布后自动添加到配置文件中
+
+## 配置示例
+
+### onLoad 事件脚本
+\`\`\`json
+{
+    "scriptName": "initForm",
+    "scriptDesc": "初始化表单",
+    "objName": "Account",
+    "eventType": "onLoad",
+    "event": "onLoad"
+}
+\`\`\`
+
+### onChange 事件脚本
+\`\`\`json
+{
+    "scriptName": "fieldChange",
+    "scriptDesc": "字段变更处理",
+    "objName": "Account",
+    "eventType": "onChange",
+    "event": "onChange",
+    "fieldId": "field_123"
+}
+\`\`\``;
+}
+
+/**
+ * CCDK API 指南
+ */
+function getCcdkApiGuide() {
+    let content = `# CCDK API 参考文档
+
+## 模块概览
+
+CloudCC CCDK 提供了丰富的 API 模块，用于客户端脚本开发：
+
+`;
+
+    Object.entries(ccdkApiTree).forEach(([moduleName, moduleInfo]) => {
+        const apiCount = Object.keys(moduleInfo.apis).length;
+        content += `### ${moduleName} - ${moduleInfo.name}\n\n`;
+        content += `${moduleInfo.description}\n\n`;
+        content += `**API 数量**: ${apiCount}\n\n`;
+        content += `**包含的 API**:\n`;
+        Object.entries(moduleInfo.apis).forEach(([apiName, apiInfo]) => {
+            content += `- \`${apiName}\`: ${apiInfo.description} (${apiInfo.version})\n`;
+        });
+        content += '\n';
+    });
+
+    content += `\n## 使用示例\n\n`;
+    content += `### 获取当前用户信息\n\`\`\`javascript\nfunction main($CCDK, obj) {\n    const userInfo = $CCDK.CCUser.getUserInfo();\n    console.error(userInfo);\n}\n\`\`\`\n\n`;
+    content += `### 打开详情页\n\`\`\`javascript\nfunction main($CCDK, obj) {\n    $CCDK.CCPage.openDetailPage({\n        objectName: '客户',\n        objId: 'account',\n        prefix: '001'\n    }, '00120227805836AlIEL4');\n}\n\`\`\`\n\n`;
+    content += `### 设置表单字段值\n\`\`\`javascript\nfunction main($CCDK, obj) {\n    $CCDK.CCUtils.setFormFieldValue({\n        formId: obj.formId,\n        list: [{\n            fieldKey: 'field_apiname',\n            value: '新值'\n        }]\n    });\n}\n\`\`\`\n\n`;
+    content += `\n💡 **提示**: 使用 \`get_ccdk_docs\` 工具获取特定模块的详细 API 文档`;
+
+    return content;
+}
+
+/**
+ * 最佳实践指南
+ */
+function getBestPracticesGuide() {
+    return `# 客户端脚本最佳实践
+
+## 1. 代码组织
+
+### 保持函数简洁
+\`\`\`javascript
+// ✅ 好的做法
+function main($CCDK, obj) {
+    const formId = obj.formId;
+    const value = getFieldValue(obj);
+    setTargetField($CCDK, formId, value);
+}
+
+function getFieldValue(obj) {
+    return obj.fieldValue || '';
+}
+
+function setTargetField($CCDK, formId, value) {
+    $CCDK.CCUtils.setFormFieldValue({
+        formId: formId,
+        list: [{ fieldKey: 'target', value: value }]
+    });
+}
+\`\`\`
+
+\`\`\`javascript
+// ❌ 不好的做法
+function main($CCDK, obj) {
+    // 所有逻辑都写在一个函数里，难以维护
+    const formId = obj.formId;
+    const value = obj.fieldValue || '';
+    $CCDK.CCUtils.setFormFieldValue({
+        formId: formId,
+        list: [{ fieldKey: 'target', value: value }]
+    });
+    // ... 更多代码
+}
+\`\`\`
+
+## 2. 错误处理
+
+### 添加适当的错误处理
+\`\`\`javascript
+function main($CCDK, obj) {
+    try {
+        if (!obj.formId) {
+            throw new Error('表单ID不存在');
+        }
+        
+        // 你的业务逻辑
+        doSomething($CCDK, obj);
+    } catch (error) {
+        $CCDK.CCMessage.showMessage('操作失败: ' + error.message, 'error');
+        console.error('Script Error:', error);
+    }
+}
+\`\`\`
+
+## 3. 性能优化
+
+### 避免不必要的操作
+\`\`\`javascript
+// ✅ 好的做法：只在需要时执行
+function main($CCDK, obj) {
+    if (obj.fieldValue === '特定值') {
+        performExpensiveOperation($CCDK, obj);
+    }
+}
+\`\`\`
+
+\`\`\`javascript
+// ❌ 不好的做法：总是执行
+function main($CCDK, obj) {
+    performExpensiveOperation($CCDK, obj); // 即使不需要也执行
+}
+\`\`\`
+
+## 4. 数据验证
+
+### 验证输入数据
+\`\`\`javascript
+function main($CCDK, obj) {
+    const value = obj.fieldValue;
+    
+    if (!value || value.trim() === '') {
+        $CCDK.CCMessage.showMessage('请输入有效值', 'warning');
+        return;
+    }
+    
+    // 继续处理
+}
+\`\`\`
+
+## 5. 异步操作
+
+### 正确处理异步操作
+\`\`\`javascript
+function main($CCDK, obj) {
+    $CCDK.CCCommon.post('ClassName', 'methodName', [])
+        .then(res => {
+            // 处理成功结果
+            console.error('Success:', res.data);
+        })
+        .catch(error => {
+            // 处理错误
+            $CCDK.CCMessage.showMessage('操作失败', 'error');
+            console.error('Error:', error);
+        });
+}
+\`\`\`
+
+## 6. 代码注释
+
+### 添加有意义的注释
+\`\`\`javascript
+function main($CCDK, obj) {
+    // 获取表单ID
+    const formId = obj.formId;
+    
+    // 根据业务规则设置目标字段值
+    const targetValue = calculateTargetValue(obj);
+    
+    // 更新表单字段
+    updateFormField($CCDK, formId, targetValue);
+}
+\`\`\``;
+}
+
+/**
+ * 常见问题指南
+ */
+function getFaqGuide() {
+    return `# 客户端脚本常见问题
+
+## Q1: 脚本发布失败，提示"没有找到有效的 main 函数"
+
+**A**: 确保脚本文件包含以下格式：
+\`\`\`javascript
+function main($CCDK, obj) {
+    // 你的代码
+}
+\`\`\`
+
+注意：
+- 函数名必须是 \`main\`
+- 参数必须是 \`$CCDK, obj\`（顺序不能错）
+- 函数签名必须完全匹配
+
+## Q2: 如何获取表单字段的值？
+
+**A**: 使用 \`$CCDK.CCUtils.getFormFieldValue\`:
+\`\`\`javascript
+function main($CCDK, obj) {
+    const formId = obj.formId;
+    $CCDK.CCUtils.getFormFieldValue({
+        formId: formId,
+        list: [{ fieldKey: 'field_apiname' }]
+    }).then(result => {
+        console.error('字段值:', result);
+    });
+}
+\`\`\`
+
+## Q3: 如何设置表单字段的值？
+
+**A**: 使用 \`$CCDK.CCUtils.setFormFieldValue\`:
+\`\`\`javascript
+function main($CCDK, obj) {
+    const formId = obj.formId;
+    $CCDK.CCUtils.setFormFieldValue({
+        formId: formId,
+        list: [{
+            fieldKey: 'target_field',
+            value: '新值'
+        }]
+    });
+}
+\`\`\`
+
+## Q4: 如何打开其他页面？
+
+**A**: 使用 \`$CCDK.CCPage\` 相关方法：
+\`\`\`javascript
+// 打开详情页
+$CCDK.CCPage.openDetailPage(obj, recordId);
+
+// 打开新建页
+$CCDK.CCPage.openCreatePage(obj);
+
+// 打开编辑页
+$CCDK.CCPage.openEditPage(obj, recordId);
+\`\`\`
+
+## Q5: 如何显示消息提示？
+
+**A**: 使用 \`$CCDK.CCMessage\`:
+\`\`\`javascript
+// 普通消息
+$CCDK.CCMessage.showMessage('提示信息', 'success');
+
+// 确认框
+$CCDK.CCMessage.showConfirm('确认信息', '标题', {}, 
+    () => { /* 确认回调 */ },
+    () => { /* 取消回调 */ }
+);
+\`\`\`
+
+## Q6: 拉取脚本时提示"Script ID is not exist"
+
+**A**: 这意味着脚本还没有发布过。需要：
+1. 先使用 \`publish_client_script\` 发布脚本
+2. 发布成功后，config.json 会自动添加 \`id\` 字段
+3. 之后就可以使用 \`pull_client_script\` 拉取了
+
+## Q7: 如何调试脚本？
+
+**A**: 
+1. 使用 \`console.error\` 输出调试信息（开发环境）
+2. 检查浏览器控制台
+3. 使用 \`$CCDK.CCMessage.showMessage\` 显示调试信息
+
+## Q8: 脚本执行时机是什么？
+
+**A**: 根据配置的 \`eventType\` 和 \`event\` 决定：
+- \`onLoad\`: 页面加载时执行
+- \`onChange\`: 字段值变更时执行
+- 其他事件根据配置执行
+
+## Q9: 如何调用自定义类？
+
+**A**: 使用 \`$CCDK.CCCommon.post\`:
+\`\`\`javascript
+$CCDK.CCCommon.post('ClassName', 'methodName', [
+    { argType: 'java.lang.String', argValue: 'value1' },
+    { argType: 'java.lang.String', argValue: 'value2' }
+]).then(res => {
+    console.error('结果:', res.data);
+});
+\`\`\`
+
+## Q10: 脚本文件应该放在哪里？
+
+**A**: 脚本文件应该放在：
+\`\`\`
+script/{objName}/{scriptName}/{scriptName}.js
+\`\`\`
+
+例如：
+\`\`\`
+script/Account/myScript/myScript.js
+\`\`\``;
+}
+
+module.exports = {
+    editClientScript
+};
+

package/src/mcp/tools/Client Script List Retriever/handler.js

@@ -0,0 +1,68 @@
+/**
+ * Client Script List Retriever 工具处理器
+ * 提供客户端脚本列表查询功能
+ */
+
+const getScriptModule = require('../../../script/get');
+
+/**
+ * 获取客户端脚本列表
+ * @param {Object} params - 参数对象
+ * @param {string} params.projectPath - 项目根目录路径
+ * @param {Object} params.condition - 查询条件（可选）
+ */
+async function listClientScripts({ projectPath = process.cwd(), condition = {} }) {
+    try {
+        const originalCwd = process.cwd();
+        process.chdir(projectPath);
+
+        try {
+            // 构建查询条件
+            const configContent = {
+                pageSize: 10000,
+                pageNo: 1,
+                condition: {
+                    id: condition.id || '',
+                    pageLabel: condition.pageLabel || '',
+                    objName: condition.objName || ''
+                }
+            };
+
+            // 将配置对象编码为 URI 格式（get.js 期望的格式）
+            const encodedConfig = encodeURI(JSON.stringify(configContent));
+
+            // 调用原有的 get 模块
+            const scriptList = await getScriptModule(['get', 'script', encodedConfig, projectPath], true);
+
+            if (!scriptList || scriptList.length === 0) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: '未找到任何客户端脚本\n\n提示：使用 create_client_script 创建新脚本'
+                    }]
+                };
+            }
+
+            return {
+                content: [{
+                    type: 'text',
+                    text: JSON.stringify(scriptList, null, 2)
+                }]
+            };
+        } finally {
+            process.chdir(originalCwd);
+        }
+    } catch (error) {
+        return {
+            content: [{
+                type: 'text',
+                text: `✗ 查询失败: ${error.message}\n\n可能的原因:\n- 项目路径不正确\n- 网络连接问题\n- 服务器API不可用`
+            }]
+        };
+    }
+}
+
+module.exports = {
+    listClientScripts
+};
+