@nlpleaf/tools

游戏开发纯库工具集（npm 包）。对外导出可复用类与工具，由 tools_gui 等上层应用引用。

安装（npm）

npm install @nlpleaf/tools

import { ReplaceText, Epub2Md, BeyondCompare, GitHelper, fileHelper } from "@nlpleaf/tools";

本地子模块开发（tools_gui）：

"@nlpleaf/tools": "file:tools"

作为纯库使用（推荐）

本工程定位为纯库（npm 包）：对外只导出可复用、无副作用的类与工具，由上层应用（如 tools_gui 的 GUI 与 CLI）按需引用，不在库内承载业务上下文（配置路径、项目选择等）。

统一出口为根目录 index.ts（构建产物 dist/index.js）：

import { ReplaceText, Epub2Md, BeyondCompare, GitHelper, fileHelper } from "@nlpleaf/tools";

[!IMPORTANT] 遗留入口：src/Main.ts（switch-case 分发）与 src/libs/cli/（commander 命令）为历史 CLI 入口，与业务/配置路径糅合。新代码请勿依赖，统一从 index.ts 引库类；这两处暂保留以兼容旧使用方，详见下文「主程序 CLI 子命令（遗留）」。

快速开始

安装依赖

npm install

构建与发布

# 编译纯库产物到 dist/
npm run build

# 打包前自检
npm pack --dry-run

# 发布到 npmjs（需 @nlpleaf 组织发布权限）
npm publish --access public

常用命令

# 运行主程序（无参数时执行默认流程）
npm run dev

# 构建 TypeScript
npm run build

# 运行测试套件
npm test

# 打印工具清单
npm run help

# 清理 FGUI 重复资源
npm run clean-duplicates

# 清理 FGUI 未使用资源
npm run clean-fgui

# 同步 libs 并打包（需 ztools-libs/ 目录，见 sync-and-pack.ts 说明）
npm run sync-and-pack

主程序 CLI 子命令（遗留）

[!WARNING] 以下为遗留入口，新项目请改用 index.ts 暴露的库类（参见顶部「作为纯库使用」）。

通过 npm run dev -- <命令> [参数...] 调用 src/Main.ts：

| 命令 | 说明 | |------|------| | BeyondCompare | 文件对比（config/BeyondCompare.json） | | ReplaceText | 批量文本替换（config/ReplaceText.json） | | ImgResizer | 图片尺寸调整 | | ExportTable | 表格导出（infoDev channel） | | ColorParser | 颜色解析 | | WordTranslate | 多语言 Word 工具 | | CC2FGUI | Cocos Prefab 转 FGUI | | CCCUtils | Cocos Creator 资源分析 | | RGBToHex | RGB 转十六进制 |

项目结构

game-dev-tools/
├── index.ts                # 纯库统一出口（推荐入口，re-export 库类）
├── src/                    # 入口与公共库
│   ├── Main.ts             # 遗留主入口（CLI 分发，勿用于新代码）
│   ├── libs/               # 可复用库（file/git/image/log/platform/cli…）
│   ├── test/               # 单元测试与示例
│   └── cases/              # 遗留工具（file-operations、other）；新业务见 client/
│
├── client/                 # 客户端业务工具（主体）
│   ├── cocos/              # Cocos Creator 引擎同步、资源清理
│   ├── fgui/               # FairyGUI 转换、清理、多语言
│   ├── data-processing/    # Excel/Word/表格导出
│   ├── development/        # 颜色解析、RGB 转换
│   ├── image/              # 图片处理
│   └── conversion/         # 换行符转换等
│
├── design/                 # 策划/配置表
│   ├── lubanConfigTools/   # Luban 配置表生成
│   └── xls2code/           # Excel → TypeScript 枚举
│
├── art/                    # 美术第三方工具
│   ├── spine/              # Spine 查看器
│   ├── TexturePacker/      # 图集打包说明
│   └── 合图切割/           # 合图切割工具（zip/air）
│
├── version/                # 版本控制运维
│   ├── git/                # Git 配置脚本
│   ├── gitea/              # 本地 Gitea 服务
│   └── svn/                # SVN 批处理
│
├── server/                 # 服务端相关
│   ├── api/                # Swagger → API 代码生成
│   └── http/               # HTTP 服务启动脚本
│
├── config/                 # 全局 JSON 配置（ProjectInfo、BeyondCompare 等）
├── docs/                   # 文档中心
├── ebook/                  # 电子书转 Markdown
├── Interface_Gen/          # 多语言接口规范与 Go/TS 生成器
├── zcmd/                   # Windows 右键/资源管理器增强
├── zstime/                 # Word/Excel 批处理转换
│
├── package.json
├── tsconfig.json
├── sync-and-pack.ts        # libs 同步打包脚本
└── README.md               # 本文件

历史目录映射（文档迁移参考）

| 旧顶层路径 | 现路径 | |-----------|--------| | cocos/ | client/cocos/ | | git/、gitea/、svn/ | version/git/、version/gitea/、version/svn/ | | http/ | server/http/ | | spine/、TexturePacker/ | art/spine/、art/TexturePacker/ | | lubanConfigTools/ | design/lubanConfigTools/ | | ztools-libs/ | 已移除；sync-and-pack 需自行恢复或跳过 |

核心功能

客户端工具（client/）

• Cocos Creator：引擎/项目同步、资源清理、Prefab 分析
• FairyGUI：CC 转 FGUI、重复/未使用资源清理、多语言采集
• 数据处理：Excel 导出、Word 多语言、表格工具
• 图片：批量缩放与格式处理

配置与代码生成

• design/lubanConfigTools：Luban 配置表管线
• design/xls2code：Excel 转 TypeScript 枚举
• Interface_Gen：跨语言接口代码生成
• server/api：Swagger API 生成

版本与运维

• version/：Git / SVN / Gitea 本地脚本
• zcmd/：Windows 注册表增强
• zstime/：Word→MD、Excel→CSV 批处理

使用场景

清理 FGUI 资源

npm run clean-duplicates   # 重复资源
npm run clean-fgui         # 未使用资源

生成 Luban 配置表

cd design/lubanConfigTools
gen.bat

生成接口代码

cd Interface_Gen/generator
npm install
npm run dev -- interfaces.json go ./output/go

文件对比 / 文本替换

npm run dev -- BeyondCompare
npm run dev -- ReplaceText

详细文档

• 文档中心 — 导航入口
• 项目状态报告
• 项目组织方案
• 客户端工具文档
• 开发指南
• 测试指南
• 导入路径规范
• Cursor 配置
• 日志工具 LogHelper
• Cocos Creator 项目管理

开发指南

添加新工具

1. 在 client/<分类>/ 下实现功能（新业务优先放 client/，勿再放 src/cases/）
2. 在 src/Main.ts 的 switch 中注册 CLI 子命令（如需）
3. 在 docs/client/ 或 docs/guides/ 补充文档
4. 可选：在 scripts/help.js 的工具清单中登记

运行测试

npm test

更新日志

v1.3.0 (2026-06-29)

• 新增根目录 index.ts 纯库统一出口（ReplaceText、Epub2Md、BeyondCompare、GitHelper、fileHelper/jsonHelper/textHelper、logger）
• 明确定位为纯库；src/Main.ts、src/libs/cli/ 标注为遗留入口
• package.json main/types 指向 index.ts
• 修复 ebook/epub2md.ts 被打包后误判为入口执行

v1.2.0 (2026-06-29)

• 文档与真实目录结构对齐（client/、version/、art/、design/ 等）
• 修复 docs/ 导航断链
• 补全 npm test / npm run help 脚本
• 修正 Main.ts CLI 分发与硬编码路径

v1.1.0 (2024-11-18)

• Cocos Creator 模块重构（CocosCreatorProjMgr）
• 文档体系初版

v1.0.0 (2024-11-18)

• ZTools 集成至根目录，统一 package.json

维护者: 开发团队
最后更新: 2026-06-29