baiduwangpan-cli 1.1.2 → 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
 ```
 
 ## 📖 完整命令参考
@@ -146,10 +148,20 @@ bdp gtree <gid> [--depth N] [--concurrency N] [--max-nodes N]
 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] [--no-cache]
+                                  [--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`
+
 ### 通用选项
 
 ```
@@ -175,6 +187,8 @@ bdp cache [clear]                查看 / 清空会话缓存 (~/.bdp/cache/)
 --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)
 ```
 
@@ -221,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  设置认证
@@ -91,6 +92,10 @@ function parseArgs(argv) {
       opts.flags.timeoutMs = parseInt(argv[++i], 10) || 0;
     } else if (arg === "--save-partial") {
       opts.flags.savePartial = true;
+    } else if (arg === "--any-word") {
+      opts.flags.anyWord = true;
+    } else if (arg === "--exact") {
+      opts.flags.exact = true;
     } else if (arg === "-n" || arg === "--lines") {
       opts.flags.n = parseInt(argv[++i], 10) || 20;
     } else if (arg === "-p" || arg === "--path") {
@@ -483,6 +488,8 @@ cmds.gsearch = async (args, json) => {
     concurrency: args.flags.concurrency || 4,
     unique: args.flags.unique !== false,
     all: args.flags.all === true,
+    exact: args.flags.exact === true,
+    anyWord: args.flags.anyWord === true,
     timeoutMs: args.flags.timeoutMs || (args.flags.timeout ? args.flags.timeout * 1000 : 0),
     depth: args.flags.depth || 1,
     maxPages: args.flags.maxPages || 50,
@@ -536,7 +543,7 @@ cmds.gsearch = async (args, json) => {
     );
   };
 
-  verboseLog(args, `gsearch gid=${gid} keyword="${keyword}" page=${opts.page} limit=${opts.limit} concurrency=${opts.concurrency} unique=${opts.unique} all=${opts.all} timeoutMs=${opts.timeoutMs} savePartial=${savePartial} depth=${opts.depth} maxPages=${opts.maxPages} maxRequests=${opts.maxRequests} cache=${opts.cache}`);
+  verboseLog(args, `gsearch gid=${gid} keyword="${keyword}" page=${opts.page} limit=${opts.limit} concurrency=${opts.concurrency} unique=${opts.unique} all=${opts.all} exact=${opts.exact} anyWord=${opts.anyWord} timeoutMs=${opts.timeoutMs} savePartial=${savePartial} depth=${opts.depth} maxPages=${opts.maxPages} maxRequests=${opts.maxRequests} cache=${opts.cache}`);
   const result = await group.searchFiles(gid, keyword, opts);
 
   if (result.partial) {
@@ -584,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;
@@ -659,7 +693,11 @@ GROUP CHAT OPERATIONS (群聊)
   gsearch <gid> <keyword>    Search group file names (全量遍历目录, 缓存命中秒回)
                              [--page N] [--limit N] [--depth N] [--concurrency N]
                              [--max-pages N] [--max-requests N] [--no-unique]
-                             [--all|--all-results] [--timeout N] [--save-partial] [--no-cache]
+                             [--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)
 
@@ -692,6 +730,8 @@ OPTIONS
   --all, --all-results        Fetch all results, no paging (gsearch; slow but never truncates)
   --timeout <N>               Abort after N seconds and return partial results (gsearch; 0=unlimited)
   --save-partial              Auto-save partial results to JSON when scan is incomplete (gsearch)
+  --any-word                  Match ANY of the space-separated keywords (OR) (gsearch; default=ALL)
+  --exact                     Match exact file name (case-insensitive) instead of substring (gsearch)
 
 EXAMPLES
   bdp login --bduss abc123 --stoken def456
@@ -704,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 = {}) {
@@ -514,7 +694,25 @@ async function treeFiles(gid, options = {}) {
 
 async function searchFiles(gid, keyword, options = {}) {
   const gidS = toStr(gid);
-  const kw = keyword.toLowerCase();
+
+  // 关键词解析：空格分隔多关键词。
+  //  - 默认（all）：每个词都要出现（AND，可换序）→ "玄空 飞星" 只命中同时含两者的名字（精确收窄）
+  //  - --any-word：任一词出现即可（OR，更宽）→ "玄空 飞星" 命中含"玄空"或"飞星"的名字
+  //  - --exact：整名精确相等（最严格）；单关键词默认仍是子串包含（兼容旧行为）
+  const rawKw = String(keyword).toLowerCase();
+  const words = rawKw.split(/\s+/).filter(Boolean);
+  const matchMode = options.exact ? "exact" : (options.anyWord ? "any" : "all");
+  const matchesName = (name) => {
+    const n = String(name || "").toLowerCase();
+    if (matchMode === "exact") {
+      // 精确匹配按文件名（去掉路径前缀），顶层分享 name 形如 "/xxx"，子目录文件 name 无前缀
+      const base = n.includes("/") ? n.slice(n.lastIndexOf("/") + 1) : n;
+      return base === rawKw;
+    }
+    if (words.length <= 1) return n.includes(rawKw);
+    if (matchMode === "any") return words.some((w) => n.includes(w));
+    return words.every((w) => n.includes(w));
+  };
 
   const limit = options.limit || 50;
   const page = options.page || 1;
@@ -570,7 +768,7 @@ async function searchFiles(gid, keyword, options = {}) {
   for (const share of shares) {
     if (finished) break;
     if (!share.isDir) scannedShares++;
-    if (share.name.toLowerCase().includes(kw)) {
+    if (matchesName(share.name)) {
       pushIfMatch({
         name: share.name,
         path: share.name,
@@ -617,7 +815,7 @@ async function searchFiles(gid, keyword, options = {}) {
               maxPages, cache, budget, throttleState,
             });
             if (cached) cachedDirs++;
-            const matches = files.filter((f) => f.name.toLowerCase().includes(kw));
+            const matches = files.filter((f) => matchesName(f.name));
             const subDirs = files.filter((f) => f.isDir);
             return { matches, subDirs };
           } catch (e) {
@@ -733,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.2",
+  "version": "1.1.5",
   "description": "百度网盘 CLI — 全盘读写 · 免下载读取文件内容 · 群聊文件浏览 (Agent 友好)",
   "main": "lib/index.js",
   "bin": {