npm package: @king-3/file-kit
Description: 多功能文件工具箱（Base64 转换 · 视频转音频 · 加密/解密）
Author: king3
Latest version: 1.4.1

# @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)