网盘整理流水线 kakayanjiahua-star/baidu-pan-organizer

百度网盘整理工具箱 · Baidu Pan Organizer 把乱成一团的百度网盘，交给 AI 按流程理干净。
官方只给 SSE，一半客户端用不了 —— 这里有一个桥、一套流程、一份踩坑清单。

这是什么

百度网盘官方已经发布了 MCP Server（16 个工具：列目录、搜索、移动、复制、重命名、建目录、分享…），但有三个卡点让人用不起来：

| 卡点 | 现状 | 本项目的做法 |
| 官方只有 SSE 入口 | DSH / 部分客户端只认 stdio，直接接不上 | 转接桥：stdio ⇄ SSE 双向翻译，零依赖 |
| 网盘大了没法"看着整理" | 几十万文件，AI 看不到全貌，只能瞎点 | 先扫描出地图：类型 / 大文件 / 重复 / 最乱目录 |
| 让 AI 直接搬文件很吓人 | 搬错了、改名了、删了怎么办 | 先出方案你点头、一次一个、留痕可回滚、永不删除 |

它不是一个"点一下自动整理"的黑盒，而是一条可控的流水线：扫描 → 地图 → 方案 → 执行 → 核对。

五步工作流

| 步骤 | 脚本 | 做什么 | 你参与吗 |
| 1 扫描 | src/scan.mjs | 递归拉全盘清单（断点续扫、限流退避） | 不用 |
| 2 出地图 | src/analyze.mjs src/structure.mjs src/dedup.mjs | 类型分布、大文件 TOP、md5 重复、目录结构 | 看结果 |
| 3 出方案 | src/plan.mjs | 按你的配置生成分类与迁移清单 | 你点头才继续 |
| 4 执行 | src/apply.mjs | 先干跑，再逐条移动，全程留痕 | 决定何时开跑 |
| 5 核对 | src/verify.mjs | 按文件 ID 查真实位置，判定到位 / 没动 / 落别处 | 看报告 |

工作原理：为什么要一个"桥"

快速开始

git clone https://github.com/kakayanjiahua-star/baidu-pan-organizer.git
cd baidu-pan-organizer
node --version # 需要 Node ≥ 18，零依赖，不用 npm install

① 拿 Access Token（官方授权，一次约 30 天有效）

浏览器打开官方授权链接 → 登录 → 点「授权」→ 页面会跳到一个打不开的地址（正常），把地址栏里 access_token= 后面那串复制出来：

https://openapi.baidu.com/oauth/2.0/authorize?response_type=token&client_id=&redirect_uri=oob&scope=basic,netdisk

个人"限时体验"密钥由官方不定期更换，长期使用建议申请企业开发者（token 可自动续期）。
把 token 写进项目根目录的 baidu-pan-mcp.env（已在 .gitignore 里，不会被提交）：
BAIDU_PAN_TOKEN=你的_access_token

② 接进你的 AI 客户端

| 客户端 | 怎么接 |
| DSH / DeepSeek Harness | 把 configs/dsh.cordis.patch.yml 的内容贴进 cordis.patch.yml（热挂载即生效） |
| Cursor / Cline | 把 configs/cursor.mcp.json 的内容并进 mcp.json |
| Claude Desktop | 把 configs/claude_desktop_config.json 并进 claude_desktop_config.json |

桥的三种用法（都不需要装依赖）：

node src/bridge.mjs --selftest # 自检：连一次百度，打印工具清单
node src/bridge.mjs # 作为 MCP 服务（stdio），给客户端调用
node src/bridge.mjs --token "xxx" # 也可以直接传 token

③ 先扫描，再整理

node src/scan.mjs # 全盘扫描（大页 + 限流退避 + 断点续扫）
node src/dedup.mjs && node src/structure.mjs
node src/analyze.mjs # → scan-out/网盘地图.md
cp examples/classify.config.json classify.config.json # 改成你自己的分类
node src/plan.mjs # → scan-out/归类方案.md（先看这份！）
node src/apply.mjs # 干跑：只打印要做什么
node src/apply.mjs --go --sync --batch 3 --gap 4000 # 真执行
node src/verify.mjs # 核对：到位 / 没动 / 落别处

配置：分类规则长什么样

{
"keep": ["/我的私人目录"], // 永远不动的目录
"moves": { // 目录 → 目标（整目录搬）
"/网课-英语": "/1-学习课程/英语", "/电影收藏": "/4-影视音乐" },
"childMoves": { // 把一个大目录里的子项分别归位
"/资料合集": {
"default": "/5-资料归档/其他",
"map": { "电子资料": "/5-资料归档/电子资料", "设计素材": "/6-素材库/设计" }
}
},
"rules": [ // 按名字正则匹配
{ "match": "^来自[：:]", "to": "/7-设备直传/{name}" } ], "defaultTo": "/9-待你确认" // 拿不准的一律先放这里，绝不猜着搬 }

优先级：keep → childMoves → moves → rules → defaultTo。任何没匹配上的目录都会被列出来，不会静默消失。

实测踩坑清单（这份最值钱）

这些都是我们在一台 41 万文件 / 9.7 TB 的真实网盘上撞出来的：

| 坑 | 现象 | 正确做法 |
| 官方 /mcp 端点不存在 | POST /mcp → 404，只有 /sse 活的 | 桥必须走 SSE |
| 本地 stdio 版不是全套 | 官方 stdio 版只提供"上传"一个工具 | 想要 16 个工具只能走远程 SSE + 桥 |
| 分类接口选错会 31064 | xpan/file?method=listall → file is not authorized | 用 xpan/multimedia?method=listall&path=/&recursion=1 |
| 翻页会重复抓 | 59.9 万条里有 18.6 万条是重复记录 | 按 fs_id 去重后再统计（并验证同一 ID 不会对应多个路径） |
| 建目录会生成空壳 | mkdir rtype=1 反复建同名目录 → 生成 名字_时间戳 空目录（我们造出过 10 个） | 用 rtype=0 并容忍"已存在" |
| newname 是文件名不是文件夹 | 本想把散文件放进「散文件/」文件夹，结果 3 个文件被改名 | dest 是目标文件夹，newname 是新文件名，二者别混 |
| 异步移动无法跟踪 | async=1 常常不返回 info，日志里看着"失败"其实成功了 | 一律 async=0 逐条同步，或记录 taskid 轮询 |
| 目录列表有缓存 | 用它核对会误判"没搬" | 核对用 multimedia?method=filemetas&fsids=[...] 按 ID 查真实 path |
| curl 的方括号 | URL 里的 fsids=[1,2] 被 curl 当通配符，返回空 | 加 -g |
| 个人密钥会变 + 限流紧 | errno 31034 hit frequency limit；密钥不定期更换 | 页间隔 ≥ 45s、逐条重试；长期用企业开发者 token |
| 平台禁止移动某些目录 | 个别目录返回 errno 445 文件夹禁止移动 | 记下来交给人工，别硬试 |
| AI 没有删除权限 | 官方 16 个工具里没有 delete | 空目录/重复副本列清单给用户手动删 |
| 重复不能只看名字 | 百度对大部分文件返回脱敏 md5（含非 16 进制字符） | md5 有效才算"确证重复"，其余标"疑似"待人工抽查 |

完整版见 docs/pitfalls.md。

安全与边界

| 项 | 做法 |
| 会不会删我东西 | 不会。官方 MCP 根本没有删除接口，本工具也不调用任何删除 |
| 怎么改 | 只改路径（元数据移动），不下载、不上传、不占带宽 |
| 撞名怎么办 | ondup=fail —— 宁可报错，绝不静默改名 |
| 搬错了怎么办 | 每步写 apply-log.jsonl（旧路径 → 新路径），按它可整批搬回 |
| token 去哪了 | 只在本地 baidu-pan-mcp.env，已 .gitignore；仓库自带 隐私闸门 防误提交 |
| 它会自己乱来吗 | 不会：plan 只产出清单，apply 默认干跑，要显式加 --go 才动 |

常见问题

没有企业开发者账号能用吗？

能。官方开放了"个人限时体验"入口，用 response_type=token 拿一个约 30 天有效的 token 即可。缺点是密钥会被官方不定期更换、接口限流更紧。

为什么不用现成的百度网盘 CLI / Skill？
官方另有 bdpan CLI（bdpan-storage Skill），但它的所有操作被限制在 /apps/bdpan/ 目录内，动不了你网盘里的存量文件；而且 Windows 原生不支持（需要 WSL）。想整理存量，只能用开放平台 API。

能整理多大的网盘？

实测 41 万条目 / 9.7 TB：全量扫描约 50 分钟（受官方限流影响），整理 140 次目录移动约 10 分钟。文件越多，扫描越慢，但支持断点续扫，可以分几次跑。

会不会把我网盘搞乱？

流程天然防呆：先出方案（Markdown 表）→ 你确认 → 干跑 → 才执行。任何“拿不准”的目录都会进 /9-待你确认，不会替你猜。

仓库结构

baidu-pan-organizer/
├── src/
│ ├── bridge.mjs # stdio ⇄ SSE 转接桥（零依赖） │ ├── scan.mjs # 全盘扫描（断点续扫 + 限流退避） │ ├── dedup.mjs # 清单去重（按 fs_id） │ ├── structure.mjs # 目录结构（一级 → 二级） │ ├── analyze.mjs # 网盘地图（类型 / 大文件 / 重复） │ ├── plan.mjs # 配置驱动的整理方案 │ ├── apply.mjs # 迁移执行器（干跑 / 留痕 / 回滚） │ ├── verify.mjs # 按文件 ID 权威核对 │ └── check-fsid.mjs # 数据自检（同一 ID 是否对应多路径） ├── configs/ # 各客户端接入示例 ├── examples/ # 假数据 + 示例配置（可直接跑通全程） ├── docs/ # 图与踩坑清单 └── SKILL.md # 给 Agent 的操作手册（放进 skills 目录即可）

给 Agent 用

把 SKILL.md 丢进你的技能目录（DSH：$DSH_HOME/skills/），AI 就会按“先扫描 → 出方案给你审 → 干跑 → 执行 → 核对”的顺序干活，不会上来就搬文件。

路线图

- [ ] 手机/相册直传目录的“按年月自动归档”
- [ ] 重复文件报告一键转成“待删清单”
- [ ] 支持企业开发者 OAuth 授权码模式（token 自动续期）
- [ ] 英文文档完善 / 接入更多客户端示例

Star History

许可证

MIT · 与百度官方无隶属关系；使用开放平台接口请遵守其服务条款。