@luffysolution/omnischolar-pi 0.2.0 → 0.3.0

package/README.en.md

@@ -20,7 +20,7 @@ It can search public indexes, combine online records with your Zotero notes, sen
 - Generate or edit scientific illustrations with configured image services
 - Preserve local Markdown edits and place incoming conflict versions in `.conflicts/`
 
-OmniScholar exposes 38 tools. See the [tool list](docs/TOOLS.en.md).
+OmniScholar exposes 43 tools. See the [tool list](docs/TOOLS.en.md).
 
 <details>
 <summary>Install and connect an agent</summary>

package/README.md

@@ -25,7 +25,7 @@ OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、
 - 调用已配置的图片服务生成或编辑科研示意图
 - 保留手工修改过的 Markdown，把待合并版本放入 `.conflicts/`
 
-OmniScholar 共提供 38 个工具，完整列表见[工具目录](docs/TOOLS.md)。
+OmniScholar 共提供 43 个工具，完整列表见[工具目录](docs/TOOLS.md)。
 
 <details>
 <summary>安装与部署</summary>

package/README.zh-CN.md

@@ -18,7 +18,7 @@ OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、
 - 调用已配置的图片服务生成或编辑科研示意图
 - 保留手工修改过的 Markdown，把待合并版本放入 `.conflicts/`
 
-OmniScholar 共提供 38 个工具，完整列表见[工具目录](docs/TOOLS.md)。
+OmniScholar 共提供 43 个工具，完整列表见[工具目录](docs/TOOLS.md)。
 
 ## 安装
 
@@ -67,7 +67,7 @@ codex plugin add omnischolar@omnischolar
 
 在 ChatGPT 桌面应用中重启应用，打开 **Plugins**，选择 **OmniScholar** Marketplace，然后安装或启用 **OmniScholar**。在 Codex CLI 中可运行 `/plugins` 浏览同一 Marketplace。
 
-插件会同时安装 8 个 Skills，并从 PyPI 最新版本启动本地 MCP：
+插件会同时安装 10 个 Skills，并从 PyPI 最新版本启动本地 MCP：
 
 ```sh
 uvx --from luffysolution-omnischolar@latest omnischolar mcp
@@ -197,6 +197,8 @@ OpenAlex、PubMed、arXiv 和 Crossref 无需 API key。其他服务按需启用
 | `scholar-search` | 文献、专利、作者、引用网络、期刊和数据集 |
 | `zotero-research` | 本地 Zotero 匹配、笔记、批注和附件 |
 | `paper-reading` | MinerU 解析，以及正文、公式、表格和图片精读 |
+| `literature-reading` | 全文、图表、公式、段落、比较和综述解读 |
+| `literature-retrieval` | 聚焦检索、段落定位和有界阅读上下文 |
 | `academic-citation` | 证据核对、引用候选、格式化和参考文献 |
 | `scientific-figure` | 科研图片生成、编辑、检查和标注 |
 | `materials-project` | 材料筛选、性质、计算来源、相数据和导出 |

package/docs/INSTALLATION.en.md

@@ -112,7 +112,7 @@ claude plugin install omnischolar@omnischolar --scope user
 
 Choose `--scope project` to share the enabled plugin through repository settings, or `--scope local` to enable it only for yourself in the current repository. If Claude reports `Run /reload-plugins to activate`, run that command before using the plugin.
 
-Claude Code copies the repository-root plugin into its versioned cache, discovers the nine folders under `skills/`, and starts `.mcp.json` automatically when the plugin is enabled. The MCP command uses the latest PyPI package:
+Claude Code copies the repository-root plugin into its versioned cache, discovers the ten folders under `skills/`, and starts `.mcp.json` automatically when the plugin is enabled. The MCP command uses the latest PyPI package:
 
 ```sh
 uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp

package/docs/INSTALLATION.md

@@ -112,7 +112,7 @@ claude plugin install omnischolar@omnischolar --scope user
 
 使用 `--scope project` 可通过仓库设置与协作者共享启用状态；使用 `--scope local` 则只在当前仓库为自己启用。如果 Claude 提示 `Run /reload-plugins to activate`，请先运行该命令。
 
-Claude Code 会把仓库根插件复制到版本化缓存，发现 `skills/` 下的 9 个 Skills，并在插件启用时自动启动 `.mcp.json`。MCP 命令使用 PyPI 最新包：
+Claude Code 会把仓库根插件复制到版本化缓存，发现 `skills/` 下的 10 个 Skills，并在插件启用时自动启动 `.mcp.json`。MCP 命令使用 PyPI 最新包：
 
 ```sh
 uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp

package/docs/RESEARCH.en.md

@@ -48,6 +48,14 @@ The combined view can include metadata, notes, annotations, attachment details,
 
 `zotero_item` defaults to metadata-only output; request `mode=aggregate` when notes, annotations, attachments, indexed text, or PDF selection are needed. After parsing, use `omnischolar_read` for cursor-based full-text reading or bounded figure, formula, paragraph, comparison, and review evidence. The complete Markdown remains in the output directory and is not returned to the agent by default.
 
+### Focused retrieval and reading contexts
+
+Use `omnischolar_focus` over parsed local publications for bounded BM25 + TF-IDF vector evidence retrieval. It returns matching paragraphs, headings, character ranges, and `paper.md#Lx-Ly` line locators rather than a complete Markdown document. Restrict it with `keys`, `section`, `topK`, and `maxPerDocument`. The local backend explicitly reports `strategy=hybrid-bm25-tfidf`, `vectorBackend=tfidf-local`, and `semantic=false`, so term-vector similarity is not presented as dense semantic embedding retrieval.
+
+Use `omnischolar_locate` for exact paragraph location in one paper, with phrase or all-term matching and Zotero key, title, section, and stable anchors. Use `omnischolar_read` with `mode=figures` for image paths, table Markdown, captions, and bounded figure/table context. The agent must still distinguish visual observation, caption text, author claims, and interpretation.
+
+For multi-turn reading, call `omnischolar_context` with `open`, then pass its `contextId` to `omnischolar_focus`, `omnischolar_locate`, or `omnischolar_read`. The cache stores selected evidence only; `get` is paginated and bounded, so it does not automatically re-inject a complete paper into the agent. `compare` and `review` can add per-paper evidence to the same context.
+
 Notes and annotations are personal reading context, not evidence from the publication. Check the paper itself before citing a claim.
 
 ## MinerU parsing

package/docs/RESEARCH.md

@@ -48,6 +48,14 @@ http://127.0.0.1:23119/api
 
 `zotero_item` 默认返回元数据；需要笔记、批注或 PDF 选择时再显式使用 `mode=aggregate`。已解析文献使用 `omnischolar_read` 按全文游标、图表、公式、段落、对比或综述模式分段读取，完整 Markdown 仍保存在输出目录，不会默认一次返回给 Agent。
 
+### 聚焦检索与阅读上下文
+
+已解析的本地文献可以用 `omnischolar_focus` 做有界的 BM25 + TF-IDF 向量混合证据检索。它返回匹配段落、章节、字符范围和 `paper.md#Lx-Ly` 行定位，不返回整篇 Markdown；可用 `keys`、`section`、`topK` 和 `maxPerDocument` 限定范围。当前本地后端会明确返回 `strategy=hybrid-bm25-tfidf`、`vectorBackend=tfidf-local` 和 `semantic=false`，因此不会把词项向量相似度误称为真正的语义 embedding 检索。
+
+需要单篇精确定位时使用 `omnischolar_locate`，按短语或全部词项匹配段落，并保留 Zotero key、标题、章节和定位锚点。图表读取使用 `omnischolar_read` 的 `figures` 模式，返回图片路径、表格 Markdown、标题以及受限的图表上下文；Agent 仍需区分图像观察、图注、作者结论和自己的解释。
+
+多轮阅读可以先用 `omnischolar_context` 的 `open` 创建上下文，再把 `contextId` 传给 `omnischolar_focus`、`omnischolar_locate` 或 `omnischolar_read`。缓存只保存选中的证据片段，`get` 仍然分页并受字符上限约束，不会自动把整篇论文再次注入 Agent。`compare` 和 `review` 模式也可以把每篇文献的有界证据加入同一个上下文。
+
 Zotero 笔记和批注属于个人阅读记录，不应当作论文原文证据。需要引用论文结论时，仍要核对原文。
 
 ## MinerU 解析

package/docs/TOOLS.en.md

@@ -19,6 +19,9 @@ Tool and capability names match the values returned to agents.
 | `zotero_search` | zotero | `zotero.search` | none | yes | none | free |
 | `zotero_item` | zotero | `zotero.item`, `zotero.aggregate` | none | yes | none | free |
 | `omnischolar_read` | literature | `literature.read`, `literature.fulltext`, `literature.figures`, `literature.formulas` | none | no | none | free |
+| `omnischolar_focus` | literature | `literature.focus`, `literature.retrieval`, `literature.evidence` | none | no | none | free |
+| `omnischolar_locate` | literature | `literature.locate`, `literature.paragraphs`, `literature.evidence` | none | no | none | free |
+| `omnischolar_context` | literature | `literature.context.open`, `literature.context.append`, `literature.context.read` | filesystem | no | none | free |
 | `omnischolar_parse` | parsing | `pdf.parse`, `sync.publish` | external-upload | yes | mineru | metered |
 | `omnischolar_sync` | parsing | `sync.plan`, `sync.apply`, `sync.recovery` | filesystem | yes | none | free |
 | `ai4scholar_search` | ai4scholar | `ai4scholar.search` | paid | yes | ai4scholar | paid |

package/docs/TOOLS.md

@@ -19,6 +19,9 @@
 | `zotero_search` | zotero | `zotero.search` | none | yes | none | free |
 | `zotero_item` | zotero | `zotero.item`, `zotero.aggregate` | none | yes | none | free |
 | `omnischolar_read` | literature | `literature.read`, `literature.fulltext`, `literature.figures`, `literature.formulas` | none | no | none | free |
+| `omnischolar_focus` | literature | `literature.focus`, `literature.retrieval`, `literature.evidence` | none | no | none | free |
+| `omnischolar_locate` | literature | `literature.locate`, `literature.paragraphs`, `literature.evidence` | none | no | none | free |
+| `omnischolar_context` | literature | `literature.context.open`, `literature.context.append`, `literature.context.read` | filesystem | no | none | free |
 | `omnischolar_parse` | parsing | `pdf.parse`, `sync.publish` | external-upload | yes | mineru | metered |
 | `omnischolar_sync` | parsing | `sync.plan`, `sync.apply`, `sync.recovery` | filesystem | yes | none | free |
 | `ai4scholar_search` | ai4scholar | `ai4scholar.search` | paid | yes | ai4scholar | paid |

package/host-configs/README.md

@@ -8,4 +8,4 @@
 - Pi: see `pi.md`; the npm Extension bridges the local MCP server
 - WorkBuddy/CodeBuddy: merge `workbuddy.json` into `~/.codebuddy/.mcp.json` or project `.mcp.json`
 
-All supported MCP entries start the latest PyPI package with `uvx --from luffysolution-omnischolar@latest omnischolar mcp`. These files contain no provider credentials.
+All supported MCP entries start the latest PyPI package with `uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp`. These files contain no provider credentials.

package/host-configs/hermes.yaml

@@ -1,6 +1,6 @@
 mcp_servers:
   omnischolar:
     command: "uvx"
-    args: ["--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"]
+    args: ["--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"]
     # Optional: restrict exposure with tools.include or tools.exclude.
     # Inherit OMNISCHOLAR_* and provider environment variables from Hermes.

package/host-configs/opencode.jsonc

@@ -3,7 +3,7 @@
   "mcp": {
     "omnischolar": {
       "type": "local",
-      "command": ["uvx", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
+      "command": ["uvx", "--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
       "enabled": true,
       "timeout": 10000
     }

package/host-configs/workbuddy.json

@@ -3,7 +3,7 @@
     "omnischolar": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
+      "args": ["--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
       "description": "OmniScholar research tools"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luffysolution/omnischolar-pi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.2.0" };
+const CLIENT_INFO = { name: "omnischolar-pi", version: "0.3.0" };
 export function resultText(result) {
     return result.content
         .map((item) => {

package/skills/academic-citation/SKILL.md

@@ -2,7 +2,6 @@
 name: academic-citation
 description: Verify, format, and insert scholarly citations with OmniScholar. Use for APA, IEEE, GB/T 7714 and other styles, citation-network evidence, bibliography generation, candidate discovery, or verified citation insertion.
 license: MIT
-compatibility: Requires OmniScholar. Online verification needs an enabled literature provider; Ai4Scholar formatting and candidate operations require configured credentials.
 ---
 
 # Academic citation

package/skills/chemical-data/SKILL.md

@@ -2,7 +2,6 @@
 name: chemical-data
 description: Inspect CAS Common Chemistry contract status and query substance records only when a provider-issued API contract is configured. Use for chemical names, CAS Registry Numbers, structures, and basic compound information; not literature, reaction, or materials-property discovery.
 license: MIT
-compatibility: Requires OmniScholar. CAS search and detail remain contract-blocked unless the user supplies an authorized provider-issued endpoint/request/response contract.
 ---
 
 # Chemical substance data

package/skills/literature-reading/SKILL.md

@@ -10,11 +10,11 @@ Follow the user's language. Keep the original paper and generated Markdown on di
 
 ## Select a mode
 
-- `full`: read the entire paper progressively with `omnischolar_read`, following `nextCursor` until `hasMore` is false. Summarize each section before moving on.
-- `figures`: retrieve figure/table asset paths, captions, and section context. Inspect the referenced local assets when the host supports image input; distinguish visual observations from captions and author claims.
+- `full`: use `omnischolar_focus` first to identify relevant sections, then read the entire paper progressively with `omnischolar_read`, following `nextCursor` until `hasMore` is false. Summarize each section before moving on.
+- `figures`: retrieve figure/table asset paths, captions, bounded analysis context, and section context. Inspect the referenced local assets when the host supports image input; distinguish visual observations from captions and author claims.
 - `formulas`: retrieve bounded displayed formulas with their section headings. Explain symbols and assumptions only when supported by nearby text.
-- `paragraphs`: use `query` and optionally `section` to retrieve matching paragraphs instead of loading the document.
-- `compare`: pass multiple Zotero keys and retrieve compact, comparable metadata, abstracts, headings, and requested evidence.
+- `paragraphs`: use `omnischolar_locate` for stable line/character anchors, or `query` and optionally `section` with `omnischolar_read` for bounded matching paragraphs.
+- `compare`: pass multiple Zotero keys and retrieve compact, comparable metadata, abstracts, headings, and requested evidence. Add `contextId` when later questions should reuse only the selected evidence.
 - `review`: pass multiple Zotero keys and build a literature-review evidence matrix. Preserve differences in methods, population/materials, outcomes, limitations, and confidence; do not merge claims merely because titles are similar.
 
 ## Workflow
@@ -23,8 +23,9 @@ Follow the user's language. Keep the original paper and generated Markdown on di
 2. Use `zotero_item` with `mode=item` for metadata and `mode=aggregate` only when notes, annotations, or attachment selection are needed.
 3. Confirm the selected PDF and run `omnischolar_sync` with `action=plan` before parsing.
 4. Parse only when structured content is necessary and external upload is authorized. `omnischolar_parse` returns a local publication path and parse metadata, not the full Markdown body.
-5. Use `omnischolar_read` for bounded evidence retrieval. Record Zotero key, Markdown path, heading, figure/table/formula identifier, and cursor where relevant.
-6. State OCR, layout, formula, table, and missing-text limitations. Never treat Zotero notes or annotations as independent evidence without labeling them.
+5. Use `omnischolar_focus` for cross-paper evidence retrieval, `omnischolar_locate` for exact paragraph anchors, and `omnischolar_read` for bounded mode-specific reading. Record Zotero key, Markdown path, heading, figure/table/formula identifier, line locator, and cursor where relevant.
+6. Open an `omnischolar_context` for multi-turn work and append only selected evidence. Context reads are paginated; they are not a substitute for the original paper.
+7. State OCR, layout, formula, table, and missing-text limitations. Never treat Zotero notes or annotations as independent evidence without labeling them.
 
 Full-text mode is intentionally paginated. Never bypass pagination by requesting an oversized result. If a retrieved excerpt is truncated, continue with its cursor rather than guessing the missing text.
 

package/skills/literature-retrieval/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: literature-retrieval
+description: Find focused evidence in parsed local papers, locate paragraphs, compare selected papers, and maintain a bounded reading context without loading whole documents.
+license: MIT
+---
+
+# Focused literature retrieval
+
+Use this workflow when the task is to find where a paper discusses a concept, method, result, limitation, or comparison dimension. Retrieval is evidence selection; it is not itself a scientific conclusion.
+
+## Workflow
+
+1. Match the Zotero parent by DOI first, then normalized title/year/author. If the match or PDF attachment is ambiguous, stop and report the choices.
+2. Use `zotero_item` with `mode=item` for identity. Use `mode=aggregate` only when attachment selection or annotations are needed.
+3. Confirm local parsed output with `omnischolar_sync` and `action=plan`. Parse only when structured content is needed and an external upload is authorized.
+4. Call `omnischolar_focus` with a short research concept, optional `keys`, `section`, `topK`, and `includeContext`. Treat returned `excerpt`, heading, paragraph ID, and line locator as the evidence packet.
+5. Call `omnischolar_locate` when the user needs exact paragraphs in one paper. Prefer `matchMode=phrase` for a quoted phrase and `allTerms` for a concept.
+6. Use `omnischolar_context` with `action=open` before a long multi-turn task. Pass its `contextId` to focus, locate, and `omnischolar_read`; retrieve the cache later with a bounded `get` call.
+7. For several papers, use `omnischolar_read` with `mode=compare` or `mode=review`, pass `contextId` when continuity is needed, and preserve per-paper provenance.
+
+## Retrieval policy
+
+- The current local retriever uses bounded BM25-style lexical retrieval plus a transparent TF-IDF vector score. It does not claim dense semantic embedding support; `semantic` remains `false` until a real embedding backend is configured.
+- Exact identifiers, formulas, material names, gene/protein names, numbers, and quoted phrases should be verified with `omnischolar_locate` or a section read even when focused search returns a hit.
+- `markdownPath` is a local provenance field. Do not expose unrelated local files, credentials, or Zotero private data.
+- A cache stores selected excerpts only. Never add an entire paper or an unbounded tool response to a context.
+- Distinguish extracted text, caption/table content, visual observations, author claims, interpretation, and uncertainty in the final answer.
+
+## Handoff to reading modes
+
+- `full`: follow `nextCursor` with `omnischolar_read`; never request an oversized page.
+- `figures`: use `omnischolar_read` with `mode=figures`; inspect the referenced asset when the host supports images, then separate caption, visual observation, and claim.
+- `formulas`: use `mode=formulas` and explain symbols only with nearby evidence.
+- `compare`/`review`: use bounded per-paper evidence and an evidence matrix; do not merge similar claims without checking methods and populations/materials.

package/skills/materials-project/SKILL.md

@@ -2,7 +2,6 @@
 name: materials-project
 description: Query Materials Project records, inspect structures and phase data, and export sourced results with OmniScholar. Use for materials screening, property retrieval, phase analysis, XRD capability checks, or JSON/CSV/Markdown/CIF export.
 license: MIT
-compatibility: Requires OmniScholar and a Materials Project API key. Simulated XRD additionally requires the optional local backend reported by the runtime.
 ---
 
 # Materials Project

package/skills/omnischolar/SKILL.md

@@ -13,6 +13,7 @@ Choose the smallest workflow that answers the request. Follow the user's languag
 - Literature, patents, authors, citation graphs, recommendations, journals, snippets, or datasets: follow `scholar-search`.
 - Local collections, metadata, notes, annotations, attachments, or PDF selection: follow `zotero-research`.
 - Structured PDF text, equations, tables, figures, or close reading: follow `paper-reading`.
+- Focused retrieval, paragraph location, evidence caching, or retrieval-first paper work: follow `literature-retrieval`.
 - Interpreting parsed papers, full-text reading, figure/formula analysis, comparisons, or literature reviews: follow `literature-reading`.
 - Citation evidence, candidates, formatting, or insertion: follow `academic-citation`.
 - Generated or edited illustrations: follow `scientific-figure`.

package/skills/paper-reading/SKILL.md

@@ -2,7 +2,6 @@
 name: paper-reading
 description: Parse and analyze a selected local PDF with OmniScholar and MinerU. Use when the task needs structured full text, equations, tables, figures, captions, or close reading beyond metadata and Zotero notes.
 license: MIT
-compatibility: Requires OmniScholar; Zotero-based reading needs local Zotero, and external parsing needs configured MinerU access.
 ---
 
 # PDF parsing and close reading

package/skills/zotero-research/SKILL.md

@@ -2,7 +2,6 @@
 name: zotero-research
 description: Search and inspect the user's local Zotero library with OmniScholar. Use for collections, bibliographic metadata, notes, annotations, attachments, indexed text, local-paper matching, or selecting a PDF without modifying Zotero.
 license: MIT
-compatibility: Requires OmniScholar and a running Zotero desktop instance with local application access enabled.
 ---
 
 # Read-only Zotero research