用途
soia-pkm-alipan 是一个面向阿里云盘的原子操作层技能，对标 weread-skills 之于微信读书的定位：只提供可靠的原子操作，不做业务判断。整理策略、学习计划等高阶工作交给 soia-pkm-alipan-curator，本技能作为 curator 的底层依赖存在。
触发场景包括：「看下云盘」「云盘里有什么」「登录阿里云盘」「下载云盘文件」「云盘登录过期了」「全盘扫描云盘」等。
主要能力
技能覆盖的操作为：安装/登录 aliyunpan、显式 driveId 双盘操作、目录浏览、移动/重命名/删除、下载上传、容量查询、全盘 JSONL 扫描。
常用命令与注意事项：
- 列目录：
aliyunpan ls "/路径"，中文路径需加引号 - 移动：
aliyunpan mv "/源" "/目标目录/"，支持多源，只能同盘 - 重命名：
aliyunpan rename "/旧全路径" "/新全路径"，必须同目录内 - 建目录：
aliyunpan mkdir "/路径"，一次一个最稳 - 删除：
aliyunpan rm "/路径"，进回收站，30 天可恢复 - 下载：
aliyunpan download "/路径" --saveto <本地目录>，大文件耗时，需告知用户 - 容量：
aliyunpan quota，87% 以上时提醒用户清理
使用方式
接入三步（新用户引导）：
# 1. 安装（macOS，brew 官方 formula）
brew install aliyunpan # 更新: brew upgrade aliyunpan
# 2. 登录（扫码，需用户本人在终端操作）
aliyunpan login
# 3. 验证
aliyunpan who && aliyunpan quota
安装本技能（单个技能）：
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-alipan -y
配置约定路径为 ~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-alipan/config.yml，也可通过环境变量 SOIA_PKM_ALIPAN_CONFIG_FILE=<custom-config-path> 指定自定义配置。如果本技能不需要私有配置，可以不创建 config.yml。需要 API key、cookie、session、provider home 或本机路径时，只能放进私有 config.yml、进程环境或 provider 自己的登录态里，不能写进仓库、vault 正文或日志。
双盘模型（关键概念）
一个账号两个盘，共享同一容量配额（用 aliyunpan quota 看总量）：备份盘 / 资源库，可用 aliyunpan drive 列出各盘 DriveID。所有 ls/mv/rename 只作用于当前盘，跨盘移动 CLI 不支持，需在 App 里手动操作。
注意：不要用 aliyunpan drive <driveId> 做全局切换，该命令会写全局配置，多代理/多脚本并发时会互相污染当前盘上下文。铁律是每条命令都显式带 --driveId（如 aliyunpan ls --driveId <id> "/路径"），而不是切换后再跑无盘参数的命令。
输出解析与脚本化
ls 输出为表格：序号 · 文件大小(目录为"-") · 日期 时间 · 名称(目录以/结尾，可能带尾随空格)。提取目录名的可靠 sed 方式、循环内所有 aliyunpan 命令加 </dev/null、批量操作后终态验证（重新 ls 对照）等细节在资料中给出。批量操作后逐条回显"✓/✗"。
安全守则（实战教训）
- 工具输出不可盲信：出现物理不可能的结果（同目录同名多项、行数与字节矛盾）→ 疑似输出被污染，换通道交叉验证（Read vs Bash），或请用户在 App 亲眼核对后再继续。
- 删除/覆盖前先看：rm 前先 ls 确认内容；同名冲突会自动加 (1) 后缀，移动前查目标是否已存在。
- 高危操作留人：清空目录、批量删除、跨盘手动迁移，列清单请用户确认或亲手操作。
- 凭据：登录态属于 aliyunpan provider，默认在 ~/.config/aliyunpan/，不要搬进 skill，也不要 cat 打印 token。若需要改登录态目录，只把 ALIYUNPAN_CONFIG_DIR 这个 override 放进本技能私有配置。
- 删除/移动/重命名前先确认：命中路径、显式技能调用、任何默认配置都只是推荐输入，唯一跳过条件是客户当前这句话明确说"直接删/不用确认"，跳过后要在回执里说明本次沿用的范围假设。
- 批量前先小样本探测：批量 mv/rm/rename 前，先用最小样本（如 1 条）跑一遍并汇报预计总量，客户确认规模无误后再放开全量执行。
深入实战手册
遇到特定场景时建议先读 references/ops-playbook.md（2026-07 云盘整理战役实战沉淀），内容包括：安装/登录细节（两步授权+扫码流程、登录态约 3 天过期的症状与处理、非交互环境取二维码链接的技巧）、--driveId 显式传参铁律、批量操作实战坑（批量 rename 的 cd 依赖坑与恢复方法、ll 输出里的 FILE ID 与直达链接拼法、移动改名不改 file_id 但跨盘移动会换 file_id、删除进回收站 30 天且回收站清空才真正释放配额）、全盘 JSONL 爬虫（已脚本化为 scripts/scan_drive.py，参数化 DFS + 线程池 + 重试 + 断点续扫 + 聚合剪枝 + 敏感目录不下钻；输出保留目录名原始连续空格，并记录 file_id、大小与 SHA-1）、防代理卡死纪律（长内容一律脚本落文件、对话回复限 15 行）。
完整图书馆流水线 = scan_drive.py（实盘→JSONL）→ alipan-curator 的 gen_catalog.py（JSONL→折叠树总览+全文检索）。scan_drive.py 产出的 .errors/.progress sidecar 刻意与 --out 主产出同目录、同生命周期，用于断点续扫（--resume）定位进度与质量核对，不要挪去临时目录。
回执与日志
每次执行都要让客户看见过程和结果，最低回执格式包括完成说明、日志摘要（started/processed/created/updated/skipped/failed）、文件变化、验证、问题与下一步。回执中不打印秘密值。
限制
跨盘移动 CLI 不支持，需在 App 内手动操作；删除操作进回收站，30 天可恢复，回收站清空后才真正释放配额；登录态约 3 天过期，需重新登录；大文件下载耗时，需提前告知用户。资料未提供收费、价格与具体平台支持范围等信息。