baiduwangpan-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NkAntony777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+<div align="center">
+
+# baiduwangpan-cli
+
+**百度网盘 CLI — 全盘读写 · 免下载读取 · 群聊文件浏览**
+
+专为 AI Agent 设计的百度网盘命令行工具
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/baiduwangpan-cli)](https://www.npmjs.com/package/baiduwangpan-cli)
+[![npm downloads](https://img.shields.io/npm/dm/baiduwangpan-cli)](https://www.npmjs.com/package/baiduwangpan-cli)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)]()
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## ✨ 特性
+
+- **🗂️ 全盘访问** — 不受 `/apps/` 目录限制，读写网盘任意路径
+- **📄 免下载读取** — 通过 HTTP Range 直接读取文件内容到 stdout，无需下载整个文件
+- **👥 群聊文件浏览** — 逆向 mbox API，列出群组、浏览群内分享库、搜索群文件
+- **🤖 Agent 友好** — 所有命令支持 `--json` 结构化输出，零解析成本
+- **🔧 双模式** — 既是 CLI 工具，也可作为 Node.js 库 `require()` 使用
+- **🔐 凭证安全** — 配置存储在 `~/.bdp/config.json`，不写入代码或日志
+
+## 📌 能力一览
+
+| 能力 | 命令 | 说明 |
+|:-----|:------|:-----|
+| 列目录 | `bdp ls /` | 全盘任意目录 |
+| 搜索文件名 | `bdp search "报告"` | 递归全盘搜索 |
+| **读取文件内容** | `bdp cat /文档/data.json` | 免下载，限 1MB |
+| **读取前 N 行** | `bdp head -n 50 /文档/log.txt` | 免下载 |
+| **读取后 N 行** | `bdp tail -n 30 /文档/log.txt` | 免下载 |
+| **搜索文件内容** | `bdp grep "关键词" /文档/file.txt` | 免下载 |
+| 预览文件 | `bdp peek /文档/report.pdf` | 类型检测 + 前 10 行 |
+| 下载 | `bdp get /文档/file.zip` | 保存到本地 |
+| 上传 | `bdp put ./file.txt /文档/` | 全盘任意位置 |
+| **列出群组** | `bdp groups` | 所有群聊 + gid |
+| **群内分享库** | `bdp gshares <gid>` | 顶层分享目录 |
+| **浏览群文件** | `bdp gls <gid> <fs_id>` | 分页 + 递归 |
+| **搜索群文件** | `bdp gsearch <gid> "关键词"` | 按文件名搜索 |
+
+## 🚀 快速开始
+
+### 1. 安装
+
+```bash
+npm install -g baiduwangpan-cli
+```
+
+安装时会**自动下载** BaiduPCS-Go 引擎（支持 GitHub 镜像加速，国内也能装）。也支持手动克隆：
+
+```bash
+git clone https://github.com/NkAntony777/baiduwangpan-cli.git
+cd baiduwangpan-cli
+npm install        # postinstall 自动下载引擎
+npm link           # 全局注册 bdp 命令
+```
+
+> **依赖**: Node.js 14+ 和 `curl`（已在 Windows 10+ / macOS / 大多数 Linux 预装）
+
+### 2. 配置认证
+
+```bash
+bdp login --bduss <你的BDUSS> --stoken <你的STOKEN>
+bdp whoami  # 验证
+```
+
+<details>
+<summary>📋 如何获取 BDUSS 和 STOKEN</summary>
+
+1. 浏览器打开 [pan.baidu.com](https://pan.baidu.com) 并登录
+2. 按 `F12` → **Application** → **Cookies** → `https://pan.baidu.com`
+3. 找到 **BDUSS** 和 **STOKEN** 的值，复制
+
+> ⚠️ STOKEN 必须在百度网盘页面获取（不是百度首页），值中应包含大写字母。
+
+</details>
+
+### 3. 开始使用
+
+```bash
+# 浏览网盘
+bdp ls /
+bdp search "中医"
+
+# 免下载读取文件
+bdp head -n 10 /文档/data.csv
+bdp cat /文档/config.json
+
+# 浏览群聊文件
+bdp groups
+bdp gshares 539478953581833690
+bdp gls 539478953581833690 742474845517885
+bdp gsearch 539478953581833690 "倪海厦"
+```
+
+## 📖 完整命令参考
+
+### 网盘文件操作
+
+```
+bdp ls [path]                    列出目录
+bdp search <keyword> [-p dir]    搜索文件名
+bdp cat <path>                   读取文件内容 (免下载, 限 1MB)
+bdp head [-n N] <path>           读取前 N 行 (默认 20)
+bdp tail [-n N] <path>           读取后 N 行 (默认 20)
+bdp grep <pattern> <path>        搜索文件内容
+bdp peek <path>                  预览文件信息 + 前 10 行
+bdp get <path> [-o dir]          下载文件
+bdp put <local> <remote>         上传文件
+bdp mkdir <path>                 创建目录
+bdp rm <path>                    删除文件/目录
+```
+
+### 群聊文件操作
+
+```
+bdp groups                       列出所有群组
+bdp gshares <gid>                列出群内分享库
+bdp gls <gid> <fs_id> [--page N] 浏览分享库内容
+bdp gsearch <gid> <keyword>      搜索群文件名
+```
+
+### 通用选项
+
+```
+--json                           JSON 结构化输出 (Agent 友好)
+-n <N>                           行数 (head/tail, 默认 20)
+-p <path>                        搜索路径 (search, 默认 /)
+-i                               忽略大小写 (grep)
+-N                               显示行号 (cat/grep)
+-o <dir>                         输出目录 (get)
+--page <N>                       页码 (gls)
+```
+
+## 🤖 Agent 集成示例
+
+所有命令支持 `--json` 输出，适合 AI Agent 直接调用和解析：
+
+```bash
+# Agent 获取群组列表 (JSON)
+bdp groups --json
+# → [{"gid":"539478953581833690","name":"国学文化SVIP13",...}]
+
+# Agent 读取文件内容 (JSON)
+bdp head -n 5 /文档/data.csv --json
+# → {"path":"/文档/data.csv","lines":5,"content":["header","row1","row2",...]}
+
+# Agent 搜索群文件 (JSON)
+bdp gsearch 539478953581833690 "倪海厦" --json
+# → [{"name":"N 倪海厦","path":"/全店svip200位大师课(共16T)/N 倪海厦","isDir":true,...}]
+```
+
+### 作为 Node.js 库使用
+
+```javascript
+const { pan, group } = require('baiduwangpan-cli');
+
+// 免下载读取文件
+const content = pan.cat('/文档/data.json');
+
+// 搜索群聊文件
+const results = await group.searchFiles('539478953581833690', '倪海厦');
+```
+
+## 🏗️ 架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Agent / 用户                      │
+├─────────────┬───────────────────────────────────────┤
+│   CLI 模式  │            库模式 (require)            │
+│  bdp <cmd>  │     const {pan, group} = require()    │
+├─────────────┴───────────────────────────────────────┤
+│                   bin/bdp.js                         │
+│              (统一命令解析 + 路由)                    │
+├──────────────────┬──────────────────────────────────┤
+│    lib/pan.js    │         lib/group.js             │
+│   全盘文件操作    │        群聊文件浏览               │
+├──────────────────┼──────────────────────────────────┤
+│  BaiduPCS-Go     │     lib/http.js (curl)           │
+│  (BDUSS 认证)    │     mbox API (逆向)              │
+│  locate → dlink  │     /mbox/group/listshare        │
+│  upload/download │     /mbox/msg/shareinfo          │
+├──────────────────┴──────────────────────────────────┤
+│              百度网盘 CDN / API                      │
+└─────────────────────────────────────────────────────┘
+```
+
+### 免下载读取原理
+
+```
+bdp cat /文档/报告.txt
+    │
+    ├── BaiduPCS-Go locate /文档/报告.txt
+    │       → 获取 CDN 直链 dlink (有效期 8h)
+    │
+    ├── curl -r 0-1048575 <dlink>
+    │       → HTTP Range 请求，只读取前 1MB
+    │       → 百度 CDN 返回 206 Partial Content
+    │
+    └── stdout 输出文件内容
+            → Agent 直接读取，无需下载整个文件
+```
+
+### 群聊 API 链路（逆向 `/mbox/`）
+
+```
+bdp groups                          bdp gshares <gid>
+    │                                   │
+    ├── /mbox/group/list                ├── /mbox/group/listshare
+    │   → 获取全部群组 (gid)             │   → 获取分享库 (msg_id + from_uk + fs_id)
+    │                                   │
+    └───────────────────────────────────┘
+                ↓
+        bdp gls <gid> <fs_id>
+                │
+                ├── /mbox/msg/shareinfo
+                │   → 浏览文件/子目录 (分页)
+                │   → 递归遍历目录树
+                ↓
+            文件列表 (名称/大小/类型/fs_id)
+```
+
+## 📁 项目结构
+
+```
+baiduwangpan-cli/
+├── package.json              # npm 配置 (bin: bdp)
+├── bin/
+│   └── bdp.js                # CLI 入口 (统一命令解析)
+├── lib/
+│   ├── index.js              # 库导出
+│   ├── config.js             # 配置管理 (~/.bdp/config.json)
+│   ├── http.js               # HTTP 客户端 (curl 封装)
+│   ├── pan.js                # 网盘操作 (BaiduPCS-Go 桥接)
+│   └── group.js              # 群聊操作 (逆向 mbox API)
+├── bdp.js                    # 早期独立版 (保留参考)
+├── bdp-group.js              # 早期独立版 (保留参考)
+└── bdp.py                    # Python 版 (备用)
+```
+
+## ⚠️ 注意事项
+
+- **BDUSS 有效期**：Cookie 会过期，失效后重新执行 `bdp login`
+- **下载限速**：非 SVIP 用户下载受百度限速策略限制
+- **cat 限制**：为防止误读超大文件，`cat` 默认限制 1MB，可通过 `BDP_MAX_CAT_BYTES` 环境变量调整
+- **群聊文件**：群聊 API 为逆向获取，可能随百度服务端变更而失效
+
+## 🤝 致谢
+
+- [BaiduPCS-Go](https://github.com/qjfoidnh/BaiduPCS-Go) — 强大的百度网盘 Go 客户端，本工具的底层引擎
+- [hustuhao/bdntoy](https://github.com/hustuhao/bdntoy) — mbox API 逆向参考
+- 所有百度网盘逆向工程社区的贡献者
+
+## 📄 License
+
+[MIT](LICENSE)

package/bin/bdp.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+
+/**
+ * bdp — 百度网盘统一 CLI 工具
+ *
+ * 网盘文件操作:
+ *   bdp ls [path]                  列出目录
+ *   bdp search <keyword> [-p dir]  全盘搜索
+ *   bdp cat <path>                 读取文件内容（免下载）
+ *   bdp head [-n N] <path>         读取前 N 行
+ *   bdp tail [-n N] <path>         读取后 N 行
+ *   bdp grep <pattern> <path>      搜索文件内容
+ *   bdp peek <path>                预览文件信息
+ *   bdp get <path> [-o dir]        下载文件
+ *   bdp put <local> <remote>       上传文件
+ *   bdp mkdir <path>               创建目录
+ *   bdp rm <path>                  删除文件
+ *
+ * 群聊文件操作:
+ *   bdp groups                     列出所有群组
+ *   bdp gshares <gid>              列出群内分享库
+ *   bdp gls <gid> <fs_id>          浏览分享库内容
+ *   bdp gsearch <gid> <keyword>    搜索群文件
+ *
+ * 配置:
+ *   bdp login --bduss X --stoken Y  设置认证
+ *   bdp whoami                      查看当前状态
+ *   bdp config                      查看配置
+ *
+ * 全局选项:
+ *   --json                         JSON 输出（Agent 友好）
+ */
+
+const { config } = require("../lib");
+const pan = require("../lib/pan");
+const group = require("../lib/group");
+
+// ── Utils ──────────────────────────────────────────────
+
+function formatSize(bytes) {
+  if (!bytes || bytes === 0) return "-";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
+}
+
+function output(data, jsonFlag, formatter) {
+  if (jsonFlag) {
+    console.log(JSON.stringify(data, null, 2));
+  } else if (formatter) {
+    formatter(data);
+  }
+}
+
+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 === "-n" || arg === "--lines") {
+      opts.flags.n = parseInt(argv[++i], 10) || 20;
+    } else if (arg === "-p" || arg === "--path") {
+      opts.flags.p = argv[++i];
+    } else if (arg === "-k" || arg === "--keyword") {
+      opts.flags.k = argv[++i];
+    } else if (arg === "-i" || arg === "--ignore-case") {
+      opts.flags.i = true;
+    } else if (arg === "--number" || arg === "-N") {
+      opts.flags.number = true;
+    } else if (arg === "-o" || arg === "--output") {
+      opts.flags.o = argv[++i];
+    } else if (arg === "--bduss") {
+      opts.flags.bduss = argv[++i];
+    } else if (arg === "--stoken") {
+      opts.flags.stoken = argv[++i];
+    } else if (arg === "--page") {
+      opts.flags.page = parseInt(argv[++i], 10) || 1;
+    } else if (arg.startsWith("-")) {
+      opts.flags[arg.replace(/^-+/, "")] = true;
+    } else {
+      opts._.push(arg);
+    }
+  }
+  return opts;
+}
+
+// ── Commands ───────────────────────────────────────────
+
+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)
+  );
+};
+
+cmds.whoami = async (args, json) => {
+  const cfg = config.get();
+  output(
+    {
+      loggedIn: !!(cfg.bduss && cfg.stoken),
+      bduss: cfg.bduss ? "***set***" : "missing",
+      stoken: cfg.stoken ? "***set***" : "missing",
+      pcsPath: cfg.pcsPath,
+      configFile: config.CONFIG_FILE,
+    },
+    json,
+    (d) => {
+      console.log(`Status:     ${d.loggedIn ? "✅ Logged in" : "❌ Not logged in"}`);
+      console.log(`BDUSS:      ${d.bduss}`);
+      console.log(`STOKEN:     ${d.stoken}`);
+      console.log(`PCS Path:   ${d.pcsPath}`);
+      console.log(`Config:     ${d.configFile}`);
+    }
+  );
+};
+
+cmds.config = async (args, json) => {
+  const cfg = config.get();
+  output(cfg, json, (d) => {
+    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(`  pcsPath:   ${d.pcsPath}`);
+    console.log(`  ua:        ${d.ua.substring(0, 40)}...`);
+    console.log(`  maxBytes:  ${d.maxBytes}`);
+    console.log(`  file:      ${config.CONFIG_FILE}`);
+  });
+};
+
+cmds.ls = async (args, json) => {
+  const dirPath = args._[0] || "/";
+  const raw = pan.ls(dirPath);
+  if (json) {
+    console.log(JSON.stringify({ path: dirPath, raw }));
+  } else {
+    console.log(raw);
+  }
+};
+
+cmds.search = async (args, json) => {
+  const keyword = args.flags.k || args._[0] || "";
+  const searchPath = args.flags.p || "/";
+  if (!keyword) { console.error("Usage: bdp search <keyword> [-p /path]"); process.exit(1); }
+  const raw = pan.search(keyword, searchPath);
+  if (json) {
+    console.log(JSON.stringify({ keyword, path: searchPath, raw }));
+  } else {
+    console.log(raw);
+  }
+};
+
+cmds.cat = async (args, json) => {
+  const filePath = args._[0];
+  if (!filePath) { console.error("Usage: bdp cat <path>"); process.exit(1); }
+  const text = pan.cat(filePath);
+  if (json) {
+    console.log(JSON.stringify({ path: filePath, content: text }));
+  } else if (args.flags.number) {
+    text.split("\n").forEach((line, i) => {
+      console.log(`${String(i + 1).padStart(6)}  ${line}`);
+    });
+  } else {
+    process.stdout.write(text);
+  }
+};
+
+cmds.head = async (args, json) => {
+  const filePath = args._[0];
+  if (!filePath) { console.error("Usage: bdp head [-n N] <path>"); process.exit(1); }
+  const n = args.flags.n || 20;
+  const lines = pan.head(filePath, n);
+  if (json) {
+    console.log(JSON.stringify({ path: filePath, lines: n, content: lines }));
+  } else {
+    lines.forEach((l) => console.log(l));
+  }
+};
+
+cmds.tail = async (args, json) => {
+  const filePath = args._[0];
+  if (!filePath) { console.error("Usage: bdp tail [-n N] <path>"); process.exit(1); }
+  const n = args.flags.n || 20;
+  const lines = pan.tail(filePath, n);
+  if (json) {
+    console.log(JSON.stringify({ path: filePath, lines: n, content: lines }));
+  } else {
+    lines.forEach((l) => console.log(l));
+  }
+};
+
+cmds.grep = async (args, json) => {
+  const pattern = args._[0];
+  const filePath = args._[1];
+  if (!pattern || !filePath) { console.error("Usage: bdp grep <pattern> <path>"); process.exit(1); }
+  const matches = pan.grep(pattern, filePath, { ignoreCase: args.flags.i });
+  if (json) {
+    console.log(JSON.stringify({ path: filePath, pattern, matches }));
+  } else {
+    matches.forEach((m) => {
+      if (args.flags.number) console.log(`${filePath}:${m.line}:${m.content}`);
+      else console.log(m.content);
+    });
+  }
+};
+
+cmds.peek = async (args, json) => {
+  const filePath = args._[0];
+  if (!filePath) { console.error("Usage: bdp peek <path>"); process.exit(1); }
+  const info = pan.peek(filePath);
+  output(info, json, (d) => {
+    console.log(`Path:   ${d.path}`);
+    console.log(`Size:   ${d.size ? formatSize(d.size) : "unknown"}`);
+    console.log(`Type:   ${d.type || (d.isDir ? "directory" : "unknown")}`);
+    console.log(`Dlink:  ${d.dlink ? "✅" : "❌"}`);
+    if (d.preview) {
+      console.log(`\n── Preview ──`);
+      d.preview.forEach((l) => console.log(l));
+    }
+  });
+};
+
+cmds.get = async (args, json) => {
+  const filePath = args._[0];
+  if (!filePath) { console.error("Usage: bdp get <path> [-o dir]"); process.exit(1); }
+  const saveTo = args.flags.o;
+  const raw = pan.download(filePath, saveTo);
+  output({ path: filePath, savedTo: saveTo || "default", raw }, json, () => console.log(raw));
+};
+
+cmds.put = async (args, json) => {
+  const local = args._[0];
+  const remote = args._[1];
+  if (!local || !remote) { console.error("Usage: bdp put <local> <remote>"); process.exit(1); }
+  const raw = pan.upload(local, remote);
+  output({ local, remote, raw }, json, () => console.log(raw));
+};
+
+cmds.mkdir = async (args, json) => {
+  const dirPath = args._[0];
+  if (!dirPath) { console.error("Usage: bdp mkdir <path>"); process.exit(1); }
+  const raw = pan.mkdir(dirPath);
+  output({ path: dirPath, raw }, json, () => console.log(raw));
+};
+
+cmds.rm = async (args, json) => {
+  const filePath = args._[0];
+  if (!filePath) { console.error("Usage: bdp rm <path>"); process.exit(1); }
+  const raw = pan.remove(filePath);
+  output({ path: filePath, raw }, json, () => console.log(raw));
+};
+
+// ── Group Commands ─────────────────────────────────────
+
+cmds.groups = async (args, json) => {
+  const groups = await group.listGroups();
+  output(groups, json, (list) => {
+    console.log(`${list.length} groups:\n`);
+    list.forEach((g, i) => {
+      console.log(`  [${i}] ${g.name}  (gid: ${g.gid})`);
+    });
+  });
+};
+
+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);
+  output(shares, json, (list) => {
+    console.log(`${list.length} shares in group ${gid}:\n`);
+    list.forEach((s, i) => {
+      console.log(`  [${i}] ${s.name} ${s.isDir ? "[DIR]" : ""}  ${formatSize(s.size)}  fs_id:${s.fsId}`);
+      console.log(`      shared by: ${s.fromUser}  msg_id:${s.msgId}`);
+    });
+  });
+};
+
+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) => {
+      const dir = f.isDir ? "[DIR] " : "      ";
+      console.log(`  ${dir}${f.name}  ${formatSize(f.size)}  fs_id:${f.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) => {
+      const dir = r.isDir ? "[DIR] " : "      ";
+      console.log(`  ${dir}${r.path || r.name}  ${formatSize(r.size)}  fs_id:${r.fsId}`);
+    });
+  });
+};
+
+// ── Main ───────────────────────────────────────────────
+
+const HELP = `bdp — 百度网盘 CLI
+
+USAGE
+  bdp <command> [options] [arguments]
+
+PAN FILE OPERATIONS (全盘)
+  ls [path]                  List directory
+  search <keyword> [-p dir]  Search files by name
+  cat <path>                 Read file content (no download, max 1MB)
+  head [-n N] <path>         Read first N lines (default 20)
+  tail [-n N] <path>         Read last N lines (default 20)
+  grep <pattern> <path>      Search inside file content
+  peek <path>                Preview file info + first lines
+  get <path> [-o dir]        Download file
+  put <local> <remote>       Upload file
+  mkdir <path>               Create directory
+  rm <path>                  Delete file/dir
+
+GROUP CHAT OPERATIONS (群聊)
+  groups                     List all groups
+  gshares <gid>              List share libraries in group
+  gls <gid> <fs_id>          Browse files in a share
+  gsearch <gid> <keyword>    Search group file names
+
+CONFIGURATION
+  login --bduss X --stoken Y  Save credentials
+  whoami                       Check login status
+  config                       Show configuration
+
+OPTIONS
+  --json                      Output JSON (for Agent consumption)
+  -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)
+
+EXAMPLES
+  bdp login --bduss abc123 --stoken def456
+  bdp ls /
+  bdp search "报告"
+  bdp head -n 50 /文档/日志.txt
+  bdp groups --json
+  bdp gshares 539478953581833690
+  bdp gls 539478953581833690 742474845517885 --json
+  bdp gsearch 539478953581833690 "倪海厦"`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const rest = argv.slice(1);
+  const args = parseArgs(rest);
+  const json = args.flags.json || false;
+
+  const handler = cmds[command];
+  if (!handler) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  try {
+    await handler(args, json);
+  } catch (e) {
+    if (json) {
+      console.log(JSON.stringify({ error: e.message }));
+    } else {
+      console.error(`[ERROR] ${e.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+main();