baiduwangpan-cli
v1.11.3
Published
百度网盘 CLI — 全盘读写 · 免下载读取文件内容 · 群聊文件浏览 (Agent 友好)
Maintainers
Readme
baiduwangpan-cli
百度网盘 CLI — 全盘读写 · 免下载读取 · 群聊文件浏览/下载
专为 AI Agent 设计的百度网盘命令行工具
✨ 特性
- 🗂️ 全盘访问 — 不受
/apps/目录限制,读写网盘任意路径 - 📄 免下载读取 — 通过 HTTP Range 直接读取文件内容到 stdout,无需下载整个文件
- 👥 群聊文件浏览 + 下载 — 逆向 mbox API,列出群组、浏览群内分享库、搜索群文件,并支持直接下载群文件到本地(免转存)
- 🤖 Agent 友好 — 所有命令支持
--json结构化输出,零解析成本 - 🔌 MCP 接入 —
bdp serve --mcp可作为 MCP 服务器运行(stdio 或 HTTP),工具描述与参数 schema 由客户端自动发现;23 个工具含移动/重命名/删除,Agent 可自主整理 - 🗂️ 内容整理 —
bdp organize按类型/年份/来源生成归类方案,默认只出计划不动文件 - 🌐 MCP over HTTP —
bdp serve --mcp --http支持独立进程/远程 agent 接入(默认仅本机 + 令牌认证) - 📚 结构化目录/搜索 —
ls/search的--json返回真正的结构化entries[],不再需要解析文本表格 - 🔤 编码自动识别 — UTF-8 / GBK / Big5 自动判别,中文古籍不再乱码,grep 不再静默漏检
- 🚦 可信的退出码 — 命令失败一定以非零退出码结束,Agent 不会把失败当成功
- 🔧 双模式 — 既是 CLI 工具,也可作为 Node.js 库
require()使用 - 🔐 凭证安全 — 配置存储在
~/.bdp/config.json,不写入代码或日志;bdp config默认脱敏 - 🧹 重复文件清理 —
bdp dedup先按 size 粗筛再按 md5 精算,自动破解百度的 md5 混淆 - 👁️ 全类型预览 —
bdp preview抽取 PDF 文本层(中文 CID 字体可还原)、ZIP 中央目录、DOCX/XLSX 正文 - 🔎 本地全文索引 —
bdp index+bdp ask,中文二元分词 + SQLite FTS5,零外部依赖
📌 能力一览
| 能力 | 命令 | 说明 |
|:-----|:------|:-----|
| 列目录 | bdp ls / | 全盘任意目录 |
| 搜索文件名 | bdp search "报告" | 递归全盘搜索,支持 glob/正则 |
| 读取文件内容 | bdp cat /文档/data.json | 免下载,限 1MB |
| 读取前 N 行 | bdp head -n 50 /文档/log.txt | 免下载 |
| 读取后 N 行 | bdp tail -n 30 /文档/log.txt | 免下载 |
| 搜索文件内容 | bdp grep "关键词" /文档/file.txt | 免下载 |
| 预览文件 | bdp peek /文档/report.pdf | 类型检测 + 前 10 行 + md5/ctime |
| 全类型预览 | bdp preview /文档/报告.pdf | PDF 文本 / ZIP 目录 / DOCX / XLSX / 图片尺寸 |
| 查重复文件 | bdp dedup /med | 自动反混淆 md5,报告可释放空间 |
| 建立全文索引 | bdp index build /中医 | 本地 SQLite FTS5,增量更新 |
| 检索内容 | bdp ask "甘草配伍" | 基于索引搜正文,不只搜文件名 |
| 内容整理 | bdp organize /med --by type | 按类型/年份/来源归类(默认只出计划) |
| 设置配置项 | bdp config --set webTransport native | 白名单校验,凭证类字段需用 bdp login |
| 下载 | bdp get /文档/file.zip | 保存到本地,size 校验 + 断点续传 |
| 上传 | bdp put ./file.txt /文档/ | 全盘任意位置 |
| 移动/重命名 | bdp mv <src> <dst> | 移动或重命名 |
| 拷贝 | bdp cp <src> <dst> | 网盘内复制 |
| 配额 | bdp quota | 总容量/已用/剩余 |
| 容量分析 | bdp du [path] | 递归统计目录大小,找空间大户 |
| 回收站 | bdp recycle list/restore/clean | 列出/还原/清空回收站 |
| 离线下载 | bdp offline add <url> | 百度服务器代下 |
| 分享管理 | bdp share set/cancel | 生成/取消分享链接 |
| 列出群组 | bdp groups | 所有群聊 + gid |
| 群内分享库 | bdp gshares <gid> | 顶层分享目录 |
| 浏览群文件 | bdp gls <gid> <fs_id> | 分页 + 递归 |
| 搜索群文件 | bdp gsearch <gid> "关键词" | 按文件名搜索(缓存命中秒回) |
| 下载群文件 | bdp gdownload <gid> <fs_id> | 直接下载到本地,免转存(逆向 sharedownload API) |
| 群目录树 | bdp gtree <gid> | BFS 构建目录树 |
| 群缓存管理 | bdp cache [clear] | 查看 / 清空会话缓存 |
| 列出我的分享 | bdp share list | 网页 API,绕过引擎 panic bug |
| 错误码释义 | bdp error -3 [--json] | 内置错误码字典(--json 返回结构化:code/codeText/name/description/severity/retryable/action;--verbose 附带 internalDetail) |
| MCP 服务器 | bdp serve --mcp [--http] | stdio 或 HTTP 传输,23 个带 schema 的工具(含写操作) |
🚀 快速开始
1. 安装
npm install -g baiduwangpan-cli安装时会自动下载 BaiduPCS-Go 引擎(镜像优先加速,国内也能装;全部下载源失败时打印手动下载地址,不阻断安装)。
CLI 会自动发现引擎(包根固定路径或 BaiduPCS-Go-v4.0.1-windows-x64/ 版本子目录),升级不会丢 pcsPath 配置。也支持手动克隆:
git clone https://github.com/NkAntony777/baiduwangpan-cli.git
cd baiduwangpan-cli
npm install # postinstall 自动下载引擎
npm link # 全局注册 bdp 命令依赖: Node.js 22.5+(推荐 24;
bdp index/bdp ask依赖内置node:sqlite)和curl(已在 Windows 10+ / macOS / 大多数 Linux 预装)
2. 配置认证
方式一:浏览器自动登录(推荐)
bdp login自动启动 Chrome/Edge → 打开百度网盘登录页 → 手机扫码 → 在页面会话内验证登录 → 自动同步引擎。无需 F12。
扫码产生的新会话可能被百度限制为只能在原浏览器上下文中使用。因此 bdp 会保留专用 profile,并在登录后将浏览器最小化;PCS API 继续使用 BDUSS/STOKEN,网页和群聊 API 通过该浏览器的 CDP 会话调用。浏览器被关闭后,下次网页 API 调用会使用同一 profile 自动重启。
方式二:手动凭证
bdp login --bduss <你的BDUSS> --stoken <你的STOKEN>
bdp whoami # 验证- 浏览器打开 pan.baidu.com 并登录
- 按
F12→ Application → Cookies →https://pan.baidu.com - 找到 BDUSS 和 STOKEN 的值,复制
⚠️ STOKEN 必须在百度网盘页面获取(不是百度首页),值中应包含大写字母。
💡 推荐直接运行
bdp login,全程自动化,无需手动操作。
3. 开始使用
# 浏览网盘
bdp ls /
bdp search "中医"
# 免下载读取文件
bdp head -n 10 /文档/data.csv
bdp cat /文档/config.json
# 浏览群聊文件
bdp groups
bdp gshares 539478953581833690
bdp gls 539478953581833690 742474845517885
# 下载群文件到本地 (免转存)
bdp gdownload 539478953581833690 954615608563687 -o ./downloads🆕 v1.9.1 新增(v1.9.0 的四路审核修复)
| 修复 | 说明 |
|:-----|:-----|
| 信封报实际账号 | meta.profile 此前报的是「请求的 profile」,多账号下恒为 null;现取实际激活的账号(MCP 侧同样) |
| 失败路径也有信封 | cat/head/tail/grep/login 与顶层错误输出此前绕过信封 |
| 错误码不再丢数值 | "errno=31066" 能命中条目却返回 code: null |
| 缺参数不再污染网盘 | bdp_mkdir {} 曾会真的建出名为 undefined 的目录;现统一报 user-error |
| --no-meta 位置自由 | bdp --no-meta ls 此前报「未知命令」 |
| 参数错误不再让你提 Issue | 新增 -32001 TOOL_ARGUMENT_ERROR(severity: user-error) |
🆕 v1.10.0 新增(MCP 并发恢复)
| 改进 | 说明 |
|:-----|:-----|
| 并发不再等于串行 | 引擎调用此前用 spawnSync,一次 ls / 冻结事件循环 594ms —— MCP 单进程下所有并发请求全部排队(8 并发 4047ms,加速比 1.0×)。现改用异步 spawn,输出逐字节不变 |
并发基准(实测;同一台机器、同一网盘账号;改前 = spawnSync,改后 = 异步 spawn):
| 并发数 | 改前 | 改后 | |:---|:---|:---| | 1 | 436ms | ~470ms | | 2 | 869ms | 460ms | | 4 | 1733ms | 441ms | | 8 | 4047ms | 554ms(7.3×) |
事件循环也不再被冻结:8 并发期间定时器触发 52 次(改前单次调用就是 0 次)。
🆕 v1.9.2 新增(错误码分层)
| 改进 | 说明 |
|:-----|:-----|
| 结论与内部细节分层 | 每条错误码拆成 description(结论)与 internalDetail(实测记录/实现坑)。默认只下发结论;CLI --verbose / MCP {"verbose":true} 才给内部细节 |
| 全局开关位置自由 | bdp --verbose error -3 此前报「未知命令」;现 --json/--verbose/--no-meta/--legacy-json 均支持前置换 |
🆕 v1.9.0 新增(统一响应信封 + 结构化错误码)
| 改进 | 说明 |
|:-----|:-----|
| 统一响应信封 | 所有 --json 输出追加 meta(command/version/profile/elapsedMs),只追加不改既有字段;--no-meta 可关闭。返回裸数组的历史接口(groups/gshares/--legacy-json/share cancel)不加 |
| 结构化错误码 | 错误码表抽到 lib/error-codes.js,CLI bdp error --json 与 MCP bdp_error 返回同一份结构 |
| 错误码可判断重试 | 每条错误带 severity(retryable/fatal/user-error/unknown)与 action(建议的下一步) |
| MCP 错误也结构化 | 工具失败返回 {error:{code,name,message,severity,retryable,action}},code 永远是数值 |
| 19 个 MCP 工具 | 新增 bdp_error |
🆕 v1.8.5 新增(第二轮红队 + 性能剖析)
| 修复 | 说明 |
|:-----|:-----|
| 群文件直下恢复 | webJsonAsync 此前把 POST 的 method/body 丢了 → native 传输下 bdp gdownload 自 v1.8.1 起一直是坏的 |
| 中文不再乱码/漏检 | UTF-8 末尾被截断时按字节奇偶判断会误判成 GBK → cat 乱码、grep 搜中文返回 0 条 |
| --dry-run 不再真下载 | 目录路径的 dry-run 判定原本排在引擎回退之后 → 会把整个目录拉下来 |
| CLI 也有边界标记 | --json 通道的正文此前没有 <untrusted_file> 标记,而文档声称有 |
| rename 越权被堵 | 目标名 .. 可绕过「只改文件名」→ 引擎归一化后变成跨目录移动 |
| 合法文件名不再被改坏 | 净化曾删掉 ZWSP/ZWNJ/LRM 等合法排版字符 → 返回的路径再也找不到文件 |
| 公开分享要确认 | bdp share set 创建对外可访问的链接,此前无任何闸门 |
| 离线下载拒绝内网 | bdp offline add 可让百度服务器去取 169.254.169.254 等内网地址 |
| pcsPath 精确匹配 | 前缀匹配会让 BaiduPCS-GoX.exe 通过 → 重新打开任意 exe 启动器 |
🆕 v1.8.4 新增(三路对抗性审核的修复)
| 修复 | 说明 |
|:-----|:-----|
| 提示注入防线接线 | sanitizeUntrusted 此前是死代码 —— MCP 返回的正文裸奔。现所有返回值都清洗控制字符与 Unicode 格式字符,正文类字段包上 <untrusted_file>…</untrusted_file> 边界标记 |
| 删除不再谎报成功 | 引擎退出码此前被忽略,引擎没真跑也报「✅ 已删除」。现按 BaiduPCS-Go 源码的成功标记判定,未确认即失败 |
| 凭证不再被覆盖抹掉 | 配置损坏时 config --set 拒绝写入并告警;写入改为原子替换 |
| pcsPath 只认引擎 | --set pcsPath 只能指向文件名以 BaiduPCS-Go 开头的引擎 |
| rename 只改文件名 | MCP bdp_rename 目标含 / 会被拒绝,跨目录移动请用 bdp_move |
| 回收站能列出文件 | md5 列的正则只认纯 hex,而百度返回混淆 md5 → 文件行被丢弃。现已放宽并反混淆 |
| offline --path 生效 | bdp offline add --path <dir> 的保存目录此前被静默丢弃 |
| 体积上限按字节 | MCP HTTP 请求体 8MB 上限此前按 UTF-16 码元计,中文可放大 3 倍;超限现在真正返回 413 |
| recycle clean 要 --yes | 与 bdp rm 一致的确认闸门 |
| 扫描完整性自报 | dedup/organize 的输出带 partial/scanPartial/scanFailedDirs;此前目录扫描失败时那批文件会静默消失 |
| 请求不再无限挂起 | native 传输此前没有超时且 worker 忙等,一次挂起即 100% CPU 死循环。现所有请求带超时,worker 改为事件唤醒 |
| MCP/CLI 深度对齐 | MCP bdp_organize 此前硬编码深度 6(CLI 是 12),同一目录少覆盖 41% 的文件 |
Node 版本要求已从
>=14提升到 >=22.5(bdp index/bdp ask依赖内置node:sqlite)。
🆕 v1.8.x 新增(内容深度能力)
| 能力 | 命令 | 说明 |
|:-----|:-----|:-----|
| md5 反混淆 | 自动 | 百度返回的 md5 是混淆值 —— 同一内容在不同路径返回值不同。不解密就无法去重。算法移植自 BaiduPCS-Go 源码,用真实网盘数据验证 9/9 |
| 重复文件清理 | bdp dedup /med | 先 size 粗筛再 md5 精算,报告可释放空间;删除走回收站可恢复 |
| 全类型预览 | bdp preview /报告.pdf | PDF 文本层(中文 CID 字体可还原)/ ZIP 中央目录 / DOCX / XLSX / EPUB / 图片尺寸 |
| 本地全文索引 | bdp index build /中医 | SQLite FTS5 + 中文二元分词,增量更新 |
| 内容检索 | bdp ask 甘草配伍 | 搜正文而非仅文件名 |
| 内容整理 | bdp organize /med --by type | 按类型/年份/来源归类;同名目标自动加序号去重 |
| 配置项写入 | bdp config --set webTransport native | 白名单 + 值校验;凭证类字段仍走 bdp login |
| Agent 写操作 | MCP bdp_move/bdp_rename/bdp_remove | Agent 能自主整理;remove 需显式 confirm,rename 默认 dry-run |
| MCP over HTTP | bdp serve --mcp --http | 独立进程/远程 agent 接入;默认仅绑 127.0.0.1 + Bearer 令牌 |
v1.8.1 起并发真正生效:
--concurrency此前形同虚设(worker 池退出条件错误 +spawnSync阻塞事件循环), 实测 dedup 扫描提速 19.4×、index 全量构建提速 9.2×(结果完全一致)。
🆕 v1.7.0 新增
| 改进 | 说明 |
|:-----|:-----|
| 凭证不再泄漏 | bdp config --json 此前会明文吐出完整 BDUSS/STOKEN(而 SKILL.md 要求 Agent 优先用 --json)。现已默认脱敏,JSON 带 "redacted": true |
| 失败不再伪装成功 | ls/get/put 失败时退出码曾为 0(get 还会把失败报成"下载完成 0B")。现统一以退出码 1 结束,JSON 带 {"error","errno"} |
| GBK 中文古籍修复 | 编码检测的 GBK 回退分支曾是死代码(Buffer.toString("utf-8") 永不抛错),导致 75% 字符乱码、grep 静默返回空。现自动识别 UTF-8/GBK/Big5 |
| ls/search 结构化 | --json 从"塞一段文本表格"改为真正的 entries[](index/name/path/isDir/size/mtime) |
| search 分页 | 新增 --limit/--page/--max-results/--fields;输出含 total/hasMore/nextPage,避免一次搜索吃掉 13 万 tokens |
| 二进制守卫 | PDF/zip/图片/音视频不再被当文本读取,直接报错并提示改用 bdp get |
| du 完整性 | capped/partial 沿路径向上传播,不再出现"capped:false 但 size 不完整";新增 --progress、depthLimit、depthCapped |
| share list 可用 | 改走网页 API,绕过引擎 panic bug |
| rm 批量 + 确认 | 支持多路径删除、--yes、结构化输出 |
| mkdir 幂等 | 目录已存在不再报失败 |
| gls nextPage | 补上 SKILL.md 一直引用却不存在的翻页字段 |
| error -3 可用 | 负数错误码此前无法执行(bdp error -- -3 现在也支持) |
| MCP 服务器 | bdp serve --mcp [--http] 暴露 23 个带 JSON Schema 的工具(含移动/重命名/删除,Agent 可自主整理) |
v1.6.0 及更早版本的行为差异详见 CHANGELOG.md。
📖 完整命令参考
网盘文件操作
bdp ls [path] 列出目录
bdp search <keyword> [-p dir] 搜索文件名
[--regex 正则] [--glob 通配符] [--any-word] [--exact]
bdp cat <path> 读取文件内容 (免下载, 限 1MB)
bdp head [-n N] <path> 读取前 N 行 (默认 20)
bdp tail [-n N] <path> 读取后 N 行 (默认 20)
bdp grep <pattern> <path> 搜索文件内容
bdp peek <path> 预览文件信息 + 前 10 行 (含 md5/ctime)
bdp preview <path> 多类型预览 (PDF文本/ZIP目录/DOCX/XLSX/EPUB/图片尺寸)
bdp dedup [path] 查重复文件 (自动反混淆md5) [--top N] [--depth N]
bdp dedup <path> --remove-duplicates --yes 删除重复副本 (走回收站, 可恢复)
bdp organize [path] --by type|year|source 内容整理归类 (默认只出计划)
[--target /归档] [--layout type-year] [--apply --yes]
bdp index build [path] 建立本地全文索引 [--include a,b] [--no-extract]
bdp index status 查看索引状态 (索引在 ~/.bdp/index/)
bdp ask <查询> 检索网盘正文 [--limit N] [-p dir] [--ext ext]
bdp get <path> [-o dir] 下载文件 (直链分块, size 校验, 断点续传)
[--resume] [--force] [--progress] [--no-verify-size] [--dry-run]
<gid>:<fs_id> 形式自动走群文件直下
bdp put <local> <remote> 上传文件 [--dry-run]
bdp mkdir <path> 创建目录
bdp rm <path> 删除文件/目录 [--dry-run]
bdp mv <src> <dst> 移动/重命名文件/目录
bdp rename <path> <newName> 只改文件名 (默认 dry-run, --yes 才改名; 不能跨目录)
bdp cp <src> <dst> 拷贝文件/目录
bdp quota 网盘配额 (总/已用/剩余)
bdp du [path] 目录容量分析 (递归统计, --depth/--top/--concurrency)
bdp recycle list / restore <id>... / clean 回收站管理 (clean 不可恢复,需 --yes)
bdp offline add <url> [--path D] 离线下载 (百度服务器代下)
bdp offline list 离线任务列表
bdp share set <path> [--pwd P] 创建分享链接 [--combined 输出带密码链接]
bdp share cancel <id>... 取消分享
bdp share list 列出分享 (受 BaiduPCS-Go v4.0.1 引擎 bug 限制)
bdp profile list / use <name> 多账号 profile 管理
bdp serve --mcp 启动 MCP 服务器 (stdio) -- 23 个带 schema 的工具
bdp serve --mcp --http [--port N] [--host H] [--token T] MCP over HTTP
(默认仅绑 127.0.0.1 + Bearer 令牌; /health 免令牌)
bdp config --set <key> <value> 设置配置项 (白名单: webTransport/maxBytes/ua/pcsPath)
bdp doctor 健康检查 (登录/配置/引擎/索引新鲜度; ok=false 时退出码 1)
bdp help [command] 帮助总览 / 单命令详情 (--json 结构化输出)群聊文件操作
bdp groups 列出所有群组
bdp gshares <gid> [--no-cache] 列出群内分享库 (自动游标翻页)
bdp gls <gid> <fs_id> [--page N] [--page-size N] [--from-uk X] [--msg-id Y]
[--parent-fs-id Z] [--no-cache] 浏览分享库内容
bdp gtree <gid> [--depth N] [--concurrency N] [--max-nodes N]
[--max-pages N] [--max-requests N] [--no-cache] 构建群目录树
bdp gsearch <gid> <keyword> 搜索群文件名 (全量遍历目录)
[--page N] [--limit N] [--depth N] [--concurrency N]
[--max-pages N] [--max-requests N] [--no-unique]
[--all|--all-results] [--timeout N] [--save-partial]
[--any-word] [--exact] [--no-cache]
bdp gdownload <gid> <fs_id>... 直接下载群文件到本地 (逆向 /api/sharedownload, 免转存)
单文件直下;多个 fs_id(同消息)自动 zip 打包下载
[-o dir] [--filename NAME] [--from-uk X] [--msg-id Y] [--no-cache]
bdp cache [clear] 查看 / 清空会话缓存 (~/.bdp/cache/)
bdp error <code> [--json] 解释错误码 (结构化: code/codeText/name/description/severity/retryable/action)
bdp error --list [--json] 列出全部已知错误码群文件下载限制说明(实测,2026-08):
- 单文件 ≤ ~20MB:直接下载 ✅
- 同消息多文件:zip 打包下载 ✅(总包 ≤ ~100MB)
- 大文件(> ~100MB):网页端受百度限制(单文件加密 / zip 报
31090 package is too large),需用官方客户端;转存接口已被百度下线(errno=-10)- 详见
docs/group-download-final-verdict.md
通用选项
当前共 39 条 CLI 命令、23 个 MCP 工具、13 个内置错误码。
--json JSON 结构化输出 (Agent 友好)
--json-file <path> JSON 写入文件 (UTF-8, 绕开控制台编码)
--verbose 进度/日志只写 stderr(bdp error:附带 internalDetail)
-n <N> 行数 (head/tail, 默认 20)
-p <path> 搜索路径 (search, 默认 /)
-i 忽略大小写 (grep)
-N 显示行号 (cat/grep)
-o <dir> 输出目录 (get)
--resume 断点续传 (get;存在部分文件时自动续传)
--force 覆盖重下 (get;先删除旧文件)
--progress 显示实时进度 + 速度 (get,stderr)
--no-verify-size 关闭下载后 size 校验 (get;默认开启)
--regex / --glob 搜索模式: 正则 / 通配符 (search)
--any-word 空格分隔关键词命中任意一个 (search/gsearch)
--exact 整名精确匹配 (search/gsearch)
--pwd <P> 分享提取码 (share set)
--combined 输出带提取码的分享链接 (share set)
--dry-run 模拟执行不落盘 (get/put/rm/dedup)
--profile <name> 切换账号 profile (全局参数,命令前/后均可)
--page <N> 页码 (gls/gsearch, 默认 1)
--page-size <N> 每页条数 (gls, 默认 50, 最大 100)
--limit <N> 每页条数 (search/gsearch 默认 50;ask 默认 20)
--depth <N> 递归深度 (gsearch 默认 1 / gtree 默认 2 / du 默认 3 / dedup 默认 12)
--concurrency <N> 并发扫描数 (gsearch/gtree 默认 4,1-8;du/dedup 默认 8;get 分块默认 3)
--max-nodes <N> 树节点上限 (gtree, 默认 2000)
--max-pages <N> 单目录最大页数 (gsearch/gtree, 默认 50, 100 条/页);preview 为 PDF 解析页数上限 (默认 200)
--max-requests <N> 单命令请求预算 (gsearch/gtree, 默认 400, 防限流)
--from-uk <X> / --msg-id <Y> 分享来源参数 (gls 子目录)
--parent-fs-id <Z> 父目录 fsId (gls, errno=-3 时回退用)
--no-unique 保留不同 msgId 的重复项 (gsearch)
--all, --all-results 忽略分页获取全部结果 (gsearch; 不限时, 慢但完整)
--timeout <N> 超时秒数,到点返回已扫到的部分结果 (gsearch; 0=不限时, 默认 0)
--save-partial 未完整时自动把已搜到的结果存为 JSON 并打印路径 (gsearch; 配 --json-file 时写该文件)
--any-word 空格分隔关键词命中任意一个即可 (gsearch; 默认=全部命中 AND)
--exact 按文件名精确匹配,忽略路径前缀 (gsearch; 大小写不敏感)
--no-cache 禁用会话缓存 (gsearch/gtree/gshares/gls)全局选项位置自由:
--json/--verbose/--no-meta/--legacy-json/--profile <name>/--json-file <path>都可以放在命令之前,也可以放在命令之后,布尔开关与带值选项可任意交错 (如bdp --json --profile x error -3)。带值选项的取值不能以-开头(-x和--json都不行)—— 否则报错退出 1。只给开关不给命令 → 退出码 1:
bdp --json(给了全局选项但没给命令)会报「缺少命令」并退出码 1,--json下返回 JSON 错误体。裸跑bdp(一个参数都不给)仍打印帮助并退出码 0。同步引擎路径:已清零(v1.11.0,v1.11.1 经四路审核复核)—— 此前 15 条命令走同步引擎 (
spawnSync冻结整个事件循环,引擎挂死 = MCP 服务器整体不可用)。现已全部改为异步 spawn, 写操作不再冻住事件循环。读操作默认 120s、写操作 600s;登录时同步引擎凭证单独限 30s。 到点会杀掉该子进程,只有这一次调用失败。
curl 也不再冻住事件循环(v1.11.3):
webTransport=curl的 Web API / Range、群文件下载、预览 HEAD 兜底都改成异步 spawn。 下载时限仍是单文件约 3600s、打包约 7200s,但只占一次调用,不再卡住整个进程。 Windows 交互终端启动时仍会同步查一次代码页(chcp),耗时可以忽略。
MCP 并发闸门:stdio 与 HTTP 的并发工具调用默认上限 4(
BDP_MCP_MAX_CONCURRENCY)。 没设置或不是数字 → 4;设成 0 或负数 → 1。 口径是工具调用总数,不是引擎进程数:dedup / organize / ask 不调引擎,quota 走 BaiduPCS-Go,四者都各占一个槽位。
get 下载可靠性(v1.2.0)
bdp get 已从裸跑 BaiduPCS-Go 升级为直链分块下载 + 三重保障(实测,2026-08):
bdp get /文档/大文件.zip # 下载到当前目录,自动 size 校验
bdp get /文档/大文件.zip -o ./dl # 下载到指定目录 (自动创建)
bdp get /文档/大文件.zip --resume # 断点续传(存在部分文件时自动续传,无需该参数)
bdp get /文档/大文件.zip --force # 已有文件时覆盖重下
bdp get /文档/大文件.zip --progress # 实时进度 + 速度 (stderr)
bdp get /文档/大文件.zip --json # JSON 元信息: {path, localPath, size, md5, remoteMd5,
# md5Match, md5Obfuscated, dlinkExpiry, verified,
# skipped, resumed, avgSpeedBps}- size 校验(默认开启,
--no-verify-size可关):下载后比对远端/本地字节数,0 字节或大小不符即报错并保留文件供排查 - 断点续传:curl 有界 Range 分块下载(4MB/块,实测部分 CDN 节点只接受 ≤5MB 的有界 Range,无界请求会 403),每块失败自动换新 dlink 重试;中断后重跑同一命令即从断点继续
- 并发分块:大文件(>32MB)默认 3 路并发分块(
--concurrency 1可回串行)。实测百度对非 SVIP 是账号级限速,并发无法突破总量限速,但多 CDN 节点并行能提升稳定性(坏节点/单连接抖动不影响整体) - md5 软校验:百度
/api/list返回的 md5 是混淆键(含o/t等非 hex 字符,非内容哈希),无法作为完整性依据;CLI 计算本地 md5 供流水线比对,md5Obfuscated:true标注远端不可信 - 默认保存位置:
-o指定目录,否则当前目录(与gdownload一致) - 目录下载 / 获取 dlink 失败等边界场景自动回退 BaiduPCS-Go 引擎(无校验/续传)
多账号 profile(v1.3.0)
多个百度账号切换,认证字段按 profile 隔离(pcsPath/ua 等配置保持全局):
bdp --profile svip login --bduss X --stoken Y # 登录到 svip profile
bdp profile list # 列出所有 profile
bdp --profile svip quota # 用 svip 账号执行命令
bdp login --profile 备份 ... # --profile 也可放命令后
bdp profile unset # 切回全局账号- 存储在
~/.bdp/config.json的profiles+activeProfile字段;无 profile 时行为与旧版完全一致 bdp whoami会显示当前 profile
容量管理(v1.6.0)
网盘容量见底时的排查三件套(百度无服务端目录大小接口,du 走 /api/list 并发遍历):
bdp quota # 总/已用/剩余(实测 99.78% 时优先排查下面两项)
bdp recycle list # 回收站:删除的文件保留 60 天仍占容量,先看这里
bdp recycle restore <fs_id>... # 还原误删
bdp recycle clean --yes # 清空回收站释放容量(不可恢复,非交互环境必须加 --yes)
bdp du / # 顶层目录容量分布(找空间大户)
bdp du /玄学 --depth 5 --top 20 # 深扫指定目录(深度封顶的子目录标 [深度封顶])
bdp du / --json # JSON 输出(Agent 可解析)注意:
du全盘扫描较慢(API 限制,深度 4 全盘约 10 分钟),建议先顶层后深扫;若 quota 已用量与全盘可见内容差距巨大,优先怀疑百度扩容/福利空间到期(总量缩水,历史总量需在网页端空间明细核实)。
🤖 Agent 集成示例
所有命令支持 --json 输出,适合 AI Agent 直接调用和解析。Agent 运行时发现用法:
bdp help --json # 全部命令的 usage/desc/options/examples(结构化)
bdp help get --json # 单个命令的完整定义
bdp help gsearch --json # 群搜索的全部选项# Agent 获取群组列表 (JSON)
bdp groups --json
# → [{"gid":"539478953581833690","name":"国学文化SVIP13",...}]
# Agent 读取文件内容 (JSON)
bdp head -n 5 /文档/data.csv --json
# → {"path":"/文档/data.csv","lines":5,"content":["header","row1","row2",...]}
# Agent 搜索群文件 (JSON)
bdp gsearch 539478953581833690 "倪海厦" --json
# → [{"name":"N 倪海厦","path":"/全店svip200位大师课(共16T)/N 倪海厦","isDir":true,...}]作为 Node.js 库使用
const { pan, group } = require('baiduwangpan-cli');
// 免下载读取文件
const content = pan.cat('/文档/data.json');
// 搜索群聊文件
const results = await group.searchFiles('539478953581833690', '倪海厦');🏗️ 架构
┌─────────────────────────────────────────────────────┐
│ Agent / 用户 │
├─────────────┬───────────────────────────────────────┤
│ CLI 模式 │ 库模式 (require) │
│ bdp <cmd> │ const {pan, group} = require() │
├─────────────┴───────────────────────────────────────┤
│ bin/bdp.js │
│ (统一命令解析 + 路由) │
├──────────────────┬──────────────────────────────────┤
│ lib/pan.js │ lib/group.js │
│ 全盘文件操作 │ 群聊文件浏览 + 下载 │
├──────────────────┼──────────────────────────────────┤
│ BaiduPCS-Go │ lib/http.js (curl / browser) │
│ (BDUSS 认证) │ mbox API (逆向) │
│ locate → dlink │ /mbox/group/listshare │
│ upload/download │ /mbox/msg/shareinfo │
│ │ /api/sharedownload → dlink │
├──────────────────┴──────────────────────────────────┤
│ 百度网盘 CDN / API │
└─────────────────────────────────────────────────────┘免下载读取原理
bdp cat /文档/报告.txt
│
├── BaiduPCS-Go locate /文档/报告.txt
│ → 获取 CDN 直链 dlink (有效期 8h)
│
├── curl -r 0-1048575 <dlink>
│ → HTTP Range 请求,只读取前 1MB
│ → 百度 CDN 返回 206 Partial Content
│
└── stdout 输出文件内容
→ Agent 直接读取,无需下载整个文件群聊 API 链路(逆向 /mbox/)
bdp groups bdp gshares <gid>
│ │
├── /mbox/group/list ├── /mbox/group/listshare
│ → 获取全部群组 (gid) │ → 获取分享库 (msg_id + from_uk + fs_id)
│ │ └ has_more=1 时按 last_msg_time 游标翻页
└───────────────────────────────────┘
↓
bdp gls <gid> <fs_id> bdp gsearch <gid> "关键词"
│ │
├── /mbox/msg/shareinfo ├── 全量遍历: shareinfo 自动翻页 (每页上限 100)
│ → 浏览文件/子目录 │ → 目录级并发扫描 + 磁盘缓存
↓ ↓
文件列表 (名称/大小/类型/fs_id) 匹配结果逆向实测结论(2026-08):
- 群聊文件没有服务端搜索接口(
listshare/shareinfo的key/keyword参数被忽略,/api/search不支持群维度)——网页端搜索同样是客户端遍历,gsearch走的是同一条路。 shareinfo每页硬上限 100 条(num>100不返回更多),page翻页可用 →gsearch/gtree自动全页遍历,不再漏数据。- 高频调用会触发限流,表现为
errno=-3、self-echo(errno=0但返回目录自身)、或空列表;工具自动退避重试、连续限流停止扫描,重跑命令即续扫(--max-requests可控制单命令请求预算,默认 400)。 - 群文件路径可能含非法百分号编码(裸
%),直接decodeURIComponent会抛URIError报废整个目录 → 已改为安全解码。 gsearch/gtree/gshares默认启用磁盘会话缓存(目录 30min / 分享 5min,~/.bdp/cache/,--no-cache关闭、bdp cache clear清理)——重复搜索秒回,深扫续扫收敛。
📁 项目结构
baiduwangpan-cli/
├── package.json # npm 配置 (bin: bdp,唯一入口)
├── bin/
│ └── bdp.js # CLI 入口 (统一命令解析 + 命令注册表)
├── lib/
│ ├── index.js # 库导出
│ ├── config.js # 配置管理 (~/.bdp/config.json,含多账号 profile)
│ ├── http.js # 网页 API 双传输 (curl / browser)
│ ├── browser-login.js # 浏览器登录、持久 profile 与 CDP 请求
│ ├── pan.js # 网盘操作 (BaiduPCS-Go 桥接 + 直链分块下载)
│ ├── group.js # 群聊操作 (逆向 mbox API)
│ ├── pcs-extra.js # 引擎扩展命令 (mv/cp/quota/offline/share)
│ ├── name-match.js # 文件名匹配 (glob/正则/AND/OR)
│ ├── table.js # pcstable 表格解析 (CJK 显示宽对齐)
│ ├── file-type.js # 二进制文件类型识别 (魔数)
│ ├── mcp.js # MCP 服务器 (stdio + HTTP, JSON-RPC 2.0)
│ └── console.js # Windows 控制台编码兜底 (chcp 65001)
├── test/ # Node.js 回归测试
├── skills/
│ └── baiduwangpan/ # Agent Skill 源文件 (SKILL.md + reference + scripts)
└── baiduwangpan-skill.zip # Agent Skill 打包 (Releases 附件)唯一入口:
bdp命令(bin/bdp.js)。历史原型bdp.py/bdp.js/bdp-group.js已删除(git 历史可查),避免多入口行为不一致。Agent 不确定命令用法时用bdp help <命令> --json查询。
🤖 Agent Skill 使用
本仓库附带一个标准格式的 Agent Skill,让 Claude Code / Codex / OpenClaw / Cursor 等 Agent 通过自然语言操作百度网盘。
安装 Skill
从 Releases 下载 baiduwangpan-skill.zip,或直接复制仓库 skills/baiduwangpan/ 文件夹:
# 各平台 skills 目录
~/.claude/skills/ # Claude Code
~/.codex/skills/ # Codex CLI
~/.config/opencode/skills/ # OpenCode
# 或对应 Agent 的 skills 目录Skill 使用
Agent 加载 skill 后,自然语言即可驱动(skill 会自动触发):
用户: 看看我网盘里有什么
用户: 在群里找倪海厦的资料
用户: 读一下 /文档/data.csv 前几行
用户: 搜索网盘里所有报告文件skill 会自动执行 bdp 命令并返回结构化结果(含 --json 输出)。
Skill 内容
skills/baiduwangpan/
├── SKILL.md # 技能定义(触发规则 + 命令规范 + 安全边界)
├── reference/
│ ├── commands.md # 完整命令参考
│ ├── authentication.md # 凭证获取与配置
│ ├── examples.md # Agent 使用示例 + JSON 输出格式
│ └── troubleshooting.md # 故障排查
└── scripts/
├── setup.sh # macOS/Linux 自动安装
└── setup.ps1 # Windows 自动安装⚠️ 注意事项
- BDUSS 有效期:Cookie 会过期,失效后重新执行
bdp login - 下载限速:非 SVIP 用户下载受百度限速策略限制
- cat 限制:为防止误读超大文件,
cat默认限制 1MB,可通过BDP_MAX_CAT_BYTES环境变量调整 - 群聊文件:群聊 API 为逆向获取,可能随百度服务端变更而失效
- share list:v1.7.0 起改走网页 API(BaiduPCS-Go v4.0.1 引擎的
share list有 panic bug,网页 API 正常) - rm 高危:非交互环境(Agent/管道)执行
bdp rm必须显式加--yes,否则拒绝执行并返回退出码 1;交互终端会弹 y/N 确认 - config 脱敏:
bdp config/bdp config --json默认对 BDUSS/STOKEN 脱敏("redacted": true),仅--show-secrets才输出原值 - du 的 size 可能偏小:百度没有服务端目录大小接口,
du靠递归求和,默认只扫 3 层;JSON 里partial: true表示因深度封顶而不完整,实际占用以bdp quota为准 - PowerShell 中文乱码:CLI 启动时自动
chcp 65001(仅 TTY 且非 UTF-8 代码页时),中文正常显示;管道/重定向场景无副作用 - 1.1.0 升级:若引擎丢失(postinstall 网络失败),CLI 会自动发现
BaiduPCS-Go-v*版本子目录中的二进制;config 里失效的绝对pcsPath也会自动回退到自动发现,无需手改配置
🤝 致谢
- BaiduPCS-Go — 强大的百度网盘 Go 客户端,本工具的底层引擎
- hustuhao/bdntoy — mbox API 逆向参考
- 所有百度网盘逆向工程社区的贡献者
