dsh-book-reader 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] — 2026-10-20
+
+### Changed
+
+- Search is now a basic in-page find bar: `Cmd/Ctrl+F` opens it, matches are
+  highlighted on the PDF text layer, and `Enter` / `Shift+Enter` (or the
+  previous/next buttons) jump between occurrences with an `n / total` counter.
+- The search result list, its snippets, and the per-result “→ AI” insertion are
+  gone; search no longer inserts anything into the composer.
+- `pdf_search` is now normalized text search: wrapping quotes/backticks and
+  `$…$` are stripped, NFKC folds math alphanumerics and ligatures, dashes and
+  line-break hyphenation are removed, and if no literal phrase matches it falls
+  back to a space-insensitive pass (`compact`) and then keyword AND (`terms`).
+  The result gains `mode`; hits rank body pages before front matter (at most 3
+  front-matter hits), `pages` counts every matched page, and the tool default
+  limit is 30. The tool description now states these rules so the model stops
+  passing quoted or LaTeX-marked phrases.
+- `pdf_search` accepts an optional `pages` selection (the same syntax as
+  `pdf_read_pages`; printed pages by default, `page_numbers:"pdf"` for physical
+  pages) to scan only a page range and report matches inside it. This keeps a
+  late-chapter search from being crowded out by earlier pages.
+
+### Fixed
+
+- Opening a book now jumps to the remembered page immediately, before a saved
+  fixed zoom is replayed, so the cover no longer flashes for a few hundred
+  milliseconds while the zoom settles. The scroll is re-applied after the zoom
+  commit so the page stays aligned.
+
 ## [0.2.0] — 2026-10-20
 
 ### Added
@@ -16,8 +45,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - New config key `rememberView` (default `true`).
 - Host routes `GET /dsh-pdf-reader/view?path=…` and
   `POST /dsh-pdf-reader/view` for the browser half.
-- Docs: the README is split into a concise English `README.md` and a concise
-  Simplified Chinese `README.zh-CN.md`; they no longer share one page.
+- Docs: the README is split into an English `README.md` and a Simplified Chinese
+  `README.zh-CN.md`, both rewritten in a product-page style (badges, quick start,
+  feature table, model-tool examples, FAQ, data/privacy notes).
 
 ## [0.1.1] — 2026-10-18
 
@@ -71,6 +101,7 @@ First public release.
 - `pdfjs-dist` is pinned to `6.3.289` to match the host process.
 - MIT licensed.
 
+[0.3.0]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.3.0
 [0.2.0]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.2.0
 [0.1.1]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.1.1
 [0.1.0]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.1.0

package/README.md

@@ -1,54 +1,90 @@
 # dsh-book-reader
 
-A reading toolbar for DSH's official PDF preview, plus three PDF tools the model can use.
+[![npm version](https://img.shields.io/npm/v/dsh-book-reader.svg)](https://www.npmjs.com/package/dsh-book-reader)
+[![license](https://img.shields.io/npm/l/dsh-book-reader.svg)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-0.2.x-blue)](https://github.com/deepseek-ai/deepseek-harness)
+
+**Read PDFs in DSH together with the model.** A native toolbar on the official PDF preview, plus three tools the model can use to look up the TOC, search the full text, and read pages — page images included, when a formula or diagram needs to be seen.
 
 [中文说明](README.zh-CN.md)
 
-## Features
+## Why this one
+
+- **Native, not a replacement.** It decorates DSH's own PDF preview, so zoom, text selection, reload, and Office→PDF keep working. No extra viewer, no sidebar dependency.
+- **The model can actually read the book.** Three tools give it the page map, text search, and page content, with page images only when needed.
+- **It remembers where you were.** Reopening a book restores the last page and zoom.
+
+## Quick start
 
-**Reading toolbar** — only on `.pdf` previews in the right sidebar; the stock previewer is untouched.
+1. DSH **Plugins → Add plugin** → `dsh-book-reader` (or `dsh plugin add dsh-book-reader`). Restart DSH.
+2. Open any `.pdf` in the right sidebar — the toolbar appears in the preview header.
+3. Ask the model about the PDF; it can search and read from now on.
+
+Optional — give the model the reading guide (costs, page numbering, pitfalls):
+
+```sh
+ln -sfn "<installed package dir>" "<workspace>/.dsh/skills/pdf-reader"
+```
+
+## Features
 
-- Previous/next page, a current-page readout, and a jump box (printed page numbers, or `p152` for PDF page 152).
-- Full-text search with `Cmd/Ctrl+Shift+F`; click a result to jump, or insert its page reference into the chat.
-- AI position hint: before each turn the model may receive one short “you are reading page N” line (the `AI●` toggle, on by default).
-- **Remembers your place**: reopening a book restores the last page and zoom. State is stored by DSH per book and survives restarts.
-- Hover/focus explanations on every control, in English or Chinese.
+| | Feature | What it does |
+| --- | --- | --- |
+| 🧭 | Navigation | Previous/next page, page readout, jump box (printed page, or `p152` for PDF page 152) |
+| 🔎 | Search | Full-text search (`Cmd/Ctrl+F`) with in-page highlights; `Enter` / `Shift+Enter` jump between occurrences, no snippets |
+| 🤖 | AI position hint | One short “you are reading page N” line per turn, only when the page changed (`AI●` toggle) |
+| 💾 | Reading memory | Remembers page and zoom per book; restores them when you reopen it |
+| 💬 | Tooltips | Hover/focus explanations on every control, English or Chinese |
+| 🧰 | Model tools | `pdf_info`, `pdf_search`, `pdf_read_pages` — see below |
 
-**Model tools** — the model calls them when you ask about a PDF.
+## Model tools
 
-| Tool | What it does |
-| --- | --- |
-| `pdf_info` | Page count, printed↔physical page offset, outline/TOC |
-| `pdf_search` | Literal full-text search; page numbers and snippets |
-| `pdf_read_pages` | Reads chosen pages as text, optionally with page images |
+| Tool | Use it for | Cost |
+| --- | --- | --- |
+| `pdf_info` | Page count, printed↔physical page offset, outline/TOC | text, ~free |
+| `pdf_search` | Finding a phrase, theorem number, or figure caption. Tolerates quotes/LaTeX, hyphen and math-notation splits, with keyword fallbacks; body pages first; optional `pages` range | text, ~free |
+| `pdf_read_pages` | Reading chosen pages as text, optionally with page images | text ~free; images ~350–1024 tokens/page |
 
-## Install
+Example prompts:
 
-1. **Plugins → Add plugin** in DSH and enter `dsh-book-reader` (or run `dsh plugin add dsh-book-reader`).
-2. Restart DSH after installing or upgrading.
-3. Optional: give the model the reading guide by linking the skill into your workspace:
+> “What does chapter 5 of this book cover?” → `pdf_info` + `pdf_read_pages`
+> “Find where ‘singular value’ appears.” → `pdf_search`
+> “Search only chapter 7 (printed pp. 270–295) for ‘SVD’.” → `pdf_search` with `pages:"270-295"`
+> “Show me the formula in theorem 5.6.” → `pdf_read_pages` with images
 
-   ```sh
-   ln -sfn "<installed package dir>" "<workspace>/.dsh/skills/pdf-reader"
-   ```
+The model decides when text is enough and when an image is worth it.
 
 ## Configuration
 
-All keys are optional and the defaults are safe. Common ones:
+Every key is optional and the defaults are safe. Common ones:
 
 - `rememberView` (default `true`) — remember page/zoom per book.
-- `maxPagesPerCall` (default `4`) — page cap for `pdf_read_pages`.
-- `defaultScale` (default `2.5`) — image render scale.
+- `maxPagesPerCall` (default `4`) — page cap per read call.
+- `defaultScale` (default `2.5`) — image render scale (~180 DPI).
 - `autoShare` (default `true`) — the AI position hint.
 
 The full list with defaults is in [`cordis.patch.yml`](cordis.patch.yml).
 
+## FAQ
+
+**The toolbar does not appear.** Only `.pdf` previews get it (not `.docx`/`.pptx`/images). Update/reinstall the plugin and restart DSH.
+
+**The model does not know my page.** The hint is sent at most once per turn and only when the page changed; turn on `AI●`, or mention the page in your message.
+
+**Scanned PDFs.** No text layer: search finds nothing and text reads are empty. Page images still work — check `textCoverage.isLikelyScanned` from `pdf_info`.
+
+**Search finds nothing.** Quotes and `$…$` are stripped, hyphen/math splits and missing spaces have fallbacks, and when no literal phrase matches the tool falls back to keyword AND (`mode` in the result says which pass matched). Try one short distinctive word.
+
+**Does it modify my PDF?** No. It only reads and renders; nothing is written next to your books.
+
+**Where is the remembered state?** In DSH's data directory (`~/.dsh/storages/book_reader_views.json`), at most 500 books, keyed by file path.
+
+**A DSH upgrade broke the toolbar.** The toolbar relies on the preview's private DOM markers; page tools keep working regardless.
+
 ## Notes
 
-- Only the official PDF preview is supported; the toolbar relies on that preview's private DOM markers, so a DSH upgrade may change behavior.
-- Tools read only inside the session workspace unless `allowOutsideWorkspace` is set; the local HTTP routes are loopback-only and unauthenticated.
-- Scanned PDFs have no text layer — page images are the only option (no OCR).
-- `pdfjs-dist` is pinned to `6.3.289` to match the host process.
+- Local HTTP routes are loopback-only and unauthenticated; model tools stay inside the session workspace by default (`allowOutsideWorkspace` opts out).
+- `pdfjs-dist` is pinned to `6.3.289` to match the DSH host process.
 
 ## More
 

package/README.zh-CN.md

@@ -1,36 +1,58 @@
 # dsh-book-reader
 
-给 DSH 官方 PDF 预览加一条读书工具栏，并给模型三个 PDF 工具。
+[![npm version](https://img.shields.io/npm/v/dsh-book-reader.svg)](https://www.npmjs.com/package/dsh-book-reader)
+[![license](https://img.shields.io/npm/l/dsh-book-reader.svg)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-0.2.x-blue)](https://github.com/deepseek-ai/deepseek-harness)
+
+**在 DSH 里和模型一起读 PDF。** 官方 PDF 预览上加一条原生工具栏，并给模型三个工具：查目录、全文搜索、读指定页——公式和图表需要时还能直接看页面图片。
 
 [English](README.md)
 
-## 功能
+## 为什么用它
+
+- **原生，不替换。** 装饰 DSH 自己的 PDF 预览器，缩放、选中、刷新、Office→PDF 都保持原样；不额外装阅读器、不依赖侧边栏插件。
+- **模型真的能读这本书。** 三个工具给它页码/目录、文本搜索和页面内容；只有需要看公式、图表时才花图片 token。
+- **记住你读到哪。** 再次打开同一本书，自动回到上次的页码和缩放。
+
+## 三步上手
 
-**阅读工具栏** —— 只在右侧栏的 `.pdf` 预览上出现，不替换官方预览器。
+1. DSH 的 **Plugins → Add plugin** → `dsh-book-reader`（或 `dsh plugin add dsh-book-reader`），重启 DSH。
+2. 在右侧栏打开任意 `.pdf`，预览头部出现工具栏。
+3. 直接问模型关于这本书的问题，它就能自己搜、自己读。
+
+可选——把阅读指南交给模型（成本、页码规则、常见坑）：
+
+```sh
+ln -sfn "<已安装的包目录>" "<workspace>/.dsh/skills/pdf-reader"
+```
+
+## 功能
 
-- 上一页/下一页、跟随滚动的页码读数、跳页框（印刷页码，或 `p152` 表示 PDF 第 152 页）。
-- 全文搜索（`Cmd/Ctrl+Shift+F`）：点结果跳页，或把该页引用插入对话框。
-- AI 位置提示：每轮对话开始前，模型可能收到一行“你正在看第 N 页”的短提示（`AI●` 开关，默认开）。
-- **记住阅读位置**：再次打开同一本书时恢复上次的页码和缩放；状态按书保存在 DSH 侧，重启后仍有效。
-- 每个控件都有悬停/聚焦说明，跟随 DSH 界面语言（中文或英文）。
+| | 功能 | 说明 |
+| --- | --- | --- |
+| 🧭 | 翻页与跳页 | 上一页/下一页、跟随滚动的页码读数、跳页框（印刷页码，或 `p152` 表示 PDF 第 152 页） |
+| 🔎 | 全文搜索 | `Cmd/Ctrl+F` 打开搜索，命中文字在页面上高亮；`Enter` / `Shift+Enter` 在命中之间顺序跳转，不显示摘要 |
+| 🤖 | AI 位置提示 | 每轮对话最多一行“你正在看第 N 页”，页码变了才发（`AI●` 开关） |
+| 💾 | 阅读记忆 | 按书记住页码和缩放，重新打开时恢复 |
+| 💬 | 悬停说明 | 每个控件都有悬停/聚焦提示，跟随 DSH 界面语言（中/英） |
+| 🧰 | 模型工具 | `pdf_info`、`pdf_search`、`pdf_read_pages`，见下 |
 
-**模型工具** —— 你问 PDF 内容时由模型调用。
+## 模型工具
 
-| 工具 | 作用 |
-| --- | --- |
-| `pdf_info` | 页数、印刷页↔物理页偏移、目录/TOC |
-| `pdf_search` | 字面全文搜索；返回页码和摘要 |
-| `pdf_read_pages` | 读取指定页的文本，也可返回页面图片 |
+| 工具 | 用途 | 成本 |
+| --- | --- | --- |
+| `pdf_info` | 页数、印刷页↔物理页偏移、目录/TOC | 文本，几乎免费 |
+| `pdf_search` | 找短语、定理编号、图表标题。容忍引号/LaTeX、连字符与数学符号拆分，支持关键词回退；正文页优先；可用 `pages` 限定页范围 | 文本，几乎免费 |
+| `pdf_read_pages` | 读指定页的文本，可选返回页面图片 | 文本几乎免费；图片约 350–1024 token/页 |
 
-## 安装
+可以这样问：
 
-1. DSH 的 **Plugins → Add plugin** 输入 `dsh-book-reader`（或命令行 `dsh plugin add dsh-book-reader`）。
-2. 安装或升级后重启 DSH。
-3. 可选：把 skill 软链到工作区，让模型拿到阅读流程说明：
+> “这本书第 5 章讲了什么？” → `pdf_info` + `pdf_read_pages`
+> “找一下 singular value 出现在哪几页。” → `pdf_search`
+> “只在第 7 章（印刷页 270–295）里找 SVD。” → `pdf_search` 加 `pages:"270-295"`
+> “把定理 5.6 的公式截给我看。” → `pdf_read_pages` 带图片
 
-   ```sh
-   ln -sfn "<已安装的包目录>" "<workspace>/.dsh/skills/pdf-reader"
-   ```
+什么时候用文本、什么时候值得花图片 token，由模型自己判断。
 
 ## 配置
 
@@ -38,17 +60,31 @@
 
 - `rememberView`（默认 `true`）—— 按书记住页码/缩放。
 - `maxPagesPerCall`（默认 `4`）—— 单次读页上限。
-- `defaultScale`（默认 `2.5`）—— 图片渲染倍率。
+- `defaultScale`（默认 `2.5`）—— 图片渲染倍率（约 180 DPI）。
 - `autoShare`（默认 `true`）—— AI 位置提示。
 
 完整键和默认值见 [`cordis.patch.yml`](cordis.patch.yml) 注释。
 
+## 常见问题
+
+**看不到工具栏？** 只有 `.pdf` 预览会挂工具栏（`.docx`/`.pptx`/图片不会）。升级/重装插件后重启 DSH。
+
+**模型不知道我在哪一页？** 位置提示每轮最多一次、页码变了才发；打开 `AI●`，或直接在消息里提页码。
+
+**扫描件？** 没有文本层：搜索为空、文本读页为空；页面图片仍然可用，先用 `pdf_info` 的 `textCoverage.isLikelyScanned` 判断。
+
+**搜索找不到东西？** 引号和 `$…$` 会被去掉，连字符/数学符号拆分、缺空格有回退；整句没有字面命中时会退化成关键词 AND 搜索（结果的 `mode` 会说明命中方式）。试一个更短、更独特的词。
+
+**会改我的 PDF 吗？** 不会。只读取和渲染，不会往书目录写任何东西。
+
+**记住的状态存哪？** DSH 数据目录下的 `~/.dsh/storages/book_reader_views.json`，按文件路径索引，最多保留 500 本。
+
+**DSH 升级后工具栏失效？** 工具栏依赖预览器的私有 DOM 标记；即使失效，模型工具仍然可用。
+
 ## 说明
 
-- 只支持官方 PDF 预览；工具栏依赖该预览的私有 DOM 标记，DSH 升级可能影响行为。
-- 工具默认只在会话工作区内读取（可设 `allowOutsideWorkspace`）；本地 HTTP 路由只认回环地址、无鉴权。
-- 扫描件没有文本层，只能看图（没有 OCR）。
-- `pdfjs-dist` 锁定 `6.3.289`，以和宿主进程一致。
+- 本地 HTTP 路由只认回环地址、无鉴权；模型工具默认只在会话工作区内读取（可设 `allowOutsideWorkspace`）。
+- `pdfjs-dist` 锁定 `6.3.289`，与 DSH 宿主进程保持一致。
 
 ## 更多
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pdf-reader
-description: 'Read a PDF (book, paper, manual) cheaply and accurately with the dsh-book-reader tools: page map/TOC, literal full-text search, then selective page reads (text first, images only when typography matters). Use whenever the user asks about specific pages, a section, a theorem, a figure, or "this page" in a PDF.'
+description: 'Read a PDF (book, paper, manual) cheaply and accurately with the dsh-book-reader tools: page map/TOC, normalized text search (quote/LaTeX-tolerant, with hyphen/space and keyword fallbacks), then selective page reads (text first, images only when typography matters). Use whenever the user asks about specific pages, a section, a theorem, a figure, or "this page" in a PDF.'
 ---
 
 # Reading a PDF with `dsh-book-reader`
@@ -11,7 +11,7 @@ expense, not the first move.
 | Tool | Cost | Use for |
 | --- | --- | --- |
 | `pdf_info` | ~0 (text) | page count, printed↔physical offset, outline/TOC |
-| `pdf_search` | ~0 (text) | locating a phrase, theorem number, or figure caption |
+| `pdf_search` | ~0 (text) | locating a phrase, theorem number, or figure caption (quotes and `$…$` are stripped; optional `pages` range) |
 | `pdf_read_pages` + `include_image:false` | ~0 (text, per page) | prose, theorem statements, exercise text |
 | `pdf_read_pages` (images on) | **~350–1024 tokens/page** | formulas, diagrams, tables, layout |
 
@@ -19,7 +19,12 @@ expense, not the first move.
 
 1. `pdf_info` once per document → note `printedOffset` and the outline. Never
    hardcode an offset; it is detected (`printed = pdf − printedOffset`).
-2. `pdf_search` for a distinctive phrase → page numbers.
+2. `pdf_search` for a short, distinctive phrase → page numbers. If the result's
+   `mode` is not `"phrase"` (i.e. `"compact"` or `"terms"`), treat the hits as
+   candidate pages and read them before quoting exact wording. When the reader
+   is late in the book (or the position hint says so), pass `pages:"…"` around
+   the current printed page (e.g. `pages:"270-295"`) so earlier chapters cannot
+   crowd the 30-hit budget; `page_numbers:"pdf"` switches to physical pages.
 3. `pdf_read_pages` with **`include_image:false`** to read those pages as text.
 4. Only if the text is ambiguous or the question is about typography (a formula,
    a diagram, a table) → call again with images on, and crop.
@@ -82,7 +87,20 @@ needs it, and prefer `include_image:false` first.
 - `pdf_info` also reports `title`, `author`, `fileSizeBytes`, `pageSize` and
   `textCoverage` (`isLikelyScanned`). Check `textCoverage.isLikelyScanned`
   *before* searching: a scanned PDF has no text layer, so go straight to images.
-- Search is literal: it does not unfold hyphenation and is not a regex engine.
+- **`pdf_search` is normalized text search, not a regex engine.** Wrapping
+  quotes/backticks and `$…$` are stripped; NFKC folds math alphanumerics
+  (`ℒ (𝑉)`→`L (V)`) and ligatures; dash variants are dropped, so line-break
+  hyphenation (`com- plex`) matches `complex`. If no literal phrase matches, the
+  tool falls back to a space-insensitive pass (`mode: "compact"`, so `L(V)`
+  finds `ℒ (𝑉)`) and then to keyword AND (`mode: "terms"`). Body pages rank
+  before front matter (at most 3 front-matter hits), `pages` counts every matched
+  page before `limit`, and the default limit is 30. If a query finds nothing, try
+  one shorter distinctive word and read the pages rather than assuming absence.
+- **`pdf_search` can be scoped to a page range.** `pages:"270-295"` (same syntax
+  as `pdf_read_pages`, printed pages by default) only scans those pages; the
+  returned `pages` count then counts matches inside that range. Use it when the
+  user is reading a later chapter and whole-book hits would be dominated by
+  earlier pages.
 - Page numbers are 1-based; relative paths resolve against the session directory.
 - No annotation/note features: this plugin reads and renders only.