baiduwangpan-cli 1.0.0 → 1.0.2

package/README.md

@@ -65,13 +65,25 @@ npm link           # 全局注册 bdp 命令
 
 ### 2. 配置认证
 
+**方式一：浏览器自动登录（推荐）**
+
+```bash
+bdp login
+```
+
+自动启动 Chrome/Edge → 打开百度网盘登录页 → **手机扫码** → 在页面会话内验证登录 → 自动同步引擎。无需 F12。
+
+扫码产生的新会话可能被百度限制为只能在原浏览器上下文中使用。因此 `bdp` 会保留专用 profile，并在登录后将浏览器最小化；PCS API 继续使用 BDUSS/STOKEN，网页和群聊 API 通过该浏览器的 CDP 会话调用。浏览器被关闭后，下次网页 API 调用会使用同一 profile 自动重启。
+
+**方式二：手动凭证**
+
 ```bash
 bdp login --bduss <你的BDUSS> --stoken <你的STOKEN>
 bdp whoami  # 验证
 ```
 
 <details>
-<summary>📋 如何获取 BDUSS 和 STOKEN</summary>
+<summary>📋 如何获取 BDUSS 和 STOKEN（手动方式）</summary>
 
 1. 浏览器打开 [pan.baidu.com](https://pan.baidu.com) 并登录
 2. 按 `F12` → **Application** → **Cookies** → `https://pan.baidu.com`
@@ -79,6 +91,8 @@ bdp whoami  # 验证
 
 > ⚠️ STOKEN 必须在百度网盘页面获取（不是百度首页），值中应包含大写字母。
 
+> 💡 推荐直接运行 `bdp login`，全程自动化，无需手动操作。
+
 </details>
 
 ### 3. 开始使用
@@ -183,7 +197,7 @@ const results = await group.searchFiles('539478953581833690', '倪海厦');
 │    lib/pan.js    │         lib/group.js             │
 │   全盘文件操作    │        群聊文件浏览               │
 ├──────────────────┼──────────────────────────────────┤
-│  BaiduPCS-Go     │     lib/http.js (curl)           │
+│  BaiduPCS-Go     │  lib/http.js (curl / browser)    │
 │  (BDUSS 认证)    │     mbox API (逆向)              │
 │  locate → dlink  │     /mbox/group/listshare        │
 │  upload/download │     /mbox/msg/shareinfo          │
@@ -237,14 +251,63 @@ baiduwangpan-cli/
 ├── lib/
 │   ├── index.js              # 库导出
 │   ├── config.js             # 配置管理 (~/.bdp/config.json)
-│   ├── http.js               # HTTP 客户端 (curl 封装)
+│   ├── http.js               # 网页 API 双传输 (curl / browser)
+│   ├── browser-login.js      # 浏览器登录、持久 profile 与 CDP 请求
 │   ├── pan.js                # 网盘操作 (BaiduPCS-Go 桥接)
 │   └── group.js              # 群聊操作 (逆向 mbox API)
+├── test/                     # Node.js 回归测试
+├── skills/
+│   └── baiduwangpan/         # Agent Skill 源文件 (SKILL.md + reference + scripts)
+├── baiduwangpan-skill.zip    # Agent Skill 打包 (Releases 附件)
 ├── bdp.js                    # 早期独立版 (保留参考)
 ├── bdp-group.js              # 早期独立版 (保留参考)
 └── bdp.py                    # Python 版 (备用)
 ```
 
+## 🤖 Agent Skill 使用
+
+本仓库附带一个标准格式的 Agent Skill，让 Claude Code / Codex / OpenClaw / Cursor 等 Agent 通过自然语言操作百度网盘。
+
+### 安装 Skill
+
+从 [Releases](https://github.com/NkAntony777/baiduwangpan-cli/releases) 下载 `baiduwangpan-skill.zip`，或直接复制仓库 `skills/baiduwangpan/` 文件夹：
+
+```bash
+# 各平台 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`

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,22 @@ 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 === "--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 {
@@ -90,14 +132,77 @@ function parseArgs(argv) {
 const cmds = {};
 
 cmds.login = async (args, json) => {
-  if (args.flags.bduss) config.set("bduss", args.flags.bduss);
-  if (args.flags.stoken) config.set("stoken", args.flags.stoken);
-  const cfg = config.get();
-  output(
-    { success: true, bduss: cfg.bduss ? "***set***" : "missing", stoken: cfg.stoken ? "***set***" : "missing" },
-    json,
-    () => console.log("Credentials saved to " + config.CONFIG_FILE)
-  );
+  // 方式 1: 手动传入凭证
+  if (args.flags.bduss || args.flags.stoken) {
+    if (!args.flags.bduss || !args.flags.stoken) {
+      throw new Error("Manual login requires both --bduss and --stoken");
+    }
+    config.setAuth({
+      bduss: args.flags.bduss,
+      stoken: args.flags.stoken,
+      webTransport: "curl",
+    });
+    const cfg = config.get();
+    output(
+      { success: true, bduss: cfg.bduss ? "***set***" : "missing", stoken: cfg.stoken ? "***set***" : "missing" },
+      json,
+      () => console.log("Credentials saved to " + config.CONFIG_FILE)
+    );
+    return;
+  }
+
+  // 方式 2: 浏览器自动登录（扫码，Agent 代劳）
+  const { browserLogin } = require("../lib/browser-login");
+  const status = (msg) => {
+    if (!json) console.log(msg);
+  };
+
+  status("🔐 bdp login: 未提供 --bduss/--stoken，启动浏览器扫码登录...");
+  try {
+    const previous = config.get();
+    const creds = await browserLogin({
+      onStatus: status,
+      profileDir: previous.browserProfile || undefined,
+      port: previous.webTransport === "browser" ? previous.browserPort : undefined,
+    });
+    config.setAuth({
+      bduss: creds.bduss,
+      stoken: creds.stoken,
+      webTransport: "browser",
+      browserProfile: creds.browserProfile,
+      browserPort: creds.browserPort,
+    });
+    status("✅ 登录成功，凭证已保存到 " + config.CONFIG_FILE);
+
+    // 同步登录 BaiduPCS-Go 引擎（全盘操作依赖）
+    try {
+      const { spawnSync } = require("child_process");
+      const cfg = config.get();
+      const loginResult = spawnSync(cfg.pcsPath, ["login", `-bduss=${creds.bduss}`, `-stoken=${creds.stoken}`], {
+        encoding: "utf-8",
+        timeout: 30000,
+      });
+      if (loginResult.stdout && loginResult.stdout.includes("登录成功")) {
+        status("✅ BaiduPCS-Go 引擎已同步登录");
+      } else {
+        status("⚠️ BaiduPCS-Go 引擎登录失败: " + (loginResult.stdout || loginResult.stderr || "未知错误").trim().substring(0, 100));
+      }
+    } catch (e) {
+      status("⚠️ BaiduPCS-Go 引擎登录异常: " + e.message);
+    }
+
+    if (json) {
+      console.log(JSON.stringify({ success: true, method: "browser-qr", bduss: "***set***", stoken: "***set***" }));
+    }
+  } catch (e) {
+    if (json) {
+      console.log(JSON.stringify({ error: e.message }));
+    } else {
+      console.error(`[ERROR] ${e.message}`);
+      console.error("        提示: 也可手动方式 bdp login --bduss <值> --stoken <值>");
+    }
+    process.exit(1);
+  }
 };
 
 cmds.whoami = async (args, json) => {
@@ -107,6 +212,7 @@ cmds.whoami = async (args, json) => {
       loggedIn: !!(cfg.bduss && cfg.stoken),
       bduss: cfg.bduss ? "***set***" : "missing",
       stoken: cfg.stoken ? "***set***" : "missing",
+      webTransport: cfg.webTransport,
       pcsPath: cfg.pcsPath,
       configFile: config.CONFIG_FILE,
     },
@@ -115,6 +221,7 @@ cmds.whoami = async (args, json) => {
       console.log(`Status:     ${d.loggedIn ? "✅ Logged in" : "❌ Not logged in"}`);
       console.log(`BDUSS:      ${d.bduss}`);
       console.log(`STOKEN:     ${d.stoken}`);
+      console.log(`Web API:    ${d.webTransport}`);
       console.log(`PCS Path:   ${d.pcsPath}`);
       console.log(`Config:     ${d.configFile}`);
     }
@@ -127,6 +234,7 @@ cmds.config = async (args, json) => {
     console.log("Configuration:");
     console.log(`  bduss:     ${d.bduss ? d.bduss.substring(0, 10) + "..." : "(not set)"}`);
     console.log(`  stoken:    ${d.stoken ? d.stoken.substring(0, 10) + "..." : "(not set)"}`);
+    console.log(`  web API:   ${d.webTransport}`);
     console.log(`  pcsPath:   ${d.pcsPath}`);
     console.log(`  ua:        ${d.ua.substring(0, 40)}...`);
     console.log(`  maxBytes:  ${d.maxBytes}`);
@@ -284,29 +392,119 @@ 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,
+  };
+  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.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,
+  };
+  verboseLog(args, `gtree gid=${gid} depth=${opts.depth} concurrency=${opts.concurrency} maxNodes=${opts.maxNodes}`);
+  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,
+  };
+
+  verboseLog(args, `gsearch gid=${gid} keyword="${keyword}" page=${opts.page} limit=${opts.limit} concurrency=${opts.concurrency} unique=${opts.unique} all=${opts.all}`);
+  const result = await group.searchFiles(gid, keyword, opts);
+
+  if (result.partial) {
+    verboseLog(args, `partial: ${result.failedShares}/${result.totalShares} shares failed`);
+  }
+
+  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.partial) {
+      console.error(`[verbose] ${result.failedShares} shares failed (partial result)`);
+    }
+  }
+};
+
+cmds.error = async (args, json) => {
+  const code = args._[0] || "-3";
+  const ERRORS = {
+    "-3": "群分享 API 拒绝请求。已观察到大目录、错误的 msgId/fromUk、过期分享都可能触发。\n" +
+          "处理：减小 --page-size（自动重试 50→20→10），或携带 gsearch 返回的 fromUk/msgId/parentFsId 信息重试；\n" +
+          "      若回退到父目录（fallback level=parent），Agent 应从父目录换路径继续遍历。",
+    "-6": "接口鉴权失败。通常为 access_token/cookie 失效，请重新执行 bdp login。",
+  };
+  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 ───────────────────────────────────────────────
@@ -332,22 +530,38 @@ 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
+                             [--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] [--no-unique] [--all]
+  error <code>               Explain an error code (e.g. -3)
 
 CONFIGURATION
-  login --bduss X --stoken Y  Save credentials
+  login                        Browser QR login (auto-detect cookies)
+  login --bduss X --stoken Y   Save credentials manually
   whoami                       Check login status
   config                       Show 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)
+  --concurrency <N>           Parallel share scans for gsearch/gtree (default 4)
+  --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
@@ -357,7 +571,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);
@@ -372,6 +589,7 @@ async function main() {
     process.exit(0);
   }
 
+  let exitCode = 0;
   try {
     await handler(args, json);
   } catch (e) {
@@ -380,8 +598,13 @@ async function main() {
     } else {
       console.error(`[ERROR] ${e.message}`);
     }
-    process.exit(1);
+    exitCode = 1;
+  } finally {
+    try {
+      require("../lib/browser-login").disconnectBrowserSession();
+    } catch {}
   }
+  process.exit(exitCode);
 }
 
 main();