@king-3/file-kit 1.0.0-beta.2

package/README.md

@@ -0,0 +1,750 @@
+# @king-3/file-kit
+
+> 🔧 多功能文件工具箱 — Base64 转换 · 视频转音频 · 文件加密/解密
+
+[![npm version](https://img.shields.io/npm/v/@king-3/file-kit.svg)](https://www.npmjs.com/package/@king-3/file-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ 核心功能
+
+- 📄 **Base64 转换** - 文件 ↔ Base64 JSON，支持双向转换和完整还原
+- 🎵 **视频转音频** - 从视频中提取音频轨道，支持 5 种格式和 3 种质量级别
+- 🔐 **文件加密/解密** - 基于 AES-256-GCM 的军事级加密，确保数据安全
+
+## 📦 安装
+
+### 全局安装（推荐）
+
+```bash
+# 使用 pnpm
+pnpm install @king-3/file-kit -g
+
+# 使用 npm
+npm install @king-3/file-kit -g
+
+# 使用 yarn
+yarn global add @king-3/file-kit
+```
+
+### 本地安装
+
+```bash
+pnpm install @king-3/file-kit --save-dev
+```
+
+## 🚀 快速开始
+
+### 命令行模式
+
+```bash
+# 查看帮助
+fkt --help
+
+# 查看版本
+fkt --version
+
+# 启动交互模式
+fkt -i
+```
+
+### 交互模式
+
+交互模式提供友好的可视化界面，一步步引导您完成操作：
+
+```bash
+fkt -i
+```
+
+进入交互模式后，你可以通过方向键选择以下功能：
+
+- 📦 文件转 Base64
+- 🔄 Base64 还原文件
+- 🎵 视频提取音频
+- 🔐 文件加密
+- 🔓 文件解密
+
+---
+
+## 📖 功能详解
+
+### 1️⃣ Base64 转换
+
+将任意文件编码为 Base64 格式并保存为 JSON 文件，适用于 API 传输、数据库存储等场景。
+
+#### 基础用法
+
+```bash
+fkt base64 <文件路径> [选项]
+```
+
+#### 使用示例
+
+```bash
+# 转换文本文件
+fkt base64 document.txt
+
+# 转换图片
+fkt base64 photo.jpg
+
+# 转换 PDF
+fkt base64 report.pdf
+
+# 指定输出目录
+fkt base64 file.txt -o ./output
+```
+
+#### 输出格式
+
+生成的 JSON 文件格式如下：
+
+```json
+{
+  "type": "base64",
+  "createdAt": "2024-12-16 10:30:45",
+  "file": {
+    "name": "document.txt",
+    "extension": ".txt",
+    "size": 1024,
+    "base64": "SGVsbG8gV29ybGQh..."
+  }
+}
+```
+
+#### 命令选项
+
+| 选项                  | 描述                           |
+| --------------------- | ------------------------------ |
+| `-o, --output <path>` | 指定输出目录（默认：当前目录） |
+| `-h, --help`          | 显示帮助信息                   |
+
+---
+
+### 2️⃣ Base64 还原
+
+从 Base64 JSON 文件恢复原始文件。
+
+#### 基础用法
+
+```bash
+fkt restore <JSON文件路径> [选项]
+```
+
+#### 使用示例
+
+```bash
+# 还原文件（默认输出到当前目录）
+fkt restore archive.base64.json
+
+# 指定输出目录
+fkt restore archive.base64.json -o ./restored
+```
+
+#### 特性
+
+- ✅ 保留原始文件大小信息
+- ✅ 显示原始创建时间戳
+- ✅ 验证 JSON 格式完整性
+
+#### 命令选项
+
+| 选项                  | 描述                           |
+| --------------------- | ------------------------------ |
+| `-o, --output <path>` | 指定输出目录（默认：当前目录） |
+| `-h, --help`          | 显示帮助信息                   |
+
+---
+
+### 3️⃣ 视频转音频
+
+从视频文件中提取音频轨道，支持多种格式和质量选项。底层使用 FFmpeg 进行专业级音视频处理。
+
+#### 基础用法
+
+```bash
+fkt video-to-audio <视频文件> [选项]
+# 或使用别名
+fkt v2a <视频文件> [选项]
+```
+
+#### 支持的音频格式
+
+| 格式     | 扩展名  | 编码器     | 特点           | 适用场景        |
+| -------- | ------- | ---------- | -------------- | --------------- |
+| **MP3**  | `.mp3`  | libmp3lame | 最佳兼容性     | 日常使用、分享  |
+| **AAC**  | `.m4a`  | aac        | Apple 生态优化 | iOS/macOS 设备  |
+| **FLAC** | `.flac` | flac       | 无损压缩       | 音乐收藏、归档  |
+| **ALAC** | `.m4a`  | alac       | Apple 无损格式 | iTunes/iOS 无损 |
+| **WAV**  | `.wav`  | pcm_s16le  | 未压缩原始音频 | 专业音频编辑    |
+
+#### 质量选项
+
+| 质量       | MP3  | AAC  | FLAC   | 说明             |
+| ---------- | ---- | ---- | ------ | ---------------- |
+| **low**    | 128k | 128k | 级别 0 | 快速，文件小     |
+| **medium** | 192k | 192k | 级别 5 | 平衡质量（推荐） |
+| **high**   | 320k | 256k | 级别 8 | 最佳质量         |
+
+#### 使用示例
+
+**基础转换**
+
+```bash
+# 交互式选择格式和质量
+fkt v2a video.mp4
+```
+
+**指定格式和质量**
+
+```bash
+# 转换为高质量 MP3
+fkt v2a video.mp4 -f mp3 -q high
+
+# 转换为中等质量 AAC
+fkt v2a video.mp4 -f aac -q medium
+
+# 转换为无损 FLAC
+fkt v2a video.mp4 -f flac -q high
+```
+
+**指定输出路径**
+
+```bash
+# 指定输出目录
+fkt v2a video.mp4 -o ./audio -f mp3 -q high
+
+# 输出文件: ./audio/video.mp3
+```
+
+**批量转换**
+
+```bash
+# 使用 shell 循环批量转换
+for file in *.mp4; do
+  fkt v2a "$file" -f mp3 -q high
+done
+```
+
+#### 进度显示
+
+转换过程中会实时显示进度：
+
+```
+⠋ 正在提取音频 45%
+```
+
+完成后显示输出路径：
+
+```
+✔ 音频已提取到: ./video.mp3
+```
+
+#### 命令选项
+
+| 选项                  | 描述                              |
+| --------------------- | --------------------------------- |
+| `-f, --format <fmt>`  | 音频格式（mp3/aac/flac/alac/wav） |
+| `-q, --quality <qlt>` | 音频质量（low/medium/high）       |
+| `-o, --output <path>` | 输出目录（默认：视频所在目录）    |
+| `-h, --help`          | 显示帮助信息                      |
+
+---
+
+### 4️⃣ 文件加密
+
+使用 AES-256-GCM 算法对文件进行加密，生成加密的 JSON 文件。
+
+#### 加密算法
+
+- **算法**：AES-256-GCM（Galois/Counter Mode）
+- **密钥派生**：PBKDF2-SHA256（100,000 次迭代）
+- **初始化向量**：16 字节随机生成
+- **盐值**：32 字节随机生成
+- **认证标签**：GCM 模式自动生成，确保数据完整性
+
+#### 基础用法
+
+```bash
+fkt encrypt <文件路径> [选项]
+```
+
+#### 使用示例
+
+```bash
+# 交互式加密（会提示输入密码）
+fkt encrypt secret.txt
+
+# 命令行指定密码
+fkt encrypt secret.txt -p myPassword123
+
+# 指定输出目录
+fkt encrypt secret.txt -o ./encrypted -p myPassword123
+```
+
+#### 输出格式
+
+生成的加密 JSON 文件格式：
+
+```json
+{
+  "type": "crypto",
+  "algorithm": "aes-256-gcm",
+  "createdAt": "2024-12-16 10:30:45",
+  "file": {
+    "name": "secret.txt",
+    "extension": ".txt",
+    "size": 2048,
+    "iv": "base64_encoded_iv",
+    "authTag": "base64_encoded_auth_tag",
+    "salt": "base64_encoded_salt",
+    "encrypted": "base64_encoded_data"
+  }
+}
+```
+
+#### 安全建议
+
+- ⚠️ **请妥善保管密码**，丢失后无法恢复文件
+- 🔒 密码长度至少 6 位，建议使用强密码
+- 💾 建议备份加密文件到安全位置
+- 🔑 不要在命令行直接暴露密码（使用交互模式）
+
+#### 命令选项
+
+| 选项                   | 描述                             |
+| ---------------------- | -------------------------------- |
+| `-p, --password <pwd>` | 加密密码（建议使用交互模式输入） |
+| `-o, --output <path>`  | 输出目录（默认：当前目录）       |
+| `-h, --help`           | 显示帮助信息                     |
+
+---
+
+### 5️⃣ 文件解密
+
+从加密的 JSON 文件中解密并还原原始文件。
+
+#### 基础用法
+
+```bash
+fkt decrypt <加密JSON文件> [选项]
+```
+
+#### 使用示例
+
+```bash
+# 交互式解密（会提示输入密码）
+fkt decrypt secret.crypto.json
+
+# 命令行指定密码
+fkt decrypt secret.crypto.json -p myPassword123
+
+# 指定输出目录
+fkt decrypt secret.crypto.json -o ./decrypted -p myPassword123
+```
+
+#### 特性
+
+- ✅ 自动验证密码正确性
+- ✅ 验证数据完整性（通过 GCM 认证标签）
+- ✅ 还原原始文件名和扩展名
+- ✅ 密码错误时友好提示
+
+#### 错误处理
+
+如果密码错误，会显示以下提示：
+
+```
+✖ 解密失败：密码错误或文件已损坏
+```
+
+#### 命令选项
+
+| 选项                   | 描述                             |
+| ---------------------- | -------------------------------- |
+| `-p, --password <pwd>` | 解密密码（建议使用交互模式输入） |
+| `-o, --output <path>`  | 输出目录（默认：当前目录）       |
+| `-h, --help`           | 显示帮助信息                     |
+
+---
+
+## 🎮 命令参考
+
+### 全局选项
+
+| 选项            | 别名 | 描述         |
+| --------------- | ---- | ------------ |
+| `--help`        | `-h` | 显示帮助信息 |
+| `--version`     | `-v` | 显示版本号   |
+| `--interactive` | `-i` | 启动交互模式 |
+
+### 命令列表
+
+| 命令                     | 别名  | 描述            |
+| ------------------------ | ----- | --------------- |
+| `base64 <input>`         | -     | 文件转 Base64   |
+| `restore <input>`        | -     | Base64 还原文件 |
+| `video-to-audio <input>` | `v2a` | 视频提取音频    |
+| `encrypt <input>`        | -     | 文件加密        |
+| `decrypt <input>`        | -     | 文件解密        |
+
+---
+
+## 🎯 使用场景
+
+### 场景 1：文件分享与存储
+
+**问题**：需要将二进制文件转换为文本格式，便于在 API 或数据库中存储和传输。
+
+**解决方案**：
+
+```bash
+# 转换为 Base64
+fkt base64 document.pdf -o ./archive
+
+# 通过 API 传输或存储到数据库
+# ...
+
+# 需要时还原
+fkt restore ./archive/document.json -o ./restored
+```
+
+---
+
+### 场景 2：敏感文件加密存储
+
+**问题**：需要安全存储敏感文件，如合同、身份证件等。
+
+**解决方案**：
+
+```bash
+# 加密文件
+fkt encrypt contract.pdf -o ./encrypted
+
+# 安全传输或备份加密文件
+# ...
+
+# 需要时解密
+fkt decrypt ./encrypted/contract.crypto.json -o ./restored
+```
+
+---
+
+### 场景 3：视频素材音频提取
+
+**问题**：从视频素材中提取音频用于后期制作或音乐收藏。
+
+**解决方案**：
+
+```bash
+# 提取高质量 MP3（日常使用）
+fkt v2a interview.mp4 -f mp3 -q high -o ./audio
+
+# 提取无损 FLAC（专业编辑）
+fkt v2a concert.mp4 -f flac -q high -o ./audio
+
+# Apple 设备使用 ALAC
+fkt v2a music_video.mp4 -f alac -q high -o ./audio
+```
+
+---
+
+### 场景 4：自动化工作流
+
+**问题**：需要批量处理多个文件。
+
+**解决方案**：
+
+```bash
+# 批量加密
+for file in *.txt; do
+  fkt encrypt "$file" -p myPassword123 -o ./encrypted
+done
+
+# 批量转换视频
+for video in *.mp4; do
+  fkt v2a "$video" -f mp3 -q high -o ./audio
+done
+```
+
+---
+
+## 📊 架构设计
+
+```
+┌─────────────────────────────────────┐
+│         CLI 层 (cli.ts)             │  ← Citty 命令行解析
+├─────────────────────────────────────┤
+│       Config 层 (config/)           │  ← 配置管理
+│  • defaults.ts                      │     - CLI 默认配置
+│  • audio-formats.ts                 │     - 音频格式配置
+│  • crypto-algorithm.ts              │     - 加密算法配置
+├─────────────────────────────────────┤
+│      Commands 层 (commands/)        │  ← 命令处理
+│  • base64.ts                        │     - Base64 转换命令
+│  • restore.ts                       │     - Base64 还原命令
+│  • video-to-audio.ts                │     - 视频转音频命令
+│  • encrypt.ts                       │     - 文件加密命令
+│  • decrypt.ts                       │     - 文件解密命令
+├─────────────────────────────────────┤
+│        Core 层 (core/)              │  ← 核心业务逻辑
+│  • base64.ts                        │     - Base64 编解码
+│  • crypto.ts                        │     - 加密解密算法
+│  • extract.ts                       │     - 视频音频提取
+├─────────────────────────────────────┤
+│       Utils 层 (utils/)             │  ← 通用工具函数
+│  • errors.ts                        │     - 错误处理
+│  • helpers.ts                       │     - 命令助手
+│  • file.ts                          │     - 文件操作
+│  • logger.ts                        │     - 日志输出
+│  • prompts.ts                       │     - 交互提示
+│  • time.ts                          │     - 时间格式化
+└─────────────────────────────────────┘
+```
+
+---
+
+## 🛠️ 技术栈
+
+| 技术               | 描述                    | 用途               |
+| ------------------ | ----------------------- | ------------------ |
+| **Citty**          | 现代化命令行框架        | CLI 路由和参数解析 |
+| **Clack Prompts**  | 美观的交互式 CLI 提示库 | 用户交互界面       |
+| **FFmpeg**         | 强大的多媒体处理工具    | 视频音频转换       |
+| **Ansis**          | 轻量级终端颜色库        | 终端输出美化       |
+| **Node.js Crypto** | Node.js 内置加密模块    | AES-256-GCM 加密   |
+
+---
+
+## ⚙️ 配置
+
+### 环境变量
+
+```bash
+# 开启调试模式（显示详细错误堆栈）
+DEBUG=1 fkt base64 file.txt
+
+# 指定 FFmpeg 路径（如果未在 PATH 中）
+FFMPEG_PATH=/usr/local/bin/ffmpeg fkt v2a video.mp4
+```
+
+---
+
+## 🔧 常见问题
+
+### Q1: FFmpeg 相关错误
+
+**错误**：`FFmpeg 未找到` 或 `spawn ffmpeg ENOENT`
+
+**解决方案**：
+
+```bash
+npm install @ffmpeg-installer/ffmpeg
+```
+
+---
+
+### Q2: 视频转音频进度卡住
+
+**原因**：视频文件损坏或格式不支持
+
+**解决方案**：
+
+1. 检查视频文件是否完整：
+
+```bash
+ffmpeg -i video.mp4
+```
+
+2. 尝试使用其他格式：
+
+```bash
+fkt v2a video.mp4 -f mp3
+```
+
+3. 检查文件权限：
+
+```bash
+ls -la video.mp4
+```
+
+---
+
+### Q3: Base64 文件过大
+
+**原因**：Base64 编码会增加约 33% 的体积
+
+**建议**：
+
+- 对于大文件（>10MB），考虑先压缩再编码
+- Base64 更适合小型文件或需要文本传输的场景
+- 对于大型文件，建议使用加密功能而非 Base64
+
+---
+
+### Q4: 加密/解密失败
+
+**问题**：密码错误或文件损坏
+
+**解决方案**：
+
+```bash
+# 确保密码正确（区分大小写）
+fkt decrypt file.crypto.json -p correctPassword
+
+# 检查 JSON 文件完整性
+cat file.crypto.json | jq
+
+# 验证文件类型
+fkt decrypt file.crypto.json  # 使用交互模式
+```
+
+---
+
+### Q5: 权限错误
+
+**错误**：`EACCES: permission denied`
+
+**解决方案**：
+
+```bash
+# 检查文件权限
+ls -la file.txt
+
+# 修改权限
+chmod 644 file.txt
+
+# 检查目录权限
+chmod 755 ./output
+```
+
+---
+
+### Q6: 内存不足（大文件处理）
+
+**问题**：处理大文件时内存溢出
+
+**解决方案**：
+
+```bash
+# 增加 Node.js 内存限制
+NODE_OPTIONS="--max-old-space-size=4096" fkt base64 large-file.zip
+```
+
+---
+
+## 📝 开发
+
+### 本地开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/coderking3/file-kit.git
+cd file-kit
+
+# 安装依赖
+pnpm install
+
+# 开发模式运行
+pnpm dev base64 test.txt
+
+# 类型检查
+pnpm typecheck
+
+# 代码格式化
+pnpm format
+
+# 代码检查
+pnpm lint
+
+# 构建
+pnpm build
+```
+
+### 项目结构
+
+```
+file-kit/
+├── src/
+│   ├── cli.ts              # CLI 入口
+│   ├── config/             # 配置层
+│   │   ├── defaults.ts
+│   │   ├── audio-formats.ts
+│   │   └── crypto-algorithm.ts
+│   ├── commands/           # 命令层
+│   │   ├── index.ts
+│   │   ├── base64.ts
+│   │   ├── restore.ts
+│   │   ├── video-to-audio.ts
+│   │   ├── encrypt.ts
+│   │   └── decrypt.ts
+│   ├── core/               # 核心逻辑层
+│   │   ├── base64.ts
+│   │   ├── crypto.ts
+│   │   └── extract.ts
+│   ├── utils/              # 工具函数层
+│   │   ├── errors.ts
+│   │   ├── file.ts
+│   │   ├── helpers.ts
+│   │   ├── logger.ts
+│   │   ├── prompts.ts
+│   │   └── time.ts
+│   └── types/              # 类型定义
+│       └── index.ts
+├── bin/
+│   └── cli.mjs             # 可执行文件
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### 发布流程
+
+```bash
+# 更新版本号
+pnpm release
+
+# 构建并发布
+pnpm build
+pnpm publish
+```
+
+---
+
+## 🤝 贡献
+
+欢迎贡献代码！请遵循以下步骤：
+
+1. Fork 本仓库
+2. 创建特性分支（`git checkout -b feature/AmazingFeature`）
+3. 提交更改（`git commit -m 'Add some AmazingFeature'`）
+4. 推送到分支（`git push origin feature/AmazingFeature`）
+5. 开启 Pull Request
+
+### 贡献指南
+
+- 遵循现有代码风格
+- 添加适当的测试
+- 更新相关文档
+- 确保所有测试通过
+
+---
+
+## 📄 许可证
+
+[MIT License](LICENSE) © 2024 King3
+
+---
+
+## 🔗 相关链接
+
+- 📦 [NPM 包](https://www.npmjs.com/package/@king-3/file-kit)
+- 🐙 [GitHub 仓库](https://github.com/coderking3/file-kit)
+- 🐛 [问题反馈](https://github.com/coderking3/file-kit/issues)
+- 📋 [更新日志](https://github.com/coderking3/file-kit/releases)
+
+---
+
+## 💬 联系方式
+
+- **作者**：King3
+- **邮箱**：king3.wm@gmail.com
+- **问题反馈**：[GitHub Issues](https://github.com/coderking3/file-kit/issues)