baiduwangpan-cli 1.1.3 → 1.1.5

package/README.md

@@ -2,7 +2,7 @@
 
 # baiduwangpan-cli
 
-**百度网盘 CLI — 全盘读写 · 免下载读取 · 群聊文件浏览**
+**百度网盘 CLI — 全盘读写 · 免下载读取 · 群聊文件浏览/下载**
 
 专为 AI Agent 设计的百度网盘命令行工具
 
@@ -21,7 +21,7 @@
 
 - **🗂️ 全盘访问** — 不受 `/apps/` 目录限制，读写网盘任意路径
 - **📄 免下载读取** — 通过 HTTP Range 直接读取文件内容到 stdout，无需下载整个文件
-- **👥 群聊文件浏览** — 逆向 mbox API，列出群组、浏览群内分享库、搜索群文件
+- **👥 群聊文件浏览 + 下载** — 逆向 mbox API，列出群组、浏览群内分享库、搜索群文件，并支持**直接下载群文件到本地**（免转存）
 - **🤖 Agent 友好** — 所有命令支持 `--json` 结构化输出，零解析成本
 - **🔧 双模式** — 既是 CLI 工具，也可作为 Node.js 库 `require()` 使用
 - **🔐 凭证安全** — 配置存储在 `~/.bdp/config.json`，不写入代码或日志
@@ -43,6 +43,7 @@
 | **群内分享库** | `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]` | 查看 / 清空会话缓存 |
 
@@ -113,7 +114,8 @@ bdp cat /文档/config.json
 bdp groups
 bdp gshares 539478953581833690
 bdp gls 539478953581833690 742474845517885
-bdp gsearch 539478953581833690 "倪海厦"
+# 下载群文件到本地 (免转存)
+bdp gdownload 539478953581833690 954615608563687 -o ./downloads
 ```
 
 ## 📖 完整命令参考
@@ -148,9 +150,18 @@ bdp gsearch <gid> <keyword>      搜索群文件名 (全量遍历目录)
                                   [--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/)
 ```
 
+> **群文件下载限制说明**（实测，2026-08）：
+> - 单文件 ≤ ~20MB：直接下载 ✅
+> - 同消息多文件：zip 打包下载 ✅（总包 ≤ ~100MB）
+> - 大文件（> ~100MB）：网页端受百度限制（单文件加密 / zip 报 `31090 package is too large`），需用官方客户端；转存接口已被百度下线（`errno=-10`）
+> - 详见 `docs/group-download-final-verdict.md`
+
 ### 通用选项
 
 ```
@@ -224,12 +235,13 @@ const results = await group.searchFiles('539478953581833690', '倪海厦');
 │              (统一命令解析 + 路由)                    │
 ├──────────────────┬──────────────────────────────────┤
 │    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                      │
 └─────────────────────────────────────────────────────┘

package/bin/bdp.js

@@ -21,6 +21,7 @@
  *   bdp gshares <gid>              列出群内分享库
  *   bdp gls <gid> <fs_id>          浏览分享库内容
  *   bdp gsearch <gid> <keyword>    搜索群文件
+ *   bdp gdownload <gid> <fs_id>    直接下载群文件到本地（免转存）
  *
  * 配置:
  *   bdp login --bduss X --stoken Y  设置认证
@@ -590,6 +591,33 @@ cmds.gsearch = async (args, json) => {
   }
 };
 
+cmds.gdownload = async (args, json) => {
+  const gid = args._[0];
+  const fsIds = args._.slice(1);
+  if (!gid || fsIds.length === 0) { console.error("Usage: bdp gdownload <gid> <fs_id> [fs_id2 ...] [-o dir] [--from-uk X] [--msg-id Y] [--filename NAME]"); process.exit(1); }
+
+  const opts = {
+    cache: args.flags.noCache !== true,
+  };
+  if (args.flags.fromUk) opts.fromUk = args.flags.fromUk;
+  if (args.flags.msgId) opts.msgId = args.flags.msgId;
+  if (args.flags.o) opts.outDir = args.flags.o;
+  if (args.flags.filename) opts.filename = args.flags.filename;
+
+  verboseLog(args, `gdownload gid=${gid} fsIds=[${fsIds.join(",")}] outDir=${opts.outDir || process.cwd()} filename=${opts.filename || "auto"} fromUk=${opts.fromUk || "auto"} msgId=${opts.msgId || "auto"}`);
+
+  // 单文件 → 直接下载；多 fs_id（同一分享消息）→ zip 打包下载（逆向 type=batch）
+  const result = fsIds.length === 1
+    ? await group.downloadFile(gid, fsIds[0], opts)
+    : await group.downloadFiles(gid, fsIds, opts);
+
+  output(
+    { path: result.path, name: result.name, size: result.size, fsId: fsIds.length === 1 ? fsIds[0] : undefined, count: result.count, fromUk: result.fromUk, msgId: result.msgId },
+    json,
+    () => console.log(`✅ 已下载 ${result.size} 字节 → ${result.path}${result.count ? `（${result.count} 个文件 zip 打包）` : ""}`)
+  );
+};
+
 cmds.cache = async (args, json) => {
   const action = args._[0] || "info";
   const { clearGroupCache } = group;
@@ -667,6 +695,9 @@ GROUP CHAT OPERATIONS (群聊)
                              [--max-pages N] [--max-requests N] [--no-unique]
                              [--all|--all-results] [--timeout N] [--save-partial]
                              [--any-word] [--exact] [--no-cache]
+  gdownload <gid> <fs_id>...  Direct download group files (免转存, 逆向 sharedownload API)
+                             single fs_id → direct file; multiple fs_ids → zip 打包 (type=batch)
+                             [--from-uk X] [--msg-id Y] [-o dir] [--filename NAME]
   cache [clear]              Show cache info or clear session cache
   error <code>               Explain an error code (e.g. -3)
 
@@ -713,6 +744,8 @@ EXAMPLES
   bdp gls 539478953581833690 292608024165826 --from-uk 2642611875 --msg-id 5069931974377329661 --json
   bdp gsearch 539478953581833690 "倪海厦" --limit 20 --json
   bdp gsearch 539478953581833690 "古籍" --page 2 --limit 20 --json-file result.json
+  bdp gdownload 539478953581833690 954615608563687 -o ./downloads --from-uk 1101635869133 --msg-id 713945176566573051
+  bdp gdownload 539478953581833690 527948256537856 986718405708023 -o ./zips   # 多文件 zip 打包下载
   bdp error -3`;
 
 async function main() {

package/lib/group.js

@@ -443,6 +443,186 @@ async function listFiles(gid, fsId, options = {}) {
   );
 }
 
+// ── 群文件下载 (gdownload) ─────────────────────────────
+//
+// 逆向结论（2026-08-12）：
+//   - /mbox/msg/transfer 转存已被百度拒绝（非空目录一律 errno=-10，UI 已移除保存按钮）
+//   - 新版 IM 前端的下载链路是 POST /api/sharedownload?sign=&timestamp=
+//     （sign/timestamp 留空即可），product=mbox 参数族，登录态直接返回可下载的 dlink
+//   - dlink 有 8 小时有效期；只支持单文件（目录 fs_id 返回的 dlink 为空）
+
+// 解析 fs_id 的来源（fromUk/msgId）：显式优先；顶层分享自动解析；否则报错提示
+// 复用逻辑与 listFiles 一致，保证 gdownload 与 gls/gsearch 参数同源
+async function resolveShareSource(gidS, fsIdS, options = {}, { cache }) {
+  let fromUkS = toStr(options.fromUk || "");
+  let msgIdS = toStr(options.msgId || "");
+  if (!fromUkS || !msgIdS) {
+    const shares = await listShares(gidS, { cache });
+    const match = shares.find((s) => s.fsId === fsIdS);
+    if (!match) {
+      throw new Error(
+        `Cannot determine fromUk/msgId for fsId ${fsIdS} (not a top-level share). ` +
+        `Pass --from-uk and --msg-id explicitly (use bdp gsearch/gsearch --json to get them).`
+      );
+    }
+    fromUkS = match.fromUk;
+    msgIdS = match.msgId;
+  }
+  return { fromUk: fromUkS, msgId: msgIdS };
+}
+
+// 获取群文件直链。返回 { dlink, name, size, isDir, md5, path, fsId, fromUk, msgId }
+async function getShareDlink(gid, fsId, options = {}) {
+  const gidS = toStr(gid);
+  const fsIdS = toStr(fsId);
+  const cache = options.cache === true;
+
+  const { fromUk, msgId } = await resolveShareSource(gidS, fsIdS, options, { cache });
+  const bdstoken = await getBdstoken();
+  const url = `${http.PAN_BASE}/api/sharedownload?sign=&timestamp=&clienttype=0&app_id=${http.APP_ID}&web=1&bdstoken=${bdstoken}`;
+  const body = new URLSearchParams({
+    uk: fromUk,
+    product: "mbox",
+    encrypt: "0",
+    primaryid: msgId,
+    fid_list: JSON.stringify([fsIdS]),
+    extra: JSON.stringify({ type: "group", gid: gidS }),
+  }).toString();
+
+  const data = await http.webJson(url, { method: "POST", body });
+  if (data.errno !== 0) {
+    throw new Error(`API error: errno=${data.errno} (msg_id ${msgId} 不属于群 ${gidS} 或分享已失效)`);
+  }
+  const item = (data.list || [])[0];
+  if (!item) throw new Error(`No file info returned for fsId ${fsIdS}`);
+
+  const result = {
+    dlink: item.dlink || "",
+    name: item.server_filename || "",
+    size: parseInt(item.size || "0", 10),
+    isDir: item.isdir === 1 || item.isdir === "1",
+    md5: item.md5 || "",
+    path: safeDecode(item.path || ""),
+    fsId: toStr(item.fs_id),
+    fromUk,
+    msgId,
+  };
+  // 目录的 dlink 为无效串（实测 "&clienttype=0"），先于 dlink 判空检查
+  if (result.isDir) {
+    throw new Error(
+      `fsId ${fsIdS} 是目录（${result.name}）。sharedownload 只支持单文件下载。` +
+      `请用 bdp gls <gid> <fs_id> 或 bdp gsearch <gid> <关键词> 找到具体文件后下载。`
+    );
+  }
+  if (!result.dlink) {
+    throw new Error(`No dlink returned for fsId ${fsIdS}（分享可能已失效或禁止下载）`);
+  }
+  return result;
+}
+
+// 下载群文件到本地。options: { outDir, filename, fromUk, msgId, ua }
+// 返回 { path, name, size, dlink, fromUk, msgId }
+async function downloadFile(gid, fsId, options = {}) {
+  const info = await getShareDlink(gid, fsId, options);
+  const { spawnSync } = require("child_process");
+  const fs = require("fs");
+  const path = require("path");
+
+  const outDir = options.outDir || process.cwd();
+  const filename = options.filename || info.name || `fs_${info.fsId}`;
+  const outPath = path.join(outDir, filename);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  // dlink 校验 UA：netdisk 客户端 UA 会返回 118 字节错误页，浏览器 UA 正常（实测）
+  const args = [
+    "-s", "-L",
+    "-H", `User-Agent: ${options.ua || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}`,
+    "-o", outPath,
+    "--max-time", String(options.timeoutSec || 3600),
+    info.dlink,
+  ];
+  const result = spawnSync("curl", args, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024, timeout: (options.timeoutSec || 3600) * 1000 });
+  if (result.error) throw new Error(`Download failed: ${result.error.message}`);
+
+  let size = 0;
+  try { size = fs.statSync(outPath).size; } catch {}
+  if (info.size && size !== info.size) {
+    throw new Error(
+      `Download size mismatch: got ${size} bytes, expected ${info.size} bytes. ` +
+      `dlink 可能已过期（有效期 8h），请重试。`
+    );
+  }
+  return { path: outPath, name: filename, size, dlink: info.dlink, fromUk: info.fromUk, msgId: info.msgId };
+}
+
+// ── 群文件批量打包下载 (gdownload 多 fs_id → zip) ───────
+//
+// 逆向结论（2026-08-12 实测）：
+//   - sharedownload 单文件 >~20MB 时返回加密 list（无法解密，key 未破解）
+//   - type=batch 时返回明文 zip 打包链接（method=batchdownload&zipcontent=...），
+//     小文件打包实测可用（10MB zip 完整下载）；超大文件报 error_code=31090 "package is too large"
+//   - zip 打包按 msg_id 归组：所有 fs_id 必须属于同一条分享消息
+
+// 获取多文件 zip 打包直链。options: { fromUk, msgId, cache }
+async function getShareZipDlink(gid, fsIds, options = {}) {
+  const gidS = toStr(gid);
+  const fsIdList = fsIds.map(toStr);
+  if (fsIdList.length < 2) throw new Error(`getShareZipDlink needs >= 2 fs_ids`);
+
+  // 来源以第一个 fs_id 为准（其余视为同一分享消息内的文件）
+  const { fromUk, msgId } = await resolveShareSource(gidS, fsIdList[0], options, { cache: options.cache === true });
+  const bdstoken = await getBdstoken();
+  const url = `${http.PAN_BASE}/api/sharedownload?sign=&timestamp=&clienttype=0&app_id=${http.APP_ID}&web=1&bdstoken=${bdstoken}`;
+  const body = new URLSearchParams({
+    uk: fromUk,
+    product: "mbox",
+    encrypt: "0",
+    type: "batch",
+    primaryid: msgId,
+    fid_list: JSON.stringify(fsIdList),
+    extra: JSON.stringify({ type: "group", gid: gidS }),
+  }).toString();
+
+  const data = await http.webJson(url, { method: "POST", body });
+  if (data.errno !== 0) {
+    throw new Error(`API error: errno=${data.errno} (zip batch)`);
+  }
+  if (!data.dlink) {
+    throw new Error(`No zip dlink returned for ${fsIdList.length} files`);
+  }
+  return { dlink: data.dlink, fromUk, msgId, count: fsIdList.length };
+}
+
+// 批量打包下载。options: { outDir, filename, fromUk, msgId, ua }
+async function downloadFiles(gid, fsIds, options = {}) {
+  const { dlink, fromUk, msgId, count } = await getShareZipDlink(gid, fsIds, options);
+  const { spawnSync } = require("child_process");
+  const fs = require("fs");
+  const path = require("path");
+
+  const outDir = options.outDir || process.cwd();
+  const filename = options.filename || `bdp-group-${count}files.zip`;
+  const outPath = path.join(outDir, filename);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const args = [
+    "-s", "-L",
+    "-H", `User-Agent: ${options.ua || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}`,
+    "-o", outPath,
+    "--max-time", String(options.timeoutSec || 7200),
+    dlink,
+  ];
+  const result = spawnSync("curl", args, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024, timeout: (options.timeoutSec || 7200) * 1000 });
+  if (result.error) throw new Error(`Download failed: ${result.error.message}`);
+
+  let size = 0;
+  try { size = fs.statSync(outPath).size; } catch {}
+  if (size === 0) {
+    throw new Error(`Zip download failed (0 bytes). dlink 可能已过期或包太大（error_code 31090）。`);
+  }
+  return { path: outPath, name: filename, size, dlink, fromUk, msgId, count };
+}
+
 // ── 目录树 (gtree) ────────────────────────────────────
 
 async function treeFiles(gid, options = {}) {
@@ -751,5 +931,6 @@ async function searchFiles(gid, keyword, options = {}) {
 
 module.exports = {
   listGroups, listShares, listFiles, treeFiles, searchFiles,
+  getShareDlink, downloadFile, getShareZipDlink, downloadFiles,
   ShareApiError, describeErrno2131, clearGroupCache,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baiduwangpan-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "百度网盘 CLI — 全盘读写 · 免下载读取文件内容 · 群聊文件浏览 (Agent 友好)",
   "main": "lib/index.js",
   "bin": {