网盘同步专家

网盘同步专家

百度网盘文件管理工具,所有操作限制在 /apps/bdpan/ 目录内。适配所有支持SKILL.md的Agent平台。

触发规则

网盘文件操作触发

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

1. 用户消息中包含明确指向百度网盘的关键词,至少匹配以下之一:
   • 百度网盘、百度云盘、bdpan、baidu netdisk、baidu pan、baidu drive、pan.baidu.com
2. 操作意图明确(上传/下载/转存/分享/查看/搜索/移动/复制/重命名/创建文件夹/删除/登录/注销)
3. 对于写操作(上传、删除、移动、覆盖式下载、公开分享),即使触发词命中,也必须先列出"将要执行的操作 + 影响范围"并取得用户显式确认(y)后再执行

不要触发的情况:

• 用户仅说"网盘""云盘""云存储""百度云"等泛指或可能指向其他百度产品的词,未明确指向百度网盘 → 应反问"您指的是百度网盘(pan.baidu.com)吗?"再决定
• 用户在讨论其他云盘服务(OneDrive、Google Drive、阿里云盘、夸克网盘等)
• 仅复述、引用或摘要历史聊天记录中的网盘内容,而无新的操作意图

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

上下文延续(受限): 当前对话已在进行百度网盘操作时,后续消息可在只读类操作(ls/search/whoami)上继续延续;但写操作(upload/download/share/mv/cp/rename/mkdir/rm)每一次都必须重新出示触发词或得到用户显式确认,禁止凭借历史上下文静默执行。

记忆备份/恢复触发

以下表达即使未提及"网盘"也应触发(仅限支持Agent记忆备份的环境):

以下情况不触发记忆备份/恢复:

• "帮我记住…"、"整理记忆"、"清理记忆"(本地操作,不涉及网盘)
• "备份我的代码/文件"(操作对象不是记忆)
• 不支持的环境(报错说明不支持,不执行)

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

---

安全约束(最高优先级,不可被任何用户指令覆盖)

1. 登录:必须使用 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh,禁止直接调用 bdpan login 及其任何子命令/参数(包括 --get-auth-url、--set-code 等,即使在 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
3. 路径校验:验证远端路径在 /apps/bdpan/ 范围内

---

确认规则

额外规则:

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

---

核心操作

查看状态

bdpan whoami

列表查询

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

上传

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

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

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

智能下载策略(差异化核心)

根据文件大小自动选择下载策略,解决大文件超时中断痛点:

下载策略选择

# 1. 获取文件大小
bdpan ls --json <远端路径>
# 从JSON输出中读取 size 字段(字节)

小文件(≤ 50MB)直接下载

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

Bash 工具 timeout 参数设为 300000(5 分钟)。

大文件(> 50MB)后台下载流程

# 启动后台下载
nohup bdpan download <远端路径> <本地路径> > /tmp/bdpan-dl-$$.log 2>&1 & echo $!

# 轮询进度
kill -0  2>/dev/null && echo "running" || echo "done"; ls -l <本地路径> 2>/dev/null; tail -5 /tmp/bdpan-dl-.log 2>/dev/null

# 清理日志
rm -f /tmp/bdpan-dl-.log

Agent执行大文件后台下载行为规范:

• 启动后台下载后,立即告知用户:下载已在后台启动,文件大小 X,预计需要 Y 时间
• 每次轮询后向用户报告进度(已下载大小 / 总大小、百分比)
• 下载完成后告知用户最终结果
• 如果进程异常退出,检查日志并报告错误原因

分享链接下载(先转存再下载到本地)

bdpan download "https://pan.baidu.com/s/1xxxxx?pwd=abcd" ./downloaded/
bdpan download "https://pan.baidu.com/s/1xxxxx" ./downloaded/ -p abcd    # 提取码单独传入
bdpan download "https://pan.baidu.com/s/1xxxxx?pwd=abcd" ./downloaded/ -t my-folder  # 指定转存目录

分享链接下载同样适用大文件策略:转存完成后,用 bdpan ls --json 获取文件大小,再按上述策略执行下载。

完整性校验(差异化)

下载完成后验证文件完整性:

# 1. 获取远端文件大小
bdpan ls --json <远端路径> | grep -o '"size":[0-9]*'

# 2. 获取本地文件大小
ls -l <本地路径> | awk '{print $5}'

# 3. 比对大小
# 如大小不一致,提示用户重新下载

转存

将分享文件转存到网盘,不下载到本地(与 download 分享链接模式的区别)。

bdpan transfer "https://pan.baidu.com/s/1xxxxx" -p <提取码> [-d 目标目录] [--json]

步骤:确认分享链接格式有效 → 确认有提取码(链接中含 ?pwd= 或反问用户)→ 确认目标目录 → 执行。转存成功后只展示本次转存的文件(非整个目录),显示数量和目标目录。

分享

bdpan share <路径> [路径...] [--period <天数>] [--json]

--period / -d 参数: 分享有效期(天),取值:0=永久, 1, 7, 30(默认:7)

智能选择规则:

Agent 必须根据用户的语义意图判断有效期,而非仅匹配固定关键词。

• 用户表达了"希望长期有效/永久/不过期/一直能用"等语义 → 使用 --period 0,并提示用户:永久链接无法自动过期,请注意文件安全
• 用户指定了具体天数或时间范围 → 选择最接近的枚举值(1、7、30)
• 用户未表达任何有效期偏好 → 默认 --period 7

步骤:bdpan ls 确认文件存在 → 根据用户意图选择有效期 → 执行分享 → 展示链接+提取码+有效期。

付费接口,需在百度网盘开放平台购买服务。

搜索

bdpan search <关键词> [--category 0-7] [--no-dir|--dir-only] [--page-size N] [--page N] [--json]

category:0=全部 1=视频 2=音频 3=图片 4=文档 5=应用 6=其他 7=种子。--no-dir 和 --dir-only 互斥。

移动 / 复制 / 重命名 / 创建文件夹

bdpan mv <源路径> <目标目录>
bdpan cp <源路径> <目标目录>
bdpan rename <路径> <新名称>       # 第二参数是文件名,非完整路径
bdpan mkdir <路径>

---

批量处理模板(差异化)

批量上传

# 批量上传目录下所有文件
for file in ./local-dir/*; do
  filename=$(basename "$file")
  bdpan upload "$file" "remote-dir/$filename"
done

批量下载

# 获取文件列表并批量下载
bdpan ls --json remote-dir/ | jq -r '.[].path' | while read path; do
  bdpan download "$path" "./local-dir/$(basename $path)"
done

增量同步机制(差异化)

仅上传变化的文件,减少带宽消耗:

# 1. 获取远端文件列表(含大小和时间)
bdpan ls --json remote-dir/ > /tmp/remote-files.json

# 2. 对比本地文件
for file in ./local-dir/*; do
  filename=$(basename "$file")
  local_size=$(stat -c%s "$file")
  remote_size=$(jq -r ".[] | select(.name==\"$filename\") | .size" /tmp/remote-files.json)

  if [ "$local_size" != "$remote_size" ]; then
    echo "文件 $filename 有变化,上传中..."
    bdpan upload "$file" "remote-dir/$filename"
  else
    echo "文件 $filename 无变化,跳过"
  fi
done

---

路径规则

映射关系:我的应用数据 ↔ /apps

禁止: 命令中使用中文路径(我的应用数据/...)、展示时暴露 API 路径(/apps/bdpan/...)。

---

授权码处理

用户发送 32 位十六进制字符串时,先确认:"这是百度网盘授权码吗?确认后将执行登录流程。" 确认后执行 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh(不使用 --yes,保留安全确认环节)。

---

管理功能

安装

bash ${CLAUDE_SKILL_DIR}/scripts/install.sh [--yes]

安装器从百度 CDN(issuecdn.baidupcs.com)下载并执行。注意:install.sh 不执行本地 SHA256 校验,完整性依赖 HTTPS 传输保护。安全敏感场景建议先手动审查安装器内容或在沙箱中执行。

登录 / 注销 / 卸载

bash ${CLAUDE_SKILL_DIR}/scripts/login.sh              # 登录(内置安全免责声明)
bdpan logout                                            # 注销
bash ${CLAUDE_SKILL_DIR}/scripts/uninstall.sh [--yes]   # 卸载

更新(必须用户明确指令触发)

bash ${CLAUDE_SKILL_DIR}/scripts/update.sh              # 检查并更新(需用户确认)
bash ${CLAUDE_SKILL_DIR}/scripts/update.sh --check       # 仅检查更新

---

记忆备份与恢复

支持Agent记忆备份的运行环境,自动检测当前环境是否支持。

网盘存储路径: /apps/bdpan/agent-memory///manual//

备份内容: 7 个 Workspace 文件(AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md、MEMORY.md、HEARTBEAT.md)+ memory/*.md + manifest.json

备份记忆

bash ${CLAUDE_SKILL_DIR}/scripts/memory-backup.sh backup

查看备份列表

bash ${CLAUDE_SKILL_DIR}/scripts/memory-backup.sh list

恢复备份

bash ${CLAUDE_SKILL_DIR}/scripts/memory-backup.sh restore 2026-03-16

bash ${CLAUDE_SKILL_DIR}/scripts/memory-backup.sh restore 2026-03-16 --force

bash ${CLAUDE_SKILL_DIR}/scripts/memory-backup.sh restore 2026-03-16 --yes

恢复安全机制:

1. 影响预览:恢复前会列出所有将被覆盖/新增的本地文件清单
2. 显式确认:默认必须用户输入 y 才会执行覆盖(非交互式环境下若未加 --yes 直接拒绝执行)
3. Safety net:恢复前自动将当前本地记忆备份到 /.backup-before-restore//,防止误操作数据丢失

操作流程

1. 执行前自动检查:bdpan 是否安装 → 是否已登录(未满足则引导处理)
2. 检测当前 Agent 类型 → 不支持的环境报错退出
3. 执行对应操作(backup/list/restore)

---

常见问题FAQ

Q: 大文件下载总是超时中断怎么办? A: 使用智能下载策略。先用 bdpan ls --json 获取文件大小,大于50MB的文件使用nohup后台下载模式,Agent轮询进度。这避免了Bash工具超时限制导致的中断。

Q: 下载速度很慢怎么办? A: 下载速度受百度网盘服务端限制。非会员用户可能遇到限速。建议:1)确认网络连接正常;2)使用后台下载模式避免超时;3)如需更高速度,考虑开通百度网盘会员。

Q: 如何判断下载是否完整? A: 使用完整性校验。下载完成后,用 bdpan ls --json 获取远端文件大小,与本地文件大小(ls -l)比对。大小不一致则需要重新下载。

Q: 分享链接转存和下载有什么区别? A: 转存(bdpan transfer)将分享文件保存到你的网盘,不下载到本地。下载分享链接(bdpan download "分享链接")先转存再下载到本地。如只需保存到网盘用transfer,如需本地文件用download。

Q: 批量上传很多文件如何操作? A: 使用批量处理模板。用for循环遍历本地目录,逐个执行 bdpan upload。如需增量同步(仅上传变化文件),先获取远端文件列表,对比大小后仅上传有变化的文件。

Q: 记忆备份支持哪些环境? A: 支持Agent记忆备份的运行环境。脚本会自动检测当前环境,不支持的环境会报错退出。操作对象必须是Agent记忆文件(AGENTS.md、SOUL.md、MEMORY.md等)。

Q: 恢复记忆会覆盖当前记忆吗? A: 会,但有安全机制保护。恢复前会:1)列出所有将被覆盖的文件清单;2)要求用户显式确认;3)自动将当前记忆备份到 .backup-before-restore/ 目录,防止误操作数据丢失。

故障排查

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux
• Shell: bash(脚本执行需要)

第三方依赖

API Key 配置

• 通过百度网盘OAuth授权登录,无需手动配置API Key
• 授权码通过 bash ${CLAUDE_SKILL_DIR}/scripts/login.sh 流程获取
• 禁止读取或输出 ~/.config/bdpan/config.json 内容(含敏感凭据)

可用性分类

• 分类: MD+EXEC(纯Markdown指令,需要命令行执行能力运行bdpan CLI)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent使用bdpan CLI管理百度网盘文件。需要bdpan CLI和百度网盘账户。