Customer-readable description
This skill integrates the official Baidu 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, using the officially published Baidu baidu-drive Skill and its bdpan CLI by default, 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 creating 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 state; complete authorization using the official script |
Official authorization URL, non-sensitive status, and verification result; does not display token or configuration files |
| List directories or search files | Use ls --json / search --json |
Remote scope, entries, and failure reasons |
| Transfer or manage files | Upload, download, share, save to own Netdisk, 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, nor does it 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 state; for uploads, downloads, shares, save-to-own-Netdisk, or remote organization, it will first show the exact scope and conflict policy, then execute after confirmation and read back for verification.
Dependencies and installation
First install this skill:
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
When only this skill is needed, the npx route can be used. Note that the skill will land in the shared source of truth ~/.agents/skills; if a plugin is also installed, the same skill will appear as two index copies and drift separately, so it is recommended to choose one of the two:
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-baidu-netdisk-ops -y
Prefer to install the official Baidu upstream Skill:
npx skills add https://github.com/baidu-netdisk/bdpan-storage/skills --skill baidu-drive
Then follow the upstream baidu-drive/SKILL.md procedure:
- By upstream
scripts/install.shinstallbdpan(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). - For login, first check whether
bdpan help logincontains--device-code: when supported, the Agent directly executes this skill'sdevice code login entry, automatically generating the authorization link/QR code and waiting for the customer to authorize on the Baidu page or App; this entry automatically passes--accept-disclaimer, and the customer does not need to enterYor the authorization code in the terminal. Only when the old version does not support device codes should it fall back to upstreamscripts/login.sh --yes; at this point--yesonly skips the script security notice that has already been shown to the customer; authorization is still completed by the customer. - Run
bdpan whoamito verify the login state.
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 the dependency. Installation, login, and updates all require explicit user intent; do not trigger them silently. After the customer explicitly requests login,--yes is only used to skip the script disclaimer that has already been shown; it does not mean completing Baidu authorization on the customer's behalf.
Community mode requires AppKey, SecretKey, and the application name; official mode does not require these variables. For the facts, limitations, and switching boundaries of the two backends, see provider-cli.md。
Private configuration and path contract
-
Private configuration is placed by default at:
~/.config/soia-skills/soia-pkm-baidu-netdisk-ops/config.ymlCan be overridden with
SOIA_PKM_BAIDU_NETDISK_OPS_CONFIG_FILE=<custom-config-path>. 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, nor does it actively setBDPAN_CONFIG_PATH、BDPAN_BINorBDPAN_INSTALL_DIR。 -
The community provider only reads from the private configuration's
env:theBAIDUPAN_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, nor does it print these values. -
The official application isolation root is
/apps/bdpan/; the user-visible name is usually我的应用数据/bdpan/. For user-facing display and command input, use relative paths or this skill's virtual paths, for example/资料、/资料/a.pdf; do not expose the full provider prefix to the user. -
Paths are forbidden from containing
..or~, and do not treat local absolute paths as remote paths. Before writing, check the source, the destination parent directory, and the conflict policy. -
bdpan's JSON fields are primarilyfs_id、server_filename、isdir、size、md5、server_mtime; the parser only supports equivalent case-insensitive fields and does not parse human-readable tables.
Standard workflow
Dependencies and installation
Install the entire domain (Claude Code and Codex share the same domain plugin):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
Install only this one skill:
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-baidu-netdisk-ops -y
WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and it needs to be installed separately, see docs/install/workbuddy.md。
1. Installation and login
python3 <skill-path>/scripts/run_with_env.py -- version
python3 <skill-path>/scripts/run_with_env.py -- whoami
The wrapper will select according to config.yml the 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 is invalid, first check whether the current CLI supports device codes; if it does, use this skill's scripts/device_login.py, which will automatically include --accept-disclaimer, generate a link, and wait for authorization. When device code login produces a QR code image address, use scripts/decode_qr.py to extract the browser authorization address, and give the address to the customer as a clickable link; the customer only needs to complete authorization in the Baidu App/browser, and does not need to open a terminal, enter Y , or paste an authorization code. Only older versions fall back to the upstream scripts/login.sh --yes. After login, execute in sequence whoami and --json ls, check the actual output and exit code; do not write authorization codes, QR code contents, or tokens into receipts. For the full gate and failure handling, see login-playbook.md。
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 exist. If the directory does not exist, permissions are insufficient, the exit code is non-zero, or the scan shows LIST_FAIL , you must not describe the result as an "empty directory".
3. Remote write operations
First use the wrapper to execute ls --json to check the source and target parent directories, 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. If an upload returns a business JSON error (especially errno=-10), you must stop retrying and read back the target; at the same time, have the customer check the cloud drive capacity and the open platform's upload capability. Do not infer write permission solely from a successful login.
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, after execution, re-list the affected directories or verify the target.share invokes capabilities that may incur charges, so you must remind the user separately and obtain confirmation:
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; a directory upload ends with / . Overwriting, large files, batch tasks, and share transfers must all be confirmed first; after completion, verify local file existence, size, and, if necessary, independently compute the hash. A terminal timeout does not equal a failed transfer; first query the task/target status before deciding whether to retry. Explicit API business errors must not be handled as timeouts.
5. Full-disk read-only JSONL scan
The scanner selects the CLI according to configuration and only calls the corresponding provider's read-only ls --json, normalizes entries to path、name、id、dir、size、sha1, and preserves md5、mtime:
python3 <skill-path>/scripts/scan_drive.py \
--root / \
--out <user-output-dir>/baidupan-scan.jsonl \
--workers 4 --resume
to be reusable --root /资料 to limit the scope; use --no-descend <目录名> to skip directory recursion; use --resume to skip completed directories via the sidecar. The scan itself does not modify the remote.
At the end, you must check the process exit code, the main JSONL,.errors、.done and statistics. If errors exist, deliver a "partial scan"; do not deliver "full-disk complete".
Memory backup and restore reminder
The 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 the 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 restore the latest backup by default. - "Help me remember..." and "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 restoration are handled by the upstream script; 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 not supported 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 connections, atomic operations, and standardized scan input; it does not copy soia-pkm-alipan-curator specific actions for Alibaba Cloud Drive. The two providers can share the JSONL contract consumed by the curator, but the Baidu official CLI, Alibaba Cloud Drive CLI, and high-risk curation decisions should not be merged into a single trigger. If a Baidu version curator is needed in the future, the upper-layer inventory/catalog/plan approach should be reused, and capabilities should be injected through a provider adapter.
Logs and completion receipts
Every execution must report:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <CLI/版本/登录态检查,不打印秘密值>
- processed: <远端路径或扫描范围;数量如可得>
- created/updated: <数量或用户指定产物>
- skipped/failed: <数量和原因>
文件变化:
- <绝对路径或“未改动文件”>
验证:
- <whoami/ls/本地字节数/扫描 sidecar 等证据>
问题与下一步:
- <缺依赖、待确认事项或建议命令;没有则写“无”>
Verification evidence
- Static:
quick_validate.py skills/soia-pkm-baidu-netdisk-ops、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 using a real Baidu account; real runs still need to be executed according to the official login, user confirmation, and final-state review gates.