paper-review

paper-review (DeepSeek Harness plugin)

All PDF conversion lives in the separate paper-parser package; this package contains the Harness host/client halves only.

A paper-review panel for the DeepSeek Harness: upload a PDF paper and read it as structured, selectable text beside the conversation, with figures and display equations rendered visually.

Features

• PDF → structured text (runs on the Harness host, via poppler):
  • two-column layout reconstruction (gutter detection + full-width line reassembly)
  • headings (size + all-caps normalization) and run-in heading splitting
  • tables (geometric column detection, wrapped-cell continuation)
  • sub/superscripts, dot-leader table of contents
  • scanned-PDF fallback to page images
• Figures and display equations rendered as images (pdftoppm crops + pdfimages raster extraction), with equation text kept as hidden spans so it stays searchable.
• Right-side reader panel: real third column when space allows (the harness details column), auto sidebar-collapse to make room, floating fallback for narrow windows, slim tab when collapsed.
• Ask dialog: select text → a small dialog appears → type a question ("explain this", "how does this relate to…") → the question plus the selection, its surrounding context, and the abstract are sent to the model.
• Projects: Create project materializes the paper (paper.pdf, paper.md, paper.html, figures, README with title/abstract) into a Paper workspace, opens a session there, and asks the agent to load the paper — each project keeps its own paper, so multiple papers coexist.

Requirements

• DeepSeek Harness (dsh) installed.
• poppler CLI tools on PATH: pdftotext, pdftoppm, pdfimages.
  • macOS: brew install poppler
  • Debian/Ubuntu: sudo apt-get install poppler-utils

Install

From npm (recommended)

dsh plugin --profile readPaper add @deepseek-ai/dsh-web-app paper-review
# then start the harness:
dsh --profile readPaper

dsh plugin installs the packages, then reconciles dsh.profile.bundles — packages that declare dsh.bundle join the profile's layer stack automatically.

Why @deepseek-ai/dsh-web-app is included: a profile created on a machine that has never used it before is seeded with only @deepseek-ai/dsh-base (the web surface bundle is not a default for unknown profile names). Adding @deepseek-ai/dsh-web-app explicitly is what gives the profile the browser GUI this plugin's panel renders into. On a machine where a readPaper profile already exists with the web app, plain dsh plugin --profile readPaper add paper-review is enough.

Prerequisites

• poppler CLI tools on PATH (pdftotext, pdftoppm, pdfimages) — see Requirements.
• pnpm for the dsh plugin command (it forwards to pnpm). If pnpm is missing: corepack enable pnpm or npm i -g pnpm.

Manual install (no npm)

• Copy this directory into ~/.dsh/profiles/readPaper/packages/paper-review.
• Make it resolvable (no pnpm needed):

  mkdir -p ~/.dsh/profiles/readPaper/node_modules
  ln -s ../packages/paper-review ~/.dsh/profiles/readPaper/node_modules/paper-review
  

• Add "paper-review" to dsh.profile.bundles in ~/.dsh/profiles/readPaper/package.json.
• dsh --profile readPaper

Usage

• Paper tab on the right edge opens the reader column.
• Load PDF… uploads (drag-and-drop onto the reader also works).
• Select text → the ask dialog appears → type a question, press Enter.
• Create project writes the paper into the Paper workspace and opens a session with the paper loaded as context.
• The converted documents are stored under ~/.dsh/paper-review/ and survive restarts.

How it works

• lib/index.js (host half): HTTP routes (/paper-review/…) for upload, conversion, documents, figures, projects, and per-session stores. The converter extracts word geometry with pdftotext -bbox, rebuilds columns and lines, classifies blocks (headings, tables, ToC, math), and rasterizes figure/equation regions with pdftoppm.
• lib/client.js (client half): the panel, tab, ask dialog, and project flow. Ships as a hand-written __ModuleLoader__ CJS bundle — no build step.
• cordis.patch.yml: the bundle patch that inserts the plugin row.

Development

• npm run check — syntax checks.
• npm run eval — downloads 10 recent astro-ph papers with their arXiv HTML versions, converts them, and scores text coverage against the references (PAPERS=2 npm run eval for a quick run). The corpus lands in eval/run/ (gitignored).

Limitations

• Conversion fidelity depends on the PDF's text layer (scanned papers render as page images).
• Display equations are images (their text is preserved as hidden spans); inline math is reconstructed as sub/superscript text.
• Content that exists only as PDF annotations (e.g., giant author lists in some journals) cannot be extracted.
• The plugin's HTTP routes follow the harness's localhost trust model.