Skill-123yunpan/README.md

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）；重复文件与回收站文件不计入	同样阻断上传

python3 scripts/123yunpan.py space

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

---

🚀 快速开始

1. 获取凭证

1. 访问 123pan.com/member 购买开发者权益包
2. 通过站内信获取 client_id 和 client_secret

2. 配置

# 一键配置（推荐）
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"
}

---

📖 完整命令参考

文件管理

# 浏览文件夹
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

上传

# 上传文件（自动选择单次/分片上传，自动检测秒传）
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)

分享管理

# 创建单个分享
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

直链管理

# 启用文件直链
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

离线下载

# 创建离线下载任务
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)

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

视频转码

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/

其他

# 查看配置
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 后重试一次
• 错误码会翻译为「原因 + 处置建议」再打印，不会只丢裸码

---

⚠️ 注意事项

项目	说明
文件名限制	不能包含 `\"/:*?
上传限制	单文件最大 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云盘开放平台文档
• 123云盘官网