cuxml 1.0.6 → 2.1.0

package/README.md

@@ -1,140 +1,253 @@
-# cuxml
+# CUXML
 
-CU: `'Can Use'` or `'customUI'`, whatever……
+> CU: `'Can Use'` or `'customUI'`, whatever……
 
-## What is it?
+[![npm version](https://badge.fury.io/js/cuxml.svg)](https://www.npmjs.com/package/cuxml)
+[![License](https://img.shields.io/npm/l/cuxml.svg)](LICENSE)
 
-1. 可以将 customUI XML 设置的回调函数转成 JavaScript 函数，以便于在 WPS Office JS插件中使用，当然只是些简单的模版，复杂的还是需要自己写。
-    > Can convert the callback functions of customUI XML settings to JavaScript functions, so that they can be used in WPS Office JS plug-ins. Of course, it is just some simple templates, and complex ones need to be written by yourself.
+**CUXML** 是一个专为 WPS Office JS 插件开发者设计的工具，用于处理 RibbonUI XML 文件。它可以显著简化开发流程，让你更专注于业务逻辑。
 
-3. 根据 CustomUI Ribbon 元素的布局规则和标准，帮助你快速粗略地检查 XML 文件是否符合规范。[simple types](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-customui/869c8c9a-45f8-4119-b068-f61e76d04322)
-    > According to the layout rules and standards of CustomUI Ribbon elements, help you quickly and roughly check whether the XML file conforms to the specification.
+## ✨ 特性
 
->Only the namespace of Simple types  in the http://schemas.microsoft.com/office/2006/01/customui  are supported. It's may be support for customUI 2007/2010…… also.
+- 🔄 **XML 到 JavaScript 转换** - 自动将 RibbonUI XML 的回调函数配置转换为 JavaScript 代码
+- 🔍 **XML 合规性检查** - 全面检查 XML 文件是否符合 CustomUI 规范
+- 👀 **文件监视** - 监视 XML 文件变化，自动重新转换
+- 📦 **模块化 API** - 提供完整的编程接口，支持同步和异步调用
+- 🔌 **MCP 支持** - 可作为 MCP 插件集成到 AI 工具链中
 
-## 示例 Example
+## 📦 安装
 
-XML file:
+```bash
+npm install -g cuxml
+```
 
-```xml
- <group id="test1" label="test1" getVisible="onthing"></group>
+## 🚀 快速开始
+
+### 命令行使用
+
+#### 转换 XML 文件
+
+```bash
+# 基本用法（不指定输出路径时，自动生成 {input}_temp.js）
+cuxml -i ./ribbon.xml  # 输出到 ./ribbon_temp.js
+
+# 指定输出路径
+cuxml -i ./ribbon.xml -o ./ribbon.js
+
+# 监视模式（文件变化时自动转换）
+cuxml -i ./ribbon.xml -w  # 输出到 ./ribbon_temp.js
+
+# 使用默认输入路径（当前目录下的 ribbon.xml）
+cuxml  # 需要在当前目录有 ribbon.xml 文件
 ```
 
-输出到 JS 文件：
+#### 检查 XML 文件
 
-> Out callback function to JS file:
+```bash
+cuxml check ./ribbon.xml
+
+# 显示详细信息
+cuxml check ./ribbon.xml -v
+```
+
+#### 查看帮助
 
 ```bash
-cuxml callback test.xml test.js -w
+cuxml -h
+cuxml check -h
+cuxml convert -h
 ```
 
-不出意外的话，你会得到这样的结果：
-> normally, you will get the result:
-
-```js
-/**
-* @param {RibbonUI} ctrl 你不需要关心这个参数，它代表一个菜单控件元素对象。比如 button、group 等。
-* @note 
-*  - 这是控件的回调函数，你不应该调用这个函数。
-*  - 通用模版而已，你可以根据需要自行修改。
-*  - 这里的回调函数都是异步的，你不应该在这里写长耗时同步的代码，否则可能会导致 UI 卡死。(AI 说的)
-*  
-*  Time: Fri Apr 14 2023 01:43:09 GMT+0800 (China Standard Time)
-*/
-function onthing(ctrl){
-
-    // 以下代码只是通用模版，你可以根据需要自行修改
-    // 通过 ctrl.Id 来判断当前元素
-    // use ctrl.Id to judge the current element
-
-    switch(ctrl.Id){
-        // xmlPath: customUI[0]>ribbon[0]>tabs[0]>tab[0]>group[2]
-        case "test1":
+### API 使用
+
+```javascript
+const cuxml = require('cuxml');
+
+// 转换 XML 到 JavaScript
+cuxml.convert('./ribbon.xml', './ribbon.js')
+  .then(result => console.log(result))
+  .catch(error => console.error(error));
+
+// 同步转换
+const result = cuxml.convertSync('./ribbon.xml', './ribbon.js');
+
+// 检查 XML 文件
+cuxml.check('./ribbon.xml')
+  .then(result => console.log(result));
+
+// 同步检查
+const checkResult = cuxml.checkSync('./ribbon.xml');
+
+// 检查 XML 字符串
+cuxml.check('<customUI xmlns="...">...</customUI>');
+
+// 监视文件变化
+const watcher = cuxml.watch('./ribbon.xml', './ribbon.js');
+// 停止监视: watcher.close();
+
+// 格式化检查结果
+const detailedResult = cuxml.checkSync('./ribbon.xml', { detailed: true });
+console.log(cuxml.formatCheckResult(detailedResult));
+```
+
+### MCP 插件
+
+CUXML 可以作为 MCP (Model Context Protocol) 插件使用：
+
+```javascript
+// 安装 MCP SDK
+npm install @modelcontextprotocol/sdk
+
+// 配置 MCP 服务器
+{
+  "mcpServers": {
+    "cuxml": {
+      "command": "node",
+      "args": ["./node_modules/cuxml/src/mcp.js"]
+    }
+  }
+}
+```
+
+## 📖 详细文档
+
+完整的使用文档和技术细节请参考：[CUXML Agent 文档](./test/agent_new.md)
+
+## 🔧 功能说明
+
+### XML 到 JavaScript 转换
+
+将 RibbonUI XML 文件中的回调函数配置自动转换为 JavaScript 函数代码：
+
+- 智能解析 XML 中的回调函数属性
+- 生成标准化的 JavaScript 函数模板
+- 支持自动函数名处理（带 `.` 连接符的属性名会被截取）
+- 自动处理函数名：`onClick.button1` → `button1`
+
+**示例：**
+
+```xml
+<button id="myButton" onAction="handleClick" label="点击我"/>
+```
+
+生成：
+
+```javascript
+function handleClick(ctrl) {
+    switch (ctrl.Id) {
+        case "myButton":
+            // TODO: 实现控件逻辑
             break;
         default:
             break;
-    };
-
-    // 避免 UI 报错，总是返回 true
-    // Need return true
-
+    }
     return true;
 }
+```
 
+### XML 合规性检查
+
+全面检查 XML 文件是否符合 CustomUI 规范：
+
+- ✅ XML 语法规范性
+- ✅ ID 唯一性检查（防止重复 ID）
+- ✅ 属性冲突检测（如 `label` 和 `getLabel` 不能同时存在）
+- ✅ 标签嵌套合规性
+- ✅ 属性值类型验证
+- ✅ 元素不支持的属性检测
+
+## 📁 项目结构
+
+```
+cuxml/
+├── src/
+│   ├── api.js          # API 模块
+│   ├── checker.js      # XML 检查器
+│   ├── cli.js          # CLI 工具
+│   ├── converter.js    # 转换器
+│   ├── mcp.js          # MCP 插件
+│   ├── parser.js       # XML 解析器
+│   └── templates.js    # 模板生成器
+├── lib/
+│   ├── simpleTypes.json        # Simple Types 配置
+│   ├── clashAttributes.json    # 冲突属性配置
+│   ├── StDelegate.json        # 回调函数属性配置
+│   └── cbfTypes.json         # Callback 函数类型配置
+├── test/              # 测试文件和示例
+├── index.js           # 主入口
+└── package.json
 ```
 
-# Command
-
-1. Run in Your WPS Office JS Plugin Project directory.
-
-    ```bash
-    npx cuxml # if support npx
-    ```
-    or
-    ```bash
-    node ./node_modules/cuxml/index.js # last choice……
-    ``` 
-> 更多命令行参数请查看 --help 选项.
-> More command line parameters, please check the --help option.
-
-## 注意
-
-**输出结果到文件时，保险起见，最好输出到临时文件，避免覆盖你已经写好的文件。**
-
-## 最新更新
-
-1. check， 仅输出有'问题'的 Element。
-2. callback :
-    + id 为空的 Element 会被忽略。
-    + 匹配属性的回调函数返回值类型，在注释中标明。
-    + JS 函数的注释中，添加了回调函数对应的 XML 元素属性。
-    + 生成的 JS 函数只有一个参数，即 RibbonUI 对象。**不必添加多余的参数，目前 WPS Office Client 传参数时只有一个！**
-        ```js
-        // RibbonUI 对象成员大概如下：
-        {
-            Id: "test1", // 当前元素的 id 属性
-            content:{...},
-            Tag: "",// 如果你在 XML 中设置了 tag 属性，这里就会有值。
-        }
-        ```
-
-## Bug
-
-1. 可预见的： 如果 XML 中的回调函数名称带有" `.` "连接符，生成的 JS 代码会有语法错误。
-    > Predictable: If the callback function name in XML contains a "`.`" connection symbol, the generated JS code will have a syntax error.
-    
-    这种情况，cuxml 可能不适合用来批量生成 JS 回调函数。
-    > In this case, cuxml may not be suitable for generating JS callback functions in batches.
-
-    example:
-    ```xml
-    <group id="test1" label="test1" getVisible="on.thing"></group>
-    ```
-    > output:
-    ```js
-    function on.thing(ctrl){
-        // ...
-    }
-    ```
+## 🎯 最佳实践
+
+### 1. 文件组织
+
+```
+project/
+├── src/
+│   └── ribbon.xml          # RibbonUI 配置文件
+├── gen/
+│   └── ribbon_callbacks.js # 自动生成的回调函数
+├── main.js                 # 主逻辑文件
+└── package.json
+```
+
+### 2. 开发工作流
+
+```bash
+# 开发阶段：使用监视模式，实时更新
+cuxml -i src/ribbon.xml -o gen/ribbon_callbacks.js -w
+
+# 构建阶段：生成并验证
+cuxml check src/ribbon.xml && cuxml -i src/ribbon.xml -o gen/ribbon_callbacks.js
+```
+
+### 3. 错误处理
+
+```javascript
+const cuxml = require('cuxml');
+
+try {
+  cuxml.check('./ribbon.xml');
+  cuxml.convert('./ribbon.xml', './ribbon.js');
+  console.log('✅ 转换成功！');
+} catch (error) {
+  console.error('❌ 转换失败：', error.message);
+  // 处理错误
+}
+```
+
+## 🔗 相关资源
+
+- [Microsoft CustomUI 规范](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-customui/574eeee8-7a03-406a-b95f-f9e51e53dd9d)
+- [Simple Types 参考](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-customui/869c8c9a-45f8-4119-b068-f61e76d04322)
+- [WPS Office 开发文档](https://wps.cn/developer/)
+- [CUXML Agent 文档](./test/agent_new.md) - 完整的使用文档
+
+## 🤝 贡献
+
+欢迎贡献！请随时提交 Issue 或 Pull Request。
+
+## 📄 许可证
+
+[ISC](LICENSE)
+
+## 📊 版本历史
 
-    是的， 我们能解决这个问题，但是，JS 函数的调用和声明方式是多变的，比如：
+### v2.0.0 (2026-02-14)
 
-    ```xml
-    <group id="test1" label="test1" getVisible="onthing"></group>
-    ```
+**重大更新：完全重构**
 
-    ```js
-    // cuxml 能将其转换为 function nothing(ctrl){};
-    // 实际上也许你偏向于这种写法： let nothing = function(ctrl){};
-    // 又或者它实际可能是：sync function nothing(ctrl){};
-    ```
-    
-    类似以下的写法，cuxml 可能无法准确的转换
+- ✨ 全新的模块化架构
+- ✨ 完整的 API 模块（支持同步和异步）
+- ✨ 统一的 CLI 命令（`cuxml`）
+- ✨ MCP 协议支持
+- ✨ 完整的 JSDoc 文档
+- ✨ 改进的错误处理和日志输出
+- 🔧 优化项目结构
+- 🐛 修复多个已知问题
 
-    ```xml
-    <group id="test1" getVisible="myRibbon.nothing"></group>
-    <group id="test1" getVisible="a.b.c.nothing"></group>
-    <group id="test1" getVisible="new nothing"></group>
-    ```
+### v1.0.x
 
-    所以……如果你需要将 XML 中的诸如以上的回调函数转换为 JS 函数，也许你得自己写一些代码了。
+- 初始版本
+- 基本的 XML 转换和检查功能

package/index.js

@@ -1,39 +1,17 @@
 #!/usr/bin/env node
-const Command = require('commander').Command;
-const program = new Command();
-const pkg = require('./package.json')
 
+/**
+ * CUXML - WPS Office RibbonUI XML 处理工具
+ * 
+ * 主入口文件，根据调用方式决定是作为 CLI 还是库使用
+ */
 
-program
-    .name('cxml')
-    .description(pkg.description)
-    .version(pkg.version);
-program.command('check')
-    .description('检查 XML 文件是否符合规范（CustomUI for MS Office 2006/2007……）仅输出有问题的 Element。')
-    .argument('<xmlFile>', '要检查的 XML 文件')
-    .argument('[outFile]', '输出检查结果到文件 [outFile]')
-    .option('-w, --watch', '监视 <xmlFile> 文件')
-    .action((xmlFile, outFile, options) => {
-        console.log(JSON.stringify([options, xmlFile, outFile]));
-        require('./cxml_w.js')(xmlFile, outFile, options)
-    });
-program.command('callback')
-    .description('生成 XML 中 CustomUI 元素设置的回调属性为 JavaScript Function 并写入 <jsFile>')
-    .argument('<xmlFile>', 'customUI XML 文件')
-    .argument('<jsFile>', '要写入的 JavaScript 文件')
-    .option('-w, --write', '写入方式: 覆盖 JS 文件 <jsFile>')
-    .option('-a, --append', '写入方式: 追加到 <jsFile> 文件末尾')
-    .option('-watch, --watch', '监视 <xmlFile> 文件, 当文件发生变化时自动更新 <jsFile>,写入模式为覆盖')
-    .action((xmlFile, jsFile, options) => {
-        //console.log(JSON.stringify([options, xmlFile, jsFile]));
-        if(options.watch){
-            let w = require('chokidar').watch(xmlFile);
-            w.on('change', (p,s) => {
-                let xmlFile = p;
-                require('./xml2cbFn.js')(xmlFile, jsFile, {write: true});
-            })
-        }else{
-            require('./xml2cbFn.js')(xmlFile, jsFile, options);
-        }
-    });
-program.parse();
+const CUXMLAPI = require('./src/api');
+
+// 导出 API 供其他模块使用
+module.exports = CUXMLAPI;
+
+// 如果直接执行此文件，启动 CLI
+if (require.main === module) {
+    require('./src/cli');
+}

package/{cbfTypes.json → lib/cbfTypes.json}

@@ -1,7 +1,7 @@
 [
     {
         "n": "getVisible",
-        "t": "boolean"
+        "t": "string"
     },
     {
         "n": "getDescription",
@@ -9,7 +9,7 @@
     },
     {
         "n": "getEnabled",
-        "t": "boolean"
+        "t": "string"
     },
     {
         "n": "getImage",
@@ -29,15 +29,15 @@
     },
     {
         "n": "getShowImage",
-        "t": "boolean"
+        "t": "string"
     },
     {
         "n": "getShowLabel",
-        "t": "boolean"
+        "t": "string"
     },
     {
         "n": "getSize",
-        "t": "number"
+        "t": "string"
     },
     {
         "n": "getSupertip",
@@ -45,15 +45,15 @@
     },
     {
         "n": "onAction",
-        "t": "void"
+        "t": "string"
     },
     {
         "n": "getPressed",
-        "t": "boolean"
+        "t": "string"
     },
     {
         "n": "getItemCount",
-        "t": "number"
+        "t": "string"
     },
     {
         "n": "getItemID",
@@ -81,7 +81,7 @@
     },
     {
         "n": "onChange",
-        "t": "void"
+        "t": "string"
     },
     {
         "n": "loadImage",
@@ -89,7 +89,7 @@
     },
     {
         "n": "onLoad",
-        "t": "void"
+        "t": "string"
     },
     {
         "n": "getSelectedItemID",
@@ -97,7 +97,7 @@
     },
     {
         "n": "getSelectedItemIndex",
-        "t": "number"
+        "t": "string"
     },
     {
         "n": "getContent",
@@ -105,11 +105,11 @@
     },
     {
         "n": "getItemHeight",
-        "t": "number"
+        "t": "string"
     },
     {
         "n": "getItemWidth",
-        "t": "number"
+        "t": "string"
     },
     {
         "n": "getTitle",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cuxml",
-  "version": "1.0.6",
+  "version": "2.1.0",
   "description": "A tool to help use ribbon UI for your WPS Office Client JS add-in project.",
   "keywords": [
     "wps office",
@@ -17,7 +17,7 @@
   },
   "author": "",
   "license": "ISC",
-  "homepage": "https://github.com/YYago/cuxml",
+  "homepage": "https://github.com/YYago/cuxml/README.md",
   "bugs": {
     "url": "https://github.com/YYago/cuxml/issues"
   },