# 配置

[English](CONFIGURATION.en.md)

OmniScholar 使用 `schemaVersion: 1` 的 JSON 配置。可直接复制根目录的 [`omnischolar.config.example.json`](../omnischolar.config.example.json)，再删除不需要的服务。

## 配置文件位置

程序使用找到的第一个配置文件，不合并多份配置：

1. `--config PATH` 指定的文件
2. `OMNISCHOLAR_CONFIG` 指向的文件
3. 当前项目的 `omnischolar.config.json`
4. 用户配置目录中的 `omnischolar.config.json`
5. 内置默认值

相对路径以配置文件所在目录为基准。拼错字段名或填写不合法的值时，程序会直接报错。

示例配置中的服务默认启用。填写对应 API key 后即可直接使用。

如果前四项都不存在，第一次启动 MCP 或执行安装命令时会自动创建用户级完整配置模板。模板包含所有服务区块、`apiKey`、`apiKeyEnv` 以及 Vertex 的 `project`、`location` 等字段；Windows 通常位于 `%LOCALAPPDATA%\omnischolar\omnischolar.config.json`，Linux 通常位于 `~/.config/omnischolar/omnischolar.config.json`，macOS 通常位于 `~/Library/Application Support/omnischolar/omnischolar.config.json`。也可以运行 `omnischolar config init` 主动创建；程序不会覆盖已有配置。旧版本生成的嵌套目录文件不会自动迁移或读取，请按需手动复制设置。

## 最小配置

```json
{
  "schemaVersion": 1,
  "runtime": {
    "workspaceRoots": ["./research-inputs"],
    "requestTimeoutSeconds": 30
  },
  "zotero": {
    "enabled": true,
    "baseUrl": "http://127.0.0.1:23119/api"
  },
  "output": {
    "rootDirectory": "./research-output"
  }
}
```

`workspaceRoots` 限定可读取的本地文件，`output.rootDirectory` 限定写入位置。若要直接写入 Obsidian，可把输出目录设为 Vault 中的一个文件夹。

核心服务支持 Windows、Linux 和 macOS。Zotero 功能需要本机运行 Zotero Desktop；XRD 计算需要可选的 `pymatgen` 后端。

`omnischolar_status` 不显示配置文件绝对路径；需要查看路径时使用 `omnischolar config path`。

新文献的子文件夹和文件名可以继续细分：

```json
{
  "output": {
    "rootDirectory": "F:/个人知识库",
    "literatureDirectory": "文献/已解析",
    "folderNameTemplate": "{author}{separator}{year}",
    "filenameTemplate": "{year}{separator}{author}{separator}{title}",
    "filenameSeparator": "+",
    "assetFilenameTemplate": "figure{separator}{index}{separator}{original}{extension}"
  }
}
```

文献和文件夹模板支持 `{author}`、`{year}`、`{title}`、`{separator}`；`folderNameTemplate` 控制每篇文献目录名。连接符支持 `-`、`+` 和 `_`，并由文献、文件夹、附件模板共用。附件图片模板支持 `{index}`、`{original}`、`{extension}`、`{separator}`，用于控制 Zotero key 前缀之后的名称；默认图片名类似 `ABCD1234-image-1.png`。这些设置只影响新建文献，已有同步记录沿用 manifest 中的路径。这里的附件图片是解析生成的图片，不是 Zotero 原始 PDF 附件。

## Zotero 阅读记录与本地解读

MinerU 原文和 `source/zotero-reading-record.md` 都会写入 Obsidian 可读取的书目信息 frontmatter，包括标题、条目类型、作者、Zotero key、DOI、URL、期刊或会议名称、标签、摘要、集合以及 Zotero 跳转链接。标签会转换为空格安全、符号安全的 Obsidian 标签格式。

解析并发布论文时，OmniScholar 会在每篇文献目录的 `source/` 中生成 `zotero-reading-record.md`。当 `output.source.copyPdf` 为 true 时，选中的 Zotero PDF 也会复制到该目录。阅读记录将 Zotero 笔记与 PDF 批注分成两个区块，保留批注类型、颜色、页码、标签、评论和 PDF 相对链接。笔记和批注是个人阅读记录，不应直接当作论文原文证据。

配置示例：

```json
{
  "output": {
    "source": {
      "directory": "source",
      "copyPdf": true,
      "pdfFilenameTemplate": "paper.pdf",
      "zoteroReadingRecordFilename": "zotero-reading-record.md",
      "embedPdf": true
    }
  }
}
```

默认目录结构为：

```text
<output.rootDirectory>/
├── Literatures/<paper>/source/
│   ├── paper.pdf
│   └── zotero-reading-record.md
├── Literatures/<paper>/<paper>.md
├── Literatures/<paper>/assets/
└── Literatures/<paper>/<自由命名的解读文件>.md
```

MinerU 原文和图片资产位于同一篇文献目录。`literature-reading` 默认在对话中完成整篇专业解读；只有用户要求保存或内容过长时才写入 Markdown，默认位置也是该文献目录。Skill 保持 MinerU 原文和资产不变，同名文件不得静默覆盖。输出文件中的图表引用实际 MinerU 图片，并使用可预览、可点击的相对链接。


## API key

API key 可以直接写入对应服务的 `apiKey`。例如：

```json
{
  "schemaVersion": 1,
  "ai4scholar": {
    "enabled": true,
    "apiKey": "在这里填写 Ai4Scholar API key"
  },
  "data": {
    "materialsProject": {
      "enabled": true,
      "apiKey": "在这里填写 Materials Project API key"
    }
  }
}
```

也可以只填写变量名，让程序从环境变量读取：

```json
{
  "mineru": {
    "enabled": true,
    "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY"
  }
}
```

读取顺序为 `apiKey`、`apiKeyEnv` 指向的环境变量、该服务的默认环境变量。直接写入配置文件最简单，但该文件包含敏感信息，请限制文件权限，不要提交到版本库或复制到 Agent 的 MCP 配置中。

| 服务 | 是否需要 key 或其他信息 |
|---|---|
| OpenAlex、PubMed、arXiv、Crossref | 基本检索无需 key；PubMed key 可提高 NCBI 请求额度 |
| Semantic Scholar | key 可选；匿名共享流量更容易遇到 429 |
| Unpaywall | 需要联系邮箱 |
| easyScholar | 需要 API key |
| Zotero | 不需要 key；需开启本地 API |
| MinerU | 需要 API key，并确认 PDF 上传 |
| Ai4Scholar | 需要 API key，部分调用消耗额度 |
| Materials Project | 需要 API key |
| 图片服务 | 按服务商要求配置 key、模型和服务地址 |
| CAS Common Chemistry | 当前还需要服务商提供的正式接口说明文件 |

## 付费与上传

填写对应 API key 后即可使用 Ai4Scholar、图片生成、MinerU 和参考图上传。CAS 需要正式接口契约文件，DashScope/Qwen 需要 workspace 地址。
- 同步恢复只处理本地文件，不会沿用以前的上传许可。
- 付费请求超时后，如果服务端结果不明确，程序不会自动重试。

## 文献检索

```json
{
  "schemaVersion": 1,
  "research": {
    "fallback": true,
    "maxPages": 5,
    "providers": {
      "openalex": { "enabled": true, "email": "researcher@example.org" },
      "pubmed": { "enabled": true, "email": "researcher@example.org" },
      "arxiv": { "enabled": true },
      "crossref": { "enabled": true, "email": "researcher@example.org" },
      "unpaywall": { "enabled": true, "email": "researcher@example.org" }
    }
  }
}
```

`fallback` 只会改用支持同一项查询的服务。HTTP 429 会作为限流结果返回，不会触发连续重试。

## MinerU

```json
{
  "schemaVersion": 1,
  "mineru": {
    "enabled": true,
    "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
    "model": "pipeline"
  }
}
```

默认不启用 MinerU v1 备用接口。当前文档对页数限制的描述不一致，因此程序不会自行切换接口。

## 检查配置

```sh
omnischolar config path
omnischolar config schema
omnischolar status
omnischolar doctor --json
```