PikPak 单资源管道
语言 / Language: 本 skill 的说明、帮助文本与错误信息以简体中文为主，面向中文用户；这是有意的区域定位，不是强制。仓库同时提供英文 README（README.en.md），英文用户可据此了解全部能力边界；脚本的机器可读输出（--json、-F json）与退出码不依赖语言，可直接被其他语言的调用方解析。如需其他语言的支持，请以机器可读输出为准，不要把中文提示文本作为程序接口。
This skill's documentation, help text and error messages are primarily Simplified Chinese and target a Chinese-speaking audience by design. English readers can use README.en.md for the full capability and limitation overview. Machine-readable output (--json, -F json) and exit codes are language-independent and are the supported interface for non-Chinese callers.
本地执行器，不是“来去无痕迹”服务。一项资源一个 --state 文件；同一状态文件记录来源指纹→task ID→file ID→本地路径/大小/SHA-256，并记录非敏感 account scope 别名、account_scope_binding=operator_declared_unverified 和当前登录身份的域隔离 SHA-256。别名只是操作者声明，不是身份验证；脚本只接受 auth status -F json 白名单位置中的稳定账号 ID，缺失或冲突就停止，不回显或保存原值。正式 CLI 的实际 JSON 字段尚未按真实账号验收确认，中性假 CLI 不代表实盘兼容。
本地执行环境与文案边界
PIKPAK_BIN、PATH、Python 解释器、脚本文件及其父目录必须由当前操作者控制；子进程默认继承环境。不要在不可信 CI、多租户或提权服务中直接运行，除非宿主已固定并核验可执行文件与环境。仓库不假称 permissions / allowed-tools 等 frontmatter 字段会被所有宿主强制执行；实际最小权限由部署宿主负责。
命令帮助和错误摘要可能是中文；这是当前 CLI 适配器的文案事实，不代表强制用户语言。Agent 应按用户语言解释结构化结果，不应为降低扫描告警而删除安全校验或伪造国际化。
使用前
先取得用户对当前本人账号、资源、目标目录、云写入与本地下载的明确授权。--account-scope <别名> 只记录操作者声明；step1/2/3/4 每次都必须显式传入与收据相同的别名，并重新读取当前登录身份哈希，缺失、旧收据缺身份收据、不一致或 logged_in 但没有稳定 ID 都拒绝。来源不明账号不查询。脚本每一步都会运行 auth status -F json；没有账号授权或 CLI 未返回受支持的稳定 ID 时不要启动。--help 不访问账号。注册/安装由用户自己完成。
以下命令从本 skill 目录运行；所有步骤保持同一个状态文件。链接是用户确认的合法来源，不提供未核验演示 magnet。
python3 scripts/magnet_pipeline.py step1-add '<授权链接>' --account-scope <当前账号别名> --state ./job-1.json
# 可加 --folder <folderID>；本 CLI 不支持 add 改名，已删除无效 --name
python3 scripts/magnet_pipeline.py step2-status <返回的taskID> --account-scope <同一账号别名> --state ./job-1.json
python3 scripts/magnet_pipeline.py step3-download <确认的fileID> --dest ./downloads --account-scope <同一账号别名> --state ./job-1.json
# 只有用户确认本地内容正确后才加此标记；仍然不执行任何删除
python3 scripts/magnet_pipeline.py step4-cleanup <同一fileID> --verified-local --account-scope <同一账号别名> --state ./job-1.json
可验证状态与故障出口
| 状态/情形 | 行为与恢复 |
|---|---|
| 首次 add | 调用前原子记录 submitting；返回有效 ID 才记 submitted |
| 相同链接+目录再 add | 复用已记录 task ID，不发第二次创建 |
| 换链接/目录却复用 state | 拒绝；新资源请显式选择新状态文件 |
| add 超时/退出码异常/响应缺 ID | 保留 submitting；可能已经创建，禁止盲目再 add |
| status | state 必须已有完整 fingerprint/目录/有效 task ID/account scope 且与请求严格一致；缺 ID 在 task get 前拒绝，不自动认领；响应中外层/嵌套 task_id/id/file_id 若冲突、status/phase 规范化后冲突、字段畸形或显式 ok=false/success=false/error 均失败；旧 ready/downloaded 收据遇此类观察会安全撤销为 blocked，保留本地收据但不能继续下载/清理 |
| task get 超时/查询失败 | CLI 超时以退出分类 124 返回给 step2；旧 ready/downloaded 撤销为 blocked，移除 latest_task_status=complete，记录 query_failure；保留来源/目录/账号/task/file 绑定和本地字节/收据；再次同一有效 complete 并核验本地收据前阻止下载与清理 |
| pending/running | 记录 latest_task_status 与 waiting；保留原 file ID 和本地收据，但撤销下载/清理资格；单次退出，无无限循环 |
| error | 保留 failed，退出 2，不自动删任务/重提 |
| complete | 记录 latest_task_status=complete 与确切 file ID；同一 file ID 的本地大小/hash 复核成功可恢复 downloaded，否则 ready；新 file ID 不继承旧本地收据；指定 folder 若响应没有可核验目录字段则标记 folder_verification=unknown，并同时阻止下载与清理；有字段则必须与请求 folder 严格一致 |
| folder fields | 仅对响应实际提供的 folder_id/parent_id 等已出现字段做一致性检查；多个字段冲突拒绝。未核证官方 schema，不把 mock/第三方字段当平台保证 |
| response errors | 只输出错误分类，不回显响应正文、message、URL 或 token；不把同时存在的陈旧成功字段当作成功 |
| download 失败 | 非零退出；保留 .part，不换目的地，不生成清理建议 |
| 下载退出 0 但没实际普通文件 | 拒绝记成功，不生成清理建议 |
| 清理 | 完整来源/task ID/file ID/account scope 绑定、最近有效观察仍 complete、目录绑定为 matched（未指定 folder 除外）、已下载且 ID 唯一匹配、本地大小/SHA-256 未变、--verified-local 才打印；只打印，不删除 |
submitting 的人工恢复：先停止写入并保存状态副本，在官方界面对账原链接、目录、时间、当前账号与确切 task ID；不要按文件名/首个任务猜。只有用户确认当前 CLI 返回的稳定账号 ID 与原收据属于同一账号后，才可在本地私密状态副本保留原 fingerprint、同一非敏感 account scope、account_scope_binding=operator_declared_unverified 和身份哈希，补 task_id 并置 stage 为 submitted（version 保持 1）；缺 scope、声明标记或身份哈希的旧收据不得静默补写。之后每一步仍须显式传入该 scope 并重新核对身份再跑 step2。脚本没有自动认领或跨账号恢复；无法核对就停，不新建 state 绕过去重。
step3/4 不接受孤立的 ready/downloaded 标志；两步都要显式传入与收据一致的 account scope，并且收据必须带 account_scope_binding=operator_declared_unverified 与当前身份哈希。旧收据缺少 latest_task_status、account scope、声明标记或身份收据时，先停并人工核对，不能手填 complete/scope/身份绕过；pending/running 或查询超时后即便本地文件还在，也须重新观察同一 complete 并核验收据才恢复资格。指定 folder 但观察不到可核验目录字段时虽可标 unknown，但 step3 下载和 step4 清理都会阻止，不能生成清理预览。
CLI 入口用独占 .lock 防同一 state 并发；崩溃遗留锁不自动抢占，用户核对进程与远端后再移走旧锁。同一资源使用不同 state/机器仍可能重复，本地防重复不是服务端幂等键/全局 exactly-once。状态文件不包含原始 URL/凭据，但仍应私密保留，不放分享目录。
下载收据的真实含义
download -o 接受完整输出文件，不是目录。本脚本用 <dest>/<fileID>.part 下载，成功后不覆盖地落为 <dest>/<fileID>，保留原 ID 命名避免文件名注入/碰撞；不会失败后去掉 -o 偷偷下载到 cwd。已有目标/中断文件不覆盖，人工核验或移走后重试，不承诺断点续传。文件夹/多文件 BT 未实现，使用批量备份。
本地 SHA-256 只证明“清理预览时仍是下载后同一份字节”，不证明与服务端源内容一致。仍需用户核对来源、大小、可用的可信校验值/内容；输出为 downloaded_unverified，不能把 CLI 退出 0 当成完整性证明。不支持恶意本地用户并发替换文件的威胁模型。
清理边界
step4 先只读 auth status -F json 核对当前身份摘要；不查询 task/file、不回读云对象、不删除。必须使用本次收据的唯一 file ID、匹配的 account scope 和身份哈希，以及（若指定 folder）已验证为 matched 的目录；全部 ID 验证后才打印，不能传 shell 片段。账号切换拒绝已在受支持字段的中性 fixture 合同内验证，官方稳定 ID 字段的真实 schema 尚未验收；不能因此移除身份门禁或声称真实账号兼容。最后执行删除仍是独立的用户授权动作；人工执行前核对当前账号和云端对象。
pikpak rm --help 只写“删除”，未保证回收站、可恢复或立即释放容量。本脚本不会清空回收站、不会用 task rm --delete-files、也不会承诺“云端不留痕迹”。跨设备账号变化不能靠本地收据验证，清理预览不是自动执行授权。
机制来源、固定许可证、发行证据与不采纳项见同目录下 references/upstream-design.md（纯 Markdown 文本，随本 skill 一同分发，可直接用文本编辑器完整阅读；其中不含脚本、不联网、不在运行时执行任何外部请求）。rclone 为 MIT，固定研读快照与发行 tag 的祖先关系未核验；AutoOfflineDownloadBot 许可未确认，仅作行为对照，不复制代码、不安装运行。
引荐披露 / Referral disclosure
本套 skill 的公开邀请码是 22874035，来自分享者；使用可能让分享者获得推广奖励，福利以 PikPak 官方页面为准。你可以拒绝，不影响本 skill。
This public referral code is 22874035. It may reward the sharer; benefits follow PikPak's official page. You can decline without affecting this skill.
本 skill 不自动注册、登录或改变账号。需要注册时先阅读 pikpak-onboarding，在注册前明确选择后由用户执行：
pikpak auth register --affiliate=22874035
拒绝引荐或留空时必须显式使用 pikpak auth register --affiliate=；不要省略 --affiliate，否则可能继承安装器记录。