联通云盘（pan.wo.cn）文件操作

所有操作都通过本技能自带的 scripts/wopan_api.py 完成。不要自己拼 HTTP 请求：内部接口有 AES 加密和签名，手拼必错。

前提

cd <本技能目录>            # SKILL.md 所在目录
python3 scripts/wopan_api.py --help

• 需要 Python 3.9+ 和 pycryptodome。缺失时报 ModuleNotFoundError: Crypto，先 pip install pycryptodome。
• 凭据存在 scripts/state/wopan.json（600，等同密码）。本技能不预置任何凭据，首次运行必须按下方「首次运行」填入自己的 token。不要打印、不要外发、不要复制进其它仓库。

首次运行：补充凭据（必做）

本技能不随包携带任何凭据。首次使用前，必须把你的联通云盘 token 填入 scripts/state/wopan.json，否则 status 会报 ❌ 没有凭据。

token 从哪来

联通云盘（pan.wo.cn）网页登录后，api-user 通道的响应里会明文返回一对 token（不加密）：

• access_token：约 36 字符（UUID 形式），有效期约 7 天
• refresh_token：约 36 字符，用于续期

也可从已配置好的 AList wopan 驱动里复制同一对。

两种填入方式

方式 A（推荐，不触发续期）：

python3 scripts/wopan_api.py login \
  --access-token <你的access_token> \
  --refresh-token <你的refresh_token> \
  --no-refresh

--no-refresh 必须带：不带会调续期接口，若服务端轮换 refresh_token，可能顶掉你其它客户端（如 AList）里的那一对。

方式 B（手写文件）： 在 scripts/ 下建 state/wopan.json（权限建议 600）：

{
  "access_token": "<你的access_token>",
  "refresh_token": "<你的refresh_token>",
  "family_id": "",
  "saved_at": ""
}

填好后验证

python3 scripts/wopan_api.py status     # 应输出 ✅ 凭证有效
python3 scripts/wopan_api.py ls          # 应列出根目录

跨机器 / 多人共用注意

• token 是无状态 bearer 凭据，不绑 IP，不会因为换 IP 互踢。
• 真正会顶掉别人的是 refresh：若服务端轮换 refresh_token，其它持有旧 refresh_token 的客户端会失效。只在一处执行 refresh。
• 只想短期借给别人用（7 天内）：只给 access_token，用 login --no-refresh 且不要保存 refresh_token。
• scripts/state/wopan.json 等同密码，不要提交 git、不要随包再外发。

命令速查

固定流程

1. 确认凭证

python3 scripts/wopan_api.py status

• 输出 ✅ 凭证有效 → 继续。
• 输出 ❌ 没有凭据 或 ❌ 凭证失效 → 向用户要一次 refresh_token（可选 access_token），然后：

python3 scripts/wopan_api.py login --refresh-token <RT> --access-token <AT> --no-refresh

--no-refresh 必须带：不带会调续期接口，可能轮换掉用户其它客户端（如 AList）里的那对 token。不要自己决定续期，先问用户。

2. 定位目标

python3 scripts/wopan_api.py ls                 # 根目录 8 项之类
python3 scripts/wopan_api.py ls --dir <目录id>   # 逐层下钻

ls 每行格式：📁/📄 名称 字节大小 创建时间 id=<32位hex> fid=<长串>。把 id 记下来供 --dir 使用。

3. 执行操作

按上表选一条执行。上传/下载都会打印进度与结果。

4. 必须校验

命令返回 0 不代表 业务成功，用数据核对：

• 上传后：ls（或 ls --dir）确认出现同名文件且大小一致。
• 下载后：比对大小；要求高时 md5sum 两边比对。

5. 失败查症状表

症状表

硬性规则

1. delete 前必须得到用户确认：进回收站但脚本没有恢复功能。先 ls 把要删的名称和大小念给用户，确认后再删。
2. upload 会真实写入用户网盘，先确认目标目录（默认根目录）和文件名，不要上传含密钥/隐私的文件到不相关位置。
3. 不要打印 token，不要把 scripts/state/wopan.json 内容贴进对话或日志。
4. 文件名含空格、中文、括号时加引号：delete "我的 文件 (1).zip"。
5. --dir 只接受目录 id（32 位 hex），不能传名称或路径。
6. 目录只能逐层进：mkdir 不自动创建父目录，父目录必须已存在。
7. 上传大文件自动分片（8MB/片），实测约 4MB/s；慢是网络，不是脚本。

参考

• 内部协议细节（端点、加密、签名、错误码、上传分片语义）：references/protocol.md。仅在需要修脚本或排查协议级问题时读。
• python3 scripts/wopan_api.py selftest 可在无账号情况下检查协议是否仍被服务端接受。