Customer-readable description
This skill integrates Baidu's official baidu-drive Skill and bdpan CLI into the PKM workflow, handling secure Baidu Netdisk atomic operations and read-only resource scanning.
Positioning
This skill is the Baidu Netdisk adapter for the PKM layer. By default it uses Baidu's officially published baidu-drive Skill and its bdpan CLI, and can also explicitly switch to the community mqhe2007/baidupan-cli for open platform application directory testing. Both backends are selected by the same private configuration; this skill adds PKM-oriented security boundaries, read-only scanning, and standard JSONL output.
It is not responsible for automatically organizing directories, generating collections, or formulating study plans; these should be handled by upper-layer curator skills consuming the scan results.
What this skill can do
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Log in to or verify Baidu Netdisk | Check bdpan, version, and login status; complete authorization according to the official script |
Official authorization address, non-sensitive status, and verification result; does not display tokens or configuration files |
| Browse directories or search files | Use ls --json / search --json |
Remote scope, entries, and failure reasons |
| Transfer or manage files | Upload, download, share, transfer, move, copy, rename, create directory | Expected scope, execution result, conflict policy, and final-state verification |
| Build full-disk index input | Run read-only DFS, generate JSONL and .errors/.progress/.done sidecar |
Scan statistics, error count, and output location |
Official bdpan intentionally does not provide a delete command. This skill does not add deletion through other clients, and does not use web cookies, BDUSS, or undocumented interfaces.
How customers use it
Describe the goal in natural language, and provide the remote virtual path (such as /资料) and the necessary local target path. The Agent will first check dependencies and login status; when upload, download, sharing, transfer, or remote organization is involved, it will first show the exact scope and conflict policy, then execute after obtaining confirmation and read back for verification.
Dependencies and installation
Prefer to install Baidu's official upstream Skill:
npx skills add https://github.com/baidu-netdisk/bdpan-storage/skills --skill baidu-drive
Then strictly follow the upstream baidu-drive/SKILL.md operation:
- Installed by upstream
scripts/install.shinstallsbdpan(the current upstream installer version is subject to the repository; the installation script is downloaded from Baidu CDN, and the script and network source should be reviewed before execution). - Login only uses upstream
scripts/login.sh. Do not let the Agent directly executebdpan login, and do not enter the account, password, verification code, or authorization code on behalf of the user. - Run
bdpan whoamito verify login status.
The upstream Skill's path is its own installation directory; do not mistake this skill's directory for the upstream directory; when the upstream Skill is missing, stop and prompt to install dependencies. Installation, login, and updates all require the user's explicit intent; do not execute silently, and do not use --yes to bypass confirmation.
Community mode requires AppKey, SecretKey and an application name; official mode does not require these variables. For the facts, limitations and switching boundaries of both backends, see provider-cli.md。
Private configuration and path contract
-
Private configuration is stored by default at:
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-baidupan/config.ymlCan be overridden with
SOIA_PKM_BAIDUPAN_CONFIG_FILE=<custom-config-path>override. Copy this skill's config.example.yml and fill it in according to the selected backend; do not put the privateconfig.ymlback into the repository. -
The only configuration options are
provider: official|communityand the optionalbinary: bdpan|baidupan-cli。binaryis only used to select the CLI; by default it is selected according toprovider. -
The official provider configuration is maintained by
bdpanitself in~/.config/bdpan/config.json. The Agent does not read, print or copy this file, and does not actively setBDPAN_CONFIG_PATH、BDPAN_BINorBDPAN_INSTALL_DIR。 -
The community provider reads only from the private configuration's
env:to readBAIDUPAN_APP_KEY、BAIDUPAN_APP_SECRET、BAIDUPAN_APP_NAMEand the optionalBAIDUPAN_CRYPTO_PASSPHRASE; the process environment takes precedence over the configuration file. The wrapper does not perform shell interpolation and does not print these values. -
The official application isolation root is
/apps/bdpan/; the user-visible name is usually我的应用数据/bdpan/. For user display and command input, use relative paths or this skill's virtual paths, for example/资料、/资料/a.pdf, and do not expose the full provider prefix to users. -
Paths are forbidden from containing
..or~, and do not treat local absolute paths as remote paths. Before writing, check the source, the target parent directory and the conflict policy. -
bdpanThe JSON fields offs_id、server_filename、isdir、size、md5、server_mtimeare primarily
Standard workflow
1. Installation and login
python3 <skill-path>/scripts/run_with_env.py -- version
python3 <skill-path>/scripts/run_with_env.py -- whoami
The wrapper selects according to config.yml selects bdpan or baidupan-cli. If official mode's bdpan does not exist, first ask the user to confirm, then run the upstream installation script; if community mode's baidupan-cli does not exist, install it from its Releases . When official mode login has expired, run the upstream scripts/login.sh, do not call bdpan logindirectly; only community mode uses baidupan-cli login. After logging in, run whoamiagain, and do not write the authorization code or token into the receipt.
2. Read-only operations
python3 <skill-path>/scripts/run_with_env.py -- --json ls
python3 <skill-path>/scripts/run_with_env.py -- --json ls 资料
python3 <skill-path>/scripts/run_with_env.py -- --json search "关键词"
python3 <skill-path>/scripts/run_with_env.py -- whoami
Prefer reading existing scan/index artifacts; only scan the remote when no usable artifacts are available. If the directory does not exist, permissions are insufficient, the exit code is non-zero, or the scan produces LIST_FAIL , do not describe the result as an "empty directory".
3. Remote write operations
First use the wrapper to run ls --json to check the source and target parent directory, then explicitly confirm the exact scope, conflict policy and whether partial success is allowed. Command names and parameters are subject to the selected provider's reference documentation.
python3 <skill-path>/scripts/run_with_env.py -- mkdir 资料/新目录
python3 <skill-path>/scripts/run_with_env.py -- mv 资料/旧名 资料/
python3 <skill-path>/scripts/run_with_env.py -- cp 资料/a.pdf 备份/
python3 <skill-path>/scripts/run_with_env.py -- rename 资料/旧名 新名
All write operations must re-list the affected directory or verify the target after execution.share invokes capabilities that may incur charges, and must be separately flagged and confirmed:
python3 <skill-path>/scripts/run_with_env.py -- share 资料/a.pdf --period 7 --json
python3 <skill-path>/scripts/run_with_env.py -- transfer '<share-url>' -p '<提取码>' --json
4. Upload and download
python3 <skill-path>/scripts/run_with_env.py -- upload <local-file> 资料/
python3 <skill-path>/scripts/run_with_env.py -- download 资料/a.pdf <local-file>
python3 <skill-path>/scripts/run_with_env.py -- download '<share-url>' <local-dir> -p '<提取码>'
The remote target of a single-file upload must include the file name; directory uploads end with / . Overwrites, large files, batch tasks and share transfers must all be confirmed first; after completion, verify the local file's existence, size, and if necessary independently compute the hash. A terminal timeout does not mean the transfer failed; first query the task/target status before deciding whether to retry.
5. Full-disk read-only JSONL scan
The scanner selects the CLI according to the configuration and calls only the corresponding provider's read-only ls --json, normalizing entries into path、name、id、dir、size、sha1, and retain md5、mtime:
python3 <skill-path>/scripts/scan_drive.py \
--root / \
--out <user-output-dir>/baidupan-scan.jsonl \
--workers 4 --resume
Reusable --root /资料 to limit scope; use --no-descend <目录名> to skip directory recursion; use --resume to skip completed directories via sidecar. The scan itself does not modify the remote.
Wrap-up must check the process exit code, the main JSONL,.errors、.done and statistics. When errors exist, deliver a "partial scan", not a "full completion".
Memory backup and restore reminder
Official baidu-drive Skill has built-in memory backup/restore; this is not another Baidu Drive Backup Plugin that must be installed. Only when the current environment is KimiClaw, MaxClaw, QClaw, or OpenClaw should you handle it according to the upstream Skill's capabilities:
- "Back up memory", "save memory to cloud drive" →
backup。 - "View memory backups", "backup list" →
list。 - "Restore memory", "revert memory", "restore the 2026-03-16 backup" →
restore; you must confirm the date first, and must not default to restoring the latest backup. - "Help me remember...", "organize/clean up memory" are local memory operations and do not trigger cloud drive backup; "back up code/files" is also not memory backup.
- Memory operations must call the upstream Skill's own
scripts/memory-backup.sh, and must not directly callbdpan upload/download. The local safety-net, manifest, and environment detection before restore are handled by the upstream scripts; this skill does not copy these scripts, nor does it read memory files. - If the current environment is not one of the above four, clearly state that it is unsupported and do not execute any backup/restore commands.
The upstream script path is based on the actually installed baidu-drive Skill; do not replace <skill-path> with this skill's directory.
Boundary with curator
This skill is only responsible for provider connection, atomic operations, and standardized scan input; it does not copy soia-pkm-alipan-curator 's Alibaba Cloud Drive-specific actions. The two providers can share the JSONL contract consumed by curator, but the Baidu official CLI, Alibaba Cloud Drive CLI, and high-risk organization decisions should not be merged into one trigger. If a Baidu version of curator is needed in the future, it should reuse the upper-layer inventory/catalog/plan approach and inject capabilities through a provider adapter.
Logs and completion receipt
Every execution must report:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <CLI/版本/登录态检查,不打印秘密值>
- processed: <远端路径或扫描范围;数量如可得>
- created/updated: <数量或用户指定产物>
- skipped/failed: <数量和原因>
文件变化:
- <绝对路径或“未改动文件”>
验证:
- <whoami/ls/本地字节数/扫描 sidecar 等证据>
问题与下一步:
- <缺依赖、待确认事项或建议命令;没有则写“无”>
Verification evidence
- Static:
quick_validate.py skills/soia-pkm-baidupan、scripts/audit_skills.py、git diff --check。 - Forward:
tests/test_baidupan_scan.pyuse a temporary fake CLI to verify official JSON fields, two-level directory conversion, clean JSONL,.errorsand.donesidecar; configuration loading tests verify provider/binary selection and that secret values are not echoed back. - Not done: no end-to-end upload, share, or transfer tests were performed with a real Baidu account; real runs still need to follow the official login, user confirmation, and final-state review gates.