123云盘 (123 Cloud Drive) Skill

Agent Quick Start

脚本路径: scripts/123yunpan.py（相对于本 skill 目录）

首次使用: 先跑 config check 确认凭证有效，再操作文件

输出格式: 加 --json 获取单行 JSON，方便解析

文件 ID: 所有操作都基于 file_id（数字），先 file list 或 file search 获取 ID

⚠️ 操作规则:

1. 删除规则: 用户要求删除文件时，必须先向用户展示文件列表（如"删除文件如下：A.txt、B.zip"），确认后再执行删除操作，删除后提醒"如需找回，请前往回收站恢复"
2. 下载规则: 下载完成后告知用户保存位置，如"文件已保存到：/path/to/file.pdf"
3. 分享规则: 分享少于 20 个文件时直接给出链接；超过 20 个时导出 Excel 文件并发送给用户
4. 搜索规则: 用户未给出具体云盘位置只给了文件名，搜索到多个匹配结果时，列出文件让用户选择，不要自行决定
5. 批量规则: 批量操作前先告知用户数量和预计耗时，如"共 150 个文件，预计需要 2 分钟"
6. 上传规则: 用户未指定目标文件夹时，先列出根目录让用户选择上传位置
7. 错误规则: 遇到错误时给出解决方案，不要只报错。如"文件不存在"→提示检查 file_id 是否正确；"分享失败"→提示检查文件是否违规

# 1. 验证配置
python3 scripts/123yunpan.py config check --json

# 2. 查看根目录
python3 scripts/123yunpan.py --json file list --parent-id 0

# 3. 搜索文件
python3 scripts/123yunpan.py --json file search "关键词" --parent-id 0

# 4. 查看目录树（快速了解结构）
python3 scripts/123yunpan.py file tree --parent-id 0 --max-depth 2

Common Workflows

🔍 "帮我找某个文件"

1. file search "关键词" --parent-id 0 --json    → 获取 file_id
2. file detail --file-id {id} --json              → 确认文件信息
3. file download --file-id {id} -o ./             → 下载
4. 告知用户：文件已保存到：./xxx.pdf

🔗 "把这个文件夹分享出去"

1. file tree --parent-id {folder_id} --max-depth 2  → 确认内容
2. 少于 20 个：share create 逐个创建，直接给出链接
3. 超过 20 个：share create-batch --parent-id {folder_id} --expire 0 -o links.xlsx → 导出 Excel

⬆️ "上传文件到云盘"

1. 用户未指定位置 → file list --parent-id 0 --json → 列出根目录让用户选
2. upload --file /path/to/file --parent-id {folder_id}
3. 告知用户：文件已上传到：{folder_id}/xxx.pdf

⬇️ "批量下载这些文件"

1. file search "关键词" --parent-id {root} --json   → 获取 file_id 列表
2. file download-batch --file-ids "id1,id2,id3" -o ./downloads/  → 批量下载

📊 "看看空间占用情况"

1. file storage-report --parent-id 0 --top 10  → 按文件夹分析+大文件排行

🗑️ "删除文件"

1. file list --parent-id {folder_id} --search "关键词" --json  → 找到 file_id
2. 向用户展示将删除的文件列表，格式：删除文件如下：XXX.txt、XXX.zip
3. file trash --file-ids "{id1},{id2}"                          → 移入回收站
4. 提醒用户：如需找回，请前往回收站恢复

> ⚠️ 删除操作必须先向用户展示文件列表，确认后再执行！

🔄 "把配置迁移到另一台机器"

# 机器 A:
config export -o config.json

# 机器 B:
config import --file config.json
config check   → 验证导入成功

Overview

This skill provides a complete CLI wrapper for the 123 Cloud Drive Open Platform API. It covers 70+ API endpoints across authentication, file management, upload, download, sharing, offline download, direct links, image hosting, and video transcoding.

Prerequisites

1. Purchase Developer Access Pack

Visit https://www.123pan.com/member and purchase a developer access pack. You will receive client_id and client_secret via in-app message.

2. Configuration

The skill requires three credentials stored in environment variables:

# Required for API authentication
export TWOPAN_CLIENT_ID="your_client_id_here"
export TWOPAN_CLIENT_SECRET="your_client_secret_here"
export TWOPAN_ACCESS_TOKEN="your_access_token_here"

If these are not set when the skill is first used, the CLI will output a clear reminder:

⚠️  123云盘技能需要配置以下环境变量才能使用：
    export TWOPAN_CLIENT_ID="your_client_id"
    export TWOPAN_CLIENT_SECRET="your_client_secret"
    export TWOPAN_ACCESS_TOKEN="your_access_token"

    获取方式：
    1. 访问 https://www.123pan.com/member 购买开发者权益包
    2. 通过 client_id + client_secret 调用 /api/v1/access_token 获取 access_token
    3. 将三个值设置为环境变量

    或运行: 123yunpan.py setup

3. Interactive Setup (Recommended)

Run 123yunpan.py setup without arguments for interactive credential entry:

$ python3 scripts/123yunpan.py setup
⚠️  未检测到 client_id
   获取方式：访问 https://www.123pan.com/member 购买开发者权益包
请输入 client_id: █
⚠️  未检测到 client_secret
请输入 client_secret: █
正在获取 access_token...
✅ 配置已保存！

If config already exists (from a previous setup or env vars), it skips prompting and uses the existing values. Non-interactive mode also works: setup --client-id ID --client-secret SECRET.

CLI Usage

# === Global Options ===
# Add --no-color to disable colored output, --json to output raw JSON

# Setup / get token
python3 scripts/123yunpan.py setup --client-id YOUR_ID --client-secret YOUR_SECRET

# Check config status
python3 scripts/123yunpan.py config
python3 scripts/123yunpan.py config check     # 验证 token 有效性
python3 scripts/123yunpan.py config export --output config.json
python3 scripts/123yunpan.py config import --file config.json

# === File Management ===
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   # 含回收站
python3 scripts/123yunpan.py file search "Photoshop" --parent-id 27172609 --max-depth 3
python3 scripts/123yunpan.py file tree --parent-id 0 --max-depth 3
python3 scripts/123yunpan.py file storage-report --parent-id 0 --top 10
python3 scripts/123yunpan.py file detail --file-id 12345
python3 scripts/123yunpan.py file details-multi --file-ids "1,2,3"
python3 scripts/123yunpan.py file list --search "keyword"
python3 scripts/123yunpan.py file mkdir --name "New Folder" --parent-id 0
python3 scripts/123yunpan.py file rename --file-id 12345 --new-name "renamed.txt"
python3 scripts/123yunpan.py file rename-batch --file-ids "1,2,3" --new-names "a.txt,b.txt,c.txt"
python3 scripts/123yunpan.py file move --file-ids "1,2,3" --target-parent-id 0
python3 scripts/123yunpan.py file copy --file-id 12345 --target-parent-id 0
python3 scripts/123yunpan.py file copy-batch --file-ids "1,2,3" --target-parent-id 0
python3 scripts/123yunpan.py file copy-progress --task-id abc123
python3 scripts/123yunpan.py file trash --file-ids "12345"
python3 scripts/123yunpan.py file recover --file-id 12345
python3 scripts/123yunpan.py file recover-by-path --file-id 12345 --target-parent-id 0 --filename "restored.txt"
python3 scripts/123yunpan.py file download --file-id 12345 --output /path/to/save
python3 scripts/123yunpan.py file download-batch --file-ids "1,2,3" --output-dir /path/to/save

# === Upload (V2 Recommended) ===
python3 scripts/123yunpan.py upload --file /path/to/file.txt --parent-id 0

# === Share Management ===
python3 scripts/123yunpan.py share create --name "My Share" --file-ids "1,2,3" --expire 7
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 --expire 0 -o result.xlsx
python3 scripts/123yunpan.py share list --limit 10
python3 scripts/123yunpan.py share list --all-pages
python3 scripts/123yunpan.py share stats --top 10
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 update --share-ids "1,2" --traffic-switch 2
python3 scripts/123yunpan.py share export --output shares.xlsx
python3 scripts/123yunpan.py share export --output shares.json --format json
python3 scripts/123yunpan.py share pay-create --name "Paid Share" --file-ids "1,2" --amount 10
python3 scripts/123yunpan.py share pay-list --limit 10
python3 scripts/123yunpan.py share pay-update --share-ids "1" --amount 20

# === Offline Download ===
python3 scripts/123yunpan.py offline create --url "https://example.com/file.zip" --parent-id 0
python3 scripts/123yunpan.py offline progress --task-id abc123
python3 scripts/123yunpan.py offline list

# === User Info ===
python3 scripts/123yunpan.py user-info

# === Direct Link ===
python3 scripts/123yunpan.py direct-link enable --file-id 12345
python3 scripts/123yunpan.py direct-link disable --file-id 12345
python3 scripts/123yunpan.py direct-link url --file-id 12345
python3 scripts/123yunpan.py direct-link short-url --file-id 12345  # 短直链（更隐私）
python3 scripts/123yunpan.py direct-link cache-refresh --file-id 12345
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 offline-logs
python3 scripts/123yunpan.py direct-link traffic-logs

# === Image Hosting (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 "1,2,3" --target-parent-id 0
python3 scripts/123yunpan.py oss copy-process --task-id abc123
python3 scripts/123yunpan.py oss copy-fail --task-id abc123

# === Video Transcode ===
python3 scripts/123yunpan.py transcode list --parent-id 0 --limit 100
python3 scripts/123yunpan.py transcode folder --parent-id 0
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 record --file-id 12345
python3 scripts/123yunpan.py transcode result --file-id 12345
python3 scripts/123yunpan.py transcode delete --file-id 12345
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 transcode download-all --file-id 12345 --output /path/
python3 scripts/123yunpan.py transcode upload-cloud --file-id 12345 --parent-id 0

# === Safebox ===
python3 scripts/123yunpan.py safebox unlock --password "your_password"

# === Cache Management ===
python3 scripts/123yunpan.py cache list           # 列出所有缓存文件
python3 scripts/123yunpan.py cache clear           # 清除全部缓存
python3 scripts/123yunpan.py cache clear --root-id 12345  # 清除指定文件夹的缓存
python3 scripts/123yunpan.py cache info            # 显示缓存目录信息

JSON Output Fields (--json)

加 --json 后所有命令输出单行 JSON，以下是主要命令的字段说明：

file list --json

{"code":0, "data":{"fileList":[
  {"fileId":12345, "filename":"报告.pdf", "size":1048576, "type":0,
   "parentFileID":0, "createAt":"2026-01-01T00:00:00Z", "trashed":0}
], "lastFileId":12345}}

• type: 0=文件, 1=文件夹
• trashed: 0=正常, 1=已删除
• size: 字节数

file detail --json

{"fileId":12345, "filename":"报告.pdf", "size":1048576,
 "md5":"abc123...", "type":0, "parentFileID":0,
 "downloadUrl":"https://...", "createAt":"2026-01-01T00:00:00Z"}

user-info --json

{"uid":1812749510, "nickname":"暖心向阳335",
 "spaceUsed":9223372036854775807, "spacePermanent":9223372036854775807,
 "vip":1}

• spaceUsed/spacePermanent: 字节数，用 human_size() 转换

share create --json

{"code":0, "data":{"shareID":5193007, "shareKey":"JyAKVv-o6bI"},
 "_shareUrl":"https://www.123pan.com/s/JyAKVv-o6bI"}

• _shareUrl 是 CLI 自动拼接的，不是 API 返回的

share list --json

{"code":0, "data":{"shareList":[
  {"shareId":5193007, "shareName":"分享",
   "shareKey":"JyAKVv-o6bI", "shareExpire":7,
   "previewCount":10, "downloadCount":5, "saveCount":2,
   "createAt":"2026-01-01T00:00:00Z"}
], "lastShareId":5193007}}

upload --json

{"code":0, "data":{"fileID":12345, "completed":true, "reuse":false}}

• reuse: true=秒传成功（文件已存在）

通用规则

• 所有 API 返回格式: {"code":0, "message":"ok", "data":{...}}
• code=0 表示成功，非 0 为错误
• file list 和 share list 使用 lastFileId/lastShareId 做游标分页
• 错误时返回: {"code":错误码, "message":"错误描述"}

API Reference Summary

Short Direct Link (短直链)

除了分享链接和完整直链外，还可以生成短直链 — 格式为 https://{user_id}.v.123pan.cn/{user_id}/{file_id}，不暴露文件名，更隐私友好。

生成短直链

# CLI 命令
python3 scripts/123yunpan.py direct-link short-url --file-id 12345

# 输出示例
{
  "short_url": "https://1812749510.v.123pan.cn/1812749510/12345",
  "user_id": 1812749510,
  "file_id": 12345
}

手动拼接（Python）

import base64, json

def get_user_id_from_token(token):
    """从 JWT token 解析 user_id，无需额外 API 调用"""
    parts = token.split(".")
    payload = parts[1] + "=" * (4 - len(parts[1]) % 4)
    return json.loads(base64.b64decode(payload)).get("id", 0)

user_id = get_user_id_from_token(access_token)
short_url = f"https://{user_id}.v.123pan.cn/{user_id}/{file_id}"

三种链接格式对比

> ⚠️ 短直链需要文件已在开启了直链功能的文件夹中，否则无法使用。

Share URL Construction

The share create API returns shareID and shareKey — it does NOT return a full shareUrl. You must construct the URL yourself. The CLI supports two formats via --url-format:

uid 格式自动从 JWT token 解析 user_id，无需额外 API 调用。解析失败时自动回退到 short。

# 默认 short 格式
python3 scripts/123yunpan.py share create --name "分享" --file-ids 123,456 --expire 7

# UID 格式
python3 scripts/123yunpan.py share create --name "分享" --file-ids 123,456 --url-format uid

# 批量分享也支持
python3 scripts/123yunpan.py share create-batch --parent-id 27172609 --url-format uid -o result.xlsx

Example response from POST /api/v1/share/create:

{
  "code": 0,
  "message": "ok",
  "data": {
    "shareID": 5193007,
    "shareKey": "JyAKVv-o6bI"
  }
}

Direct Link & Short Direct Link

The skill supports two types of direct links:

Full direct link (contains filename in URL):

https://{user_id}.v.123pan.cn/{user_id}/{file_id}/{filename}

Short direct link (privacy-friendlier, no filename):

https://{user_id}.v.123pan.cn/{user_id}/{file_id}

To generate short direct links, parse user_id from the JWT access token (no extra API call needed):

import base64, json
parts = token.split(".")
payload = parts[1] + "=" * (4 - len(parts[1]) % 4)
user_id = json.loads(base64.b64decode(payload))["id"]
short_link = f"https://{user_id}.v.123pan.cn/{user_id}/{file_id}"

> See references/competitor-upload-patterns.md for full upload workflow, SHA1 reuse, and WebDAV patterns.

Recursive File Listing

The file list API only returns direct children of a folder. To find all files in a multi-level directory tree, you must traverse recursively. See references/bulk-operations.md for BFS and layered traversal patterns.

Quick pattern — find all files under a root folder:

from collections import deque

def find_all_files(root_id, list_folder_fn):
    queue = deque([(root_id, [])])
    all_files = []
    while queue:
        pid, path = queue.popleft()
        for item in list_folder_fn(pid):
            if item.get("trashed"):
                continue
            if item["type"] == 1:  # folder
                queue.append((item["fileId"], path + [item["filename"]]))
            else:  # file
                all_files.append({
                    "fileId": item["fileId"],
                    "filename": item["filename"],
                    "path": "/".join(path),
                })
    return all_files

> ⚠️ Deep traversal can involve hundreds of API calls. For 100+ folders, expect 5-10 minutes. Use checkpoint/resume (save progress to JSON every N items) to handle interruptions.

Common Pitfalls

1. API response format (CRITICAL): The 123yunpan API returns {code: 0, message: "ok", data: {...}} — NOT {result: {...}}. Always parse the data field. Use client._extract(resp) — the CLI script handles both formats.

1. Token expiry & auto-refresh: access_token expires after a period. The CLI automatically refreshes on 401 responses using client_id/secret. For manual refresh, run setup or call /api/v1/access_token.

1. File name restrictions: Filenames must be <256 chars and cannot contain: \\\\\\\"/:*?|><

1. Upload size: Single file upload limit is 10GB via the API.

1. fileIDList must be a string (CRITICAL): When calling the share create API directly, fileIDList must be a comma-separated string ("123,456"), NOT a JSON array ([123, 456]). Passing an array causes the API to return "文件列表不能为空". The CLI handles this internally via ",".join(str(x) for x in file_ids). Max 100 file IDs per share. shareExpire must be 0, 1, 7, or 30.

1. Share response has no shareUrl: The share create response only returns shareID + shareKey. You must construct the URL. Use --url-format short (default, https://www.123pan.com/s/{shareKey}) or --url-format uid (https://{user_id}.share.123pan.cn/123pan/{shareKey}). See "Share URL Construction" section above.

1. Pagination: Use lastFileId/lastShareId for cursor-based pagination. When value is -1, you've reached the last page.

1. Upload API domain routing (CRITICAL): Upload endpoints are split across two domains:
• Main API domain (https://open-api.123pan.com): /upload/v2/file/create (chunked create), /upload/v1/file/create (v1 create)
• Upload domain (https://openapi-upload.123242.com): /upload/v2/file/single/create (single upload), /upload/v2/file/slice (chunked slice), /upload/v2/file/upload_complete (chunked complete)
• Upload domain is obtained via GET /upload/v2/file/domain — it returns a list ["https://..."], not an object with host field.

1. Single upload requires multipart/form-data (CRITICAL): The /upload/v2/file/single/create endpoint does NOT accept JSON body. It requires Content-Type: multipart/form-data with fields parentFileID, filename, etag, size as text parts and the file content as a file part. Sending JSON results in a 500 server crash.

1. duplicate parameter (CRITICAL): The duplicate field in upload create causes "duplicate参数错误" when set to 0 (skip). Do not send duplicate at all (defaults to overwrite), or use 2 (overwrite) or 1 (rename). The value 0 is rejected by the API. The CLI now defaults to not sending this parameter (overwrite behavior).

1. Trash behavior: The v2 file list includes trashed files — filter by trashed field yourself. trashed: 1 means the file is in trash.

1. Batch operations rate limit: When creating shares or making many API calls (e.g., 2500+ files), limit to ~2 requests/second (0.5s sleep). Use checkpoint/resume: save progress to JSON every 10 items, skip already-processed items on restart.

1. Deep directory traversal: Folders can be 4-5 levels deep. Use BFS with a queue for unknown structures, or layered traversal when structure is known. Each level requires a separate API call — 1400+ folders may take 10+ minutes. Use BFS caching (~/.123yunpan_cache/) to avoid repeated traversals — 57s → 0.15s on cache hit. CLI commands file search and share create-batch auto-use cache; add --no-cache to force refresh.

1. Common error responses:

1. Packaging & versioning: Version must be updated in two places: (1) scripts/123yunpan.py line 4 comment (vX.Y.Z), (2) SKILL.md frontmatter (version: X.Y.Z). No zip/unzip CLI — use Python's zipfile module. Package includes SKILL.md + README.md + scripts/ + references/ (no LICENSE per user preference). Exclude __pycache__/. Extraction for patching: python3 -c "import zipfile; zipfile.ZipFile('pkg.zip').extractall('_tmp')". Repackaging: cd _tmp && python3 -c "import zipfile,os; [zipfile.ZipFile('out.zip','w',zipfile.ZIP_DEFLATED).write(f, os.path.relpath(f,'.')) for r,d,fs in os.walk('.') for f in fs if '__pycache__' not in r]".

> ⚠️ Remember to also update the version in scripts/123yunpan.py line 4 when bumping the version in SKILL.md frontmatter.

1. Argparse parameter names must match SKILL.md exactly: Before adding/changing argparse arguments, cross-check every --flag in SKILL.md CLI examples. Mismatches (e.g. --name in code vs --new-name in docs) silently break user workflows. Use parse_int_list() (not type=int, nargs="+") for all file-ID arguments to support both comma-separated (1,2,3) and space-separated (1 2 3) input.

1. _refresh_token uses imported names, not module paths: The ApiClient methods use Request and urlopen (from from urllib.request import ...), NOT urllib.request.Request. Using the module path will crash with NameError since urllib is not imported as a module.

1. BFS traversal optional params: bfs_list_files() accepts max_depth, use_cache, max_age — always forward these from callers (e.g. cmd_file_search). Unused parameters silently cause unbounded traversal.

1. Global options placement: --no-color and --json must appear before the subcommand (e.g., --json file list --parent-id 0), not after. Placing them after the subcommand will cause argparse to ignore them.

1. file tree vs recursive traversal: file tree is a display-only convenience command that shows directory structure. For bulk operations (downloading, moving, sharing), use recursive BFS traversal or file list with pagination — file tree does not return file IDs suitable for batch operations.

1. share export format: Without --format, the default output is Excel (.xlsx). Use --format json explicitly for JSON output. Excel output requires openpyxl (pip install openpyxl).

1. config import safety: Importing config will overwrite your current ~/.123yunpan_config.json. Back up your existing config before importing. The CLI warns before overwriting if the file exists.

See references/bulk-operations.md for batch operation code patterns, BFS traversal, and background execution tips.

Verification Checklist

• [ ] Environment variables TWOPAN_CLIENT_ID, TWOPAN_CLIENT_SECRET, TWOPAN_ACCESS_TOKEN are set
• [ ] Run 123yunpan.py setup to validate credentials and fetch token
• [ ] Test with 123yunpan.py file list --parent-id 0 --limit 5
• [ ] Confirm token refresh works by checking ~/.123yunpan_config.json

Changelog

v1.2.0 (2026-05-09)

• 新增: --no-color 和 --json 全局选项，支持禁用彩色输出和 JSON 格式输出
• 新增: file tree 命令 — 目录树展示，支持 --parent-id 和 --max-depth 参数
• 新增: file download-batch 命令 — 批量下载文件，支持 --file-ids 和 --output-dir 参数
• 新增: file storage-report 命令 — 存储分析，支持 --parent-id 和 --top 参数
• 新增: offline list 命令 — 列出离线下载任务（占位，待完善）
• 新增: share export 命令 — 导出分享记录到 Excel/JSON，支持 --output 和 --format 参数
• 新增: config export 命令 — 导出配置到 JSON，支持 --output 参数
• 新增: config import 命令 — 从 JSON 导入配置，支持 --file 参数

v1.1.5 (2026-05-09)

• 修复: upload 命令的 --duplicate 参数默认值从 0（跳过）改为不发送（默认覆盖），避免API报错
• 修复: _refresh_token 方法使用了未导入的 urllib.request 模块，导致自动刷新Token时崩溃
• 修复: file search --max-depth 参数未实际生效，BFS遍历无深度限制
• 修复: 代码参数名与文档不一致（--new-name、--target-parent-id、--ips），统一到文档标准
• 优化: 所有 --file-ids/--share-ids 参数同时支持逗号分隔和空格分隔格式（如 1,2,3 或 1 2 3）
• 新增: cache list 命令 - 列出所有BFS缓存文件
• 新增: cache clear 命令 - 清除缓存（支持指定文件夹或全部清除）
• 新增: cache info 命令 - 显示缓存目录信息
• 优化: 批量操作进度显示增加ETA（预计剩余时间）估算
• 优化: 清理重复的import语句

v1.1.4

• 初始版本，支持70+ API端点