baiduwangpan-cli 1.0.1 → 1.1.0

package/README.md

@@ -229,18 +229,25 @@ 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>
-                │
-                ├── /mbox/msg/shareinfo
-                │   → 浏览文件/子目录 (分页)
-                │   → 递归遍历目录树
-                ↓
-            文件列表 (名称/大小/类型/fs_id)
+        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` 但返回目录自身）、或空列表；工具自动退避重试、连续限流停止扫描，重跑命令即续扫。
+- 群文件路径可能含**非法百分号编码**（裸 `%`），直接 `decodeURIComponent` 会抛 `URIError` 报废整个目录 → 已改为安全解码。
+- `gsearch`/`gtree`/`gshares` 默认启用**磁盘会话缓存**（目录 30min / 分享 5min，`~/.bdp/cache/`，`--no-cache` 关闭、`bdp cache clear` 清理）——重复搜索秒回，深扫续扫收敛。
+
 ## 📁 项目结构
 
 ```

package/bin/bdp.js

@@ -52,12 +52,38 @@ function output(data, jsonFlag, formatter) {
   }
 }
 
+function emitJson(data, args) {
+  const json = JSON.stringify(data, null, 2);
+  if (args.flags.jsonFile) {
+    require("fs").writeFileSync(args.flags.jsonFile, json, "utf-8");
+    console.log(args.flags.jsonFile);
+  } else {
+    console.log(json);
+  }
+}
+
+function verboseLog(args, msg) {
+  if (args.flags.verbose) process.stderr.write(`[verbose] ${msg}\n`);
+}
+
 function parseArgs(argv) {
   const opts = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--json") {
       opts.flags.json = true;
+    } else if (arg === "--legacy-json") {
+      opts.flags.legacyJson = true;
+    } else if (arg === "--json-file") {
+      opts.flags.jsonFile = argv[++i];
+    } else if (arg === "--verbose") {
+      opts.flags.verbose = true;
+    } else if (arg === "--unique") {
+      opts.flags.unique = true;
+    } else if (arg === "--no-unique") {
+      opts.flags.unique = false;
+    } else if (arg === "--all") {
+      opts.flags.all = true;
     } else if (arg === "-n" || arg === "--lines") {
       opts.flags.n = parseInt(argv[++i], 10) || 20;
     } else if (arg === "-p" || arg === "--path") {
@@ -76,6 +102,28 @@ function parseArgs(argv) {
       opts.flags.stoken = argv[++i];
     } else if (arg === "--page") {
       opts.flags.page = parseInt(argv[++i], 10) || 1;
+    } else if (arg === "--page-size") {
+      opts.flags.pageSize = parseInt(argv[++i], 10) || 50;
+    } else if (arg === "--limit") {
+      opts.flags.limit = parseInt(argv[++i], 10) || 50;
+    } else if (arg === "--concurrency") {
+      opts.flags.concurrency = parseInt(argv[++i], 10) || 4;
+    } else if (arg === "--depth") {
+      opts.flags.depth = parseInt(argv[++i], 10) || 2;
+    } else if (arg === "--max-nodes") {
+      opts.flags.maxNodes = parseInt(argv[++i], 10) || 2000;
+    } else if (arg === "--max-pages") {
+      opts.flags.maxPages = parseInt(argv[++i], 10) || 50;
+    } else if (arg === "--max-requests") {
+      opts.flags.maxRequests = parseInt(argv[++i], 10) || 400;
+    } else if (arg === "--no-cache") {
+      opts.flags.noCache = true;
+    } else if (arg === "--from-uk") {
+      opts.flags.fromUk = argv[++i];
+    } else if (arg === "--msg-id") {
+      opts.flags.msgId = argv[++i];
+    } else if (arg === "--parent-fs-id") {
+      opts.flags.parentFsId = argv[++i];
     } else if (arg.startsWith("-")) {
       opts.flags[arg.replace(/^-+/, "")] = true;
     } else {
@@ -337,7 +385,7 @@ cmds.groups = async (args, json) => {
 cmds.gshares = async (args, json) => {
   const gid = args._[0];
   if (!gid) { console.error("Usage: bdp gshares <gid>"); process.exit(1); }
-  const shares = await group.listShares(gid);
+  const shares = await group.listShares(gid, { cache: args.flags.noCache !== true });
   output(shares, json, (list) => {
     console.log(`${list.length} shares in group ${gid}:\n`);
     list.forEach((s, i) => {
@@ -350,31 +398,169 @@ cmds.gshares = async (args, json) => {
 cmds.gls = async (args, json) => {
   const gid = args._[0];
   const fsId = args._[1];
-  if (!gid || !fsId) { console.error("Usage: bdp gls <gid> <fs_id>"); process.exit(1); }
-  const result = await group.listFiles(gid, fsId, { page: args.flags.page || 1 });
-  output(result, json, (d) => {
-    console.log(`${d.files.length} items${d.hasMore ? " (has more — use --page)" : ""}:\n`);
-    d.files.forEach((f) => {
+  if (!gid || !fsId) { console.error("Usage: bdp gls <gid> <fs_id> [--page N] [--page-size N]"); process.exit(1); }
+
+  const opts = {
+    page: args.flags.page || 1,
+    pageSize: args.flags.pageSize || 50,
+    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.parentFsId) opts.parentFsId = args.flags.parentFsId;
+
+  verboseLog(args, `gls gid=${gid} fsId=${fsId} page=${opts.page} pageSize=${opts.pageSize}`);
+  const result = await group.listFiles(gid, fsId, opts);
+
+  if (args.flags.legacyJson) {
+    emitJson(result.files, args);
+    return;
+  }
+
+  if (result.autoResolved) {
+    console.error(`[auto] 传入的 fromUk/msgId 与群 ${gid} 不匹配（API errno=2131），已自动改用 gshares 解析的参数 (fromUk=${result.fromUk}, msgId=${result.msgId})`);
+  }
+
+  if (result.fallback) {
+    verboseLog(args, `fallback: ${result.fallback.reason} -> ${result.fallback.resolvedFsId} (${result.fallback.level})`);
+  }
+
+  if (args.flags.jsonFile || json) {
+    emitJson(result, args);
+  } else {
+    if (result.fallback) {
+      console.log(`⚠️  fallback: ${result.fallback.reason} — 已回退到 ${result.fallback.resolvedFsId} (${result.fallback.level})`);
+    }
+    console.log(`${result.files.length} items${result.hasMore ? " (has more — use --page)" : ""}:\n`);
+    result.files.forEach((f) => {
       const dir = f.isDir ? "[DIR] " : "      ";
       console.log(`  ${dir}${f.name}  ${formatSize(f.size)}  fs_id:${f.fsId}`);
     });
-  });
+  }
+};
+
+cmds.gtree = async (args, json) => {
+  const gid = args._[0];
+  if (!gid) { console.error("Usage: bdp gtree <gid> [--depth N] [--concurrency N] [--max-nodes N]"); process.exit(1); }
+
+  const opts = {
+    depth: args.flags.depth || 2,
+    concurrency: args.flags.concurrency || 4,
+    maxNodes: args.flags.maxNodes || 2000,
+    maxPages: args.flags.maxPages || 50,
+    maxRequests: args.flags.maxRequests || 400,
+    cache: args.flags.noCache !== true,
+  };
+  verboseLog(args, `gtree gid=${gid} depth=${opts.depth} concurrency=${opts.concurrency} maxNodes=${opts.maxNodes} maxPages=${opts.maxPages} maxRequests=${opts.maxRequests} cache=${opts.cache}`);
+  const result = await group.treeFiles(gid, opts);
+
+  if (args.flags.jsonFile || json) {
+    emitJson(result, args);
+  } else {
+    console.log(`${result.tree.length} nodes (depth ${result.depth}, ${result.failed.length} failed${result.truncated ? ", truncated" : ""}):\n`);
+    result.tree.forEach((n) => {
+      const dir = n.isDir ? "[DIR] " : "      ";
+      console.log(`  ${dir}${n.path || n.name}  ${formatSize(n.size)}  fs_id:${n.fsId}`);
+    });
+  }
 };
 
 cmds.gsearch = async (args, json) => {
   const gid = args._[0];
   const keyword = args._[1];
-  if (!gid || !keyword) { console.error("Usage: bdp gsearch <gid> <keyword>"); process.exit(1); }
-  const results = await group.searchFiles(gid, keyword);
-  output(results, json, (list) => {
-    console.log(`${list.length} matches for "${keyword}":\n`);
-    list.forEach((r) => {
+  if (!gid || !keyword) { console.error("Usage: bdp gsearch <gid> <keyword> [--page N] [--limit N]"); process.exit(1); }
+
+  const opts = {
+    page: args.flags.page || 1,
+    limit: args.flags.limit || 50,
+    concurrency: args.flags.concurrency || 4,
+    unique: args.flags.unique !== false,
+    all: args.flags.all === true,
+    depth: args.flags.depth || 1,
+    maxPages: args.flags.maxPages || 50,
+    maxRequests: args.flags.maxRequests || 400,
+    cache: args.flags.noCache !== true,
+  };
+
+  verboseLog(args, `gsearch gid=${gid} keyword="${keyword}" page=${opts.page} limit=${opts.limit} concurrency=${opts.concurrency} unique=${opts.unique} all=${opts.all} depth=${opts.depth} maxPages=${opts.maxPages} maxRequests=${opts.maxRequests} cache=${opts.cache}`);
+  const result = await group.searchFiles(gid, keyword, opts);
+
+  if (result.partial) {
+    verboseLog(args, `partial: ${result.failedShares}/${result.totalShares} shares failed`);
+    if (result.failedDirs && result.failedDirs.length > 0) {
+      verboseLog(args, `failed dirs: ${result.failedDirs.map((f) => `${f.name || f.fsId}(${f.errno})`).slice(0, 10).join(", ")}`);
+    }
+  }
+  if (result.throttled) {
+    verboseLog(args, `throttled: API 限流中断，重跑命令可续扫（磁盘缓存只补缺失目录）`);
+  }
+
+  if (args.flags.legacyJson) {
+    emitJson(result.results, args);
+    return;
+  }
+
+  if (args.flags.jsonFile || json) {
+    emitJson(result, args);
+  } else {
+    console.log(`${result.returned} matches for "${keyword}"${result.hasMore ? " (has more — use --page " + (result.nextPage || "?") + ")" : ""}:\n`);
+    result.results.forEach((r) => {
       const dir = r.isDir ? "[DIR] " : "      ";
       console.log(`  ${dir}${r.path || r.name}  ${formatSize(r.size)}  fs_id:${r.fsId}`);
     });
+    if (result.throttled) {
+      console.error(`⚠️  API 限流中断（已扫描 ${result.scannedShares}/${result.totalShares} 分享，失败 ${result.failedShares}）。重跑命令可续扫（磁盘缓存加速）`);
+    } else if (result.partial) {
+      console.error(`[verbose] ${result.failedShares} shares failed (partial result)`);
+    }
+  }
+};
+
+cmds.cache = async (args, json) => {
+  const action = args._[0] || "info";
+  const { clearGroupCache } = group;
+  if (action === "clear") {
+    clearGroupCache();
+    output({ cleared: true }, json, () => console.log("✅ 群聊会话缓存已清除"));
+    return;
+  }
+  // info: 显示缓存目录位置
+  const path = require("path");
+  const os = require("os");
+  const dir = process.env.BDP_CACHE_DIR || path.join(os.homedir(), ".bdp", "cache");
+  output({ cacheDir: dir, ttl: { dir: "30min", shares: "5min" } }, json, () => {
+    console.log(`Cache dir:  ${dir}`);
+    console.log(`Dir TTL:    30 min (gsearch/gtree 目录列表)`);
+    console.log(`Shares TTL: 5 min (gshares 分享列表)`);
+    console.log(`Clear with: bdp cache clear`);
   });
 };
 
+cmds.error = async (args, json) => {
+  const code = args._[0] || "-3";
+  const ERRORS = {
+    "-3": "群分享 API 拒绝请求。已观察到大目录、错误的 msgId/fromUk、过期分享、请求过于频繁(限流)都可能触发。\n" +
+          "处理：减小 --page-size（自动重试 50→20→10）或 --concurrency；\n" +
+          "      限流表现为 errno=0 但只返回目录自身（self-echo），工具会自动退避重试(1s/2s)；\n" +
+          "      大目录已支持自动全页遍历（每页上限 100，--max-pages 控制页数）；\n" +
+          "      若回退到父目录（fallback level=parent），Agent 应从父目录换路径继续遍历。",
+    "-6": "接口鉴权失败。通常为 access_token/cookie 失效，请重新执行 bdp login。",
+    "2131": "群分享 msg_id 不属于该群（shareinfo 以 msg_id 为查找键，from_uk 不参与校验）。\n" +
+            "常见原因：gid 与 --from-uk/--msg-id/--parent-fs-id 来自不同群/分享库（参数错配）。\n" +
+            "处理：用 bdp gshares <gid> 查看本群分享（或 bdp gsearch <gid> <关键词>），\n" +
+            "      取其中一行的 fsId/fromUk/msgId 重试，保证 gid/fsId/fromUk/msgId 同源；\n" +
+            "      fsId 为子目录时保持其父分享行的 fromUk/msgId 不变；\n" +
+            "      或去掉 --from-uk/--msg-id 让 CLI 自动解析（仅顶层分享）。\n" +
+            "      工具已支持：显式参数错配时自动按 fsId 纠正（结果含 autoResolved:true）。",
+  };
+  const msg = ERRORS[code] || `未知错误码 ${code}，请提交 Issue: https://github.com/NkAntony777/baiduwangpan-cli/issues`;
+  if (args.flags.jsonFile || json) {
+    emitJson({ code, description: msg }, args);
+  } else {
+    console.log(msg);
+  }
+};
+
 // ── Main ───────────────────────────────────────────────
 
 const HELP = `bdp — 百度网盘 CLI
@@ -398,8 +584,15 @@ PAN FILE OPERATIONS (全盘)
 GROUP CHAT OPERATIONS (群聊)
   groups                     List all groups
   gshares <gid>              List share libraries in group
+  gtree <gid>                Build directory tree (BFS)
+                             [--depth N] [--concurrency N] [--max-nodes N]
   gls <gid> <fs_id>          Browse files in a share
-  gsearch <gid> <keyword>    Search group file names
+                             [--page N] [--page-size N] [--from-uk X] [--msg-id Y] [--parent-fs-id Z]
+  gsearch <gid> <keyword>    Search group file names (全量遍历目录, 缓存命中秒回)
+                             [--page N] [--limit N] [--depth N] [--concurrency N]
+                             [--max-pages N] [--max-requests N] [--no-unique] [--all] [--no-cache]
+  cache [clear]              Show cache info or clear session cache
+  error <code>               Explain an error code (e.g. -3)
 
 CONFIGURATION
   login                        Browser QR login (auto-detect cookies)
@@ -409,12 +602,25 @@ CONFIGURATION
 
 OPTIONS
   --json                      Output JSON (for Agent consumption)
+  --json-file <path>          Write JSON to file (UTF-8, bypasses console encoding)
+  --legacy-json               Output bare array (gls/gsearch legacy format)
+  --verbose                   Write progress/log to stderr only
   -n <N>                      Number of lines (head/tail)
   -p <path>                   Search path (search)
   -i                          Ignore case (grep)
   -N                          Show line numbers (cat/grep)
   -o <dir>                    Output directory (get)
-  --page <N>                  Page number (gls)
+  --page <N>                  Page number (gls/gsearch)
+  --page-size <N>             Page size for gls (default 50, max 100)
+  --limit <N>                 Page size for gsearch (default 50)
+  --depth <N>                 Recursive search/tree depth (gsearch default 1, gtree default 2)
+  --max-nodes <N>             Tree node cap (gtree default 2000)
+  --max-pages <N>             Max pages per directory scan (gsearch/gtree default 50, 100 items/page)
+  --max-requests <N>          Request budget per command (gsearch/gtree default 400, prevents throttle)
+  --concurrency <N>           Parallel share scans for gsearch/gtree (default 4)
+  --no-cache                  Disable in-process session cache (gsearch/gtree/gshares/gls)
+  --no-unique                 Keep duplicates from different msgId (gsearch)
+  --all                       Fetch all results, no paging (gsearch, not Agent default)
 
 EXAMPLES
   bdp login --bduss abc123 --stoken def456
@@ -424,7 +630,10 @@ EXAMPLES
   bdp groups --json
   bdp gshares 539478953581833690
   bdp gls 539478953581833690 742474845517885 --json
-  bdp gsearch 539478953581833690 "倪海厦"`;
+  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 error -3`;
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -439,20 +648,22 @@ async function main() {
     process.exit(0);
   }
 
+  let exitCode = 0;
   try {
     await handler(args, json);
   } catch (e) {
     if (json) {
-      console.log(JSON.stringify({ error: e.message }));
+      console.log(JSON.stringify({ error: e.message, ...(e.errno !== undefined ? { errno: e.errno } : {}) }));
     } else {
       console.error(`[ERROR] ${e.message}`);
     }
-    process.exitCode = 1;
+    exitCode = 1;
   } finally {
     try {
       require("../lib/browser-login").disconnectBrowserSession();
     } catch {}
   }
+  process.exit(exitCode);
 }
 
 main();

package/lib/browser-login.js

@@ -233,8 +233,13 @@ async function openPersistentSession({ browser, profileDir, port, minimized }) {
     proc = launchBrowser(browser, profileDir, port, { minimized });
     await waitForDevTools(port, 15000);
   }
-  const { cdp, tab } = await connectPanTab(port);
-  return { browser, profileDir, port, proc, cdp, tab };
+  try {
+    const { cdp, tab } = await connectPanTab(port);
+    return { browser, profileDir, port, proc, cdp, tab };
+  } catch (e) {
+    if (proc) killBrowser(proc);
+    throw e;
+  }
 }
 
 async function getBrowserSession(settings = {}) {
@@ -276,15 +281,10 @@ async function getBrowserSession(settings = {}) {
 
 async function browserJson(url, options = {}, settings = {}) {
   const session = await getBrowserSession(settings);
-  let response;
-  try {
-    response = await evaluateFetch(session.cdp, url, options);
-  } catch (error) {
-    session.cdp.close();
-    activeSession = null;
-    throw error;
-  }
+  const response = await evaluateFetch(session.cdp, url, options);
 
+  // 注意：fetch 错误（网络/API 断连）不关闭共享会话——并发批处理中一个请求失败会
+  // 连带杀死同批其他在途请求（ws 关闭）。会话死活由下次调用前的 ping 自动检测重连。
   try {
     return JSON.parse(response.text.replace(/^\s+/, ""));
   } catch {
@@ -379,7 +379,8 @@ async function browserLogin({
 
 function scheduleDisconnect() {
   if (disconnectTimer) clearTimeout(disconnectTimer);
-  disconnectTimer = setTimeout(disconnectBrowserSession, 500);
+  // 空闲 90 秒后断开浏览器会话（并发批处理扫描中请求间隔可能较长，短超时会中途断连）
+  disconnectTimer = setTimeout(disconnectBrowserSession, 90000);
   disconnectTimer.unref();
 }
 

package/lib/group.js

@@ -1,5 +1,109 @@
 const http = require("./http");
 const { getBdstoken } = http;
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+
+// ── 常量（逆向实测结论）────────────────────────────────
+const MAX_PAGE_SIZE = 100;         // shareinfo 服务端每页硬上限（num>100 不返回更多）
+const MAX_LIST_SHARE_PAGES = 10;   // listshare 分页上限（10 页 × 50 条消息）
+const DIR_CACHE_TTL = 1800000;     // 目录列表缓存 30 分钟（群文件树很少变动）
+const EMPTY_DIR_CACHE_TTL = 60000; // 空目录缓存 1 分钟（限流时 API 可能返回空列表，短 TTL 防缓存投毒）
+const SHARE_CACHE_TTL = 300000;    // 群分享列表缓存 5 分钟（新分享消息较频繁）
+const DEFAULT_MAX_REQUESTS = 400;  // 单条命令 shareinfo 请求预算（防深扫失控触发限流）
+
+// ── 会话级缓存（内存 L1 + 磁盘 L2，跨命令复用）──────────
+const cacheStore = new Map();
+
+function cacheDir() {
+  return process.env.BDP_CACHE_DIR || path.join(os.homedir(), ".bdp", "cache");
+}
+
+function cachePath(key) {
+  return path.join(cacheDir(), crypto.createHash("sha1").update(key).digest("hex") + ".json");
+}
+
+function cacheGet(key) {
+  const entry = cacheStore.get(key); // L1
+  if (entry) {
+    if (Date.now() - entry.at <= entry.ttl) return entry.value;
+    cacheStore.delete(key);
+  }
+  try {
+    // L2: 磁盘缓存（跨 CLI 进程复用，避免重复扫描触发限流）
+    const disk = JSON.parse(fs.readFileSync(cachePath(key), "utf-8"));
+    if (Date.now() - disk.at <= disk.ttl) {
+      cacheStore.set(key, { at: disk.at, ttl: disk.ttl, value: disk.value });
+      return disk.value;
+    }
+    fs.unlinkSync(cachePath(key));
+  } catch {}
+  return null;
+}
+
+function cacheSet(key, value, ttl) {
+  cacheStore.set(key, { at: Date.now(), ttl, value });
+  try {
+    fs.mkdirSync(cacheDir(), { recursive: true });
+    fs.writeFileSync(cachePath(key), JSON.stringify({ at: Date.now(), ttl, value }), "utf-8");
+  } catch {}
+}
+
+function clearGroupCache() {
+  cacheStore.clear();
+  try {
+    fs.rmSync(cacheDir(), { recursive: true, force: true });
+  } catch {}
+}
+
+// ── 工具 ──────────────────────────────────────────────
+
+function toStr(v) {
+  if (v === null || v === undefined) return "";
+  return String(v);
+}
+
+// 安全解码：部分群文件路径含非法百分号编码（裸 % 等），decodeURIComponent 会抛 URIError
+// 导致整个目录扫描失败（实测 30/349 目录因此报废）。失败时回退原始字符串。
+function safeDecode(s) {
+  if (!s) return "";
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+class ShareApiError extends Error {
+  constructor(errno, message) {
+    super(message);
+    this.errno = errno;
+    this.name = "ShareApiError";
+  }
+}
+
+// errno=2131 的详细说明（bdp error 2131 与 gls 报错共用）
+function describeErrno2131(gidS, msgIdS) {
+  return (
+    `shareinfo rejected: msg_id ${msgIdS} 不属于群 ${gidS} 的任何分享 (errno=2131)。` +
+    `群分享参数必须同源：gid 与 --from-uk/--msg-id/--parent-fs-id 应来自同一次 gshares/gsearch 结果。` +
+    `处理：运行 bdp gshares ${gidS} 查看本群分享（或 bdp gsearch ${gidS} <关键词>），` +
+    `取其中一行的 fsId/fromUk/msgId 重试；fsId 为子目录时保持同一行的 fromUk/msgId。`
+  );
+}
+
+// 限流退化检测：shareinfo 被限流时 errno=0 但返回"目录自身"而非子项。
+// 目录不可能包含自身，故返回列表里出现请求 fs_id 即可判定为退化响应。
+function isSelfEcho(data, fsIdS) {
+  const records = data.records;
+  if (!Array.isArray(records) || records.length === 0) return false;
+  return records.some((r) => toStr(r.fs_id) === toStr(fsIdS));
+}
+
+// ── 群组列表 ──────────────────────────────────────────
 
 async function listGroups() {
   const bdstoken = await getBdstoken();
@@ -12,112 +116,557 @@ async function listGroups() {
   if (data.errno !== 0) throw new Error(`API error: errno=${data.errno}`);
 
   return (data.records || []).map((g) => ({
-    gid: g.gid,
+    gid: toStr(g.gid),
     name: g.name,
-    gnum: g.gnum,
+    gnum: toStr(g.gnum),
     description: g.gdesc || "",
-    type: g.type,
+    type: toStr(g.type),
     created: g.ctime,
   }));
 }
 
-async function listShares(gid) {
-  const bdstoken = await getBdstoken();
-  const data = await http.webJson(
-    `${http.PAN_BASE}/mbox/group/listshare?clienttype=0&app_id=${http.APP_ID}&web=1&type=2&gid=${gid}&limit=50&desc=1&bdstoken=${bdstoken}`,
-    { method: "POST", body: "" }
-  );
+// ── 群内分享库 ────────────────────────────────────────
 
-  if (data.errno !== 0) throw new Error(`API error: errno=${data.errno}`);
+async function listShares(gid, options = {}) {
+  const gidS = toStr(gid);
+  const cache = options.cache === true;
+  const ttlMs = options.ttlMs || SHARE_CACHE_TTL;
+  const key = `shares:${gidS}`;
+
+  if (cache) {
+    const hit = cacheGet(key);
+    if (hit) return hit;
+  }
 
+  const bdstoken = await getBdstoken();
   const shares = [];
-  for (const msg of data.records?.msg_list || []) {
-    for (const f of msg.file_list || []) {
-      shares.push({
-        msgId: msg.msg_id,
-        fromUk: msg.uk,
-        fromUser: msg.uname,
-        name: decodeURIComponent(f.path || f.server_filename || ""),
-        fsId: f.fs_id,
-        isDir: f.isdir === "1",
-        size: parseInt(f.size || "0"),
-      });
+  const seenMsg = new Set();
+  let cursor = "";
+  let stop = false;
+
+  // has_more=1 时用 last_msg_time 游标翻页（desc 序）；无新消息/无游标则停止
+  for (let page = 0; page < MAX_LIST_SHARE_PAGES && !stop; page++) {
+    const url =
+      `${http.PAN_BASE}/mbox/group/listshare?clienttype=0&app_id=${http.APP_ID}&web=1&type=2&gid=${gidS}` +
+      `&limit=50&desc=1${cursor ? `&last_msg_time=${cursor}` : ""}&bdstoken=${bdstoken}`;
+    const data = await http.webJson(url, { method: "POST", body: "" });
+
+    if (data.errno !== 0) throw new Error(`API error: errno=${data.errno}`);
+
+    let added = 0;
+    for (const msg of data.records?.msg_list || []) {
+      const mid = toStr(msg.msg_id);
+      if (seenMsg.has(mid)) continue; // 防重复页
+      seenMsg.add(mid);
+      added++;
+      for (const f of msg.file_list || []) {
+        shares.push({
+          msgId: mid,
+          fromUk: toStr(msg.uk),
+          fromUser: msg.uname,
+          name: safeDecode(f.path || f.server_filename || ""),
+          fsId: toStr(f.fs_id),
+          isDir: f.isdir === "1",
+          size: parseInt(f.size || "0", 10),
+        });
+      }
     }
+
+    if (data.has_more !== 1 || added === 0) stop = true;
+    else cursor = toStr(data.last_msg_time || "");
+    if (!cursor) stop = true;
   }
+
+  if (cache) cacheSet(key, shares, ttlMs);
   return shares;
 }
 
+// ── 底层 shareinfo 请求 ───────────────────────────────
+
+function mapShareInfoFile(f, parentFsId, fromUkS, msgIdS) {
+  return {
+    name: f.server_filename || "",
+    path: safeDecode(f.path || ""),
+    isDir: f.isdir === 1 || f.isdir === "1",
+    size: parseInt(f.size || "0", 10),
+    fsId: toStr(f.fs_id),
+    md5: f.md5 || "",
+    category: parseInt(f.category || "0", 10),
+    ctime: toStr(f.server_ctime || ""),
+    mtime: toStr(f.server_mtime || ""),
+    parentFsId,
+    fromUk: fromUkS,
+    msgId: msgIdS,
+  };
+}
+
+// 单页 shareinfo；errno!=0 抛 ShareApiError；限流退化（self-echo）标记 throttled
+async function shareInfoRaw(gidS, fsIdS, fromUkS, msgIdS, page, pageSize) {
+  const bdstoken = await getBdstoken();
+  const url =
+    `${http.PAN_BASE}/mbox/msg/shareinfo?type=2&from_uk=${fromUkS}&msg_id=${msgIdS}` +
+    `&to_uk=0&num=${pageSize}&page=${page}&fs_id=${fsIdS}&gid=${gidS}` +
+    `&clienttype=0&app_id=${http.APP_ID}&web=1&bdstoken=${bdstoken}`;
+
+  const data = await http.webJson(url, { method: "POST", body: "" });
+
+  if (data.errno !== 0) {
+    throw new ShareApiError(data.errno, `API error: errno=${data.errno}`);
+  }
+  if (isSelfEcho(data, fsIdS)) {
+    const e = new ShareApiError(-3, `shareinfo throttled (self-echo) for fs_id ${fsIdS}`);
+    e.throttled = true;
+    throw e;
+  }
+  return data;
+}
+
+// 限流/瞬时错误退避重试：2s → 4s → 2 次后放弃。
+//  - 网络/连接错误（非 ShareApiError）：本地瞬时故障，重试（实测并发扫描中 API 会随机断连）
+//  - self-echo 限流：重试，但受 throttleState 上限约束（consecutive≥3 停止扫描 / total≥5 不再重试）
+//  - 硬 errno（-3/2131 等）：不重试（listFiles 有 page-size 降级链处理 -3）
+// budget 为整条命令的请求预算，耗尽后拒绝新请求（防深扫失控）。
+async function shareInfoRawWithRetry(gidS, fsIdS, fromUkS, msgIdS, page, pageSize, budget, throttleState) {
+  if (budget) {
+    if (budget.remaining <= 0) throw new ShareApiError(-3, "shareinfo request budget exhausted");
+    budget.remaining--;
+  }
+  let attempts = 0;
+  for (;;) {
+    try {
+      const data = await shareInfoRaw(gidS, fsIdS, fromUkS, msgIdS, page, pageSize);
+      if (throttleState) throttleState.consecutive = 0;
+      return data;
+    } catch (e) {
+      const isThrottled = e instanceof ShareApiError && e.throttled;
+      const isNetwork = !(e instanceof ShareApiError);
+      if (!isThrottled && !isNetwork) throw e;
+      if (isThrottled && throttleState) {
+        throttleState.consecutive = (throttleState.consecutive || 0) + 1;
+        throttleState.total = (throttleState.total || 0) + 1;
+      }
+      const maxRetries = isThrottled && throttleState && (throttleState.consecutive >= 3 || throttleState.total >= 5) ? 0 : 2;
+      if (attempts >= maxRetries) throw e;
+      attempts++;
+      await delay(2000 * attempts);
+    }
+  }
+}
+
+// 单页 shareinfo（gls 用），带限流退避
+async function shareInfoRequest(gidS, fsIdS, fromUkS, msgIdS, page, pageSize) {
+  const data = await shareInfoRawWithRetry(gidS, fsIdS, fromUkS, msgIdS, page, pageSize);
+  const files = (Array.isArray(data.records) ? data.records : []).map((f) =>
+    mapShareInfoFile(f, fsIdS, fromUkS, msgIdS)
+  );
+  return { files, hasMore: data.has_more === 1, page, pageSize };
+}
+
+// 全量拉取目录内容（gsearch/gtree 用）：自动翻页 + 去重 + 缓存。
+// 逆向实测：shareinfo 每页硬上限 100，has_more=1 时 page=N 可继续翻页；
+// 旧实现只取 page=1，超过 100 子项的目录会漏数据。
+async function fetchShareDir({ gidS, fsIdS, fromUkS, msgIdS, maxPages = 50, cache = false, ttlMs = DIR_CACHE_TTL, budget, throttleState }) {
+  const key = `dir:${gidS}:${fsIdS}:${fromUkS}:${msgIdS}`;
+  if (cache) {
+    const hit = cacheGet(key);
+    if (hit) return { ...hit, cached: true };
+  }
+
+  const files = [];
+  const seenFs = new Set();
+  let hasMore = false;
+  let pages = 0;
+
+  for (let page = 1; page <= maxPages; page++) {
+    const data = await shareInfoRawWithRetry(gidS, fsIdS, fromUkS, msgIdS, page, MAX_PAGE_SIZE, budget, throttleState);
+    const records = Array.isArray(data.records) ? data.records : [];
+    for (const f of records) {
+      const fsId = toStr(f.fs_id);
+      if (seenFs.has(fsId)) continue;
+      seenFs.add(fsId);
+      files.push(mapShareInfoFile(f, fsIdS, fromUkS, msgIdS));
+    }
+    hasMore = data.has_more === 1;
+    pages = page;
+    if (!hasMore || records.length === 0) break;
+  }
+
+  const result = { files, hasMore, pages, truncated: pages >= maxPages };
+  // 空目录用短 TTL 缓存：限流时 API 可能返回空列表（缓存投毒会导致静默丢数据）
+  if (cache) cacheSet(key, result, files.length === 0 ? EMPTY_DIR_CACHE_TTL : ttlMs);
+  return { ...result, cached: false };
+}
+
+// ── 列出分享库内容 (gls) ──────────────────────────────
+
 async function listFiles(gid, fsId, options = {}) {
+  const gidS = toStr(gid);
+  const fsIdS = toStr(fsId);
+  const parentFsId = toStr(options.parentFsId || "");
   const page = options.page || 1;
-  const num = options.num || 100;
+  let pageSize = options.pageSize || 50;
+  pageSize = Math.min(Math.max(1, pageSize), MAX_PAGE_SIZE);
+  const cache = options.cache === true;
 
-  // First get the fromUk and msgId for this fsId
-  let { fromUk, msgId } = options;
-  if (!fromUk || !msgId) {
-    const shares = await listShares(gid);
-    const match = shares.find((s) => s.fsId === fsId);
-    if (match) {
-      fromUk = match.fromUk;
-      msgId = match.msgId;
-    } else if (shares.length > 0) {
-      fromUk = shares[0].fromUk;
-      msgId = shares[0].msgId;
-    } else {
-      throw new Error("Cannot find share info for this fsId");
+  // 来源解析：显式传入优先；否则仅在顶层分享中精确匹配（禁止"用第一个分享"兜底）
+  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.`
+      );
     }
+    fromUkS = match.fromUk;
+    msgIdS = match.msgId;
   }
 
-  const bdstoken = await getBdstoken();
-  const data = await http.webJson(
-    `${http.PAN_BASE}/mbox/msg/shareinfo?type=2&from_uk=${fromUk}&msg_id=${msgId}&to_uk=0&num=${num}&page=${page}&fs_id=${fsId}&gid=${gid}&clienttype=0&app_id=${http.APP_ID}&web=1&bdstoken=${bdstoken}`,
-    { method: "POST", body: "" }
+  // errno=-3 时依次降 page-size: 50 → 20 → 10
+  const attempts = [...new Set([pageSize, 50, 20, 10].filter((n) => n <= pageSize))];
+  let lastErrno = null;
+
+  for (const size of attempts) {
+    try {
+      const result = await shareInfoRequest(gidS, fsIdS, fromUkS, msgIdS, page, size);
+      return {
+        files: result.files,
+        hasMore: result.hasMore,
+        page,
+        pageSize: size,
+        fromUk: fromUkS,
+        msgId: msgIdS,
+        fallback: null,
+      };
+    } catch (e) {
+      if (e instanceof ShareApiError && e.errno === -3) {
+        lastErrno = -3;
+        continue; // 尝试更小的 page-size
+      }
+      if (e instanceof ShareApiError && e.errno === 2131) {
+        // msg_id 不属于该群（常见：gid 与参数来自不同群/分享库）。
+        // 尝试按 fsId 从本群 gshares 自动解析纠正一次；失败则给出明确指引。
+        try {
+          const shares = await listShares(gidS, { cache });
+          const match = shares.find((s) => s.fsId === fsIdS);
+          if (match) {
+            const result = await shareInfoRequest(gidS, fsIdS, match.fromUk, match.msgId, page, size);
+            return {
+              files: result.files,
+              hasMore: result.hasMore,
+              page,
+              pageSize: size,
+              fromUk: match.fromUk,
+              msgId: match.msgId,
+              fallback: null,
+              autoResolved: true,
+            };
+          }
+        } catch {}
+        throw new ShareApiError(2131, describeErrno2131(gidS, msgIdS));
+      }
+      throw e;
+    }
+  }
+
+  // 全部 page-size 都失败（errno=-3）→ 回退
+  if (parentFsId) {
+    // 回退到父目录，展示兄弟内容帮助 Agent 换路径
+    try {
+      const parent = await shareInfoRequest(gidS, toStr(parentFsId), fromUkS, msgIdS, 1, 50);
+      return {
+        files: parent.files,
+        hasMore: parent.hasMore,
+        page: 1,
+        pageSize: 50,
+        fromUk: fromUkS,
+        msgId: msgIdS,
+        fallback: {
+          reason: "errno=-3",
+          requestedFsId: fsIdS,
+          resolvedFsId: toStr(parentFsId),
+          level: "parent",
+        },
+      };
+    } catch (e) {
+      throw new ShareApiError(
+        -3,
+        `shareinfo rejected for fsId ${fsIdS} (errno=-3), and parent fallback also failed. ` +
+        `The share may be expired or the directory may be too large for the API.`
+      );
+    }
+  }
+
+  // 目标本身是顶层分享 → 退回 gshares 结果
+  try {
+    const shares = await listShares(gidS, { cache });
+    const match = shares.find((s) => s.fsId === fsIdS);
+    if (match) {
+      return {
+        files: [{
+          name: match.name,
+          path: match.name,
+          isDir: match.isDir,
+          size: match.size,
+          fsId: match.fsId,
+          md5: "",
+          category: 0,
+          ctime: "",
+          mtime: "",
+          parentFsId: "",
+          fromUk: match.fromUk,
+          msgId: match.msgId,
+        }],
+        hasMore: false,
+        page: 1,
+        pageSize: 50,
+        fromUk: fromUkS,
+        msgId: msgIdS,
+        fallback: {
+          reason: "errno=-3",
+          requestedFsId: fsIdS,
+          resolvedFsId: fsIdS,
+          level: "group-shares",
+        },
+      };
+    }
+  } catch {}
+
+  throw new ShareApiError(
+    -3,
+    `shareinfo rejected for fsId ${fsIdS} (errno=-3). ` +
+    `群分享 API 拒绝请求：已观察到大目录、错误的 msgId/fromUk、过期分享、请求过于频繁都可能触发。` +
+    `请减小 --page-size，稍后重试，或携带 gsearch 返回的 fromUk/msgId/parentFsId 信息重试。`
   );
+}
 
-  if (data.errno !== 0) throw new Error(`API error: errno=${data.errno}`);
+// ── 目录树 (gtree) ────────────────────────────────────
 
-  const files = (Array.isArray(data.records) ? data.records : []).map((f) => ({
-    name: f.server_filename || "",
-    path: decodeURIComponent(f.path || ""),
-    isDir: f.isdir === 1 || f.isdir === "1",
-    size: parseInt(f.size || "0"),
-    fsId: f.fs_id,
-    md5: f.md5 || "",
-    category: parseInt(f.category || "0"),
-    ctime: f.server_ctime || "",
-    mtime: f.server_mtime || "",
-  }));
+async function treeFiles(gid, options = {}) {
+  const gidS = toStr(gid);
+  const maxDepth = Math.min(Math.max(1, options.depth || 2), 5);
+  const concurrency = Math.min(Math.max(1, options.concurrency || 4), 8);
+  const maxNodes = options.maxNodes || 2000;
+  const maxPages = Math.min(Math.max(1, options.maxPages || 50), 200);
+  const cache = options.cache === true;
+  const budget = { remaining: Math.min(Math.max(1, options.maxRequests || DEFAULT_MAX_REQUESTS), 2000) };
+  const throttleState = { consecutive: 0 };
+
+  const shares = await listShares(gidS, { cache });
+  const tree = [];
+  const failed = [];
+
+  // BFS: queue 元素 { node, depth, share }
+  const queue = shares.map((s) => ({ node: { ...s, parentFsId: "" }, depth: 1, share: s }));
+  let scanned = 0;
+
+  // 逐层 BFS，层内并发
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const level = queue.filter((q) => q.depth === depth);
+    if (level.length === 0) break;
+
+    const results = await Promise.all(
+      level.map(async (entry) => {
+        const { node, share } = entry;
+        if (!node.isDir || node.size > 0) return null; // 非目录不进队列
+        scanned++;
+        try {
+          const { files } = await fetchShareDir({
+            gidS, fsIdS: node.fsId, fromUkS: share.fromUk, msgIdS: share.msgId,
+            maxPages, cache, budget, throttleState,
+          });
+          return files.map((f) => ({
+            node: { ...f, fromUser: share.fromUser },
+            depth: depth + 1,
+            share,
+          }));
+        } catch {
+          failed.push({ fsId: node.fsId, name: node.name });
+          return null;
+        }
+      })
+    );
 
-  return { files, hasMore: data.has_more === 1, page };
+    for (const list of results) {
+      if (!list) continue;
+      for (const item of list) {
+        tree.push(item.node);
+        if (tree.length >= maxNodes) break;
+        if (item.depth <= maxDepth && item.node.isDir) queue.push({ node: item.node, depth: item.depth, share: item.share });
+      }
+      if (tree.length >= maxNodes) break;
+    }
+    if (tree.length >= maxNodes) break;
+
+    // 检测到限流后自动放慢下一层
+    if (throttleState.consecutive > 0) await delay(300);
+    // 连续限流 ≥3 次：停止扫描，结果可续扫（磁盘缓存加速重跑）
+    if (throttleState.consecutive >= 3) break;
+  }
+
+  return { tree, failed, scanned, maxDepth, truncated: tree.length >= maxNodes, throttled: throttleState.consecutive >= 3 };
 }
 
+// ── 群文件搜索 (gsearch) ──────────────────────────────
+
 async function searchFiles(gid, keyword, options = {}) {
-  const maxDepth = options.maxDepth || 1;
-  const results = [];
+  const gidS = toStr(gid);
   const kw = keyword.toLowerCase();
 
-  const shares = await listShares(gid);
+  const limit = options.limit || 50;
+  const page = options.page || 1;
+  const concurrency = Math.min(Math.max(1, options.concurrency || 4), 8);
+  const unique = options.unique !== false;
+  const fetchAll = options.all === true;
+  const depth = Math.min(Math.max(1, options.depth || 1), 5); // 默认 1 层（兼容旧行为）
+  const maxPages = Math.min(Math.max(1, options.maxPages || 50), 200); // 单目录最多拉取页数（100/页）
+  const cache = options.cache === true;
+  const maxRequests = Math.min(Math.max(1, options.maxRequests || DEFAULT_MAX_REQUESTS), 2000);
+  const budget = { remaining: maxRequests };
+  const throttleState = { consecutive: 0 };
+  const startIdx = (page - 1) * limit;
+  const stopAt = fetchAll ? Infinity : startIdx + limit + 1; // +1 判断 hasMore
+
+  const shares = await listShares(gidS, { cache });
+  const totalShares = shares.length;
+
+  const seen = new Set();
+  const results = [];
+  const failedDirs = [];
+  let scannedShares = 0;
+  let failedShares = 0;
+  let throttledShares = 0;
+  let cachedDirs = 0;
+  let finished = false;
+
+  const pushIfMatch = (item) => {
+    if (finished) return;
+    const key = unique ? toStr(item.fsId) : `${toStr(item.fsId)}|${toStr(item.msgId)}`;
+    if (unique && seen.has(key)) return;
+    seen.add(key);
+    results.push(item);
+    if (results.length >= stopAt) finished = true;
+  };
 
+  // 阶段 1：顶层分享名称匹配（非目录分享在此完成扫描）
   for (const share of shares) {
+    if (finished) break;
+    if (!share.isDir) scannedShares++;
     if (share.name.toLowerCase().includes(kw)) {
-      results.push({ ...share, group: gid });
+      pushIfMatch({
+        name: share.name,
+        path: share.name,
+        isDir: share.isDir,
+        size: share.size,
+        fsId: share.fsId,
+        md5: "",
+        category: 0,
+        ctime: "",
+        mtime: "",
+        parentFsId: "",
+        fromUk: share.fromUk,
+        msgId: share.msgId,
+        fromUser: share.fromUser,
+        group: gidS,
+      });
     }
+  }
 
-    if (share.isDir && maxDepth > 0) {
-      try {
-        const { files } = await listFiles(gid, share.fsId, {
-          fromUk: share.fromUk,
-          msgId: share.msgId,
-        });
-        for (const f of files) {
-          if (f.name.toLowerCase().includes(kw)) {
-            results.push({ ...f, group: gid });
+  // 阶段 2：BFS 递归扫描目录（每层并发，默认 depth=1 保持旧行为）
+  const dirShares = shares.filter((s) => s.isDir);
+  let queue = dirShares.map((s) => ({ fsId: s.fsId, fromUk: s.fromUk, msgId: s.msgId, depth: 1 }));
+
+  for (let level = 1; level <= depth && queue.length > 0 && !finished; level++) {
+    const current = queue;
+    queue = [];
+
+    for (let i = 0; i < current.length && !finished; i += concurrency) {
+      const batch = current.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (share) => {
+          scannedShares++;
+          if (budget.remaining <= 0) {
+            // 请求预算耗尽：剩余目录快速失败，避免失控触发限流
+            failedShares++;
+            return { matches: [], subDirs: [] };
+          }
+          try {
+            const { files, cached } = await fetchShareDir({
+              gidS, fsIdS: share.fsId, fromUkS: share.fromUk, msgIdS: share.msgId,
+              maxPages, cache, budget, throttleState,
+            });
+            if (cached) cachedDirs++;
+            const matches = files.filter((f) => f.name.toLowerCase().includes(kw));
+            const subDirs = files.filter((f) => f.isDir);
+            return { matches, subDirs };
+          } catch (e) {
+            failedShares++;
+            const errno = e instanceof ShareApiError ? e.errno : "?";
+            if (e instanceof ShareApiError && e.throttled) throttledShares++;
+            failedDirs.push({ fsId: share.fsId, name: share.name || "", errno, message: e.message });
+            return { matches: [], subDirs: [] };
           }
+        })
+      );
+
+      for (const { matches, subDirs } of batchResults) {
+        if (finished) break;
+        for (const f of matches) {
+          pushIfMatch({ ...f, group: gidS });
+          if (finished) break;
         }
-      } catch {}
+        // 收集下一层待扫描目录
+        if (level < depth && !finished) {
+          for (const d of subDirs) {
+            queue.push({ fsId: d.fsId, name: d.name, fromUk: d.fromUk, msgId: d.msgId, depth: level + 1 });
+          }
+        }
+      }
+
+      // 检测到限流后自动放慢（批间降速），缓解服务端压力
+      if (throttleState.consecutive > 0) await delay(300);
+      // 连续限流 ≥3 次：服务端已饱和，停止扫描快速失败。
+      // 已成功扫描的目录已写入磁盘缓存，重跑命令只补扫缺失部分（续扫收敛）。
+      if (throttleState.consecutive >= 3) {
+        if (throttledShares < 3) throttledShares = 3;
+        finished = true;
+        break;
+      }
     }
   }
 
-  return results;
+  const complete = scannedShares >= totalShares;
+  const hasMore = !fetchAll && results.length > startIdx + limit;
+  const pageSlice = fetchAll ? results : results.slice(startIdx, startIdx + limit);
+
+  return {
+    results: pageSlice,
+    page,
+    pageSize: limit,
+    returned: pageSlice.length,
+    total: null,
+    hasMore,
+    nextPage: hasMore ? page + 1 : null,
+    unique,
+    complete,
+    partial: failedShares > 0,
+    throttled: throttleState.consecutive >= 3,
+    failedDirs: failedShares > 0 ? failedDirs.slice(0, 50) : [],
+    scannedShares,
+    totalShares,
+    failedShares,
+    throttledShares,
+    cachedDirs,
+    budgetUsed: maxRequests - budget.remaining,
+    depth,
+    maxPages,
+  };
 }
 
-module.exports = { listGroups, listShares, listFiles, searchFiles };
+module.exports = {
+  listGroups, listShares, listFiles, treeFiles, searchFiles,
+  ShareApiError, describeErrno2131, clearGroupCache,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baiduwangpan-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "百度网盘 CLI — 全盘读写 · 免下载读取文件内容 · 群聊文件浏览 (Agent 友好)",
   "main": "lib/index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/bdp.js",
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "postinstall": "node scripts/postinstall.js"
   },
   "engines": {
@@ -38,7 +38,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/NkAntony777/baiduwangpan-cli.git"
+    "url": "git+https://github.com/NkAntony777/baiduwangpan-cli.git"
   },
   "homepage": "https://github.com/NkAntony777/baiduwangpan-cli",
   "bugs": {