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]" 或按需安装