SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-pkm-alipan

soia-pkm-alipan

Office & productivity

View repository

Updated 10-16 07:12

About this skill

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

Customer-readable description

What this skill can do

Alibaba Cloud Drive atomic operation layer: install/log in to 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

What the customer wants What the skill will do What the customer can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, 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 that require external state, and clearly state what is missing Installation 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 -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-alipan/config.yml
SOIA_PKM_ALIPAN_CONFIG_FILE=<custom-config-path>
  • If this skill does not require private configuration, you may skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is required, 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 and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly stated, 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.

Logs and completion receipt

Every execution must let the customer see the process and results. Minimum receipt format:

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

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

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

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

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

Positioning

Benchmark against weread-skills for WeChat Reading: only providereliable atomic operations, and do not make business judgments. Higher-level work such as organizing strategies and study plans is left to soia-pkm-alipan-curator。

Three-step onboarding (new user guidance)

# 1. 安装（macOS，brew 官方 formula）
brew install aliyunpan          # 更新: brew upgrade aliyunpan
# 2. 登录（扫码，需用户本人在终端操作）
aliyunpan login
# 3. 验证
aliyunpan who && aliyunpan quota

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 to the global config, and when multiple agents/scripts run concurrently they will pollute each other's current drive context. The iron rule isevery command must explicitly include --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 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 it from swallowing the while loop's stdin
  • After batch operationsmust verify the final state(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 verify with their own eyes in the App before continuing.
  2. Before deleting/overwriting, first look：rm before ls to confirm the content; name conflicts automatically get a (1) suffix—check whether the target already exists before moving, 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 themselves.
  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/config.yml(see config.example.yml）。
  5. Confirm before deleting/moving/renaming: the matched path, explicit skill invocation, and any default config are only recommended inputs and do not constitute a reason to skip confirmation; the only condition for skipping is that the customer's current message explicitly says "delete directly/no need to confirm"; after skipping, state in the receipt the scope assumptions used this time.
  6. Probe with a small sample before batching: before batch mv/rm/rename , first run a minimal sample (e.g. 1 item) and report the estimated total; after the customer confirms the scale is correct, proceed with the full execution—do not go straight at a directory of unknown size.

In-depth practical manual

When encountering the following scenarios, first read references/ops-playbook.md(July 2026 cloud drive cleanup campaign practical takeaways), do not re-trial-and-error:

  • Installation/login details: two-step authorization + QR code scanning flow, symptoms and handling of login session expiring in about 3 days, tips for obtaining the QR code link in a non-interactive environment (no real TTY) (pseudo-terminal pty / long-running process reading stdout)
  • --driveId The iron rule of explicit argument 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: the cd dependency pitfall of batch rename and recovery methods,ll the FILE ID and direct link concatenation method in the output, 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 freed when the recycle bin is emptied
  • Full-drive JSONL crawler:Already scripted as scripts/scan_drive.py(parameterized DFS + thread pool + retry + 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. See ops-playbook §3 for usage.Complete library pipeline = scan_drive.py(live drive→JSONL)→ alipan-curator's gen_catalog.py(JSONL→collapsed tree overview + full-text search). See ops-playbook for handling of the two pitfalls: momentary login disconnection and the history parser collapsing special spaces.scan_drive.py The produced .errors/.progress sidecar is deliberately in the same directory and same lifecycle as the --out main output—resumable scanning (--resume) relies on the sidecar to locate progress, and quality verification must match the main output; this is by design, not an omission, do not move it to a temporary directory
  • Discipline for preventing agent hangs: always write long content to files via scripts, limit conversational replies to 15 lines