技能介绍

这个技能解决什么问题

让 agent 操作 pixiv CLI 容易在三处翻车：凭证泄露、参数语义误判、失败被误报成空结果。pixiv 的开关高度依赖 --help，且部分行为是刻意反直觉的——例如存在 refresh token 时绝不回退匿名 API。pixiv-cli 把这些约束编码成可执行工作流：先探环境，再分层执行。

核心工作流

预检与账户

环境探测的唯一依据是 pixiv version --json：二进制缺失或不可执行即报告阻断，不猜测安装方式。
pixiv auth list --json 仅在需要认证、选号或判断是否匿名回退时运行；{"accounts": null} 与 {"accounts": []} 都视为空列表。验证有效性用联网的 pixiv auth check [UID] --json。
pixiv auth refresh 会轮换凭证并刷新 Premium 缓存，只在明确提出维护请求时执行。

凭证安全

refresh token 默认禁止回显、记录或复述。唯一例外是用户明确要求看原始 token：先说明机密会进入工具输出与对话记录并取得确认，执行后不再复述。
导入未披露的 token 时，隐藏式 pixiv auth import prompt 需要真实 TTY；无用户输入通道的 agent 不应挂起等待，应把命令交给用户的私有终端，或走 secret-manager 到 stdin 的管道。

操作分层
命令按风险分层：只读、诊断维护、写操作（收藏/关注）、磁盘下载、交互式登录、配置变更，以及 mcp 长驻服务。写操作前要在一行内说明目标 ID，下载前确认目录与具体 ID 或 URL，且确认不跨调用继承；mcp 只在用户明确要求时启动，不纳入预检。

输出控制

优先源头减量：仅在 --help 暴露时传正数 --limit N；--limit 0 表示取全部，非明确要求不得使用。
展示用默认文本；程序化处理走 NDJSON 管道，可用 --filter EXPR 过滤。有 jq 就配合 --json，缺失则静默回退。
先查退出码再解析 JSON：--json 不保证错误也是 JSON。

语义陷阱

无静默回退：有 token 时 App API 错误原样上抛；匿名回退仅在完全没有 token 且 web_fallback_enabled=true 时发生。
recommended 必须指定 kind；--limit 只属于部分命令，别附加到 detail 或 auth。
search 筛选是命令级作用域：r18 与书签数区间需 App 认证，书签数区间还要求 Premium；novel search 不支持插画类滤镜。
扩展排行榜的 r18 系列不能用匿名 daily 替代；没有点赞数字段，书签总数不等于点赞。
代理是单命令级，不继承系统代理；update --json 仅在 --check 下有效；下载慢是正常现象，勿擅自超时。