npm - crabatool - Versions diffs - 1.0.842 → 1.0.844 - Mend

crabatool 1.0.842 → 1.0.844

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/index.js CHANGED Viewed

@@ -1,4 +1,4 @@
-var config = require('./lib/config.js');
+var config = require('./lib/config.js');
 var start = require('./tool/start.js');
 var autoUpdate = require('./tool/autoUpdate.js');
 var processManager = require('./tool/processManager.js');
@@ -18,6 +18,13 @@ exports.DbHelper = require('./lib/db/dbHelper.js');
 exports.StringBuilder = require('./lib/stringBuilder.js');
 exports.hashUtils = require('./tool/hash.js');
+// 先检查版本参数，避免被initArgs处理
+if (process.argv.includes('-v')) {
+  var packageJson = require('./package.json');
+  console.log('crabatool version: ' + packageJson.version);
+  process.exit(0);
+}
 start.initArgs();
 exports.run = async function(options) {
@@ -174,7 +181,7 @@ async function checkFast(args) {
     upgrade.updateCraba();
     return false;
   }
-    // crabatool -install -webPath 项目路径 -version可选参数
+  // crabatool -install -webPath 项目路径 -version可选参数
   if (args.includes('-install')) {
     start.bindAndCheckConfig('-webPath');
     start.checkWebPath();
@@ -200,7 +207,7 @@ async function checkFast(args) {
     return false;
   }
-  if (args.includes('-v')) {
+  if (args.includes('-crabaVersion')) {
     var data = upgrade.getNewVersion();
     console.log(data);
     return false;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "crabatool",
-  "version": "1.0.842",
+  "version": "1.0.844",
   "description": "crabatool",
   "main": "index.js",
   "bin": {

package/readme.md CHANGED Viewed

@@ -1,60 +1,1125 @@
-# 使用方法
-1. 打开命令行终端，安装crabatool 输入：npm install crabatool -g 或从本地仓库安装（更快） npm install crabatool -g --registry http://172.17.0.236:4873/
+# crabatool
-2. 快捷使用crabatool进行代码检测 比如，检查某个路径下面的所有js，可直接在命令行终端输入命令：crabatool -checkjs -webPath F:\Beefun\srcs\Beefun -modName Beefun
+crabatool 是一个基于 Node.js 的前端工程化脚手架工具，主要服务于 Craba/NGP 前端项目体系。支持命令行（CLI）和 JS 配置文件两种使用方式，兼容 Windows、macOS、Linux，可集成 Jenkins 实现自动化构建。
-3. 快捷使用crabatool启动nodejs服务 crabatool -run -webPath F:\shell_master\web\src\main\resources\static\shell
+当前版本：`1.0.844`
-4. 快捷使用crabatool更新指定项目的平台 crabatool -update -webPath F:\shell_master\web\src\main\resources\static\shell
+---
-5. 跳过系统信息上报：crabatool --skip-report -checkjs -webPath 项目路径
+## 目录
--checkjs表示使用代码检查功能； -webPath表示要检查哪个站点的路径； -modName表示项目名称
+- [环境要求](#环境要求)
+- [安装](#安装)
+- [快速上手](#快速上手)
+- [命令行参数总览](#命令行参数总览)
+- [常用功能](#常用功能)
+  - [1. 安装平台资源 (-install)](#1-安装平台资源--install)
+  - [2. 启动本地服务 (-run)](#2-启动本地服务--run)
+  - [3. 更新平台资源 (-update)](#3-更新平台资源--update)
+  - [4. JS 语法检测 (-checkjs)](#4-js-语法检测--checkjs)
+  - [5. 安装/更新 IDEA 环境 (-idea)](#5-安装更新-idea-环境--idea)
+  - [6. 安装/更新 VSCode 环境 (-vscode)](#6-安装更新-vscode-环境--vscode)
+  - [7. 合并压缩 JS 文件 (-mergejs)](#7-合并压缩-js-文件--mergejs)
+  - [8. 合并压缩 CSS 文件 (-mergecss)](#8-合并压缩-css-文件--mergecss)
+  - [9. 打包资源文件为 JSON (-mergeFiles)](#9-打包资源文件为-json--mergefiles)
+  - [10. 查询craba框架的最新版本 (-crabaVersion)](#10-查询craba框架的最新版本--crabaversion)
+  - [11. 查看crabatool工具版本 (-v)](#11-查看crabatool工具版本--v)
+- [其他功能](#其他功能)
+  - [1. 打包 init.js 和 biz.js (-mergeinitjs)](#1-打包-initjs-和-bizjs--mergeinitjs)
+  - [2. 图标字体检测 (-checkiconfont)](#2-图标字体检测--checkiconfont)
+  - [3. 检测平台更新标记 (-checkUpdate)](#3-检测平台更新标记--checkupdate)
+  - [4. 生成文件哈希清单 (-makeHash)](#4-生成文件哈希清单--makehash)
+  - [5. 计算页面路径哈希 (-pageHash)](#5-计算页面路径哈希--pagehash)
+  - [6. 自动添加版本号 (-addVersion)](#6-自动添加版本号--addversion)
+  - [7. 导出 gspx 页面标题清单 (-exportgspx)](#7-导出-gspx-页面标题清单--exportgspx)
+  - [8. 自动生成节点 ID (-autoId)](#8-自动生成节点-id--autoid)
+  - [9. 更新 crabaTool 自身 (-updateTool)](#9-更新-crabatool-自身--updatetool)
+  - [10. 上传平台资源 (-upload)](#10-上传平台资源--upload)
+  - [11. 上传/更新 NGP 皮肤图标 (-uploadSkin / -updateSkin)](#11-上传更新-ngp-皮肤图标--uploadskin---updateskin)
+  - [12. 字体库解压部署 (-iconfont)](#12-字体库解压部署--iconfont)
+  - [13. 转换 Javadoc 文档 (-convertJavadoc)](#13-转换-javadoc-文档--convertjavadoc)
+- [配置参数完整列表](#配置参数完整列表)
+- [通过 JS 配置文件使用](#通过-js-配置文件使用)
+- [交互式菜单模式](#交互式菜单模式)
+- [文件监听与热刷新](#文件监听与热刷新)
+- [代理转发配置](#代理转发配置)
+- [Jenkins 集成](#jenkins-集成)
+- [导出的模块 API](#导出的模块-api)
+- [常见问题](#常见问题)
-## 命令行参数说明
+---
+## 环境要求
+- **Node.js**：需要先安装 [Node.js](https://nodejs.cn/download/)
+- 支持平台：Windows、macOS、Linux
+---
+## 安装
+全局安装（推荐）：
+```bash
+npm install crabatool -g
+```
+从内网仓库安装（更快）：
+```bash
+npm install crabatool -g --registry http://172.17.0.236:4873/
+```
+> 全局安装一次后，在任意路径下都可以直接使用 `crabatool` 命令。后续更新执行 `npm install crabatool -g` 或 `npm update crabatool -g` 即可。
+---
+## 快速上手
+```bash
+# 显示帮助信息（进入交互式菜单，这个命令没有带任何参数不适合Agent和大模型）
+crabatool
+# 安装项目平台资源
+crabatool -install -webPath F:\myproject\www
+# 更新项目平台资源
+crabatool -update -webPath F:\myproject\www
+# 检测项目 JS 语法
+crabatool -checkjs -webPath F:\myproject\www -modName mymod
+# 启动本地开发服务器
+crabatool -run -webPath F:\myproject\www -port 9090
+# 查看craba框架的最新版本号
+crabatool -crabaVersion
+# 查看crabatool工具的版本号
+crabatool -v
+# 查看crabatool工具的版本号（另一种方式）
+crabatool -version
+```
+---
+## 命令行参数总览
 ### 通用参数
-- `--skip-report`: 跳过系统信息上报，提高启动速度，保护隐私
-- `--help` 或 `-h`: 显示帮助信息
-- `-v`: 显示版本信息
-### 功能参数
-- `-checkjs`: 检查JavaScript代码
-- `-checkiconfont`: 检查图标字体
-- `-run`: 启动本地服务器
-- `-update`: 更新指定项目
-- `-updateTool`: 更新crabaTool工具本身
-- `-upload`: 上传项目
-- `-mergejs`: 合并JavaScript文件
-- `-mergecss`: 合并CSS文件
-- `-makeHash`: 生成文件哈希值
-### 使用示例
-```bash
-# 显示帮助信息
-crabatool --help
-# 跳过系统信息上报并检查JS代码
-crabatool --skip-report -checkjs -webPath 项目路径
-# 跳过上报并启动服务器
-crabatool --skip-report -run -webPath 项目路径
-# 正常启动（包含系统信息上报）
-crabatool -run -webPath 项目路径
+| 参数 | 说明 |
+|------|------|
+| `--skip-report` | 跳过系统信息上报，提高启动速度，保护隐私 |
+| `-crabaVersion` | 查看craba框架的最新版本号 |
+| `-v` | 查看crabatool工具的版本号 |
+| `-version` | 查看crabatool工具的版本号 |
+### 功能命令
+| 命令 | 说明 |
+|------|------|
+| `-install` | 安装项目的 Craba 平台资源 |
+| `-update` | 更新项目的 Craba 平台资源 |
+| `-checkjs` | 检查项目 JS 语法兼容性 |
+| `-idea` | 安装/更新 IDEA 开发环境配置 |
+| `-vscode` | 安装/更新 VSCode 开发环境配置 |
+| `-mergejs` | 合并压缩指定 JS 文件 |
+| `-mergecss` | 合并压缩指定 CSS 文件 |
+| `-mergeFiles` | 将多种资源文件打包为 JSON 资源包 |
+| `-run` | 启动本地前端服务器 |
+| `-mergeinitjs` | 打包合并 init.js 和 biz.js |
+| `-checkiconfont` | 检测项目图标字体使用情况 |
+| `-checkUpdate` | 检测服务端是否标记了平台更新 |
+| `-updateTool` | 更新 crabaTool 工具自身 |
+| `-makeHash` | 生成文件的 SRI 哈希清单 |
+| `-pageHash` | 计算 gspx 页面路径的哈希值 |
+| `-addVersion` | 自动给文件添加版本号（时间戳） |
+| `-exportgspx` | 导出目录下所有 gspx 文件的标题清单 |
+| `-autoId` | 自动为 gspx 页面节点生成 ID |
+| `-upload` | 打包并上传平台资源到服务端 |
+| `-uploadSkin` | 上传 NGP 皮肤和图标库 |
+| `-updateSkin` | 更新 NGP 皮肤和图标库 |
+| `-iconfont` | 解压并部署字体库文件 |
+| `-convertJavadoc` | 转换 Javadoc HTML 文档为 JSON/MD |
+---
+## 常用功能
+### 1. 安装平台资源 (-install)
+首次安装 Craba 平台资源到指定项目路径。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目根路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-version` | 指定分支版本号，默认为 `master` |
+**使用示例：**
+```bash
+# 安装主分支平台
+crabatool -install -webPath F:\myproject\www
+# 安装指定分支
+crabatool -install -webPath F:\myproject\www -version ngp5.3
+```
+---
+### 2. 启动本地服务 (-run)
+启动基于 Express 的本地前端静态资源服务器，支持自动打开浏览器、文件热刷新、代理转发、gzip 压缩等。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 网站根路径（login.html 或 index.html 所在目录），支持绝对路径和相对路径 |
+| `-port` | 前端服务端口号 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-modName` | NGP 项目的模块名称（NGP 项目必填） |
+| `-refresh true` | 开启文件变动自动刷新浏览器（监听 js/css/gspx/html 文件变动） |
+| `-proxy` | 配置 API 代理转发规则（JSON 格式字符串） |
+| `-proxySrc` | 从 JSON 文件读取代理配置 |
+| `-noOpen true` | 启动后不自动打开浏览器 |
+| `-localLogin true` | 使用本地 login.html 而非重写的登录页 |
+| `-defaultPage` | 自定义首页文件名（默认 NGP 为 login.html，其他为 index.html） |
+| `-virtualName` | 虚拟路径名 |
+| `-childModList` | 子模块列表，逗号分隔（配置后自动打包 init.js 和 biz.js） |
+| `-ignoreCompress true` | 不压缩打包后的 init.js 和 biz.js |
+**使用示例：**
+```bash
+# 基本启动
+crabatool -run -webPath F:\myproject\www -port 9090
+# NGP 项目启动
+crabatool -run -webPath F:\shell\web\src\main\resources\static\shell -port 9090 -modName shell
+# 启动并开启热刷新
+crabatool -run -webPath F:\myproject\www -port 9090 -refresh true
+# 启动并配置代理转发
+crabatool -run -webPath F:\myproject\www -port 9090 -proxy "{'/apis/':{'target':'http://127.0.0.1:8082','changeOrigin':true}}"
+```
+**热刷新说明：**
+- 开启 `-refresh true` 后，crabatool 会通过 WebSocket 监听 js、gspx、css、html 文件的变动。
+- 文件变动时浏览器会收到刷新消息，但会等待浏览器被激活（focus）时才真正刷新，避免高频刷新影响性能。
+- WebSocket 端口默认为 `port + 6000`（如超出端口范围会自动调整）。
+**文件监听功能：**
+- 启动服务时默认开启文件监听功能（`enableFileWatcher`），监听 `.js` 文件的变动并自动执行 ESLint 语法检查、编码检查、文件大小检查、ES6+ 兼容性检查。
+- 通过配置 `enableFileWatcher: false` 可以关闭。
+---
+### 4. 更新平台资源 (-update)
+从内网服务器拉取最新的 Craba 平台资源，覆盖到指定项目路径下。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-version` | 指定分支版本号，如 `ngp4.7`、`ngp5.1`、`ngp5.3`，默认为 `master` |
+| `-progress 0` | 不显示进度条 |
+**使用示例：**
+```bash
+# 更新主分支平台
+crabatool -update -webPath F:\myproject\www
+# 更新指定分支
+crabatool -update -webPath ../web/src/main/resources/static/shell -version ngp4.7
+```
+---
+### 5. JS 语法检测 (-checkjs)
+对项目下所有 JS 文件进行语法兼容性检测，包括 ESLint 规则检查、编码检测、文件大小检测、ES6+ 语法检测（let/const/箭头函数/async/await/then/debugger 等），同时检查 gspx 文件中的标签使用规范。检测结果可推送到钉钉群机器人。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-modName` | 项目（模块）名称 |
+| `-ignoreCheck` | 忽略检测的目录或文件，逗号分隔，相对 webPath 的路径 |
+| `-globals` | 全局变量名列表，逗号分隔，检测时会忽略这些变量（`$` 字符在 shell 中需转义为 `\$`） |
+| `-webhooks` | 检测报告推送地址（如钉钉群机器人 Webhook URL） |
+| `-progress 0` | 不显示进度条（适用于 Jenkins 等 CI 环境） |
+| `-checkgspx false` | 不检查 gspx 文件 |
+| `-checkutf8 true` | 检查 UTF-8 编码 |
+| `-checkCustomControl false` | 不检查自定义控件 |
+| `-ignoreFiles` | 忽略的文件列表，逗号分隔 |
+| `-cssFiles` | 额外需要检测的 CSS 文件列表 |
+| `-Debug true` | 开启调试模式 |
+| `-notCheckCraba true` | 跳过 craba.min.js 存在性检查 |
+**使用示例：**
+```bash
+# 基本检测
+crabatool -checkjs -webPath F:\myproject\www -modName mymod
+# 忽略特定目录和文件
+crabatool -checkjs -webPath F:\myproject\www -modName mymod -ignoreCheck ueditor,iconfont,js/math.min.js
+# 配置全局变量和钉钉推送
+crabatool -checkjs -webPath F:\myproject\www -modName mymod -globals \$doc,CrabaMarkdown -webhooks https://oapi.dingtalk.com/robot/send?access_token=xxx
+# 跳过上报且不显示进度条（CI 环境）
+crabatool --skip-report -checkjs -webPath F:\myproject\www -progress 0
+```
+**检测报告推送格式：**
+推送到 Webhook 的数据格式为：
+```json
+{
+  "msgtype": "markdown",
+  "markdown": {
+    "title": "代码检测报告",
+    "text": "检测结果（markdown 格式）"
+  }
+}
+```
+---
+### 6. 安装/更新 IDEA 环境 (-idea)
+自动安装或更新 IntelliJ IDEA 的 Craba 开发环境，包括：
+- gspx 智能语法提示（XSD）
+- 新建页面模板（Craba.gspx / CrabaJs.js）
+- gspx 文件语法高亮（关联为 XML 类型）
+```bash
+crabatool -idea
+```
+---
+### 7. 安装/更新 VSCode 环境 (-vscode)
+自动安装或更新 VSCode 的 Craba 开发环境，包括：
+- gspx 智能语法提示（XSD + RedHat XML 插件）
+- 新建页面模板
+- 快捷键配置（ctrl+alt+n、alt+j 等）
+```bash
+crabatool -vscode
+```
+---
+### 8. 合并压缩 JS 文件 (-mergejs)
+将指定的多个 JS 文件合并为一个文件，支持压缩和变量替换。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-inNames` | 输入文件名列表，逗号分隔 |
+| `-outName` | 输出文件的完整路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-targetPath` | 输入文件的根目录（与 inNames 组合为完整路径）；不填则 inNames 需为完整路径 |
+| `-ignorecompress true` | 不压缩 JS（默认会压缩） |
+| `-hidejspath true` | 合并后的文件中不显示原始文件路径注释 |
+| `-exp` | 变量替换表达式，格式为 `${变量名}=替换值` |
+**使用示例：**
+```bash
+# 合并同目录下多个 JS（压缩）
+crabatool -mergejs -targetPath F:\project\js -inNames a.js,b.js -outName F:\output\merged.js
+# 合并不同路径的 JS（不压缩）
+crabatool -mergejs -inNames F:\js\a.js,D:\js\b.js -outName E:\output.js -ignorecompress true
+# 压缩单个文件
+crabatool -mergejs -targetPath F:\project\js -inNames app.js -outName F:\output\app.min.js
+# 压缩并替换变量
+crabatool -mergejs -targetPath F:\project\js -inNames app.js -outName F:\output\app.min.js -exp ${plugHost}=http://192.168.1.100:8082/
 ```
-[详细使用文档](http://crabadoc.ca.com/#~/Pages/Guide.gspx?id=1655080677276)
+---
+### 9. 合并压缩 CSS 文件 (-mergecss)
+将指定的多个 CSS 文件合并为一个文件。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-inNames` | 输入文件名列表，逗号分隔 |
+| `-outName` | 输出文件的完整路径 |
-# 功能介绍
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-targetPath` | 输入文件的根目录 |
+| `-ignoreCompress` | 不压缩 CSS |
+**使用示例：**
+```bash
+crabatool -mergecss -targetPath F:\project\skins -inNames iconfont.css,craba.min.css -outName D:\output\craba.min.css
+# 不压缩
+crabatool -mergecss -targetPath F:\project\skins -inNames a.css,b.css -outName D:\output\merged.css -ignoreCompress
+```
+---
+### 10. 打包资源文件为 JSON (-mergeFiles)
+将多种类型的资源文件（JS/CSS/gspx）压缩后以路径为 key 合并到一个 JSON 资源包中，减少 HTTP 请求。可以追加到 init.js 中或生成独立资源文件。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-inNames` | 输入文件名列表，逗号分隔（支持 .js/.css/.gspx） |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-outName` | 输出文件路径（独立资源包方式） |
+| `-initJs` | 追加到指定 init.js 文件中（追加方式） |
+| `-targetPath` | 输入文件的根目录 |
+| `-modName` | 模块名称（作为资源路径前缀） |
+| `-webPath` | 项目路径 |
+| `-clearCache true` | 清除缓存 |
+**使用示例：**
+```bash
+crabatool -mergeFiles -modName shell -webPath F:\project\shell -targetPath F:\project\shell -inNames skins/craba.min.css,Main.gspx,Main.js,js/init.js -outName F:\project\shell\shell.res.js
+# 追加到 init.js
+crabatool -mergeFiles -modName jxc -webPath F:\project\jxc -targetPath F:\project\jxc -inNames skins/skin.css,js/wpsSettings.js -initJs F:\project\jxc\js\init.js
+```
+---
+### 11. 查询craba框架的最新版本 (-crabaVersion)
+查询服务端 Craba 框架的最新版本号和更新时间。
+```bash
+crabatool -crabaVersion
+```
+---
+### 12. 查看crabatool工具版本 (-v)
+查看当前 crabatool 工具的版本号。
+**使用示例：**
+```bash
+# 查看crabatool工具的版本号
+crabatool -v
+```
+---
+## 其他功能
+### 1. 打包 init.js 和 biz.js (-mergeinitjs)
+将 NGP 项目模块及其子模块下的 JS 业务文件合并打包为 `init.js` 和 `biz.js`，减少 HTTP 请求。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目路径 |
+| `-port` | 端口号 |
+| `-modName` | 模块名称 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-childModList` | 子模块列表，逗号分隔（如 `baseinfo,recordsheet,accounting`） |
+| `-ignoreCompress` | 是否跳过压缩（`true` 不压缩，`false` 压缩） |
+| `-mergeInitAndBiz true` | 将最终的 init.js 和 biz.js 合并为一个文件 |
+| `-progress 0` | 不显示进度条 |
+**使用示例：**
+```bash
+crabatool -mergeinitjs -webPath F:\myproject\www -port 9090 -modName jxc -childModList baseinfo,recordsheet,accounting -ignoreCompress false
+# Jenkins 环境
+crabatool -mergeinitjs -webPath /opt/project/www -port 9090 -modName shell -childModList baseinfo,recordsheet -ignoreCompress false -progress 0
+```
-1. 提供前端本地服务功能；【实现】
-2. 自动刷新浏览器，监听到 css、js、gspx 文件有变动，会自动刷新网页，提高开发效率。配置项：config.refresh = true;【实现】
-3. 根据配置自动打包 biz.js 和 init.js，针对 ngp 的功能，减少 http 请求；【实现】
-4. 本地服务启动后自动打开浏览器预览页面；【实现】
+> **工作原理：** 工具会先打包当前模块 `模块名/js/init.js` 和 `模块名/js/biz/xxx => 模块名/js/biz.js`，然后打包各子模块的对应文件。如果不包含子模块，`-childModList` 填 `null` 即可。
-5. 更新或安装本地 IDEA\VsCode 的智能语法提示；【未实现】
-6. 更新或安装本地 IDEA\VSCode 的新建页面模板；【未实现】
-7. 新建空白项目和 ngp 项目；【未实现】
-8. 根据配置将当前项目所有业务 js 文件统一打包、es6 语法转换、文件合并；【未实现】
+---
+### 2. 图标字体检测 (-checkiconfont)
+扫描项目中 JS 和 gspx 文件内所有 `aicon-*`、`bicon-*` 图标的使用情况，并上报到文档服务器。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-modName` | 模块名称 |
+| `-reportHost` | 报告接收服务地址 |
+| `-ignoreFiles` | 忽略的文件列表，逗号分隔 |
+| `-cssFiles` | 额外需要扫描的 CSS 文件列表，逗号分隔 |
+**使用示例：**
+```bash
+crabatool -checkiconfont -webPath F:\myproject\www -modName mymod -reportHost http://127.0.0.1:9998 -ignoreFiles biconfont/iconfont.js
+```
+---
+### 3. 检测平台更新标记 (-checkUpdate)
+检测服务端是否标记了平台需要更新。如果有更新标记且当前 Git 仓库有推送权限，将自动下载更新并推送 Git。主要用于 Jenkins 自动化流程。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-version` | 分支版本，默认为 `master` |
+**使用示例：**
+```bash
+crabatool -checkUpdate -version master -webPath F:\myproject\www
+```
+---
+### 4. 生成文件哈希清单 (-makeHash)
+计算指定文件的 SRI（Subresource Integrity）哈希值，生成 JSON 清单文件。支持本地文件、远程 URL 和目录扫描。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-outJson` | 输出 JSON 文件路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-files` | 文件路径列表，逗号分隔（支持本地路径、HTTP/HTTPS URL、目录路径） |
+| `-exts` | 文件扩展名过滤，逗号分隔，如 `.js`（配合目录扫描使用） |
+| `-webPath` | 项目路径（用于生成相对路径 key） |
+| `-modName` | 模块名称（作为路径前缀） |
+| `-hashName` | 哈希算法名称，默认 `sha384` |
+**使用示例：**
+```bash
+# 对指定文件列表生成哈希
+crabatool -makeHash -webPath F:\project\www -files F:\project\www\js\a.js,F:\project\www\js\b.js -outJson F:\project\www\js\hash.json
+# 对目录下所有 JS 文件生成哈希
+crabatool -makeHash -webPath F:\project\www -files F:\project\www\js\ -exts .js -outJson F:\output\hash.json -hashName sha384
+# 支持远程 URL
+crabatool -makeHash -webPath F:\project\www -files http://example.com/js/lib.js,F:\project\www\js\app.js -outJson F:\output\hash.json
+```
+**输出格式：**
+```json
+{
+  "模块名/js/a.js": "sha384-xxxxbase64xxxx",
+  "http://example.com/js/lib.js": "sha384-xxxxbase64xxxx"
+}
+```
+---
+### 5. 计算页面路径哈希 (-pageHash)
+计算 gspx 页面相对路径的哈希值，用于生成页面的配置 ID 前缀码。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-pageHash` | gspx 页面的相对路径（必须以 `.gspx` 结尾） |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-ngp true` | 使用 NGP 模式计算哈希（会去掉 jxc/sale 等模块前缀） |
+**使用示例：**
+```bash
+crabatool -pageHash /jxc/recordsheet/report.gspx
+# NGP 模式
+crabatool -pageHash /jxc/recordsheet/report.gspx -ngp true
+```
+---
+### 6. 自动添加版本号 (-addVersion)
+在指定文件中将占位符替换为当前时间戳，用于 Jenkins 自动构建时给产品添加版本号。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-file` | 目标文件路径 |
+| `-exp` | 替换表达式。直接文本替换（如 `AUTOVERSION`），或特殊值 `version`（替换 `version: 'xxx'` 格式）、`staticVersion`（替换 `staticVersion = 'xxx'` 格式） |
+**使用示例：**
+```bash
+# 替换文件中的 AUTOVERSION 文本为时间戳
+crabatool -addVersion -file F:\project\www\index.html -exp AUTOVERSION
+```
+**index.html 中的配合代码示例：**
+```js
+if (!$app.isLocal()) {
+    $craba.addVersion({ name: 'every', version: 'AUTOVERSION' });
+}
+```
+---
+### 7. 导出 gspx 页面标题清单 (-exportgspx)
+扫描指定目录下所有 gspx 文件，提取 `<Page>` 标签的 Title 属性，导出到桌面的 `exportgspx.txt` 文件。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 要扫描的目录路径 |
+**使用示例：**
+```bash
+crabatool -exportgspx -webPath F:\project\srcs
+```
+> 输出文件默认生成到桌面 `~/Desktop/exportgspx.txt`。
+---
+### 8. 自动生成节点 ID (-autoId)
+自动为 gspx 页面中的 UI 控件节点生成唯一 ID。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-webPath` | 项目路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-ignoreAutoId` | 忽略自动生成 ID 的标签列表，逗号分隔 |
+| `-ignoreFiles` | 忽略的文件列表，逗号分隔 |
+**使用示例：**
+```bash
+crabatool -autoId -webPath F:\project\www
+```
+> 也可以在配置文件中设置 `autoId: true`，启动时自动执行。
+---
+### 9. 更新 crabaTool 自身 (-updateTool)
+手动检查并更新 crabaTool 工具到最新版本。
+```bash
+crabatool -updateTool
+```
+> crabaTool 也支持启动时自动分离式更新检查（带命令行参数启动时触发），可通过配置 `enableDetachedUpdate: false` 关闭。
+---
+### 10. 上传平台资源 (-upload)
+对 Craba 平台源码进行打包压缩（JS/CSS），然后上传到服务端指定分支下。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-targetPath` | 平台源码根路径 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-version` | 目标分支版本 |
+| `-host` | 上传服务地址 |
+| `-hidejspath true` | 压缩后不保留原始文件路径注释 |
+| `-Debug true` | 调试模式 |
+**使用示例：**
+```bash
+crabatool -upload -version master -targetPath F:\CarpaNET_NEW -host http://127.0.0.1:9998 -hidejspath true
+```
+---
+### 11. 上传/更新 NGP 皮肤图标 (-uploadSkin / -updateSkin)
+管理 NGP 项目的皮肤和图标库资源。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-skinPath` | 皮肤资源目录路径 |
+| `-version` | 分支版本 |
+**使用示例：**
+```bash
+# 上传皮肤
+crabatool -uploadSkin -skinPath F:\project\skins -version master
+# 更新皮肤
+crabatool -updateSkin -skinPath F:\project\skins -version master
+```
+---
+### 12. 字体库解压部署 (-iconfont)
+从指定目录中找到字体库 ZIP 文件，解压并部署到目标目录，同时生成标准化的 iconfont.css。
+**必填参数：**
+| 参数 | 说明 |
+|------|------|
+| `-zipPath` | 字体库 ZIP 文件所在目录 |
+| `-fontPath` | 字体文件部署目标目录 |
+**可选参数：**
+| 参数 | 说明 |
+|------|------|
+| `-prefix` | CSS 类名前缀，默认 `.bicon-` |
+| `-fontName` | 字体名称，默认 `biconfont` |
+**使用示例：**
+```bash
+crabatool -iconfont -zipPath F:\project\biconfont -fontPath F:\project\skins\bicon -prefix .bicon- -fontName biconfont
+```
+---
+### 13. 转换 Javadoc 文档 (-convertJavadoc)
+将 Javadoc 生成的 HTML 文档转换为 JSON 格式。
+**参数：**
+| 参数 | 说明 |
+|------|------|
+| `-targetPath` | 包含 HTML 文件的目录（批量转换） |
+| `-filePath` | 单个 HTML 文件路径（单文件转换） |
+| `-outPath` | 输出路径（JSON 文件） |
+**使用示例：**
+```bash
+# 批量转换目录
+crabatool -convertJavadoc -targetPath F:\docs\shell -outPath F:\docs\shell.json
+# 转换单个文件
+crabatool -convertJavadoc -filePath F:\docs\shell\Entity.html -outPath F:\docs\md
+```
+---
+## 配置参数完整列表
+以下参数既可以在配置文件（craba.js）中设置，也可以通过命令行传入。**命令行参数优先级高于配置文件**。
+| 配置文件参数名 | 命令行参数名 | 类型 | 说明 |
+|----------------|--------------|------|------|
+| `webPath` | `-webPath` | string | **必填**。网站根路径，支持相对路径和绝对路径，路径中用 `\\` 或 `/` |
+| `port` | `-port` | number | **必填（-run 时）**。前端服务端口号 |
+| `modName` | `-modName` | string | NGP 项目必填。模块名称 |
+| `childModList` | `-childModList` | array / 逗号分隔字符串 | 子模块列表，用于 init.js 和 biz.js 打包 |
+| `refresh` | `-refresh` | boolean | 是否开启文件变动自动刷新浏览器 |
+| `ignoreCompress` | `-ignoreCompress` | boolean | 是否跳过 JS/CSS 压缩 |
+| `webhooks` | `-webhooks` | string | 钉钉群机器人 Webhook 地址（用于推送检测报告） |
+| `progress` | `-progress` | number | 是否显示进度条（`0` 为不显示） |
+| `globals` | `-globals` | array / 逗号分隔字符串 | checkjs 功能的全局变量白名单 |
+| `ignoreCheck` | `-ignoreCheck` | array / 逗号分隔字符串 | checkjs 功能需忽略的文件/目录（相对 webPath） |
+| `ignoreFiles` | `-ignoreFiles` | array / 逗号分隔字符串 | 忽略的文件列表 |
+| `ignoreAutoId` | `-ignoreAutoId` | array / 逗号分隔字符串 | autoId 功能忽略的标签 |
+| `autoId` | `-autoId` | boolean | 是否自动生成节点 ID |
+| `version` | `-version` | string | 平台分支版本，默认 `master` |
+| `branchName` | `-branchName` | string | Git 分支名称 |
+| `host` | `-host` | string | 自定义服务地址 |
+| `reportHost` | `-reportHost` | string | 检测报告接收服务地址 |
+| `aiHost` | `-aiHost` | string | AI 服务地址 |
+| `proxy` | `-proxy` | JSON | 代理转发规则 |
+| `proxySrc` | `-proxySrc` | string | 代理配置文件路径（JSON 文件） |
+| `hidejspath` | `-hidejspath` | boolean | 合并文件时不显示原始文件路径 |
+| `Debug` | `-Debug` | boolean | 开启调试模式 |
+| `checkgspx` | `-checkgspx` | boolean | 是否检查 gspx 文件，默认 `true` |
+| `checkutf8` | `-checkutf8` | boolean | 是否检查 UTF-8 编码 |
+| `clearCache` | `-clearCache` | boolean | 清除缓存 |
+| `noOpen` | `-noOpen` | boolean | 启动服务后不自动打开浏览器 |
+| `notCheckCraba` | `-notCheckCraba` | boolean | 跳过 craba.min.js 存在性检查 |
+| `localLogin` | `-localLogin` | boolean | 使用本地 login.html |
+| `defaultPage` | `-defaultPage` | string | 自定义首页 |
+| `virtualName` | `-virtualName` | string | 虚拟路径名 |
+| `mergeInitAndBiz` | `-mergeInitAndBiz` | boolean | 合并 init.js 和 biz.js |
+| `checkCustomControl` | `-checkCustomControl` | boolean | 检查自定义控件，默认 `true` |
+| `enableFileWatcher` | - | boolean | 是否启用文件监听功能，默认 `true` |
+| `enableDetachedUpdate` | - | boolean | 是否启用分离式自动更新，默认 `true` |
+---
+## 通过 JS 配置文件使用
+除了纯命令行方式，crabatool 还支持通过创建一个 JS 配置文件来管理参数，避免每次在命令行中输入大量参数。这种方式不适合Agent和大模型。
+### 使用步骤
+**第一步：** 在项目中创建一个 `craba.js` 配置文件，将常用参数写在里面：
+```js
+var crabaTool = require('crabatool');
+var config = {
+  // 【必填】网站路径
+  webPath: "F:/myproject/web/src/main/resources/static/shell",
+  // 【必填】前端服务端口
+  port: 3001,
+  // 【NGP 必填】模块名称
+  modName: "shell",
+  // 【可选】开启文件变动自动刷新
+  refresh: true,
+  // 【可选】子模块列表（用于 init.js 和 biz.js 自动打包）
+  childModList: ['recordsheet', 'baseinfo', 'accounting'],
+  // 【可选】打包后是否跳过压缩（true 不压缩，false 压缩）
+  ignoreCompress: true,
+  // 【可选】代理转发规则
+  proxy: {
+    '/apis/': {
+      target: 'http://127.0.0.1:8082',
+      changeOrigin: true
+    }
+  }
+};
+crabaTool.run(config);
+```
+**第二步：** 通过 `node craba.js` 加上功能命令来执行：
+```bash
+# 启动本地服务（使用配置文件中的 webPath、port 等参数）
+node craba.js -run
+# 检测 JS 语法
+node craba.js -checkjs
+# 打包 init.js 和 biz.js
+node craba.js -mergeinitjs
+```
+### 命令行参数覆盖配置文件
+命令行传入的参数会**覆盖**配置文件中的同名参数。例如：
+```bash
+# 虽然配置文件中 webPath 指向 shell 目录，但这里会使用命令行传入的路径
+node craba.js -run -webPath E:/other/path
+# 覆盖端口号
+node craba.js -run -port 8080
+```
+### 适用场景
+- **本地开发**：把 `webPath`、`port`、`modName`、`proxy` 等固定参数写到 `craba.js` 中，每次只需 `node craba.js -run` 即可启动
+- **多人协作**：将 `craba.js` 提交到 Git 仓库，团队成员 clone 后直接使用，无需记忆大量参数
+- **Jenkins/CI**：配置文件设置基础参数，Jenkins 脚本中通过命令行参数动态覆盖特定值
+---
+## 交互式菜单模式
+不带任何参数运行 `crabatool`（或 `node craba.js`）时，将进入交互式菜单模式：
+```
+---------------------------------------------------------------------------------------------------------
+1 启动服务。                         主要包含：自动合并打包init.js和biz.js，查看本地平台的版本
+2.1 更新当前项目的craba平台(主分支)，然后启动服务。
+2.2 更新当前项目的craba平台(其他分支)，然后启动服务。
+3 查询最新平台版本和日期。
+4 校验当前项目js和gspx语法。
+5 打包当前项目前端所有js。
+6 安装或更新IDEA环境。
+7 安装或更新vscode环境。
+8 新建Craba项目。
+9 更新 crabaTool 工具。
+0 结束
+---------------------------------------------------------------------------------------------------------
+请输入对应功能的编号（数字）：
+```
+通过输入编号选择功能。其中编号 8 支持创建两种类型的项目：
+- **普通 Craba 纯前端项目**
+- **NGP 微前端项目**
+---
+## 文件监听与热刷新
+### 启动时热刷新
+启动服务时通过 `-refresh true` 参数开启：
+```bash
+crabatool -run -webPath F:\project\www -port 9090 -refresh true
+```
+- 监听文件类型：`.js`、`.css`、`.gspx`、`.html`
+- 工作原理：通过 WebSocket 通知浏览器，浏览器在被激活（focus）时才执行刷新
+- WebSocket 端口：自动分配为 `port + 6000`
+### 文件监听代码检测
+启动服务时默认开启文件监听器（OpenFileWatcher），当 `.js` 文件发生变动时自动执行：
+- ESLint 语法检查
+- 文件编码检查
+- 文件大小检查
+- ES6+ 兼容性检查
+### 独立文件监听器
+crabatool 也导出了独立的文件监听 API，可在自定义项目中使用：
+```js
+var openFileWatcher = require('crabatool/tool/openFileWatcher.js');
+const watcher = openFileWatcher.createWatcher({
+  watchExtensions: ['.js'],
+  debounceDelay: 300,
+  verbose: false
+});
+watcher.start('./src');
+```
+---
+## 代理转发配置
+启动本地服务时可配置 API 代理转发，基于 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
+### 命令行方式
+```bash
+crabatool -run -webPath F:\project\www -port 9090 -proxy "{'/apis/':{'target':'http://127.0.0.1:8082','changeOrigin':true}}"
+```
+> 注意：命令行中 JSON 使用单引号包裹 key 和 value，工具会自动转换为双引号解析。
+### 配置文件方式
+在 `craba.js` 配置文件中直接写 JS 对象，更直观：
+```js
+var config = {
+  webPath: "F:/project/www",
+  port: 9090,
+  proxy: {
+    '/apis/': {
+      target: 'http://127.0.0.1:8082',
+      changeOrigin: true
+    },
+    '/shell/framework/': {
+      target: 'http://127.0.0.1:8339',
+      changeOrigin: true,
+      logLevel: 'debug'
+    }
+  }
+};
+```
+也支持数组格式：
+```js
+proxy: [
+  { context: '/apis/', target: 'http://127.0.0.1:8082', changeOrigin: true }
+]
+```
+### 从文件读取代理配置
+```bash
+crabatool -run -webPath F:\project\www -port 9090 -proxySrc F:\config\proxy.json
+```
+---
+## Jenkins 集成
+crabatool 可集成到 Jenkins 实现自动化构建流程，典型用法包括：平台更新、JS 打包、代码语法检测、检测报告推送钉钉。
+### Jenkins Shell 配置示例
+```bash
+# 进入助手目录
+cd /opt/ngp/shell/crabatool/
+# 更新助手
+npm update crabatool -registry=https://registry.npmjs.org
+# 打包 init.js 和 biz.js（必须在 jar 打包前执行）
+node craba.js -mergeinitjs -modName shell -childModList baseinfo,recordsheet,accounting -ignoreCompress false -progress 0
+# 代码语法检测并推送钉钉
+node craba.js -checkjs -webPath /opt/ngp/shell/web/src/main/resources/static/shell -modName shell -ignoreCheck folder1,js/craba.min.js -webhooks https://oapi.dingtalk.com/robot/send?access_token=xxxxx -progress 0
+```
+### 关键参数说明
+- `-progress 0`：Jenkins 环境下关闭进度条显示
+- `-webhooks`：推送地址，推荐使用钉钉群自定义机器人
+- `-ignoreCheck`：忽略检测的目录/文件，逗号分隔，相对 webPath 路径
+- `-globals`：全局变量白名单。Shell 中 `$` 字符需转义为 `\$`，如 `-globals \$doc,$jq`
+### 自动添加版本号
+在 Jenkins 构建脚本中添加：
+```bash
+crabatool -addVersion -file /opt/project/www/index.html -exp AUTOVERSION
+```
+### 自动检测并更新平台
+```bash
+crabatool -checkUpdate -version master -webPath /opt/project/www
+```
+---
+## 导出的模块 API
+crabatool 作为 npm 包，除了 CLI 工具外还导出了以下模块，可在 Node.js 项目中直接引用：
+```js
+var crabaTool = require('crabatool');
+```
+| 模块 | 说明 |
+|------|------|
+| `crabaTool.run(config)` | 启动工具主入口 |
+| `crabaTool.config` | 全局配置对象 |
+| `crabaTool.utils` | 工具函数集合 |
+| `crabaTool.server` | Express 服务器模块（`server.start(options)` / `server.run(options)`） |
+| `crabaTool.stringUtils` | 字符串处理工具 |
+| `crabaTool.pager` | 分页工具 |
+| `crabaTool.cuid` | 唯一 ID 生成器 |
+| `crabaTool.JSONCRUD` | JSON 文件增删改查工具 |
+| `crabaTool.DbHelper` | 数据库操作助手（MySQL） |
+| `crabaTool.StringBuilder` | 字符串拼接工具 |
+| `crabaTool.hashUtils` | 哈希计算工具 |
+---
+## 常见问题
+### 1. npm 安装失败或延迟
+尝试使用内网仓库：
+```bash
+npm install crabatool -g --registry http://172.17.0.236:4873/
+```
+或切换为官方源：
+```bash
+npm install crabatool -g --registry https://registry.npmjs.org
+```
+### 2. 命令行参数和配置文件的优先级
+命令行参数优先级 **高于** 配置文件中的值。例如：
+```bash
+node craba.js -run -webPath E:/other/path
+```
+即使 `craba.js` 中配置了 `webPath`，也会使用命令行传入的路径。
+### 3. 全局安装后 crabatool 命令找不到
+确保使用管理员权限安装，且 npm 全局目录在系统 PATH 中。
+### 4. webPath 路径格式
+- 支持绝对路径和相对路径（相对于命令行执行目录）
+- 路径中可使用 `/` 或 `\\`
+- 应指向 `login.html`（NGP）或 `index.html` 所在目录
+### 5. 不同环境如何灵活配置
+- 本地开发：使用配置文件（`craba.js`）设置默认参数
+- Jenkins/CI：通过命令行参数动态覆盖配置
+- 多项目共用：创建 `.bat` / `.sh` 脚本，通过 `-webPath` 等参数区分项目
+### 6. 跳过系统信息上报
+```bash
+crabatool --skip-report -run -webPath 项目路径
+```

package/res/client.js CHANGED Viewed

@@ -45,7 +45,7 @@
         return;
       // 更新了平台 全部刷新
-      var mainPanel = $common.getMainPanel();
+      var mainPanel = $common.getMainPanel(null, false);
       if (!mainPanel || files.includes('js/craba.min.js') || files.includes('js/crabaEx.min.js') || files.includes('js/agency.js')) {
         window.location.reload();
         return;