SuperAPI AI Directory

soia-pkm-alipan-drive-ops

General & other

View repository

Updated 10-16 08:41

About this skill

soia-pkm-alipan-drive-ops — Alibaba Cloud Drive atomic operation layer

Customer-readable description

What this skill can do

Alibaba Cloud Drive atomic operation layer: install/login aliyunpan, explicit driveId dual-drive operations, directory browsing, move/rename/delete, download/upload, capacity query, full-drive 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 workflow, and execute the minimal reliable steps The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and a final receipt.
Missing dependencies, permissions, configuration, or key Stop actions that require external state, and clearly point out what is missing Install commands, application addresses, configuration paths, or questions that require customer confirmation
Execution complete 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

  1. State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
  2. The Agent first determines whether this skill is triggered, then checks dependencies, configuration, permissions, and risky actions.
  3. For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek customer confirmation first.
  4. After execution, verify the real output; do not substitute "looks successful" for evidence.
  5. The final reply must give the customer a visible summary: what was done, log summary, file changes, issues, and next steps.

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-alipan-drive-ops -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/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 may only be placed in private config.yml, the process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs.
  • Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md 's subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, first supplement the description or ask the customer, and do not guess.
  • Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.

Private configuration loading and command entry point

The following commands are executed from this skill's directory; if the current directory is different, 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 forming two sets of sessions with the default ~/.config/aliyunpan/ . The configuration file should only be read by the wrapper;alipan_env.py is only for scripts to load as a module, and running it directly will 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; but after configuring a private ALIYUNPAN_CONFIG_DIR , prefer using the wrapper above to avoid commands falling into another set of login states. 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 results. Minimum receipt format:

完成:<一句话说明本次完成了什么>。

日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化:
- <绝对路径或“未改动文件”>

验证:
- <运行过的检查、命令或人工核对点>

问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>

Positioning

Benchmark against what weread-skills is to WeRead: only providereliable atomic operations, without making 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 collaborative 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 determined to be expired; this is not a hard blocker requiring the user to scan a QR code at the terminal where the agent is located. Recover remotely according to the following process:

  1. 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 will fail by reading EOF at "Press Enter to continue". For the verified tail -f keep-alive solution and complete commands, see ops-playbook §1.4。
  2. Capture the authorization link completely from the pty output "up to the space"; do not truncate it with a character whitelist regex:scope parameter contains :、,. Only push the complete link to the authorized user of this task themselves, and never print tokens, cookies, sessions, or other credentials.
  3. Clearly inform that the link is only 5 minutesvalid; after expiration, restart login and sendnew link, and do not let the user retry the old link. After the user completes the two steps of authorization and QR code scanning in the browser, confirm completion.
  4. Only after receiving user confirmation, feed one Enter to the keep-alive stdin so that the login process continues; then use python3 scripts/run_with_env.py -- aliyunpan who to verify the returned UID, and clean up the corresponding tail -f helper process.
  5. Long tasks should be continued using 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 idly or rerun from the beginning. If the failure occurs during high-density concurrent listing, the resumed scan must reduce workers and comply with the throttling of at least 300 ms for batch listing; see ops-playbook "API Rate Limiting and 429 Discipline"。

Discipline: never attempt to read, copy, or forward login credential files; authorization links 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 drive List the DriveID of each drive
  • All ls/mv/rename only applies 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 without a drive parameter. See references/ops-playbook.md section 1.5.

Common commands

Operation Command Note
List directory aliyunpan ls "/路径" Quote paths containing Chinese characters
Move aliyunpan mv "/源" "/目标目录/" Supports multiple sources; 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 within 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 The 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#/$##'
  • Add </dev/nullto all aliyunpan commands inside the loop, to prevent them from swallowing the while loop's stdin
  • After batch operations,final-state verification is required(re-run ls to compare), echoing "✓/✗" for each item

Safety rules (lessons from practice, must be followed)

  1. Tool output cannot be blindly trusted: if physically impossible results appear (multiple items with the same name in the same directory, line count contradicting byte count) → suspect the output is polluted, cross-verify through another channel (Read vs Bash), or ask the user to check with their own eyes in the App before continuing.
  2. Before deleting/overwriting, look first:rm before ls to confirm the contents; name conflicts automatically get a (1) suffix—before moving, check whether the target already exists, to avoid creating xxx(1) duplicate directories.
  3. Keep a human in the loop for high-risk operations: emptying directories, batch deletion, manual cross-drive migration—list the items and ask the user to confirm or do it by hand.
  4. Credentials: the login state belongs to the aliyunpan provider, by default 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, only put the ALIYUNPAN_CONFIG_DIR override into this skill's private config: ~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-alipan-drive-ops/config.yml(see config.example.yml). When running commands, prefer using python3 scripts/run_with_env.py -- aliyunpan <command> to load this override; no log, diagnostic output, or final receipt may print the token or env values.
  5. Confirm before deleting/moving/renaming: a matched path, an explicit skill invocation, or any default config is only a recommended input and does not constitute a reason to skip confirmation; the only condition for skipping is when the customer's current sentence explicitly says "delete directly/no need to confirm", and after skipping you must state in the receipt the scope assumptions followed this time.
  6. Probe with a small sample before batching: before batch mv/rm/rename , first run through 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.
  7. Obey rate limiting first, then recover: Batch write operations are throttled to 200–300 ms each time, and batch listing is no less than 300 ms each time; upon receiving 429, read x-retry-after and wait, never retry consecutively. See the "API Rate Limiting and 429 Discipline" section of the ops-playbook for details.

In-Depth Practical Handbook

When encountering the following scenarios, first read references/ops-playbook.md(distilled from the 2026-07 cloud drive organization campaign), and do not redo trial and error:

  • Installation/login details: two-step authorization + QR code scanning process, the symptoms and handling of login state expiring after 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 process, see "Remote Collaboration Recovery for Login Expiration" above
  • --driveId The iron rule of explicit parameter passing: why you must never use aliyunpan drive <id> to switch the global drive (multiple agents running concurrently will pollute each other's current drive context)
  • Practical pitfalls of batch operations and rate-limiting discipline: the cd dependency pitfall of batch rename, API buckets and 429 waiting,ll the FILE ID in the output and how to construct the direct link, moving and 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
  • Full-drive JSONL crawler:has been scripted as scripts/scan_drive.py(parameterized DFS + thread pool + retry + resumable scan + aggregate pruning + no descending into sensitive directories); the output preserves the original consecutive spaces in directory names, and records file_id, size, and SHA-1. Sibling directories with the same name will each be marked ambiguous_name: true and none will be descended into,.errors the sidecar synchronously records AMBIGUOUS_NAME, making the consumer side fail-closed; you must first rename to disambiguate, then rescan that subtree in a targeted manner. For usage, see ops-playbook §3.Complete library pipeline = scan_drive.py(live drive→JSONL) → alipan-curator's gen_catalog.py(JSONL→collapsed tree overview + full-text search). For handling of the three pitfalls—instant login disconnection, the historical parser collapsing special spaces, and same-name shadowing—see the ops-playbook.scan_drive.py produced by .errors/.progress/.done the sidecar is deliberately placed in the same directory and has the same lifecycle as --out the main output—resumable scanning (--resume) relies on the sidecar to locate progress (.done records line by line the directories that have been completely listed, and is the authoritative checkpoint for resuming the scan), and quality verification must match the main output; this is by design, not an omission, so do not move it to a temporary directory
  • Discipline for preventing agent hangs: always write long content to files via scripts, and limit conversational replies to 15 lines