{"id":"4dfccc99-2673-4c6a-b5aa-3fa3b24e634a","entityType":"agent","slug":"clawhub-may-yaha-baidu-netdisk-storage","name":"Baidu Drive","canonicalUrl":"https://www.xpersona.co/agent/clawhub-may-yaha-baidu-netdisk-storage","canonicalPath":"/agent/clawhub-may-yaha-baidu-netdisk-storage","generatedAt":"2026-10-09T16:16:01.814Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":null},"description":"百度网盘(Baidu Drive)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。 TRIGGER: 用户提及\"百度网盘/bdpan/网盘/云盘/baidu drive/Baidu Drive\"并涉及文件操作。 DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 3.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17f4ba5w8e33tn7eqqvnxt76183gkmk:baidu-netdisk-storage","sourceUrl":"https://clawhub.ai/may-yaha/baidu-netdisk-storage","homepage":"https://clawhub.ai/may-yaha/skills/baidu-netdisk-storage","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/may-yaha/baidu-netdisk-storage","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/may-yaha/skills/baidu-netdisk-storage","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":59,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Baidu Drive technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":null},"stars":null,"forks":null,"downloads":3852,"packageName":null,"latestVersion":"1.4.3","tractionLabel":"3.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T06:35:35.991Z","lastCrawledAt":"2026-10-09T06:35:35.991Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T06:35:35.991Z","lastVerifiedAt":null,"highlights":[{"version":"1.4.3","createdAt":"2026-04-16T10:15:00.365Z","changelog":"refactor(skill): 统一英文名 baidu netdisk → baidu drive，移除公测标识","fileCount":12,"zipByteSize":30746},{"version":"1.4.0","createdAt":"2026-04-09T10:39:20.439Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":29557},{"version":"1.3.0","createdAt":"2026-03-27T10:46:48.337Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":28484},{"version":"2.0.1","createdAt":"2026-03-27T10:36:39.771Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":27890},{"version":"2.0.0","createdAt":"2026-03-27T10:30:38.860Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":27774},{"version":"1.2.2","createdAt":"2026-03-26T07:18:45.338Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":30564},{"version":"1.2.1","createdAt":"2026-03-26T06:35:00.580Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":31194},{"version":"1.2.0","createdAt":"2026-03-26T06:15:36.521Z","changelog":"feat(skill): 修复常见 bug","fileCount":11,"zipByteSize":31192}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17f4ba5w8e33tn7eqqvnxt76183gkmk:baidu-netdisk-storage","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17f4ba5w8e33tn7eqqvnxt76183gkmk:baidu-netdisk-storage` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/may-yaha/baidu-netdisk-storage before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T16:16:01.811Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-may-yaha-baidu-netdisk-storage/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":null},"readme":"Skill: Baidu Drive\n\nOwner: may-yaha\n\nSummary: 百度网盘(Baidu Drive)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。 TRIGGER: 用户提及\"百度网盘/bdpan/网盘/云盘/baidu drive/Baidu Drive\"并涉及文件操作。 DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时。\n\nTags: latest:1.4.3\n\nVersion history:\n\nv1.4.3 | 2026-04-16T10:15:00.365Z | user\n\nrefactor(skill): 统一英文名 baidu netdisk → baidu drive，移除公测标识\n\nv1.4.0 | 2026-04-09T10:39:20.439Z | user\n\nfeat(skill): 修复常见 bug\n\nv1.3.0 | 2026-03-27T10:46:48.337Z | user\n\nfeat(skill): 修复常见 bug\n\nv2.0.1 | 2026-03-27T10:36:39.771Z | user\n\nfeat(skill): 修复常见 bug\n\nv2.0.0 | 2026-03-27T10:30:38.860Z | user\n\nfeat(skill): 修复常见 bug\n\nv1.2.2 | 2026-03-26T07:18:45.338Z | user\n\nfeat(skill): 修复常见 bug\n\nv1.2.1 | 2026-03-26T06:35:00.580Z | user\n\nfeat(skill): 修复常见 bug\n\nv1.2.0 | 2026-03-26T06:15:36.521Z | user\n\nfeat(skill): 修复常见 bug\n\nv1.0.0 | 2026-03-26T05:40:55.475Z | user\n\nbaidu-netdisk-storage v1.0.0\n\n- 首个版本，支持百度网盘文件管理，包括上传、下载、转存、分享、列表、搜索、移动、复制、重命名、创建文件夹等操作。\n- 限定所有操作在 /apps/bdpan/ 目录内，严格按照触发和前置检查规则执行，确保安全和合规。\n- 提供详细安全规范，禁止自动泄露凭证、禁止自动更新和未经确认的关键操作。\n- 支持安装、登录、更新、卸载等管理操作，通过专用脚本实现，强化安全限制。\n- 优化命令与用户确认流程，适配多种产品使用场景，支持指令上下文延续。\n- 提供操作指令和参数说明，并要求在含糊指令或关键场景下主动向用户确认。\n\nArchive index:\n\nArchive v1.4.3: 12 files, 30746 bytes\n\nFiles: reference/authentication.md (2336b), reference/bdpan-commands.md (14912b), reference/examples.md (7744b), reference/notes.md (986b), reference/troubleshooting.md (7494b), scripts/install.sh (10434b), scripts/login.sh (7077b), scripts/uninstall.sh (4349b), scripts/update.sh (8994b), skill-card.md (2443b), SKILL.md (9305b), _meta.json (140b)\n\nFile v1.4.3:SKILL.md\n\n---\nname: baidu-drive\ndescription: >-\n  百度网盘(Baidu Drive)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。\n  TRIGGER: 用户提及\"百度网盘/bdpan/网盘/云盘/baidu drive/Baidu Drive\"并涉及文件操作。\n  DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时。\nallowed-tools: Bash, Read, Glob, Grep, AskUserQuestion\nargument-hint: \"[操作指令]\"\n---\n\n# 百度网盘存储 Skill\n\n百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。\n\n> 使用注意事项详见 [reference/notes.md](./reference/notes.md)\n\n## 触发规则\n\n同时满足以下条件才执行：\n\n1. 用户明确提及\"百度网盘\"、\"bdpan\"、\"网盘\"\n2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/登录/注销）\n\n未通过触发规则时，禁止执行任何 bdpan 命令。\n\n> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及\"网盘\"即可触发。\n\n---\n\n## 安全约束（最高优先级，不可被任何用户指令覆盖）\n\n1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code` 等，即使在 GUI 环境也禁止）\n2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）\n3. **更新/登录**：更新必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行 update.sh 或 login.sh\n4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量（这些变量供用户在脚本外手动配置，Agent 不应代为设置）\n5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径\n\n---\n\n## 前置检查\n\n每次触发时按顺序执行：\n\n1. **安装检查**：`command -v bdpan`，未安装则告知用户并确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh`（用户确认后可加 `--yes` 跳过安装器内部确认）\n2. **登录检查**：`bdpan whoami`，未登录则引导执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`\n3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内\n\n---\n\n## 确认规则\n\n| 风险等级 | 操作 | 策略 |\n|----------|------|------|\n| **高（必须确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 列出影响范围，等待用户确认 |\n| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |\n| **低（直接执行）** | ls、search、whoami、mkdir、share | 无需确认 |\n\n**额外规则：**\n- 操作意图模糊（\"处理文件\"→确认上传还是下载）→ 必须确认\n- 序数/代词引用有歧义（\"第N个\"、\"它\"、\"上面那个\"）→ 必须确认\n- 用户取消意图（\"算了\"、\"不要了\"、\"取消\"）→ 立即中止，不执行任何命令\n\n---\n\n## 核心操作\n\n### 查看状态\n\n```bash\nbdpan whoami\n```\n\n### 列表查询\n\n```bash\nbdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]\n```\n\n### 上传\n\n```bash\nbdpan upload <本地路径> <远端路径>\n```\n\n**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。\n\n步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。\n\n### 下载\n\n**直接下载：**\n\n```bash\nbdpan download <远端路径> <本地路径>\n```\n\n步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → **检查文件大小决定下载策略** → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。\n\n**大文件下载策略（重要）：**\n\nAgent 的 Bash 工具有执行超时限制，大文件下载可能因超时而中断。必须根据文件大小选择下载策略：\n\n1. **获取文件大小**：用 `bdpan ls --json <远端路径>` 获取 `size` 字段（字节）\n2. **按大小分策略执行**：\n\n| 文件大小 | 策略 | 执行方式 |\n|----------|------|---------|\n| ≤ 50MB | 直接下载 | `bdpan download <远端路径> <本地路径>`，Bash timeout 设为 300000（5 分钟） |\n| > 50MB | 后台下载 | 使用 `nohup` 后台执行，Agent 轮询进度 |\n\n**小文件（≤ 50MB）直接下载：**\n\n正常执行 `bdpan download`，Bash 工具 timeout 参数设为 `300000`（5 分钟）。\n\n**大文件（> 50MB）后台下载流程：**\n\n```bash\n# 1. 启动后台下载（nohup + 进度日志）\nnohup bdpan download <远端路径> <本地路径> > /tmp/bdpan-dl-$$.log 2>&1 & echo $!\n```\n\n```bash\n# 2. 轮询检查进度（每 30 秒检查一次，使用 Bash run_in_background）\n#    检查进程是否存活 + 已下载文件大小\nkill -0 <PID> 2>/dev/null && echo \"running\" || echo \"done\"; ls -l <本地路径> 2>/dev/null; tail -5 /tmp/bdpan-dl-<PID>.log 2>/dev/null\n```\n\n```bash\n# 3. 下载完成后清理日志\nrm -f /tmp/bdpan-dl-<PID>.log\n```\n\nAgent 执行大文件后台下载时的行为规范：\n- 启动后台下载后，**立即告知用户**：下载已在后台启动，文件大小 X，预计需要 Y 时间\n- 每次轮询后向用户报告进度（已下载大小 / 总大小、百分比）\n- 下载完成后告知用户最终结果\n- 如果进程异常退出，检查日志并报告错误原因\n\n**分享链接下载（先转存再下载到本地）：**\n\n```bash\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd    # 提取码单独传入\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder  # 指定转存目录\n```\n\n> 分享链接下载同样适用大文件策略：转存完成后，用 `bdpan ls --json` 获取文件大小，再按上述策略执行下载。\n\n### 转存\n\n将分享文件转存到网盘，**不下载到本地**（与 download 分享链接模式的区别）。\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p <提取码> [-d 目标目录] [--json]\n```\n\n步骤：确认分享链接格式有效 → 确认有提取码（链接中含 `?pwd=` 或反问用户）→ 确认目标目录 → 执行。转存成功后只展示本次转存的文件（非整个目录），显示数量和目标目录。\n\n### 分享\n\n```bash\nbdpan share <路径> [路径...] [--json]\n```\n\n步骤：`bdpan ls` 确认文件存在 → 执行分享 → 展示链接+提取码+有效期。\n\n> 付费接口，需在百度网盘开放平台购买服务。\n\n### 搜索\n\n```bash\nbdpan search <关键词> [--category 0-7] [--no-dir|--dir-only] [--page-size N] [--page N] [--json]\n```\n\ncategory：0=全部 1=视频 2=音频 3=图片 4=文档 5=应用 6=其他 7=种子。`--no-dir` 和 `--dir-only` 互斥。\n\n### 移动 / 复制 / 重命名 / 创建文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\nbdpan cp <源路径> <目标目录>\nbdpan rename <路径> <新名称>       # 第二参数是文件名，非完整路径\nbdpan mkdir <路径>\n```\n\n---\n\n## 路径规则\n\n| 场景 | 格式 | 示例 |\n|------|------|------|\n| **命令参数** | 相对路径（相对于 `/apps/bdpan/`） | `bdpan upload ./f.txt docs/f.txt` |\n| **展示给用户** | 中文名 | \"已上传到：我的应用数据/bdpan/docs/f.txt\" |\n\n映射关系：`我的应用数据` ↔ `/apps`\n\n**禁止：** 命令中使用中文路径（`我的应用数据/...`）、展示时暴露 API 路径（`/apps/bdpan/...`）。\n\n---\n\n## 授权码处理\n\n用户发送 32 位十六进制字符串时，先确认：\"这是百度网盘授权码吗？确认后将执行登录流程。\" 确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`（不使用 `--yes`，保留安全确认环节）。\n\n---\n\n## 管理功能\n\n### 安装\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh [--yes]\n```\n\n安装器从百度 CDN（`issuecdn.baidupcs.com`）下载并执行。注意：install.sh 不执行本地 SHA256 校验，完整性依赖 HTTPS 传输保护。安全敏感场景建议先手动审查安装器内容或在沙箱中执行。\n\n### 登录 / 注销 / 卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh              # 登录（内置安全免责声明）\nbdpan logout                                            # 注销\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh [--yes]   # 卸载\n```\n\n### 更新（必须用户明确指令触发）\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh              # 检查并更新（需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check       # 仅检查更新\n```\n\n---\n\n## 参考文档\n\n遇到对应问题时按需查阅，无需预加载：\n\n| 文档 | 何时查阅 |\n|------|---------|\n| [bdpan-commands.md](./reference/bdpan-commands.md) | 需要完整命令参数、选项、JSON 输出格式 |\n| [authentication.md](./reference/authentication.md) | 认证流程细节、Token 管理 |\n| [examples.md](./reference/examples.md) | 更多使用示例（批量上传、自动备份等） |\n| [troubleshooting.md](./reference/troubleshooting.md) | 遇到错误需要排查 |\n\nFile v1.4.3:_meta.json\n\n{\n  \"ownerId\": \"kn732m45det8fggw8x5d7mv9jx80w2q0\",\n  \"slug\": \"baidu-netdisk-storage\",\n  \"version\": \"1.4.3\",\n  \"publishedAt\": 1776334500365\n}\n\nFile v1.4.3:reference/authentication.md\n\n# 认证指南\n\n本指南详细介绍 bdpan CLI 的登录认证流程。\n\n---\n\n## 登录方式\n\n> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。\n\n---\n\n## 验证登录状态\n\n```bash\nbdpan whoami\n```\n\n**已登录时输出：**\n```\n认证状态: 已登录\nToken 有效期至: 2026-03-10 10:30:00\n```\n\n**未登录时输出：**\n```\n认证状态: 未登录\n请执行 bdpan login 进行登录\n```\n\n---\n\n## 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n---\n\n## 常见问题\n\n### 登录后提示 Token 已过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n### 授权链接无效\n\n**症状：** 浏览器打开链接后提示链接无效\n\n**解决方案：**\n1. 重新执行登录脚本获取新的授权链接\n2. 确保在链接有效期内完成授权（通常 10 分钟）\n\n### 授权码输入后报错\n\n**症状：** 输入授权码后提示错误\n\n**解决方案：**\n1. 确保授权码复制完整，没有多余空格\n2. 检查浏览器中显示的授权码是否与输入的一致\n3. 如多次失败，重新执行登录脚本获取新授权码\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n---\n\n## 安全说明\n\n- **OAuth 2.0**：使用授权码模式，不存储用户密码\n- **Token 存储**：Token 加密存储在本地配置文件\n- **自动续期**：Token 快过期时工具会自动刷新\n\n---\n\n## 自动登录失败场景\n\n以下场景会自动切换到 OOB 模式：\n\n| 场景 | 说明 |\n|------|------|\n| SSH 远程登录 | 无图形界面 |\n| WSL 环境 | WebView 支持受限 |\n| 桌面环境锁定 | WebView 无法弹出 |\n| 浏览器未安装 | 无法打开 WebView |\n\n切换到 OOB 模式时，工具会自动提示授权链接，无需用户干预。\n\nFile v1.4.3:reference/bdpan-commands.md\n\n# bdpan CLI 命令快速参考\n\n## 认证命令\n\n### login - 登录授权\n\n> **⛔ Agent 必须通过登录脚本执行登录，禁止直接调用 `bdpan login`。详见 [SKILL.md](../SKILL.md) 安全约束。**\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本内置了安全免责声明和完整的 OOB 授权流程。无论 GUI 或非 GUI 环境，统一使用此脚本。\n\n### logout - 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n### uninstall - 完全卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh\n```\n\n完全卸载 bdpan CLI，自动执行以下操作：\n1. 注销登录并清除授权信息\n2. 删除配置目录（`~/.config/bdpan/`）\n3. 删除 bdpan 二进制文件（`~/.local/bin/bdpan`）\n\n**选项：**\n- `--yes, -y` - 跳过确认提示（自动化场景）\n\n**环境变量：**\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n### whoami - 查看认证状态\n\n```bash\nbdpan whoami\n```\n\n显示当前登录状态、用户名和 Token 有效期信息。\n\n**已登录时输出：**\n```\n认证状态: 已登录\n用户名: your_username\nToken 有效期至: 2026-04-04 10:30:00\n```\n\n**选项：**\n- `--json` - JSON 格式输出\n\n---\n\n## 文件操作命令\n\n### upload - 上传文件\n\n```bash\nbdpan upload <local> <remote>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `local` | 本地文件或文件夹路径 |\n| `remote` | 网盘目标路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 单文件上传\nbdpan upload ./report.pdf report.pdf\n\n# 文件夹上传\nbdpan upload ./project/ project/\n\n# 上传到子目录\nbdpan upload ./data.tar.gz backup/data.tar.gz\n```\n\n**选项：**\n- `--json` - JSON 格式输出上传结果\n\n### download - 下载文件\n\n```bash\nbdpan download <remote> <local> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `remote` | 网盘文件/文件夹路径（相对于 `/apps/bdpan/`）**或**百度网盘分享链接 |\n| `local` | 本地保存路径 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（用于分享链接，如果链接中未包含） |\n| `-t` | 自定义转存目录（相对路径自动拼接 `/apps/bdpan`，绝对路径直接使用） |\n| `--json` | JSON 格式输出下载结果 |\n\n**示例：**\n```bash\n# 单文件下载\nbdpan download report.pdf ./downloaded-report.pdf\n\n# 文件夹下载\nbdpan download project/ ./project-restore/\n\n# 从分享链接下载（链接中包含提取码）\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\n\n# 使用 -p 参数单独传入提取码\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd\n\n# 使用 -t 参数自定义转存目录\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder\n```\n\n**分享链接下载说明：**\n- 自动识别分享链接格式 `https://pan.baidu.com/s/1{surl}?pwd={pwd}`\n- 分享文件会先转存到 `/apps/bdpan/{日期}/` 目录（或使用 `-t` 指定的目录）\n- 然后下载到指定的本地路径\n\n### transfer - 转存分享文件到网盘（不下载到本地）\n\n```bash\nbdpan transfer <分享链接> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `分享链接` | 百度网盘分享链接 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（如果链接中未包含） |\n| `-d` | 目标目录（相对路径自动拼接 `/apps/bdpan`，默认为应用根目录） |\n| `--json` | JSON 格式输出转存结果 |\n\n**示例：**\n```bash\n# 基本用法 - 转存到应用根目录 /apps/bdpan/\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n\n# 提取码在链接中\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n\n# 指定目标目录\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd -d my-folder/\n\n# JSON 输出\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd --json\n```\n\n**与 download 的区别：**\n- `transfer` 仅将分享文件转存到自己的网盘，不下载到本地\n- `download` 会先转存再下载到本地路径\n- 适用于只需要保存到网盘、不需要本地副本的场景\n\n### ls - 查看文件列表\n\n```bash\nbdpan ls [path]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `path` | 要查看的目录路径 | 根目录 |\n\n**选项：**\n- `--json` - JSON 格式输出\n\n**示例：**\n```bash\n# 查看根目录\nbdpan ls\n\n# 查看子目录\nbdpan ls backup\n\n# JSON 输出\nbdpan ls --json\n```\n\n**输出格式：**\n```\n类型    大小          修改时间              文件名\n------  ------------  --------------------  --------\n目录     -            2026-02-20 10:30:00  documents\n文件    1.5 MB        2026-02-25 15:20:00  readme.txt\n文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n共 3 项\n```\n\n### share - 创建分享链接\n\n```bash\nbdpan share <path>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `path` | 要分享的文件或文件夹路径 |\n\n**示例：**\n```bash\n# 分享文件\nbdpan share report.pdf\n\n# 分享文件夹\nbdpan share project\n\n# JSON 输出\nbdpan share --json report.pdf\n```\n\n**输出格式：**\n```\n分享链接创建成功!\n链接: https://pan.baidu.com/s/1xxxxxxx\n提取码: abcd\n有效期: 7 天\n```\n\n### search - 搜索文件\n\n```bash\nbdpan search <关键词> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `关键词` | 搜索关键词（必填） |\n\n**选项：**\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--category` | int | `0` | 文件类型筛选：1=视频, 2=音频, 3=图片, 4=文档, 5=应用, 6=其他, 7=种子 |\n| `--page-size` | int | `5` | 每页数量（最大 50） |\n| `--page` | int | `1` | 页码 |\n| `--no-dir` | bool | `false` | 仅显示文件，排除文件夹 |\n| `--dir-only` | bool | `false` | 仅显示文件夹 |\n| `--json` | - | - | JSON 格式输出 |\n\n> `--no-dir` 和 `--dir-only` 互斥，不能同时使用。\n\n**示例：**\n```bash\n# 搜索文件\nbdpan search report\n\n# 搜索图片类型文件\nbdpan search photo --category 3\n\n# 搜索文件，排除文件夹，每页 10 条\nbdpan search data --no-dir --page-size 10\n\n# 翻页\nbdpan search report --page 2\n\n# JSON 输出\nbdpan search report --json\n```\n\n**输出格式：**\n```\n找到 15 个结果（第 1 页，共 3 页）\n\n#   名称              类型    大小      修改时间\n--- ----------------- ------- --------- ----------------\n1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n\n提示: 使用 --page 2 查看下一页\n```\n\n### mv - 移动文件或文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要移动的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 移动文件到子目录\nbdpan mv report.pdf backup\n\n# 移动文件夹\nbdpan mv old-project archive\n\n# JSON 输出\nbdpan mv report.pdf backup --json\n```\n\n**输出格式：**\n```\n已移动 report.pdf -> backup\n```\n\n### cp - 复制文件或文件夹\n\n```bash\nbdpan cp <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要复制的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 复制文件到子目录\nbdpan cp report.pdf backup\n\n# 复制文件夹\nbdpan cp project project-copy\n\n# JSON 输出\nbdpan cp report.pdf backup --json\n```\n\n**输出格式：**\n```\n已复制 report.pdf -> backup\n```\n\n### rename - 重命名文件或文件夹\n\n```bash\nbdpan rename <路径> <新名称>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要重命名的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `新名称` | 新文件名（仅名称，不含路径） |\n\n**示例：**\n```bash\n# 重命名文件\nbdpan rename old-name.pdf new-name.pdf\n\n# 重命名子目录中的文件\nbdpan rename docs/draft.md final.md\n\n# JSON 输出\nbdpan rename old-name.pdf new-name.pdf --json\n```\n\n**输出格式：**\n```\n已重命名 old-name.pdf -> new-name.pdf\n```\n\n### mkdir - 创建文件夹\n\n```bash\nbdpan mkdir <路径>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要创建的文件夹路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 创建文件夹\nbdpan mkdir backup\n\n# 创建多级目录\nbdpan mkdir backup/2026/03\n\n# JSON 输出\nbdpan mkdir backup --json\n```\n\n**输出格式：**\n```\n已创建文件夹: backup\n```\n\n---\n\n## 版本管理命令\n\n### update - 自动更新 Skill\n\n> **使用 `bash ${CLAUDE_SKILL_DIR}/scripts/update.sh` 更新 Skill 文件。CLI 更新由 `bdpan` 自身管理。**\n\n```bash\n# 检查并更新（交互式，需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh\n\n# 仅检查更新，不执行\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check\n\n# 跳过确认，自动更新（自动化场景）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --yes\n```\n\n**功能说明：**\n- 通过百度配置接口获取最新 Skill 版本信息\n- 对比本地 VERSION 文件判断是否需要更新\n- 下载 zip 包并解压覆盖，更新 VERSION 文件\n- 支持 SHA256 完整性校验（如配置中包含 checksum）\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `--check, -c` | 仅检查更新，不执行安装 |\n| `--yes, -y` | 跳过用户确认，自动执行更新 |\n| `--help` | 显示帮助信息 |\n\n### version - 查看版本信息\n\n```bash\n# 查看当前版本\nbdpan version\n\n# 检查是否有更新\nbdpan version --check\n```\n\n---\n\n## init - 查看安装信息（v3.4.0+）\n\n```bash\nbdpan init\n```\n\n显示安装路径、配置文件路径和 PATH 配置建议。\n\n**输出示例：**\n```\nbdpan 安装信息\n────────────────────────────\n安装路径: /home/user/.local/bin/bdpan\n配置路径: /home/user/.config/bdpan/config.json\n\nPATH 配置建议:\n  export PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n---\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config-path <path>` | 指定配置文件完整路径（适用于 AI Agent 集成） |\n| `--json` | JSON 格式输出 |\n| `--no-check-update` | 禁用版本更新检查 |\n| `--help` | 显示帮助 |\n| `--version` | 显示版本 |\n\n---\n\n## JSON 输出格式\n\n### ls 命令输出\n\n```json\n[\n  {\n    \"fs_id\": 524080722157776,\n    \"path\": \"我的应用数据/report.pdf\",\n    \"server_filename\": \"report.pdf\",\n    \"size\": 1536000,\n    \"isdir\": false,\n    \"md5\": \"a1b2c3d4e5f6...\",\n    \"server_mtime\": \"2026-02-25T15:20:00+08:00\",\n    \"server_ctime\": \"2026-02-25T14:00:00+08:00\"\n  },\n  {\n    \"fs_id\": 841873986109404,\n    \"path\": \"我的应用数据/documents\",\n    \"server_filename\": \"documents\",\n    \"size\": 0,\n    \"isdir\": true,\n    \"md5\": \"\",\n    \"server_mtime\": \"2026-02-20T10:30:00+08:00\",\n    \"server_ctime\": \"2026-02-20T09:00:00+08:00\"\n  }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fs_id` | number | 文件唯一 ID |\n| `path` | string | 文件路径（中文显示名，如 `我的应用数据/...`） |\n| `server_filename` | string | 文件名 |\n| `size` | number | 文件大小（字节），目录为 0 |\n| `isdir` | boolean | 是否为目录（`true`/`false`，注意是小写布尔值） |\n| `md5` | string | 文件 MD5 值，目录为空字符串 |\n| `server_mtime` | string | 服务端修改时间（ISO 8601 带时区） |\n| `server_ctime` | string | 服务端创建时间（ISO 8601 带时区） |\n\n> **注意：** `path` 字段返回中文显示名（`我的应用数据/...`），不是 API 路径（`/apps/bdpan/...`）。展示给用户时可直接使用此路径。\n\n### share 命令输出\n\n```json\n{\n  \"link\": \"https://pan.baidu.com/s/1xxxxxxx\",\n  \"short_url\": \"xxxxxxx\",\n  \"share_id\": 25747091668,\n  \"period\": 7,\n  \"pwd\": \"abcd\"\n}\n```\n\n### upload/download 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"local_path\": \"./report.pdf\",\n  \"remote_path\": \"report.pdf\"\n}\n```\n\n### transfer 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"remote_path\": \"my-folder/shared-file.pdf\",\n  \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n  \"file_count\": 1\n}\n```\n\n### search 命令输出\n\n```json\n{\n  \"total\": 15,\n  \"page\": 1,\n  \"page_size\": 5,\n  \"results\": [\n    {\n      \"fs_id\": 524080722157776,\n      \"path\": \"我的应用数据/bdpan/report.pdf\",\n      \"server_filename\": \"report.pdf\",\n      \"size\": 1536000,\n      \"isdir\": false,\n      \"category\": 4,\n      \"server_mtime\": \"2026-02-25T15:20:00+08:00\"\n    }\n  ]\n}\n```\n\n### mv/cp/rename/mkdir 命令输出\n\n```json\n{\n  \"status\": \"ok\"\n}\n```\n\n---\n\n## 路径规则\n\n- 所有路径相对于应用根目录 `/apps/bdpan/`\n- 支持相对路径: `backup/data.tar.gz`\n- 支持绝对路径: `/apps/bdpan/backup/data.tar.gz`\n- 路径穿越 `..` 会被自动阻止\n\n> **⛔ 双向路径映射规则：** 调用 bdpan 命令时，\"我的应用数据\" 必须转换为 `/apps`；向用户展示路径时，`/apps` 必须转换为 \"我的应用数据\"。详见 [路径规则](../SKILL.md) 章节。\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_PATH` | 配置文件完整路径（优先级最高） | 无 |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n\n**配置路径优先级（v3.4.0+）：**\n1. `--config-path` 命令行参数（最高优先级）\n2. `BDPAN_CONFIG_PATH` 环境变量\n3. `BDPAN_CONFIG_DIR` 环境变量 + `config.json`\n4. `~/.config/bdpan/config.json`（默认路径）\n\n**使用示例：**\n```bash\n# 使用命令行参数指定配置\nbdpan --config-path /custom/path/config.json ls\n\n# 使用环境变量指定配置\nexport BDPAN_CONFIG_PATH=/custom/path/config.json\nbdpan ls\n```\n\n### AI Agent 集成\n\n当 AI Agent 无法通过默认路径读取配置时，可以通过以下方式指定：\n\n```python\nimport subprocess\nimport os\n\nenv = os.environ.copy()\nenv[\"BDPAN_CONFIG_PATH\"] = \"/home/user/.config/bdpan/config.json\"\n\nresult = subprocess.run(\n    [\"bdpan\", \"ls\", \"--json\"],\n    env=env,\n    capture_output=True,\n    text=True\n)\n```\n\n---\n\n## 常见错误码\n\n| 错误 | 说明 | 解决方案 |\n|------|------|---------|\n| Token expired | Token 过期 | 重新登录 |\n| Path not allowed | 路径不在允许范围 | 使用 /apps/bdpan/ 下的路径 |\n| File not found | 文件不存在 | 检查路径是否正确 |\n| errno=13045 | 自己的分享链接 | 文件已在网盘中，直接使用 `bdpan ls` 查找 |\n\n---\n\n## 平台支持\n\n| 功能 | macOS | Linux | Windows (WSL) |\n|------|-------|-------|---------------|\n| 基础功能 | ✅ | ✅ | ✅ |\n| WebView 登录 | ✅ | - | -（WSL 无图形界面，使用 OOB 模式） |\n\nFile v1.4.3:reference/examples.md\n\n# 使用示例\n\n本文档包含 baidu drive 的详细使用示例。\n\n---\n\n## 上传并分享\n\n### 示例 1: 上传并分享单个文件\n\n```\n用户: 帮我上传并分享 ./report.pdf\nAI: [执行 bdpan upload ./report.pdf report.pdf]\n    [执行 bdpan share report.pdf]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: abcd\n    有效期: 7 天\n```\n\n### 示例 2: 上传并分享文件夹\n\n```\n用户: 把 ./project 文件夹上传并分享\nAI: [执行 bdpan upload ./project/ project/]\n    [执行 bdpan share project]\n\n    文件夹上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: efgh\n    有效期: 7 天\n```\n\n### 示例 3: 上传到子目录\n\n```\n用户: 上传 ./data.tar.gz 到 backup 目录并分享\nAI: [执行 bdpan upload ./data.tar.gz backup/data.tar.gz]\n    [执行 bdpan share backup/data.tar.gz]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: ijkl\n    有效期: 7 天\n```\n\n---\n\n## 下载文件\n\n### 示例 4: 下载单个文件\n\n```\n用户: 从网盘下载 report.pdf\nAI: [执行 bdpan download report.pdf ./report.pdf]\n\n    正在下载 report.pdf → ./report.pdf ...\n    ✓ 下载成功\n```\n\n### 示例 5: 下载文件夹\n\n```\n用户: 把 backup 文件夹下载到本地\nAI: [执行 bdpan download backup/ ./backup/]\n\n    正在下载 backup/ → ./backup/ ...\n    ✓ 下载成功\n```\n\n---\n\n## 文件列表\n\n### 示例 6: 查看已上传文件\n\n```\n用户: 查看我上传了哪些文件\nAI: [执行 bdpan ls]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    目录     -            2026-02-20 10:30:00  backup\n    文件    1.5 MB        2026-02-25 15:20:00  report.pdf\n    文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n    共 3 项\n```\n\n### 示例 7: 查看子目录\n\n```\n用户: 查看 backup 目录下的文件\nAI: [执行 bdpan ls backup]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    文件    2.1 GB        2026-02-19 08:00:00  data-2026-02-19.tar.gz\n    文件    1.8 GB        2026-02-18 08:00:00  data-2026-02-18.tar.gz\n\n    共 2 项\n```\n\n---\n\n## JSON 输出（用于脚本）\n\n### 示例 8: JSON 格式文件列表\n\n```\n用户: 列出所有文件名（JSON 格式）\nAI: [执行 bdpan ls --json]\n\n    输出:\n    [\n      {\n        \"Name\": \"report.pdf\",\n        \"IsDir\": false,\n        \"Size\": 1536000,\n        \"Modified\": \"2026-02-25T15:20:00Z\"\n      },\n      {\n        \"Name\": \"backup\",\n        \"IsDir\": true,\n        \"Size\": 0,\n        \"Modified\": \"2026-02-20T10:30:00Z\"\n      }\n    ]\n```\n\n### 示例 9: 使用 jq 处理输出\n\n```bash\n# 提取所有文件名\nbdpan ls --json | jq -r '.[].Name'\n\n# 只列出文件（排除目录）\nbdpan ls --json | jq '.[] | select(.IsDir == false)'\n\n# 按大小排序\nbdpan ls --json | jq 'sort_by(.Size) | reverse'\n\n# 检查文件是否存在\nbdpan ls --json | jq -e '.[] | select(.Name == \"target.txt\")'\n```\n\n---\n\n## 认证流程\n\n### 示例 10: 登录（统一使用 login.sh 脚本）\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n```\n用户: 帮我登录百度网盘\nAI: [执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh]\n\n    [展示安全免责声明]\n    已阅读上述安全须知，确认继续登录? [y/N]\n\n用户: y\nAI: 正在获取授权链接...\n\n    请在浏览器中打开以下链接完成授权:\n    https://openapi.baidu.com/oauth/2.0/authorize?...\n\n    授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n    [等待用户输入...]\n\n用户: [粘贴授权码] ca0ee3070f75d0246357e5c74d525bda\nAI: [处理授权码]\n\n    ✓ 登录成功！\n    用户: username@baidu.com\n```\n\n---\n\n## 转存分享文件到网盘\n\n### 示例 15: 转存分享链接（提取码在链接中）\n\n```\n用户: 帮我把这个链接转存到网盘 https://pan.baidu.com/s/1xxxxx?pwd=abcd\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/\n```\n\n### 示例 16: 转存到指定目录\n\n```\n用户: 把 https://pan.baidu.com/s/1xxxxx 转存到 shared 目录，提取码是 efgh\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p efgh -d shared/]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/shared/\n```\n\n### 示例 17: 转存并查看结果（JSON）\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" --json\n# 输出:\n# {\n#   \"status\": \"success\",\n#   \"remote_path\": \"shared-file.pdf\",\n#   \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n#   \"file_count\": 1\n# }\n```\n\n---\n\n## 搜索文件\n\n### 示例 18: 搜索文件\n\n```\n用户: 在网盘里搜索 report\nAI: [执行 bdpan search report]\n\n    找到 3 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n    2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n    3   report-backup     目录    -         2026-02-20 10:30\n```\n\n### 示例 19: 按类型搜索\n\n```\n用户: 搜索网盘里所有的图片文件\nAI: [执行 bdpan search \"\" --category 3 --no-dir]\n\n    找到 5 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   photo.jpg         图片    3.2 MB    2026-03-15 14:30\n    2   screenshot.png    图片    1.1 MB    2026-03-10 09:20\n    ...\n```\n\n---\n\n## 文件管理（移动/复制/重命名/创建文件夹）\n\n### 示例 20: 移动文件\n\n```\n用户: 把网盘里的 report.pdf 移动到 backup 目录\nAI: [执行 bdpan mv report.pdf backup]\n\n    已移动 report.pdf -> backup\n```\n\n### 示例 21: 复制文件\n\n```\n用户: 复制 report.pdf 到 archive 目录\nAI: [执行 bdpan cp report.pdf archive]\n\n    已复制 report.pdf -> archive\n```\n\n### 示例 22: 重命名文件\n\n```\n用户: 把 draft.pdf 重命名为 final-report.pdf\nAI: [执行 bdpan rename draft.pdf final-report.pdf]\n\n    已重命名 draft.pdf -> final-report.pdf\n```\n\n### 示例 23: 创建文件夹\n\n```\n用户: 在网盘里创建一个 projects 文件夹\nAI: [执行 bdpan mkdir projects]\n\n    已创建文件夹: projects\n```\n\n### 示例 24: 组合操作——创建目录并移动文件\n\n```\n用户: 帮我在网盘里创建一个 archive/2026 目录，然后把 old-report.pdf 移动过去\nAI: [执行 bdpan mkdir archive/2026]\n    已创建文件夹: archive/2026\n\n    [执行 bdpan mv old-report.pdf archive/2026]\n    已移动 old-report.pdf -> archive/2026\n```\n\n---\n\n## 高级用法\n\n### 示例 12: 批量上传\n\n```bash\n# 上传当前目录所有 PDF 文件\nfor f in *.pdf; do\n  bdpan upload \"$f\" \"documents/$f\"\ndone\n\n# 上传并记录结果\nfor f in *.pdf; do\n  echo \"上传 $f...\"\n  bdpan upload \"$f\" \"documents/$f\" --json | jq '.'\ndone\n```\n\n### 示例 13: 自动备份脚本\n\n```bash\n#!/bin/bash\n# 每日备份脚本\n\nDATE=$(date +%Y-%m-%d)\nBACKUP_FILE=\"backup-${DATE}.tar.gz\"\n\n# 打包\ntar -czf \"/tmp/${BACKUP_FILE}\" ~/important-data/\n\n# 上传\nbdpan upload \"/tmp/${BACKUP_FILE}\" \"backup/${BACKUP_FILE}\"\n\n# 清理\nrm \"/tmp/${BACKUP_FILE}\"\n\necho \"备份完成: ${BACKUP_FILE}\"\n```\n\n### 示例 14: 检查上传状态\n\n```bash\n# 检查文件是否已上传\ncheck_uploaded() {\n  local file=$1\n  bdpan ls --json | jq -e \".[] | select(.Name == \\\"${file}\\\")\" > /dev/null\n}\n\nif check_uploaded \"report.pdf\"; then\n  echo \"文件已存在\"\nelse\n  echo \"文件不存在，开始上传...\"\n  bdpan upload ./report.pdf report.pdf\nfi\n```\n\nFile v1.4.3:reference/notes.md\n\n# 开发笔记与注意事项\n\n本文档包含 Skill 开发阶段的注意事项和内部说明，**不面向最终用户**。\n\n---\n\n## 安全须知\n\n> **1.** 请**备份**网盘重要数据。\n> **2.** AI Agent 行为不可预测，请**人工审核**每条指令。\n> **3.** 严禁在公用或不可信环境中扫码授权。使用完毕后执行 `bdpan logout` 清除授权。\n> **4.** 严格保护配置文件与 Token，切勿在公开仓库或对话中暴露。\n\n**首次使用时，向用户展示上述安全须知。**\n\n---\n\n## 内部实现说明\n\n### Agent 安全限制\n\n所有 Agent 安全约束（登录方式、Token 保护、更新控制、环境变量、路径安全）集中定义在 [SKILL.md](../SKILL.md) 的「安全约束」章节。此处不再重复，维护时以 SKILL.md 为准。\n\n### 授权码处理\n\n当用户在对话中发送一个 32 位十六进制字符串（正则：`^[a-fA-F0-9]{32}$`），处理规则详见 SKILL.md「授权码处理」章节。\n\nFile v1.4.3:reference/troubleshooting.md\n\n# 故障排除指南\n\n本指南涵盖了使用 bdpan CLI 时的常见问题和解决方案。\n\n---\n\n## 认证问题\n\n### Token 过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n### WebView 无法打开\n\n**症状：** 登录过程中浏览器或 WebView 窗口未出现。\n\n**解决方案：**\n工具会自动降级到 OOB（Out-of-Band）模式，按以下步骤操作：\n\n1. 复制控制台显示的授权链接：\n   ```\n   https://openapi.baidu.com/oauth/...?device_code=xxxxx\n   ```\n\n2. 在浏览器中打开该链接\n\n3. 完成授权后，浏览器会显示授权码\n\n4. 复制授权码并粘贴到命令行提示处\n\n5. 按回车确认\n\n**示例输出：**\n```\n请在浏览器中打开以下链接完成授权:\nhttps://openapi.baidu.com/oauth/2.0/authorize?response_type=device_code&client_id=...&device_code=xxxxx\n\n授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n[等待用户输入授权码...]\n```\n\n### 授权后登录失败\n\n**症状：** 授权页面完成但登录仍然失败。\n\n**解决方案：**\n```bash\n# 清除配置并重试\nrm ~/.config/bdpan/config.json\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n---\n\n## 文件操作问题\n\n### 路径不在允许范围\n\n**症状：**\n```\n错误: 路径不在允许范围内\nError: Path not in allowed range\n```\n\n**解决方案：**\n确保所有路径都在 `/apps/bdpan/` 目录下。\n\n错误：\n```bash\nbdpan ls /my-documents\nbdpan upload ./file.txt /other/file.txt\n```\n\n正确：\n```bash\nbdpan ls my-documents\nbdpan upload ./file.txt my-documents/file.txt\n```\n\n### 使用中文路径导致下载/上传失败\n\n**症状：**\n```\n错误: 文件不存在\n# 实际原因：使用了 \"/我的应用数据/bdpan/...\" 而不是 \"/apps/bdpan/...\"\n```\n\n**说明：**\n百度网盘界面中显示的 **\"我的应用数据\"** 是中文显示名，对应的 API 实际路径是 **`/apps`**。两个方向都需要映射：\n- **调用命令时**：中文路径 → API 路径（`我的应用数据` → `/apps`）\n- **展示给用户时**：API 路径 → 中文路径（`/apps` → `我的应用数据`）\n\n**路径映射：**\n| 用户可见名称 | API 实际路径 |\n|-------------|-------------|\n| 我的应用数据 | `/apps` |\n| 我的应用数据/bdpan | `/apps/bdpan` |\n\n**解决方案：**\n调用命令时使用相对路径或英文 API 绝对路径，展示给用户时转换为中文名：\n\n```bash\n# ✅ 命令中使用 API 路径\nbdpan download report.pdf ./report.pdf\n\n# ✅ 展示给用户时使用中文名\n# \"文件已上传到：我的应用数据/bdpan/report.pdf\"\n\n# ❌ 命令中使用中文路径\nbdpan download /我的应用数据/bdpan/report.pdf ./report.pdf\n\n# ❌ 展示给用户时暴露 API 路径\n# \"文件已上传到：/apps/bdpan/report.pdf\"\n```\n\n### 文件不存在\n\n**症状：**\n```\n错误: 文件不存在\nError: File not found\n```\n\n**解决方案：**\n1. 检查本地文件是否存在：\n   ```bash\n   ls -la <本地路径>\n   ```\n2. 检查远程文件是否存在：\n   ```bash\n   bdpan ls\n   ```\n\n### 上传/下载超时\n\n**症状：** 操作耗时过长并超时，或大文件下载中途中断。\n\n**原因：** Agent 的 Bash 工具有执行超时限制（默认 2 分钟，最大 10 分钟），大文件下载耗时超过此限制会导致进程被终止。\n\n**解决方案：**\n1. Agent 应遵循 SKILL.md 中的**大文件下载策略**：≤ 50MB 直接下载，> 50MB 使用 `nohup` 后台下载 + 轮询进度\n2. 如果后台下载仍然失败，建议用户在终端直接执行：\n   ```bash\n   bdpan download <远端路径> <本地路径>\n   ```\n3. 检查网络连接稳定性\n4. 对于非常大的文件，考虑先压缩/分割：\n   ```bash\n   # 上传前压缩\n   tar -czf archive.tar.gz large-folder/\n   bdpan upload archive.tar.gz backup/archive.tar.gz\n   ```\n\n### 转存失败\n\n**症状：**\n```\n错误: 转存失败\nError: Transfer failed\n```\n\n**常见原因及解决方案：**\n\n1. **分享链接已失效**：联系分享者重新生成链接\n2. **提取码错误**：确认提取码是否正确\n   ```bash\n   # 提取码通过 -p 传入\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n   # 或包含在链接中\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n   ```\n3. **网盘空间不足**：清理网盘空间后重试\n\n#### 错误码 errno=13045（自己的分享链接）\n\n**症状：**\n```\n转存失败: errno=13045, msg=prohibit transfer self share link\n```\n\n**原因：**\n这是您自己创建并分享的链接，文件已经在您的网盘中，无需再次转存。\n\n**处理方式：**\n- **不向用户展示错误**，直接告知文件已在网盘中\n- 使用 `bdpan ls` 查找并展示该文件\n- 如需要，可提供分享链接供他人使用\n\n示例回复：\n```\n✅ 文件已在您的网盘中！\n\n文件信息：\n- 文件名：example.pdf\n- 位置：我的应用数据/bdpan/example.pdf\n- 大小：1.2 MB\n\n无需转存，直接使用即可。\n```\n\n### 权限不足\n\n**症状：**\n```\n错误: 权限不足\nError: Permission denied\n```\n\n**解决方案：**\n1. 检查本地文件权限：\n   ```bash\n   ls -l <本地路径>\n   ```\n2. 确保您对目标目录有写入权限：\n   ```bash\n   ls -ld <目标目录>\n   ```\n\n---\n\n## 安装问题\n\n### 命令未找到\n\n**症状：** `bdpan: command not found`\n\n**解决方案：**\n```bash\n# 重新运行安装脚本\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n\n# 或者检查 ~/.local/bin 是否在 PATH 中\necho $PATH\n\n# 如果缺失则添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 下载了错误的架构\n\n**症状：** 二进制文件无法运行或提示 \"exec format error\"\n\n**解决方案：**\n```bash\n# 删除现有二进制文件\nrm ~/.local/bin/bdpan\n\n# 重新安装\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n```\n\n---\n\n## JSON 输出问题\n\n### 无效的 JSON 输出\n\n**症状：** `--json` 输出无法被解析。\n\n**解决方案：**\n1. 确保 stdout 中没有错误消息\n2. 检查输出中只有 JSON 内容\n3. 使用 `jq` 验证：\n   ```bash\n   bdpan ls --json | jq .\n   ```\n\n---\n\n## 平台特定问题\n\n### macOS\n\n#### Gatekeeper 阻止\n\n**症状：** 无法打开应用，因为它来自身份不明的开发者。\n\n**解决方案：**\n```bash\nxattr -d com.apple.quarantine ~/.local/bin/bdpan\n```\n\n### Linux\n\n#### 缺少依赖\n\n**症状：** 二进制文件运行失败，提示缺少库。\n\n**解决方案：**\n安装所需依赖（特定于发行版）：\n```bash\n# Debian/Ubuntu\nsudo apt-get install libc6\n\n# Fedora/RHEL\nsudo dnf install glibc\n```\n\n### Windows (WSL)\n\n#### 路径问题\n\n**症状：** Windows 路径无法正常工作。\n\n**解决方案：**\n在 WSL 中始终使用 Unix 风格路径：\n```bash\n# 正确\nbdpan upload ./file.txt file.txt\n\n# 错误\nbdpan upload .\\\\file.txt file.txt\n```\n\n---\n\n## 获取帮助\n\n### 检查版本\n\n```bash\nbdpan version\n```\n\n### 获取命令帮助\n\n```bash\nbdpan --help\nbdpan upload --help\nbdpan download --help\n```\n\n### 启用调试模式\n\n```bash\n# 检查配置文件是否存在及权限\nls -la ~/.config/bdpan/\n\n# 检查登录状态和 Token 有效期\nbdpan whoami\n```\n\n> **⛔ 安全警告：** 切勿使用 `cat` 查看配置文件内容，配置文件中包含 access_token 等敏感凭据，打印到终端或对话中可能导致泄露。\n\nFile v1.4.3:skill-card.md\n\n## Description:\n\nBaidu Drive enables agents to manage Baidu Netdisk files, including uploads, downloads, transfers, sharing, search, move, copy, rename, and folder creation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[may-yaha](https://clawhub.ai/user/may-yaha)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to let an agent operate files in a Baidu Drive app folder, including upload, download, transfer from share links, sharing, search, and file organization.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Install and update flows can run or replace code from Baidu-hosted remote endpoints with limited independent authenticity controls.\n\nMitigation: Review the skill before installing, use it only when the Baidu-hosted installer and update channel are trusted, and avoid automatic install or update modes in sensitive environments.\n\nRisk: A shell-backed agent can affect the Baidu Drive app folder, local download paths, and share-link creation.\n\nMitigation: Confirm upload, download, and share destinations before execution, and avoid exposing local token or configuration files.\n\nRisk: Uninstall behavior can delete the configured bdpan data directory when BDPAN_CONFIG_DIR is customized.\n\nMitigation: Verify the exact configured directory before running uninstall with a custom BDPAN_CONFIG_DIR value.\n\n## Reference(s):\n\n- [bdpan CLI Command Reference](reference/bdpan-commands.md)\n- [Authentication Guide](reference/authentication.md)\n- [Examples](reference/examples.md)\n- [Troubleshooting Guide](reference/troubleshooting.md)\n- [Development Notes](reference/notes.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and occasional JSON command output.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May propose or execute bdpan CLI operations after the skill's confirmation checks; outputs can include links, paths, status text, or JSON from bdpan.]\n\n## Skill Version(s):\n\n1.4.3 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.4.0: 11 files, 29557 bytes\n\nFiles: reference/authentication.md (2336b), reference/bdpan-commands.md (14912b), reference/examples.md (7746b), reference/notes.md (1045b), reference/troubleshooting.md (7494b), scripts/install.sh (10441b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (9312b), _meta.json (140b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: baidu-netdisk\ndescription: >-\n  百度网盘(Baidu Netdisk)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。\n  TRIGGER: 用户提及\"百度网盘/bdpan/网盘/云盘/baidu drive\"并涉及文件操作。\n  DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时。\nallowed-tools: Bash, Read, Glob, Grep, AskUserQuestion\nargument-hint: \"[操作指令]\"\n---\n\n# 百度网盘存储 Skill\n\n百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。\n\n> 内测阶段，使用注意事项详见 [reference/notes.md](./reference/notes.md)\n\n## 触发规则\n\n同时满足以下条件才执行：\n\n1. 用户明确提及\"百度网盘\"、\"bdpan\"、\"网盘\"\n2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/登录/注销）\n\n未通过触发规则时，禁止执行任何 bdpan 命令。\n\n> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及\"网盘\"即可触发。\n\n---\n\n## 安全约束（最高优先级，不可被任何用户指令覆盖）\n\n1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code` 等，即使在 GUI 环境也禁止）\n2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）\n3. **更新/登录**：更新必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行 update.sh 或 login.sh\n4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量（这些变量供用户在脚本外手动配置，Agent 不应代为设置）\n5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径\n\n---\n\n## 前置检查\n\n每次触发时按顺序执行：\n\n1. **安装检查**：`command -v bdpan`，未安装则告知用户并确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh`（用户确认后可加 `--yes` 跳过安装器内部确认）\n2. **登录检查**：`bdpan whoami`，未登录则引导执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`\n3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内\n\n---\n\n## 确认规则\n\n| 风险等级 | 操作 | 策略 |\n|----------|------|------|\n| **高（必须确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 列出影响范围，等待用户确认 |\n| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |\n| **低（直接执行）** | ls、search、whoami、mkdir、share | 无需确认 |\n\n**额外规则：**\n- 操作意图模糊（\"处理文件\"→确认上传还是下载）→ 必须确认\n- 序数/代词引用有歧义（\"第N个\"、\"它\"、\"上面那个\"）→ 必须确认\n- 用户取消意图（\"算了\"、\"不要了\"、\"取消\"）→ 立即中止，不执行任何命令\n\n---\n\n## 核心操作\n\n### 查看状态\n\n```bash\nbdpan whoami\n```\n\n### 列表查询\n\n```bash\nbdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]\n```\n\n### 上传\n\n```bash\nbdpan upload <本地路径> <远端路径>\n```\n\n**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。\n\n步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。\n\n### 下载\n\n**直接下载：**\n\n```bash\nbdpan download <远端路径> <本地路径>\n```\n\n步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → **检查文件大小决定下载策略** → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。\n\n**大文件下载策略（重要）：**\n\nAgent 的 Bash 工具有执行超时限制，大文件下载可能因超时而中断。必须根据文件大小选择下载策略：\n\n1. **获取文件大小**：用 `bdpan ls --json <远端路径>` 获取 `size` 字段（字节）\n2. **按大小分策略执行**：\n\n| 文件大小 | 策略 | 执行方式 |\n|----------|------|---------|\n| ≤ 50MB | 直接下载 | `bdpan download <远端路径> <本地路径>`，Bash timeout 设为 300000（5 分钟） |\n| > 50MB | 后台下载 | 使用 `nohup` 后台执行，Agent 轮询进度 |\n\n**小文件（≤ 50MB）直接下载：**\n\n正常执行 `bdpan download`，Bash 工具 timeout 参数设为 `300000`（5 分钟）。\n\n**大文件（> 50MB）后台下载流程：**\n\n```bash\n# 1. 启动后台下载（nohup + 进度日志）\nnohup bdpan download <远端路径> <本地路径> > /tmp/bdpan-dl-$$.log 2>&1 & echo $!\n```\n\n```bash\n# 2. 轮询检查进度（每 30 秒检查一次，使用 Bash run_in_background）\n#    检查进程是否存活 + 已下载文件大小\nkill -0 <PID> 2>/dev/null && echo \"running\" || echo \"done\"; ls -l <本地路径> 2>/dev/null; tail -5 /tmp/bdpan-dl-<PID>.log 2>/dev/null\n```\n\n```bash\n# 3. 下载完成后清理日志\nrm -f /tmp/bdpan-dl-<PID>.log\n```\n\nAgent 执行大文件后台下载时的行为规范：\n- 启动后台下载后，**立即告知用户**：下载已在后台启动，文件大小 X，预计需要 Y 时间\n- 每次轮询后向用户报告进度（已下载大小 / 总大小、百分比）\n- 下载完成后告知用户最终结果\n- 如果进程异常退出，检查日志并报告错误原因\n\n**分享链接下载（先转存再下载到本地）：**\n\n```bash\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd    # 提取码单独传入\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder  # 指定转存目录\n```\n\n> 分享链接下载同样适用大文件策略：转存完成后，用 `bdpan ls --json` 获取文件大小，再按上述策略执行下载。\n\n### 转存\n\n将分享文件转存到网盘，**不下载到本地**（与 download 分享链接模式的区别）。\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p <提取码> [-d 目标目录] [--json]\n```\n\n步骤：确认分享链接格式有效 → 确认有提取码（链接中含 `?pwd=` 或反问用户）→ 确认目标目录 → 执行。转存成功后只展示本次转存的文件（非整个目录），显示数量和目标目录。\n\n### 分享\n\n```bash\nbdpan share <路径> [路径...] [--json]\n```\n\n步骤：`bdpan ls` 确认文件存在 → 执行分享 → 展示链接+提取码+有效期。\n\n> 付费接口，需在百度网盘开放平台购买服务。\n\n### 搜索\n\n```bash\nbdpan search <关键词> [--category 0-7] [--no-dir|--dir-only] [--page-size N] [--page N] [--json]\n```\n\ncategory：0=全部 1=视频 2=音频 3=图片 4=文档 5=应用 6=其他 7=种子。`--no-dir` 和 `--dir-only` 互斥。\n\n### 移动 / 复制 / 重命名 / 创建文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\nbdpan cp <源路径> <目标目录>\nbdpan rename <路径> <新名称>       # 第二参数是文件名，非完整路径\nbdpan mkdir <路径>\n```\n\n---\n\n## 路径规则\n\n| 场景 | 格式 | 示例 |\n|------|------|------|\n| **命令参数** | 相对路径（相对于 `/apps/bdpan/`） | `bdpan upload ./f.txt docs/f.txt` |\n| **展示给用户** | 中文名 | \"已上传到：我的应用数据/bdpan/docs/f.txt\" |\n\n映射关系：`我的应用数据` ↔ `/apps`\n\n**禁止：** 命令中使用中文路径（`我的应用数据/...`）、展示时暴露 API 路径（`/apps/bdpan/...`）。\n\n---\n\n## 授权码处理\n\n用户发送 32 位十六进制字符串时，先确认：\"这是百度网盘授权码吗？确认后将执行登录流程。\" 确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`（不使用 `--yes`，保留安全确认环节）。\n\n---\n\n## 管理功能\n\n### 安装\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh [--yes]\n```\n\n安装器从百度 CDN（`issuecdn.baidupcs.com`）下载并执行。注意：install.sh 不执行本地 SHA256 校验，完整性依赖 HTTPS 传输保护。安全敏感场景建议先手动审查安装器内容或在沙箱中执行。\n\n### 登录 / 注销 / 卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh              # 登录（内置安全免责声明）\nbdpan logout                                            # 注销\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh [--yes]   # 卸载\n```\n\n### 更新（必须用户明确指令触发）\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh              # 检查并更新（需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check       # 仅检查更新\n```\n\n---\n\n## 参考文档\n\n遇到对应问题时按需查阅，无需预加载：\n\n| 文档 | 何时查阅 |\n|------|---------|\n| [bdpan-commands.md](./reference/bdpan-commands.md) | 需要完整命令参数、选项、JSON 输出格式 |\n| [authentication.md](./reference/authentication.md) | 认证流程细节、Token 管理 |\n| [examples.md](./reference/examples.md) | 更多使用示例（批量上传、自动备份等） |\n| [troubleshooting.md](./reference/troubleshooting.md) | 遇到错误需要排查 |\n\nFile v1.4.0:_meta.json\n\n{\n  \"ownerId\": \"kn732m45det8fggw8x5d7mv9jx80w2q0\",\n  \"slug\": \"baidu-netdisk-storage\",\n  \"version\": \"1.4.0\",\n  \"publishedAt\": 1775731160439\n}\n\nFile v1.4.0:reference/authentication.md\n\n# 认证指南\n\n本指南详细介绍 bdpan CLI 的登录认证流程。\n\n---\n\n## 登录方式\n\n> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。\n\n---\n\n## 验证登录状态\n\n```bash\nbdpan whoami\n```\n\n**已登录时输出：**\n```\n认证状态: 已登录\nToken 有效期至: 2026-03-10 10:30:00\n```\n\n**未登录时输出：**\n```\n认证状态: 未登录\n请执行 bdpan login 进行登录\n```\n\n---\n\n## 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n---\n\n## 常见问题\n\n### 登录后提示 Token 已过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n### 授权链接无效\n\n**症状：** 浏览器打开链接后提示链接无效\n\n**解决方案：**\n1. 重新执行登录脚本获取新的授权链接\n2. 确保在链接有效期内完成授权（通常 10 分钟）\n\n### 授权码输入后报错\n\n**症状：** 输入授权码后提示错误\n\n**解决方案：**\n1. 确保授权码复制完整，没有多余空格\n2. 检查浏览器中显示的授权码是否与输入的一致\n3. 如多次失败，重新执行登录脚本获取新授权码\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n---\n\n## 安全说明\n\n- **OAuth 2.0**：使用授权码模式，不存储用户密码\n- **Token 存储**：Token 加密存储在本地配置文件\n- **自动续期**：Token 快过期时工具会自动刷新\n\n---\n\n## 自动登录失败场景\n\n以下场景会自动切换到 OOB 模式：\n\n| 场景 | 说明 |\n|------|------|\n| SSH 远程登录 | 无图形界面 |\n| WSL 环境 | WebView 支持受限 |\n| 桌面环境锁定 | WebView 无法弹出 |\n| 浏览器未安装 | 无法打开 WebView |\n\n切换到 OOB 模式时，工具会自动提示授权链接，无需用户干预。\n\nFile v1.4.0:reference/bdpan-commands.md\n\n# bdpan CLI 命令快速参考\n\n## 认证命令\n\n### login - 登录授权\n\n> **⛔ Agent 必须通过登录脚本执行登录，禁止直接调用 `bdpan login`。详见 [SKILL.md](../SKILL.md) 安全约束。**\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本内置了安全免责声明和完整的 OOB 授权流程。无论 GUI 或非 GUI 环境，统一使用此脚本。\n\n### logout - 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n### uninstall - 完全卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh\n```\n\n完全卸载 bdpan CLI，自动执行以下操作：\n1. 注销登录并清除授权信息\n2. 删除配置目录（`~/.config/bdpan/`）\n3. 删除 bdpan 二进制文件（`~/.local/bin/bdpan`）\n\n**选项：**\n- `--yes, -y` - 跳过确认提示（自动化场景）\n\n**环境变量：**\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n### whoami - 查看认证状态\n\n```bash\nbdpan whoami\n```\n\n显示当前登录状态、用户名和 Token 有效期信息。\n\n**已登录时输出：**\n```\n认证状态: 已登录\n用户名: your_username\nToken 有效期至: 2026-04-04 10:30:00\n```\n\n**选项：**\n- `--json` - JSON 格式输出\n\n---\n\n## 文件操作命令\n\n### upload - 上传文件\n\n```bash\nbdpan upload <local> <remote>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `local` | 本地文件或文件夹路径 |\n| `remote` | 网盘目标路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 单文件上传\nbdpan upload ./report.pdf report.pdf\n\n# 文件夹上传\nbdpan upload ./project/ project/\n\n# 上传到子目录\nbdpan upload ./data.tar.gz backup/data.tar.gz\n```\n\n**选项：**\n- `--json` - JSON 格式输出上传结果\n\n### download - 下载文件\n\n```bash\nbdpan download <remote> <local> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `remote` | 网盘文件/文件夹路径（相对于 `/apps/bdpan/`）**或**百度网盘分享链接 |\n| `local` | 本地保存路径 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（用于分享链接，如果链接中未包含） |\n| `-t` | 自定义转存目录（相对路径自动拼接 `/apps/bdpan`，绝对路径直接使用） |\n| `--json` | JSON 格式输出下载结果 |\n\n**示例：**\n```bash\n# 单文件下载\nbdpan download report.pdf ./downloaded-report.pdf\n\n# 文件夹下载\nbdpan download project/ ./project-restore/\n\n# 从分享链接下载（链接中包含提取码）\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\n\n# 使用 -p 参数单独传入提取码\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd\n\n# 使用 -t 参数自定义转存目录\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder\n```\n\n**分享链接下载说明：**\n- 自动识别分享链接格式 `https://pan.baidu.com/s/1{surl}?pwd={pwd}`\n- 分享文件会先转存到 `/apps/bdpan/{日期}/` 目录（或使用 `-t` 指定的目录）\n- 然后下载到指定的本地路径\n\n### transfer - 转存分享文件到网盘（不下载到本地）\n\n```bash\nbdpan transfer <分享链接> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `分享链接` | 百度网盘分享链接 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（如果链接中未包含） |\n| `-d` | 目标目录（相对路径自动拼接 `/apps/bdpan`，默认为应用根目录） |\n| `--json` | JSON 格式输出转存结果 |\n\n**示例：**\n```bash\n# 基本用法 - 转存到应用根目录 /apps/bdpan/\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n\n# 提取码在链接中\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n\n# 指定目标目录\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd -d my-folder/\n\n# JSON 输出\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd --json\n```\n\n**与 download 的区别：**\n- `transfer` 仅将分享文件转存到自己的网盘，不下载到本地\n- `download` 会先转存再下载到本地路径\n- 适用于只需要保存到网盘、不需要本地副本的场景\n\n### ls - 查看文件列表\n\n```bash\nbdpan ls [path]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `path` | 要查看的目录路径 | 根目录 |\n\n**选项：**\n- `--json` - JSON 格式输出\n\n**示例：**\n```bash\n# 查看根目录\nbdpan ls\n\n# 查看子目录\nbdpan ls backup\n\n# JSON 输出\nbdpan ls --json\n```\n\n**输出格式：**\n```\n类型    大小          修改时间              文件名\n------  ------------  --------------------  --------\n目录     -            2026-02-20 10:30:00  documents\n文件    1.5 MB        2026-02-25 15:20:00  readme.txt\n文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n共 3 项\n```\n\n### share - 创建分享链接\n\n```bash\nbdpan share <path>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `path` | 要分享的文件或文件夹路径 |\n\n**示例：**\n```bash\n# 分享文件\nbdpan share report.pdf\n\n# 分享文件夹\nbdpan share project\n\n# JSON 输出\nbdpan share --json report.pdf\n```\n\n**输出格式：**\n```\n分享链接创建成功!\n链接: https://pan.baidu.com/s/1xxxxxxx\n提取码: abcd\n有效期: 7 天\n```\n\n### search - 搜索文件\n\n```bash\nbdpan search <关键词> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `关键词` | 搜索关键词（必填） |\n\n**选项：**\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--category` | int | `0` | 文件类型筛选：1=视频, 2=音频, 3=图片, 4=文档, 5=应用, 6=其他, 7=种子 |\n| `--page-size` | int | `5` | 每页数量（最大 50） |\n| `--page` | int | `1` | 页码 |\n| `--no-dir` | bool | `false` | 仅显示文件，排除文件夹 |\n| `--dir-only` | bool | `false` | 仅显示文件夹 |\n| `--json` | - | - | JSON 格式输出 |\n\n> `--no-dir` 和 `--dir-only` 互斥，不能同时使用。\n\n**示例：**\n```bash\n# 搜索文件\nbdpan search report\n\n# 搜索图片类型文件\nbdpan search photo --category 3\n\n# 搜索文件，排除文件夹，每页 10 条\nbdpan search data --no-dir --page-size 10\n\n# 翻页\nbdpan search report --page 2\n\n# JSON 输出\nbdpan search report --json\n```\n\n**输出格式：**\n```\n找到 15 个结果（第 1 页，共 3 页）\n\n#   名称              类型    大小      修改时间\n--- ----------------- ------- --------- ----------------\n1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n\n提示: 使用 --page 2 查看下一页\n```\n\n### mv - 移动文件或文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要移动的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 移动文件到子目录\nbdpan mv report.pdf backup\n\n# 移动文件夹\nbdpan mv old-project archive\n\n# JSON 输出\nbdpan mv report.pdf backup --json\n```\n\n**输出格式：**\n```\n已移动 report.pdf -> backup\n```\n\n### cp - 复制文件或文件夹\n\n```bash\nbdpan cp <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要复制的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 复制文件到子目录\nbdpan cp report.pdf backup\n\n# 复制文件夹\nbdpan cp project project-copy\n\n# JSON 输出\nbdpan cp report.pdf backup --json\n```\n\n**输出格式：**\n```\n已复制 report.pdf -> backup\n```\n\n### rename - 重命名文件或文件夹\n\n```bash\nbdpan rename <路径> <新名称>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要重命名的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `新名称` | 新文件名（仅名称，不含路径） |\n\n**示例：**\n```bash\n# 重命名文件\nbdpan rename old-name.pdf new-name.pdf\n\n# 重命名子目录中的文件\nbdpan rename docs/draft.md final.md\n\n# JSON 输出\nbdpan rename old-name.pdf new-name.pdf --json\n```\n\n**输出格式：**\n```\n已重命名 old-name.pdf -> new-name.pdf\n```\n\n### mkdir - 创建文件夹\n\n```bash\nbdpan mkdir <路径>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要创建的文件夹路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 创建文件夹\nbdpan mkdir backup\n\n# 创建多级目录\nbdpan mkdir backup/2026/03\n\n# JSON 输出\nbdpan mkdir backup --json\n```\n\n**输出格式：**\n```\n已创建文件夹: backup\n```\n\n---\n\n## 版本管理命令\n\n### update - 自动更新 Skill\n\n> **使用 `bash ${CLAUDE_SKILL_DIR}/scripts/update.sh` 更新 Skill 文件。CLI 更新由 `bdpan` 自身管理。**\n\n```bash\n# 检查并更新（交互式，需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh\n\n# 仅检查更新，不执行\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check\n\n# 跳过确认，自动更新（自动化场景）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --yes\n```\n\n**功能说明：**\n- 通过百度配置接口获取最新 Skill 版本信息\n- 对比本地 VERSION 文件判断是否需要更新\n- 下载 zip 包并解压覆盖，更新 VERSION 文件\n- 支持 SHA256 完整性校验（如配置中包含 checksum）\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `--check, -c` | 仅检查更新，不执行安装 |\n| `--yes, -y` | 跳过用户确认，自动执行更新 |\n| `--help` | 显示帮助信息 |\n\n### version - 查看版本信息\n\n```bash\n# 查看当前版本\nbdpan version\n\n# 检查是否有更新\nbdpan version --check\n```\n\n---\n\n## init - 查看安装信息（v3.4.0+）\n\n```bash\nbdpan init\n```\n\n显示安装路径、配置文件路径和 PATH 配置建议。\n\n**输出示例：**\n```\nbdpan 安装信息\n────────────────────────────\n安装路径: /home/user/.local/bin/bdpan\n配置路径: /home/user/.config/bdpan/config.json\n\nPATH 配置建议:\n  export PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n---\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config-path <path>` | 指定配置文件完整路径（适用于 AI Agent 集成） |\n| `--json` | JSON 格式输出 |\n| `--no-check-update` | 禁用版本更新检查 |\n| `--help` | 显示帮助 |\n| `--version` | 显示版本 |\n\n---\n\n## JSON 输出格式\n\n### ls 命令输出\n\n```json\n[\n  {\n    \"fs_id\": 524080722157776,\n    \"path\": \"我的应用数据/report.pdf\",\n    \"server_filename\": \"report.pdf\",\n    \"size\": 1536000,\n    \"isdir\": false,\n    \"md5\": \"a1b2c3d4e5f6...\",\n    \"server_mtime\": \"2026-02-25T15:20:00+08:00\",\n    \"server_ctime\": \"2026-02-25T14:00:00+08:00\"\n  },\n  {\n    \"fs_id\": 841873986109404,\n    \"path\": \"我的应用数据/documents\",\n    \"server_filename\": \"documents\",\n    \"size\": 0,\n    \"isdir\": true,\n    \"md5\": \"\",\n    \"server_mtime\": \"2026-02-20T10:30:00+08:00\",\n    \"server_ctime\": \"2026-02-20T09:00:00+08:00\"\n  }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fs_id` | number | 文件唯一 ID |\n| `path` | string | 文件路径（中文显示名，如 `我的应用数据/...`） |\n| `server_filename` | string | 文件名 |\n| `size` | number | 文件大小（字节），目录为 0 |\n| `isdir` | boolean | 是否为目录（`true`/`false`，注意是小写布尔值） |\n| `md5` | string | 文件 MD5 值，目录为空字符串 |\n| `server_mtime` | string | 服务端修改时间（ISO 8601 带时区） |\n| `server_ctime` | string | 服务端创建时间（ISO 8601 带时区） |\n\n> **注意：** `path` 字段返回中文显示名（`我的应用数据/...`），不是 API 路径（`/apps/bdpan/...`）。展示给用户时可直接使用此路径。\n\n### share 命令输出\n\n```json\n{\n  \"link\": \"https://pan.baidu.com/s/1xxxxxxx\",\n  \"short_url\": \"xxxxxxx\",\n  \"share_id\": 25747091668,\n  \"period\": 7,\n  \"pwd\": \"abcd\"\n}\n```\n\n### upload/download 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"local_path\": \"./report.pdf\",\n  \"remote_path\": \"report.pdf\"\n}\n```\n\n### transfer 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"remote_path\": \"my-folder/shared-file.pdf\",\n  \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n  \"file_count\": 1\n}\n```\n\n### search 命令输出\n\n```json\n{\n  \"total\": 15,\n  \"page\": 1,\n  \"page_size\": 5,\n  \"results\": [\n    {\n      \"fs_id\": 524080722157776,\n      \"path\": \"我的应用数据/bdpan/report.pdf\",\n      \"server_filename\": \"report.pdf\",\n      \"size\": 1536000,\n      \"isdir\": false,\n      \"category\": 4,\n      \"server_mtime\": \"2026-02-25T15:20:00+08:00\"\n    }\n  ]\n}\n```\n\n### mv/cp/rename/mkdir 命令输出\n\n```json\n{\n  \"status\": \"ok\"\n}\n```\n\n---\n\n## 路径规则\n\n- 所有路径相对于应用根目录 `/apps/bdpan/`\n- 支持相对路径: `backup/data.tar.gz`\n- 支持绝对路径: `/apps/bdpan/backup/data.tar.gz`\n- 路径穿越 `..` 会被自动阻止\n\n> **⛔ 双向路径映射规则：** 调用 bdpan 命令时，\"我的应用数据\" 必须转换为 `/apps`；向用户展示路径时，`/apps` 必须转换为 \"我的应用数据\"。详见 [路径规则](../SKILL.md) 章节。\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_PATH` | 配置文件完整路径（优先级最高） | 无 |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n\n**配置路径优先级（v3.4.0+）：**\n1. `--config-path` 命令行参数（最高优先级）\n2. `BDPAN_CONFIG_PATH` 环境变量\n3. `BDPAN_CONFIG_DIR` 环境变量 + `config.json`\n4. `~/.config/bdpan/config.json`（默认路径）\n\n**使用示例：**\n```bash\n# 使用命令行参数指定配置\nbdpan --config-path /custom/path/config.json ls\n\n# 使用环境变量指定配置\nexport BDPAN_CONFIG_PATH=/custom/path/config.json\nbdpan ls\n```\n\n### AI Agent 集成\n\n当 AI Agent 无法通过默认路径读取配置时，可以通过以下方式指定：\n\n```python\nimport subprocess\nimport os\n\nenv = os.environ.copy()\nenv[\"BDPAN_CONFIG_PATH\"] = \"/home/user/.config/bdpan/config.json\"\n\nresult = subprocess.run(\n    [\"bdpan\", \"ls\", \"--json\"],\n    env=env,\n    capture_output=True,\n    text=True\n)\n```\n\n---\n\n## 常见错误码\n\n| 错误 | 说明 | 解决方案 |\n|------|------|---------|\n| Token expired | Token 过期 | 重新登录 |\n| Path not allowed | 路径不在允许范围 | 使用 /apps/bdpan/ 下的路径 |\n| File not found | 文件不存在 | 检查路径是否正确 |\n| errno=13045 | 自己的分享链接 | 文件已在网盘中，直接使用 `bdpan ls` 查找 |\n\n---\n\n## 平台支持\n\n| 功能 | macOS | Linux | Windows (WSL) |\n|------|-------|-------|---------------|\n| 基础功能 | ✅ | ✅ | ✅ |\n| WebView 登录 | ✅ | - | -（WSL 无图形界面，使用 OOB 模式） |\n\nFile v1.4.0:reference/examples.md\n\n# 使用示例\n\n本文档包含 baidu-netdisk 的详细使用示例。\n\n---\n\n## 上传并分享\n\n### 示例 1: 上传并分享单个文件\n\n```\n用户: 帮我上传并分享 ./report.pdf\nAI: [执行 bdpan upload ./report.pdf report.pdf]\n    [执行 bdpan share report.pdf]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: abcd\n    有效期: 7 天\n```\n\n### 示例 2: 上传并分享文件夹\n\n```\n用户: 把 ./project 文件夹上传并分享\nAI: [执行 bdpan upload ./project/ project/]\n    [执行 bdpan share project]\n\n    文件夹上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: efgh\n    有效期: 7 天\n```\n\n### 示例 3: 上传到子目录\n\n```\n用户: 上传 ./data.tar.gz 到 backup 目录并分享\nAI: [执行 bdpan upload ./data.tar.gz backup/data.tar.gz]\n    [执行 bdpan share backup/data.tar.gz]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: ijkl\n    有效期: 7 天\n```\n\n---\n\n## 下载文件\n\n### 示例 4: 下载单个文件\n\n```\n用户: 从网盘下载 report.pdf\nAI: [执行 bdpan download report.pdf ./report.pdf]\n\n    正在下载 report.pdf → ./report.pdf ...\n    ✓ 下载成功\n```\n\n### 示例 5: 下载文件夹\n\n```\n用户: 把 backup 文件夹下载到本地\nAI: [执行 bdpan download backup/ ./backup/]\n\n    正在下载 backup/ → ./backup/ ...\n    ✓ 下载成功\n```\n\n---\n\n## 文件列表\n\n### 示例 6: 查看已上传文件\n\n```\n用户: 查看我上传了哪些文件\nAI: [执行 bdpan ls]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    目录     -            2026-02-20 10:30:00  backup\n    文件    1.5 MB        2026-02-25 15:20:00  report.pdf\n    文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n    共 3 项\n```\n\n### 示例 7: 查看子目录\n\n```\n用户: 查看 backup 目录下的文件\nAI: [执行 bdpan ls backup]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    文件    2.1 GB        2026-02-19 08:00:00  data-2026-02-19.tar.gz\n    文件    1.8 GB        2026-02-18 08:00:00  data-2026-02-18.tar.gz\n\n    共 2 项\n```\n\n---\n\n## JSON 输出（用于脚本）\n\n### 示例 8: JSON 格式文件列表\n\n```\n用户: 列出所有文件名（JSON 格式）\nAI: [执行 bdpan ls --json]\n\n    输出:\n    [\n      {\n        \"Name\": \"report.pdf\",\n        \"IsDir\": false,\n        \"Size\": 1536000,\n        \"Modified\": \"2026-02-25T15:20:00Z\"\n      },\n      {\n        \"Name\": \"backup\",\n        \"IsDir\": true,\n        \"Size\": 0,\n        \"Modified\": \"2026-02-20T10:30:00Z\"\n      }\n    ]\n```\n\n### 示例 9: 使用 jq 处理输出\n\n```bash\n# 提取所有文件名\nbdpan ls --json | jq -r '.[].Name'\n\n# 只列出文件（排除目录）\nbdpan ls --json | jq '.[] | select(.IsDir == false)'\n\n# 按大小排序\nbdpan ls --json | jq 'sort_by(.Size) | reverse'\n\n# 检查文件是否存在\nbdpan ls --json | jq -e '.[] | select(.Name == \"target.txt\")'\n```\n\n---\n\n## 认证流程\n\n### 示例 10: 登录（统一使用 login.sh 脚本）\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n```\n用户: 帮我登录百度网盘\nAI: [执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh]\n\n    [展示安全免责声明]\n    已阅读上述安全须知，确认继续登录? [y/N]\n\n用户: y\nAI: 正在获取授权链接...\n\n    请在浏览器中打开以下链接完成授权:\n    https://openapi.baidu.com/oauth/2.0/authorize?...\n\n    授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n    [等待用户输入...]\n\n用户: [粘贴授权码] ca0ee3070f75d0246357e5c74d525bda\nAI: [处理授权码]\n\n    ✓ 登录成功！\n    用户: username@baidu.com\n```\n\n---\n\n## 转存分享文件到网盘\n\n### 示例 15: 转存分享链接（提取码在链接中）\n\n```\n用户: 帮我把这个链接转存到网盘 https://pan.baidu.com/s/1xxxxx?pwd=abcd\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/\n```\n\n### 示例 16: 转存到指定目录\n\n```\n用户: 把 https://pan.baidu.com/s/1xxxxx 转存到 shared 目录，提取码是 efgh\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p efgh -d shared/]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/shared/\n```\n\n### 示例 17: 转存并查看结果（JSON）\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" --json\n# 输出:\n# {\n#   \"status\": \"success\",\n#   \"remote_path\": \"shared-file.pdf\",\n#   \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n#   \"file_count\": 1\n# }\n```\n\n---\n\n## 搜索文件\n\n### 示例 18: 搜索文件\n\n```\n用户: 在网盘里搜索 report\nAI: [执行 bdpan search report]\n\n    找到 3 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n    2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n    3   report-backup     目录    -         2026-02-20 10:30\n```\n\n### 示例 19: 按类型搜索\n\n```\n用户: 搜索网盘里所有的图片文件\nAI: [执行 bdpan search \"\" --category 3 --no-dir]\n\n    找到 5 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   photo.jpg         图片    3.2 MB    2026-03-15 14:30\n    2   screenshot.png    图片    1.1 MB    2026-03-10 09:20\n    ...\n```\n\n---\n\n## 文件管理（移动/复制/重命名/创建文件夹）\n\n### 示例 20: 移动文件\n\n```\n用户: 把网盘里的 report.pdf 移动到 backup 目录\nAI: [执行 bdpan mv report.pdf backup]\n\n    已移动 report.pdf -> backup\n```\n\n### 示例 21: 复制文件\n\n```\n用户: 复制 report.pdf 到 archive 目录\nAI: [执行 bdpan cp report.pdf archive]\n\n    已复制 report.pdf -> archive\n```\n\n### 示例 22: 重命名文件\n\n```\n用户: 把 draft.pdf 重命名为 final-report.pdf\nAI: [执行 bdpan rename draft.pdf final-report.pdf]\n\n    已重命名 draft.pdf -> final-report.pdf\n```\n\n### 示例 23: 创建文件夹\n\n```\n用户: 在网盘里创建一个 projects 文件夹\nAI: [执行 bdpan mkdir projects]\n\n    已创建文件夹: projects\n```\n\n### 示例 24: 组合操作——创建目录并移动文件\n\n```\n用户: 帮我在网盘里创建一个 archive/2026 目录，然后把 old-report.pdf 移动过去\nAI: [执行 bdpan mkdir archive/2026]\n    已创建文件夹: archive/2026\n\n    [执行 bdpan mv old-report.pdf archive/2026]\n    已移动 old-report.pdf -> archive/2026\n```\n\n---\n\n## 高级用法\n\n### 示例 12: 批量上传\n\n```bash\n# 上传当前目录所有 PDF 文件\nfor f in *.pdf; do\n  bdpan upload \"$f\" \"documents/$f\"\ndone\n\n# 上传并记录结果\nfor f in *.pdf; do\n  echo \"上传 $f...\"\n  bdpan upload \"$f\" \"documents/$f\" --json | jq '.'\ndone\n```\n\n### 示例 13: 自动备份脚本\n\n```bash\n#!/bin/bash\n# 每日备份脚本\n\nDATE=$(date +%Y-%m-%d)\nBACKUP_FILE=\"backup-${DATE}.tar.gz\"\n\n# 打包\ntar -czf \"/tmp/${BACKUP_FILE}\" ~/important-data/\n\n# 上传\nbdpan upload \"/tmp/${BACKUP_FILE}\" \"backup/${BACKUP_FILE}\"\n\n# 清理\nrm \"/tmp/${BACKUP_FILE}\"\n\necho \"备份完成: ${BACKUP_FILE}\"\n```\n\n### 示例 14: 检查上传状态\n\n```bash\n# 检查文件是否已上传\ncheck_uploaded() {\n  local file=$1\n  bdpan ls --json | jq -e \".[] | select(.Name == \\\"${file}\\\")\" > /dev/null\n}\n\nif check_uploaded \"report.pdf\"; then\n  echo \"文件已存在\"\nelse\n  echo \"文件不存在，开始上传...\"\n  bdpan upload ./report.pdf report.pdf\nfi\n```\n\nFile v1.4.0:reference/notes.md\n\n# 开发笔记与注意事项\n\n本文档包含 Skill 开发阶段的注意事项和内部说明，**不面向最终用户**。\n\n---\n\n## BETA 阶段安全须知\n\n> **1.** 本工具处于公测期，仅供技术交流，请**备份**网盘重要数据。\n> **2.** AI Agent 行为不可预测，请**人工审核**每条指令。\n> **3.** 严禁在公用或不可信环境中扫码授权。使用完毕后执行 `bdpan logout` 清除授权。\n> **4.** 严格保护配置文件与 Token，切勿在公开仓库或对话中暴露。\n\n**首次使用时，向用户展示上述安全须知。**\n\n---\n\n## 内部实现说明\n\n### Agent 安全限制\n\n所有 Agent 安全约束（登录方式、Token 保护、更新控制、环境变量、路径安全）集中定义在 [SKILL.md](../SKILL.md) 的「安全约束」章节。此处不再重复，维护时以 SKILL.md 为准。\n\n### 授权码处理\n\n当用户在对话中发送一个 32 位十六进制字符串（正则：`^[a-fA-F0-9]{32}$`），处理规则详见 SKILL.md「授权码处理」章节。\n\nFile v1.4.0:reference/troubleshooting.md\n\n# 故障排除指南\n\n本指南涵盖了使用 bdpan CLI 时的常见问题和解决方案。\n\n---\n\n## 认证问题\n\n### Token 过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n### WebView 无法打开\n\n**症状：** 登录过程中浏览器或 WebView 窗口未出现。\n\n**解决方案：**\n工具会自动降级到 OOB（Out-of-Band）模式，按以下步骤操作：\n\n1. 复制控制台显示的授权链接：\n   ```\n   https://openapi.baidu.com/oauth/...?device_code=xxxxx\n   ```\n\n2. 在浏览器中打开该链接\n\n3. 完成授权后，浏览器会显示授权码\n\n4. 复制授权码并粘贴到命令行提示处\n\n5. 按回车确认\n\n**示例输出：**\n```\n请在浏览器中打开以下链接完成授权:\nhttps://openapi.baidu.com/oauth/2.0/authorize?response_type=device_code&client_id=...&device_code=xxxxx\n\n授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n[等待用户输入授权码...]\n```\n\n### 授权后登录失败\n\n**症状：** 授权页面完成但登录仍然失败。\n\n**解决方案：**\n```bash\n# 清除配置并重试\nrm ~/.config/bdpan/config.json\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n---\n\n## 文件操作问题\n\n### 路径不在允许范围\n\n**症状：**\n```\n错误: 路径不在允许范围内\nError: Path not in allowed range\n```\n\n**解决方案：**\n确保所有路径都在 `/apps/bdpan/` 目录下。\n\n错误：\n```bash\nbdpan ls /my-documents\nbdpan upload ./file.txt /other/file.txt\n```\n\n正确：\n```bash\nbdpan ls my-documents\nbdpan upload ./file.txt my-documents/file.txt\n```\n\n### 使用中文路径导致下载/上传失败\n\n**症状：**\n```\n错误: 文件不存在\n# 实际原因：使用了 \"/我的应用数据/bdpan/...\" 而不是 \"/apps/bdpan/...\"\n```\n\n**说明：**\n百度网盘界面中显示的 **\"我的应用数据\"** 是中文显示名，对应的 API 实际路径是 **`/apps`**。两个方向都需要映射：\n- **调用命令时**：中文路径 → API 路径（`我的应用数据` → `/apps`）\n- **展示给用户时**：API 路径 → 中文路径（`/apps` → `我的应用数据`）\n\n**路径映射：**\n| 用户可见名称 | API 实际路径 |\n|-------------|-------------|\n| 我的应用数据 | `/apps` |\n| 我的应用数据/bdpan | `/apps/bdpan` |\n\n**解决方案：**\n调用命令时使用相对路径或英文 API 绝对路径，展示给用户时转换为中文名：\n\n```bash\n# ✅ 命令中使用 API 路径\nbdpan download report.pdf ./report.pdf\n\n# ✅ 展示给用户时使用中文名\n# \"文件已上传到：我的应用数据/bdpan/report.pdf\"\n\n# ❌ 命令中使用中文路径\nbdpan download /我的应用数据/bdpan/report.pdf ./report.pdf\n\n# ❌ 展示给用户时暴露 API 路径\n# \"文件已上传到：/apps/bdpan/report.pdf\"\n```\n\n### 文件不存在\n\n**症状：**\n```\n错误: 文件不存在\nError: File not found\n```\n\n**解决方案：**\n1. 检查本地文件是否存在：\n   ```bash\n   ls -la <本地路径>\n   ```\n2. 检查远程文件是否存在：\n   ```bash\n   bdpan ls\n   ```\n\n### 上传/下载超时\n\n**症状：** 操作耗时过长并超时，或大文件下载中途中断。\n\n**原因：** Agent 的 Bash 工具有执行超时限制（默认 2 分钟，最大 10 分钟），大文件下载耗时超过此限制会导致进程被终止。\n\n**解决方案：**\n1. Agent 应遵循 SKILL.md 中的**大文件下载策略**：≤ 50MB 直接下载，> 50MB 使用 `nohup` 后台下载 + 轮询进度\n2. 如果后台下载仍然失败，建议用户在终端直接执行：\n   ```bash\n   bdpan download <远端路径> <本地路径>\n   ```\n3. 检查网络连接稳定性\n4. 对于非常大的文件，考虑先压缩/分割：\n   ```bash\n   # 上传前压缩\n   tar -czf archive.tar.gz large-folder/\n   bdpan upload archive.tar.gz backup/archive.tar.gz\n   ```\n\n### 转存失败\n\n**症状：**\n```\n错误: 转存失败\nError: Transfer failed\n```\n\n**常见原因及解决方案：**\n\n1. **分享链接已失效**：联系分享者重新生成链接\n2. **提取码错误**：确认提取码是否正确\n   ```bash\n   # 提取码通过 -p 传入\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n   # 或包含在链接中\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n   ```\n3. **网盘空间不足**：清理网盘空间后重试\n\n#### 错误码 errno=13045（自己的分享链接）\n\n**症状：**\n```\n转存失败: errno=13045, msg=prohibit transfer self share link\n```\n\n**原因：**\n这是您自己创建并分享的链接，文件已经在您的网盘中，无需再次转存。\n\n**处理方式：**\n- **不向用户展示错误**，直接告知文件已在网盘中\n- 使用 `bdpan ls` 查找并展示该文件\n- 如需要，可提供分享链接供他人使用\n\n示例回复：\n```\n✅ 文件已在您的网盘中！\n\n文件信息：\n- 文件名：example.pdf\n- 位置：我的应用数据/bdpan/example.pdf\n- 大小：1.2 MB\n\n无需转存，直接使用即可。\n```\n\n### 权限不足\n\n**症状：**\n```\n错误: 权限不足\nError: Permission denied\n```\n\n**解决方案：**\n1. 检查本地文件权限：\n   ```bash\n   ls -l <本地路径>\n   ```\n2. 确保您对目标目录有写入权限：\n   ```bash\n   ls -ld <目标目录>\n   ```\n\n---\n\n## 安装问题\n\n### 命令未找到\n\n**症状：** `bdpan: command not found`\n\n**解决方案：**\n```bash\n# 重新运行安装脚本\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n\n# 或者检查 ~/.local/bin 是否在 PATH 中\necho $PATH\n\n# 如果缺失则添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 下载了错误的架构\n\n**症状：** 二进制文件无法运行或提示 \"exec format error\"\n\n**解决方案：**\n```bash\n# 删除现有二进制文件\nrm ~/.local/bin/bdpan\n\n# 重新安装\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n```\n\n---\n\n## JSON 输出问题\n\n### 无效的 JSON 输出\n\n**症状：** `--json` 输出无法被解析。\n\n**解决方案：**\n1. 确保 stdout 中没有错误消息\n2. 检查输出中只有 JSON 内容\n3. 使用 `jq` 验证：\n   ```bash\n   bdpan ls --json | jq .\n   ```\n\n---\n\n## 平台特定问题\n\n### macOS\n\n#### Gatekeeper 阻止\n\n**症状：** 无法打开应用，因为它来自身份不明的开发者。\n\n**解决方案：**\n```bash\nxattr -d com.apple.quarantine ~/.local/bin/bdpan\n```\n\n### Linux\n\n#### 缺少依赖\n\n**症状：** 二进制文件运行失败，提示缺少库。\n\n**解决方案：**\n安装所需依赖（特定于发行版）：\n```bash\n# Debian/Ubuntu\nsudo apt-get install libc6\n\n# Fedora/RHEL\nsudo dnf install glibc\n```\n\n### Windows (WSL)\n\n#### 路径问题\n\n**症状：** Windows 路径无法正常工作。\n\n**解决方案：**\n在 WSL 中始终使用 Unix 风格路径：\n```bash\n# 正确\nbdpan upload ./file.txt file.txt\n\n# 错误\nbdpan upload .\\\\file.txt file.txt\n```\n\n---\n\n## 获取帮助\n\n### 检查版本\n\n```bash\nbdpan version\n```\n\n### 获取命令帮助\n\n```bash\nbdpan --help\nbdpan upload --help\nbdpan download --help\n```\n\n### 启用调试模式\n\n```bash\n# 检查配置文件是否存在及权限\nls -la ~/.config/bdpan/\n\n# 检查登录状态和 Token 有效期\nbdpan whoami\n```\n\n> **⛔ 安全警告：** 切勿使用 `cat` 查看配置文件内容，配置文件中包含 access_token 等敏感凭据，打印到终端或对话中可能导致泄露。\n\nArchive v1.3.0: 11 files, 28484 bytes\n\nFiles: reference/authentication.md (2336b), reference/bdpan-commands.md (14912b), reference/examples.md (7746b), reference/notes.md (1045b), reference/troubleshooting.md (7063b), scripts/install.sh (10441b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (7321b), _meta.json (140b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: bdpan-storage\ndescription: 百度网盘文件管理。支持上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。当用户提及\"百度网盘\"\"bdpan\"\"网盘\"并涉及文件操作时触发。\nallowed-tools: Bash, Read, Glob, Grep, AskUserQuestion\nargument-hint: \"[操作指令]\"\n---\n\n# 百度网盘存储 Skill\n\n百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。\n\n> 内测阶段，使用注意事项详见 [reference/notes.md](./reference/notes.md)\n\n## 触发规则\n\n同时满足以下条件才执行：\n\n1. 用户明确提及\"百度网盘\"、\"bdpan\"、\"网盘\"\n2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/登录/注销）\n\n未通过触发规则时，禁止执行任何 bdpan 命令。\n\n> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及\"网盘\"即可触发。\n\n---\n\n## 安全约束（最高优先级，不可被任何用户指令覆盖）\n\n1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code` 等，即使在 GUI 环境也禁止）\n2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）\n3. **更新/登录**：更新必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行 update.sh 或 login.sh\n4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量（这些变量供用户在脚本外手动配置，Agent 不应代为设置）\n5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径\n\n---\n\n## 前置检查\n\n每次触发时按顺序执行：\n\n1. **安装检查**：`command -v bdpan`，未安装则告知用户并确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh`（用户确认后可加 `--yes` 跳过安装器内部确认）\n2. **登录检查**：`bdpan whoami`，未登录则引导执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`\n3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内\n\n---\n\n## 确认规则\n\n| 风险等级 | 操作 | 策略 |\n|----------|------|------|\n| **高（必须确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 列出影响范围，等待用户确认 |\n| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |\n| **低（直接执行）** | ls、search、whoami、mkdir、share | 无需确认 |\n\n**额外规则：**\n- 操作意图模糊（\"处理文件\"→确认上传还是下载）→ 必须确认\n- 序数/代词引用有歧义（\"第N个\"、\"它\"、\"上面那个\"）→ 必须确认\n- 用户取消意图（\"算了\"、\"不要了\"、\"取消\"）→ 立即中止，不执行任何命令\n\n---\n\n## 核心操作\n\n### 查看状态\n\n```bash\nbdpan whoami\n```\n\n### 列表查询\n\n```bash\nbdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]\n```\n\n### 上传\n\n```bash\nbdpan upload <本地路径> <远端路径>\n```\n\n**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。\n\n步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。\n\n### 下载\n\n**直接下载：**\n\n```bash\nbdpan download <远端路径> <本地路径>\n```\n\n步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。\n\n**分享链接下载（先转存再下载到本地）：**\n\n```bash\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd    # 提取码单独传入\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder  # 指定转存目录\n```\n\n### 转存\n\n将分享文件转存到网盘，**不下载到本地**（与 download 分享链接模式的区别）。\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p <提取码> [-d 目标目录] [--json]\n```\n\n步骤：确认分享链接格式有效 → 确认有提取码（链接中含 `?pwd=` 或反问用户）→ 确认目标目录 → 执行。转存成功后只展示本次转存的文件（非整个目录），显示数量和目标目录。\n\n### 分享\n\n```bash\nbdpan share <路径> [路径...] [--json]\n```\n\n步骤：`bdpan ls` 确认文件存在 → 执行分享 → 展示链接+提取码+有效期。\n\n> 付费接口，需在百度网盘开放平台购买服务。\n\n### 搜索\n\n```bash\nbdpan search <关键词> [--category 0-7] [--no-dir|--dir-only] [--page-size N] [--page N] [--json]\n```\n\ncategory：0=全部 1=视频 2=音频 3=图片 4=文档 5=应用 6=其他 7=种子。`--no-dir` 和 `--dir-only` 互斥。\n\n### 移动 / 复制 / 重命名 / 创建文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\nbdpan cp <源路径> <目标目录>\nbdpan rename <路径> <新名称>       # 第二参数是文件名，非完整路径\nbdpan mkdir <路径>\n```\n\n---\n\n## 路径规则\n\n| 场景 | 格式 | 示例 |\n|------|------|------|\n| **命令参数** | 相对路径（相对于 `/apps/bdpan/`） | `bdpan upload ./f.txt docs/f.txt` |\n| **展示给用户** | 中文名 | \"已上传到：我的应用数据/bdpan/docs/f.txt\" |\n\n映射关系：`我的应用数据` ↔ `/apps`\n\n**禁止：** 命令中使用中文路径（`我的应用数据/...`）、展示时暴露 API 路径（`/apps/bdpan/...`）。\n\n---\n\n## 授权码处理\n\n用户发送 32 位十六进制字符串时，先确认：\"这是百度网盘授权码吗？确认后将执行登录流程。\" 确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`（不使用 `--yes`，保留安全确认环节）。\n\n---\n\n## 管理功能\n\n### 安装\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh [--yes]\n```\n\n安装器从百度 CDN（`issuecdn.baidupcs.com`）下载，install.sh 内置 SHA256 校验确保完整性。安全敏感场景建议先手动审查安装器内容或在沙箱中执行。\n\n### 登录 / 注销 / 卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh              # 登录（内置安全免责声明）\nbdpan logout                                            # 注销\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh [--yes]   # 卸载\n```\n\n### 更新（必须用户明确指令触发）\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh              # 检查并更新（需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check       # 仅检查更新\n```\n\n---\n\n## 参考文档\n\n遇到对应问题时按需查阅，无需预加载：\n\n| 文档 | 何时查阅 |\n|------|---------|\n| [bdpan-commands.md](./reference/bdpan-commands.md) | 需要完整命令参数、选项、JSON 输出格式 |\n| [authentication.md](./reference/authentication.md) | 认证流程细节、Token 管理 |\n| [examples.md](./reference/examples.md) | 更多使用示例（批量上传、自动备份等） |\n| [troubleshooting.md](./reference/troubleshooting.md) | 遇到错误需要排查 |\n\nFile v1.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn732m45det8fggw8x5d7mv9jx80w2q0\",\n  \"slug\": \"baidu-netdisk-storage\",\n  \"version\": \"1.3.0\",\n  \"publishedAt\": 1774608408337\n}\n\nFile v1.3.0:reference/authentication.md\n\n# 认证指南\n\n本指南详细介绍 bdpan CLI 的登录认证流程。\n\n---\n\n## 登录方式\n\n> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。\n\n---\n\n## 验证登录状态\n\n```bash\nbdpan whoami\n```\n\n**已登录时输出：**\n```\n认证状态: 已登录\nToken 有效期至: 2026-03-10 10:30:00\n```\n\n**未登录时输出：**\n```\n认证状态: 未登录\n请执行 bdpan login 进行登录\n```\n\n---\n\n## 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n---\n\n## 常见问题\n\n### 登录后提示 Token 已过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n### 授权链接无效\n\n**症状：** 浏览器打开链接后提示链接无效\n\n**解决方案：**\n1. 重新执行登录脚本获取新的授权链接\n2. 确保在链接有效期内完成授权（通常 10 分钟）\n\n### 授权码输入后报错\n\n**症状：** 输入授权码后提示错误\n\n**解决方案：**\n1. 确保授权码复制完整，没有多余空格\n2. 检查浏览器中显示的授权码是否与输入的一致\n3. 如多次失败，重新执行登录脚本获取新授权码\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n---\n\n## 安全说明\n\n- **OAuth 2.0**：使用授权码模式，不存储用户密码\n- **Token 存储**：Token 加密存储在本地配置文件\n- **自动续期**：Token 快过期时工具会自动刷新\n\n---\n\n## 自动登录失败场景\n\n以下场景会自动切换到 OOB 模式：\n\n| 场景 | 说明 |\n|------|------|\n| SSH 远程登录 | 无图形界面 |\n| WSL 环境 | WebView 支持受限 |\n| 桌面环境锁定 | WebView 无法弹出 |\n| 浏览器未安装 | 无法打开 WebView |\n\n切换到 OOB 模式时，工具会自动提示授权链接，无需用户干预。\n\nFile v1.3.0:reference/bdpan-commands.md\n\n# bdpan CLI 命令快速参考\n\n## 认证命令\n\n### login - 登录授权\n\n> **⛔ Agent 必须通过登录脚本执行登录，禁止直接调用 `bdpan login`。详见 [SKILL.md](../SKILL.md) 安全约束。**\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本内置了安全免责声明和完整的 OOB 授权流程。无论 GUI 或非 GUI 环境，统一使用此脚本。\n\n### logout - 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n### uninstall - 完全卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh\n```\n\n完全卸载 bdpan CLI，自动执行以下操作：\n1. 注销登录并清除授权信息\n2. 删除配置目录（`~/.config/bdpan/`）\n3. 删除 bdpan 二进制文件（`~/.local/bin/bdpan`）\n\n**选项：**\n- `--yes, -y` - 跳过确认提示（自动化场景）\n\n**环境变量：**\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n### whoami - 查看认证状态\n\n```bash\nbdpan whoami\n```\n\n显示当前登录状态、用户名和 Token 有效期信息。\n\n**已登录时输出：**\n```\n认证状态: 已登录\n用户名: your_username\nToken 有效期至: 2026-04-04 10:30:00\n```\n\n**选项：**\n- `--json` - JSON 格式输出\n\n---\n\n## 文件操作命令\n\n### upload - 上传文件\n\n```bash\nbdpan upload <local> <remote>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `local` | 本地文件或文件夹路径 |\n| `remote` | 网盘目标路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 单文件上传\nbdpan upload ./report.pdf report.pdf\n\n# 文件夹上传\nbdpan upload ./project/ project/\n\n# 上传到子目录\nbdpan upload ./data.tar.gz backup/data.tar.gz\n```\n\n**选项：**\n- `--json` - JSON 格式输出上传结果\n\n### download - 下载文件\n\n```bash\nbdpan download <remote> <local> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `remote` | 网盘文件/文件夹路径（相对于 `/apps/bdpan/`）**或**百度网盘分享链接 |\n| `local` | 本地保存路径 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（用于分享链接，如果链接中未包含） |\n| `-t` | 自定义转存目录（相对路径自动拼接 `/apps/bdpan`，绝对路径直接使用） |\n| `--json` | JSON 格式输出下载结果 |\n\n**示例：**\n```bash\n# 单文件下载\nbdpan download report.pdf ./downloaded-report.pdf\n\n# 文件夹下载\nbdpan download project/ ./project-restore/\n\n# 从分享链接下载（链接中包含提取码）\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\n\n# 使用 -p 参数单独传入提取码\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd\n\n# 使用 -t 参数自定义转存目录\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder\n```\n\n**分享链接下载说明：**\n- 自动识别分享链接格式 `https://pan.baidu.com/s/1{surl}?pwd={pwd}`\n- 分享文件会先转存到 `/apps/bdpan/{日期}/` 目录（或使用 `-t` 指定的目录）\n- 然后下载到指定的本地路径\n\n### transfer - 转存分享文件到网盘（不下载到本地）\n\n```bash\nbdpan transfer <分享链接> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `分享链接` | 百度网盘分享链接 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（如果链接中未包含） |\n| `-d` | 目标目录（相对路径自动拼接 `/apps/bdpan`，默认为应用根目录） |\n| `--json` | JSON 格式输出转存结果 |\n\n**示例：**\n```bash\n# 基本用法 - 转存到应用根目录 /apps/bdpan/\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n\n# 提取码在链接中\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n\n# 指定目标目录\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd -d my-folder/\n\n# JSON 输出\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd --json\n```\n\n**与 download 的区别：**\n- `transfer` 仅将分享文件转存到自己的网盘，不下载到本地\n- `download` 会先转存再下载到本地路径\n- 适用于只需要保存到网盘、不需要本地副本的场景\n\n### ls - 查看文件列表\n\n```bash\nbdpan ls [path]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `path` | 要查看的目录路径 | 根目录 |\n\n**选项：**\n- `--json` - JSON 格式输出\n\n**示例：**\n```bash\n# 查看根目录\nbdpan ls\n\n# 查看子目录\nbdpan ls backup\n\n# JSON 输出\nbdpan ls --json\n```\n\n**输出格式：**\n```\n类型    大小          修改时间              文件名\n------  ------------  --------------------  --------\n目录     -            2026-02-20 10:30:00  documents\n文件    1.5 MB        2026-02-25 15:20:00  readme.txt\n文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n共 3 项\n```\n\n### share - 创建分享链接\n\n```bash\nbdpan share <path>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `path` | 要分享的文件或文件夹路径 |\n\n**示例：**\n```bash\n# 分享文件\nbdpan share report.pdf\n\n# 分享文件夹\nbdpan share project\n\n# JSON 输出\nbdpan share --json report.pdf\n```\n\n**输出格式：**\n```\n分享链接创建成功!\n链接: https://pan.baidu.com/s/1xxxxxxx\n提取码: abcd\n有效期: 7 天\n```\n\n### search - 搜索文件\n\n```bash\nbdpan search <关键词> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `关键词` | 搜索关键词（必填） |\n\n**选项：**\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--category` | int | `0` | 文件类型筛选：1=视频, 2=音频, 3=图片, 4=文档, 5=应用, 6=其他, 7=种子 |\n| `--page-size` | int | `5` | 每页数量（最大 50） |\n| `--page` | int | `1` | 页码 |\n| `--no-dir` | bool | `false` | 仅显示文件，排除文件夹 |\n| `--dir-only` | bool | `false` | 仅显示文件夹 |\n| `--json` | - | - | JSON 格式输出 |\n\n> `--no-dir` 和 `--dir-only` 互斥，不能同时使用。\n\n**示例：**\n```bash\n# 搜索文件\nbdpan search report\n\n# 搜索图片类型文件\nbdpan search photo --category 3\n\n# 搜索文件，排除文件夹，每页 10 条\nbdpan search data --no-dir --page-size 10\n\n# 翻页\nbdpan search report --page 2\n\n# JSON 输出\nbdpan search report --json\n```\n\n**输出格式：**\n```\n找到 15 个结果（第 1 页，共 3 页）\n\n#   名称              类型    大小      修改时间\n--- ----------------- ------- --------- ----------------\n1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n\n提示: 使用 --page 2 查看下一页\n```\n\n### mv - 移动文件或文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要移动的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 移动文件到子目录\nbdpan mv report.pdf backup\n\n# 移动文件夹\nbdpan mv old-project archive\n\n# JSON 输出\nbdpan mv report.pdf backup --json\n```\n\n**输出格式：**\n```\n已移动 report.pdf -> backup\n```\n\n### cp - 复制文件或文件夹\n\n```bash\nbdpan cp <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要复制的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 复制文件到子目录\nbdpan cp report.pdf backup\n\n# 复制文件夹\nbdpan cp project project-copy\n\n# JSON 输出\nbdpan cp report.pdf backup --json\n```\n\n**输出格式：**\n```\n已复制 report.pdf -> backup\n```\n\n### rename - 重命名文件或文件夹\n\n```bash\nbdpan rename <路径> <新名称>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要重命名的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `新名称` | 新文件名（仅名称，不含路径） |\n\n**示例：**\n```bash\n# 重命名文件\nbdpan rename old-name.pdf new-name.pdf\n\n# 重命名子目录中的文件\nbdpan rename docs/draft.md final.md\n\n# JSON 输出\nbdpan rename old-name.pdf new-name.pdf --json\n```\n\n**输出格式：**\n```\n已重命名 old-name.pdf -> new-name.pdf\n```\n\n### mkdir - 创建文件夹\n\n```bash\nbdpan mkdir <路径>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要创建的文件夹路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 创建文件夹\nbdpan mkdir backup\n\n# 创建多级目录\nbdpan mkdir backup/2026/03\n\n# JSON 输出\nbdpan mkdir backup --json\n```\n\n**输出格式：**\n```\n已创建文件夹: backup\n```\n\n---\n\n## 版本管理命令\n\n### update - 自动更新 Skill\n\n> **使用 `bash ${CLAUDE_SKILL_DIR}/scripts/update.sh` 更新 Skill 文件。CLI 更新由 `bdpan` 自身管理。**\n\n```bash\n# 检查并更新（交互式，需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh\n\n# 仅检查更新，不执行\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check\n\n# 跳过确认，自动更新（自动化场景）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --yes\n```\n\n**功能说明：**\n- 通过百度配置接口获取最新 Skill 版本信息\n- 对比本地 VERSION 文件判断是否需要更新\n- 下载 zip 包并解压覆盖，更新 VERSION 文件\n- 支持 SHA256 完整性校验（如配置中包含 checksum）\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `--check, -c` | 仅检查更新，不执行安装 |\n| `--yes, -y` | 跳过用户确认，自动执行更新 |\n| `--help` | 显示帮助信息 |\n\n### version - 查看版本信息\n\n```bash\n# 查看当前版本\nbdpan version\n\n# 检查是否有更新\nbdpan version --check\n```\n\n---\n\n## init - 查看安装信息（v3.4.0+）\n\n```bash\nbdpan init\n```\n\n显示安装路径、配置文件路径和 PATH 配置建议。\n\n**输出示例：**\n```\nbdpan 安装信息\n────────────────────────────\n安装路径: /home/user/.local/bin/bdpan\n配置路径: /home/user/.config/bdpan/config.json\n\nPATH 配置建议:\n  export PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n---\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config-path <path>` | 指定配置文件完整路径（适用于 AI Agent 集成） |\n| `--json` | JSON 格式输出 |\n| `--no-check-update` | 禁用版本更新检查 |\n| `--help` | 显示帮助 |\n| `--version` | 显示版本 |\n\n---\n\n## JSON 输出格式\n\n### ls 命令输出\n\n```json\n[\n  {\n    \"fs_id\": 524080722157776,\n    \"path\": \"我的应用数据/report.pdf\",\n    \"server_filename\": \"report.pdf\",\n    \"size\": 1536000,\n    \"isdir\": false,\n    \"md5\": \"a1b2c3d4e5f6...\",\n    \"server_mtime\": \"2026-02-25T15:20:00+08:00\",\n    \"server_ctime\": \"2026-02-25T14:00:00+08:00\"\n  },\n  {\n    \"fs_id\": 841873986109404,\n    \"path\": \"我的应用数据/documents\",\n    \"server_filename\": \"documents\",\n    \"size\": 0,\n    \"isdir\": true,\n    \"md5\": \"\",\n    \"server_mtime\": \"2026-02-20T10:30:00+08:00\",\n    \"server_ctime\": \"2026-02-20T09:00:00+08:00\"\n  }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fs_id` | number | 文件唯一 ID |\n| `path` | string | 文件路径（中文显示名，如 `我的应用数据/...`） |\n| `server_filename` | string | 文件名 |\n| `size` | number | 文件大小（字节），目录为 0 |\n| `isdir` | boolean | 是否为目录（`true`/`false`，注意是小写布尔值） |\n| `md5` | string | 文件 MD5 值，目录为空字符串 |\n| `server_mtime` | string | 服务端修改时间（ISO 8601 带时区） |\n| `server_ctime` | string | 服务端创建时间（ISO 8601 带时区） |\n\n> **注意：** `path` 字段返回中文显示名（`我的应用数据/...`），不是 API 路径（`/apps/bdpan/...`）。展示给用户时可直接使用此路径。\n\n### share 命令输出\n\n```json\n{\n  \"link\": \"https://pan.baidu.com/s/1xxxxxxx\",\n  \"short_url\": \"xxxxxxx\",\n  \"share_id\": 25747091668,\n  \"period\": 7,\n  \"pwd\": \"abcd\"\n}\n```\n\n### upload/download 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"local_path\": \"./report.pdf\",\n  \"remote_path\": \"report.pdf\"\n}\n```\n\n### transfer 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"remote_path\": \"my-folder/shared-file.pdf\",\n  \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n  \"file_count\": 1\n}\n```\n\n### search 命令输出\n\n```json\n{\n  \"total\": 15,\n  \"page\": 1,\n  \"page_size\": 5,\n  \"results\": [\n    {\n      \"fs_id\": 524080722157776,\n      \"path\": \"我的应用数据/bdpan/report.pdf\",\n      \"server_filename\": \"report.pdf\",\n      \"size\": 1536000,\n      \"isdir\": false,\n      \"category\": 4,\n      \"server_mtime\": \"2026-02-25T15:20:00+08:00\"\n    }\n  ]\n}\n```\n\n### mv/cp/rename/mkdir 命令输出\n\n```json\n{\n  \"status\": \"ok\"\n}\n```\n\n---\n\n## 路径规则\n\n- 所有路径相对于应用根目录 `/apps/bdpan/`\n- 支持相对路径: `backup/data.tar.gz`\n- 支持绝对路径: `/apps/bdpan/backup/data.tar.gz`\n- 路径穿越 `..` 会被自动阻止\n\n> **⛔ 双向路径映射规则：** 调用 bdpan 命令时，\"我的应用数据\" 必须转换为 `/apps`；向用户展示路径时，`/apps` 必须转换为 \"我的应用数据\"。详见 [路径规则](../SKILL.md) 章节。\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_PATH` | 配置文件完整路径（优先级最高） | 无 |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n\n**配置路径优先级（v3.4.0+）：**\n1. `--config-path` 命令行参数（最高优先级）\n2. `BDPAN_CONFIG_PATH` 环境变量\n3. `BDPAN_CONFIG_DIR` 环境变量 + `config.json`\n4. `~/.config/bdpan/config.json`（默认路径）\n\n**使用示例：**\n```bash\n# 使用命令行参数指定配置\nbdpan --config-path /custom/path/config.json ls\n\n# 使用环境变量指定配置\nexport BDPAN_CONFIG_PATH=/custom/path/config.json\nbdpan ls\n```\n\n### AI Agent 集成\n\n当 AI Agent 无法通过默认路径读取配置时，可以通过以下方式指定：\n\n```python\nimport subprocess\nimport os\n\nenv = os.environ.copy()\nenv[\"BDPAN_CONFIG_PATH\"] = \"/home/user/.config/bdpan/config.json\"\n\nresult = subprocess.run(\n    [\"bdpan\", \"ls\", \"--json\"],\n    env=env,\n    capture_output=True,\n    text=True\n)\n```\n\n---\n\n## 常见错误码\n\n| 错误 | 说明 | 解决方案 |\n|------|------|---------|\n| Token expired | Token 过期 | 重新登录 |\n| Path not allowed | 路径不在允许范围 | 使用 /apps/bdpan/ 下的路径 |\n| File not found | 文件不存在 | 检查路径是否正确 |\n| errno=13045 | 自己的分享链接 | 文件已在网盘中，直接使用 `bdpan ls` 查找 |\n\n---\n\n## 平台支持\n\n| 功能 | macOS | Linux | Windows (WSL) |\n|------|-------|-------|---------------|\n| 基础功能 | ✅ | ✅ | ✅ |\n| WebView 登录 | ✅ | - | -（WSL 无图形界面，使用 OOB 模式） |\n\nFile v1.3.0:reference/examples.md\n\n# 使用示例\n\n本文档包含 bdpan-storage 的详细使用示例。\n\n---\n\n## 上传并分享\n\n### 示例 1: 上传并分享单个文件\n\n```\n用户: 帮我上传并分享 ./report.pdf\nAI: [执行 bdpan upload ./report.pdf report.pdf]\n    [执行 bdpan share report.pdf]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: abcd\n    有效期: 7 天\n```\n\n### 示例 2: 上传并分享文件夹\n\n```\n用户: 把 ./project 文件夹上传并分享\nAI: [执行 bdpan upload ./project/ project/]\n    [执行 bdpan share project]\n\n    文件夹上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: efgh\n    有效期: 7 天\n```\n\n### 示例 3: 上传到子目录\n\n```\n用户: 上传 ./data.tar.gz 到 backup 目录并分享\nAI: [执行 bdpan upload ./data.tar.gz backup/data.tar.gz]\n    [执行 bdpan share backup/data.tar.gz]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: ijkl\n    有效期: 7 天\n```\n\n---\n\n## 下载文件\n\n### 示例 4: 下载单个文件\n\n```\n用户: 从网盘下载 report.pdf\nAI: [执行 bdpan download report.pdf ./report.pdf]\n\n    正在下载 report.pdf → ./report.pdf ...\n    ✓ 下载成功\n```\n\n### 示例 5: 下载文件夹\n\n```\n用户: 把 backup 文件夹下载到本地\nAI: [执行 bdpan download backup/ ./backup/]\n\n    正在下载 backup/ → ./backup/ ...\n    ✓ 下载成功\n```\n\n---\n\n## 文件列表\n\n### 示例 6: 查看已上传文件\n\n```\n用户: 查看我上传了哪些文件\nAI: [执行 bdpan ls]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    目录     -            2026-02-20 10:30:00  backup\n    文件    1.5 MB        2026-02-25 15:20:00  report.pdf\n    文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n    共 3 项\n```\n\n### 示例 7: 查看子目录\n\n```\n用户: 查看 backup 目录下的文件\nAI: [执行 bdpan ls backup]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    文件    2.1 GB        2026-02-19 08:00:00  data-2026-02-19.tar.gz\n    文件    1.8 GB        2026-02-18 08:00:00  data-2026-02-18.tar.gz\n\n    共 2 项\n```\n\n---\n\n## JSON 输出（用于脚本）\n\n### 示例 8: JSON 格式文件列表\n\n```\n用户: 列出所有文件名（JSON 格式）\nAI: [执行 bdpan ls --json]\n\n    输出:\n    [\n      {\n        \"Name\": \"report.pdf\",\n        \"IsDir\": false,\n        \"Size\": 1536000,\n        \"Modified\": \"2026-02-25T15:20:00Z\"\n      },\n      {\n        \"Name\": \"backup\",\n        \"IsDir\": true,\n        \"Size\": 0,\n        \"Modified\": \"2026-02-20T10:30:00Z\"\n      }\n    ]\n```\n\n### 示例 9: 使用 jq 处理输出\n\n```bash\n# 提取所有文件名\nbdpan ls --json | jq -r '.[].Name'\n\n# 只列出文件（排除目录）\nbdpan ls --json | jq '.[] | select(.IsDir == false)'\n\n# 按大小排序\nbdpan ls --json | jq 'sort_by(.Size) | reverse'\n\n# 检查文件是否存在\nbdpan ls --json | jq -e '.[] | select(.Name == \"target.txt\")'\n```\n\n---\n\n## 认证流程\n\n### 示例 10: 登录（统一使用 login.sh 脚本）\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n```\n用户: 帮我登录百度网盘\nAI: [执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh]\n\n    [展示安全免责声明]\n    已阅读上述安全须知，确认继续登录? [y/N]\n\n用户: y\nAI: 正在获取授权链接...\n\n    请在浏览器中打开以下链接完成授权:\n    https://openapi.baidu.com/oauth/2.0/authorize?...\n\n    授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n    [等待用户输入...]\n\n用户: [粘贴授权码] ca0ee3070f75d0246357e5c74d525bda\nAI: [处理授权码]\n\n    ✓ 登录成功！\n    用户: username@baidu.com\n```\n\n---\n\n## 转存分享文件到网盘\n\n### 示例 15: 转存分享链接（提取码在链接中）\n\n```\n用户: 帮我把这个链接转存到网盘 https://pan.baidu.com/s/1xxxxx?pwd=abcd\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/\n```\n\n### 示例 16: 转存到指定目录\n\n```\n用户: 把 https://pan.baidu.com/s/1xxxxx 转存到 shared 目录，提取码是 efgh\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p efgh -d shared/]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/shared/\n```\n\n### 示例 17: 转存并查看结果（JSON）\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" --json\n# 输出:\n# {\n#   \"status\": \"success\",\n#   \"remote_path\": \"shared-file.pdf\",\n#   \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n#   \"file_count\": 1\n# }\n```\n\n---\n\n## 搜索文件\n\n### 示例 18: 搜索文件\n\n```\n用户: 在网盘里搜索 report\nAI: [执行 bdpan search report]\n\n    找到 3 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n    2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n    3   report-backup     目录    -         2026-02-20 10:30\n```\n\n### 示例 19: 按类型搜索\n\n```\n用户: 搜索网盘里所有的图片文件\nAI: [执行 bdpan search \"\" --category 3 --no-dir]\n\n    找到 5 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   photo.jpg         图片    3.2 MB    2026-03-15 14:30\n    2   screenshot.png    图片    1.1 MB    2026-03-10 09:20\n    ...\n```\n\n---\n\n## 文件管理（移动/复制/重命名/创建文件夹）\n\n### 示例 20: 移动文件\n\n```\n用户: 把网盘里的 report.pdf 移动到 backup 目录\nAI: [执行 bdpan mv report.pdf backup]\n\n    已移动 report.pdf -> backup\n```\n\n### 示例 21: 复制文件\n\n```\n用户: 复制 report.pdf 到 archive 目录\nAI: [执行 bdpan cp report.pdf archive]\n\n    已复制 report.pdf -> archive\n```\n\n### 示例 22: 重命名文件\n\n```\n用户: 把 draft.pdf 重命名为 final-report.pdf\nAI: [执行 bdpan rename draft.pdf final-report.pdf]\n\n    已重命名 draft.pdf -> final-report.pdf\n```\n\n### 示例 23: 创建文件夹\n\n```\n用户: 在网盘里创建一个 projects 文件夹\nAI: [执行 bdpan mkdir projects]\n\n    已创建文件夹: projects\n```\n\n### 示例 24: 组合操作——创建目录并移动文件\n\n```\n用户: 帮我在网盘里创建一个 archive/2026 目录，然后把 old-report.pdf 移动过去\nAI: [执行 bdpan mkdir archive/2026]\n    已创建文件夹: archive/2026\n\n    [执行 bdpan mv old-report.pdf archive/2026]\n    已移动 old-report.pdf -> archive/2026\n```\n\n---\n\n## 高级用法\n\n### 示例 12: 批量上传\n\n```bash\n# 上传当前目录所有 PDF 文件\nfor f in *.pdf; do\n  bdpan upload \"$f\" \"documents/$f\"\ndone\n\n# 上传并记录结果\nfor f in *.pdf; do\n  echo \"上传 $f...\"\n  bdpan upload \"$f\" \"documents/$f\" --json | jq '.'\ndone\n```\n\n### 示例 13: 自动备份脚本\n\n```bash\n#!/bin/bash\n# 每日备份脚本\n\nDATE=$(date +%Y-%m-%d)\nBACKUP_FILE=\"backup-${DATE}.tar.gz\"\n\n# 打包\ntar -czf \"/tmp/${BACKUP_FILE}\" ~/important-data/\n\n# 上传\nbdpan upload \"/tmp/${BACKUP_FILE}\" \"backup/${BACKUP_FILE}\"\n\n# 清理\nrm \"/tmp/${BACKUP_FILE}\"\n\necho \"备份完成: ${BACKUP_FILE}\"\n```\n\n### 示例 14: 检查上传状态\n\n```bash\n# 检查文件是否已上传\ncheck_uploaded() {\n  local file=$1\n  bdpan ls --json | jq -e \".[] | select(.Name == \\\"${file}\\\")\" > /dev/null\n}\n\nif check_uploaded \"report.pdf\"; then\n  echo \"文件已存在\"\nelse\n  echo \"文件不存在，开始上传...\"\n  bdpan upload ./report.pdf report.pdf\nfi\n```\n\nFile v1.3.0:reference/notes.md\n\n# 开发笔记与注意事项\n\n本文档包含 Skill 开发阶段的注意事项和内部说明，**不面向最终用户**。\n\n---\n\n## BETA 阶段安全须知\n\n> **1.** 本工具处于公测期，仅供技术交流，请**备份**网盘重要数据。\n> **2.** AI Agent 行为不可预测，请**人工审核**每条指令。\n> **3.** 严禁在公用或不可信环境中扫码授权。使用完毕后执行 `bdpan logout` 清除授权。\n> **4.** 严格保护配置文件与 Token，切勿在公开仓库或对话中暴露。\n\n**首次使用时，向用户展示上述安全须知。**\n\n---\n\n## 内部实现说明\n\n### Agent 安全限制\n\n所有 Agent 安全约束（登录方式、Token 保护、更新控制、环境变量、路径安全）集中定义在 [SKILL.md](../SKILL.md) 的「安全约束」章节。此处不再重复，维护时以 SKILL.md 为准。\n\n### 授权码处理\n\n当用户在对话中发送一个 32 位十六进制字符串（正则：`^[a-fA-F0-9]{32}$`），处理规则详见 SKILL.md「授权码处理」章节。\n\nFile v1.3.0:reference/troubleshooting.md\n\n# 故障排除指南\n\n本指南涵盖了使用 bdpan CLI 时的常见问题和解决方案。\n\n---\n\n## 认证问题\n\n### Token 过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n### WebView 无法打开\n\n**症状：** 登录过程中浏览器或 WebView 窗口未出现。\n\n**解决方案：**\n工具会自动降级到 OOB（Out-of-Band）模式，按以下步骤操作：\n\n1. 复制控制台显示的授权链接：\n   ```\n   https://openapi.baidu.com/oauth/...?device_code=xxxxx\n   ```\n\n2. 在浏览器中打开该链接\n\n3. 完成授权后，浏览器会显示授权码\n\n4. 复制授权码并粘贴到命令行提示处\n\n5. 按回车确认\n\n**示例输出：**\n```\n请在浏览器中打开以下链接完成授权:\nhttps://openapi.baidu.com/oauth/2.0/authorize?response_type=device_code&client_id=...&device_code=xxxxx\n\n授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n[等待用户输入授权码...]\n```\n\n### 授权后登录失败\n\n**症状：** 授权页面完成但登录仍然失败。\n\n**解决方案：**\n```bash\n# 清除配置并重试\nrm ~/.config/bdpan/config.json\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n---\n\n## 文件操作问题\n\n### 路径不在允许范围\n\n**症状：**\n```\n错误: 路径不在允许范围内\nError: Path not in allowed range\n```\n\n**解决方案：**\n确保所有路径都在 `/apps/bdpan/` 目录下。\n\n错误：\n```bash\nbdpan ls /my-documents\nbdpan upload ./file.txt /other/file.txt\n```\n\n正确：\n```bash\nbdpan ls my-documents\nbdpan upload ./file.txt my-documents/file.txt\n```\n\n### 使用中文路径导致下载/上传失败\n\n**症状：**\n```\n错误: 文件不存在\n# 实际原因：使用了 \"/我的应用数据/bdpan/...\" 而不是 \"/apps/bdpan/...\"\n```\n\n**说明：**\n百度网盘界面中显示的 **\"我的应用数据\"** 是中文显示名，对应的 API 实际路径是 **`/apps`**。两个方向都需要映射：\n- **调用命令时**：中文路径 → API 路径（`我的应用数据` → `/apps`）\n- **展示给用户时**：API 路径 → 中文路径（`/apps` → `我的应用数据`）\n\n**路径映射：**\n| 用户可见名称 | API 实际路径 |\n|-------------|-------------|\n| 我的应用数据 | `/apps` |\n| 我的应用数据/bdpan | `/apps/bdpan` |\n\n**解决方案：**\n调用命令时使用相对路径或英文 API 绝对路径，展示给用户时转换为中文名：\n\n```bash\n# ✅ 命令中使用 API 路径\nbdpan download report.pdf ./report.pdf\n\n# ✅ 展示给用户时使用中文名\n# \"文件已上传到：我的应用数据/bdpan/report.pdf\"\n\n# ❌ 命令中使用中文路径\nbdpan download /我的应用数据/bdpan/report.pdf ./report.pdf\n\n# ❌ 展示给用户时暴露 API 路径\n# \"文件已上传到：/apps/bdpan/report.pdf\"\n```\n\n### 文件不存在\n\n**症状：**\n```\n错误: 文件不存在\nError: File not found\n```\n\n**解决方案：**\n1. 检查本地文件是否存在：\n   ```bash\n   ls -la <本地路径>\n   ```\n2. 检查远程文件是否存在：\n   ```bash\n   bdpan ls\n   ```\n\n### 上传/下载超时\n\n**症状：** 操作耗时过长并超时。\n\n**解决方案：**\n1. 大文件可能需要最多 30 分钟\n2. 检查网络连接稳定性\n3. 对于非常大的文件，考虑先压缩/分割：\n   ```bash\n   # 上传前压缩\n   tar -czf archive.tar.gz large-folder/\n   bdpan upload archive.tar.gz backup/archive.tar.gz\n   ```\n\n### 转存失败\n\n**症状：**\n```\n错误: 转存失败\nError: Transfer failed\n```\n\n**常见原因及解决方案：**\n\n1. **分享链接已失效**：联系分享者重新生成链接\n2. **提取码错误**：确认提取码是否正确\n   ```bash\n   # 提取码通过 -p 传入\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n   # 或包含在链接中\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n   ```\n3. **网盘空间不足**：清理网盘空间后重试\n\n#### 错误码 errno=13045（自己的分享链接）\n\n**症状：**\n```\n转存失败: errno=13045, msg=prohibit transfer self share link\n```\n\n**原因：**\n这是您自己创建并分享的链接，文件已经在您的网盘中，无需再次转存。\n\n**处理方式：**\n- **不向用户展示错误**，直接告知文件已在网盘中\n- 使用 `bdpan ls` 查找并展示该文件\n- 如需要，可提供分享链接供他人使用\n\n示例回复：\n```\n✅ 文件已在您的网盘中！\n\n文件信息：\n- 文件名：example.pdf\n- 位置：我的应用数据/bdpan/example.pdf\n- 大小：1.2 MB\n\n无需转存，直接使用即可。\n```\n\n### 权限不足\n\n**症状：**\n```\n错误: 权限不足\nError: Permission denied\n```\n\n**解决方案：**\n1. 检查本地文件权限：\n   ```bash\n   ls -l <本地路径>\n   ```\n2. 确保您对目标目录有写入权限：\n   ```bash\n   ls -ld <目标目录>\n   ```\n\n---\n\n## 安装问题\n\n### 命令未找到\n\n**症状：** `bdpan: command not found`\n\n**解决方案：**\n```bash\n# 重新运行安装脚本\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n\n# 或者检查 ~/.local/bin 是否在 PATH 中\necho $PATH\n\n# 如果缺失则添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 下载了错误的架构\n\n**症状：** 二进制文件无法运行或提示 \"exec format error\"\n\n**解决方案：**\n```bash\n# 删除现有二进制文件\nrm ~/.local/bin/bdpan\n\n# 重新安装\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n```\n\n---\n\n## JSON 输出问题\n\n### 无效的 JSON 输出\n\n**症状：** `--json` 输出无法被解析。\n\n**解决方案：**\n1. 确保 stdout 中没有错误消息\n2. 检查输出中只有 JSON 内容\n3. 使用 `jq` 验证：\n   ```bash\n   bdpan ls --json | jq .\n   ```\n\n---\n\n## 平台特定问题\n\n### macOS\n\n#### Gatekeeper 阻止\n\n**症状：** 无法打开应用，因为它来自身份不明的开发者。\n\n**解决方案：**\n```bash\nxattr -d com.apple.quarantine ~/.local/bin/bdpan\n```\n\n### Linux\n\n#### 缺少依赖\n\n**症状：** 二进制文件运行失败，提示缺少库。\n\n**解决方案：**\n安装所需依赖（特定于发行版）：\n```bash\n# Debian/Ubuntu\nsudo apt-get install libc6\n\n# Fedora/RHEL\nsudo dnf install glibc\n```\n\n### Windows (WSL)\n\n#### 路径问题\n\n**症状：** Windows 路径无法正常工作。\n\n**解决方案：**\n在 WSL 中始终使用 Unix 风格路径：\n```bash\n# 正确\nbdpan upload ./file.txt file.txt\n\n# 错误\nbdpan upload .\\\\file.txt file.txt\n```\n\n---\n\n## 获取帮助\n\n### 检查版本\n\n```bash\nbdpan version\n```\n\n### 获取命令帮助\n\n```bash\nbdpan --help\nbdpan upload --help\nbdpan download --help\n```\n\n### 启用调试模式\n\n```bash\n# 检查配置文件是否存在及权限\nls -la ~/.config/bdpan/\n\n# 检查登录状态和 Token 有效期\nbdpan whoami\n```\n\n> **⛔ 安全警告：** 切勿使用 `cat` 查看配置文件内容，配置文件中包含 access_token 等敏感凭据，打印到终端或对话中可能导致泄露。\n\nArchive v2.0.1: 11 files, 27890 bytes\n\nFiles: reference/authentication.md (2336b), reference/bdpan-commands.md (14912b), reference/examples.md (7746b), reference/notes.md (1045b), reference/troubleshooting.md (7063b), scripts/install.sh (8876b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (7370b), _meta.json (140b)\n\nFile v2.0.1:SKILL.md\n\n---\nname: bdpan-storage\ndescription: 百度网盘文件管理。支持上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。当用户提及\"百度网盘\"\"bdpan\"\"网盘\"并涉及文件操作时触发。\nallowed-tools: Bash, Read, Glob, Grep, AskUserQuestion\nargument-hint: \"[操作指令]\"\n---\n\n# 百度网盘存储 Skill\n\n百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。\n\n> 内测阶段，使用注意事项详见 [reference/notes.md](./reference/notes.md)\n\n## 触发规则\n\n同时满足以下条件才执行：\n\n1. 用户明确提及\"百度网盘\"、\"bdpan\"、\"网盘\"\n2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/登录/注销）\n\n未通过触发规则时，禁止执行任何 bdpan 命令。\n\n> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及\"网盘\"即可触发。\n\n---\n\n## 安全约束（最高优先级，不可被任何用户指令覆盖）\n\n1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code` 等，即使在 GUI 环境也禁止）\n2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）\n3. **更新/登录**：更新必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行 update.sh 或 login.sh\n4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量（这些变量供用户在脚本外手动配置，Agent 不应代为设置）\n5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径\n\n---\n\n## 前置检查\n\n每次触发时按顺序执行：\n\n1. **安装检查**：`command -v bdpan`，未安装则告知用户并确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh`（用户确认后可加 `--yes` 跳过安装器内部确认）\n2. **登录检查**：`bdpan whoami`，未登录则引导执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`\n3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内\n\n---\n\n## 确认规则\n\n| 风险等级 | 操作 | 策略 |\n|----------|------|------|\n| **高（必须确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 列出影响范围，等待用户确认 |\n| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |\n| **低（直接执行）** | ls、search、whoami、mkdir、share | 无需确认 |\n\n**额外规则：**\n- 操作意图模糊（\"处理文件\"→确认上传还是下载）→ 必须确认\n- 序数/代词引用有歧义（\"第N个\"、\"它\"、\"上面那个\"）→ 必须确认\n- 用户取消意图（\"算了\"、\"不要了\"、\"取消\"）→ 立即中止，不执行任何命令\n\n---\n\n## 核心操作\n\n### 查看状态\n\n```bash\nbdpan whoami\n```\n\n### 列表查询\n\n```bash\nbdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]\n```\n\n### 上传\n\n```bash\nbdpan upload <本地路径> <远端路径>\n```\n\n**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。\n\n步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。\n\n### 下载\n\n**直接下载：**\n\n```bash\nbdpan download <远端路径> <本地路径>\n```\n\n步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。\n\n**分享链接下载（先转存再下载到本地）：**\n\n```bash\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd    # 提取码单独传入\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder  # 指定转存目录\n```\n\n### 转存\n\n将分享文件转存到网盘，**不下载到本地**（与 download 分享链接模式的区别）。\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p <提取码> [-d 目标目录] [--json]\n```\n\n步骤：确认分享链接格式有效 → 确认有提取码（链接中含 `?pwd=` 或反问用户）→ 确认目标目录 → 执行。转存成功后只展示本次转存的文件（非整个目录），显示数量和目标目录。\n\n### 分享\n\n```bash\nbdpan share <路径> [路径...] [--json]\n```\n\n步骤：`bdpan ls` 确认文件存在 → 执行分享 → 展示链接+提取码+有效期。\n\n> 付费接口，需在百度网盘开放平台购买服务。\n\n### 搜索\n\n```bash\nbdpan search <关键词> [--category 0-7] [--no-dir|--dir-only] [--page-size N] [--page N] [--json]\n```\n\ncategory：0=全部 1=视频 2=音频 3=图片 4=文档 5=应用 6=其他 7=种子。`--no-dir` 和 `--dir-only` 互斥。\n\n### 移动 / 复制 / 重命名 / 创建文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\nbdpan cp <源路径> <目标目录>\nbdpan rename <路径> <新名称>       # 第二参数是文件名，非完整路径\nbdpan mkdir <路径>\n```\n\n---\n\n## 路径规则\n\n| 场景 | 格式 | 示例 |\n|------|------|------|\n| **命令参数** | 相对路径（相对于 `/apps/bdpan/`） | `bdpan upload ./f.txt docs/f.txt` |\n| **展示给用户** | 中文名 | \"已上传到：我的应用数据/bdpan/docs/f.txt\" |\n\n映射关系：`我的应用数据` ↔ `/apps`\n\n**禁止：** 命令中使用中文路径（`我的应用数据/...`）、展示时暴露 API 路径（`/apps/bdpan/...`）。\n\n---\n\n## 授权码处理\n\n用户发送 32 位十六进制字符串时，先确认：\"这是百度网盘授权码吗？确认后将执行登录流程。\" 确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`（不使用 `--yes`，保留安全确认环节）。\n\n---\n\n## 管理功能\n\n### 安装\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh [--yes]\n```\n\n安装器从百度 CDN（`issuecdn.baidupcs.com`）下载并执行。注意：install.sh 不执行本地 SHA256 校验，完整性依赖 HTTPS 传输保护。安全敏感场景建议先手动审查安装器内容或在沙箱中执行。\n\n### 登录 / 注销 / 卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh              # 登录（内置安全免责声明）\nbdpan logout                                            # 注销\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh [--yes]   # 卸载\n```\n\n### 更新（必须用户明确指令触发）\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh              # 检查并更新（需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check       # 仅检查更新\n```\n\n---\n\n## 参考文档\n\n遇到对应问题时按需查阅，无需预加载：\n\n| 文档 | 何时查阅 |\n|------|---------|\n| [bdpan-commands.md](./reference/bdpan-commands.md) | 需要完整命令参数、选项、JSON 输出格式 |\n| [authentication.md](./reference/authentication.md) | 认证流程细节、Token 管理 |\n| [examples.md](./reference/examples.md) | 更多使用示例（批量上传、自动备份等） |\n| [troubleshooting.md](./reference/troubleshooting.md) | 遇到错误需要排查 |\n\nFile v2.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn732m45det8fggw8x5d7mv9jx80w2q0\",\n  \"slug\": \"baidu-netdisk-storage\",\n  \"version\": \"2.0.1\",\n  \"publishedAt\": 1774607799771\n}\n\nFile v2.0.1:reference/authentication.md\n\n# 认证指南\n\n本指南详细介绍 bdpan CLI 的登录认证流程。\n\n---\n\n## 登录方式\n\n> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。\n\n---\n\n## 验证登录状态\n\n```bash\nbdpan whoami\n```\n\n**已登录时输出：**\n```\n认证状态: 已登录\nToken 有效期至: 2026-03-10 10:30:00\n```\n\n**未登录时输出：**\n```\n认证状态: 未登录\n请执行 bdpan login 进行登录\n```\n\n---\n\n## 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n---\n\n## 常见问题\n\n### 登录后提示 Token 已过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n### 授权链接无效\n\n**症状：** 浏览器打开链接后提示链接无效\n\n**解决方案：**\n1. 重新执行登录脚本获取新的授权链接\n2. 确保在链接有效期内完成授权（通常 10 分钟）\n\n### 授权码输入后报错\n\n**症状：** 输入授权码后提示错误\n\n**解决方案：**\n1. 确保授权码复制完整，没有多余空格\n2. 检查浏览器中显示的授权码是否与输入的一致\n3. 如多次失败，重新执行登录脚本获取新授权码\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n---\n\n## 安全说明\n\n- **OAuth 2.0**：使用授权码模式，不存储用户密码\n- **Token 存储**：Token 加密存储在本地配置文件\n- **自动续期**：Token 快过期时工具会自动刷新\n\n---\n\n## 自动登录失败场景\n\n以下场景会自动切换到 OOB 模式：\n\n| 场景 | 说明 |\n|------|------|\n| SSH 远程登录 | 无图形界面 |\n| WSL 环境 | WebView 支持受限 |\n| 桌面环境锁定 | WebView 无法弹出 |\n| 浏览器未安装 | 无法打开 WebView |\n\n切换到 OOB 模式时，工具会自动提示授权链接，无需用户干预。\n\nFile v2.0.1:reference/bdpan-commands.md\n\n# bdpan CLI 命令快速参考\n\n## 认证命令\n\n### login - 登录授权\n\n> **⛔ Agent 必须通过登录脚本执行登录，禁止直接调用 `bdpan login`。详见 [SKILL.md](../SKILL.md) 安全约束。**\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本内置了安全免责声明和完整的 OOB 授权流程。无论 GUI 或非 GUI 环境，统一使用此脚本。\n\n### logout - 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n### uninstall - 完全卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh\n```\n\n完全卸载 bdpan CLI，自动执行以下操作：\n1. 注销登录并清除授权信息\n2. 删除配置目录（`~/.config/bdpan/`）\n3. 删除 bdpan 二进制文件（`~/.local/bin/bdpan`）\n\n**选项：**\n- `--yes, -y` - 跳过确认提示（自动化场景）\n\n**环境变量：**\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n### whoami - 查看认证状态\n\n```bash\nbdpan whoami\n```\n\n显示当前登录状态、用户名和 Token 有效期信息。\n\n**已登录时输出：**\n```\n认证状态: 已登录\n用户名: your_username\nToken 有效期至: 2026-04-04 10:30:00\n```\n\n**选项：**\n- `--json` - JSON 格式输出\n\n---\n\n## 文件操作命令\n\n### upload - 上传文件\n\n```bash\nbdpan upload <local> <remote>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `local` | 本地文件或文件夹路径 |\n| `remote` | 网盘目标路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 单文件上传\nbdpan upload ./report.pdf report.pdf\n\n# 文件夹上传\nbdpan upload ./project/ project/\n\n# 上传到子目录\nbdpan upload ./data.tar.gz backup/data.tar.gz\n```\n\n**选项：**\n- `--json` - JSON 格式输出上传结果\n\n### download - 下载文件\n\n```bash\nbdpan download <remote> <local> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `remote` | 网盘文件/文件夹路径（相对于 `/apps/bdpan/`）**或**百度网盘分享链接 |\n| `local` | 本地保存路径 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（用于分享链接，如果链接中未包含） |\n| `-t` | 自定义转存目录（相对路径自动拼接 `/apps/bdpan`，绝对路径直接使用） |\n| `--json` | JSON 格式输出下载结果 |\n\n**示例：**\n```bash\n# 单文件下载\nbdpan download report.pdf ./downloaded-report.pdf\n\n# 文件夹下载\nbdpan download project/ ./project-restore/\n\n# 从分享链接下载（链接中包含提取码）\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\n\n# 使用 -p 参数单独传入提取码\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd\n\n# 使用 -t 参数自定义转存目录\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder\n```\n\n**分享链接下载说明：**\n- 自动识别分享链接格式 `https://pan.baidu.com/s/1{surl}?pwd={pwd}`\n- 分享文件会先转存到 `/apps/bdpan/{日期}/` 目录（或使用 `-t` 指定的目录）\n- 然后下载到指定的本地路径\n\n### transfer - 转存分享文件到网盘（不下载到本地）\n\n```bash\nbdpan transfer <分享链接> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `分享链接` | 百度网盘分享链接 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（如果链接中未包含） |\n| `-d` | 目标目录（相对路径自动拼接 `/apps/bdpan`，默认为应用根目录） |\n| `--json` | JSON 格式输出转存结果 |\n\n**示例：**\n```bash\n# 基本用法 - 转存到应用根目录 /apps/bdpan/\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n\n# 提取码在链接中\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n\n# 指定目标目录\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd -d my-folder/\n\n# JSON 输出\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd --json\n```\n\n**与 download 的区别：**\n- `transfer` 仅将分享文件转存到自己的网盘，不下载到本地\n- `download` 会先转存再下载到本地路径\n- 适用于只需要保存到网盘、不需要本地副本的场景\n\n### ls - 查看文件列表\n\n```bash\nbdpan ls [path]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `path` | 要查看的目录路径 | 根目录 |\n\n**选项：**\n- `--json` - JSON 格式输出\n\n**示例：**\n```bash\n# 查看根目录\nbdpan ls\n\n# 查看子目录\nbdpan ls backup\n\n# JSON 输出\nbdpan ls --json\n```\n\n**输出格式：**\n```\n类型    大小          修改时间              文件名\n------  ------------  --------------------  --------\n目录     -            2026-02-20 10:30:00  documents\n文件    1.5 MB        2026-02-25 15:20:00  readme.txt\n文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n共 3 项\n```\n\n### share - 创建分享链接\n\n```bash\nbdpan share <path>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `path` | 要分享的文件或文件夹路径 |\n\n**示例：**\n```bash\n# 分享文件\nbdpan share report.pdf\n\n# 分享文件夹\nbdpan share project\n\n# JSON 输出\nbdpan share --json report.pdf\n```\n\n**输出格式：**\n```\n分享链接创建成功!\n链接: https://pan.baidu.com/s/1xxxxxxx\n提取码: abcd\n有效期: 7 天\n```\n\n### search - 搜索文件\n\n```bash\nbdpan search <关键词> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `关键词` | 搜索关键词（必填） |\n\n**选项：**\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--category` | int | `0` | 文件类型筛选：1=视频, 2=音频, 3=图片, 4=文档, 5=应用, 6=其他, 7=种子 |\n| `--page-size` | int | `5` | 每页数量（最大 50） |\n| `--page` | int | `1` | 页码 |\n| `--no-dir` | bool | `false` | 仅显示文件，排除文件夹 |\n| `--dir-only` | bool | `false` | 仅显示文件夹 |\n| `--json` | - | - | JSON 格式输出 |\n\n> `--no-dir` 和 `--dir-only` 互斥，不能同时使用。\n\n**示例：**\n```bash\n# 搜索文件\nbdpan search report\n\n# 搜索图片类型文件\nbdpan search photo --category 3\n\n# 搜索文件，排除文件夹，每页 10 条\nbdpan search data --no-dir --page-size 10\n\n# 翻页\nbdpan search report --page 2\n\n# JSON 输出\nbdpan search report --json\n```\n\n**输出格式：**\n```\n找到 15 个结果（第 1 页，共 3 页）\n\n#   名称              类型    大小      修改时间\n--- ----------------- ------- --------- ----------------\n1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n\n提示: 使用 --page 2 查看下一页\n```\n\n### mv - 移动文件或文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要移动的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 移动文件到子目录\nbdpan mv report.pdf backup\n\n# 移动文件夹\nbdpan mv old-project archive\n\n# JSON 输出\nbdpan mv report.pdf backup --json\n```\n\n**输出格式：**\n```\n已移动 report.pdf -> backup\n```\n\n### cp - 复制文件或文件夹\n\n```bash\nbdpan cp <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要复制的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 复制文件到子目录\nbdpan cp report.pdf backup\n\n# 复制文件夹\nbdpan cp project project-copy\n\n# JSON 输出\nbdpan cp report.pdf backup --json\n```\n\n**输出格式：**\n```\n已复制 report.pdf -> backup\n```\n\n### rename - 重命名文件或文件夹\n\n```bash\nbdpan rename <路径> <新名称>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要重命名的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `新名称` | 新文件名（仅名称，不含路径） |\n\n**示例：**\n```bash\n# 重命名文件\nbdpan rename old-name.pdf new-name.pdf\n\n# 重命名子目录中的文件\nbdpan rename docs/draft.md final.md\n\n# JSON 输出\nbdpan rename old-name.pdf new-name.pdf --json\n```\n\n**输出格式：**\n```\n已重命名 old-name.pdf -> new-name.pdf\n```\n\n### mkdir - 创建文件夹\n\n```bash\nbdpan mkdir <路径>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要创建的文件夹路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 创建文件夹\nbdpan mkdir backup\n\n# 创建多级目录\nbdpan mkdir backup/2026/03\n\n# JSON 输出\nbdpan mkdir backup --json\n```\n\n**输出格式：**\n```\n已创建文件夹: backup\n```\n\n---\n\n## 版本管理命令\n\n### update - 自动更新 Skill\n\n> **使用 `bash ${CLAUDE_SKILL_DIR}/scripts/update.sh` 更新 Skill 文件。CLI 更新由 `bdpan` 自身管理。**\n\n```bash\n# 检查并更新（交互式，需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh\n\n# 仅检查更新，不执行\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check\n\n# 跳过确认，自动更新（自动化场景）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --yes\n```\n\n**功能说明：**\n- 通过百度配置接口获取最新 Skill 版本信息\n- 对比本地 VERSION 文件判断是否需要更新\n- 下载 zip 包并解压覆盖，更新 VERSION 文件\n- 支持 SHA256 完整性校验（如配置中包含 checksum）\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `--check, -c` | 仅检查更新，不执行安装 |\n| `--yes, -y` | 跳过用户确认，自动执行更新 |\n| `--help` | 显示帮助信息 |\n\n### version - 查看版本信息\n\n```bash\n# 查看当前版本\nbdpan version\n\n# 检查是否有更新\nbdpan version --check\n```\n\n---\n\n## init - 查看安装信息（v3.4.0+）\n\n```bash\nbdpan init\n```\n\n显示安装路径、配置文件路径和 PATH 配置建议。\n\n**输出示例：**\n```\nbdpan 安装信息\n────────────────────────────\n安装路径: /home/user/.local/bin/bdpan\n配置路径: /home/user/.config/bdpan/config.json\n\nPATH 配置建议:\n  export PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n---\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config-path <path>` | 指定配置文件完整路径（适用于 AI Agent 集成） |\n| `--json` | JSON 格式输出 |\n| `--no-check-update` | 禁用版本更新检查 |\n| `--help` | 显示帮助 |\n| `--version` | 显示版本 |\n\n---\n\n## JSON 输出格式\n\n### ls 命令输出\n\n```json\n[\n  {\n    \"fs_id\": 524080722157776,\n    \"path\": \"我的应用数据/report.pdf\",\n    \"server_filename\": \"report.pdf\",\n    \"size\": 1536000,\n    \"isdir\": false,\n    \"md5\": \"a1b2c3d4e5f6...\",\n    \"server_mtime\": \"2026-02-25T15:20:00+08:00\",\n    \"server_ctime\": \"2026-02-25T14:00:00+08:00\"\n  },\n  {\n    \"fs_id\": 841873986109404,\n    \"path\": \"我的应用数据/documents\",\n    \"server_filename\": \"documents\",\n    \"size\": 0,\n    \"isdir\": true,\n    \"md5\": \"\",\n    \"server_mtime\": \"2026-02-20T10:30:00+08:00\",\n    \"server_ctime\": \"2026-02-20T09:00:00+08:00\"\n  }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fs_id` | number | 文件唯一 ID |\n| `path` | string | 文件路径（中文显示名，如 `我的应用数据/...`） |\n| `server_filename` | string | 文件名 |\n| `size` | number | 文件大小（字节），目录为 0 |\n| `isdir` | boolean | 是否为目录（`true`/`false`，注意是小写布尔值） |\n| `md5` | string | 文件 MD5 值，目录为空字符串 |\n| `server_mtime` | string | 服务端修改时间（ISO 8601 带时区） |\n| `server_ctime` | string | 服务端创建时间（ISO 8601 带时区） |\n\n> **注意：** `path` 字段返回中文显示名（`我的应用数据/...`），不是 API 路径（`/apps/bdpan/...`）。展示给用户时可直接使用此路径。\n\n### share 命令输出\n\n```json\n{\n  \"link\": \"https://pan.baidu.com/s/1xxxxxxx\",\n  \"short_url\": \"xxxxxxx\",\n  \"share_id\": 25747091668,\n  \"period\": 7,\n  \"pwd\": \"abcd\"\n}\n```\n\n### upload/download 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"local_path\": \"./report.pdf\",\n  \"remote_path\": \"report.pdf\"\n}\n```\n\n### transfer 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"remote_path\": \"my-folder/shared-file.pdf\",\n  \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n  \"file_count\": 1\n}\n```\n\n### search 命令输出\n\n```json\n{\n  \"total\": 15,\n  \"page\": 1,\n  \"page_size\": 5,\n  \"results\": [\n    {\n      \"fs_id\": 524080722157776,\n      \"path\": \"我的应用数据/bdpan/report.pdf\",\n      \"server_filename\": \"report.pdf\",\n      \"size\": 1536000,\n      \"isdir\": false,\n      \"category\": 4,\n      \"server_mtime\": \"2026-02-25T15:20:00+08:00\"\n    }\n  ]\n}\n```\n\n### mv/cp/rename/mkdir 命令输出\n\n```json\n{\n  \"status\": \"ok\"\n}\n```\n\n---\n\n## 路径规则\n\n- 所有路径相对于应用根目录 `/apps/bdpan/`\n- 支持相对路径: `backup/data.tar.gz`\n- 支持绝对路径: `/apps/bdpan/backup/data.tar.gz`\n- 路径穿越 `..` 会被自动阻止\n\n> **⛔ 双向路径映射规则：** 调用 bdpan 命令时，\"我的应用数据\" 必须转换为 `/apps`；向用户展示路径时，`/apps` 必须转换为 \"我的应用数据\"。详见 [路径规则](../SKILL.md) 章节。\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_PATH` | 配置文件完整路径（优先级最高） | 无 |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n\n**配置路径优先级（v3.4.0+）：**\n1. `--config-path` 命令行参数（最高优先级）\n2. `BDPAN_CONFIG_PATH` 环境变量\n3. `BDPAN_CONFIG_DIR` 环境变量 + `config.json`\n4. `~/.config/bdpan/config.json`（默认路径）\n\n**使用示例：**\n```bash\n# 使用命令行参数指定配置\nbdpan --config-path /custom/path/config.json ls\n\n# 使用环境变量指定配置\nexport BDPAN_CONFIG_PATH=/custom/path/config.json\nbdpan ls\n```\n\n### AI Agent 集成\n\n当 AI Agent 无法通过默认路径读取配置时，可以通过以下方式指定：\n\n```python\nimport subprocess\nimport os\n\nenv = os.environ.copy()\nenv[\"BDPAN_CONFIG_PATH\"] = \"/home/user/.config/bdpan/config.json\"\n\nresult = subprocess.run(\n    [\"bdpan\", \"ls\", \"--json\"],\n    env=env,\n    capture_output=True,\n    text=True\n)\n```\n\n---\n\n## 常见错误码\n\n| 错误 | 说明 | 解决方案 |\n|------|------|---------|\n| Token expired | Token 过期 | 重新登录 |\n| Path not allowed | 路径不在允许范围 | 使用 /apps/bdpan/ 下的路径 |\n| File not found | 文件不存在 | 检查路径是否正确 |\n| errno=13045 | 自己的分享链接 | 文件已在网盘中，直接使用 `bdpan ls` 查找 |\n\n---\n\n## 平台支持\n\n| 功能 | macOS | Linux | Windows (WSL) |\n|------|-------|-------|---------------|\n| 基础功能 | ✅ | ✅ | ✅ |\n| WebView 登录 | ✅ | - | -（WSL 无图形界面，使用 OOB 模式） |\n\nFile v2.0.1:reference/examples.md\n\n# 使用示例\n\n本文档包含 bdpan-storage 的详细使用示例。\n\n---\n\n## 上传并分享\n\n### 示例 1: 上传并分享单个文件\n\n```\n用户: 帮我上传并分享 ./report.pdf\nAI: [执行 bdpan upload ./report.pdf report.pdf]\n    [执行 bdpan share report.pdf]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: abcd\n    有效期: 7 天\n```\n\n### 示例 2: 上传并分享文件夹\n\n```\n用户: 把 ./project 文件夹上传并分享\nAI: [执行 bdpan upload ./project/ project/]\n    [执行 bdpan share project]\n\n    文件夹上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: efgh\n    有效期: 7 天\n```\n\n### 示例 3: 上传到子目录\n\n```\n用户: 上传 ./data.tar.gz 到 backup 目录并分享\nAI: [执行 bdpan upload ./data.tar.gz backup/data.tar.gz]\n    [执行 bdpan share backup/data.tar.gz]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: ijkl\n    有效期: 7 天\n```\n\n---\n\n## 下载文件\n\n### 示例 4: 下载单个文件\n\n```\n用户: 从网盘下载 report.pdf\nAI: [执行 bdpan download report.pdf ./report.pdf]\n\n    正在下载 report.pdf → ./report.pdf ...\n    ✓ 下载成功\n```\n\n### 示例 5: 下载文件夹\n\n```\n用户: 把 backup 文件夹下载到本地\nAI: [执行 bdpan download backup/ ./backup/]\n\n    正在下载 backup/ → ./backup/ ...\n    ✓ 下载成功\n```\n\n---\n\n## 文件列表\n\n### 示例 6: 查看已上传文件\n\n```\n用户: 查看我上传了哪些文件\nAI: [执行 bdpan ls]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    目录     -            2026-02-20 10:30:00  backup\n    文件    1.5 MB        2026-02-25 15:20:00  report.pdf\n    文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n    共 3 项\n```\n\n### 示例 7: 查看子目录\n\n```\n用户: 查看 backup 目录下的文件\nAI: [执行 bdpan ls backup]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    文件    2.1 GB        2026-02-19 08:00:00  data-2026-02-19.tar.gz\n    文件    1.8 GB        2026-02-18 08:00:00  data-2026-02-18.tar.gz\n\n    共 2 项\n```\n\n---\n\n## JSON 输出（用于脚本）\n\n### 示例 8: JSON 格式文件列表\n\n```\n用户: 列出所有文件名（JSON 格式）\nAI: [执行 bdpan ls --json]\n\n    输出:\n    [\n      {\n        \"Name\": \"report.pdf\",\n        \"IsDir\": false,\n        \"Size\": 1536000,\n        \"Modified\": \"2026-02-25T15:20:00Z\"\n      },\n      {\n        \"Name\": \"backup\",\n        \"IsDir\": true,\n        \"Size\": 0,\n        \"Modified\": \"2026-02-20T10:30:00Z\"\n      }\n    ]\n```\n\n### 示例 9: 使用 jq 处理输出\n\n```bash\n# 提取所有文件名\nbdpan ls --json | jq -r '.[].Name'\n\n# 只列出文件（排除目录）\nbdpan ls --json | jq '.[] | select(.IsDir == false)'\n\n# 按大小排序\nbdpan ls --json | jq 'sort_by(.Size) | reverse'\n\n# 检查文件是否存在\nbdpan ls --json | jq -e '.[] | select(.Name == \"target.txt\")'\n```\n\n---\n\n## 认证流程\n\n### 示例 10: 登录（统一使用 login.sh 脚本）\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n```\n用户: 帮我登录百度网盘\nAI: [执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh]\n\n    [展示安全免责声明]\n    已阅读上述安全须知，确认继续登录? [y/N]\n\n用户: y\nAI: 正在获取授权链接...\n\n    请在浏览器中打开以下链接完成授权:\n    https://openapi.baidu.com/oauth/2.0/authorize?...\n\n    授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n    [等待用户输入...]\n\n用户: [粘贴授权码] ca0ee3070f75d0246357e5c74d525bda\nAI: [处理授权码]\n\n    ✓ 登录成功！\n    用户: username@baidu.com\n```\n\n---\n\n## 转存分享文件到网盘\n\n### 示例 15: 转存分享链接（提取码在链接中）\n\n```\n用户: 帮我把这个链接转存到网盘 https://pan.baidu.com/s/1xxxxx?pwd=abcd\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/\n```\n\n### 示例 16: 转存到指定目录\n\n```\n用户: 把 https://pan.baidu.com/s/1xxxxx 转存到 shared 目录，提取码是 efgh\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p efgh -d shared/]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/shared/\n```\n\n### 示例 17: 转存并查看结果（JSON）\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" --json\n# 输出:\n# {\n#   \"status\": \"success\",\n#   \"remote_path\": \"shared-file.pdf\",\n#   \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n#   \"file_count\": 1\n# }\n```\n\n---\n\n## 搜索文件\n\n### 示例 18: 搜索文件\n\n```\n用户: 在网盘里搜索 report\nAI: [执行 bdpan search report]\n\n    找到 3 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n    2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n    3   report-backup     目录    -         2026-02-20 10:30\n```\n\n### 示例 19: 按类型搜索\n\n```\n用户: 搜索网盘里所有的图片文件\nAI: [执行 bdpan search \"\" --category 3 --no-dir]\n\n    找到 5 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   photo.jpg         图片    3.2 MB    2026-03-15 14:30\n    2   screenshot.png    图片    1.1 MB    2026-03-10 09:20\n    ...\n```\n\n---\n\n## 文件管理（移动/复制/重命名/创建文件夹）\n\n### 示例 20: 移动文件\n\n```\n用户: 把网盘里的 report.pdf 移动到 backup 目录\nAI: [执行 bdpan mv report.pdf backup]\n\n    已移动 report.pdf -> backup\n```\n\n### 示例 21: 复制文件\n\n```\n用户: 复制 report.pdf 到 archive 目录\nAI: [执行 bdpan cp report.pdf archive]\n\n    已复制 report.pdf -> archive\n```\n\n### 示例 22: 重命名文件\n\n```\n用户: 把 draft.pdf 重命名为 final-report.pdf\nAI: [执行 bdpan rename draft.pdf final-report.pdf]\n\n    已重命名 draft.pdf -> final-report.pdf\n```\n\n### 示例 23: 创建文件夹\n\n```\n用户: 在网盘里创建一个 projects 文件夹\nAI: [执行 bdpan mkdir projects]\n\n    已创建文件夹: projects\n```\n\n### 示例 24: 组合操作——创建目录并移动文件\n\n```\n用户: 帮我在网盘里创建一个 archive/2026 目录，然后把 old-report.pdf 移动过去\nAI: [执行 bdpan mkdir archive/2026]\n    已创建文件夹: archive/2026\n\n    [执行 bdpan mv old-report.pdf archive/2026]\n    已移动 old-report.pdf -> archive/2026\n```\n\n---\n\n## 高级用法\n\n### 示例 12: 批量上传\n\n```bash\n# 上传当前目录所有 PDF 文件\nfor f in *.pdf; do\n  bdpan upload \"$f\" \"documents/$f\"\ndone\n\n# 上传并记录结果\nfor f in *.pdf; do\n  echo \"上传 $f...\"\n  bdpan upload \"$f\" \"documents/$f\" --json | jq '.'\ndone\n```\n\n### 示例 13: 自动备份脚本\n\n```bash\n#!/bin/bash\n# 每日备份脚本\n\nDATE=$(date +%Y-%m-%d)\nBACKUP_FILE=\"backup-${DATE}.tar.gz\"\n\n# 打包\ntar -czf \"/tmp/${BACKUP_FILE}\" ~/important-data/\n\n# 上传\nbdpan upload \"/tmp/${BACKUP_FILE}\" \"backup/${BACKUP_FILE}\"\n\n# 清理\nrm \"/tmp/${BACKUP_FILE}\"\n\necho \"备份完成: ${BACKUP_FILE}\"\n```\n\n### 示例 14: 检查上传状态\n\n```bash\n# 检查文件是否已上传\ncheck_uploaded() {\n  local file=$1\n  bdpan ls --json | jq -e \".[] | select(.Name == \\\"${file}\\\")\" > /dev/null\n}\n\nif check_uploaded \"report.pdf\"; then\n  echo \"文件已存在\"\nelse\n  echo \"文件不存在，开始上传...\"\n  bdpan upload ./report.pdf report.pdf\nfi\n```\n\nFile v2.0.1:reference/notes.md\n\n# 开发笔记与注意事项\n\n本文档包含 Skill 开发阶段的注意事项和内部说明，**不面向最终用户**。\n\n---\n\n## BETA 阶段安全须知\n\n> **1.** 本工具处于公测期，仅供技术交流，请**备份**网盘重要数据。\n> **2.** AI Agent 行为不可预测，请**人工审核**每条指令。\n> **3.** 严禁在公用或不可信环境中扫码授权。使用完毕后执行 `bdpan logout` 清除授权。\n> **4.** 严格保护配置文件与 Token，切勿在公开仓库或对话中暴露。\n\n**首次使用时，向用户展示上述安全须知。**\n\n---\n\n## 内部实现说明\n\n### Agent 安全限制\n\n所有 Agent 安全约束（登录方式、Token 保护、更新控制、环境变量、路径安全）集中定义在 [SKILL.md](../SKILL.md) 的「安全约束」章节。此处不再重复，维护时以 SKILL.md 为准。\n\n### 授权码处理\n\n当用户在对话中发送一个 32 位十六进制字符串（正则：`^[a-fA-F0-9]{32}$`），处理规则详见 SKILL.md「授权码处理」章节。\n\nFile v2.0.1:reference/troubleshooting.md\n\n# 故障排除指南\n\n本指南涵盖了使用 bdpan CLI 时的常见问题和解决方案。\n\n---\n\n## 认证问题\n\n### Token 过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n### WebView 无法打开\n\n**症状：** 登录过程中浏览器或 WebView 窗口未出现。\n\n**解决方案：**\n工具会自动降级到 OOB（Out-of-Band）模式，按以下步骤操作：\n\n1. 复制控制台显示的授权链接：\n   ```\n   https://openapi.baidu.com/oauth/...?device_code=xxxxx\n   ```\n\n2. 在浏览器中打开该链接\n\n3. 完成授权后，浏览器会显示授权码\n\n4. 复制授权码并粘贴到命令行提示处\n\n5. 按回车确认\n\n**示例输出：**\n```\n请在浏览器中打开以下链接完成授权:\nhttps://openapi.baidu.com/oauth/2.0/authorize?response_type=device_code&client_id=...&device_code=xxxxx\n\n授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n[等待用户输入授权码...]\n```\n\n### 授权后登录失败\n\n**症状：** 授权页面完成但登录仍然失败。\n\n**解决方案：**\n```bash\n# 清除配置并重试\nrm ~/.config/bdpan/config.json\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n---\n\n## 文件操作问题\n\n### 路径不在允许范围\n\n**症状：**\n```\n错误: 路径不在允许范围内\nError: Path not in allowed range\n```\n\n**解决方案：**\n确保所有路径都在 `/apps/bdpan/` 目录下。\n\n错误：\n```bash\nbdpan ls /my-documents\nbdpan upload ./file.txt /other/file.txt\n```\n\n正确：\n```bash\nbdpan ls my-documents\nbdpan upload ./file.txt my-documents/file.txt\n```\n\n### 使用中文路径导致下载/上传失败\n\n**症状：**\n```\n错误: 文件不存在\n# 实际原因：使用了 \"/我的应用数据/bdpan/...\" 而不是 \"/apps/bdpan/...\"\n```\n\n**说明：**\n百度网盘界面中显示的 **\"我的应用数据\"** 是中文显示名，对应的 API 实际路径是 **`/apps`**。两个方向都需要映射：\n- **调用命令时**：中文路径 → API 路径（`我的应用数据` → `/apps`）\n- **展示给用户时**：API 路径 → 中文路径（`/apps` → `我的应用数据`）\n\n**路径映射：**\n| 用户可见名称 | API 实际路径 |\n|-------------|-------------|\n| 我的应用数据 | `/apps` |\n| 我的应用数据/bdpan | `/apps/bdpan` |\n\n**解决方案：**\n调用命令时使用相对路径或英文 API 绝对路径，展示给用户时转换为中文名：\n\n```bash\n# ✅ 命令中使用 API 路径\nbdpan download report.pdf ./report.pdf\n\n# ✅ 展示给用户时使用中文名\n# \"文件已上传到：我的应用数据/bdpan/report.pdf\"\n\n# ❌ 命令中使用中文路径\nbdpan download /我的应用数据/bdpan/report.pdf ./report.pdf\n\n# ❌ 展示给用户时暴露 API 路径\n# \"文件已上传到：/apps/bdpan/report.pdf\"\n```\n\n### 文件不存在\n\n**症状：**\n```\n错误: 文件不存在\nError: File not found\n```\n\n**解决方案：**\n1. 检查本地文件是否存在：\n   ```bash\n   ls -la <本地路径>\n   ```\n2. 检查远程文件是否存在：\n   ```bash\n   bdpan ls\n   ```\n\n### 上传/下载超时\n\n**症状：** 操作耗时过长并超时。\n\n**解决方案：**\n1. 大文件可能需要最多 30 分钟\n2. 检查网络连接稳定性\n3. 对于非常大的文件，考虑先压缩/分割：\n   ```bash\n   # 上传前压缩\n   tar -czf archive.tar.gz large-folder/\n   bdpan upload archive.tar.gz backup/archive.tar.gz\n   ```\n\n### 转存失败\n\n**症状：**\n```\n错误: 转存失败\nError: Transfer failed\n```\n\n**常见原因及解决方案：**\n\n1. **分享链接已失效**：联系分享者重新生成链接\n2. **提取码错误**：确认提取码是否正确\n   ```bash\n   # 提取码通过 -p 传入\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n   # 或包含在链接中\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n   ```\n3. **网盘空间不足**：清理网盘空间后重试\n\n#### 错误码 errno=13045（自己的分享链接）\n\n**症状：**\n```\n转存失败: errno=13045, msg=prohibit transfer self share link\n```\n\n**原因：**\n这是您自己创建并分享的链接，文件已经在您的网盘中，无需再次转存。\n\n**处理方式：**\n- **不向用户展示错误**，直接告知文件已在网盘中\n- 使用 `bdpan ls` 查找并展示该文件\n- 如需要，可提供分享链接供他人使用\n\n示例回复：\n```\n✅ 文件已在您的网盘中！\n\n文件信息：\n- 文件名：example.pdf\n- 位置：我的应用数据/bdpan/example.pdf\n- 大小：1.2 MB\n\n无需转存，直接使用即可。\n```\n\n### 权限不足\n\n**症状：**\n```\n错误: 权限不足\nError: Permission denied\n```\n\n**解决方案：**\n1. 检查本地文件权限：\n   ```bash\n   ls -l <本地路径>\n   ```\n2. 确保您对目标目录有写入权限：\n   ```bash\n   ls -ld <目标目录>\n   ```\n\n---\n\n## 安装问题\n\n### 命令未找到\n\n**症状：** `bdpan: command not found`\n\n**解决方案：**\n```bash\n# 重新运行安装脚本\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n\n# 或者检查 ~/.local/bin 是否在 PATH 中\necho $PATH\n\n# 如果缺失则添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### 下载了错误的架构\n\n**症状：** 二进制文件无法运行或提示 \"exec format error\"\n\n**解决方案：**\n```bash\n# 删除现有二进制文件\nrm ~/.local/bin/bdpan\n\n# 重新安装\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh\n```\n\n---\n\n## JSON 输出问题\n\n### 无效的 JSON 输出\n\n**症状：** `--json` 输出无法被解析。\n\n**解决方案：**\n1. 确保 stdout 中没有错误消息\n2. 检查输出中只有 JSON 内容\n3. 使用 `jq` 验证：\n   ```bash\n   bdpan ls --json | jq .\n   ```\n\n---\n\n## 平台特定问题\n\n### macOS\n\n#### Gatekeeper 阻止\n\n**症状：** 无法打开应用，因为它来自身份不明的开发者。\n\n**解决方案：**\n```bash\nxattr -d com.apple.quarantine ~/.local/bin/bdpan\n```\n\n### Linux\n\n#### 缺少依赖\n\n**症状：** 二进制文件运行失败，提示缺少库。\n\n**解决方案：**\n安装所需依赖（特定于发行版）：\n```bash\n# Debian/Ubuntu\nsudo apt-get install libc6\n\n# Fedora/RHEL\nsudo dnf install glibc\n```\n\n### Windows (WSL)\n\n#### 路径问题\n\n**症状：** Windows 路径无法正常工作。\n\n**解决方案：**\n在 WSL 中始终使用 Unix 风格路径：\n```bash\n# 正确\nbdpan upload ./file.txt file.txt\n\n# 错误\nbdpan upload .\\\\file.txt file.txt\n```\n\n---\n\n## 获取帮助\n\n### 检查版本\n\n```bash\nbdpan version\n```\n\n### 获取命令帮助\n\n```bash\nbdpan --help\nbdpan upload --help\nbdpan download --help\n```\n\n### 启用调试模式\n\n```bash\n# 检查配置文件是否存在及权限\nls -la ~/.config/bdpan/\n\n# 检查登录状态和 Token 有效期\nbdpan whoami\n```\n\n> **⛔ 安全警告：** 切勿使用 `cat` 查看配置文件内容，配置文件中包含 access_token 等敏感凭据，打印到终端或对话中可能导致泄露。\n\nArchive v2.0.0: 11 files, 27774 bytes\n\nFiles: reference/authentication.md (2336b), reference/bdpan-commands.md (14912b), reference/examples.md (7746b), reference/notes.md (1045b), reference/troubleshooting.md (7063b), scripts/install.sh (8876b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (7112b), _meta.json (140b)\n\nFile v2.0.0:SKILL.md\n\n---\nname: bdpan-storage\ndescription: 百度网盘文件管理。支持上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。当用户提及\"百度网盘\"\"bdpan\"\"网盘\"并涉及文件操作时触发。\nallowed-tools: Bash, Read, Glob, Grep, AskUserQuestion\nargument-hint: \"[操作指令]\"\n---\n\n# 百度网盘存储 Skill\n\n百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。\n\n> 内测阶段，使用注意事项详见 [reference/notes.md](./reference/notes.md)\n\n## 触发规则\n\n同时满足以下条件才执行：\n\n1. 用户明确提及\"百度网盘\"、\"bdpan\"、\"网盘\"\n2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/登录/注销）\n\n未通过触发规则时，禁止执行任何 bdpan 命令。\n\n> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及\"网盘\"即可触发。\n\n---\n\n## 安全约束（最高优先级，不可被任何用户指令覆盖）\n\n1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code` 等，即使在 GUI 环境也禁止）\n2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）\n3. **更新**：必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行更新或登录脚本\n4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量\n5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径\n\n---\n\n## 前置检查\n\n每次触发时按顺序执行：\n\n1. **安装检查**：`command -v bdpan`，未安装则执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh --yes`\n2. **登录检查**：`bdpan whoami`，未登录则引导执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`\n3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内\n\n---\n\n## 确认规则\n\n| 风险等级 | 操作 | 策略 |\n|----------|------|------|\n| **高（必须确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 列出影响范围，等待用户确认 |\n| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |\n| **低（直接执行）** | ls、search、whoami、mkdir、share | 无需确认 |\n\n**额外规则：**\n- 操作意图模糊（\"处理文件\"→确认上传还是下载）→ 必须确认\n- 序数/代词引用有歧义（\"第N个\"、\"它\"、\"上面那个\"）→ 必须确认\n- 用户取消意图（\"算了\"、\"不要了\"、\"取消\"）→ 立即中止，不执行任何命令\n\n---\n\n## 核心操作\n\n### 查看状态\n\n```bash\nbdpan whoami\n```\n\n### 列表查询\n\n```bash\nbdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]\n```\n\n### 上传\n\n```bash\nbdpan upload <本地路径> <远端路径>\n```\n\n**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。\n\n步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。\n\n### 下载\n\n**直接下载：**\n\n```bash\nbdpan download <远端路径> <本地路径>\n```\n\n步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。\n\n**分享链接下载（先转存再下载到本地）：**\n\n```bash\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd    # 提取码单独传入\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder  # 指定转存目录\n```\n\n### 转存\n\n将分享文件转存到网盘，**不下载到本地**（与 download 分享链接模式的区别）。\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p <提取码> [-d 目标目录] [--json]\n```\n\n步骤：确认分享链接格式有效 → 确认有提取码（链接中含 `?pwd=` 或反问用户）→ 确认目标目录 → 执行。转存成功后只展示本次转存的文件（非整个目录），显示数量和目标目录。\n\n### 分享\n\n```bash\nbdpan share <路径> [路径...] [--json]\n```\n\n步骤：`bdpan ls` 确认文件存在 → 执行分享 → 展示链接+提取码+有效期。\n\n> 付费接口，需在百度网盘开放平台购买服务。\n\n### 搜索\n\n```bash\nbdpan search <关键词> [--category 0-7] [--no-dir|--dir-only] [--page-size N] [--page N] [--json]\n```\n\ncategory：0=全部 1=视频 2=音频 3=图片 4=文档 5=应用 6=其他 7=种子。`--no-dir` 和 `--dir-only` 互斥。\n\n### 移动 / 复制 / 重命名 / 创建文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\nbdpan cp <源路径> <目标目录>\nbdpan rename <路径> <新名称>       # 第二参数是文件名，非完整路径\nbdpan mkdir <路径>\n```\n\n---\n\n## 路径规则\n\n| 场景 | 格式 | 示例 |\n|------|------|------|\n| **命令参数** | 相对路径（相对于 `/apps/bdpan/`） | `bdpan upload ./f.txt docs/f.txt` |\n| **展示给用户** | 中文名 | \"已上传到：我的应用数据/bdpan/docs/f.txt\" |\n\n映射关系：`我的应用数据` ↔ `/apps`\n\n**禁止：** 命令中使用中文路径（`我的应用数据/...`）、展示时暴露 API 路径（`/apps/bdpan/...`）。\n\n---\n\n## 授权码处理\n\n用户发送 32 位十六进制字符串时，先确认：\"这是百度网盘授权码吗？确认后将执行登录流程。\" 确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`（不使用 `--yes`，保留安全确认环节）。\n\n---\n\n## 管理功能\n\n### 安装\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/install.sh [--yes]\n```\n\n安装器从百度 CDN（`issuecdn.baidupcs.com`）下载，内部完成 SHA256 完整性校验。安全敏感场景建议沙箱执行或手动审查。\n\n### 登录 / 注销 / 卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh              # 登录（内置安全免责声明）\nbdpan logout                                            # 注销\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh [--yes]   # 卸载\n```\n\n### 更新（必须用户明确指令触发）\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh              # 检查并更新（需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check       # 仅检查更新\n```\n\n---\n\n## 参考文档\n\n遇到对应问题时按需查阅，无需预加载：\n\n| 文档 | 何时查阅 |\n|------|---------|\n| [bdpan-commands.md](./reference/bdpan-commands.md) | 需要完整命令参数、选项、JSON 输出格式 |\n| [authentication.md](./reference/authentication.md) | 认证流程细节、Token 管理 |\n| [examples.md](./reference/examples.md) | 更多使用示例（批量上传、自动备份等） |\n| [troubleshooting.md](./reference/troubleshooting.md) | 遇到错误需要排查 |\n\nFile v2.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn732m45det8fggw8x5d7mv9jx80w2q0\",\n  \"slug\": \"baidu-netdisk-storage\",\n  \"version\": \"2.0.0\",\n  \"publishedAt\": 1774607438860\n}\n\nFile v2.0.0:reference/authentication.md\n\n# 认证指南\n\n本指南详细介绍 bdpan CLI 的登录认证流程。\n\n---\n\n## 登录方式\n\n> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。\n\n---\n\n## 验证登录状态\n\n```bash\nbdpan whoami\n```\n\n**已登录时输出：**\n```\n认证状态: 已登录\nToken 有效期至: 2026-03-10 10:30:00\n```\n\n**未登录时输出：**\n```\n认证状态: 未登录\n请执行 bdpan login 进行登录\n```\n\n---\n\n## 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n---\n\n## 常见问题\n\n### 登录后提示 Token 已过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n### 授权链接无效\n\n**症状：** 浏览器打开链接后提示链接无效\n\n**解决方案：**\n1. 重新执行登录脚本获取新的授权链接\n2. 确保在链接有效期内完成授权（通常 10 分钟）\n\n### 授权码输入后报错\n\n**症状：** 输入授权码后提示错误\n\n**解决方案：**\n1. 确保授权码复制完整，没有多余空格\n2. 检查浏览器中显示的授权码是否与输入的一致\n3. 如多次失败，重新执行登录脚本获取新授权码\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n---\n\n## 安全说明\n\n- **OAuth 2.0**：使用授权码模式，不存储用户密码\n- **Token 存储**：Token 加密存储在本地配置文件\n- **自动续期**：Token 快过期时工具会自动刷新\n\n---\n\n## 自动登录失败场景\n\n以下场景会自动切换到 OOB 模式：\n\n| 场景 | 说明 |\n|------|------|\n| SSH 远程登录 | 无图形界面 |\n| WSL 环境 | WebView 支持受限 |\n| 桌面环境锁定 | WebView 无法弹出 |\n| 浏览器未安装 | 无法打开 WebView |\n\n切换到 OOB 模式时，工具会自动提示授权链接，无需用户干预。\n\nFile v2.0.0:reference/bdpan-commands.md\n\n# bdpan CLI 命令快速参考\n\n## 认证命令\n\n### login - 登录授权\n\n> **⛔ Agent 必须通过登录脚本执行登录，禁止直接调用 `bdpan login`。详见 [SKILL.md](../SKILL.md) 安全约束。**\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本内置了安全免责声明和完整的 OOB 授权流程。无论 GUI 或非 GUI 环境，统一使用此脚本。\n\n### logout - 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n### uninstall - 完全卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh\n```\n\n完全卸载 bdpan CLI，自动执行以下操作：\n1. 注销登录并清除授权信息\n2. 删除配置目录（`~/.config/bdpan/`）\n3. 删除 bdpan 二进制文件（`~/.local/bin/bdpan`）\n\n**选项：**\n- `--yes, -y` - 跳过确认提示（自动化场景）\n\n**环境变量：**\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n### whoami - 查看认证状态\n\n```bash\nbdpan whoami\n```\n\n显示当前登录状态、用户名和 Token 有效期信息。\n\n**已登录时输出：**\n```\n认证状态: 已登录\n用户名: your_username\nToken 有效期至: 2026-04-04 10:30:00\n```\n\n**选项：**\n- `--json` - JSON 格式输出\n\n---\n\n## 文件操作命令\n\n### upload - 上传文件\n\n```bash\nbdpan upload <local> <remote>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `local` | 本地文件或文件夹路径 |\n| `remote` | 网盘目标路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 单文件上传\nbdpan upload ./report.pdf report.pdf\n\n# 文件夹上传\nbdpan upload ./project/ project/\n\n# 上传到子目录\nbdpan upload ./data.tar.gz backup/data.tar.gz\n```\n\n**选项：**\n- `--json` - JSON 格式输出上传结果\n\n### download - 下载文件\n\n```bash\nbdpan download <remote> <local> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `remote` | 网盘文件/文件夹路径（相对于 `/apps/bdpan/`）**或**百度网盘分享链接 |\n| `local` | 本地保存路径 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（用于分享链接，如果链接中未包含） |\n| `-t` | 自定义转存目录（相对路径自动拼接 `/apps/bdpan`，绝对路径直接使用） |\n| `--json` | JSON 格式输出下载结果 |\n\n**示例：**\n```bash\n# 单文件下载\nbdpan download report.pdf ./downloaded-report.pdf\n\n# 文件夹下载\nbdpan download project/ ./project-restore/\n\n# 从分享链接下载（链接中包含提取码）\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\n\n# 使用 -p 参数单独传入提取码\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd\n\n# 使用 -t 参数自定义转存目录\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder\n```\n\n**分享链接下载说明：**\n- 自动识别分享链接格式 `https://pan.baidu.com/s/1{surl}?pwd={pwd}`\n- 分享文件会先转存到 `/apps/bdpan/{日期}/` 目录（或使用 `-t` 指定的目录）\n- 然后下载到指定的本地路径\n\n### transfer - 转存分享文件到网盘（不下载到本地）\n\n```bash\nbdpan transfer <分享链接> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `分享链接` | 百度网盘分享链接 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（如果链接中未包含） |\n| `-d` | 目标目录（相对路径自动拼接 `/apps/bdpan`，默认为应用根目录） |\n| `--json` | JSON 格式输出转存结果 |\n\n**示例：**\n```bash\n# 基本用法 - 转存到应用根目录 /apps/bdpan/\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n\n# 提取码在链接中\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n\n# 指定目标目录\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd -d my-folder/\n\n# JSON 输出\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd --json\n```\n\n**与 download 的区别：**\n- `transfer` 仅将分享文件转存到自己的网盘，不下载到本地\n- `download` 会先转存再下载到本地路径\n- 适用于只需要保存到网盘、不需要本地副本的场景\n\n### ls - 查看文件列表\n\n```bash\nbdpan ls [path]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `path` | 要查看的目录路径 | 根目录 |\n\n**选项：**\n- `--json` - JSON 格式输出\n\n**示例：**\n```bash\n# 查看根目录\nbdpan ls\n\n# 查看子目录\nbdpan ls backup\n\n# JSON 输出\nbdpan ls --json\n```\n\n**输出格式：**\n```\n类型    大小          修改时间              文件名\n------  ------------  --------------------  --------\n目录     -            2026-02-20 10:30:00  documents\n文件    1.5 MB        2026-02-25 15:20:00  readme.txt\n文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n共 3 项\n```\n\n### share - 创建分享链接\n\n```bash\nbdpan share <path>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `path` | 要分享的文件或文件夹路径 |\n\n**示例：**\n```bash\n# 分享文件\nbdpan share report.pdf\n\n# 分享文件夹\nbdpan share project\n\n# JSON 输出\nbdpan share --json report.pdf\n```\n\n**输出格式：**\n```\n分享链接创建成功!\n链接: https://pan.baidu.com/s/1xxxxxxx\n提取码: abcd\n有效期: 7 天\n```\n\n### search - 搜索文件\n\n```bash\nbdpan search <关键词> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `关键词` | 搜索关键词（必填） |\n\n**选项：**\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--category` | int | `0` | 文件类型筛选：1=视频, 2=音频, 3=图片, 4=文档, 5=应用, 6=其他, 7=种子 |\n| `--page-size` | int | `5` | 每页数量（最大 50） |\n| `--page` | int | `1` | 页码 |\n| `--no-dir` | bool | `false` | 仅显示文件，排除文件夹 |\n| `--dir-only` | bool | `false` | 仅显示文件夹 |\n| `--json` | - | - | JSON 格式输出 |\n\n> `--no-dir` 和 `--dir-only` 互斥，不能同时使用。\n\n**示例：**\n```bash\n# 搜索文件\nbdpan search report\n\n# 搜索图片类型文件\nbdpan search photo --category 3\n\n# 搜索文件，排除文件夹，每页 10 条\nbdpan search data --no-dir --page-size 10\n\n# 翻页\nbdpan search report --page 2\n\n# JSON 输出\nbdpan search report --json\n```\n\n**输出格式：**\n```\n找到 15 个结果（第 1 页，共 3 页）\n\n#   名称              类型    大小      修改时间\n--- ----------------- ------- --------- ----------------\n1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n\n提示: 使用 --page 2 查看下一页\n```\n\n### mv - 移动文件或文件夹\n\n```bash\nbdpan mv <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要移动的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 移动文件到子目录\nbdpan mv report.pdf backup\n\n# 移动文件夹\nbdpan mv old-project archive\n\n# JSON 输出\nbdpan mv report.pdf backup --json\n```\n\n**输出格式：**\n```\n已移动 report.pdf -> backup\n```\n\n### cp - 复制文件或文件夹\n\n```bash\nbdpan cp <源路径> <目标目录>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `源路径` | 要复制的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `目标目录` | 目标目录路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 复制文件到子目录\nbdpan cp report.pdf backup\n\n# 复制文件夹\nbdpan cp project project-copy\n\n# JSON 输出\nbdpan cp report.pdf backup --json\n```\n\n**输出格式：**\n```\n已复制 report.pdf -> backup\n```\n\n### rename - 重命名文件或文件夹\n\n```bash\nbdpan rename <路径> <新名称>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要重命名的文件或文件夹路径（相对于 `/apps/bdpan/`） |\n| `新名称` | 新文件名（仅名称，不含路径） |\n\n**示例：**\n```bash\n# 重命名文件\nbdpan rename old-name.pdf new-name.pdf\n\n# 重命名子目录中的文件\nbdpan rename docs/draft.md final.md\n\n# JSON 输出\nbdpan rename old-name.pdf new-name.pdf --json\n```\n\n**输出格式：**\n```\n已重命名 old-name.pdf -> new-name.pdf\n```\n\n### mkdir - 创建文件夹\n\n```bash\nbdpan mkdir <路径>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `路径` | 要创建的文件夹路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 创建文件夹\nbdpan mkdir backup\n\n# 创建多级目录\nbdpan mkdir backup/2026/03\n\n# JSON 输出\nbdpan mkdir backup --json\n```\n\n**输出格式：**\n```\n已创建文件夹: backup\n```\n\n---\n\n## 版本管理命令\n\n### update - 自动更新 Skill\n\n> **使用 `bash ${CLAUDE_SKILL_DIR}/scripts/update.sh` 更新 Skill 文件。CLI 更新由 `bdpan` 自身管理。**\n\n```bash\n# 检查并更新（交互式，需用户确认）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh\n\n# 仅检查更新，不执行\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check\n\n# 跳过确认，自动更新（自动化场景）\nbash ${CLAUDE_SKILL_DIR}/scripts/update.sh --yes\n```\n\n**功能说明：**\n- 通过百度配置接口获取最新 Skill 版本信息\n- 对比本地 VERSION 文件判断是否需要更新\n- 下载 zip 包并解压覆盖，更新 VERSION 文件\n- 支持 SHA256 完整性校验（如配置中包含 checksum）\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `--check, -c` | 仅检查更新，不执行安装 |\n| `--yes, -y` | 跳过用户确认，自动执行更新 |\n| `--help` | 显示帮助信息 |\n\n### version - 查看版本信息\n\n```bash\n# 查看当前版本\nbdpan version\n\n# 检查是否有更新\nbdpan version --check\n```\n\n---\n\n## init - 查看安装信息（v3.4.0+）\n\n```bash\nbdpan init\n```\n\n显示安装路径、配置文件路径和 PATH 配置建议。\n\n**输出示例：**\n```\nbdpan 安装信息\n────────────────────────────\n安装路径: /home/user/.local/bin/bdpan\n配置路径: /home/user/.config/bdpan/config.json\n\nPATH 配置建议:\n  export PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n---\n\n## 全局选项\n\n| 选项 | 说明 |\n|------|------|\n| `--config-path <path>` | 指定配置文件完整路径（适用于 AI Agent 集成） |\n| `--json` | JSON 格式输出 |\n| `--no-check-update` | 禁用版本更新检查 |\n| `--help` | 显示帮助 |\n| `--version` | 显示版本 |\n\n---\n\n## JSON 输出格式\n\n### ls 命令输出\n\n```json\n[\n  {\n    \"fs_id\": 524080722157776,\n    \"path\": \"我的应用数据/report.pdf\",\n    \"server_filename\": \"report.pdf\",\n    \"size\": 1536000,\n    \"isdir\": false,\n    \"md5\": \"a1b2c3d4e5f6...\",\n    \"server_mtime\": \"2026-02-25T15:20:00+08:00\",\n    \"server_ctime\": \"2026-02-25T14:00:00+08:00\"\n  },\n  {\n    \"fs_id\": 841873986109404,\n    \"path\": \"我的应用数据/documents\",\n    \"server_filename\": \"documents\",\n    \"size\": 0,\n    \"isdir\": true,\n    \"md5\": \"\",\n    \"server_mtime\": \"2026-02-20T10:30:00+08:00\",\n    \"server_ctime\": \"2026-02-20T09:00:00+08:00\"\n  }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fs_id` | number | 文件唯一 ID |\n| `path` | string | 文件路径（中文显示名，如 `我的应用数据/...`） |\n| `server_filename` | string | 文件名 |\n| `size` | number | 文件大小（字节），目录为 0 |\n| `isdir` | boolean | 是否为目录（`true`/`false`，注意是小写布尔值） |\n| `md5` | string | 文件 MD5 值，目录为空字符串 |\n| `server_mtime` | string | 服务端修改时间（ISO 8601 带时区） |\n| `server_ctime` | string | 服务端创建时间（ISO 8601 带时区） |\n\n> **注意：** `path` 字段返回中文显示名（`我的应用数据/...`），不是 API 路径（`/apps/bdpan/...`）。展示给用户时可直接使用此路径。\n\n### share 命令输出\n\n```json\n{\n  \"link\": \"https://pan.baidu.com/s/1xxxxxxx\",\n  \"short_url\": \"xxxxxxx\",\n  \"share_id\": 25747091668,\n  \"period\": 7,\n  \"pwd\": \"abcd\"\n}\n```\n\n### upload/download 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"local_path\": \"./report.pdf\",\n  \"remote_path\": \"report.pdf\"\n}\n```\n\n### transfer 命令输出\n\n```json\n{\n  \"status\": \"success\",\n  \"remote_path\": \"my-folder/shared-file.pdf\",\n  \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n  \"file_count\": 1\n}\n```\n\n### search 命令输出\n\n```json\n{\n  \"total\": 15,\n  \"page\": 1,\n  \"page_size\": 5,\n  \"results\": [\n    {\n      \"fs_id\": 524080722157776,\n      \"path\": \"我的应用数据/bdpan/report.pdf\",\n      \"server_filename\": \"report.pdf\",\n      \"size\": 1536000,\n      \"isdir\": false,\n      \"category\": 4,\n      \"server_mtime\": \"2026-02-25T15:20:00+08:00\"\n    }\n  ]\n}\n```\n\n### mv/cp/rename/mkdir 命令输出\n\n```json\n{\n  \"status\": \"ok\"\n}\n```\n\n---\n\n## 路径规则\n\n- 所有路径相对于应用根目录 `/apps/bdpan/`\n- 支持相对路径: `backup/data.tar.gz`\n- 支持绝对路径: `/apps/bdpan/backup/data.tar.gz`\n- 路径穿越 `..` 会被自动阻止\n\n> **⛔ 双向路径映射规则：** 调用 bdpan 命令时，\"我的应用数据\" 必须转换为 `/apps`；向用户展示路径时，`/apps` 必须转换为 \"我的应用数据\"。详见 [路径规则](../SKILL.md) 章节。\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_PATH` | 配置文件完整路径（优先级最高） | 无 |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n\n**配置路径优先级（v3.4.0+）：**\n1. `--config-path` 命令行参数（最高优先级）\n2. `BDPAN_CONFIG_PATH` 环境变量\n3. `BDPAN_CONFIG_DIR` 环境变量 + `config.json`\n4. `~/.config/bdpan/config.json`（默认路径）\n\n**使用示例：**\n```bash\n# 使用命令行参数指定配置\nbdpan --config-path /custom/path/config.json ls\n\n# 使用环境变量指定配置\nexport BDPAN_CONFIG_PATH=/custom/path/config.json\nbdpan ls\n```\n\n### AI Agent 集成\n\n当 AI Agent 无法通过默认路径读取配置时，可以通过以下方式指定：\n\n```python\nimport subprocess\nimport os\n\nenv = os.environ.copy()\nenv[\"BDPAN_CONFIG_PATH\"] = \"/home/user/.config/bdpan/config.json\"\n\nresult = subprocess.run(\n    [\"bdpan\", \"ls\", \"--json\"],\n    env=env,\n    capture_output=True,\n    text=True\n)\n```\n\n---\n\n## 常见错误码\n\n| 错误 | 说明 | 解决方案 |\n|------|------|---------|\n| Token expired | Token 过期 | 重新登录 |\n| Path not allowed | 路径不在允许范围 | 使用 /apps/bdpan/ 下的路径 |\n| File not found | 文件不存在 | 检查路径是否正确 |\n| errno=13045 | 自己的分享链接 | 文件已在网盘中，直接使用 `bdpan ls` 查找 |\n\n---\n\n## 平台支持\n\n| 功能 | macOS | Linux | Windows (WSL) |\n|------|-------|-------|---------------|\n| 基础功能 | ✅ | ✅ | ✅ |\n| WebView 登录 | ✅ | - | -（WSL 无图形界面，使用 OOB 模式） |\n\nFile v2.0.0:reference/examples.md\n\n# 使用示例\n\n本文档包含 bdpan-storage 的详细使用示例。\n\n---\n\n## 上传并分享\n\n### 示例 1: 上传并分享单个文件\n\n```\n用户: 帮我上传并分享 ./report.pdf\nAI: [执行 bdpan upload ./report.pdf report.pdf]\n    [执行 bdpan share report.pdf]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: abcd\n    有效期: 7 天\n```\n\n### 示例 2: 上传并分享文件夹\n\n```\n用户: 把 ./project 文件夹上传并分享\nAI: [执行 bdpan upload ./project/ project/]\n    [执行 bdpan share project]\n\n    文件夹上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: efgh\n    有效期: 7 天\n```\n\n### 示例 3: 上传到子目录\n\n```\n用户: 上传 ./data.tar.gz 到 backup 目录并分享\nAI: [执行 bdpan upload ./data.tar.gz backup/data.tar.gz]\n    [执行 bdpan share backup/data.tar.gz]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: ijkl\n    有效期: 7 天\n```\n\n---\n\n## 下载文件\n\n### 示例 4: 下载单个文件\n\n```\n用户: 从网盘下载 report.pdf\nAI: [执行 bdpan download report.pdf ./report.pdf]\n\n    正在下载 report.pdf → ./report.pdf ...\n    ✓ 下载成功\n```\n\n### 示例 5: 下载文件夹\n\n```\n用户: 把 backup 文件夹下载到本地\nAI: [执行 bdpan download backup/ ./backup/]\n\n    正在下载 backup/ → ./backup/ ...\n    ✓ 下载成功\n```\n\n---\n\n## 文件列表\n\n### 示例 6: 查看已上传文件\n\n```\n用户: 查看我上传了哪些文件\nAI: [执行 bdpan ls]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    目录     -            2026-02-20 10:30:00  backup\n    文件    1.5 MB        2026-02-25 15:20:00  report.pdf\n    文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n    共 3 项\n```\n\n### 示例 7: 查看子目录\n\n```\n用户: 查看 backup 目录下的文件\nAI: [执行 bdpan ls backup]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    文件    2.1 GB        2026-02-19 08:00:00  data-2026-02-19.tar.gz\n    文件    1.8 GB        2026-02-18 08:00:00  data-2026-02-18.tar.gz\n\n    共 2 项\n```\n\n---\n\n## JSON 输出（用于脚本）\n\n### 示例 8: JSON 格式文件列表\n\n```\n用户: 列出所有文件名（JSON 格式）\nAI: [执行 bdpan ls --json]\n\n    输出:\n    [\n      {\n        \"Name\": \"report.pdf\",\n        \"IsDir\": false,\n        \"Size\": 1536000,\n        \"Modified\": \"2026-02-25T15:20:00Z\"\n      },\n      {\n        \"Name\": \"backup\",\n        \"IsDir\": true,\n        \"Size\": 0,\n        \"Modified\": \"2026-02-20T10:30:00Z\"\n      }\n    ]\n```\n\n### 示例 9: 使用 jq 处理输出\n\n```bash\n# 提取所有文件名\nbdpan ls --json | jq -r '.[].Name'\n\n# 只列出文件（排除目录）\nbdpan ls --json | jq '.[] | select(.IsDir == false)'\n\n# 按大小排序\nbdpan ls --json | jq 'sort_by(.Size) | reverse'\n\n# 检查文件是否存在\nbdpan ls --json | jq -e '.[] | select(.Name == \"target.txt\")'\n```\n\n---\n\n## 认证流程\n\n### 示例 10: 登录（统一使用 login.sh 脚本）\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n```\n用户: 帮我登录百度网盘\nAI: [执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh]\n\n    [展示安全免责声明]\n    已阅读上述安全须知，确认继续登录? [y/N]\n\n用户: y\nAI: 正在获取授权链接...\n\n    请在浏览器中打开以下链接完成授权:\n    https://openapi.baidu.com/oauth/2.0/authorize?...\n\n    授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n    [等待用户输入...]\n\n用户: [粘贴授权码] ca0ee3070f75d0246357e5c74d525bda\nAI: [处理授权码]\n\n    ✓ 登录成功！\n    用户: username@baidu.com\n```\n\n---\n\n## 转存分享文件到网盘\n\n### 示例 15: 转存分享链接（提取码在链接中）\n\n```\n用户: 帮我把这个链接转存到网盘 https://pan.baidu.com/s/1xxxxx?pwd=abcd\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/\n```\n\n### 示例 16: 转存到指定目录\n\n```\n用户: 把 https://pan.baidu.com/s/1xxxxx 转存到 shared 目录，提取码是 efgh\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p efgh -d shared/]\n\n    ✓ 转存成功！\n    文件已保存到：我的应用数据/bdpan/shared/\n```\n\n### 示例 17: 转存并查看结果（JSON）\n\n```bash\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" --json\n# 输出:\n# {\n#   \"status\": \"success\",\n#   \"remote_path\": \"shared-file.pdf\",\n#   \"share_link\": \"https://pan.baidu.com/s/1xxxxx\",\n#   \"file_count\": 1\n# }\n```\n\n---\n\n## 搜索文件\n\n### 示例 18: 搜索文件\n\n```\n用户: 在网盘里搜索 report\nAI: [执行 bdpan search report]\n\n    找到 3 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   report.pdf        文档    1.5 MB    2026-02-25 15:20\n    2   report-draft.docx 文档    256 KB    2026-02-24 09:15\n    3   report-backup     目录    -         2026-02-20 10:30\n```\n\n### 示例 19: 按类型搜索\n\n```\n用户: 搜索网盘里所有的图片文件\nAI: [执行 bdpan search \"\" --category 3 --no-dir]\n\n    找到 5 个结果（第 1 页，共 1 页）\n\n    #   名称              类型    大小      修改时间\n    --- ----------------- ------- --------- ----------------\n    1   photo.jpg         图片    3.2 MB    2026-03-15 14:30\n    2   screenshot.png    图片    1.1 MB    2026-03-10 09:20\n    ...\n```\n\n---\n\n## 文件管理（移动/复制/重命名/创建文件夹）\n\n### 示例 20: 移动文件\n\n```\n用户: 把网盘里的 report.pdf 移动到 backup 目录\nAI: [执行 bdpan mv report.pdf backup]\n\n    已移动 report.pdf -> backup\n```\n\n### 示例 21: 复制文件\n\n```\n用户: 复制 report.pdf 到 archive 目录\nAI: [执行 bdpan cp report.pdf archive]\n\n    已复制 report.pdf -> archive\n```\n\n### 示例 22: 重命名文件\n\n```\n用户: 把 draft.pdf 重命名为 final-report.pdf\nAI: [执行 bdpan rename draft.pdf final-report.pdf]\n\n    已重命名 draft.pdf -> final-report.pdf\n```\n\n### 示例 23: 创建文件夹\n\n```\n用户: 在网盘里创建一个 projects 文件夹\nAI: [执行 bdpan mkdir projects]\n\n    已创建文件夹: projects\n```\n\n### 示例 24: 组合操作——创建目录并移动文件\n\n```\n用户: 帮我在网盘里创建一个 archive/2026 目录，然后把 old-report.pdf 移动过去\nAI: [执行 bdpan mkdir archive/2026]\n    已创建文件夹: archive/2026\n\n    [执行 bdpan mv old-report.pdf archive/2026]\n    已移动 old-report.pdf -> archive/2026\n```\n\n---\n\n## 高级用法\n\n### 示例 12: 批量上传\n\n```bash\n# 上传当前目录所有 PDF 文件\nfor f in *.pdf; do\n  bdpan upload \"$f\" \"documents/$f\"\ndone\n\n# 上传并记录结果\nfor f in *.pdf; do\n  echo \"上传 $f...\"\n  bdpan upload \"$f\" \"documents/$f\" --json | jq '.'\ndone\n```\n\n### 示例 13: 自动备份脚本\n\n```bash\n#!/bin/bash\n# 每日备份脚本\n\nDATE=$(date +%Y-%m-%d)\nBACKUP_FILE=\"backup-${DATE}.tar.gz\"\n\n# 打包\ntar -czf \"/tmp/${BACKUP_FILE}\" ~/important-data/\n\n# 上传\nbdpan upload \"/tmp/${BACKUP_FILE}\" \"backup/${BACKUP_FILE}\"\n\n# 清理\nrm \"/tmp/${BACKUP_FILE}\"\n\necho \"备份完成: ${BACKUP_FILE}\"\n```\n\n### 示例 14: 检查上传状态\n\n```bash\n# 检查文件是否已上传\ncheck_uploaded() {\n  local file=$1\n  bdpan ls --json | jq -e \".[] | select(.Name == \\\"${file}\\\")\" > /dev/null\n}\n\nif check_uploaded \"report.pdf\"; then\n  echo \"文件已存在\"\nelse\n  echo \"文件不存在，开始上传...\"\n  bdpan upload ./report.pdf report.pdf\nfi\n```\n\nFile v2.0.0:reference/notes.md\n\n# 开发笔记与注意事项\n\n本文档包含 Skill 开发阶段的注意事项和内部说明，**不面向最终用户**。\n\n---\n\n## BETA 阶段安全须知\n\n> **1.** 本工具处于公测期，仅供技术交流，请**备份**网盘重要数据。\n> **2.** AI Agent 行为不可预测，请**人工审核**每条指令。\n> **3.** 严禁在公用或不可信环境中扫码授权。使用完毕后执行 `bdpan logout` 清除授权。\n> **4.** 严格保护配置文件与 Token，切勿在公开仓库或对话中暴露。\n\n**首次使用时，向用户展示上述安全须知。**\n\n---\n\n## 内部实现说明\n\n### Agent 安全限制\n\n所有 Agent 安全约束（登录方式、Token 保护、更新控制、环境变量、路径安全）集中定义在 [SKILL.md](../SKILL.md) 的「安全约束」章节。此处不再重复，维护时以 SKILL.md 为准。\n\n### 授权码处理\n\n当用户在对话中发送一个 32 位十六进制字符串（正则：`^[a-fA-F0-9]{32}$`），处理规则详见 SKILL.md「授权码处理」章节。\n\nFile v2.0.0:reference/troubleshooting.md\n\n# 故障排除指南\n\n本指南涵盖了使用 bdpan CLI 时的常见问题和解决方案。\n\n---\n\n## 认证问题\n\n### Token 过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n### WebView 无法打开\n\n**症状：** 登录过程中浏览器或 WebView 窗口未出现。\n\n**解决方案：**\n工具会自动降级到 OOB（Out-of-Band）模式，按以下步骤操作：\n\n1. 复制控制台显示的授权链接：\n   ```\n   https://openapi.baidu.com/oauth/...?device_code=xxxxx\n   ```\n\n2. 在浏览器中打开该链接\n\n3. 完成授权后，浏览器会显示授权码\n\n4. 复制授权码并粘贴到命令行提示处\n\n5. 按回车确认\n\n**示例输出：**\n```\n请在浏览器中打开以下链接完成授权:\nhttps://openapi.baidu.com/oauth/2.0/authorize?response_type=device_code&client_id=...&device_code=xxxxx\n\n授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n[等待用户输入授权码...]\n```\n\n### 授权后登录失败\n\n**症状：** 授权页面完成但登录仍然失败。\n\n**解决方案：**\n```bash\n# 清除配置并重试\nrm ~/.config/bdpan/config.json\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n---\n\n## 文件操作问题\n\n### 路径不在允许范围\n\n**症状：**\n```\n错误: 路径不在允许范围内\nError: Path not in allowed range\n```\n\n**解决方案：**\n确保所有路径都在 `/apps/bdpan/` 目录下。\n\n错误：\n```bash\nbdpan ls /my-documents\nbdpan upload ./file.txt /other/file.txt\n```\n\n正确：\n```bash\nbdpan ls my-documents\nbdpan upload ./file.txt my-documents/file.txt\n```\n\n### 使用中文路径导致下载/上传失败\n\n**症状：**\n```\n错误: 文件不存在\n# 实际原因：使用了 \"/我的应用数据/bdpan/...\" 而不是 \"/apps/bdpan/...\"\n```\n\n**说明：**\n百度网盘界面中显示的 **\"我的应用数据\"** 是中文显示名，对应的 API 实际路径是 **`/apps`**。两个方向都需要映射：\n- **调用命令时**：中文路径 → API 路径（`我的应用数据` → `/apps`）\n- **展示给用户时**：API 路径 → 中文路径（`/apps` → `我的应用数据`）\n\n**路径映射：**\n| 用户可见名称 | API 实际路径 |\n|-------------|-------------|\n| 我的应用数据 | `/apps` |\n| 我的应用数据/bdpan | `/apps/bdpan` |\n\n**解决方案：**\n调用命令时使用相对路径或英文 API 绝对路径，展示给用户时转换为中文名：\n\n```bash\n# ✅ 命令中使用 API 路径\nbdpan download report.pdf ./report.pdf\n\n# ✅ 展示给用户时使用中文名\n# \"文件已上传到：我的应用数据/bdpan/report.pdf\"\n\n# ❌ 命令中使用中文路径\nbdpan download /我的应用数据/bdpan/report.pdf ./report.pdf\n\n# ❌ 展示给用户时暴露 API 路径\n# \"文件已上传到：/apps/bdpan/report.pdf\"\n```\n\n### 文件不存在\n\n**症状：**\n```\n错误: 文件不存在\nError: File not found\n```\n\n**解决方案：**\n1. 检查本地文件是否存在：\n   ```bash\n   ls -la <本地路径>\n   ```\n2. 检查远程文件是否存在：\n   ```bash\n   bdpan ls\n   ```\n\n### 上传/下载超时\n\n**症状：** 操作耗时过长并超时。\n\n**解决方案：**\n1. 大文件可能需要最多 30 分钟\n2. 检查网络连接稳定性\n3. 对于非常大的文件，考虑先压缩/分割：\n   ```bash\n   # 上传前压缩\n   tar -czf archive.tar.gz large-folder/\n   bdpan upload archive.tar.gz backup/archive.tar.gz\n   ```\n\n### 转存失败\n\n**症状：**\n```\n错误: 转存失败\nError: Transfer failed\n```\n\n**常见原因及解决方案：**\n\n1. **分享链接已失效**：联系分享者重新生成链接\n2. **提取码错误**：确认提取码是否正确\n   ```bash\n   # 提取码通过 -p 传入\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n   # 或包含在链接中\n   bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n   ```\n3. **网盘空间不足**：清理网盘空间后重试\n\n#### 错误码 errno=13045（自己的分享链接）\n\n**症状：**\n```\n转存失败: errno=13045, msg=prohibit transfer self share link\n```\n\n**原因：**\n这是您自己创建并分享的链接，文件\n\nArchive v1.2.2: 11 files, 30564 bytes\n\nFiles: reference/authentication.md (3238b), reference/bdpan-commands.md (14765b), reference/examples.md (7736b), reference/notes.md (1814b), reference/troubleshooting.md (7178b), scripts/install.sh (8876b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (14632b), _meta.json (140b)\n\nArchive v1.2.1: 11 files, 31194 bytes\n\nFiles: reference/authentication.md (3238b), reference/bdpan-commands.md (14765b), reference/examples.md (7736b), reference/notes.md (1814b), reference/troubleshooting.md (7178b), scripts/install.sh (10879b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (14933b), _meta.json (140b)\n\nArchive v1.2.0: 11 files, 31192 bytes\n\nFiles: reference/authentication.md (3238b), reference/bdpan-commands.md (14765b), reference/examples.md (7736b), reference/notes.md (1814b), reference/troubleshooting.md (7178b), scripts/install.sh (10879b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (14933b), _meta.json (140b)\n\nArchive v1.0.0: 11 files, 31153 bytes\n\nFiles: reference/authentication.md (3238b), reference/bdpan-commands.md (14765b), reference/examples.md (7736b), reference/notes.md (1814b), reference/troubleshooting.md (7178b), scripts/install.sh (10879b), scripts/login.sh (7084b), scripts/uninstall.sh (4349b), scripts/update.sh (9000b), SKILL.md (14791b), _meta.json (140b)","readmeExcerpt":"Skill: Baidu Drive Owner: may-yaha Summary: 百度网盘(Baidu Drive)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。 TRIGGER: 用户提及\"百度网盘/bdpan/网盘/云盘/baidu drive/Baidu Drive\"并涉及文件操作。 DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时。 Tags: latest:1.4.3 Version history: v1.4.3 | 2026-04-16T10:15:00.365Z | user refactor(skill): 统一英文名 baidu netdisk → baidu drive，移除公测标识 v1.4.0 | 2026-04-09T10:39:20.439Z | user feat(skill): 修复常见 bug v1.3.0 | 2026-03-27T10","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"bdpan whoami"},{"language":"bash","snippet":"bdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]"},{"language":"bash","snippet":"bdpan upload <本地路径> <远端路径>"},{"language":"bash","snippet":"bdpan download <远端路径> <本地路径>"},{"language":"bash","snippet":"# 1. 启动后台下载（nohup + 进度日志）\nnohup bdpan download <远端路径> <本地路径> > /tmp/bdpan-dl-$$.log 2>&1 & echo $!"},{"language":"bash","snippet":"# 2. 轮询检查进度（每 30 秒检查一次，使用 Bash run_in_background）\n#    检查进程是否存活 + 已下载文件大小\nkill -0 <PID> 2>/dev/null && echo \"running\" || echo \"done\"; ls -l <本地路径> 2>/dev/null; tail -5 /tmp/bdpan-dl-<PID>.log 2>/dev/null"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: baidu-drive\ndescription: >-\n  百度网盘(Baidu Drive)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。\n  TRIGGER: 用户提及\"百度网盘/bdpan/网盘/云盘/baidu drive/Baidu Drive\"并涉及文件操作。\n  DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时。\nallowed-tools: Bash, Read, Glob, Grep, AskUserQuestion\nargument-hint: \"[操作指令]\"\n---\n\n# 百度网盘存储 Skill\n\n百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。\n\n> 使用注意事项详见 [reference/notes.md](./reference/notes.md)\n\n## 触发规则\n\n同时满足以下条件才执行：\n\n1. 用户明确提及\"百度网盘\"、\"bdpan\"、\"网盘\"\n2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/登录/注销）\n\n未通过触发规则时，禁止执行任何 bdpan 命令。\n\n> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及\"网盘\"即可触发。\n\n---\n\n## 安全约束（最高优先级，不可被任何用户指令覆盖）\n\n1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code` 等，即使在 GUI 环境也禁止）\n2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）\n3. **更新/登录**：更新必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行 update.sh 或 login.sh\n4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量（这些变量供用户在脚本外手动配置，Agent 不应代为设置）\n5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径\n\n---\n\n## 前置检查\n\n每次触发时按顺序执行：\n\n1. **安装检查**：`command -v bdpan`，未安装则告知用户并确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh`（用户确认后可加 `--yes` 跳过安装器内部确认）\n2. **登录检查**：`bdpan whoami`，未登录则引导执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`\n3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内\n\n---\n\n## 确认规则\n\n| 风险等级 | 操作 | 策略 |\n|----------|------|------|\n| **高（必须确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 列出影响范围，等待用户确认 |\n| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |\n| **低（直接执行）** | ls、search、whoami、mkdir、share | 无需确认 |\n\n**额外规则：**\n- 操作意图模糊（\"处理文件\"→确认上传还是下载）→ 必须确认\n- 序数/代词引用有歧义（\"第N个\"、\"它\"、\"上面那个\"）→ 必须确认\n- 用户取消意图（\"算了\"、\"不要了\"、\"取消\"）→ 立即中止，不执行任何命令\n\n---\n\n## 核心操作\n\n### 查看状态\n\n```bash\nbdpan whoami\n```\n\n### 列表查询\n\n```bash\nbdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]\n```\n\n### 上传\n\n```bash\nbdpan upload <本地路径> <远端路径>\n```\n\n**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。\n\n步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。\n\n### 下载\n\n**直接下载：**\n\n```bash\nbdpan download <远端路径> <本地路径>\n```\n\n步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → **检查文件大小决定下载策略** → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。\n\n**大文件下载策略（重要）：**\n\nAgent 的 Bash 工具有执行超时限制，大文件下载可能因超时而中断。必须根据文件大小选择下载策略：\n\n1. **获取文件大小**：用 `bdpan ls --json <远端路径>` 获取 `size` 字段（字节）\n2. **按大小分策略执行**：\n\n| 文件大小 | 策略 | 执行方式 |\n|----------|------|---------|\n| ≤ 50MB | 直接下载 | `bdpan download <远端路径> <本地路径>`，Bash timeout 设为 300000（5 分钟） |\n| > 50MB | 后台下载 | 使用 `nohup` 后台执行，Agent 轮询进度 |\n\n**小文件（≤ 50MB）直接下载：**\n\n正常执行 `bdpan download`，Bash 工具 timeout 参数设为 `300000`（5 分钟）。\n\n**大文件（> 50MB）后台下载流程：**\n\n```bash\n# 1. 启动后台下载（nohup + 进度日志）\nnohup bdpan download <远端路径> <本地路径> > /tmp/bdpan-dl-$$.log 2>&1 & echo $!\n```\n\n```bash\n# 2. 轮询检查进度（每 30 秒检查一次，使用 Bash run_in_background）\n#    检查进程是否存活 + 已下载文件大小\nkill -0 <PID> 2>/dev/null && echo \"running\" || echo \"done\"; ls -l <本地路径> 2>/dev/null; tail -5 /tmp/bdpan-dl-<PID>.log 2>/dev/null\n```\n\n```bash\n# 3. 下"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn732m45det8fggw8x5d7mv9jx80w2q0\",\n  \"slug\": \"baidu-netdisk-storage\",\n  \"version\": \"1.4.3\",\n  \"publishedAt\": 1776334500365\n}"},{"path":"reference/authentication.md","content":"# 认证指南\n\n本指南详细介绍 bdpan CLI 的登录认证流程。\n\n---\n\n## 登录方式\n\n> **安全约束：** 登录方式的安全限制详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。Agent 必须且只能通过 login.sh 脚本执行登录。\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本会自动处理完整的登录流程（免责声明 → 用户确认 → 获取授权链接 → 校验授权码 → 完成登录）。\n\n---\n\n## 验证登录状态\n\n```bash\nbdpan whoami\n```\n\n**已登录时输出：**\n```\n认证状态: 已登录\nToken 有效期至: 2026-03-10 10:30:00\n```\n\n**未登录时输出：**\n```\n认证状态: 未登录\n请执行 bdpan login 进行登录\n```\n\n---\n\n## 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n---\n\n## 常见问题\n\n### 登录后提示 Token 已过期\n\n**症状：**\n```\n错误: Token 过期\nError: Token expired\n```\n\n**解决方案：**\n```bash\nbdpan logout\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n### 授权链接无效\n\n**症状：** 浏览器打开链接后提示链接无效\n\n**解决方案：**\n1. 重新执行登录脚本获取新的授权链接\n2. 确保在链接有效期内完成授权（通常 10 分钟）\n\n### 授权码输入后报错\n\n**症状：** 输入授权码后提示错误\n\n**解决方案：**\n1. 确保授权码复制完整，没有多余空格\n2. 检查浏览器中显示的授权码是否与输入的一致\n3. 如多次失败，重新执行登录脚本获取新授权码\n\n---\n\n## 配置文件位置\n\n```\n~/.config/bdpan/config.json\n```\n\n**环境变量：**\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n---\n\n## 安全说明\n\n- **OAuth 2.0**：使用授权码模式，不存储用户密码\n- **Token 存储**：Token 加密存储在本地配置文件\n- **自动续期**：Token 快过期时工具会自动刷新\n\n---\n\n## 自动登录失败场景\n\n以下场景会自动切换到 OOB 模式：\n\n| 场景 | 说明 |\n|------|------|\n| SSH 远程登录 | 无图形界面 |\n| WSL 环境 | WebView 支持受限 |\n| 桌面环境锁定 | WebView 无法弹出 |\n| 浏览器未安装 | 无法打开 WebView |\n\n切换到 OOB 模式时，工具会自动提示授权链接，无需用户干预。"},{"path":"reference/bdpan-commands.md","content":"# bdpan CLI 命令快速参考\n\n## 认证命令\n\n### login - 登录授权\n\n> **⛔ Agent 必须通过登录脚本执行登录，禁止直接调用 `bdpan login`。详见 [SKILL.md](../SKILL.md) 安全约束。**\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/login.sh\n```\n\n脚本内置了安全免责声明和完整的 OOB 授权流程。无论 GUI 或非 GUI 环境，统一使用此脚本。\n\n### logout - 注销登录\n\n```bash\nbdpan logout\n```\n\n清除本地存储的认证信息（`~/.config/bdpan/config.json`）。\n\n### uninstall - 完全卸载\n\n```bash\nbash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh\n```\n\n完全卸载 bdpan CLI，自动执行以下操作：\n1. 注销登录并清除授权信息\n2. 删除配置目录（`~/.config/bdpan/`）\n3. 删除 bdpan 二进制文件（`~/.local/bin/bdpan`）\n\n**选项：**\n- `--yes, -y` - 跳过确认提示（自动化场景）\n\n**环境变量：**\n| 环境变量 | 说明 | 默认值 |\n|---------|------|--------|\n| `BDPAN_INSTALL_DIR` | 二进制安装目录 | `~/.local/bin` |\n| `BDPAN_CONFIG_DIR` | 配置文件目录 | `~/.config/bdpan` |\n\n### whoami - 查看认证状态\n\n```bash\nbdpan whoami\n```\n\n显示当前登录状态、用户名和 Token 有效期信息。\n\n**已登录时输出：**\n```\n认证状态: 已登录\n用户名: your_username\nToken 有效期至: 2026-04-04 10:30:00\n```\n\n**选项：**\n- `--json` - JSON 格式输出\n\n---\n\n## 文件操作命令\n\n### upload - 上传文件\n\n```bash\nbdpan upload <local> <remote>\n```\n\n| 参数 | 说明 |\n|------|------|\n| `local` | 本地文件或文件夹路径 |\n| `remote` | 网盘目标路径（相对于 `/apps/bdpan/`） |\n\n**示例：**\n```bash\n# 单文件上传\nbdpan upload ./report.pdf report.pdf\n\n# 文件夹上传\nbdpan upload ./project/ project/\n\n# 上传到子目录\nbdpan upload ./data.tar.gz backup/data.tar.gz\n```\n\n**选项：**\n- `--json` - JSON 格式输出上传结果\n\n### download - 下载文件\n\n```bash\nbdpan download <remote> <local> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `remote` | 网盘文件/文件夹路径（相对于 `/apps/bdpan/`）**或**百度网盘分享链接 |\n| `local` | 本地保存路径 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（用于分享链接，如果链接中未包含） |\n| `-t` | 自定义转存目录（相对路径自动拼接 `/apps/bdpan`，绝对路径直接使用） |\n| `--json` | JSON 格式输出下载结果 |\n\n**示例：**\n```bash\n# 单文件下载\nbdpan download report.pdf ./downloaded-report.pdf\n\n# 文件夹下载\nbdpan download project/ ./project-restore/\n\n# 从分享链接下载（链接中包含提取码）\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/\n\n# 使用 -p 参数单独传入提取码\nbdpan download \"https://pan.baidu.com/s/1xxxxx\" ./downloaded/ -p abcd\n\n# 使用 -t 参数自定义转存目录\nbdpan download \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\" ./downloaded/ -t my-folder\n```\n\n**分享链接下载说明：**\n- 自动识别分享链接格式 `https://pan.baidu.com/s/1{surl}?pwd={pwd}`\n- 分享文件会先转存到 `/apps/bdpan/{日期}/` 目录（或使用 `-t` 指定的目录）\n- 然后下载到指定的本地路径\n\n### transfer - 转存分享文件到网盘（不下载到本地）\n\n```bash\nbdpan transfer <分享链接> [选项]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `分享链接` | 百度网盘分享链接 |\n\n**选项：**\n| 选项 | 说明 |\n|------|------|\n| `-p` | 提取码（如果链接中未包含） |\n| `-d` | 目标目录（相对路径自动拼接 `/apps/bdpan`，默认为应用根目录） |\n| `--json` | JSON 格式输出转存结果 |\n\n**示例：**\n```bash\n# 基本用法 - 转存到应用根目录 /apps/bdpan/\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd\n\n# 提取码在链接中\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"\n\n# 指定目标目录\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd -d my-folder/\n\n# JSON 输出\nbdpan transfer \"https://pan.baidu.com/s/1xxxxx\" -p abcd --json\n```\n\n**与 download 的区别：**\n- `transfer` 仅将分享文件转存到自己的网盘，不下载到本地\n- `download` 会先转存再下载到本地路径\n- 适用于只需要保存到网盘、不需要本地副本的场景\n\n### ls - 查看文件列表\n\n```bash\nbdpan ls [path]\n```\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `path` | 要查看的目录路径 | 根目录 |\n\n**选项：**\n- `--js"},{"path":"reference/examples.md","content":"# 使用示例\n\n本文档包含 baidu drive 的详细使用示例。\n\n---\n\n## 上传并分享\n\n### 示例 1: 上传并分享单个文件\n\n```\n用户: 帮我上传并分享 ./report.pdf\nAI: [执行 bdpan upload ./report.pdf report.pdf]\n    [执行 bdpan share report.pdf]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: abcd\n    有效期: 7 天\n```\n\n### 示例 2: 上传并分享文件夹\n\n```\n用户: 把 ./project 文件夹上传并分享\nAI: [执行 bdpan upload ./project/ project/]\n    [执行 bdpan share project]\n\n    文件夹上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: efgh\n    有效期: 7 天\n```\n\n### 示例 3: 上传到子目录\n\n```\n用户: 上传 ./data.tar.gz 到 backup 目录并分享\nAI: [执行 bdpan upload ./data.tar.gz backup/data.tar.gz]\n    [执行 bdpan share backup/data.tar.gz]\n\n    上传并分享成功！\n    链接: https://pan.baidu.com/s/1xxxxxxx\n    提取码: ijkl\n    有效期: 7 天\n```\n\n---\n\n## 下载文件\n\n### 示例 4: 下载单个文件\n\n```\n用户: 从网盘下载 report.pdf\nAI: [执行 bdpan download report.pdf ./report.pdf]\n\n    正在下载 report.pdf → ./report.pdf ...\n    ✓ 下载成功\n```\n\n### 示例 5: 下载文件夹\n\n```\n用户: 把 backup 文件夹下载到本地\nAI: [执行 bdpan download backup/ ./backup/]\n\n    正在下载 backup/ → ./backup/ ...\n    ✓ 下载成功\n```\n\n---\n\n## 文件列表\n\n### 示例 6: 查看已上传文件\n\n```\n用户: 查看我上传了哪些文件\nAI: [执行 bdpan ls]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    目录     -            2026-02-20 10:30:00  backup\n    文件    1.5 MB        2026-02-25 15:20:00  report.pdf\n    文件    256 KB        2026-02-24 09:15:00  config.yaml\n\n    共 3 项\n```\n\n### 示例 7: 查看子目录\n\n```\n用户: 查看 backup 目录下的文件\nAI: [执行 bdpan ls backup]\n\n    类型    大小          修改时间              文件名\n    ------  ------------  --------------------  --------\n    文件    2.1 GB        2026-02-19 08:00:00  data-2026-02-19.tar.gz\n    文件    1.8 GB        2026-02-18 08:00:00  data-2026-02-18.tar.gz\n\n    共 2 项\n```\n\n---\n\n## JSON 输出（用于脚本）\n\n### 示例 8: JSON 格式文件列表\n\n```\n用户: 列出所有文件名（JSON 格式）\nAI: [执行 bdpan ls --json]\n\n    输出:\n    [\n      {\n        \"Name\": \"report.pdf\",\n        \"IsDir\": false,\n        \"Size\": 1536000,\n        \"Modified\": \"2026-02-25T15:20:00Z\"\n      },\n      {\n        \"Name\": \"backup\",\n        \"IsDir\": true,\n        \"Size\": 0,\n        \"Modified\": \"2026-02-20T10:30:00Z\"\n      }\n    ]\n```\n\n### 示例 9: 使用 jq 处理输出\n\n```bash\n# 提取所有文件名\nbdpan ls --json | jq -r '.[].Name'\n\n# 只列出文件（排除目录）\nbdpan ls --json | jq '.[] | select(.IsDir == false)'\n\n# 按大小排序\nbdpan ls --json | jq 'sort_by(.Size) | reverse'\n\n# 检查文件是否存在\nbdpan ls --json | jq -e '.[] | select(.Name == \"target.txt\")'\n```\n\n---\n\n## 认证流程\n\n### 示例 10: 登录（统一使用 login.sh 脚本）\n\n> 登录安全约束详见 [SKILL.md](../SKILL.md) 的「安全约束」章节。\n\n```\n用户: 帮我登录百度网盘\nAI: [执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh]\n\n    [展示安全免责声明]\n    已阅读上述安全须知，确认继续登录? [y/N]\n\n用户: y\nAI: 正在获取授权链接...\n\n    请在浏览器中打开以下链接完成授权:\n    https://openapi.baidu.com/oauth/2.0/authorize?...\n\n    授权成功后，浏览器会显示授权码，请复制并粘贴到这里:\n    [等待用户输入...]\n\n用户: [粘贴授权码] ca0ee3070f75d0246357e5c74d525bda\nAI: [处理授权码]\n\n    ✓ 登录成功！\n    用户: username@baidu.com\n```\n\n---\n\n## 转存分享文件到网盘\n\n### 示例 15: 转存分享链接（提取码在链接中）\n\n```\n用户: 帮我把这个链接转存到网盘 https://pan.baidu.com/s/1xxxxx?pwd=abcd\nAI: [执行 bdpan transfer \"https://pan.baidu.com/s/1xxxxx?pwd=abcd\"]\n\n    ✓ 转存成功！\n   "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":971,"uniquenessScore":39,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T06:35:35.991Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:16:01.814Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}