安装与版本

pipx install autoverse
autoverse --version
autoverse --help

要求 Python 3.12+。包名和命令都是 autoverse。

如果用户明确要升级：

pipx upgrade autoverse

登录与凭证

默认登录：

autoverse login
autoverse whoami

Agent 和自动化调用固定为：

autoverse --json --quiet <动词> ...

用户问具体命令、字段或错误时，读取 references/commands.md。

本 Skill 只提供原子能力合同，不包含任何串行科研作业流程；跨命令的选题调研或引文扩展应由专属业务 Skill 按需调度。

autoverse usage：查看当前可用点数与各命令计费单价；
autoverse topup：查看套餐与充值引导；
autoverse topup --plan <plus|pro|ultra|test>：发起企业支付宝直连充值，自动生成标准 PNG 二维码（~/.config/autoverse/alipay_qr.png）并拉起浏览器收银台，静默轮询到账。

autoverse search "<query>"：按题名、关键词与多维学术条件检索（支持 --limit、--domain、--mode、--year-from、--year-to、--exclude、--ccf、--cast、--pku、--cscd、--cssci、--abdc、--cas、--jcr、--directory、--conference、--journal、--author、--oa、--title-only、--detailed、--fields）；
autoverse resolve <identifier>：通过 DOI、PMID、ArXiv ID 等稳定标识符解析单篇文献元数据；
autoverse batch -f <file>：批量解析文件中的标识符列表（1–50 条）；
autoverse authors "<name>"：检索作者主页与历史发文；
autoverse related <id> --via <references|cited-by|similar>：沿参考文献、施引文献或相似推荐扩展。

autoverse export --format <ris|bibtex|markdown> -f <json-file>：将检索保存的 JSON 结果在本地导出为标准题录格式（0 点数，无需网络）。

CLI 错误统一在 stderr 格式化输出为 JSON：{"error": {"code": "...", "message": "...", "retryable": bool, "request_id": "..."}}，遵循以下恢复规则：

INVALID_SESSION / NOT_AUTHENTICATED / 401：会话已过期或未登录，指导用户运行 autoverse login 完成认证。
INSUFFICIENT_CREDITS / 402：点数不足，先执行 autoverse usage 确认余额，再提示 autoverse topup 充值，不可静默重试。
REQUEST_OUTCOME_UNKNOWN：网络超时且调用已生成幂等键，先运行 autoverse usage 或 whoami 核验是否扣点/成功，不直接重发写请求。
ALL_SOURCES_UNAVAILABLE：上游学术源暂时限流或无法连接；若 retryable=true 最多再重试一次，仍失败则停止，不得将故障谎报为“检索到 0 篇”。
CURSOR_OPTION_CONFLICT：翻页参数冲突，带 cursor 时只能指定可选的 --limit，不得同时传入新搜索条件。
UNKNOWN_PLAN：充值套餐代码无效，只可选 plus, pro, ultra, test。
INPUT_FILE_*：批量输入文件不存在或编码非 UTF-8，修正文件路径与内容后重试。
OUTPUT_FILE_*：输出目标路径不可写或目录不存在，换合法路径重试。
RELATED_ID_*：引文关联仅接受规范的学术论文内部 ID，不可传入原始 DOI 或含斜杠字串。
retryable=true：属于瞬态网络或服务端抖动，同一逻辑调用最多重试 1 次。
retryable=false：属于业务或参数硬限制，立即终止，不盲目猜试参数或更换接口。