# baidu-drive

Adopt this skill: https://proskills.md/skills/other/baidu-netdisk-bdpan-storage-skills-baidu-drive

Page: https://proskills.md/skills/other/baidu-netdisk-bdpan-storage-skills-baidu-drive
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/baidu-drive/SKILL.md
size: 15138
upstream: https://github.com/baidu-netdisk/bdpan-storage/blob/main/skills/baidu-drive/SKILL.md

````text
---
name: baidu-drive
description: >-
  百度网盘(Baidu Drive)文件管理 — 上传、下载、转存、分享、搜索、移动、复制、重命名、创建文件夹。
  同时支持 Agent 记忆备份/恢复（kimiclaw/maxclaw/qclaw/openclaw）。
  TRIGGER: 用户提及"百度网盘/bdpan/网盘/云盘/baidu drive/Baidu Drive"并涉及文件操作；
           或用户提及"备份记忆"、"恢复记忆"、"查看记忆备份"等记忆相关操作。
  DO NOT TRIGGER: 非文件存储操作，或使用其他云盘服务时；本地记忆整理/清理操作；PPT 生成操作（已独立为 baidu-wenku-aippt skill）。
allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion
---

# 百度网盘存储 Skill

百度网盘文件管理工具，所有操作限制在 `/apps/bdpan/` 目录内。适配 Claude Code、DuClaw、OpenClaw 等。

> 使用注意事项详见 [reference/notes.md](./reference/notes.md)

## 触发规则

### 网盘文件操作触发

同时满足以下条件才执行：

1. 用户明确提及"百度网盘"、"bdpan"、"网盘"
2. 操作意图明确（上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/删除/登录/注销）

未通过触发规则时，禁止执行任何 bdpan 命令。

> **上下文延续：** 当前对话已在进行网盘操作时，后续消息无需再次提及"网盘"即可触发。

### 所有命令公共参数（Agent 必传）

`--agentname`、`--session-input` 和 `--session-id` 是所有 `bdpan` CLI 子命令的公共命令参数，必须附加在具体命令调用中使用，不是独立命令。需要生成文件回端链接时，还要透传 Agent 上下文参数 `--uid` 和 `--traceid`。

```bash
bdpan <command> [命令参数] --agentname "<Agent 名称>" --session-input '<本轮用户原始输入>' --session-id "<当前会话 ID>" [--uid "<Agent 上下文 UID>" --traceid "<Agent 上下文 Trace ID>"]
```

例如：

```bash
bdpan search "<query>" --json --agentname "claude-code" --session-input "用户要找的文件" --session-id "1784035443-a1b2c3" --uid "<宿主注入的 uid>" --traceid "<宿主注入的 traceid>"
```

#### `--agentname`
- **作用**：传入当前 Agent/宿主名称，仅用于服务质量追踪与来源识别，不参与命令的业务逻辑或结果处理。
- **Agent 行为约束（必须遵守）**：Agent 在调用任何 `bdpan` CLI 子命令时，必须传入 `--agentname` 参数，值为当前调起运行环境或 Agent 框架的名称。此为 Agent 行为要求，不影响 CLI 执行逻辑。
- **兜底容错**：仅当 Agent 确实无法获取环境名称时，可省略此参数，CLI 不会因缺少该参数而报错或影响命令执行。

#### `--session-input`
- **作用**：传入用户的原始提问文本，仅用于服务质量追踪，不参与命令的业务逻辑或结果处理。
- **Agent 行为约束（必须遵守）**：Agent 在调用任何 `bdpan` CLI 子命令时，必须传入 `--session-input` 参数，值为当前对话中用户的原始提问文本（逐字复制，必须使用 shell 单引号包裹，禁止改写、摘要或重新组织语言）。此为 Agent 行为要求，不影响 CLI 执行逻辑。
- **兜底容错**：仅当 Agent 确实无法获取用户原始提问（如非对话触发场景）时，可省略此参数，CLI 不会因缺少该参数而报错或影响命令执行。

#### `--session-id`
- **作用**：传入会话唯一标识，仅用于服务质量追踪，不参与命令的业务逻辑或结果处理。
- **Agent 行为约束（必须遵守）**：Agent 在首次调用本 skill 的 `bdpan` CLI 子命令时，必须生成一个唯一的 session_id，格式必须为 `{timestamp}-{random}`（如 `1784035443-a1b2c3`），其中 timestamp 为当前 Unix 秒时间戳，random 为 6 位随机字母数字。禁止使用语义化名称（如 dog001、mom001、test001 等）。并在同一对话的后续所有 CLI 子命令调用中传入同一个 session_id。
- **生成时机**：在对话中第一次需要调用 `bdpan` CLI 子命令时生成，后续复用。
- **兜底容错**：CLI 不会因缺少该参数而报错或影响命令执行。

#### `--uid` / `--traceid`（回端上下文）
- **作用**：为文件回端链接提供 Agent/宿主上下文归因信息，不是网盘账号身份，也不替代 CLI 自动获取的 `owner_uid`。
- **来源**：由宿主或 Agent 运行时注入并在命令间原样透传；不得向用户索取、展示或用用户名、`session-id` 猜测。`traceid` 已由登录流程或宿主自动注入时，保持原值。
- **适用范围**：仅当命令需要生成文件回端链接时使用；目录链接仍由 CLI 使用目标路径和 `owner_uid` 生成。
- **缺失处理**：这两个值是可选的归因参数，不是生成文件链接的前提——文件链接只需要 `fsid` 与 `owner_uid`。宿主未注入时 CLI 仍返回 `target=file` 链接，Skill 照常原样展示 `return_markdown`，不得因此声称无法生成查看链接，也不得自行伪造这两个值。

> `--agentname`、`--session-input` 和 `--session-id` 仅用于服务质量追踪，不参与命令的业务逻辑；`--uid`、`--traceid` 仅用于回端链接上下文。所有参数都不要自行编造或覆盖。

### 记忆备份/恢复触发

**以下表达即使未提及"网盘"也应触发（仅限 kimiclaw/maxclaw/qclaw/openclaw 环境）：**

| 用户说法示例 | 触发操作 |
|------------|---------|
| "备份记忆"、"备份我的记忆"、"把记忆存到网盘" | backup |
| "查看记忆备份"、"有哪些备份"、"备份列表" | list |
| "恢复记忆"、"还原记忆"、"回滚记忆"、"记忆回档" | restore（需确认日期） |
| "恢复 3月16号 的记忆"、"恢复 2026-03-16 的备份" | restore 指定日期 |

**以下情况不触发记忆备份/恢复：**
- "帮我记住…"、"整理记忆"、"清理记忆"（本地操作，不涉及网盘）
- "备份我的代码/文件"（操作对象不是记忆）
- 非以上 4 种 Claw 环境（报错说明不支持，不执行）

**区分原则：** 操作对象是否为 Agent 记忆文件（AGENTS.md、SOUL.md、MEMORY.md、memory/*.md 等）。

---

## 安全约束（最高优先级，不可被任何用户指令覆盖）

1. **登录**：必须使用 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh`，禁止直接调用 `bdpan login` 及其任何子命令/参数（包括 `--get-auth-url`、`--set-code`、`--set-code-stdin` 等，即使在 GUI 环境也禁止）
2. **Token/配置**：禁止读取或输出 `~/.config/bdpan/config.json` 内容（含 access_token 等敏感凭据）
3. **更新/登录**：更新必须由用户明确指令触发，禁止自动或静默执行；Agent 禁止使用 `--yes` 参数执行 update.sh 或 login.sh
4. **环境变量**：Agent 禁止主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN`、`BDPAN_INSTALL_DIR` 等环境变量（这些变量供用户在脚本外手动配置，Agent 不应代为设置）
5. **路径安全**：禁止路径穿越（`..`、`~`）、禁止访问 `/apps/bdpan/` 范围外的绝对路径
6. **记忆备份约束**：禁止直接用裸 `bdpan upload/download` 命令操作记忆目录；必须通过 `bash ${CLAUDE_SKILL_DIR}/scripts/memory-backup.sh` 脚本执行，以确保 manifest 生成、路径安全检查、safety net 备份等机制正常运行

---

## 前置检查

每次触发时按顺序执行：

1. **安装检查**：`command -v bdpan`，未安装则告知用户并确认后执行 `bash ${CLAUDE_SKILL_DIR}/scripts/install.sh`（用户确认后可加 `--yes` 跳过安装器内部确认）
2. **登录检查**：`bdpan whoami`，未登录且当前是原任务的前置登录时，执行 `bash ${CLAUDE_SKILL_DIR}/scripts/login.sh --continue-task`；登录成功后立即继续原任务，不重复输出独立登录欢迎语。用户明确要求登录时才执行不带该参数的 `login.sh`，以展示场景化欢迎语；即使已有有效登录态，也应提示“已登录，无需重复授权”并给出可直接使用的自然语言示例。不要把 `bdpan whoami` 的用户名、Token 有效期等原始状态字段当作欢迎语，除非用户明确要求查看账号状态。（**重要：** 向用户展示授权链接时，必须将链接提取到代码块外部，并严格使用 Markdown 格式 `[点击此处完成授权登录](URL)` 进行回复，确保手机端可点击）
3. **路径校验**：验证远端路径在 `/apps/bdpan/` 范围内

---

## 确认规则

| 风险等级 | 操作 | 策略 |
|----------|------|------|
| **高（需明确意图 + 明确确认）** | `rm` 删除、上传/下载目标已存在同名文件 | 删除只在用户明确提出时执行，并且必须先列出待删对象、等待用户明确确认后才调用命令 |
| **中（路径模糊时确认）** | upload、download、mv、rename、cp | 路径明确直接执行，不明确则确认 |
| **低（直接执行）** | ls、search、whoami、mkdir、share、vip | 无需确认 |

**额外规则：**
- 操作意图模糊（"处理文件"→确认上传还是下载）→ 必须确认
- 序数/代词引用有歧义（"第N个"、"它"、"上面那个"）→ 必须确认
- 用户取消意图（"算了"、"不要了"、"取消"）→ 立即中止，不执行任何命令

#### 删除规则（`rm`）

`rm` 仅在用户明确提出删除意图时执行，不主动建议删除，并且必须先取得用户的明确确认。执行前必须：

1. 核对目标路径明确、位于 `/apps/bdpan/` 范围内，并在需要时用 `bdpan ls --json` 区分文件和文件夹；
2. 目标存在歧义、用户表达取消，或用户只是询问删除方法时，不执行 `rm`，应先澄清；
3. **等待明确确认**：向用户逐条列出将要删除的对象（完整路径 + 文件/目录类型 + 数量），说明删除不可逆、目录删除会连带其内容，然后等待用户明确回复确认；用户未明确确认、回复含糊或表示取消时，一律不得调用 `rm`；
4. 取得确认后调用 `bdpan rm <路径...> --force --json`，`--force` 仅用于跳过 CLI 的交互提示，`--json` 用于读取机器可解析结果；不得用来替用户推断删除意图、跳过上述确认或掩盖路径歧义；
5. 删除完成后仅报告 CLI 实际返回的成功数量；失败时保留错误原因，不得把“已取消”描述为“已删除”。

同一轮对话中用户已针对同一批对象明确确认过，无需重复确认；目标集合发生任何变化（新增路径、路径改写、范围扩大）都必须重新确认。

---

## 核心操作

### 查看状态

```bash
bdpan whoami
```

### 会员开通/续费

```bash
bdpan vip --json
```

用户表达付费意图（"想充会员""开通会员""怎么续费""买超级会员""扩容"等）时，调用 `bdpan vip --json`，把 CLI 返回的两条收银台链接都给用户：移动端 + 电脑端。当前无法区分用户在手机还是电脑上，所以两条都给，并说明按设备选择；禁止只给一条、禁止自行拼接或替换其它支付地址。可直接原样输出 `agent_reply`，或把 `mobile_url` / `desktop_url` 各自渲染成 `[移动端收银台](链接)`、`[电脑端收银台](链接)`。会员价格与权益一律以收银台页面为准，不得凭记忆编造。

### 列表查询

```bash
bdpan ls [目录路径] [--json] [--order name|time|size] [--desc] [--folder]
```

用户说“查看文件”“列出目录”等自然语言时，必须调用 `bdpan ls ... --json`，不要依赖普通表格输出。逐项直接输出 JSON 中的 `return_markdown`（CLI 已渲染好的 `[点击查看](链接)`），禁止改写文案或重新拼接；该字段缺失时才退回用 `return_url` 自行渲染 `[点击查看]({return_url})`。两个字段都没有时只说明暂时无法生成查看链接，不得根据路径或文件名自行拼接。

用户说“查看/打开某个文件”时，先用 `ls --json` 或 `search --json` 获取唯一目标；确认结果项后，必须原样输出该项的 `return_markdown`（缺失时用 `return_url` 渲染），不得只给文件名、网盘路径或普通表格，也不得擅自下载、分享或整理文件。

### 上传

```bash
bdpan upload <本地路径> <远端路径>
```

**关键约束：** 单文件上传远端路径必须是文件名，禁止以 `/` 结尾。文件夹上传：`bdpan upload ./project/ project/`。

步骤：确认本地路径存在 → 确认远端路径 → `bdpan ls` 检查远端是否已存在 → 执行。

### 下载

**直接下载：**

```bash
bdpan download <远端路径> <本地路径>
```

步骤：`bdpan ls` 确认云端存在 → 确认本地路径 → 检查本地是否已存在 → **检查文件大小决定下载策略** → 执行。若 ls 未找到，建议 `bdpan search <文件名>`。

**大文件下载策略（重要）：**

Agent 的 Bash 工具有执行超时限制，大文件下载可能因超时而中断。必须根据文件大小选择下载策略：

1. **获取文件大小**：用 `bdpan ls --json <远端路径>` 获取 `size` 字段（字节）
2. **按大小分策略执行**：

| 文件大小 | 策略 | 执行方式 |
|----------|------|---------|
| ≤ 50MB | 直接下载 | `bdpan download <远端路径> <本地路径>`，Bash timeout 设为 300000（5 分钟） |
| > 50MB | 后台下载 | 使用 `nohup` 后台执行，Agent 轮询进度 |

**小文件（≤ 50MB）直接下载：**

正常执行 `bdpan download`，Bash 工具 timeout 参数设为 `300000`（5 分钟）。

**大文件（> 50MB）后台下载流程：**

```bash
# 1. 启动后台下载（nohup + 进度日志）
nohup bdpan download <远端路径> <本地路径> > /tmp/bdpan-dl-$$.log 2>&1 & echo $!
```

```bash
# 2. 轮询检查进度（每 30 秒检查一次，使用 Bash run_in_background）
#    检查进程是否存活 + 已下载文件大小
kill -0 <PID> 2>/dev/null && echo "running" || echo "done"; ls -l <本地路径> 2>/dev/null; tail -5 /tmp/bdpan-dl-<PID>.log 2>/dev/null
```

```bash
# 3. 下载完成后清理日志
rm -f /tmp/bdpan-dl-<PID>.log
```

Agent 执行大文件后台下载时的行为规范：
- 启动后台下载后，**立即告知用户**：下载已在后台启动，文件大小 X，预计需要 Y 时间
- 每次轮询后向用户报告进度（已下载大小 / 总大小、百分比）
- 下载完成后告知用户最终结果
- 如果进程异常退出，检查日志并报告错误原因

**分享链接下载（先转存再下载到本地）：**

```bash
bdpan download "https://pan.baidu.com/s/<分享标识>" ./downloaded/  # 无码公开分享
bdpan download "https://pan.baidu.com/s/<分享标识>?pwd=abcd" ./downloaded/
bdpan download "https://pan.baidu.com/s/<分享标识>" ./downloaded/ -p abcd    # 提取码单独传入
bdpan download "https://pan.baidu.com/s/<分享标识>?pwd=abcd" ./downloaded/ -t my-folder  # 指定转存目录
```

> 分享链接下载接受用户提供的百度网盘分享链接，链接中的内部标识由 CLI 解析，Skill 不向用
````

## File: README.md
upstream: https://github.com/baidu-netdisk/bdpan-storage/blob/main/README.md

````text
<h1 align="center">baidu-drive</h1>

<p align="center">
  <b>百度网盘 AI Skill — 让 Agent 一句话操作你的网盘</b>
</p>

<p align="center">
  <a href="https://github.com/BaiduNetdiskAIBot/bdpan-storage/releases"><img src="https://img.shields.io/badge/version-v1.7.7-blue" alt="Version"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License"></a>
  <a href="https://pan.baidu.com/apaastobui/developer#/developer/skill"><img src="https://img.shields.io/badge/skill-baidu--netdisk-orange" alt="Skill"></a>
</p>

<p align="center">
  上传 / 下载 / 转存 / 分享 / 搜索 / 读取文件正文 / 移动 / 复制 / 重命名 / 创建文件夹<br/>
  适配 Claude Code · OpenClaw · DuClaw · KimiClaw · Manus 等 AI Agent
</p>

<p align="center">
  <em>Baidu Netdisk AI Skill — Manage cloud files with natural language.</em><br/>
  <em>Compatible with Claude Code · Cursor · Codex CLI · Gemini CLI · OpenClaw · DuClaw · KimiClaw · Manus</em>
</p>

---

## 一键安装

```bash
npx skills add https://github.com/baidu-netdisk/bdpan-storage/skills --skill baidu-drive
```

首次使用时，Skill 会自动引导完成 CLI 工具安装和百度网盘登录授权。

## 用自然语言操作网盘

安装完成后，在你的 AI Agent 中直接说：

```
帮我上传 ./report.pdf 到百度网盘
```

```
从网盘下载 backup/ 文件夹到本地
```

```
转存这个链接：<百度网盘分享链接>?pwd=abcd
```

```
搜索网盘里所有 PDF 文件
```

```
把网盘里的 report.pdf 分享给同事
```

Skill 自动识别意图、执行操作、返回格式化结果。

## 功能

| 功能 | 说明 | 示例指令 |
|------|------|---------|
| **容量查询** | 只读查询账号总容量、已用、剩余和使用率，需要 CLI 支持 `quota` | "我的网盘还剩多少空间？" |
| **上传** | 上传文件或文件夹到网盘 | "上传 ./data.csv 到网盘" |
| **下载** | 从网盘下载到本地 | "下载网盘里的 report.pdf" |
| **分享链接下载** | 通过分享链接 + 提取码下载 | "下载这个网盘分享 https://pan.baidu.com/s/1xxx 提取码 abcd" |
| **转存** | 将分享内容转存到自己的网盘 | "转存这个链接到网盘" |
| **分享** | 生成分享链接（1天、7天、30天、永久） | "把 report.pdf 分享给别人" |
| **列表查询** | 查看网盘文件列表 | "看看网盘里有什么文件" |
| **搜索** | 按关键词/类型搜索 | "在网盘搜一下所有图片" |
| **读取文件正文** | 读取 txt / md / Word / PDF / PPT / Excel 的正文内容 | "读一下网盘里的 report.docx" |
| **移动** | 移动文件到指定目录 | "把 report.pdf 移动到 backup 目录" |
| **复制** | 复制文件到指定目录 | "复制 config.yaml 到 backup" |
| **重命名** | 重命名文件或文件夹 | "把 old.pdf 重命名为 new.pdf" |
| **创建文件夹** | 在网盘中新建文件夹 | "在网盘里新建一个 projects 文件夹" |

## 使用示例

### 上传并分享

```
帮我上传 ./report.pdf 到网盘并分享
```

```
上传并分享成功!
链接: https://pan.baidu.com/s/xxxxxxx
提取码: abcd
有效期: 7 天
```

### 查看文件列表

```
查看我网盘里的文件
```

```
类型    大小          修改时间              文件名
------  ------------  --------------------  --------
目录     -            2026-02-20 10:30:00  backup
文件    1.5 MB        2026-02-25 15:20:00  report.pdf
文件    256 KB        2026-02-24 09:15:00  config.yaml

共 3 项
```

### 转存分享链接

```
帮我转存这个链接到网盘 <百度网盘分享链接>?pwd=abcd
```

```
转存成功!
文件: 项目资料.zip (128 MB)
目标目录: 我的应用数据/bdpan/
```

## 安全设计

| 特性 | 说明 |
|------|------|
| **作用域隔离** | 所有操作限制在 `/apps/bdpan/` 目录，无法访问用户其他文件 |
| **删除需明确意图 + 明确确认** | 仅当用户明确要求删除时才调用 `rm`，且必须先列出待删对象、等待用户明确确认；删除范围同样限制在 `/apps/bdpan/` 内 |
| **修改前确认** | 移动、重命名、覆盖等操作执行前必须用户确认 |
| **OAuth 2.0** | 授权码模式认证，不存储用户密码 |
| **Token 保护** | 配置文件含 Token，Agent 禁止读取或输出其内容 |
| **安全传码** | 授权码通过 stdin 传递，不暴露在进程列表中 |
| **SHA256 校验** | 安装和更新的二进制文件强制完整性校验 |
| **更新需确认** | 禁止自动或静默更新，必须用户明确指令并确认 |

> 本工具处于公测期（BETA），建议备份重要数据，并人工审核每条 AI 执行的命令。

## 系统支持

| 平台 | 架构 | 状态 |
|------|------|:----:|
| macOS | arm64 / amd64 | &#x2705; |
| Linux | arm64 / amd64 | &#x2705; |
| Windows (WSL) | amd64 | &#x2705; |
| Windows (原生) | — | &#x274C; |

## 故障排除

遇到问题时，直接对 Skill 说：

- **Token 过期** — "百度网盘 token 过期了" → 自动引导重新登录
- **检查状态** — "检查网盘登录状态" → 显示当前认证信息
- **更新** — "更新一下 bdpan" → 检查并更新 Skill 和 CLI

更多故障排查指南参见 [troubleshooting.md](./skills/baidu-netdisk/reference/troubleshooting.md)。

## 项目结构

```
bdpan-storage/
├── skills/baidu-netdisk/           # Skill 主目录
│   ├── SKILL.md                    # Skill 定义（Agent 行为规范）
│   ├── VERSION                     # 版本号
│   ├── reference/                  # 参考文档
│   │   ├── bdpan-commands.md       # 完整命令手册
│   │   ├── authentication.md       # 认证流程说明
│   │   ├── examples.md             # 使用示例
│   │   └── troubleshooting.md      # 故障排查
│   └── scripts/                    # 管理脚本
│       ├── install.sh              # 安装
│       ├── login.sh                # 登录
│       ├── update.sh               # 更新
│       └── uninstall.sh            # 卸载
├── .github/workflows/              # CI/CD
├── docs/                           # 文档资源
└── Makefile                        # 打包工具
```

## 打包与发布

```bash
make help                           # 查看可用命令
make pack SKILL=baidu-netdisk       # 打包指定 Skill
make pack-all                       # 打包所有 Skills
```

推送 tag 自动触发 GitHub Release：

```bash
git tag v1.2.0
git push origin v1.2.0
```

## 参与贡献

欢迎参与共建！详见 [贡献指南](./docs/contributing.md)。

1. Fork 本仓库
2. 基于 `main` 创建功能分支
3. 提交 PR（使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式）

## 加入社区

<p align="center">
  <img src="./docs/join-us.png" alt="加入社区" width="260" />
</p>

<p align="center"><b>扫码添加，备注「github」即可入群</b></p>

- 与核心开发团队直接交流
- 提交 Bug 反馈和功能建议
- 参与 Skill 共建计划

## 许可证

[Apache License 2.0](./LICENSE)
````
