dsh-book-reader 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+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.1.1] — 2026-10-18
+
+### Changed
+
+- Simplified, feature-focused README (English + 中文) that leads with what the
+  plugin does instead of full internals documentation.
+- The automatic reading-position hint is now sent **at most once per turn**, and
+  only when the page changed. The per-step guard and the 3-minute default
+  throttle are gone: `autoShareMinSteps` was removed and
+  `autoShareMinIntervalMs` now defaults to `0` (optional extra throttle).
+- Repository, homepage, and issue links now point to
+  `github.com/Strepsiades2/dsh-book-reader`.
+
+### Removed
+
+- The `pdf_current_page` tool. The per-turn position hint (or a page reference
+  you insert yourself) now covers “which page am I on”, leaving three tools:
+  `pdf_info`, `pdf_search`, and `pdf_read_pages`.
+- The toolbar's manual “insert current page reference” (↗) button. The
+  automatic per-turn position hint already tells the model the current page, so
+  the button was redundant. The search panel's per-result “→ AI” insertion
+  remains.
+
+## [0.1.0] — 2026-10-18
+
+First public release.
+
+### Added
+
+- Toolbar controls on DSH's official PDF preview: previous/next page, printed
+  and physical page readout with a jump box, full-text search panel
+  (`Cmd/Ctrl+Shift+F`), share-page reference insertion, and an AI reading-position
+  toggle.
+- Hover explanations for every toolbar control, in the active DSH UI language
+  (English and Simplified Chinese).
+- Four model-facing tools: `pdf_info` (page map and outline), `pdf_search`
+  (literal full-text search), `pdf_read_pages` (text first, optional page
+  images), and `pdf_current_page` (what the user is reading).
+- Per-turn reading-position injection behind `agent/pre-step`, debounced and
+  rate-limited.
+- Local JSON routes for the browser half, loopback-only and restricted by
+  `routeAllowedRoots` / the session workspace by default.
+- Bundle display metadata: localized title/description and an SVG icon for the
+  DSH Plugins page.
+
+### Notes
+
+- Depends on the official preview's private DOM markers; DSH upgrades may change
+  them.
+- `pdfjs-dist` is pinned to `6.3.289` to match the host process.
+- MIT licensed.
+
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the dsh-book-reader authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# dsh-book-reader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read books and papers in DSH: a reading toolbar on the official PDF preview, plus three PDF tools for the model.
+
+**English** | [中文](#中文说明)
+
+## Features
+
+**Reading toolbar** — appears only on `.pdf` previews in the right sidebar; the stock previewer (zoom, selection, reload) is untouched.
+
+- Previous/next page, a page readout that follows scrolling, and a jump box that accepts printed page numbers (or `p152` for PDF page 152).
+- Full-text search panel (`Cmd/Ctrl+Shift+F`): click a result to jump there, or insert its page reference into the chat.
+- **AI position hint** (on by default): before a turn starts, the model may receive one short line with the page you are reading — at most once per turn, and only when the page changed since the last hint. Turn it off if you do not want the model to know your page automatically.
+- Every control has a hover/focus explanation in English or Chinese, following the DSH UI language.
+
+**Model tools** — the model can look up the page map, search the text, or read chosen pages (as text or as page images) when you ask about a PDF.
+
+| Tool | What it does |
+| --- | --- |
+| `pdf_info` | Page count, printed↔physical page offset, outline/TOC. Text only. |
+| `pdf_search` | Literal full-text search; returns page numbers and snippets. |
+| `pdf_read_pages` | Text of chosen pages, optionally as images (`include_image: false` for text only; images cost ~350–1024 tokens/page). |
+
+Typical loop: `pdf_info` → `pdf_search` → `pdf_read_pages` (text) → images only for formulas, diagrams, or tables.
+
+## Install
+
+- **From npm**: DSH **Plugins → Add plugin** → `dsh-book-reader` (or pin `dsh-book-reader@0.1.1`), or `dsh plugin add dsh-book-reader`.
+- A fresh install applies live (this profile has HMR); **upgrading a plugin that is already loaded needs a DSH restart** to load the new code.
+- **Optional skill** (gives the model the built-in PDF reading guide): symlink the package into the workspace:
+  ```sh
+  ln -sfn "<installed package dir>" "<workspace>/.dsh/skills/pdf-reader"
+  ```
+- **Local checkout**: `dsh plugin add "/abs/path/to/dsh-book-reader"`; keep the checkout and its `node_modules/` in place.
+
+## Configuration
+
+Every option is optional and the defaults are safe. Common ones: `maxPagesPerCall` (default 4), `defaultScale` (2.5), `autoShare` (automatic position hint), `allowOutsideWorkspace` (tools stay inside the session workspace by default), `routeAllowedRoots` (restrict the local HTTP routes). The full list with defaults is commented in [`cordis.patch.yml`](cordis.patch.yml).
+
+## Notes
+
+- HTTP routes are loopback-only and unauthenticated; the tools are workspace-scoped by default. Other local preview plugins make the same tradeoff.
+- Works only with the official PDF preview: it relies on that preview's DOM markers, which a DSH upgrade may change.
+- Scanned PDFs have no text layer — there is no OCR, so only page images help.
+- `pdfjs-dist` is pinned to `6.3.289` to match the host process.
+
+## More
+
+- [`SKILL.md`](SKILL.md) — model-facing guide: costs, page numbering, pitfalls.
+- [`CHANGELOG.md`](CHANGELOG.md) · [`LICENSE`](LICENSE) (MIT)
+
+---
+
+## 中文说明
+
+在 DSH 里读 PDF 书和论文：官方 PDF 预览上加一条读书工具栏，外加三个 PDF 工具给模型。
+
+### 功能
+
+**阅读工具栏** —— 只在右侧栏的 `.pdf` 预览上出现；不替换官方预览器（缩放、选中、刷新都保持原样）。
+
+- 上一页/下一页、随滚动更新的页码读数、跳页框（输入印刷页码，或 `p152` 表示 PDF 第 152 页）。
+- 全文搜索面板（`Cmd/Ctrl+Shift+F`）：点结果跳页，或把该页引用插入对话框。
+- **AI 位置提示**（默认开）：每轮对话开始时，模型可能收到一行“你正在看第 N 页”的短提示 —— 每轮最多一次，且页码变了才发。关掉后，模型不会自动知道你在哪页。
+- 每个控件都有 hover / 键盘聚焦提示，跟随 DSH 界面语言（中文或英文）。
+
+**模型工具** —— 默认只花文本 token，图片是按需付的钱。
+
+| 工具 | 作用 |
+| --- | --- |
+| `pdf_info` | 页数、印刷页↔物理页偏移、目录/TOC；纯文本。 |
+| `pdf_search` | 字面全文搜索；返回页码和摘要。 |
+| `pdf_read_pages` | 选中页的文本，也可返回页面图片（`include_image: false` 只取文本；图片约 350–1024 token/页）。 |
+
+典型流程：`pdf_info` → `pdf_search` → `pdf_read_pages`（文本）→ 只有公式、图表、表格才看图。
+
+### 安装
+
+- **从 npm 安装**：DSH **Plugins → Add plugin** → 输入 `dsh-book-reader`（或锁定版本 `dsh-book-reader@0.1.1`），或命令行 `dsh plugin add dsh-book-reader`。
+- 全新安装即时生效（本 profile 已启用 HMR）；**升级已加载的插件需要完整重启 DSH** 才能加载新代码。
+- **可选 skill**（给模型一份内置的 PDF 阅读指南）：把包目录软链到工作区：
+  ```sh
+  ln -sfn "<已安装的包目录>" "<workspace>/.dsh/skills/pdf-reader"
+  ```
+- **本地开发**：`dsh plugin add "/abs/path/to/dsh-book-reader"`；源码目录和 `node_modules/` 必须留在原处。
+
+### 配置
+
+全部可选，默认值即安全值。常用：`maxPagesPerCall`（默认 4）、`defaultScale`（2.5）、`autoShare`（自动位置提示）、`allowOutsideWorkspace`（工具默认只读会话工作区）、`routeAllowedRoots`（限制本地 HTTP 路由）。完整键和默认值见 [`cordis.patch.yml`](cordis.patch.yml) 注释。
+
+### 说明
+
+- HTTP 路由只认回环地址且无鉴权；工具默认只在工作区内。其他本地预览插件也是同样的权衡。
+- 只支持官方 PDF 预览（依赖它的私有 DOM 标记，DSH 升级可能失效）。
+- 扫描件没有文本层，**没有 OCR**，只能看图。
+- `pdfjs-dist` 锁定 `6.3.289`，以和宿主进程保持一致。
+
+### 更多
+
+- [`SKILL.md`](SKILL.md) —— 模型使用手册：成本、页码、常见陷阱。
+- [`CHANGELOG.md`](CHANGELOG.md) · [`LICENSE`](LICENSE)（MIT）

package/SKILL.md

@@ -0,0 +1,96 @@
+---
+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.'
+---
+
+# Reading a PDF with `dsh-book-reader`
+
+Three tools, two cost tiers. **The default is text.** Images are a deliberate
+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_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 |
+
+## Default loop (text-first)
+
+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.
+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.
+
+## When images are worth it
+
+- The question is about a **formula's exact form**, a **matrix layout**, a
+  **diagram**, or **which theorem box** a sentence is in.
+- Extracted text is known to garble math: `P_{n−1}(C)` becomes `𝒫 𝑛 − 1(𝐂)`,
+  subscripts flatten, fractions collapse, theorem numbers split across lines.
+- Prefer `crop` (`"0,0,1,0.55"` = top 55%) and `image_quality:"cheap"` (1.5×,
+  ~350 tokens) unless dense subscripts need `scale:3`.
+
+## Token economics (DeepSeek vision billing)
+
+Each image is projected onto a 14 px patch grid, downsampled 3:1, and **capped at
+1024 tokens**. For a 6×9 in book page:
+
+| Render | Pixels | Tokens |
+| --- | --- | --- |
+| 1.5× (`image_quality:"cheap"`) | 563×954 | **347** |
+| **2.5× (default)** | 938×1590 | **914** |
+| 3× | 1125×1908 | 1002 (capped — no gain above ~2.7×) |
+
+- Hard cap `maxPagesPerCall` (default **4**) is enforced before rendering.
+- `pdf_read_pages` returns `imageTokens` and per-page `tokens`; check them.
+- Images stay in the conversation and are re-billed on later turns. **Read once,
+  then answer in text.**
+- Never request `scale` above 3: the provider downscales to the same grid anyway.
+
+## Page numbering
+
+`pdf_info` returns `printedOffset` with `physical = printed + printedOffset`.
+Tools accept either numbering; **printed is the default when detectable**.
+Roman-numeral front matter has no numeric printed page — use
+`page_numbers:"pdf"`. Say which numbering you mean when it is ambiguous.
+
+## The injected reading position
+
+At most one short line per turn may arrive as a user message, e.g.
+
+```
+[dsh-pdf-reader] 正在阅读《book》printed 132 (PDF 152) · Chapter 5 › 5B
+```
+
+It is a **position marker only**. The model decides whether to read anything.
+Do not read a page just because the marker exists; read it when the question
+needs it, and prefer `include_image:false` first.
+
+## Pitfalls
+
+- **Scanned PDFs** have no text layer: `pdf_search` finds nothing and
+  `include_image:false` returns `textUnavailable`. Only images help.
+- Errors are coded: `PDF_NOT_FOUND`, `PDF_NOT_FILE`, `PDF_ENCRYPTED`,
+  `PDF_CORRUPT`, `PDF_READER_INVALID_PAGE`, `PDF_READER_INVALID_SCALE`,
+  `PDF_RENDER_TIMEOUT`, `PDF_PAGE_TOO_LARGE`, `PDF_OUTSIDE_WORKSPACE`.
+- **Tools are workspace-scoped by default.** Pass a path inside the session
+  working directory; anything outside fails with `PDF_OUTSIDE_WORKSPACE` unless
+  the user set `allowOutsideWorkspace: true`.
+- `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.
+- Page numbers are 1-based; relative paths resolve against the session directory.
+- No annotation/note features: this plugin reads and renders only.
+
+## Fallback (plugin disabled)
+
+```sh
+node -e "import('./lib/core/render.js').then(async m=>{const r=await m.renderPageToPng('<abs pdf>',344,{scale:2.5});require('fs').writeFileSync('/tmp/p344.png',r.buffer);console.log(r.width+'x'+r.height)})"
+```
+
+then `read_image('/tmp/p344.png')`. Slower, bypasses the attachment cache —
+prefer the tools.

package/cordis.patch.yml

@@ -0,0 +1,30 @@
+# dsh-book-reader bundle patch: mount the plugin into the active profile.
+# Host half: pdf_info / pdf_search / pdf_read_pages tools,
+#            /dsh-book-reader/* routes, and a minimal per-turn reading-position
+#            line injected through agent/pre-step.
+# Browser half: page readout, jump, search panel, and share-to-chat on top of
+#               the official PDF preview's document-header slot.
+#
+# All config keys are optional. The defaults shown are the shipped behavior.
+- insert:
+    - id: pdf-reader
+      name: 'dsh-book-reader'
+      # config:
+      #   enabled: true
+      #   autoShare: true                 # false stops position hints
+      #   autoShareSection: true          # include the outline section in the line
+      #   autoShareMinIntervalMs: 0       # optional: min ms between hints (0 = no time throttle)
+      #   autoSharePageDelta: 1           # require a page change before another hint
+      #   autoShareMaxAgeMs: 0            # 0 = no age limit on a reported position
+      #   allowOutsideWorkspace: false    # tools may only read inside the session cwd
+#   routeAllowedRoots: []           # extra dirs the HTTP routes may serve; [] = any
+#   maxPagesPerCall: 4              # hard cap per pdf_read_pages call
+      #   defaultScale: 2.5               # ~180 DPI; never useful above ~2.7
+      #   maxTextCharsPerPage: 1200       # text kept per page (0 disables)
+      #   maxSearchResults: 100
+      #   maxOutlineEntries: 500
+      #   maxLabels: 0                    # 0 = omit page labels (cheapest)
+      #   outlineDepth: 1                 # 0=chapters, 1=sections, 2=subsections
+      #   debugCost: false                # append JSON cost lines to .debug-cost.log
+      #   debug: false                    # include error detail in HTTP 500 bodies
+      #   maxFileBytes: 268435456         # 256 MiB

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Book Reader">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4c6ef5"/>
+      <stop offset="1" stop-color="#364fc7"/>
+    </linearGradient>
+  </defs>
+  <rect x="3" y="3" width="58" height="58" rx="14" fill="url(#bg)"/>
+  <path d="M12 21.5c6.5-3.6 13-3.6 20 0v23c-7-3.2-13.5-3.2-20 0z" fill="#f8f9fa"/>
+  <path d="M52 21.5c-6.5-3.6-13-3.6-20 0v23c7-3.2 13.5-3.2 20 0z" fill="#e9ecef"/>
+  <path d="M32 21.5v23" fill="none" stroke="#adb5bd" stroke-width="1.6" stroke-linecap="round"/>
+  <path d="M38.5 17.5h6v13l-3-2.4-3 2.4z" fill="#ffd43b"/>
+</svg>