autoverse-cli

Autoverse CLI

Autoverse 的系统层 Skill。只负责让 Agent 正确安装、登录、发现和调用 CLI。

产品链路：

scholar-relay API → autoverse CLI

CLI 是唯一稳定执行面。

何时使用

使用本 Skill：

• 用户要安装、升级或验证 autoverse；
• 要登录、退出、切换 profile 或检查身份；
• 要查看点数、价目或补点入口；
• 要了解命令、旗标、JSON、退出码或错误 code；
• CLI 调用失败，需要按结构化错误恢复；
• 开发/CI 需要平台 Key，而不是浏览器会话。

不要因普通“找论文、做开题、沿种子扩展”请求单独触发；本 Skill 不定义科研作业流程或产物。

安装与版本

pipx install autoverse
autoverse --version
autoverse --help

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

如果用户明确要升级：

pipx upgrade autoverse

登录与凭证

默认登录：

autoverse login
autoverse whoami

• 浏览器由人完成邮箱或 GitHub 确认。
• 凭证进入 OS 钥匙串；不要写入论文项目、Skill 或对话。
• 不索要或打印 API Key。
• CI / 脚本明确需要平台 Key 时，才使用 AUTOVERSE_API_KEY 或 login --token。
• --profile <name> 是全局旗标，放在动词前；不同 profile 使用独立凭证。

Agent 标准调用

Agent 和自动化调用固定为：

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

• stdout 成功时只有一行 {request_id,data}；
• stderr 成功时为空；
• 失败时 stdout 为空，stderr 只有一行 {error:{code,message,request_id,retryable}}；
• 只根据 code、retryable 和退出码分支，不解析自然语言日志；
• 用法/输入错误退出 2，运行时/鉴权/点数/上游错误退出 1；
• 支持使用 --fields 进行源头按需字段投影，完整公开 API 的高级调试走 api 逃生舱。

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

功能分类与原子命令

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

1. 账户与认证

• autoverse login：发起 OAuth 浏览器授权登录；
• autoverse whoami：展示当前登录身份与剩余点数；
• autoverse logout：清除本地登录凭证。

2. 点数与充值

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

3. 文献与作者检索

• 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>：沿参考文献、施引文献或相似推荐扩展。

4. 参考文献导出

• 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：属于业务或参数硬限制，立即终止，不盲目猜试参数或更换接口。