SuperAPI AI Directory

soia-pkm-baidupan

General & other

View repository

Updated 10-16 09:29

About this skill

soia-pkm-baidupan — Baidu Netdisk atomic operation layer

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:

  1. Installed by upstream scripts/install.sh installs bdpan(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).
  2. Login only uses upstream scripts/login.sh. Do not let the Agent directly execute bdpan login, and do not enter the account, password, verification code, or authorization code on behalf of the user.
  3. Run bdpan whoami to 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.yml
    

    Can 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 private config.yml back into the repository.

  • The only configuration options are provider: official|community and the optional binary: bdpan|baidupan-cli。binary is only used to select the CLI; by default it is selected according to provider .

  • The official provider configuration is maintained by bdpan itself in ~/.config/bdpan/config.json. The Agent does not read, print or copy this file, and does not actively set BDPAN_CONFIG_PATH、BDPAN_BIN or BDPAN_INSTALL_DIR。

  • The community provider reads only from the private configuration's env: to read BAIDUPAN_APP_KEY、BAIDUPAN_APP_SECRET、BAIDUPAN_APP_NAME and the optional BAIDUPAN_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.

  • bdpan The JSON fields of fs_id、server_filename、isdir、size、md5、server_mtime are 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 call bdpan 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.py use a temporary fake CLI to verify official JSON fields, two-level directory conversion, clean JSONL,.errors and .done sidecar; 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.