# 123云盘 (123 Cloud Drive) CLI

> 🚀 123云盘开放平台 API 命令行工具 v1.3.0

一站式管理 123 云盘：文件管理、上传下载、分享链接、离线下载、直链、图床、视频转码、专业/标准双空间配额报告。纯 Python 标准库实现，零依赖（**Excel 导出也不需要 openpyxl**）。

---

## 📋 功能一览

| 分类 | 功能 |
|------|------|
| 📁 文件管理 | 浏览、创建目录、重命名、移动、复制、回收站、下载 |
| 🔎 递归搜索 | 跨文件夹深度搜索文件名，支持自定义搜索深度 |
| ⬆️ 上传 | V2 分片上传（>100MB 自动分片）、单步上传、**秒传检测** |
| 🔗 分享 | 普通分享 / 付费分享 / **批量创建**，支持密码、有效期、流量控制 |
| 📊 分享统计 | 一键查看分享总数、预览/下载/转存次数、流量 Top N |
| 📄 分享导出 | 批量创建分享，超过 10 个链接自动生成**三列 Excel**（文件名称 / 链接 / 路径） |
| 🗑️ 分享管理 | 批量删除分享链接 / 断点续跑 |
| 📥 离线下载 | HTTP / FTP / 磁力链接离线下载 |
| 🌐 直链 | 启用直链、**短直链生成**、IP 白名单、缓存刷新、流量日志 |
| 🖼️ 图床 | 图片存储、移动、复制、离线迁移 |
| 🎬 视频转码 | 多分辨率转码、MP4/M3U8 下载 |
| 🔒 保险箱 | 解锁保险箱 |
| ⚙️ 配置管理 | 配置查看、**Token 有效性验证** |
| 🌲 目录树 | 文件夹树形结构展示 |
| ⬇️ 批量下载 | 多文件并行下载 |
| 📊 存储分析 | 按文件夹统计空间占用 |
| 📤 分享导出 | 分享链接批量导出 Excel |
| 🔄 配置迁移 | 配置导入/导出 |
| 💾 空间报告 | 专业空间 / 标准空间**双配额**明细、使用率预警、清理倒计时 |

---

## 🧮 空间规则：专业空间 / 标准空间

官方 2026-09-24 公告后，账号空间拆分为**两套独立配额**：

| 空间 | 存放内容 | 超额后果 |
|------|----------|----------|
| **专业空间** | 本人持有的文件、≥10GB 文件、直链文件、转码文件、图床文件 | 阻断开放平台的**上传 / 离线下载 / 转码** |
| **标准空间** | 转存的文件（<10GB）；重复文件与回收站文件不计入 | 同样阻断上传 |

```bash
python3 scripts/123yunpan.py space
```

- 使用率 ≥ 90% → 红色预警
- 专业空间剩余天数 > 0 → 打印清理倒计时（超出后配额不可恢复）
- `config check` 与 `upload` 执行前自动预检，专业空间已满会直接给出阻断提示

---

## 🚀 快速开始

### 1. 获取凭证

1. 访问 [123pan.com/member](https://www.123pan.com/member) 购买**开发者权益包**
2. 通过站内信获取 `client_id` 和 `client_secret`

### 2. 配置

```bash
# 一键配置（推荐）
python3 scripts/123yunpan.py setup --client-id YOUR_ID --client-secret YOUR_SECRET

# 验证配置是否有效
python3 scripts/123yunpan.py config check
```

输出示例：
```
🔍 正在验证配置...
  ✅ Client ID:    已配置
  ✅ Client Secret: 已配置
  ✅ Access Token: 已配置

✅ Token 有效！
{
  "用户ID": 1812749510,
  "昵称": "暖心向阳335",
  "VIP": "是",
  "总容量": "21.56 TB",
  "已用": "859.33 GB"
}
```

---

## 📖 完整命令参考

### 文件管理

```bash
# 浏览文件夹
python3 scripts/123yunpan.py file list --parent-id 0 --limit 100

# 只看回收站中的文件
python3 scripts/123yunpan.py file list --parent-id 0 --trashed

# 同时显示回收站文件（带 🗑️ 标记）
python3 scripts/123yunpan.py file list --parent-id 0 --show-trashed

# 跨文件夹递归搜索（最大深度 5 层）
python3 scripts/123yunpan.py file search "Photoshop" --parent-id 27172609 --max-depth 3

# 存储报告（按文件夹统计空间占用）
python3 scripts/123yunpan.py file storage-report --parent-id 0

# 获取文件详情
python3 scripts/123yunpan.py file detail --file-id 12345

# 批量获取文件详情
python3 scripts/123yunpan.py file details-multi --file-ids "123,456,789"

# 创建文件夹
python3 scripts/123yunpan.py file mkdir --name "新文件夹" --parent-id 0

# 目录树展示
python3 scripts/123yunpan.py file tree --parent-id 0

# 重命名
python3 scripts/123yunpan.py file rename --file-id 12345 --new-name "新名称.txt"

# 批量重命名
python3 scripts/123yunpan.py file rename-batch --file-ids 123 456 --new-names "a.txt" "b.txt"

# 移动文件
python3 scripts/123yunpan.py file move --file-ids "123,456" --target-parent-id 0

# 复制文件
python3 scripts/123yunpan.py file copy --file-id 12345 --target-parent-id 0

# 移入回收站
python3 scripts/123yunpan.py file trash --file-ids "123,456"

# 从回收站恢复
python3 scripts/123yunpan.py file recover --file-ids "123,456"

# 下载文件
python3 scripts/123yunpan.py file download --file-id 12345 --output /path/to/save

# 批量下载文件
python3 scripts/123yunpan.py file download-batch --file-ids "123,456,789" --output /path/to/save
```

### 上传

```bash
# 上传文件（自动选择单次/分片上传，自动检测秒传）
python3 scripts/123yunpan.py upload --file /path/to/file.txt --parent-id 0

# 上传并指定文件名
python3 scripts/123yunpan.py upload --file /path/to/file.txt --parent-id 0 --filename "自定义名.zip"

# 重复文件处理：1=重命名 2=覆盖（默认不传=覆盖）
python3 scripts/123yunpan.py upload --file /path/to/file.txt --parent-id 0 --duplicate 2
```

秒传时会显示：`⚡ 秒传成功！文件已存在，跳过上传 (fileID: 12345)`

### 分享管理

```bash
# 创建单个分享
python3 scripts/123yunpan.py share create --name "分享名" --file-ids "123,456" --expire 0

# 分享导出（批量导出分享链接到 Excel）
python3 scripts/123yunpan.py share export --output shares.xlsx

# ⭐ 查看空间占用（专业空间 / 标准空间）
python3 scripts/123yunpan.py space

# ⭐ 批量创建分享（递归遍历文件夹，导出 Excel）
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 --expire 0 -o result.xlsx

# 批量创建分享（导出 JSON）
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 -o result.json

# 超过 10 个链接自动生成 Excel；可用以下参数调整
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 --excel-threshold 50
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 --no-excel
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 --resume   # 断点续跑

# 列出分享
python3 scripts/123yunpan.py share list --limit 10
python3 scripts/123yunpan.py share list --all-pages

# ⭐ 分享统计（查看下载量 Top N）
python3 scripts/123yunpan.py share stats --top 10

# 更新分享设置
python3 scripts/123yunpan.py share update --share-ids "1,2" --traffic-switch 2

# 批量删除分享
python3 scripts/123yunpan.py share delete-batch --share-ids "1,2,3"

# 删除所有分享（跳过确认）
python3 scripts/123yunpan.py share delete-batch --all -y

# 创建付费分享
python3 scripts/123yunpan.py share pay-create --name "付费资源" --file-ids "123,456" --amount 10

# 列出付费分享
python3 scripts/123yunpan.py share pay-list --limit 10
```

### 直链管理

```bash
# 启用文件直链
python3 scripts/123yunpan.py direct-link enable --file-id 12345

# 获取完整直链
python3 scripts/123yunpan.py direct-link url --file-id 12345

# ⭐ 生成短直链（更隐私，不暴露文件名）
python3 scripts/123yunpan.py direct-link short-url --file-id 12345
# 输出: https://1812749510.v.123pan.cn/1812749510/12345

# 刷新直链缓存
python3 scripts/123yunpan.py direct-link cache-refresh --file-id 12345

# 禁用直链
python3 scripts/123yunpan.py direct-link disable --file-id 12345

# IP 白名单管理
python3 scripts/123yunpan.py direct-link ip-list
python3 scripts/123yunpan.py direct-link ip-switch --switch 1
python3 scripts/123yunpan.py direct-link ip-update --ips "1.1.1.1" "2.2.2.2"

# 流量日志
python3 scripts/123yunpan.py direct-link traffic-logs --file-id 12345
```

### 离线下载

```bash
# 创建离线下载任务
python3 scripts/123yunpan.py offline create --url "https://example.com/file.zip" --parent-id 0

# 查询下载进度
python3 scripts/123yunpan.py offline progress --task-id abc123
```

### 图床 (OSS)

```bash
python3 scripts/123yunpan.py oss list --parent-id 0 --limit 100
python3 scripts/123yunpan.py oss detail --file-id 12345
python3 scripts/123yunpan.py oss delete --file-id 12345
python3 scripts/123yunpan.py oss move --file-id 12345 --target-parent-id 0
python3 scripts/123yunpan.py oss copy --file-ids "123,456" --target-parent-id 0
```

### 视频转码

```bash
python3 scripts/123yunpan.py transcode list --parent-file-id 0 --limit 100
python3 scripts/123yunpan.py transcode resolutions --file-id 12345
python3 scripts/123yunpan.py transcode transcode --file-id 12345 --resolution 1080p
python3 scripts/123yunpan.py transcode download --file-id 12345 --output /path/
python3 scripts/123yunpan.py transcode download-m3u8 --file-id 12345 --output /path/
```

### 其他

```bash
# 查看配置
python3 scripts/123yunpan.py config

# 验证配置有效性
python3 scripts/123yunpan.py config check

# 配置导出
python3 scripts/123yunpan.py config export --output config.json

# 配置导入
python3 scripts/123yunpan.py config import --file config.json

# 获取用户信息
python3 scripts/123yunpan.py user-info

# 解锁保险箱
python3 scripts/123yunpan.py safebox unlock --password "your_password"

# ⭐ 空间占用报告（专业空间 + 标准空间）
python3 scripts/123yunpan.py space
```

---

## 📄 分享 Excel 列结构

`share create-batch` 在**有效链接数 > 10** 时自动生成 Excel，固定三列：

| 列名 | 说明 | 示例 |
|------|------|------|
| **文件名称** | 去分类前缀、去扩展名 | `Cinema 4D R20` |
| **链接** | 分享/直链 URL，可点击超链接 | `https://www.123pan.com/s/JyAKVv-o6bI` |
| **路径** | 云盘内完整相对路径（含文件名） | `软件/office/离线安装包/2021/ProPlus2021Retail.img` |

名称解析规则：`Cinema 4D/Cinema 4D R20.zip` → 名称 `Cinema 4D R20`、路径 `Cinema 4D/Cinema 4D R20.zip`。

> xlsx 由 `zipfile` + 手写 OOXML 生成，**不需要安装 openpyxl**。

---

## ⚡ 限流保护

CLI 内置端点级 QPS 表，自动限速，无需手动 `sleep`：

| 端点 | QPS |
|------|-----|
| `/api/v2/file/list` | **1.5**（最严格） |
| `/api/v1/user/info` | 10 |
| `/api/v1/access_token` | 10 |
| `/api/v1/share/create` | 3 |

- **429 / 5xx** → 指数退避重试（最多 4 次）
- **401** → 自动刷新 Token 后重试一次
- 错误码会翻译为「原因 + 处置建议」再打印，不会只丢裸码

---

## ⚠️ 注意事项

| 项目 | 说明 |
|------|------|
| 文件名限制 | 不能包含 `\\\"/:*?|><`，长度 < 256 字符 |
| 上传限制 | 单文件最大 10GB（API 限制） |
| 分享有效期 | 仅支持 0（永久）/ 1 / 7 / 30 天 |
| 分享名称长度 | 付费分享要求 < 35 字符，CLI 自动截断 |
| 多 ID 写法 | `--file-ids` / `--share-ids` 只接受一个值，多个 ID 要写成 `--file-ids "1,2,3"` |
| `--json` 位置 | 全局选项，必须写在子命令之前（`--json config check`） |
| transcode 参数 | 用 `--parent-file-id`，与 file 系列的 `--parent-id` 不同 |
| 空间双配额 | **专业空间 / 标准空间独立**，任一超额都阻断上传，先看 `space` |
| 审核驳回文件 | `status > 100` 无法分享，批量分享时自动剔除 |
| Token 刷新 | 过期时自动刷新，无需手动处理 |
| `fileIDList` 格式 | 必须是逗号分隔的**字符串**（`"123,456"`），不是数组 |
| 分享链接格式 | `https://www.123pan.com/s/{shareKey}` |
| 回收站 | v2 API 默认包含回收站文件，用 `--trashed` / `--show-trashed` 过滤 |
| Excel 阈值 | 默认超过 **10** 个链接自动生成，可用 `--excel-threshold` / `--no-excel` 调整 |
| `--no-color` | 禁用彩色输出，适用于日志记录和管道操作 |
| `--json` | 所有命令支持 `--json` 输出 JSON 格式，便于脚本解析 |

---

## 📁 文件结构

```
123yunpan/
├── SKILL.md                         # AI 技能文档（完整 API 参考，含 Changelog）
├── README.md                        # 用户文档（本文件）
├── manifest.json                    # 技能清单（命令 / 参数 / 输出字段契约）
├── scripts/
│   └── 123yunpan.py                 # CLI 主程序（纯 Python 标准库）
└── references/
    ├── bulk-operations.md           # 批量操作指南
    └── competitor-upload-patterns.md # 上传模式参考
```

---

## 📚 相关链接

- [123云盘开放平台文档](https://123yunpan.yuque.com/org-wiki-123yunpan-muaork/cr6ced)
- [123云盘官网](https://www.123pan.com)