内容
# 🛠️ 工具列表
个人一体化 **CLI** 和 **MCP 服务器**，用于日常生产力 — 媒体处理、文档转换、PDF 工具和 GitHub 仓库管理。编译为单个独立的 `agent-tools.exe` 可执行文件。
> **v2.0** — 现已包含文档工具、PDF 搜索、交互式 GitHub 仓库清理 TUI 和代码库打包工具。
---
## 📋 目录
- [安装](#安装)
- [构建二进制文件](#构建二进制文件)
- [CLI 使用](#cli-使用)
- [PDF 工具](#pdf-工具)
- [文档工具](#文档工具)
- [视频工具](#视频工具)
- [音频工具](#音频工具)
- [转换工具](#转换工具)
- [Git / GitHub 工具](#git--github-工具)
- [MCP 服务器使用](#mcp-服务器使用)
- [开发](#开发)
---
## 安装
### 前提条件
- [Node.js](https://nodejs.org/) v22+
- [FFmpeg](https://ffmpeg.org/) 在您的 `PATH` 中（用于视频/音频工具）
- [Microsoft Edge](https://www.microsoft.com/edge) （用于 `doc md-to-pdf`）
- [GitHub CLI (`gh`)](https://cli.github.com/) 已认证（用于 `git` 命令）
### 设置
```bash
git clone https://github.com/riteshrajas/agent-tools
cd agent-tools
npm install
```
---
## 构建二进制文件
```bash
# 步骤 1：将 TypeScript 捆绑为单个 CJS 文件
npm run bundle
# 步骤 2：打包为独立的 .exe 文件
npx @yao-pkg/pkg . --targets node22-win-x64 --output agent-tools.exe
```
> `.exe` 文件大小约为 124 MB（包含 Node.js 运行时），并被 gitignore。每次更改后请在本地重新构建。
---
## CLI 使用
```
agent-tools <组> <子命令> [参数] [选项]
```
### PDF 工具
```bash
# 合并多个 PDF 文件为一个
agent-tools pdf merge output.pdf file1.pdf file2.pdf file3.pdf
# 将 PDF 文件拆分为单个页面（可选提取特定页面/范围）
agent-tools pdf split input.pdf ./output_dir
agent-tools pdf split input.pdf ./output_dir --pages 1-3,5,7
# 旋转页面（90、180 或 270 度）
agent-tools pdf rotate input.pdf output.pdf 90
agent-tools pdf rotate input.pdf output.pdf 180 --pages 1,3
# 在 PDF 中搜索文本
agent-tools pdf search report.pdf "季度收入"
```
---
### 文档工具
```bash
# 将 Markdown 文件转换为样式化的 PDF（需要 Microsoft Edge）
agent-tools doc md-to-pdf README.md README.pdf
# 从 PowerPoint 演示文稿中提取所有文本（按幻灯片）
agent-tools doc read-pptx presentation.pptx
agent-tools doc read-pptx presentation.pptx --output extracted.txt
# 从 Word 文档中提取所有段落
agent-tools doc read-docx report.docx
agent-tools doc read-docx report.docx --output extracted.txt
```
---
### 视频工具
```bash
# 修剪视频（开始时间 + 可选持续时间）
agent-tools video trim input.mp4 output.mp4 00:01:30
agent-tools video trim input.mp4 output.mp4 00:01:30 -t 00:00:45
# 合并多个视频为一个
agent-tools video merge output.mp4 clip1.mp4 clip2.mp4 clip3.mp4
# 更改播放速度（1.5 = 50% 更快，0.5 = 半速）
agent-tools video speed input.mp4 output.mp4 1.5
# 更改音频音量（2.0 = 双倍，0.5 = 半速）
agent-tools video volume input.mp4 output.mp4 2.0
```
---
### 音频工具
```bash
# 修剪音频文件
agent-tools audio trim input.mp3 output.mp3 00:00:30
agent-tools audio trim input.mp3 output.mp3 00:00:30 -t 00:01:00
# 合并多个音频文件
agent-tools audio merge output.mp3 track1.mp3 track2.mp3
# 更改播放速度
agent-tools audio speed input.mp3 output.mp3 1.25
# 更改音量
agent-tools audio volume input.mp3 output.mp3 1.5
# 反转音频轨道
agent-tools audio reverse input.mp3 output.mp3
```
---
### 转换工具
```bash
# 转换图像格式，可选调整大小和质量
agent-tools convert image input.png output.jpg
agent-tools convert image input.png output.webp --width 1920 --height 1080 --quality 85
# 转换音频格式
agent-tools convert audio input.wav output.mp3
agent-tools convert audio input.flac output.ogg
# 转换视频格式
agent-tools convert video input.mov output.mp4
agent-tools convert video input.mkv output.webm
```
---
### Git / GitHub 工具
```bash
# 交互式 TUI — 审查所有仓库，标记为保留 / 存档 / 删除
# 使用箭头键导航，空格键循环操作，Enter 键确认，Esc 键退出
agent-tools git clean-repos
# 以 JSON 格式列出所有仓库（可选按名称过滤）
agent-tools git list-repos
agent-tools git list-repos --filter "old-project"
# 将整个代码库打包为单个 Markdown 文件（适用于 LLM 上下文）
agent-tools git bundle ./my-project bundle.md
agent-tools git bundle ./my-project bundle.md --ext .ts,.py,.md
agent-tools git bundle ./my-project bundle.md --max-size 102400
```
#### `git clean-repos` TUI 控制
| 键 | 操作 |
|-----|--------|
| `↑` / `↓` | 导航列表 |
| `Space` | 循环： `[ 保留 ]` → `[存档]` → `[删除 ]` |
| `Enter` | 继续审查并确认 |
| `Esc` / `q` | 退出且不更改 |
TUI 自动检测合理的默认值（旧 fork > 90 天 → 删除，180 天内未更新的仓库 → 存档，列入白名单的重要仓库 → 保留）。
---
## MCP 服务器使用
启动 MCP 服务器（通过 stdio 通信）：
```bash
agent-tools mcp
# 或通过 node
node dist/index.cjs mcp
```
### 使用 Antigravity / Claude Desktop 进行配置
添加到您的 MCP 配置文件（例如 `C:\Users\<you>\.gemini\config\mcp.json`）：
```json
{
"mcpServers": {
"agent-tools": {
"command": "P:\\Data\\Personal\\agent-tools\\agent-tools.exe",
"args": ["mcp"]
}
}
}
```
### 可用的 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `pdf_merge` | 合并多个 PDF 文件 |
| `pdf_split` | 拆分或提取 PDF 文件的页面 |
| `pdf_rotate` | 旋转 PDF 文件的页面 |
| `pdf_search` | 在 PDF 文件中搜索文本，返回匹配的页面 |
| `markdown_to_pdf` | 将 Markdown 转换为样式化的 PDF 文件 |
| `read_pptx` | 从 PowerPoint (.pptx) 中提取文本 |
| `read_docx` | 从 Word 文档 (.docx) 中提取文本 |
| `video_trim` | 修剪视频 |
| `video_merge` | 合并多个视频 |
| `video_speed` | 更改视频速度 |
| `video_volume` | 更改视频音量 |
| `audio_trim` | 修剪音频文件 |
| `audio_merge` | 合并音频文件 |
| `audio_speed` | 更改音频速度 |
| `audio_volume` | 更改音频音量 |
| `audio_reverse` | 反转音频轨道 |
| `convert_image` | 转换和调整图像大小 |
| `convert_audio` | 转换音频格式 |
| `convert_video` | 转换视频格式 |
| `github_list_repos` | 列出 GitHub 仓库（可选过滤） |
| `github_batch_clean` | 存档/删除 GitHub 仓库列表 |
| `bundle_codebase` | 将目录打包为单个 Markdown 文件 |
---
## 开发
```bash
# 监视模式（tsc）
npm run dev
# 打包（esbuild → dist/index.cjs）
npm run bundle
# 重建 .exe 文件
npx @yao-pkg/pkg . --targets node22-win-x64 --output agent-tools.exe
```
### 项目结构
```
src/
├── index.ts # 入口点 — 路由到 CLI 或 MCP
├── cli.ts # Commander CLI 定义
├── mcp-server.ts # MCP 服务器和工具模式
└── tools/
├── pdf.ts # PDF 合并/拆分/旋转（pdf-lib）
├── doc.ts # Markdown→PDF，PPTX/DOCX 读取器，PDF 搜索
├── video.ts # FFmpeg 视频工具
├── audio.ts # FFmpeg 音频工具
├── converter.ts # sharp + FFmpeg 转换器
└── git.ts # GitHub TUI 清理器 + 代码库打包器
```
---
许可证：MIT
