setup

star 521

Use when the user wants to install, configure, diagnose, or troubleshoot ScholarAIO, including setup check, dependency status, API keys, and bilingual setup flow.

ZimoLiao By ZimoLiao schedule Updated 6/5/2026
play_arrow Run Skill in Manus View GitHub

name: setup description: Use when the user wants to install, configure, diagnose, or troubleshoot ScholarAIO, including setup check, dependency status, API keys, and bilingual setup flow.

Setup / 环境配置

当用户需要配置、安装、初始化 ScholarAIO 时，按以下流程操作：

1. 诊断当前状态

scholaraio setup check --lang zh

阅读输出，了解哪些组件已就绪、哪些缺失。 如果用户明确是在让 agent 代为配置，而不是自己逐步操作：

  • 默认先跑 scholaraio setup check --lang zh
  • 优先利用检查输出中的错误说明和建议链接，直接继续下一步配置
  • 只有在会影响后续决策时，才回头问用户一个关键问题
  • 对失败项要用“现状 + 原因 + 建议动作”的方式转述，不要只说“没装”或“不可达”

1.1 跨项目 agent 接入

如果用户想在其他软件项目目录里复用 ScholarAIO，或者问“agent 是否能自己看到 ScholarAIO skills 并决定什么时候用”，优先使用自动化命令：

scholaraio setup agent
scholaraio setup agent --apply
scholaraio setup agent check --lang zh

说明时要区分三层：

  • CLI runtime：SCHOLARAIO_CONFIG 和 scholaraio 命令路径，让任何目录都能调用当前 ScholarAIO runtime。
  • skill discovery：Codex / OpenClaw 的 ~/.agents/skills/scholaraio，以及 Qwen 等 target-project wrapper。
  • host-specific entry：Claude Code 插件命令、Cursor/Cline/Windsurf/Copilot 项目 wrapper 等。

默认先跑 scholaraio setup agent 预览；只有用户明确要求代为配置，或已经确认预览内容时，才跑 scholaraio setup agent --apply。执行后提醒用户重启 agent session，让新注册的 skills / wrapper 被重新发现。

如果使用 --target-project，要提醒用户这些 wrapper 是本机集成块，里面可能包含当前 ScholarAIO checkout / config 的绝对路径；提交到共享仓库前必须检查 managed block。

不要再默认手工追加 .bashrc 或手工创建 symlink，除非：

  • setup agent 命令不可用；
  • 用户所在平台不允许自动创建 symlink / wrapper；
  • 用户明确要求手工步骤。

Claude Code 是例外：setup agent 只会打印插件 slash-command；插件安装仍需用户在 Claude Code 内执行。

1.5 核心配置 vs 附加配置

默认把 setup 分成两层：

  • 核心配置：依赖、config.yaml、LLM key、PDF 解析器选择、MinerU token、contact_email
  • 附加配置：Semantic Scholar API key、Zotero API key、非默认 LLM backend / base_url 等按需项目

执行顺序要求：

  1. 先完成核心配置
  2. 再明确告诉用户“还有一些附加配置，可提升特定能力，要不要继续配置”
  3. 只有用户表示需要相关能力时，才继续展开附加配置

对每个附加项，agent 必须按同一模板说明：

  • 用途：它解决什么问题
  • 何时需要：哪些用户才值得配
  • 做法：写到哪里、命令或字段是什么
  • 开销：免费 / 通常单独计费 / 取决于第三方政策

2. 根据缺失项引导用户

依赖缺失

  • 告诉用户缺少哪些依赖，解释每组依赖的用途：
    • embed: 语义向量检索（Qwen3 嵌入模型）
    • topics: BERTopic 主题建模
    • import: Endnote / Zotero 导入
    • Graphviz dot: diagram --format svg 的 DOT→SVG 渲染后端；Linux 可用 sudo apt-get install graphviz
    • Inkscape: Beamer \includesvg 插入 SVG 时需要；Linux 可用 sudo apt-get install inkscape
    • full: 全部功能
  • 运行 pip install -e ".[full]" 或按需安装

config.yaml 缺失

  • 运行 scholaraio setup 交互式向导自动创建
  • 或者直接帮用户创建（默认配置即可）

API key 未配置

  • LLM key（DeepSeek / OpenAI / Anthropic / Google）：问用户是否有。没有也能用，但元数据提取降级为纯正则、enrich 不可用。要明确说明：这通常由所选提供商单独计费，不要默认认为 coding agent 订阅会自动覆盖 ScholarAIO 的 API 调用
  • PDF 解析器选择：先问用户想用 MinerU 还是 Docling
  • 如果用户已经明确知道要用哪个解析器，不要替用户改主意，直接按用户选择继续配置
  • 如果用户不知道选哪个：
    • 测试本地 MinerU 服务、mineru-open-api、MinerU token 状态，以及 https://huggingface.co 可达性
    • 只要网络能跑通 MinerU 路径，就默认优先推荐 MinerU；这里的“MinerU 路径可走”包括：本地服务可达，或 mineru-open-api 已安装且可继续走免费 token 的云端路径
    • 次优先才是询问用户是否打算自行本地部署 MinerU；不要先问“要不要本地部署”再决定推荐谁
    • 仅当 MinerU 本地服务不可达，且 mineru-open-api / 免费 token 云路径也走不通时，才改为优先建议 Docling
    • 推荐时要明确说明：这是建议，不是替用户做决定；如果用户已有偏好，以用户选择为准
    • 必须把检测结果原样转述给用户，至少包括：
      • 本地 MinerU 服务是否可达
      • mineru-open-api 是否存在
      • 是否检测到现有 MinerU token
      • Hugging Face 是否可达
  • MinerU token：仅在用户选择 MinerU 云端方案时提示。要明确说明：MinerU token 是免费的，只需要注册并申请；优先使用 MINERU_TOKEN，MINERU_API_KEY 只保留兼容
  • Contact email：免费；用于 Crossref polite pool，加快 API 响应，可选但推荐
  • 将密钥写入 config.local.yaml（不进 git）

附加配置如何问

完成核心配置后，再问一次：

  • Semantic Scholar API key
    • 用途：用于 Semantic Scholar 认证访问；官方说明是“大多数端点可匿名访问，但部分端点需要 key”
    • 何时需要：用户会频繁做 citation/refetch，或后续需要依赖认证端点时
    • 做法：写入 ingest.s2_api_key 或环境变量 S2_API_KEY
    • 开销：按第三方政策；不要擅自承诺免费或收费
  • Zotero API key
    • 用途：走 Zotero Web API 导入
    • 何时需要：用户明确要用 import-zotero 的 Web API 路径，而不是本地 zotero.sqlite
    • 补充说明：Zotero 官方允许对公开库做匿名只读访问，但 ScholarAIO 当前的 Web API 导入路径按“提供 key”设计；如果用户不想配 key，优先建议本地 zotero.sqlite 导入
    • 做法：写入 zotero.api_key 或环境变量 ZOTERO_API_KEY
    • 开销：按第三方政策
  • 自定义 LLM backend / model / base_url
    • 用途：切换到 Claude / Gemini / Ollama / 自建 OpenAI-compatible 服务
    • 何时需要：用户明确不想用默认 DeepSeek，或已有自己的兼容后端
    • 做法：修改 config.yaml 的 llm.backend / model / base_url
    • 开销：取决于所选提供商

MinerU 高级字段约束

  • 对用户暴露时，默认坚持“能不改就不改”，优先开箱即用
  • mineru_model_version_cloud
    • ScholarAIO 当前是 PDF 解析场景，云端只建议 pipeline 或 vlm
    • 不要引导用户设置 MinerU-HTML；那是 HTML 解析专用，不是 PDF 默认路径
  • mineru_parse_method
    • 对云端精准解析 API，不存在通用的 parse_method 请求字段
    • ScholarAIO 只在用户明确要求 ocr 时映射为官方 file.is_ocr=true
    • auto / txt 默认都按“不强制 OCR”处理，不要过度解释成不同云端模式
  • mineru_enable_formula / mineru_enable_table / mineru_lang
    • 这些字段只对 pipeline / vlm 有效
    • 没有强需求时保留默认值
  • mineru_batch_size
    • 官方 batch 上限是 200
    • 默认值保持保守即可，不要主动调大
  • mineru_backend_local
    • 仅在用户明确要本地部署 MinerU 时才讨论
    • 对纯云端用户，不要把它当成需要配置的字段

部署引导

  • MinerU
    • 若推荐 MinerU，默认先说明：云端路径可直接继续，且免费 token 可注册申请
    • 在说明完“优先推荐 MinerU”和“免费 token 路径”之后，再问用户是否打算本地部署
    • 若打算本地部署，给出官方 Quick Start、Docker 部署、GitHub 链接，并提示本地模型/ModelScope 方案
    • 若不打算本地部署，明确告诉用户去申请免费 token
  • Docling
    • 给出官方安装文档、CLI 文档、GitHub 链接
    • 至少提供 pip install docling，以及 Linux CPU-only 场景的官方安装示例

能写成代码的优先写成代码

  • scholaraio setup 里应尽量直接实现：
    • 网络可达性探测
    • 解析器推荐逻辑
    • MinerU 本地/云端分流提问
    • 官方部署入口链接打印
  • 更偏 agent 行为规范的内容保留在本 skill，例如：
    • 什么时候主动帮用户做网络探测
    • 如何向用户解释“为什么推荐这个解析器”
    • 遇到两边都不通时的默认建议
    • 如何在用户已有明确偏好时停止“自动推荐”

沙盒 / 提权说明（对 Codex 等 agent 很重要）

  • 如果 agent 运行在沙盒里，不要把沙盒内的网络探测结果直接当成用户真实网络环境
  • 对 MinerU cloud、Hugging Face、以及 localhost:8000 这类连通性测试：
    • 优先在允许的情况下提权后再测
    • 如果不能提权，就必须明确告诉用户“这是沙盒视角结果，可能误判”
  • 特别注意：
    • agent 沙盒里的 localhost 不一定等于用户宿主机的 localhost
    • agent 沙盒里的外网策略可能比用户宿主机更严格
  • 如果用户愿意自己在宿主机验证，优先让用户运行：
    • curl -I --max-time 10 http://localhost:8000
    • curl -I --max-time 10 https://mineru.net/apiManage/token
    • curl -I --max-time 10 https://huggingface.co

成本透明要求

setup 过程中，agent 不要只说“需要 key”，必须同时说明：

  • LLM API key：通常单独计费；不配则降级
  • MinerU token：免费申请；不配仍可走本地 MinerU / Docling / PyMuPDF
  • contact_email：免费
  • 其他附加 API key：明确说“按第三方政策”，不要替对方做费用承诺

简短答法模板：

  • LLM API key：用于元数据提取和内容富化；不配会降级为纯正则，通常单独计费
  • MinerU token：用于 MinerU 云端解析；免费，不配仍可走本地 MinerU / Docling / PyMuPDF
  • contact_email：用于 Crossref polite pool；免费，不配通常只是请求识别度和服务礼貌性更弱
  • Semantic Scholar API key：用于认证访问；不配多数端点仍可用，但部分端点需要 key
  • Zotero API key：用于当前的 Zotero Web API 导入路径；不配就改走本地 zotero.sqlite

目录不存在

  • 运行 scholaraio setup check 后如果目录缺失，运行任意 scholaraio 命令会自动创建（ensure_dirs()）

3. 验证

配置完成后再次运行 scholaraio setup check 确认所有项目 [OK]。

注意

  • 用户也可以直接运行 scholaraio setup 进入交互式向导（bilingual EN/ZH）
  • config.local.yaml 存放敏感信息（API key），不进 git
  • 嵌入模型（~1.2GB）会在首次 embed/vsearch 时自动下载，setup 不触发下载
Install via CLI
npx skills add https://github.com/ZimoLiao/scholaraio --skill setup
Repository Details
star Stars 521
call_split Forks 69
navigation Branch main
article Path SKILL.md
More from Creator
ZimoLiao
ZimoLiao Explore all skills →