scimaster-cli

命令行版的 SciMaster 文献检索工具。通过 PasaMaster 上游服务搜索学术论文，一行命令拿到论文清单 + BibTeX。

升级到 0.3.0（breaking change）

0.3.0 把 sci search 与 muse-api 的交互改成异步轮询模式，根治网关 504：

• POST /openapi/v1/paper_search 立刻返回 task_id（< 2s）
• CLI 每 3s 轮询 GET /openapi/v1/paper_search/{task_id}，命中 done / failed 后退出循环
• 整轮搜索上限 30 分钟（与 muse-api max_wait_seconds 对齐）
• 终端会同行刷新 ⏳ 已等待 Ns（轮询 #M） 进度；首次 Ctrl+C 友好停止，再按一次硬退出

升级方法详见下方 更新 章节。

0.2.x 与新版 muse-api 不兼容（POST 响应字段从 papers 变成 task_id），如果你的 muse-api 已经更新，必须升级到 0.3.0；反之 0.3.0 也要求 muse-api 同步部署本次改造。

安装

全局安装

npm install -g scimaster-cli
sci --help

直接通过 npx 运行（无需安装）

npx scimaster-cli search "CRISPR gene editing"

注：bin 名为 sci，包名为 scimaster-cli。npx scimaster-cli 会自动映射到唯一的 sci 入口。

环境要求

• Node.js ≥ 20

更新

查看当前版本：

sci --version

全局安装方式

npm install -g scimaster-cli@latest
sci --version    # 验证

也可以锁定具体版本：

npm install -g [email protected]

npx 方式

npx 会把包缓存到 ~/.npm/_npx，老版本可能被复用。两种办法强制拿到最新版：

# A. 清缓存（最稳）
rm -rf ~/.npm/_npx
npx -y scimaster-cli@latest sci --version

# B. 显式指定 package（npx 1.0+）
npx -y --package=scimaster-cli@latest sci --version

开发版 / 未发布改动（贡献代码、本地联调）

git clone https://github.com/scimaster/scimaster-cli.git
cd scimaster-cli && npm install && npm run build
npm link    # 把全局 sci / sci-mcp 软链到当前 workspace
sci --version

之后修改 src/ 下任意文件 → npm run build → 全局 sci 命令立刻生效，不用重新 npm link。要切回 npm 正式版：

npm unlink -g scimaster-cli
npm install -g scimaster-cli@latest

~/.scimaster/config.json（API Key / env / 默认档位）跟随用户主目录，升级不会丢。新版本新增的字段会按默认值兜底。

快速开始

# 1. 配置 API Key（首次使用）
sci init

# 2. 选择 muse-api 环境（local / test / uat / prod）
sci env test

# 3. 选择 PasaMaster 搜索档位（影响是否扣费）
sci model              # 交互式选择
sci model low          # 或直接指定

# 4. 搜索论文
sci search "CRISPR gene editing 2024"
sci search "machine learning protein" --limit 20
sci search "cancer immunotherapy" --mode mid --out ./papers

命令速查

sci init

交互式配置 API Key。已有 Key 会询问是否覆盖。

sci env [name]

切换 muse-api 后端环境，预设：

| 别名 | URL | |------|-----| | local | http://127.0.0.1:8000 | | test | https://scimaster.test.bohrium.com | | uat | https://scimaster.uat.bohrium.com | | prod | https://scimaster.bohrium.com |

sci env              # 交互式选择
sci env prod         # 直接切到 prod
sci env --show       # 查看当前环境

切换环境不会清空 API Key——不同环境的 Key 通常不通用，必要时重新跑 sci init。

sci model [mode]

切换 PasaMaster 搜索档位：

| 档位 | 说明 | |------|------| | ultra_low | 极速档：只走 SN 检索，不调用 LLM，不扣费 | | low | 基础档：触发 LLM 排序，按 token 扣费（默认推荐） | | mid | 增强档：深度 LLM 评估，扣费更高 | | high | 极致档：最重模式，扣费最高 |

sci model            # 交互式选择
sci model mid        # 直接切到 mid
sci model --show     # 查看当前档位

sci search <query> [options]

搜索论文，结果输出为表格 + 写盘 .json / .bib。

sci search "<query>" \
  --limit 10 \             # 返回篇数，默认 10
  --mode <pasa-mode> \     # 临时覆盖档位，不写盘
  --out ./papers \         # 输出目录，默认 .
  --prefix search-results  # 输出文件名前缀，默认 search-results

sci search 走异步轮询：先短请求拿 task_id，然后每 3s 轮询服务端状态。运行中会同行刷新进度，例如：

ℹ 正在检索: "machine learning protein" (最多 10 篇, 档位: mid)...
  ⏳ 已等待 9s（轮询 #3, task=tool-abc123456…）

按一次 Ctrl+C 让 CLI 在下一次轮询前优雅停止；连按两次会硬退出（进程退出码 130）。

MCP 集成（Claude Code / Cursor）

scimaster-cli 还内置了 Model Context Protocol (MCP) stdio server：sci-mcp。装好包后，可直接让 Claude Code / Cursor 等 MCP 客户端通过 tool-call 调用论文检索，无需走 shell 解析表格输出。

注册到 Claude Code

claude mcp add --transport stdio scimaster -- npx -y scimaster-cli sci-mcp

或者手工编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "scimaster": {
      "command": "npx",
      "args": ["-y", "scimaster-cli", "sci-mcp"]
    }
  }
}

如果已全局安装：

{
  "mcpServers": {
    "scimaster": {
      "command": "sci-mcp"
    }
  }
}

注册到 Cursor

.cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（用户级）：

{
  "mcpServers": {
    "scimaster": {
      "command": "sci-mcp"
    }
  }
}

暴露的 Tool

| Tool | 说明 | |------|------| | search_papers | 输入 query / limit / mode，返回结构化论文清单（与 CLI sci search 共享同一份业务逻辑） |

返回结构（structured content）：

{
  "query": "CRISPR gene editing",
  "limit": 10,
  "mode": "low",
  "count": 10,
  "papers": [
    { "id": "arxiv:...", "title": "...", "authors": ["..."], "year": 2024,
      "abstract": "...", "doi": "...", "url": "...", "bib": "@article{...}" }
  ]
}

前置要求

sci-mcp 读取 ~/.scimaster/config.json 拿 API Key 和 baseUrl，所以首次使用前必须先在终端跑过：

sci init
sci env test         # 或其他环境
sci model low        # 或其他档位

之后 MCP server 拿着这份本地配置去调 muse-api，跟你在终端跑 sci search 走同一份配置。

配置文件

~/.scimaster/config.json   # 文件权限 0600，含 API Key

字段：

{
  "version": 1,
  "apiKey": "<your-api-key>",
  "apiBaseUrl": "https://scimaster.test.bohrium.com",
  "defaults": {
    "limit": 10,
    "mode": "low"
  }
}

也可用环境变量 / 命令行覆盖：

sci --setApiKey <key>   # 不走交互直接写 Key

错误处理

| 场景 | SearchError.kind | 提示 | 退出码 | |------|------------------|------|--------| | 未配置 API Key | no_api_key | 提示 sci init | 1 | | API Key 无效 (401/403) | auth | 提示重新 sci init | 1 | | 单次 HTTP 请求超时 (30s) | network | 提示检查网络 | 1 | | 整轮轮询超过 30min | timeout | 提示切到更低档位重试 | 1 | | Ctrl+C 用户中止 | cancelled | — | 130 | | PasaMaster 返回 FAILURE | api | 透传服务端错误信息 | 1 | | Rate Limit (429) | — | 自动重试，最多 3 次 | — | | 非法档位 / 环境 | — | 列出允许值 | 1 |

License

MIT