tools/README.md

# Tools 工具箱 🧰

这是一个实用的命令行工具集合，包含三个高效的 Rust 开发的工具，用于日常文件处理和数据处理任务。

## 📦 工具列表

### 1. [cutpic](./cutPic/README.md) - 图片裁切工具 🖼️

**功能**: 将图片按指定的行列数均匀分割成多个小图片

**适用场景**:
- 制作拼图素材
- 提取 Sprite Sheet 中的动画帧
- 分割图标集
- 创建 Instagram 九宫格
- 处理大幅面图片

**快速开始**:
```bash
# 直接使用全局命令
cutpic -i image.png -w 3 -h 2
```

[查看详细文档 →](./cutPic/README.md)

---

### 2. [zip](./zip/README.md) - ZIP 打包工具 📦

**功能**: 将文件或文件夹快速打包成 zip 压缩文件

**适用场景**:
- 项目备份
- 文件分享
- 代码归档
- 日志收集
- 资源打包

**特色功能**:
- ✅ 支持单个文件、多个文件或整个文件夹
- ✅ 智能命名（自动生成有意义的文件名）
- ✅ 剪贴板集成（Windows 上可复制文件到剪贴板）
- ✅ 详细的打包统计信息

**快速开始**:
```bash
# 直接使用全局命令
zip myfolder -n backup.zip -v
```

[查看详细文档 →](./zip/README.md)

---

### 3. [dexcel](./dexcel/README.md) - Excel 读写工具 📊

**功能**: 命令行 Excel 文件读取和写入工具

**适用场景**:
- 数据分析
- 数据转换
- 报告生成
- 数据验证
- 批量数据录入

**特色功能**:
- ✅ 灵活的范围读取（行、列选择）
- ✅ 负数列索引（从右往左倒数）
- ✅ 智能数据保留（写入时不覆盖现有数据）
- ✅ TSV 格式输出（便于管道处理）

**快速开始**:
```bash
# 直接使用全局命令

# 读取 Excel
dexcel read -f data.xlsx

# 写入 Excel
dexcel write -f data.xlsx -x 1 -y 1 -v "Hello"
```

[查看详细文档 →](./dexcel/README.md)

---

## 🚀 安装方式

### 方式一：Cargo Install（推荐）

在每个工具目录下执行：

```bash
# 安装 cutpic
cd cutPic
cargo install --path .

# 安装 dexcel
cd ../dexcel
cargo install --path .

# 安装 zip
cd ../zip
cargo install --path .
```

安装后，可以直接在命令行中使用 `cutpic`、`dexcel`、`zip` 命令。

### 方式二：本地编译

```bash
# Windows PowerShell
Get-ChildItem -Directory | Where-Object { $_.Name -ne 'target' } | ForEach-Object {
    Write-Host "Building $($_.Name)..."
    Push-Location $_.FullName
    cargo build --release
    Pop-Location
}

# Linux/macOS
for dir in */; do
    if [ -f "$dir/Cargo.toml" ]; then
        echo "Building $dir..."
        cd "$dir" && cargo build --release && cd ..
    fi
done
```

编译后的可执行文件位于各工具的 `target/release/` 目录下。

---

## 💡 综合使用示例

### 示例 1: 项目管理自动化

```bash
# 1. 打包项目源代码
zip src/ README.md LICENSE -n project-source.zip

# 2. 创建版本信息 Excel
dexcel write -f version-info.xlsx -x 1 -y 1 -v "版本"
dexcel write -f version-info.xlsx -x 1 -y 2 -v "日期"
dexcel write -f version-info.xlsx -x 1 -y 3 -v "说明"
dexcel write -f version-info.xlsx -x 2 -y 1 -v "1.0.0"
dexcel write -f version-info.xlsx -x 2 -y 2 -v "2024-01-01"
dexcel write -f version-info.xlsx -x 2 -y 3 -v "初始版本"

# 3. 打包发布文件
zip project-source.zip version-info.xlsx -n release-v1.0.0.zip -v
```

### 示例 2: 图片资源处理工作流

```bash
# 1. 分割游戏精灵图
cutpic -i spritesheet.png -w 8 -h 4 --out ./frames

# 2. 创建资源清单 Excel
dexcel write -f assets.xlsx -x 1 -y 1 -v "文件名"
dexcel write -f assets.xlsx -x 1 -y 2 -v "类型"
dexcel write -f assets.xlsx -x 1 -y 3 -v "尺寸"

# 添加资源信息
dexcel write -f assets.xlsx -x 2 -y 1 -v "frame_1.png"
dexcel write -f assets.xlsx -x 2 -y 2 -v "动画帧"
dexcel write -f assets.xlsx -x 2 -y 3 -v "64x64"

# 3. 打包所有资源
zip frames/ assets.xlsx -n game-assets.zip
```

### 示例 3: 数据备份和处理

```bash
# 1. 备份重要文档
zip documents/ reports/ -n docs-backup.zip

# 2. 创建备份清单
dexcel write -f backup-log.xlsx -x 1 -y 1 -v "文件名"
dexcel write -f backup-log.xlsx -x 1 -y 2 -v "大小"
dexcel write -f backup-log.xlsx -x 1 -y 3 -v "日期"
dexcel write -f backup-log.xlsx -x 2 -y 1 -v "docs-backup.zip"
dexcel write -f backup-log.xlsx -x 2 -y 2 -v "15MB"
dexcel write -f backup-log.xlsx -x 2 -y 3 -v "2024-01-01"

# 3. 打包备份和日志
zip docs-backup.zip backup-log.xlsx -n complete-backup.zip -v
```

---

## 🎯 工具对比

| 特性 | cutpic | zip | dexcel |
|------|--------|-----|--------|
| **主要用途** | 图片分割 | 文件压缩 | Excel 读写 |
| **输入** | 单张图片 | 多文件/文件夹 | Excel 文件 |
| **输出** | 多张图片 | ZIP 压缩包 | 控制台/Excel |
| **平台支持** | 全平台 | 全平台 | 全平台 |
| **依赖数量** | 少 | 中 | 中 |
| **学习曲线** | 简单 | 简单 | 中等 |
| **适用人群** | 设计师、开发者 | 所有人 | 数据分析师、开发者 |

---

## 🔧 技术栈

所有工具都使用 **Rust** 开发，具有以下优势：

- ⚡ **高性能**: 编译型语言，运行速度快
- 🔒 **内存安全**: 无垃圾回收，无内存泄漏
- 📦 **单文件分发**: 无需运行时环境
- 🌍 **跨平台**: Windows、macOS、Linux 原生支持
- 🛠️ **现代工具链**: Cargo 包管理，优秀的开发体验

---

## 📊 项目结构

```
tools/
├── .gitignore           # Git 忽略文件配置
├── README.md            # 本文件
├── cutPic/              # 图片裁切工具
│   ├── src/
│   │   └── main.rs
│   ├── Cargo.toml
│   ├── README.md
│   └── target/          # (被 Git 忽略)
│       └── release/
│           └── cutpic.exe
│
├── zip/                 # ZIP 打包工具
│   ├── src/
│   │   └── main.rs
│   ├── Cargo.toml
│   ├── README.md
│   └── target/          # (被 Git 忽略)
│       └── release/
│           └── zip.exe
│
└── dexcel/              # Excel 读写工具
    ├── src/
    │   └── main.rs
    ├── Cargo.toml
    ├── README.md
    ├── example.bat
    └── target/          # (被 Git 忽略)
        └── release/
            └── dexcel.exe
```

**注意**: `target/` 目录和 `Cargo.lock` 文件已被添加到 `.gitignore`，不会被提交到 Git 仓库。

---

## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 提交 Issue
- 描述清楚问题和复现步骤
- 提供环境信息（操作系统、Rust 版本等）
- 如果可能，提供截图或日志

### 提交 Pull Request
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 开发规范
- 遵循 Rust 官方代码风格
- 添加必要的注释和文档
- 确保代码通过 `cargo clippy` 检查
- 更新相关的 README 文档

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见各子项目的 LICENSE 文件。

---

## 🙏 致谢

感谢以下开源项目和社区：
- [Rust](https://www.rust-lang.org/) - 编程语言
- [Cargo](https://doc.rust-lang.org/cargo/) - 包管理器
- 所有依赖库的作者和维护者
- 所有贡献者和用户

---

## 📞 联系方式

- 项目地址: `c:\Users\macro\Documents\workspace\self\tools`
- 问题反馈: 提交 GitHub Issue

---

**Made with ❤️ using Rust**

*最后更新: 2024年*