nxxy335/Skill-123yunpan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0ecfa6de09769cbf3058d85a3fd5e6f58c6c7ea
Skill-123yunpan/README.md
T
nxxy335 f0ecfa6de0 chore: 初始化 123yunpan skill 仓库 (v1.3.0) 
- 完整 skill 本体：SKILL.md / README.md / manifest.json / config.json
- scripts/123yunpan.py：零依赖 CLI（含空间双配额、QPS 限流、零依赖 XLSX）
- references/ 参考资料
- 排除 .workbuddy/ 开发目录与 __pycache__
2026-09-27 22:41:43 +08:00

369 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
Reference in New Issue View Git Blame Copy Permalink