wocloud

联通云盘第三方客户端 —— 命令行工具 + MCP Server，零 npm 依赖。

把云盘变成可用脚本和 Agent 操作的东西：38 个 CLI 命令 + 25 个 MCP 工具，同一份代码跑在 macOS / Windows / 安卓 Termux 上。

A zero-dependency CLI + MCP (Model Context Protocol) server for China Unicom Cloud Drive (联通云盘, wocloud / wopan) — file management, upload/download, sharing, trash and batch backup, scriptable on macOS, Windows, Linux and Termux, and directly operable by AI agents.

本项目通过互操作性分析实现，不是官方客户端，与联通公司无任何隶属关系。使用前请阅读下面的免责声明。

免责声明

请在动手之前读完这一节。 本项目涉及对第三方客户端协议的分析，风险由使用者自行承担。

1. 非官方项目。 本项目未获得联通公司或其关联方的授权、认可或支持。「联通」「联通云盘」等名称与商标归其各自权利人所有，本项目仅作客观指代，不构成任何形式的官方标识。

2. 仅限个人自用。 设计目的只有一个：访问自己账号里的数据。请勿用于批量抓取他人数据、绕过付费/配额限制、绕过风控、二次分发或任何商业用途。

3. 合规责任在你自己。 使用本项目可能违反服务提供方的用户协议，或与你所在地区的法律法规冲突。是否使用、如何使用，由你自行判断并承担全部后果。

4. 账号风险。 高频或异常调用可能触发服务端风控，导致限流、限制功能甚至封禁账号。请保持与正常客户端相称的使用强度。

5. 服务随时可能失效。 接口、签名、加密方式均由第三方控制，对方一次更新就可能让本项目完全不可用。不承诺跟进，不承诺可用性。

6. 不含任何凭证。 仓库中不提供账号、token、密钥。你需要用自己的账号登录。请勿把自己生成的凭证提交到版本库（见 .gitignore）。

7. 不含逆向分析材料。 本仓库不提供分析脚本、抓包数据或客户端解包产物（这类材料可能涉及第三方商业代码）。MIT 许可证仅覆盖本仓库内的源代码。

8. 按「现状」提供。 软件存在缺陷是常态。因使用本软件造成的数据丢失、账号异常、时间损失或其他任何直接/间接损害，作者不承担责任。重要数据请保留第二份备份，不要把云盘当唯一副本。

如果你不接受以上任何一条，请立即停止使用。

Related MCP server: unifiles-mcp

这是什么

技术底色：零 npm 依赖，只用 Node 标准库。Node 18+ 即可运行。

为什么值得单独做一份： 官方客户端只在桌面端提供图形界面，多设备之间的登录状态还会互相踢下线。本项目把「续期权」收敛到一台服务器上，其余设备只拉取，从而让手机、电脑、服务器同时在线。

特性

• 零依赖：git clone 完直接 node，没有 npm install 这一步

• 三端一致：macOS、Windows、安卓 Termux 跑同一份代码

• 断点续传：上传按分片记录，中断重跑自动跳过已完成部分，SHA256 可校验

• 高速下载：直链分段并行（32 段 ≈ 单流 17 倍），过期自动换链

• 多设备共存：自建 relay + token-keeper，服务器独占续期，不再互踢

• Agent 友好：非 TTY 下自动静默进度条；MCP 让模型直接用一句话操作云盘

• 破坏性操作有闸：rm / purge / empty_trash 默认只返回预演计划，需显式确认才执行

环境要求

• Node.js 18 或更高（node -v 检查）

• 一个联通云盘账号

• 能上网的环境

无第三方依赖，无需数据库，无需编译。

安装

git clone https://github.com/Lumjiel/wocloud.git
cd wocloud
node wocloud.mjs doctor      # 自检：环境、凭证、连通性

想当全局命令用：

npm link          # 之后可直接 wocloud <命令>

安卓 Termux：

pkg install nodejs git

快速开始

# 1. 登录（终端出二维码，手机 App 扫一扫）
node wocloud.mjs login

# 2. 看看账号
node wocloud.mjs whoami
node wocloud.mjs usage
node wocloud.mjs ls
node wocloud.mjs tree --depth 12      # 全盘盘点

# 3. 传点东西
node wocloud.mjs upload ./file.iso --dir <目录id>
node wocloud.mjs push ./photos/2026 --to <目录id>      # 递归整个目录
node wocloud.mjs mirror <目录id> ~/Backup/wocloud      # 云端 → 本地镜像

# 4. 看别人的分享
node wocloud.mjs share-ls https://pan.wo.cn/s/xxxx --code abcd
node wocloud.mjs share-dl https://pan.wo.cn/s/xxxx 1 --code abcd --out ./a.jpg

单命令用法：node wocloud.mjs help <命令>。

在管道、重定向等非 TTY 环境里，进度条会自动静默，只输出完成行，可放心放进自动化脚本。

登录与多设备

token 解析链（三端一致）：

--token  →  WOCLOUD_TOKEN  →  ~/.wocloud/credentials.json  →  本机客户端 leveldb

token 失效（业务码 1001）会自动刷新并落盘；刷新失败再回退尝试客户端 leveldb。

多设备共存的两种方式：

relay 的取舍与部署见 relay/README.md：保活必须调用 exchange（exchange 会作废旧 token），因此 relay 采用明文存储 + 0600 + key 鉴权 + 仅内网监听，而不是加密存储。

命令一览

共 38 个命令。批量备份与治理用 tools/wocloud-bulk.mjs，日常操作见 docs/usage.md。

MCP Server

mcp/ 下是一个完整的 Model Context Protocol 服务端：25 个工具，零依赖，支持两种传输。

# 本地：由客户端作为子进程拉起（stdio）
node mcp/server.mjs

# 远程：常驻 HTTP 服务（必须配置鉴权）
MCP_TOKEN=<强随机串> node mcp/server.mjs --http --port 8788

设计要点：

• 同一套协议逻辑，两种传输：protocol.mjs 不碰 I/O，transport/ 只负责分帧与连接

• 破坏性操作默认预演：rm / purge / empty_trash 不带 confirm: true 时只返回执行计划

• HTTP 模式无鉴权即拒绝启动：这个 server 有删除权，公网裸奔等于开放云盘删除

• 进度按请求隔离：progressToken 存在请求级闭包里，多客户端并发不会串条

协议版本对齐 2026-07-28（该版本移除了协议级会话、GET SSE 流与 Last-Event-ID）。

完整工具清单、部署方式与设计边界见 mcp/README.md。

实测数据

协议要点

详见 docs/protocol.md。

• 双 dispatcher：/api-user/dispatcher（secretKey 加密）与 /wohome/dispatcher（accessToken 加密）

• 签名：md5(key + resTime + reqSeq + channel + "")，本身不含密钥

• 加密：AES-128-CBC / PKCS7，固定 16 字节 IV（随客户端分发，见 wocloud-core.mjs）

• 上传域名按账号分区（GetZoneInfo）；直链 120 分钟过期，需换链续传

• 分享/匿名接口：secretType: "clientSecret"，body 必须带顶层 clientId，否则只返回 1000 参数错误

两个最难查的坑：

1. clientType 必须是数字 1。传字符串（如 "MAC"）时网关返回 HTTP 400 且响应体为空，只留一个 X-Request-Id。

2. 删除文件必须带 fileVersion。缺失时接口返回 success: true，但文件根本没删，且没有任何错误提示。

目录结构

wocloud/
├── wocloud-core.mjs      核心真源：协议 / 加密 / 上传下载 / token（零依赖）
├── wocloud.mjs           CLI 主程序（瘦壳，只做参数解析与输出）
├── mcp/                  MCP Server（25 工具）
│   ├── server.mjs            入口：选择传输方式
│   ├── protocol.mjs          JSON-RPC 分发（无 I/O）
│   ├── tools.mjs             25 个工具实现
│   └── transport/            stdio.mjs / http.mjs
├── relay/                凭证中转 + token 保活（服务器唯一续期）
├── cli/                  兼容 shim + 上传性能基准脚本
├── tools/                批量备份 / 治理工具（含失败清单与 resume）
├── docs/                 协议报告、性能实测、使用手册、路线图、手法参考
└── LICENSE / package.json

文档

已知限制

• 上传域名与可用的接口集按账号分区，不同账号行为可能不一致

• 单连接下载被服务端限速，只能靠分段并行绕开，不支持真正的多线程单文件加速

• relay 的凭证是明文存储（0600 + key 鉴权 + 内网监听），不要在公网暴露

• 服务端接口随时可能变更，本项目不做及时跟进承诺

贡献

欢迎 Issue 与 PR。提交前请确认：

1. 不包含任何真实账号、token、文件 ID、手机号等个人信息

2. 不提交逆向分析脚本、抓包数据或第三方客户端代码

3. 改动经过实际账号验证，并在 PR 里说明测试环境（系统 / Node 版本 / 云盘客户端版本）

许可证

MIT © 2026 Lumjiel

许可证仅覆盖本仓库中作者编写的源代码，不涉及第三方软件、商标及逆向分析产物。 「联通」「联通云盘」等名称与商标归其各自权利人所有，本项目与联通公司无任何隶属关系。

致谢

• 协议字段与接口行为参考了社区对联通云盘客户端的公开分析，以及 wopan-sdk-go 等第三方实现的对照思路

• 上传下载的调优手法参考了 rclone 的设计

本项目与上述项目及联通公司均无隶属关系。