Book Shelf / 书架
A persistent DSH Web UI plugin that adds a full-page multi-format reader to the
sidebar and an AI explanation rail for selected text. It also includes a
separate paper library with paragraph/whole-paper translation and bilingual
comparison.
Install
- Download
dsh-epub-reader-2.4.4.tgz from the
latest release.
- In DSH open Plugins → Add plugin and choose the downloaded tgz.
- Reload the plugin and open 书架 in the sidebar.
Chinese step-by-step guide: INSTALL-zh.md. Publishing and npm
instructions: PUBLISHING.md.
What it does
- Shelf — scans the archive shelf (the first registered workspace by
default, which is
D:\BookLib on this deployment), plus any extra
libraryDirs, for supported book files.
- Copies external books — a book opened or imported from outside the
archive shelf is copied into
archiveDir first. Identical files are reused;
a name collision gets a (2) suffix rather than overwriting anything.
- Public-domain search — the Search books tab queries Project Gutenberg
(Gutendex, with the Gutenberg website search as a fallback), a Chinese-only
Project Gutenberg catalog (
lang=zh), Chinese Wikisource, Chinese Wikibooks,
and Standard Ebooks, then saves the chosen book (EPUB, or an HTML book for
the Wikimedia sources) into the archive shelf. Simplified Chinese queries are
also tried as traditional Chinese for the Chinese catalogs. Results stream
into the page one source at a time; slower sources keep searching while the
first results are already usable. The search store lives outside the Library
component, so opening a book or switching Harness pages does not abort the
stream; returning restores the query and results, and the Host keeps result
ids downloadable for 30 minutes. Only
public-domain / openly licensed catalogs are used; DRM and unauthorized book
sources are not supported. Choose which catalogs to query with Choose
sources; the selected source homepages are shown as small links. A custom
OPDS search URL can be added, but only entries that declare an
open-access EPUB acquisition link are accepted. Several custom OPDS sources
can be added with the + button. The built-in Chinese catalogs cover
traditional Chinese Gutenberg titles and Wikisource; other catalogs are
mostly English.
- Reader — parses the book into chapters, sanitizes HTML, and renders a
comfortable serif reading page with per-book progress. EPUB keeps its OPF
spine, headings, lists, tables, images and TOC; PDF/Text/Markdown/HTML/FB2/
DOCX are normalized into readable chapters.
- Ask while selecting — the floating selection bar contains a question
field to the left of 解释. Type a specific question and press Enter or
解释, or leave it blank for a direct explanation. The question is sent
together with the book, chapter, selection, and nearby context; the right
rail opens and streams the answer.
- Follow-ups — keep the whole Q&A thread in the panel and send the previous
turns to the model, so pronouns and earlier details stay in context. You can
stop the stream, copy the answer, or use quick asks (translate / example /
background).
- Per-book annotations — every completed explanation and its follow-ups are
saved on the Host under the archive directory. Opening a book opens the right
annotation rail with that book's saved records; click a record to reopen its
Q&A thread and continue asking. Records survive browser reloads and restarts.
- Paper mode — a separate paper library for English PDFs, with virtual
folders (create, drag papers in, rename), paragraph-level translation into a
JSON translation file, manual correction, retranslation, whole-paper
translation saved as a new Chinese paper, and a bilingual compare view.
Paper reading reuses the reader's AI explanation and full-book search; the
compare view has the same right-side AI rail, selection question bar,
follow-ups, saved annotation history and per-answer collapse as books, and
works for both the English source and the Chinese translation. Annotation
history and threads can delete a whole thread or an individual follow-up
question/answer pair, with an X in the record's top-right corner and a
second-click confirmation. The paper library supports right-click menus for
new folders, importing into a folder, and renaming; the new-folder control is
an icon on the right. Books can be hidden/unhidden or deleted (moved to
.epub-reader/trash) from the book-card context menu. Papers can be deleted
from their card context menu (two-step confirmation); a source paper also
removes its Chinese translation paper and moves the PDF/translation file to
the paper trash. Paper copies live in
.epub-reader/papers, separate from the book shelf. The compare toggle sits
in the paper reader header and can be hidden again; each
translation box is resizable from its bottom edge, auto-fits its text on
first open, remembers its height/collapsed state, and can be collapsed
individually or all at once. Translation text supports AI explanation.
- Zoom — Ctrl/Cmd + mouse wheel changes the reading font size in both books
and papers; the paper compare view also zooms its source/translation text.
- AI panels — explanations are expanded by default and can be collapsed
individually or with one “Collapse all” action.
- Find in book —
Ctrl/Cmd+F opens a full-book search across every
chapter, including PDF/HTML/DOCX books. Results show chapter, occurrence and
a text snippet; clicking one jumps to the chapter and highlights every match.
The reader toolbar shows the shortcut next to the search button. Simplified
Chinese queries also match traditional text (陈文龙 finds 陳文龍).
- Keyboard —
Ctrl/Cmd+Shift+E explains the current selection,
Alt+← / Alt+→ move between chapters, Esc closes search/rail.
Supported formats
| Format | Support |
|---|
.epub | Full spine, chapters, TOC, images, cover |
.pdf | Text-layer extraction, 8 pages per chapter; scanned PDFs need OCR first |
.txt / .text | Plain text, automatically chunked |
.md / .markdown | Headings, paragraphs, lists, quotes, code blocks |
.html / .htm / .xhtml | Sanitized HTML body |
.fb2 | FictionBook XML |
.docx | Word paragraphs and Heading 1–3 chapters |
.mobi / .azw3 / .azw | Convert to EPUB or PDF first (for example with Calibre) |
PDF extraction uses a vendored PDF.js runtime under vendor/pdfjs/; the package
has no npm runtime dependency for it.
Configuration
Edit the installed row's config in the profile patch (or the plugin's
cordis.patch.yml before installing):
- id: epub-reader
name: '@local/dsh-epub-reader'
config:
# Where outside books are copied and what the shelf scans by default.
# Empty = the first registered workspace (D:\BookLib here), then cwd.
archiveDir: D:\BookLib
# Extra folders to scan, if any. Absolute paths are allowed.
libraryDirs:
- D:\Books
# Optional; otherwise the Host's default model is used.
# Example: explainProvider: deepseek-account
# explainModel: deepseek-flash
explainProvider: deepseek-account
explainModel: deepseek-flash
# Off by default: the API answers only loopback browser requests.
allowRemote: false
The Host routes are mounted under /api/epub-reader. They accept only
same-origin browser requests, expose only .epub files found under a configured
shelf root, copy external files into the archive before parsing, and stream
explanations over SSE.
Notes
- Books are opened read-only; progress is stored in the browser's
localStorage.
- DRM-protected books are not supported.
- PDF support is text-first: a scanned/image-only PDF returns
PDF_NO_TEXT
instead of showing blank pages. Run OCR or convert it to a text PDF first.
- MOBI/AZW3 are not parsed directly; convert them to EPUB/PDF before importing.
- The plugin uses the official
llm Host service; no API key is read by the
plugin itself.
- Only the first 5 opened books are retained in memory; a re-open re-parses the
file.
- Annotation history is stored in
<archiveDir>/.epub-reader/annotations.json
and keyed by the EPUB content fingerprint, so the same book keeps its records
even at a different path. Copy that folder with the EPUB when moving a shelf
to another machine if the annotations should travel with it.
- Search results are cached for 30 minutes so a result can be downloaded; a
stale id returns
SEARCH_EXPIRED and the UI asks you to search again.
- Clearing the search field (the browser's X) or pressing Stop searching
aborts the in-flight request instead of leaving the spinner running.
- Custom OPDS sources must be lawful/open-access catalogs. The Host only accepts
EPUB acquisition links marked
open-access; it is not a generic downloader.
- Downloads are bounded to 120 MB and fetched only from allow-listed
gutenberg.org / standardebooks.org hosts. Large books can take a while.
- The search feature needs outbound network access from the DSH Host process.
License
Plugin code is released under the MIT License. The bundled PDF.js
runtime keeps its own Apache-2.0 license under vendor/pdfjs/LICENSE; bundled
fonts keep the licenses in vendor/pdfjs/standard_fonts/.
