Setup

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 只保留兼容
• MinerU cloud extra：mineru-open-api 不属于 core 或 full。只有用户选择 MinerU 云端方案时，才安装 scholaraio[mineru-cloud]（源码 checkout 使用 pip install -e ".[mineru-cloud]"）
• 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 不触发下载