@luffysolution/omnischolar-pi 0.1.0 → 0.1.2

package/README.zh-CN.md

@@ -1,26 +1,26 @@
-# OmniScholar
-
-[English](README.md) | 简体中文
-
-OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、OpenCode、Hermes 和 Pi 等 Agent 提供文献检索、Zotero 读取、PDF 解析、引用处理、材料数据和科研绘图工具。
-
-它可以把在线文献记录与 Zotero 笔记放在一起处理，将经你确认的 PDF 交给 MinerU 解析，再把 Markdown 保存到普通文件夹或 Obsidian Vault。Zotero 全程只读。
-
-## 功能
-
-- 检索 Semantic Scholar、OpenAlex、PubMed/PMC、arXiv、Crossref、Unpaywall、easyScholar、Google Scholar 和 Google Patents
-- 查询论文详情、作者、参考文献、施引文献、推荐、全文片段、数据集和期刊指标
-- 读取 Zotero 收藏夹、条目、笔记、批注、附件、索引文本和本地 PDF 路径，不修改文献库
-- 使用 MinerU 提取指定 PDF 的正文、公式、表格和图片
-- 查找引用候选，核对书目信息，再按要求生成参考文献
-- 查询 Materials Project，并导出 JSON、CSV、Markdown 或 CIF
-- 调用已配置的图片服务生成或编辑科研示意图
-- 保留手工修改过的 Markdown，把待合并版本放入 `.conflicts/`
-
-OmniScholar 共提供 38 个工具，完整列表见[工具目录](docs/TOOLS.md)。
-
-## 安装
-
+# OmniScholar
+
+[English](README.md) | 简体中文
+
+OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、OpenCode、Hermes 和 Pi 等 Agent 提供文献检索、Zotero 读取、PDF 解析、引用处理、材料数据和科研绘图工具。
+
+它可以把在线文献记录与 Zotero 笔记放在一起处理，将经你确认的 PDF 交给 MinerU 解析，再把 Markdown 保存到普通文件夹或 Obsidian Vault。Zotero 全程只读。
+
+## 功能
+
+- 检索 Semantic Scholar、OpenAlex、PubMed/PMC、arXiv、Crossref、Unpaywall、easyScholar、Google Scholar 和 Google Patents
+- 查询论文详情、作者、参考文献、施引文献、推荐、全文片段、数据集和期刊指标
+- 读取 Zotero 收藏夹、条目、笔记、批注、附件、索引文本和本地 PDF 路径，不修改文献库
+- 使用 MinerU 提取指定 PDF 的正文、公式、表格和图片
+- 查找引用候选，核对书目信息，再按要求生成参考文献
+- 查询 Materials Project，并导出 JSON、CSV、Markdown 或 CIF
+- 调用已配置的图片服务生成或编辑科研示意图
+- 保留手工修改过的 Markdown，把待合并版本放入 `.conflicts/`
+
+OmniScholar 共提供 38 个工具，完整列表见[工具目录](docs/TOOLS.md)。
+
+## 安装
+
 需要 Python 3.11 或更高版本：
 
 ```sh
@@ -32,33 +32,72 @@ python -m pip install luffysolution-omnischolar
 ```
 
 如需从源码开发安装，请将包名替换为 `.`。
-
-发行包名为 `luffysolution-omnischolar`，命令和 Python 包名都是 `omnischolar`。
-
-检查安装结果：
-
-```sh
-omnischolar --version
-omnischolar doctor --json
-```
-
-## 连接 Agent
-
-先查看将要修改的文件，再安装本地 MCP 配置和 Skills：
-
-```sh
-omnischolar install --dry-run claude
-omnischolar install claude
-```
-
+
+发行包名为 `luffysolution-omnischolar`，命令和 Python 包名都是 `omnischolar`。
+
+检查安装结果：
+
+```sh
+omnischolar --version
+omnischolar doctor --json
+```
+
+## 连接 Agent
+
+### Codex App 与 Codex CLI 插件安装
+
+先安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)，再添加 OmniScholar Git Marketplace 并安装插件：
+
+```sh
+codex plugin marketplace add luffysolution-svg/omnischolar --ref main
+codex plugin add omnischolar@omnischolar
+```
+
+在 ChatGPT 桌面应用中重启应用，打开 **Plugins**，选择 **OmniScholar** Marketplace，然后安装或启用 **OmniScholar**。在 Codex CLI 中可运行 `/plugins` 浏览同一 Marketplace。
+
+插件会同时安装 8 个 Skills，并使用固定的 PyPI 版本启动本地 MCP：
+
+```sh
+uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
+```
+
+采用插件安装方式时无需另外执行 `pip install`。第一次启动 MCP 需要联网，以便 `uvx` 下载并缓存包。各服务的凭据与可选配置仍保存在 OmniScholar 配置中，插件安装不会收集这些信息。
+
+### Claude Code 插件安装
+
+先安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)。在 Claude Code 中添加 GitHub Marketplace 并安装插件：
+
+```text
+/plugin marketplace add luffysolution-svg/omnischolar
+/plugin install omnischolar@omnischolar
+```
+
+如需在脚本或普通终端中执行，可使用非交互式命令：
+
+```sh
+claude plugin marketplace add luffysolution-svg/omnischolar
+claude plugin install omnischolar@omnischolar --scope user
+```
+
+如果安装结果提示需要重新加载，请运行 `/reload-plugins`，然后新建会话。插件会自动启动同一个固定版本的 `uvx` MCP，并提供 `/omnischolar:scholar-search` 等带命名空间的 Skills，无需另行安装 Python 包。
+
+### Agent 配置安装器
+
+先查看将要修改的文件，再安装本地 MCP 配置和 Skills：
+
+```sh
+omnischolar install --dry-run claude
+omnischolar install claude
+```
+
 可将 `claude` 换成 `codex`、`cursor`、`opencode`、`hermes`、`pi` 或 `workbuddy`。Codex、Claude Code、Cursor、OpenCode、Pi 和 WorkBuddy/CodeBuddy 支持用户级与项目级安装。Hermes 只提供用户级 MCP 配置；项目级命令会安装 Skills，并提示 MCP 需要手动设置。
-
-```sh
-omnischolar install cursor --scope project
-omnischolar update cursor --scope project
-omnischolar uninstall cursor --scope project
-```
-
+
+```sh
+omnischolar install cursor --scope project
+omnischolar update cursor --scope project
+omnischolar uninstall cursor --scope project
+```
+
 对 Pi，完整安装器会运行 `pi install npm:@luffysolution/omnischolar-pi`，并单独安装随包提供的 Skills。npm Extension 会启动 `omnischolar mcp`、发现工具并注册到 Pi。也可以直接安装 Extension：
 
 ```sh
@@ -66,86 +105,86 @@ pi install npm:@luffysolution/omnischolar-pi
 ```
 
 WorkBuddy/CodeBuddy 的用户级配置位于 `~/.codebuddy/.mcp.json`，项目级配置位于 `.mcp.json`。其官方文档没有给出可移植的 Skills 目录，因此安装器会配置 MCP，并将 Skills 状态报告为 `manual_required`。
-
-本地 MCP 命令为：
-
-```sh
-omnischolar mcp
-```
-
-通常无需手动运行，Agent 会根据 MCP 配置启动该进程。安装器写入受支持的配置后，会检查 `initialize`、`tools/list` 和 `omnischolar_status`。
-
-各 Agent 的路径、更新和卸载方法见[安装说明](docs/INSTALLATION.md)。
-
-## 使用示例
-
-```text
-查找 5 篇关于固态电池界面的近期综述，按 DOI 去重，并给出开放获取版本。
-
-在我的 Zotero 中找到这个 DOI，汇总笔记和批注，不要修改 Zotero。
-
-我确认上传后，用 MinerU 解析这份 PDF，并把阅读笔记保存到 Obsidian Vault。
-
-查询 Materials Project 中稳定的 Li-Fe-P-O 材料，将选中的记录导出为 CSV 和 CIF。
-
-为这个机理绘制带标签的示意图。图片只是草稿，不得写成实验数据。
-```
-
-## 配置
-
-将 [`omnischolar.config.example.json`](omnischolar.config.example.json) 复制为 `omnischolar.config.json`。API key 建议放在环境变量中，配置文件只填写变量名 `apiKeyEnv`。
-
-最小的本地配置可以只写 Zotero 和输出目录：
-
-```json
-{
-  "schemaVersion": 1,
-  "runtime": { "workspaceRoots": ["./research-inputs"] },
-  "zotero": {
-    "enabled": true,
-    "baseUrl": "http://127.0.0.1:23119/api"
-  },
-  "output": { "rootDirectory": "./research-output" }
-}
-```
-
-OpenAlex、PubMed、arXiv 和 Crossref 无需 API key。其他服务按需启用，字段和示例见[配置说明](docs/CONFIGURATION.md)。
-
-## 文件、上传与费用
-
-- Zotero 只连接本机 `23119` 端口，并且只发送 GET 请求。
-- MinerU 只有在配置和本次工具调用都确认 `allowExternalUpload` 后，才会接收选中的 PDF。
-- 图片服务会接收提示词，以及你允许上传的参考图；生成和编辑可能消耗账户额度。
-- Ai4Scholar 的部分调用可能消耗账户额度。仅保存 API key 不代表同意付费调用。
-- 付费请求发生网络错误后，如果无法确定服务端是否已经受理，OmniScholar 不会自动重试。
-- AI 生成图只能作为示意图，不能当作测量数据、实验证据或科研结果。
-
-启用上传或付费服务前，请阅读 [`PRIVACY.md`](PRIVACY.md) 和[配置说明](docs/CONFIGURATION.md)。
-
-## 内置 Skills
-
-| Skill | 用途 |
-|---|---|
-| `omnischolar` | 根据科研任务选择并组合工具 |
-| `scholar-search` | 文献、专利、作者、引用网络、期刊和数据集 |
-| `zotero-research` | 本地 Zotero 匹配、笔记、批注和附件 |
-| `paper-reading` | MinerU 解析，以及正文、公式、表格和图片精读 |
-| `academic-citation` | 证据核对、引用候选、格式化和参考文献 |
-| `scientific-figure` | 科研图片生成、编辑、检查和标注 |
-| `materials-project` | 材料筛选、性质、计算来源、相数据和导出 |
-| `chemical-data` | 配置正式 API 说明后查询 CAS Common Chemistry |
-
-## 文档
-
-- [安装与 Agent 配置](docs/INSTALLATION.md)
-- [配置与服务凭据](docs/CONFIGURATION.md)
-- [文献、Zotero、MinerU、引用与输出](docs/RESEARCH.md)
-- [材料与化学](docs/MATERIALS.md)
-- [科研绘图服务](docs/IMAGE_PROVIDERS.md)
-- [工具目录](docs/TOOLS.md)
-
-## 支持与许可证
-
-OmniScholar 使用 [MIT License](LICENSE) 开源。可在 [GitHub Issues](https://github.com/luffysolution-svg/omnischolar/issues) 提交问题，或发送邮件到 `LuffySolution@gmail.com`。报告问题前，请删除 API key、签名 URL、私人论文内容和个人 Zotero 数据。
-
-第三方服务和数据仍遵循各自的条款与许可证，详见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
+
+本地 MCP 命令为：
+
+```sh
+omnischolar mcp
+```
+
+通常无需手动运行，Agent 会根据 MCP 配置启动该进程。安装器写入受支持的配置后，会检查 `initialize`、`tools/list` 和 `omnischolar_status`。
+
+各 Agent 的路径、更新和卸载方法见[安装说明](docs/INSTALLATION.md)。
+
+## 使用示例
+
+```text
+查找 5 篇关于固态电池界面的近期综述，按 DOI 去重，并给出开放获取版本。
+
+在我的 Zotero 中找到这个 DOI，汇总笔记和批注，不要修改 Zotero。
+
+我确认上传后，用 MinerU 解析这份 PDF，并把阅读笔记保存到 Obsidian Vault。
+
+查询 Materials Project 中稳定的 Li-Fe-P-O 材料，将选中的记录导出为 CSV 和 CIF。
+
+为这个机理绘制带标签的示意图。图片只是草稿，不得写成实验数据。
+```
+
+## 配置
+
+将 [`omnischolar.config.example.json`](omnischolar.config.example.json) 复制为 `omnischolar.config.json`。API key 建议放在环境变量中，配置文件只填写变量名 `apiKeyEnv`。
+
+最小的本地配置可以只写 Zotero 和输出目录：
+
+```json
+{
+  "schemaVersion": 1,
+  "runtime": { "workspaceRoots": ["./research-inputs"] },
+  "zotero": {
+    "enabled": true,
+    "baseUrl": "http://127.0.0.1:23119/api"
+  },
+  "output": { "rootDirectory": "./research-output" }
+}
+```
+
+OpenAlex、PubMed、arXiv 和 Crossref 无需 API key。其他服务按需启用，字段和示例见[配置说明](docs/CONFIGURATION.md)。
+
+## 文件、上传与费用
+
+- Zotero 只连接本机 `23119` 端口，并且只发送 GET 请求。
+- MinerU 只有在配置和本次工具调用都确认 `allowExternalUpload` 后，才会接收选中的 PDF。
+- 图片服务会接收提示词，以及你允许上传的参考图；生成和编辑可能消耗账户额度。
+- Ai4Scholar 的部分调用可能消耗账户额度。仅保存 API key 不代表同意付费调用。
+- 付费请求发生网络错误后，如果无法确定服务端是否已经受理，OmniScholar 不会自动重试。
+- AI 生成图只能作为示意图，不能当作测量数据、实验证据或科研结果。
+
+启用上传或付费服务前，请阅读 [`PRIVACY.md`](PRIVACY.md) 和[配置说明](docs/CONFIGURATION.md)。
+
+## 内置 Skills
+
+| Skill | 用途 |
+|---|---|
+| `omnischolar` | 根据科研任务选择并组合工具 |
+| `scholar-search` | 文献、专利、作者、引用网络、期刊和数据集 |
+| `zotero-research` | 本地 Zotero 匹配、笔记、批注和附件 |
+| `paper-reading` | MinerU 解析，以及正文、公式、表格和图片精读 |
+| `academic-citation` | 证据核对、引用候选、格式化和参考文献 |
+| `scientific-figure` | 科研图片生成、编辑、检查和标注 |
+| `materials-project` | 材料筛选、性质、计算来源、相数据和导出 |
+| `chemical-data` | 配置正式 API 说明后查询 CAS Common Chemistry |
+
+## 文档
+
+- [安装与 Agent 配置](docs/INSTALLATION.md)
+- [配置与服务凭据](docs/CONFIGURATION.md)
+- [文献、Zotero、MinerU、引用与输出](docs/RESEARCH.md)
+- [材料与化学](docs/MATERIALS.md)
+- [科研绘图服务](docs/IMAGE_PROVIDERS.md)
+- [工具目录](docs/TOOLS.md)
+
+## 支持与许可证
+
+OmniScholar 使用 [MIT License](LICENSE) 开源。可在 [GitHub Issues](https://github.com/luffysolution-svg/omnischolar/issues) 提交问题，或发送邮件到 `LuffySolution@gmail.com`。报告问题前，请删除 API key、签名 URL、私人论文内容和个人 Zotero 数据。
+
+第三方服务和数据仍遵循各自的条款与许可证，详见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。

package/TERMS.md

@@ -0,0 +1,7 @@
+# Terms of Use
+
+OmniScholar is open-source software distributed under the [MIT License](LICENSE). By installing or using it, you agree to that license and to the terms of any third-party services or datasets you choose to enable.
+
+You are responsible for reviewing generated research output, respecting copyright and data-access restrictions, and confirming any external upload or paid operation. OmniScholar does not provide legal, medical, or financial advice and does not guarantee the accuracy or availability of third-party data.
+
+See [PRIVACY.md](PRIVACY.md) for data-handling details and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for third-party terms.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# Third-party notices
+
+Third-party services and datasets remain governed by their own terms, licenses, quotas, and billing policies. Product names are the property of their respective owners.
+
+CAS Common Chemistry identifies its public substance content as CC BY-NC 4.0. OmniScholar grants neither commercial data rights nor SciFinder access.

package/docs/CONFIGURATION.en.md

@@ -0,0 +1,130 @@
+# Configuration
+
+[简体中文](CONFIGURATION.md)
+
+OmniScholar uses JSON with `schemaVersion: 1`. Start with [`omnischolar.config.example.json`](../omnischolar.config.example.json) and remove services you do not use.
+
+## Config file location
+
+The first matching file is used; files are not merged:
+
+1. the path passed with `--config PATH`
+2. the file named by `OMNISCHOLAR_CONFIG`
+3. `omnischolar.config.json` in the current project
+4. `omnischolar/omnischolar.config.json` in the user config directory
+5. built-in defaults
+
+Relative paths resolve from the config file. Misspelled fields and invalid values are rejected.
+
+## Minimal config
+
+```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` limits local file reads. `output.rootDirectory` limits file writes. To use Obsidian, set the output directory to a folder inside the vault.
+
+## API keys
+
+Keep keys in environment variables and place only the variable name in the config:
+
+```json
+{
+  "schemaVersion": 1,
+  "ai4scholar": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
+    "allowPaid": false
+  },
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY"
+    }
+  }
+}
+```
+
+Credential order is `apiKey`, the variable named by `apiKeyEnv`, then the service's default environment variable. Do not place plaintext keys in agent MCP files, Skills, command lines, or source control.
+
+| Service | Key or account requirement |
+|---|---|
+| OpenAlex, PubMed, arXiv, Crossref | Basic search works without keys; a PubMed key can raise NCBI request limits |
+| Semantic Scholar | Optional key; shared anonymous traffic is more likely to receive 429 |
+| Unpaywall | Contact email required |
+| easyScholar | API key required |
+| Zotero | No key; the local API must be enabled |
+| MinerU | API key and explicit PDF upload approval |
+| Ai4Scholar | API key; some calls use account credit |
+| Materials Project | API key required |
+| Image services | Provider key, model, and endpoint as required |
+| CAS Common Chemistry | A provider-supplied interface description file is still required |
+
+## Paid calls and uploads
+
+A stored key does not approve spending or upload.
+
+- Ai4Scholar and image generation require `allowPaid` in the config and again in the individual tool call.
+- MinerU and reference-image uploads require `allowExternalUpload` in the config and again in the tool call.
+- Sync recovery only repairs local files; it does not reuse previous upload approval.
+- If a paid request times out after the provider may have accepted it, OmniScholar does not retry automatically.
+
+## Literature search
+
+```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` moves only to another service that supports the same operation. HTTP 429 is returned as a rate-limit result and does not start an immediate retry loop.
+
+## MinerU
+
+```json
+{
+  "schemaVersion": 1,
+  "mineru": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_MINERU_API_KEY",
+    "model": "pipeline",
+    "allowExternalUpload": false
+  }
+}
+```
+
+The MinerU v1 fallback is off by default. Provider documentation currently gives inconsistent page limits, so OmniScholar does not switch APIs on its own.
+
+## Check the config
+
+```sh
+omnischolar config path
+omnischolar config schema
+omnischolar status
+omnischolar doctor --json
+```
+

package/docs/CONFIGURATION.md

@@ -0,0 +1,130 @@
+# 配置
+
+[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/omnischolar.config.json`
+5. 内置默认值
+
+相对路径以配置文件所在目录为基准。拼错字段名或填写不合法的值时，程序会直接报错。
+
+## 最小配置
+
+```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 中的一个文件夹。
+
+## API key
+
+建议把 key 存入环境变量，配置中只写变量名：
+
+```json
+{
+  "schemaVersion": 1,
+  "ai4scholar": {
+    "enabled": true,
+    "apiKeyEnv": "OMNISCHOLAR_AI4SCHOLAR_API_KEY",
+    "allowPaid": false
+  },
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY"
+    }
+  }
+}
+```
+
+读取顺序为 `apiKey`、`apiKeyEnv` 指向的环境变量、该服务的默认环境变量。不要把明文 key 写入 Agent 的 MCP 配置、Skills、命令行或版本库。
+
+| 服务 | 是否需要 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 | 当前还需要服务商提供的正式接口说明文件 |
+
+## 付费与上传
+
+保存 key 不会自动允许付费或上传。
+
+- Ai4Scholar 和图片生成需在配置中启用 `allowPaid`，调用时还要再次确认 `allowPaid`。
+- MinerU 与参考图上传需在配置中启用 `allowExternalUpload`，调用时还要再次确认同名参数。
+- 同步恢复只处理本地文件，不会沿用以前的上传许可。
+- 付费请求超时后，如果服务端结果不明确，程序不会自动重试。
+
+## 文献检索
+
+```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",
+    "allowExternalUpload": false
+  }
+}
+```
+
+默认不启用 MinerU v1 备用接口。当前文档对页数限制的描述不一致，因此程序不会自行切换接口。
+
+## 检查配置
+
+```sh
+omnischolar config path
+omnischolar config schema
+omnischolar status
+omnischolar doctor --json
+```
+

package/docs/IMAGE_PROVIDERS.en.md

@@ -0,0 +1,76 @@
+# Scientific image services
+
+[简体中文](IMAGE_PROVIDERS.md)
+
+OmniScholar can connect to OpenAI, xAI, Gemini, Vertex AI, fal.ai, DashScope/Qwen, Atlas, and custom OpenAI-compatible services. Available models depend on the account, region, endpoint, and configuration.
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `omnischolar_image_models` | Show configured models and their usable operations |
+| `omnischolar_image_generate` | Text-to-image, image-to-image, or multi-reference generation |
+| `omnischolar_image_edit` | Edit an existing image |
+| `omnischolar_image_service` | Run supported provider status, model, or task operations |
+| `ai4scholar_figure` | Generate, edit, or vectorize through Ai4Scholar |
+
+Each model must explicitly declare the operation it supports. A model name appearing in a provider catalog does not by itself prove that it can generate or edit images; the corresponding operation must show `usable: true` in `omnischolar_image_models`.
+
+## Example config
+
+```json
+{
+  "schemaVersion": 1,
+  "defaults": {
+    "defaultImageProvider": "fal"
+  },
+  "media": {
+    "allowPaid": false,
+    "allowExternalUpload": false,
+    "providers": {
+      "fal": {
+        "enabled": true,
+        "apiKeyEnv": "OMNISCHOLAR_FAL_API_KEY",
+        "baseUrl": "https://fal.run",
+        "models": {},
+        "options": {}
+      },
+      "dashscope": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_DASHSCOPE_API_KEY",
+        "baseUrl": "https://your-workspace.cn-beijing.maas.aliyuncs.com/api/v1",
+        "models": {},
+        "options": {
+          "workspace": "your-workspace"
+        }
+      },
+      "qwen-cloud": {
+        "enabled": false,
+        "apiKeyEnv": "OMNISCHOLAR_QWEN_API_KEY",
+        "baseUrl": "https://your-workspace.ap-southeast-1.maas.aliyuncs.com/api/v1",
+        "models": {},
+        "options": {
+          "workspace": "your-workspace"
+        }
+      }
+    }
+  }
+}
+```
+
+A custom service needs an exact `baseUrl`, model ID, capability list, and generation or edit endpoint. Do not infer capabilities from the model name.
+
+## Generate and edit
+
+Before submitting a task, define the scientific content, labels, units, aspect ratio, and file format. Generation requires `allowPaid` for that call. Uploading a reference image also requires `allowExternalUpload` for that call.
+
+Upload only images you may share with the selected service. After files are saved, signed URLs and base64 source data are removed from the returned payload. Downloads are checked for public HTTPS, file size, MIME type, and image signature. If one file in a multi-file result is missing, the incomplete set is not published.
+
+## Current provider notes
+
+- fal has been tested for queue submission, polling, data-URI results, text-to-image, and two-reference editing. If the local machine cannot resolve the fal CDN, a data-URI result can still be saved.
+- DashScope/Qwen currently needs a workspace-scoped endpoint or an explicit `baseUrl` supplied by the provider. China workspaces use an address such as `https://<workspace>.cn-beijing.maas.aliyuncs.com/api/v1`; international workspaces use `https://<workspace>.ap-southeast-1.maas.aliyuncs.com/api/v1`. A retired generic endpoint returns `dashscope_workspace_required`.
+- Gemini's `apiKeyEnv` must name an environment variable that exists.
+- Atlas and custom services need a working endpoint and model description.
+
+Review text, structures, mechanisms, scale, and quantitative labels after generation. **AI images are illustrative drafts, not experimental data, real measurements, or scientific conclusions.**