内容
<p align="right">
<a href="./README_cn-ZH.md">中文</a> | <strong>English</strong>
</p>
# pikpakdriver
> 一个基于 Go 的 CLI 和 MCP Server，用于 [PikPak](https://mypikpak.com/) 云存储服务，独立于基于 Rust 的 [`pikpaktui`](https://github.com/niuhuan/pikpak-tui) 项目。
[](https://golang.org)
[](LICENSE)
---
## 功能特点
- **CLI 客户端** (`pikpakdriver`) — 19 个命令涵盖所有 PikPak 操作
- **MCP 服务器** (`pikpakdriver-mcp`) — 28 个 MCP 工具用于 AI 代理集成（Hermes、Claude 等）
- **完整的 API 支持** — 文件、回收站、离线下载、分享链接、事件、账户
- **代理支持** — CLI 参数和配置文件；优先级：`--proxy` > `config.json` > 无代理
- **自动登录** — 凭证保存在 `config.json` 中，会话自动刷新
- **独立性** — 自己的配置文件和会话存放在 `~/.config/pikpakdriver/`，不依赖 `pikpaktui`
---
## 快速开始
### 1. 安装
```bash
# 下载二进制文件（或从源代码编译）
# 预编译的二进制文件可以在 Releases 页面找到
# 或从源代码编译：
git clone https://github.com/suntao12138/pikpakdriver.git
cd pikpakdriver
go build -o pikpakdriver-mcp ./mcp/ # MCP 服务器
go build -o pikpakdriver ./cli/ # CLI 客户端
```
### 2. 登录（一次性）
> ⚠️ PikPak 阻止中国大陆 IP 地址访问。如有需要，请使用 `--proxy` 参数。
```bash
# 使用代理登录（推荐中国用户使用）
./pikpakdriver login --email your@email.com --password yourpass --proxy http://127.0.0.1:7890
# 验证
./pikpakdriver --proxy http://127.0.0.1:7890 whoami
```
凭证和会话保存在 `~/.config/pikpakdriver/` 中。后续运行无需重复登录。
### 3. 部署到 PATH
```bash
mv pikpakdriver-mcp ~/.local/bin/
mv pikpakdriver ~/.local/bin/
```
---
## CLI 使用
### 账户
```bash
pikpakdriver whoami # 账户信息（存储空间、VIP）
pikpakdriver login # 使用邮箱和密码登录
```
### 文件操作
```bash
pikpakdriver ls [parent_id] # 列出文件
pikpakdriver info <file_id> # 文件详情
pikpakdriver mkdir <parent_id> <name> # 创建文件夹
pikpakdriver rename <id> <new_name> # 重命名
pikpakdriver mv <id> <target_id> # 移动
pikpakdriver cp <id> <target_id> # 复制
pikpakdriver rm <id...> # 移到回收站（使用 -P 为永久删除）
pikpakdriver link <file_id> # 获取下载链接
```
### 星标
```bash
pikpakdriver star <id...> # 星标文件
pikpakdriver unstar <id...> # 取消星标
pikpakdriver starred [limit] # 列出星标文件
```
### 回收站
```bash
pikpakdriver trash ls # 列出回收站文件
pikpakdriver trash restore <id...> # 从回收站恢复
pikpakdriver trash empty # 清空回收站
```
### 离线下载
```bash
pikpakdriver offline add <magnet|url> # 添加离线下载任务
pikpakdriver offline ls # 列出任务
pikpakdriver offline info <task_id> # 任务详情
pikpakdriver offline rm <task_id> # 删除任务
pikpakdriver offline retry <task_id> # 重试失败任务
```
### 分享链接
```bash
pikpakdriver share create <file_id...> # 创建分享链接
pikpakdriver share ls # 列出分享链接
pikpakdriver share rm <share_id...> # 删除分享链接
pikpakdriver share info <share_id> # 获取分享链接信息
pikpakdriver share save <share_id> <to> # 保存分享的文件
```
### 事件和版本
```bash
pikpakdriver events [limit] # 最近的文件事件
pikpakdriver version # 版本信息
```
### 全局参数
| 参数 | 描述 |
|------|-------------|
| `--proxy <url>` | HTTP 代理（例如 `http://127.0.0.1:7890`） |
| `-j, --json` | JSON 输出格式 |
| `-h, --help` | 帮助 |
---
## MCP 服务器
MCP 服务器提供 28 个工具用于 AI 代理集成。在 Hermes Agent 中配置：
```yaml
# ~/.hermes/config.yaml
mcp_servers:
pikpakdriver:
enabled: true
command: /home/suntao/.local/bin/pikpakdriver-mcp
args: []
```
### 可用工具
| 类别 | 工具 |
|----------|-------|
| **账户** | `getAccountInfo` |
| **文件** | `listFiles` `getFileInfo` `getDownloadLink` `mkdir` `rename` `moveFiles` `copyFiles` `starFiles` `unstarFiles` `listStarred` |
| **回收站** | `trashFiles` `untrashFiles` `listTrash` `emptyTrash` `deleteFiles` |
| **离线下载** | `addOfflineTask` `listOfflineTasks` `getOfflineTask` `deleteOfflineTask` `retryOfflineTask` |
| **分享** | `createShare` `listShares` `deleteShares` `saveShare` `getShareInfo` `shareDetail` |
| **事件** | `listEvents` |
---
## 配置
所有配置文件存放在 `~/.config/pikpakdriver/` 中：
```
~/.config/pikpakdriver/
├── config.json # 邮箱、密码、代理
└── session.json # access_token、refresh_token（自动管理）
```
### 代理优先级
1. `--proxy` CLI 参数（最高）
2. `proxy` 字段在 `config.json` 中
3. 无代理（默认）
---
## 架构
```
pikpakdriver/
├── mcp/main.go # MCP 服务器入口
├── cli/
│ ├── main.go # CLI 入口
│ ├── cmd/ # 19 个子命令（cobra）
│ └── internal/auth/ # 凭证加载
├── mcp/server/
│ ├── server.go # MCP 注册
│ └── tools/ # 28 个 MCP 工具实现
├── pkg/pikpak/
│ ├── models.go # 数据模型（共享）
│ └── client.go # HTTP 客户端（共享）
└── go.mod
```
`pkg/pikpak/` 包在 CLI 和 MCP 服务器之间共享 — 所有 API 调用都通过相同的客户端层。
---
## 开发
```bash
# 先决条件
go 1.23+
# 完整编译
cd ~/Tools_Pro/pikpakdriver
go build -o pikpakdriver-mcp ./mcp/
go build -o pikpakdriver ./cli/
# 运行测试
go test ./pkg/... ./cli/...
```
参见 [TEST_REPORT.md](./TEST_REPORT.md) 以获取完整的工具验证报告。
---
## 相关项目
- [115driver](https://github.com/SheltonZhu/115driver) — 115 云盘 Go SDK/CLI/MCP（本项目的架构参考）
- [pikpaktui](https://github.com/niuhuan/pikpak-tui) — 原始的 Rust TUI 客户端，用于 PikPak（独立）
---
## 许可证
MIT
