@luffysolution/omnischolar-pi 0.1.17 → 0.1.19

package/docs/IMAGE_PROVIDERS.en.md

@@ -8,13 +8,27 @@ OmniScholar can connect to OpenAI, xAI, Gemini, Vertex AI, fal.ai, DashScope/Qwe
 
 | Tool | Use |
 |---|---|
-| `omnischolar_image_models` | Show configured models and their usable operations |
+| `omnischolar_image_models` | Discover and show models available with the current credentials |
 | `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`.
+Model selection uses the user's explicit model first, then catalog models with confirmed capabilities, then official-documentation-verified built-in models, then explicitly configured model contracts. If the model is omitted, the tool discovers and selects the newest usable model. Providers without a model catalog use a small verified built-in set and still allow `models` to override or extend the declarations.
+
+Common tool parameters include `size`, `aspectRatio`, `resolution`, `background`, `outputFormat`, `quality`, `n`, `negativePrompt`, and `seed`. Read `supported_parameters` from the selected model before calling the tool; adapters map supported controls to native names and return `parameter_unsupported` before submission instead of silently dropping controls.
+
+### Official parameter matrix
+
+| Provider/API | Verified parameters | Do not assume |
+|---|---|---|
+| OpenAI GPT Image | `size`/`resolution`, `background`, `outputFormat`, `quality`, `n` | A separate native `aspectRatio` control |
+| Google Gemini API Interactions | `aspectRatio`, `resolution` (`1K`/`2K`), `outputFormat` | `size`, `background`, `quality`, `n`, `seed` |
+| Vertex Gemini image | `aspectRatio`, `resolution` (`1K`/`2K`/`4K`), `outputFormat`, `n` | Transparency or arbitrary pixel `size` |
+| Fal Nano Banana 2 | `aspectRatio`, `resolution`, `outputFormat`, `n`, `seed` | `background` or `quality` |
+| Fal GPT Image variants | `size`/`resolution`, `background`, `outputFormat`, `quality`, `n` | Nano Banana-specific controls |
+| DashScope/Qwen native image | `size`/`resolution`, `n`, `negativePrompt`, `seed` | `background`, `quality`, or transparent output |
+| Atlas | Follow the selected model contract; GPT Image commonly exposes `size`, `quality`, `outputFormat` | A provider-wide parameter contract |
 
 ## Example config
 
@@ -29,7 +43,7 @@ Each model must explicitly declare the operation it supports. A model name appea
       "fal": {
         "enabled": true,
         "apiKeyEnv": "OMNISCHOLAR_FAL_API_KEY",
-        "baseUrl": "https://fal.run",
+        "baseUrl": "https://queue.fal.run",
         "models": {},
         "options": {}
       },
@@ -39,16 +53,18 @@ Each model must explicitly declare the operation it supports. A model name appea
         "baseUrl": "https://your-workspace.cn-beijing.maas.aliyuncs.com/api/v1",
         "models": {},
         "options": {
-          "workspace": "your-workspace"
+          "workspace": "your-workspace",
+          "region": "cn-beijing",
+          "protocol": "native"
         }
       },
       "qwen-cloud": {
         "enabled": true,
         "apiKeyEnv": "OMNISCHOLAR_QWEN_API_KEY",
-        "baseUrl": "https://your-workspace.ap-southeast-1.maas.aliyuncs.com/api/v1",
+        "baseUrl": "https://dashscope.aliyuncs.com/api/v1",
         "models": {},
         "options": {
-          "workspace": "your-workspace"
+          "protocol": "native"
         }
       }
     }
@@ -56,7 +72,29 @@ Each model must explicitly declare the operation it supports. A model name appea
 }
 ```
 
-A custom service needs an exact `baseUrl`, model ID, capability list, and generation or edit endpoint. Do not infer capabilities from the model name.
+Qwen AI Platform image models use the public native DashScope endpoint `https://dashscope.aliyuncs.com/api/v1` and do not require a workspace or region. Only Bailian regional workspace deployments need `workspace`, `region`, and a matching workspace Base URL. `protocol` defaults to `native`; set it to `openai-compatible` only when that protocol is explicitly supported. The built-in set includes `qwen-image-3.0-pro`, `qwen-image-3.0`, `wan2.7-image-pro`, `wan2.7-image`, and `z-image-turbo`; the current Qwen Image 3.0 recommendation is `qwen-image-3.0-pro`, while actual entitlement remains account- and region-dependent.
+
+Vertex AI can use a service-account JSON file:
+
+```json
+{
+  "vertex": {
+    "enabled": true,
+    "credentialsFile": "F:/path/to/service-account.json",
+    "project": null,
+    "location": "global",
+    "models": {
+      "imagen-3.0-capability-001": {
+        "capabilities": ["text-to-image", "image-to-image", "edit"]
+      }
+    }
+  }
+}
+```
+
+The service-account file is used locally to obtain an OAuth token and is never written to output artifacts. If `project` is omitted, OmniScholar reads `project_id` from the JSON; `location` defaults to `global`. Model availability still depends on project permissions, location, and model publication status.
+
+Atlas, fal, Vertex, and DashScope/Qwen expose different catalog capabilities. Atlas, fal, Vertex, and DashScope/Qwen have small built-in model sets checked against official documentation; custom services still need an exact `baseUrl`, model ID, capability list, and generation or edit endpoint. Do not infer capabilities from the model name or treat a built-in model as an entitlement guarantee.
 
 ## Generate and edit
 
@@ -67,8 +105,9 @@ Upload only images you may share with the selected service. After files are save
 ## 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`.
+- DashScope/Qwen supports the Qwen AI Platform native endpoint `https://dashscope.aliyuncs.com/api/v1` and regional Bailian workspace endpoints such as `https://<workspace>.cn-beijing.maas.aliyuncs.com/api/v1`. When `workspace` and `region` are supplied, the tool can derive the regional endpoint.
 - Gemini's `apiKeyEnv` must name an environment variable that exists.
-- Atlas and custom services need a working endpoint and model description.
+- Atlas Cloud uses `https://api.atlascloud.ai/api/v1`, submits to `model/generateImage`, and polls `model/prediction/{id}`. The built-in set includes official Nano Banana 2, GPT Image 2, and GPT Image 2.5 Flare/Sunburst IDs. Atlas image tasks are asynchronous and their `outputs` are saved locally.
+- 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.**

package/docs/IMAGE_PROVIDERS.md

@@ -8,13 +8,27 @@ OmniScholar 可连接 OpenAI、xAI、Gemini、Vertex AI、fal.ai、DashScope/Qwe
 
 | 工具 | 用途 |
 |---|---|
-| `omnischolar_image_models` | 查看已配置模型及其可用功能 |
+| `omnischolar_image_models` | 发现并查看当前凭据可用模型及其功能 |
 | `omnischolar_image_generate` | 文生图、图生图或多参考图生成 |
 | `omnischolar_image_edit` | 编辑已有图片 |
 | `omnischolar_image_service` | 调用服务商已经支持的状态、模型或任务操作 |
 | `ai4scholar_figure` | 使用 Ai4Scholar 生成、编辑或矢量化图片 |
 
-每个模型都必须明确声明支持的功能。模型名出现在服务商目录中，并不自动代表它可以生图或编辑；`omnischolar_image_models` 中对应功能需要显示 `usable: true`。
+模型选择顺序是：用户显式指定的模型、当前服务商目录中已确认能力的模型、经过官方文档核对的内置模型、显式配置的模型合同。省略模型时，工具会发现并选择最新的可用模型；没有模型目录的服务商使用内置的已核对模型，同时仍允许在 `models` 中显式覆盖或补充模型和能力。
+
+常用工具参数包括 `size`、`aspectRatio`、`resolution`、`background`、`outputFormat`、`quality`、`n`、`negativePrompt` 和 `seed`。调用前先读取模型描述中的 `supported_parameters`；工具会按服务商协议转换参数，不支持的参数组合会在提交请求前返回 `parameter_unsupported`，不会静默丢弃参数。
+
+### 官方参数能力矩阵
+
+| 服务商/API | 已核对的参数 | 明确不应默认传入 |
+|---|---|---|
+| OpenAI GPT Image | `size`/`resolution`、`background`、`outputFormat`、`quality`、`n` | 独立 `aspectRatio` |
+| Google Gemini API Interactions | `aspectRatio`、`resolution`（`1K`/`2K`）、`outputFormat` | `size`、`background`、`quality`、`n`、`seed` |
+| Vertex Gemini image | `aspectRatio`、`resolution`（`1K`/`2K`/`4K`）、`outputFormat`、`n` | 透明背景、任意像素尺寸 |
+| Fal Nano Banana 2 | `aspectRatio`、`resolution`、`outputFormat`、`n`、`seed` | `background`、`quality` |
+| Fal GPT Image 变体 | `size`/`resolution`、`background`、`outputFormat`、`quality`、`n` | Nano Banana 专属参数 |
+| DashScope/Qwen 原生图像 | `size`/`resolution`、`n`、`negativePrompt`、`seed` | `background`、`quality`、透明背景 |
+| Atlas | 按模型合同；GPT Image 常见为 `size`、`quality`、`outputFormat` | 不要使用服务商级统一假设 |
 
 ## 配置示例
 
@@ -29,7 +43,7 @@ OmniScholar 可连接 OpenAI、xAI、Gemini、Vertex AI、fal.ai、DashScope/Qwe
       "fal": {
         "enabled": true,
         "apiKeyEnv": "OMNISCHOLAR_FAL_API_KEY",
-        "baseUrl": "https://fal.run",
+        "baseUrl": "https://queue.fal.run",
         "models": {},
         "options": {}
       },
@@ -39,16 +53,18 @@ OmniScholar 可连接 OpenAI、xAI、Gemini、Vertex AI、fal.ai、DashScope/Qwe
         "baseUrl": "https://your-workspace.cn-beijing.maas.aliyuncs.com/api/v1",
         "models": {},
         "options": {
-          "workspace": "your-workspace"
+          "workspace": "your-workspace",
+          "region": "cn-beijing",
+          "protocol": "native"
         }
       },
       "qwen-cloud": {
         "enabled": true,
         "apiKeyEnv": "OMNISCHOLAR_QWEN_API_KEY",
-        "baseUrl": "https://your-workspace.ap-southeast-1.maas.aliyuncs.com/api/v1",
+        "baseUrl": "https://dashscope.aliyuncs.com/api/v1",
         "models": {},
         "options": {
-          "workspace": "your-workspace"
+          "protocol": "native"
         }
       }
     }
@@ -56,7 +72,29 @@ OmniScholar 可连接 OpenAI、xAI、Gemini、Vertex AI、fal.ai、DashScope/Qwe
 }
 ```
 
-自定义服务需要填写准确的 `baseUrl`、模型 ID、功能列表，以及生成或编辑接口。不要只凭模型名填写功能。
+千问 AI 平台图片模型使用公共 DashScope 原生接口 `https://dashscope.aliyuncs.com/api/v1`，不需要 workspace 或 region。只有百炼的地域 workspace 实例才需要填写 `workspace`、`region`，并使用对应的 workspace Base URL。`protocol` 默认是 `native`，只有明确配置为 `openai-compatible` 时才使用兼容端点。内置模型包括 `qwen-image-3.0-pro`、`qwen-image-3.0`、`wan2.7-image-pro`、`wan2.7-image` 和 `z-image-turbo`；其中当前 Qwen Image 3.0 推荐模型为 `qwen-image-3.0-pro`，具体生成权限仍以账号和地域为准。
+
+Vertex AI 可使用 service-account JSON：
+
+```json
+{
+  "vertex": {
+    "enabled": true,
+    "credentialsFile": "F:/path/to/service-account.json",
+    "project": null,
+    "location": "global",
+    "models": {
+      "imagen-3.0-capability-001": {
+        "capabilities": ["text-to-image", "image-to-image", "edit"]
+      }
+    }
+  }
+}
+```
+
+服务账号文件只用于本地换取 OAuth token，不会写入输出结果。若省略 `project`，工具会从 JSON 的 `project_id` 自动读取；默认 `location` 为 `global`。模型是否可用仍取决于项目授权、区域和模型发布状态。
+
+Atlas、fal、Vertex、DashScope/Qwen 和自定义服务的模型目录能力不同。Atlas、fal、Vertex、DashScope/Qwen 已提供少量基于官方文档核对的内置模型；自定义服务仍需要准确的 `baseUrl`、模型 ID、功能列表，以及生成或编辑接口。不要只凭模型名填写功能，也不要把内置模型视为账号已开通的保证。
 
 ## 生成与编辑
 
@@ -67,8 +105,9 @@ OmniScholar 可连接 OpenAI、xAI、Gemini、Vertex AI、fal.ai、DashScope/Qwe
 ## 当前服务说明
 
 - fal 已验证队列提交、轮询、data URI 结果、文生图和双参考图编辑。本机若无法解析 fal CDN，data URI 结果仍可保存。
-- DashScope/Qwen 当前需要绑定 workspace 的服务地址，或服务商明确提供的 `baseUrl`。中国区地址形如 `https://<workspace>.cn-beijing.maas.aliyuncs.com/api/v1`，国际区地址形如 `https://<workspace>.ap-southeast-1.maas.aliyuncs.com/api/v1`。旧通用地址会返回 `dashscope_workspace_required`。
+- DashScope/Qwen 支持千问 AI 平台的通用原生地址 `https://dashscope.aliyuncs.com/api/v1`，也支持百炼按地域的 workspace 地址，例如 `https://<workspace>.cn-beijing.maas.aliyuncs.com/api/v1`。当填写 `workspace` 和 `region` 时，工具可以自动拼接地域地址。
 - Gemini 配置中的 `apiKeyEnv` 必须指向已存在的环境变量。
-- Atlas 和自定义服务必须给出可用的服务地址与模型说明。
+- Atlas Cloud 使用 `https://api.atlascloud.ai/api/v1`、`model/generateImage` 提交和 `model/prediction/{id}` 轮询；默认内置 Nano Banana 2、GPT Image 2、GPT Image 2.5 Flare/Sunburst 的官方模型 ID。Atlas 的图片任务是异步的，结果中的 `outputs` 会保存到本地。
+- 自定义服务必须给出可用的服务地址与模型说明。
 
 生成后仍需人工检查文字、结构、机制、比例和定量描述。**AI 图片是示意草稿，不是实验数据、真实测量或科研结论。**

package/docs/RESEARCH.en.md

@@ -9,6 +9,7 @@
 | `research_sources` | Show enabled sources and available operations |
 | `literature_search` | Search papers by year, type, or open-access status |
 | `literature_get` | Retrieve details by DOI, PMID/PMCID, arXiv ID, or source ID |
+| `literature_author` | Search Semantic Scholar authors, author details, or an author's papers |
 | `literature_graph` | Find references, citations, or recommendations |
 | `journal_metrics` | Retrieve supported journal metrics |
 | `literature_fulltext` | Find lawful full-text locations or save an accessible file under the output directory |
@@ -25,7 +26,7 @@ The sources serve different purposes:
 
 Start with a small `limit`. Deduplicate by DOI when possible; otherwise compare normalized title, year, and first author. Title similarity can shortlist a paper but cannot establish that it supports a claim.
 
-On HTTP 429, OmniScholar returns a rate-limit result. Wait for the provider's backoff period or choose another source that supports the same operation. Do not submit the same request in a tight loop.
+On HTTP 429, OmniScholar reads `Retry-After` when provided and applies bounded backoff plus optional `rateLimitPerSecond` throttling for Semantic Scholar. Do not submit the same request in a tight loop.
 
 ## Zotero
 

package/docs/RESEARCH.md

@@ -9,6 +9,7 @@
 | `research_sources` | 查看已启用的数据源和可用功能 |
 | `literature_search` | 检索论文，可限制年份、类型和开放获取状态 |
 | `literature_get` | 按 DOI、PMID/PMCID、arXiv ID 或数据源 ID 获取详情 |
+| `literature_author` | 查询 Semantic Scholar 作者、作者详情或作者论文列表 |
 | `literature_graph` | 查询参考文献、施引文献或推荐论文 |
 | `journal_metrics` | 查询已支持的期刊指标 |
 | `literature_fulltext` | 查找合法全文地址，或将允许访问的文件保存到输出目录 |
@@ -25,7 +26,7 @@
 
 检索时先用较小的 `limit`。优先按 DOI 去重；没有 DOI 时，再比较标题、年份和第一作者。标题相似只能用于筛选，不能代替正文证据。
 
-遇到 HTTP 429 时，OmniScholar 会返回限流信息。等待服务商给出的时间后再试，或改用支持同一查询的数据源。不要连续提交相同请求。
+遇到 HTTP 429 时，OmniScholar 会读取 `Retry-After`（若服务商提供），并对 Semantic Scholar 使用有界退避和可选的 `rateLimitPerSecond`。仍应避免连续提交相同请求。
 
 ## Zotero
 

package/docs/TOOLS.en.md

@@ -11,6 +11,7 @@ Tool and capability names match the values returned to agents.
 | `research_sources` | literature | `literature.sources` | none | no | none | free |
 | `literature_search` | literature | `literature.search` | none | yes | none | free |
 | `literature_get` | literature | `literature.lookup` | none | yes | none | free |
+| `literature_author` | literature | `literature.lookup` | none | yes | none | free |
 | `literature_graph` | literature | `literature.references`, `literature.citations`, `literature.recommendations` | none | yes | none | free |
 | `journal_metrics` | literature | `journal.metrics` | none | yes | none | free |
 | `literature_fulltext` | literature | `fulltext.resolve`, `fulltext.fetch` | filesystem | yes | none | free |

package/docs/TOOLS.md

@@ -11,6 +11,7 @@
 | `research_sources` | literature | `literature.sources` | none | no | none | free |
 | `literature_search` | literature | `literature.search` | none | yes | none | free |
 | `literature_get` | literature | `literature.lookup` | none | yes | none | free |
+| `literature_author` | literature | `literature.lookup` | none | yes | none | free |
 | `literature_graph` | literature | `literature.references`, `literature.citations`, `literature.recommendations` | none | yes | none | free |
 | `journal_metrics` | literature | `journal.metrics` | none | yes | none | free |
 | `literature_fulltext` | literature | `fulltext.resolve`, `fulltext.fetch` | filesystem | yes | none | free |

package/omnischolar.config.example.json

@@ -151,8 +151,9 @@
         "enabled": true,
         "apiKey": "",
         "apiKeyEnv": null,
-        "project": "your-project",
-        "location": "us-central1",
+        "credentialsFile": null,
+        "project": null,
+        "location": "global",
         "models": {},
         "options": {}
       },
@@ -168,7 +169,7 @@
         "enabled": true,
         "apiKey": "",
         "apiKeyEnv": null,
-        "baseUrl": "https://fal.run",
+        "baseUrl": "https://queue.fal.run",
         "models": {},
         "options": {}
       },
@@ -179,26 +180,33 @@
         "baseUrl": "https://your-workspace.cn-beijing.maas.aliyuncs.com/api/v1",
         "models": {},
         "options": {
-          "workspace": "your-workspace"
+          "workspace": "your-workspace",
+          "region": "cn-beijing",
+          "protocol": "native"
         }
       },
       "qwen-cloud": {
         "enabled": true,
         "apiKey": "",
         "apiKeyEnv": null,
-        "baseUrl": "https://your-workspace.ap-southeast-1.maas.aliyuncs.com/api/v1",
+        "baseUrl": "https://dashscope.aliyuncs.com/api/v1",
         "models": {},
         "options": {
-          "workspace": "your-workspace"
+          "protocol": "native"
         }
       },
       "atlas": {
         "enabled": true,
         "apiKey": "",
         "apiKeyEnv": null,
-        "baseUrl": "https://your-atlas-provider.example/v1",
+        "baseUrl": "https://api.atlascloud.ai/api/v1",
         "models": {},
-        "options": {}
+        "options": {
+          "generationEndpoint": "model/generateImage",
+          "pollEndpoint": "model/prediction",
+          "pollIntervalSeconds": 2,
+          "pollTimeoutSeconds": 600
+        }
       },
       "custom": {
         "enabled": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luffysolution/omnischolar-pi",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Pi MCP bridge for the OmniScholar research toolkit",
   "type": "module",
   "license": "MIT",

package/pi-extension/dist/index.js

@@ -1,7 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Type } from "typebox";
-const CLIENT_INFO = { name: "omnischolar-pi", version: "0.1.17" };
+const CLIENT_INFO = { name: "omnischolar-pi", version: "0.1.19" };
 export function resultText(result) {
     return result.content
         .map((item) => {