# Soia Pkm Baidu Netdisk Ops > 百度网盘原子操作与只读 JSONL 扫描适配。触发：「看下百度网盘」「登录百度网盘」「扫描百度网盘」 - Skill: `soia-team/soia-pkm-baidu-netdisk-ops` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add soia-team/soia-pkm-baidu-netdisk-ops` - Raw SKILL.md: https://api.skillmd.com/api/skills/soia-team/soia-pkm-baidu-netdisk-ops/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: soia-team (https://skillmd.com/u/soia-team) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/soia-team/soia-pkm-baidu-netdisk-ops --- # soia-pkm-baidu-netdisk-ops — 百度网盘原子操作层 ## 客户可读说明 本技能把百度官方 `baidu-drive` Skill 和 `bdpan` CLI 接入 PKM 工作流，负责安全的百度网盘原子操作与只读资源扫描。 ## 定位 本技能是 PKM 层的百度网盘适配器，默认使用百度官方公开的 [`baidu-drive`](https://github.com/baidu-netdisk/bdpan-storage/tree/main/skills/baidu-drive) Skill 及其 `bdpan` CLI，也可显式切换到社区 [`mqhe2007/baidupan-cli`](https://github.com/mqhe2007/baidupan-cli) 做开放平台应用目录测试。两种后端都由同一份私有配置选择；本技能补充面向 PKM 的安全边界、只读扫描和标准 JSONL 输出。 它不负责自动整理目录、生成馆藏或制定学习计划；这些应由上层 curator 技能消费扫描结果。 ## 这个技能可以做什么 | 客户想要 | 技能会做 | 客户能看到 | |---|---|---| | 登录或验证百度网盘 | 检查 `bdpan`、版本和登录态；按官方脚本完成授权 | 官方授权地址、非敏感状态和验证结果；不显示 token 或配置文件 | | 查目录或搜索文件 | 使用 `ls --json` / `search --json` | 远端范围、条目和失败原因 | | 传输或管理文件 | 上传、下载、分享、转存、移动、复制、重命名、建目录 | 预期范围、执行结果、冲突策略和终态核对 | | 建立全盘索引输入 | 运行只读 DFS，生成 JSONL 及 `.errors`/`.progress`/`.done` sidecar | 扫描统计、错误数量和产出位置 | 官方 `bdpan` 有意不提供删除命令。本技能不通过其他客户端补充删除，也不使用网页 Cookie、BDUSS 或未公开接口。 ### 客户如何使用 用自然语言说明目标，并提供远端虚拟路径（如 `/资料`）和必要的本地目标路径。Agent 会先检查依赖和登录态；涉及上传、下载、分享、转存或远端整理时，会先展示精确范围和冲突策略，再在获得确认后执行并回读验证。 ## 依赖与安装 先安装本技能： ```bash claude plugin marketplace add soia-team/soia-open-skills ``` ```bash claude plugin install soia-pkm-vault@soia ``` 只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 `~/.agents/skills`；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一： ```bash npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-baidu-netdisk-ops -y ``` 优先安装百度官方上游 Skill： ```bash npx skills add https://github.com/baidu-netdisk/bdpan-storage/skills --skill baidu-drive ``` 随后按上游 `baidu-drive/SKILL.md` 操作： 1. 由上游 `scripts/install.sh` 安装 `bdpan`（当前上游安装器版本需以仓库为准；安装脚本从百度 CDN 下载，执行前应审查脚本和网络来源）。 2. 登录先检查 `bdpan help login` 是否包含 `--device-code`：支持时直接由 Agent 执行本技能的[设备码登录入口](references/login-playbook.md)，自动生成授权链接/二维码并等待客户在百度页面或 App 中授权；该入口自动传入 `--accept-disclaimer`，客户不需要在终端输入 `Y` 或授权码。只有旧版本不支持设备码时，才回退到上游 `scripts/login.sh --yes`；这时 `--yes` 只跳过已展示给客户的脚本安全须知提示，授权仍由客户完成。 3. 运行 `bdpan whoami` 验证登录态。 上游 Skill 的路径是它自己的安装目录，不要把本技能目录误当成上游目录；缺少上游 Skill 时应停止并提示安装依赖。安装、登录和更新都需要用户明确意图，不要静默触发；在客户明确要求登录后，`--yes` 仅用于跳过已经展示过的脚本免责声明，不代表替客户完成百度授权。 社区模式需要 AppKey、SecretKey 和应用名称；官方模式不需要这些变量。两种后端的事实、限制和切换边界见 [provider-cli.md](references/provider-cli.md)。 ## 私密配置与路径合同 - 私有配置默认放在： ```text ~/.config/soia-skills/soia-pkm-baidu-netdisk-ops/config.yml ``` 可用 `SOIA_PKM_BAIDU_NETDISK_OPS_CONFIG_FILE=` 覆盖。复制本技能的 [config.example.yml](assets/config.example.yml) 后按所选后端填写；不要把私有 `config.yml` 放回仓库。 - 配置选项只有 `provider: official|community` 和可选 `binary: bdpan|baidupan-cli`。`binary` 仅用于选择 CLI；缺省按 `provider` 选择。 - 官方 provider 配置由 `bdpan` 自己维护在 `~/.config/bdpan/config.json`。Agent 不读取、不打印、不复制该文件，也不主动设置 `BDPAN_CONFIG_PATH`、`BDPAN_BIN` 或 `BDPAN_INSTALL_DIR`。 - 社区 provider 只从私有配置的 `env:` 读取 `BAIDUPAN_APP_KEY`、`BAIDUPAN_APP_SECRET`、`BAIDUPAN_APP_NAME` 和可选的 `BAIDUPAN_CRYPTO_PASSPHRASE`；进程环境优先于配置文件。包装器不会执行 shell 插值，也不会打印这些值。 - 官方应用隔离根是 `/apps/bdpan/`；用户可见名称通常是 `我的应用数据/bdpan/`。对用户展示和命令输入使用相对路径或本技能虚拟路径，例如 `/资料`、`/资料/a.pdf`，不要把完整 provider 前缀暴露给用户。 - 禁止路径包含 `..` 或 `~`，也不要把本地绝对路径当成远端路径。写入前检查源、目标父目录和冲突策略。 - `bdpan` 的 JSON 字段以 `fs_id`、`server_filename`、`isdir`、`size`、`md5`、`server_mtime` 为主；解析器仅兼容等价大小写字段，不解析人类表格。 ## 标准工作流 ### 依赖与安装 装整个域（Claude Code 与 Codex 共用同一份域插件）： ```bash claude plugin marketplace add soia-team/soia-open-skills claude plugin install soia-pkm-vault@soia ``` 只装这一个技能： ```bash npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-baidu-netdisk-ops -y ``` **WorkBuddy** 的装载单位是角色化专家而不是插件，`npx skills add -a '*'` 覆盖不到它，需要单独安装，见 [docs/install/workbuddy.md](https://github.com/soia-team/soia-open-skills/blob/main/docs/install/workbuddy.md)。 ### 1. 安装与登录 ```bash python3 /scripts/run_with_env.py -- version python3 /scripts/run_with_env.py -- whoami ``` 包装器会按 `config.yml` 选择 `bdpan` 或 `baidupan-cli`。若官方模式的 `bdpan` 不存在，先请用户确认，再运行上游安装脚本；若社区模式的 `baidupan-cli` 不存在，从其 [Releases](https://github.com/mqhe2007/baidupan-cli/releases) 安装。官方模式登录失效时，先检查当前 CLI 是否支持设备码；支持时使用本技能的 `scripts/device_login.py`，它会自动带上 `--accept-disclaimer`、生成链接并等待授权。设备码登录产生二维码图片地址时，用 `scripts/decode_qr.py` 解出浏览器授权地址，并把地址作为可点击链接交给客户；客户只需在百度 App/浏览器完成授权，不需要打开终端、输入 `Y` 或粘贴授权码。旧版本才回退到上游 `scripts/login.sh --yes`。登录后依次执行 `whoami` 和 `--json ls`，检查实际输出和退出码；不要把授权码、二维码内容或 token 写入回执。完整门禁和失败处理见 [login-playbook.md](references/login-playbook.md)。 ### 2. 只读操作 ```bash python3 /scripts/run_with_env.py -- --json ls python3 /scripts/run_with_env.py -- --json ls 资料 python3 /scripts/run_with_env.py -- --json search "关键词" python3 /scripts/run_with_env.py -- whoami ``` 优先读取已有扫描/索引产物；只有没有可用产物时才扫描远端。目录不存在、权限不足、非零退出码或扫描出现 `LIST_FAIL` 时，不得把结果说成“空目录”。 ### 3. 远端写操作 先用包装器执行 `ls --json` 检查源和目标父目录，再明确确认精确范围、冲突策略和是否允许部分成功。命令名称和参数以所选 provider 的参考文档为准。上传若返回业务 JSON 错误（尤其是 `errno=-10`），必须停止重试并回读目标；同时让客户检查网盘容量和开放平台上传能力，不能只凭登录成功推断具备写权限。 ```bash python3 /scripts/run_with_env.py -- mkdir 资料/新目录 python3 /scripts/run_with_env.py -- mv 资料/旧名 资料/ python3 /scripts/run_with_env.py -- cp 资料/a.pdf 备份/ python3 /scripts/run_with_env.py -- rename 资料/旧名 新名 ``` 所有写操作都要在执行后重新列受影响目录或核对目标。`share` 会调用可能收费的能力，必须单独提醒并获得确认： ```bash python3 /scripts/run_with_env.py -- share 资料/a.pdf --period 7 --json python3 /scripts/run_with_env.py -- transfer '' -p '<提取码>' --json ``` ### 4. 上传与下载 ```bash python3 /scripts/run_with_env.py -- upload 资料/ python3 /scripts/run_with_env.py -- download 资料/a.pdf python3 /scripts/run_with_env.py -- download '' -p '<提取码>' ``` 单文件上传的远端目标需包含文件名；目录上传以 `/` 结尾。覆盖、大文件、批量任务和分享转存都要先确认，完成后核对本地文件存在性、大小，必要时独立计算哈希。终端超时不等于传输失败，应先查询任务/目标状态再决定是否重试；明确的 API 业务错误不能按超时处理。 ### 5. 全盘只读 JSONL 扫描 扫描器按配置选择 CLI，只调用对应 provider 的只读 `ls --json`，将条目归一化为 `path`、`name`、`id`、`dir`、`size`、`sha1`，并保留 `md5`、`mtime`： ```bash python3 /scripts/scan_drive.py \ --root / \ --out /baidupan-scan.jsonl \ --workers 4 --resume ``` 可重复使用 `--root /资料` 限制范围；使用 `--no-descend <目录名>` 跳过目录递归；使用 `--resume` 通过 sidecar 跳过已完成目录。扫描本身不修改远端。 收尾必须检查进程退出码、主 JSONL、`.errors`、`.done` 和统计。存在错误时交付“部分扫描”，不要交付“全盘完成”。 ## 记忆备份与恢复提醒 官方 `baidu-drive` Skill 内置记忆备份/恢复；这不是另一个必须安装的 Baidu Drive Backup Plugin。只有当前环境属于 KimiClaw、MaxClaw、QClaw 或 OpenClaw 时，才按上游 Skill 的能力处理： - “备份记忆”“把记忆存到网盘” → `backup`。 - “查看记忆备份”“备份列表” → `list`。 - “恢复记忆”“还原记忆”“恢复 2026-03-16 的备份” → `restore`；必须先确认日期，不能默认恢复最新备份。 - “帮我记住……”“整理/清理记忆”是本地记忆操作，不触发网盘备份；“备份代码/文件”也不是记忆备份。 - 记忆操作必须调用上游 Skill 自己的 `scripts/memory-backup.sh`，不能裸调用 `bdpan upload/download`。恢复前的本地 safety-net、manifest 和环境检测由上游脚本负责；本技能不复制这些脚本，也不读取记忆文件。 - 如果当前不是上述四种环境，明确说明不支持，不执行任何备份/恢复命令。 上游脚本路径以实际安装的 `baidu-drive` Skill 为准，不要把 `` 替换成本技能目录。 ## 与 curator 的边界 本技能只负责 provider 连接、原子操作和标准化扫描输入；不复制 `soia-pkm-alipan-curator` 的阿里云盘特定动作。两个 provider 可以共享 curator 消费的 JSONL 合同，但不应把百度官方 CLI、阿里云盘 CLI 和高风险整理决策合并到一个触发器中。未来若需要百度版 curator，应复用上层的 inventory/catalog/plan 思路，并通过 provider adapter 注入能力。 ## 日志与完成回执 每次执行都要回报： ```markdown 完成：<一句话说明本次完成了什么>。 日志摘要： - started: - processed: <远端路径或扫描范围；数量如可得> - created/updated: <数量或用户指定产物> - skipped/failed: <数量和原因> 文件变化： - <绝对路径或“未改动文件”> 验证： - 问题与下一步： - <缺依赖、待确认事项或建议命令；没有则写“无”> ``` ## 验证证据 - 静态：`quick_validate.py skills/soia-pkm-baidu-netdisk-ops`、`scripts/audit_skills.py`、`git diff --check`。 - 前向：`tests/test_baidupan_scan.py` 用临时 fake CLI 验证官方 JSON 字段、两层目录转换、干净 JSONL、`.errors` 和 `.done` sidecar；配置加载测试验证 provider/binary 选择和秘密值不回显。 - 未做：未使用真实百度账号做端到端上传、分享或转存测试；真实运行仍需按官方登录、用户确认和终态复核门禁执行。