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
  • 开销：取决于所选提供商