Customer-readable description
What this skill can do
Alibaba Cloud Drive atomic operations layer: install/log in to aliyunpan, explicit driveId dual-drive operations, directory browsing, move/rename/delete, download/upload, capacity query, full-disk JSONL scan. Serves as the underlying dependency of curator
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Complete the work covered by this skill | Read the user request, necessary context, and this skill's main-body process, and execute the minimal reliable steps | The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt. |
| Missing dependencies, permissions, configuration, or key | Stop actions requiring external state and clearly state what is missing | Installation commands, application addresses, configuration paths, or questions requiring customer confirmation |
| Execution completed | Summarize successes, skips, failures, file changes, and verification results | A completion receipt that can be copied into a ticket/log |
How the customer uses it
Other recognizable phrasings include "take a look at the cloud drive", "what's in the cloud drive", "the cloud drive login has expired"; when planning classification, indexing, or a learning path is needed, hand off to soia-pkm-alipan-curator。
- Describe the goal in natural language and provide necessary inputs: files, URL, repo, workspace, proposal, vault, or platform account status.
- For actions that support dry-run or preview, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek customer confirmation first.
Dependencies and installation
Install (recommended: install the entire domain plugin, installing all skills in this repo at once):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
If you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will have two indexes and drift independently, 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-alipan-drive-ops -y
Configuration conventions:
~/.config/soia-skills/soia-pkm-alipan-drive-ops/config.yml
SOIA_PKM_ALIPAN_DRIVE_OPS_CONFIG_FILE=<custom-config-path>
- If this skill does not need private configuration, you may skip creating
config.yml。 - If an API key, cookie, session, provider home, or local path is needed, it can only be placed in the private
config.yml, the process environment, or the provider's own login state; it must not be written into the repo, vault body, or logs. - Third-party skills may only declare dependencies and installation methods, and must not directly modify third-party skill files.
WorkBuddy The 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。
Private configuration loading and command entry point
The following commands are executed from this skill's directory; if the current directory differs, replace scripts/run_with_env.py with <skill-dir>/scripts/run_with_env.py. When running aliyunpan , prioritize using this skill's wrapper to load the private configuration, then execute the command:
python3 scripts/run_with_env.py -- aliyunpan who
python3 scripts/run_with_env.py -- aliyunpan quota
python3 scripts/run_with_env.py -- aliyunpan ls --driveId "$DRIVE_ID" "/目标目录/"
The wrapper will only launch aliyunpan、aliyunpan.exe or an absolute path whose basename is one of the two; it will reject env, shell, and any other arbitrary commands. The wrapper will read this skill's private config.yml 's env: mapping and load it in the subprocess
ALIYUNPAN_CONFIG_DIR. This way, the Homebrew-installed aliyunpan will also use the same specified login state, avoiding conflict with the default ~/.config/aliyunpan/ Form two separate sessions. The configuration file should only be read by the wrapper;alipan_env.py is only for scripts to load as a module; when run directly it does not output the configuration. Do not execute cat config.yml、env、printenv or set -x to troubleshoot the configuration.
Running aliyunpan <command> directly remains compatible, suitable for scenarios using the provider's default login state; however, once a private ALIYUNPAN_CONFIG_DIR is configured, prefer the wrapper above to avoid commands falling into the other login state. Logs and replies may only state whether the configuration exists or whether the command succeeded,must not print tokens, cookies, sessions, or the values of any environment variables。
Logs and completion receipts
Every execution must let the customer see the process and the result. Minimum receipt format:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>
文件变化:
- <绝对路径或“未改动文件”>
验证:
- <运行过的检查、命令或人工核对点>
问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>
Positioning
Benchmark against what weread-skills is to WeRead: provide onlyreliable atomic operations, and make no business judgments. High-level work such as organizing strategies and study plans is left to soia-pkm-alipan-curator。
Three onboarding steps (new user guidance)
# 1. 安装(macOS,brew 官方 formula)
brew install aliyunpan # 更新: brew upgrade aliyunpan
# 2. 登录(扫码,需用户本人在终端操作)
python3 scripts/run_with_env.py -- aliyunpan login
# 3. 验证
python3 scripts/run_with_env.py -- aliyunpan who
python3 scripts/run_with_env.py -- aliyunpan quota
If a private ALIYUNPAN_CONFIG_DIRhas not yet been configured, the above login and verification commands can also be written directly as aliyunpan login、aliyunpan who and aliyunpan quota。
Remote collaboration recovery for expired login
When a cloud drive command returns "login attempt failed, please use the login command to log in again", the login state is deemed expired; this is not a hard blocker requiring the user to scan a QR code at the terminal where the agent resides. Recover remotely as follows:
- In a non-interactive environment, start
python3 scripts/run_with_env.py -- aliyunpan loginwith a pty, and keep its stdin readable;must notredirect stdin to</dev/null, otherwise the login program reads EOF at "press Enter to continue" and fails. For the verifiedtail -fkeep-alive scheme and the complete command, see ops-playbook §1.4。 - Capture the authorization link completely from the pty output by "up to the space", and do not truncate it with a character whitelist regex:
scopeparameter contains:、,. Push only the complete link to the authorized user of this task themselves, and never print tokens, cookies, sessions, or other credentials. - Clearly state that the link is only 5 minutesvalid; after it expires, restart login and sendnew link, and do not let the user retry the old link. After the user completes both the authorization and QR code steps in the browser, confirm completion.
- Only after receiving user confirmation, feed one Enter to the keep-alive stdin so the login process continues; then use
python3 scripts/run_with_env.py -- aliyunpan whoto verify the returned UID, and clean up the correspondingtail -fhelper process. - Long tasks are continued via the existing ledger, progress, or checkpoint-resume mechanism; while waiting for authorization, prioritize work that does not depend on the cloud drive, and do not wait idle or rerun from the beginning. If the failure occurs during high-density concurrent listing, the resumed scan must reduce workers and comply with the at-least-300-ms throttling for batch listing; see ops-playbook "API rate limiting and 429 discipline"。
Discipline: never attempt to read, copy, or forward login credential files; the authorization link may only be sent to the authorized user of that task themselves.
Dual-drive model (key concept)
One account, two drives,sharing the same capacity quota(use aliyunpan quota to see the total):
- backup drive / resource library:
aliyunpan drivelists the DriveID of each drive - All
ls/mv/renameapplies only tothe current drive; cross-drive moves are not supported by the CLI and must be done manually in the App - ⚠️ Do not use
aliyunpan drive <driveId>for global switching: this command writes the global config, and when multiple agents/scripts run concurrently they will pollute each other's current drive context. The iron rule isevery command explicitly carries--driveId(e.g.aliyunpan ls --driveId <id> "/路径"), rather than switching first and then running commands with no drive parameter. Seereferences/ops-playbook.mdsection 1.5.
Common commands
| Operation | Command | Notes |
|---|---|---|
| List directory | aliyunpan ls "/路径" |
Quote Chinese paths |
| Move | aliyunpan mv "/源" "/目标目录/" |
Multiple sources supported; same drive only |
| Rename | aliyunpan rename "/旧全路径" "/新全路径" |
Must be within the same directory |
| Create directory | aliyunpan mkdir "/路径" |
One at a time is most reliable |
| Delete | aliyunpan rm "/路径" |
Goes to the recycle bin, recoverable for 30 days |
| Download | aliyunpan download "/路径" --saveto <本地目录> |
Large files take time; inform the user |
| Capacity | aliyunpan quota |
Remind the user to clean up at 87%+ |
Output parsing (required reading for scripting)
ls output is a table:序号 · 文件大小(目录为"-") · 日期 时间 · 名称(目录以/结尾,可能带尾随空格).
Reliable sed for extracting directory names:
aliyunpan ls "$DIR" </dev/null 2>/dev/null | \
sed -nE 's#^[[:space:]]+[0-9]+[[:space:]]+-[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}[[:space:]]+(.*)$#\1#p' | \
sed -E 's#[[:space:]]+$##; s#/$##'
- Inside loops, add
</dev/nullto all aliyunpan commands to prevent it from swallowing the while loop's stdin - After batch operationsmust verify the final state(re-check with ls), echoing "✓/✗" for each item
Safety rules (lessons from practice, must be followed)
- Do not blindly trust tool output: if physically impossible results appear (multiple entries with the same name in the same directory, line count contradicting byte count) → suspect output corruption, cross-verify via another channel (Read vs Bash), or ask the user to check in the App with their own eyes before continuing.
- Before deleting/overwriting, first look:
rmbeforelsconfirm the contents; name conflicts automatically get a(1)suffix—before moving, check whether the target already exists to avoid creatingxxx(1)duplicate directories. - Keep a human involved for high-risk operations: emptying directories, batch deletion, manual cross-drive migration—list the items and ask the user to confirm or do it themselves.
- Credentials: the login state belongs to the aliyunpan provider and by default is in
~/.config/aliyunpan/, do not move it into the skill, and do not cat-print the token. If you need to change the login state directory, put only theALIYUNPAN_CONFIG_DIRoverride into this skill's private config:~/.config/soia-skills/soia-pkm-alipan-drive-ops/config.yml(seeassets/config.example.yml). When running commands, prefer usingpython3 scripts/run_with_env.py -- aliyunpan <command>to load this override; no logs, diagnostic output, or final receipts may print the token or env values. - Confirm before deleting/moving/renaming: a matching path, an explicit skill invocation, or any default configuration is only a recommended input and does not constitute a reason to skip confirmation; the only condition for skipping is the customer's current sentence explicitly saying "delete directly/no confirmation needed", and after skipping you must state in the receipt the scope assumptions used this time.
- Probe with a small sample before batching: before batch
mv/rm/rename, first run it once with the smallest sample (e.g. 1 item) and report the estimated total; after the customer confirms the scale is correct, then proceed with full execution—do not go straight at a directory of unknown size. - Comply with rate limiting first, then recover: throttle batch write operations to 200–300 ms each, and batch listing to no less than 300 ms each; when you receive a 429, read
x-retry-afterand wait, never retry consecutively. See "API throttling and 429 discipline" in the ops-playbook.
In-depth practical playbook
Read this first when encountering the following scenarios references/ops-playbook.md(practical lessons consolidated from the 2026-07 cloud drive cleanup campaign); do not redo the trial and error:
- Installation/login details: two-step authorization + QR code scanning flow, the symptoms and handling of login state expiring in about 3 days, and the first step of standard remote recovery in non-interactive environments (pseudo-terminal pty / long-running process reading stdout); for the complete recovery flow see "Remote collaboration recovery for login expiration" above
--driveIdIron rule for explicit argument passing: why you must never usealiyunpan drive <id>to switch the global drive (concurrent multi-agent operation will pollute each other's current drive context)- Practical pitfalls of batch operations and throttling discipline: the cd dependency pitfall of batch rename, API buckets and 429 waiting,
llthe FILE ID in the output and how to construct the direct link, moving/renaming does not change file_id but cross-drive moves do change file_id, deletion goes to the recycle bin for 30 days and quota is only truly released when the recycle bin is emptied - CLI hard limitation with sibling directories of the same name:
ls/llonly addresses by path, and cannot enter one of them by file_id; after temporarily moving one out, the CLI cannot restore the dual same-name state as it was. Converge only when content-level evidence proves one side is redundant and the user has explicitly authorized deletion; otherwise suspend and wait for the user's naming decision or switch to the open API - Full-drive JSONL crawler:has been scripted as
scripts/scan_drive.py(parameterized DFS + thread pool + retries + resumable scanning + aggregate pruning + no drilling down into sensitive directories); output preserves the original consecutive spaces in directory names, and records file_id, size and SHA-1. Sibling directories of the same name will each be markedambiguous_name: trueand none will be drilled down,.errorsthe sidecar synchronously recordsAMBIGUOUS_NAME, making the consumer side fail-closed; for disambiguation, targeted rescans and irreversibility limitations see ops-playbook §2.7. For usage see ops-playbook §Three.Complete library pipeline =scan_drive.py(live drive→JSONL)→ alipan-curator'sgen_catalog.py(JSONL→collapsed tree overview + full-text search). For handling of the three pitfalls—transient login drops, the historical parser collapsing special spaces, and same-name shadowing—see the ops-playbook.scan_drive.pyproduced by.errors/.progress/.donesidecar is deliberately placed in the same directory and shares the same lifecycle as the--outmain output—resumable scanning (--resume) relies on the sidecar to locate progress (.donerecords line by line the directories that have been fully listed, and is the authoritative checkpoint for resuming scans), and quality verification must match up with the main output; this is by design, not an omission—do not move it to a temporary directory - Discipline against agent hangs: always write long content to files via scripts, and limit chat replies to 15 lines