crabatool 1.0.844 → 1.0.847

package/crabatool-agent-guide.md

@@ -0,0 +1,354 @@
+# crabatool 智能助手使用指南
+
+## 1. 工具简介
+
+crabatool 是一个基于 Node.js 的前端工程化脚手架工具，主要服务于 Craba/NGP 前端项目体系。支持命令行（CLI）方式使用，兼容 Windows、macOS、Linux，可集成 Jenkins 实现自动化构建。
+
+**核心价值**：
+- 快速搭建 Craba 项目环境
+- 提供本地开发服务器，支持热刷新
+- 代码质量检测与优化
+- 自动化构建与部署
+- 知识库管理与更新
+
+## 2. 环境要求与安装
+
+### 2.1 环境要求
+- **Node.js**：LTS 版本
+- 支持平台：Windows、macOS、Linux
+
+### 2.2 安装方法
+
+**全局安装（推荐）**：
+```bash
+npm install crabatool -g
+```
+
+**从内网仓库安装（更快）**：
+```bash
+npm install crabatool -g --registry http://172.17.0.236:4873/
+```
+
+**验证安装**：
+```bash
+# 查看版本号
+crabatool -v
+
+# 查看帮助信息
+crabatool --help
+```
+
+## 3. 核心功能与使用示例
+
+### 3.1 项目初始化与环境搭建
+
+**功能说明**：快速创建和配置 Craba 项目环境
+
+**使用示例**：
+```bash
+# 第一步：创建项目目录
+mkdir my-craba-app && cd my-craba-app
+
+# 第二步：安装 Craba 框架
+crabatool -install -webPath .
+
+# 第三步：创建基础文件
+# 使用智能助手或大模型生成 index.html、Main.gspx 等必要文件
+
+# 第四步：启动开发服务器
+crabatool -run -webPath . -port 8080
+
+# 第五步：打开浏览器访问
+# http://localhost:8080
+```
+
+### 3.2 本地开发服务器
+
+**功能说明**：启动基于 Express 的本地前端静态资源服务器，支持自动打开浏览器、文件热刷新、代理转发、gzip 压缩等
+
+**参数说明**：
+- `-webPath`：网站根路径（必填）
+- `-port`：前端服务端口号（必填）
+- `-refresh true`：开启文件变动自动刷新浏览器
+- `-proxy`：配置 API 代理转发规则
+
+**使用示例**：
+```bash
+# 基本启动
+crabatool -run -webPath F:\myproject\www -port 9090
+
+# 启动并开启热刷新
+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}}"
+```
+
+### 3.3 代码质量检测
+
+**功能说明**：对项目下所有 JS 文件进行语法兼容性检测，包括 ESLint 规则检查、编码检测、文件大小检测、ES6+ 语法检测，同时检查 gspx 文件中的标签使用规范
+
+**参数说明**：
+- `-webPath`：项目路径（必填）
+- `-modName`：项目（模块）名称
+- `-ignoreCheck`：忽略检测的目录或文件
+- `-globals`：全局变量名列表
+
+**使用示例**：
+```bash
+# 基本检测
+crabatool -checkjs -webPath F:\myproject\www -modName mymod
+
+# 忽略特定目录和文件
+crabatool -checkjs -webPath F:\myproject\www -modName mymod -ignoreCheck ueditor,iconfont,js/math.min.js
+```
+
+### 3.4 框架更新与管理
+
+**功能说明**：从内网服务器拉取最新的 Craba 平台资源，覆盖到指定项目路径下
+
+**参数说明**：
+- `-webPath`：项目路径（必填）
+- `-version`：指定分支版本号，默认为 `master`
+
+**使用示例**：
+```bash
+# 更新主分支平台
+crabatool -update -webPath F:\myproject\www
+
+# 更新指定分支
+crabatool -update -webPath F:\myproject\www -version ngp5.3
+```
+
+### 3.5 知识库管理
+
+**功能说明**：上传和更新 Craba 知识库文档
+
+**参数说明**：
+- `-docsPath`：文档路径（必填）
+
+**使用示例**：
+```bash
+# 上传知识库到服务器
+crabatool -uploadDocs -docsPath F:\craba-doc
+
+# 从服务器更新知识库
+crabatool -updateDocs -docsPath F:\craba-doc
+```
+
+### 3.6 版本管理
+
+**功能说明**：查看版本信息和管理版本号
+
+**使用示例**：
+```bash
+# 查看 crabatool 工具版本
+crabatool -v
+
+# 查看 Craba 框架的最新版本
+crabatool -crabaVersion
+
+# 自动添加版本号（时间戳）
+crabatool -addVersion -file F:\project\www\index.html -exp AUTOVERSION
+```
+
+## 4. 高级功能
+
+### 4.1 文件合并与压缩
+
+**功能说明**：将多个 JS 或 CSS 文件合并为一个文件，支持压缩
+
+**使用示例**：
+```bash
+# 合并压缩 JS 文件
+crabatool -mergejs -targetPath F:\project\js -inNames a.js,b.js -outName F:\output\merged.js
+
+# 合并压缩 CSS 文件
+crabatool -mergecss -targetPath F:\project\skins -inNames iconfont.css,craba.min.css -outName D:\output\craba.min.css
+
+# 打包资源文件为 JSON
+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
+```
+
+### 4.2 开发环境配置
+
+**功能说明**：自动安装或更新 IDE 开发环境配置
+
+**使用示例**：
+```bash
+# 安装/更新 IDEA 环境
+crabatool -idea
+
+# 安装/更新 VSCode 环境
+crabatool -vscode
+```
+
+### 4.3 图标字体管理
+
+**功能说明**：检测项目中图标字体的使用情况，解压并部署字体库文件
+
+**使用示例**：
+```bash
+# 检测图标字体使用情况
+crabatool -checkiconfont -webPath F:\myproject\www -modName mymod
+
+# 解压并部署字体库
+crabatool -iconfont -zipPath F:\project\biconfont -fontPath F:\project\skins\bicon -prefix .bicon- -fontName biconfont
+```
+
+## 5. 命令行参数速查
+
+### 5.1 通用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--skip-report` | 跳过系统信息上报，提高启动速度 |
+| `-v` | 查看 crabatool 工具版本号 |
+| `-crabaVersion` | 查看 Craba 框架的最新版本号 |
+
+### 5.2 核心功能参数
+
+| 命令 | 说明 | 必填参数 |
+|------|------|----------|
+| `-install` | 安装 Craba 平台资源 | `-webPath` |
+| `-run` | 启动本地前端服务器 | `-webPath`, `-port` |
+| `-update` | 更新 Craba 平台资源 | `-webPath` |
+| `-checkjs` | 检查项目 JS 语法兼容性 | `-webPath` |
+| `-uploadDocs` | 上传 Craba 知识库 | `-docsPath` |
+| `-updateDocs` | 更新 Craba 知识库 | `-docsPath` |
+| `-mergejs` | 合并压缩 JS 文件 | `-inNames`, `-outName` |
+| `-mergecss` | 合并压缩 CSS 文件 | `-inNames`, `-outName` |
+| `-mergeFiles` | 打包资源文件为 JSON | `-inNames` |
+
+## 6. 智能助手集成指南
+
+### 6.1 与 Agent 集成
+
+**使用场景**：
+- 自动初始化项目环境
+- 构建自动化工作流
+- 代码质量检测与报告
+
+**集成示例**：
+```javascript
+// Agent 调用示例
+async function initializeProject(projectPath, port = 8080) {
+  // 安装 Craba 框架
+  await execCommand(`crabatool -install -webPath ${projectPath}`);
+  
+  // 创建基础文件（index.html、Main.gspx 等）
+  await createBasicFiles(projectPath);
+  
+  // 启动开发服务器
+  await execCommand(`crabatool -run -webPath ${projectPath} -port ${port} -refresh true`);
+  
+  return `项目已初始化并启动，访问地址: http://localhost:${port}`;
+}
+
+// 创建基础文件的辅助函数
+async function createBasicFiles(projectPath) {
+  // 这里可以实现创建 index.html、Main.gspx 等必要文件的逻辑
+  // 例如使用模板生成或从默认模板复制
+  console.log(`在 ${projectPath} 中创建基础文件...`);
+  // 具体实现代码
+}
+
+// 代码质量检测
+async function checkCodeQuality(projectPath, moduleName) {
+  const result = await execCommand(`crabatool -checkjs -webPath ${projectPath} -modName ${moduleName}`);
+  return `代码质量检测完成: ${result}`;
+}
+```
+
+### 6.2 与大模型集成
+
+**使用场景**：
+- 生成项目脚手架
+- 自动化代码审查
+- 知识库管理与更新
+
+**提示词模板**：
+```
+你是一个前端工程化专家，使用 crabatool 工具来管理 Craba 项目。
+
+请根据以下需求执行相应操作：
+1. 创建一个新的 Craba 项目，路径为 ${projectPath}
+2. 安装最新版本的 Craba 框架
+3. 创建基础文件（index.html、Main.gspx 等）
+4. 启动开发服务器，端口为 ${port}
+5. 检查项目代码质量
+
+请使用 crabatool 命令完成上述任务，并返回执行结果。
+```
+
+## 7. 最佳实践
+
+### 7.1 项目初始化流程
+
+1. **创建项目目录**：`mkdir my-project && cd my-project`
+2. **安装 Craba 框架**：`crabatool -install -webPath .`
+3. **创建基础文件**：使用 agent 或大模型生成 index.html、Main.gspx 等文件
+4. **启动开发服务器**：`crabatool -run -webPath . -port 8080 -refresh true`
+5. **开发与调试**：使用热刷新功能进行开发
+6. **代码检查**：`crabatool -checkjs -webPath . -modName myproject`
+7. **构建与部署**：合并压缩文件，添加版本号
+
+### 7.2 性能优化
+
+- **开发环境**：使用 `-refresh` 启用热更新，使用 `-ignoreCompress` 不压缩代码
+- **生产环境**：合并所有 JS 文件，压缩代码，添加版本号，生成 hash 清单
+
+### 7.3 常见问题与解决方案
+
+**问题**：端口被占用
+**解决方案**：使用其他端口，如 `crabatool -run -webPath . -port 3001`
+
+**问题**：找不到模块
+**解决方案**：重新安装 crabatool，`npm install crabatool -g`
+
+**问题**：权限不足
+**解决方案**：使用管理员权限运行命令提示符或终端
+
+**问题**：npm 安装失败
+**解决方案**：使用内网仓库，`npm install crabatool -g --registry http://172.17.0.236:4873/`
+
+## 8. 命令参考速查表
+
+### 8.1 常用命令
+
+| 命令 | 功能 | 示例 |
+|------|------|------|
+| `-install` | 安装平台资源 | `crabatool -install -webPath .` |
+| `-run` | 启动本地服务 | `crabatool -run -webPath . -port 8080` |
+| `-update` | 更新平台资源 | `crabatool -update -webPath .` |
+| `-checkjs` | JS 语法检测 | `crabatool -checkjs -webPath . -modName myapp` |
+| `-v` | 查看工具版本 | `crabatool -v` |
+| `-crabaVersion` | 查看框架版本 | `crabatool -crabaVersion` |
+| `-uploadDocs` | 上传知识库 | `crabatool -uploadDocs -docsPath F:\craba-doc` |
+| `-updateDocs` | 更新知识库 | `crabatool -updateDocs -docsPath F:\craba-doc` |
+
+### 8.2 高级命令
+
+| 命令 | 功能 | 示例 |
+|------|------|------|
+| `-mergejs` | 合并压缩 JS | `crabatool -mergejs -inNames a.js,b.js -outName merged.js` |
+| `-mergecss` | 合并压缩 CSS | `crabatool -mergecss -inNames a.css,b.css -outName merged.css` |
+| `-mergeFiles` | 打包资源为 JSON | `crabatool -mergeFiles -inNames file1.js,file2.css -outName res.js` |
+| `-addVersion` | 添加版本号 | `crabatool -addVersion -file index.html -exp AUTOVERSION` |
+| `-idea` | 安装 IDEA 环境 | `crabatool -idea` |
+| `-vscode` | 安装 VSCode 环境 | `crabatool -vscode` |
+| `-checkiconfont` | 检测图标字体 | `crabatool -checkiconfont -webPath . -modName myapp` |
+| `-iconfont` | 部署字体库 | `crabatool -iconfont -zipPath ./font -fontPath ./skins` |
+
+## 9. 总结
+
+crabatool 是一个功能强大的前端工程化脚手架工具，通过命令行方式提供了丰富的功能，包括项目初始化、开发服务器、代码检测、文件合并、知识库管理等。与智能助手和大模型集成后，可以进一步提高开发效率，实现自动化工作流。
+
+**核心优势**：
+- 简单易用的命令行接口
+- 丰富的功能集
+- 跨平台支持
+- 与智能助手和大模型的良好集成
+- 适合从开发到部署的全流程使用
+
+通过本指南，智能助手和大模型可以快速掌握 crabatool 的使用方法，为前端开发提供更高效的工具支持。

package/ev-recording-implementation.md

@@ -0,0 +1,165 @@
+# runEv 录屏功能实现文档
+
+## 1. 功能概述
+
+`runEv` 是 crabatool 提供的录屏功能
+1. 用于录制教学视频和音频，支持自动检测录制完成并上传到七牛服务器，最终将音频 URL 返回给前端。
+2. 可提高录制教学人员的效率，减少繁琐人工关联教学步骤的音频还容易出错的问题。传统做法是先用ev录屏，然后给音频命名，然后教学采集界面去手工选择音频文件上传到七牛服务器，然后把音频url关联到教学里面。
+
+## 2. 实现架构
+
+### 2.1 系统架构
+
+```
+┌─────────────┐ WebSocket  ┌─────────────┐   本地文件系统  ┌─────────────┐
+│  前端页面   │────────────→│  crabatool  │──────────────→│  ev 录屏工具  │
+└─────────────┘            └─────────────┘               └─────────────┘
+       ↑                          │
+       │                          │
+       └──────────────────────────┘
+              返回音频 URL
+```
+
+### 2.2 核心组件
+
+- **前端**：`f:\crabaevery\www\local\study.plug.js` 中的 `doInsertPlayer` 函数调用独立封装的`evSocket`组件
+- **后端**：`f:\crabatool\tool\evsockettool.js` 处理录屏逻辑
+- **工具**：ev 录屏工具（自动检测路径）
+- **存储**：七牛云存储（模拟实现）
+
+## 3. 实现步骤
+
+### 3.1 前端实现
+
+1. **连接 WebSocket**：
+   - **evSocket组件**：封装在`study.plug.js`文件底部，提供crabatool之间的消息处理，并支持doInsertPlayer传递的回调方法（业务处理一些界面更新和数据修改）；且切换其他教学，关闭教学时要通知evSocket组件中断socket连接，并通知crabatool停止监听等操作，用户单独操作ev录屏不受影响。
+   - 使用固定端口 63096 连接到 crabatool 服务
+   - 处理连接成功、失败、关闭等事件
+2. **发送录屏请求**：
+   - 连接成功后发送 `evRecord` 消息，action 为 `start`
+   - 等待后端响应
+3. **处理响应**：
+   - `started`：显示录屏工具已启动的提示
+   - `completed`：获取音频 URL 并添加到当前步骤
+   - `error`：显示错误提示
+4. **资源清理**：
+   - 页面卸载时发送 `stop` 消息
+   - 连接关闭时发送 `stop` 消息
+
+### 3.2 后端实现
+
+1. **初始化**：
+   - 直接启动 runEv 服务时，什么都不用做
+   - 等待前端连接和 start 消息，如果等到的是连接消息，记录连接时间。
+2. **处理 start 消息**：
+   - 记录启动时间
+   - 自动检测 ev 录屏工具路径
+   - 启动 ev 录屏工具
+   - 创建文件监听器，监控输出目录
+3. **文件监控**：
+   - 监听文件 `change` 事件，文件创建时间必须大于启动时间
+   - 每隔3s检查文件创建时间和大小
+4. **录制完成检测**：
+   - 方案1：监控文件大小变化，连续 3 次（3 秒）大小稳定，如果3次检测发现文件大小有变动要重置计数因为ev还在录制中，且至少有过一次增长，认为录制完成。
+   - 方案2：固定3次3秒这种方式比较死板，可以根据文件大小变化规律，判断是否是录制完成。可以记录每次ev录屏过程的数据：从创建文件到每次更新文件的规律，包括文件大小、文件名、创建时间、更新时间等。
+5. **处理完成文件**：
+   - 模拟上传到七牛服务器
+   - 生成音频 URL
+   - 发送 `completed` 消息给前端
+6. **处理 stop 消息**：
+   - 停止录屏状态
+   - 清理监控文件
+   - 关闭文件监听器
+7. **日志处理**：
+   - crabatool所有关键步骤都要写日志，方便调试
+   - 日志封装log函数，需要增加日志时间。
+   
+
+## 4. 技术思路
+
+### 4.1 自动检测 ev 路径
+
+- 检查多个常见安装路径：
+  - `C:\Program Files\EVCapture\EVCapture.exe`
+  - `C:\Program Files (x86)\EVCapture\EVCapture.exe`
+  - `%LocalAppData%\EVCapture\EVCapture.exe`
+  - `%AppData%\EVCapture\EVCapture.exe`
+  - `%USERPROFILE%\Desktop\EVCapture.exe`
+  - 环境变量 `EV_PATH`
+
+### 4.3 错误处理
+
+- 捕获文件操作错误
+- 处理连接错误
+- 提供详细的日志信息
+
+## 5. 使用方法
+
+### 5.1 启动服务
+
+```bash
+# 基本启动
+crabatool -runEv -evSavePath "ev保存音频的路径，如c:\\Users\\grasp\\ev recordings\\"
+```
+
+### 5.2 前端操作
+
+1. 打开教学录制页面
+2. 点击"采集这一步的音/视频"按钮
+3. 等待录屏工具启动
+4. 手动开始录制
+5. 录制完成后，音频会自动添加到当前步骤
+
+## 6. 常见问题及解决方案
+
+### 6.1 连接失败
+
+**问题**：前端显示"连接crabatool服务失败"
+
+**解决方案**：
+
+- 确保 crabatool 服务已启动
+- 检查端口是否被占用
+- 检查网络连接
+
+### 6.3 连续录制问题
+
+**问题**：连续录制多个音频时，后续录制没有被捕获
+
+**解决方案**：
+
+- 确保服务保持运行状态
+- 每次录制完成后，socket会保持前端的通信状态
+- 等待下一次录制的消息
+
+## 7. 代码结构
+
+### 7.1 前端代码
+
+- `f:\crabaevery\www\local\study.plug.js`：
+  - `doInsertPlayer` 函数：处理插入播放器逻辑
+  - WebSocket 连接和消息处理
+  - 页面卸载时的资源清理
+
+### 7.2 后端代码
+
+- `f:\crabatool\tool\evsockettool.js`：
+  - `handleEvRecord`：处理前端消息
+  - `startEvRecording`：启动录屏
+  - `stopEvRecording`：停止录屏
+  - `watchEvOutput`：监控输出目录
+  - `startMonitoringFile`：监控文件大小变化
+  - `processEvFile`：处理完成的文件
+- `f:\crabatool\tool\sockettool.js`：
+  - 引入 `evsockettool.js`
+  - 处理 WebSocket 消息
+- `f:\crabatool\tool\start.js`：
+  - `runEvServer`：启动 ev 录屏服务
+- `f:\crabatool\index.js`：
+  - 添加 `-runEv` 命令支持
+
+## 8. 日志系统
+
+- 所有日志都包含时间戳
+- 详细记录文件监控、大小变化等信息
+- 错误信息清晰明了

package/index.js

@@ -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');
@@ -128,6 +128,24 @@ async function checkFast(args) {
     return false;
   }
 
+  // 上传craba知识库文档
+  if (args.includes('-uploadDocs')) {
+    start.bindAndCheckConfig('-docsPath');
+    start.bindConfigByArgv('-host');
+    start.bindConfigByArgv('-token');
+    require('./tool/uploadDocs.js').run();
+    return false;
+  }
+
+  // 更新craba知识库文档
+  if (args.includes('-updateDocs')) {
+    start.bindAndCheckConfig('-docsPath');
+    start.bindConfigByArgv('-host');
+    start.bindConfigByArgv('-token');
+    require('./tool/updateDocs.js').run();
+    return false;
+  }
+
   // 更新ngp的图标库和皮肤
   if (args.includes('-updateSkin')) {
     start.bindAndCheckConfig('-skinPath');
@@ -316,6 +334,13 @@ async function checkFast(args) {
     return false;
   }
 
+  // 启动ev录屏服务
+  if (args.includes('-runEv')) {
+    start.bindConfigByArgv('-evSavePath');
+    start.bindConfigByArgv('-port');
+    start.runEvServer();
+    return false;
+  }
 
   return true;
 }

package/lib/config.js

@@ -34,6 +34,7 @@ class Config {
 
     // 文件监听与代码检测相关配置
     this.enableFileWatcher = true; // 是否启用文件监听功能
+    this.evSavePath = ''; // ev录屏工具保存路径
 
     // 分离式更新相关配置
     this.enableDetachedUpdate = true; // 是否启用分离式更新

package/lib/server.js

@@ -35,7 +35,29 @@ exports.run = function(options) {
 exports.start = function(options) {
   var app = new express();
   createServer(app, options);
+}
 
+// 2. 独立server服务（crabatool使用）
+exports.startEvServer = function(options) {
+  var app = new express();
+  // 确保 port 是数字类型，避免字符串拼接导致端口超出范围
+  const portNum = parseInt(config.port, 10);
+  const socketPortNum = portNum;
+
+  // 检查计算后的端口是否在有效范围内 (0-65535)
+  if (socketPortNum > 65535) {
+    // 如果超出范围，使用一个较小的偏移量或固定端口
+    config.socketPort = portNum + 1000;
+    if (config.socketPort > 65535) {
+      // 如果还是超出，使用默认的 WebSocket 端口
+      config.socketPort = 8080;
+    }
+    utils.log(`警告: 计算的 socketPort (${socketPortNum}) 超出有效范围，已调整为 ${config.socketPort}`);
+  } else {
+    config.socketPort = socketPortNum;
+  }
+
+  require('../tool/sockettool.js');
 }
 
 // 3. 返回在线预览案例server总数
@@ -160,6 +182,7 @@ function createServer(app, options) {
 
   app.webPath = webPath; // handler.js里面动态获取当前app的网站路径（多个server实例的时候需要）
 
+  // 静态文件服务
   app.use(express.static(webPath, {
     maxage: '100h', // 强制缓存资源
     setHeaders: function(res, pathname, stat) {
@@ -180,6 +203,8 @@ function createServer(app, options) {
     }
   }));
 
+
+
   // 业务ap的代理转发
   if (config.proxy) {
     var { createProxyMiddleware } = require('http-proxy-middleware');

package/package.json

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