Preface¶

When reviewing code or documentation in DSH, the common workflow involves opening the preview on the right, identifying an issue, and pasting a text description of the location. The problem is that describing “where the awkward part is” itself consumes a lot of words, and after pasting, the connection to the original text is severed, forcing readers to guess.

Comparing existing approaches: Better Sidebar’s “Add to Conversation” inserts the filename and line number, suitable for whole paragraphs. To make specific local comments, one has to manually type the quoted text. dsh-file-annotations takes a different route—selecting text or an area directly in the preview, writing an annotation containing coordinates and a crop image, which appears above the input box and is sent along with the message.

What is this¶

A DSH client plugin maintained by DEVbyQIN, named dsh-file-annotations, current version 0.6.2, node requirement ^22.19.0 || >=24. It compiles “drafts during preview” into sendable citations, solving the issue where annotation positions and comments are either lost or degraded into large blocks of manually typed text.

It is worth noting that annotations are drafts during the preview period; they are preserved when the sidebar is collapsed, tabs are switched, or sessions are changed. After the preview is confirmed closed, the file’s JSON, localStorage, queued card, blue quote, and image preview cache are cleared, with “Undo” available within 10 seconds.

Core Features¶

Text Annotation¶

Text selection in optional text previews (TXT, JSON, Markdown, source code) and PDF with optional text layers support text annotation. Compatible with the CodeMirror editor used by Better Sidebar; text selected in the file content area can be annotated; search boxes and other standard input boxes do not trigger annotations.

After selecting text, the “Annotate” option in the text/code file and “Add to Conversation” in Better Sidebar appear in the same selection toolbar; the latter preserves the original file, line number, and insertion behavior. HTML opened by Better Sidebar allows text selection directly in the rendered webpage, or you can click “Select Element” followed by a paragraph, heading, or image to annotate the entire element. Cross-DOM fragment and multi-line text are matched as a full quote, saving the offset, context, and PDF page number. The webpage still uses the original sandbox, does not enable same-origin access, and does not provide OCR.

Region Annotation¶

The “Box Select” option is provided in the header of PDF, Image, and HTML previews. The drag layer only covers the visible content area, while tabs and exit buttons remain operable. After releasing the mouse, an input bar appears. After saving, a box and numbering are displayed on the region; pressing Esc or clicking the box select button again exits. The dashed box is retained while writing the comment, and canceling cleans it up.

PDF page numbers are read from the real page markers of the previewer; unrendered pages do not borrow the canvas from adjacent pages. PDFs and images are cropped to PNG; HTML saves the element selector, quoted text, and coordinates within the element, without providing a crop image. Old versions of HTML only stored viewport coordinates and cannot reliably infer the original element. Old records are retained in history, and new and old records are not automatically rewritten.

Pending List and History¶

After saving, the annotation appears in the pending list above the main input box, isolated by the current session. You can collapse the list, edit the comment, remove the annotation, or click the filename to open the original file. The input box contains a short “File Annotation” quote; when sending, it expands into the file path, quote or region coordinates, comment, and crop image path for this round of annotations. Saving an annotation does not automatically send a message.

Deleting the blue quote is equivalent to moving this batch of annotations out of the pending list; other message text and annotation history remain and will not be automatically added back after a refresh. To restore, click “Add to Pending” in the “Annotations” history in the file header. After the host confirms receipt, the annotation moves to history; if the submission fails, the annotation is retained and DSH restores the text draft, which can be modified and retried.

Storage¶

<workspace>/.dsh/annotations.json
<workspace>/.dsh/annotations/crops/<annotation id>.png

The storage format remains version 2, compatible with existing records. A record contains id, sessionId, path, rel, quote, comment, createdAt, as well as optional anchor, htmlAnchor, region, crop, sentAt, and detached. Here, sentAt indicates that the host has received this batch of messages, not that the AI has finished processing.

Host routes are all POST and located under /api/dsh-file-annotations/, covering resolve, read, write, crop, and crop-preview. Thumbnail reading only accepts the workspace and annotation id, not arbitrary file paths.

Installation and Enablement¶

For the desktop version, open “Plugins -> Add Plugin -> Install Existing Plugin” in DSH, enter dsh-file-annotations or github:DEVbyQIN/dsh-file-annotations, install and enable. Uninstalling is done in the application’s plugin manager. The npm package address is https://www.npmjs.com/package/dsh-file-annotations.

For the Web version, the installation command is:

dsh plugin --profile web add dsh-file-annotations@0.6.2
# or install the same version from GitHub
dsh plugin --profile web add 'github:DEVbyQIN/dsh-file-annotations#v0.6.2'

After installation, restart DSH. To uninstall:

dsh plugin --profile web remove dsh-file-annotations

Typical Usage¶

The following walks through the usage process as described in the plugin documentation.

1. Open the file preview on the right. After selecting text, click “Annotate” next to the selection, or in PDF, Image, or HTML previews, click “Box Select” and drag to define an area.
2. Input a comment and save. The annotation appears in the pending list above the main input box, isolated by the current session. A confirmation will pop up before closing the file preview that contains annotations; clicking “Cancel” or pressing Esc allows you to continue annotating; if there are no annotations, it closes directly.
3. In the list, verify the quote, comment, and region thumbnail; you can edit or remove them.
4. Supplement the general requirements in the native input box, then click DSH’s send button or press Enter. You can also send with only annotations and no extra text.
5. After the host confirms receipt, this batch of annotations moves to history; if it fails, the annotation is retained and the text draft is restored, allowing for modification and retry.

PDF defaults to reading and selection. Box select must be manually enabled. Writing an annotation pauses box select; after saving or canceling, you can continue to select the next area. Switching files or sessions exits box select. The dashed rectangle icon in the PDF preview is used to toggle box select; it turns blue when active. “Open PDF with default box select” can be set to Auto or Manual, and the setting is remembered and applied to future PDFs. The initial setting is Manual.

Regarding shortcuts, on macOS desktop the first load changes “Open File” to ⌘O and “Selection Annotate” to ⌘P; the Web version retains ⌘⇧E (Windows: Ctrl+Shift+E), and the Linux Web version does not bind a default shortcut. Inside the input bar, ⌘Enter / Ctrl+Enter saves the current annotation and sends all pending annotations for this session.

Applicable Scenarios and Notes¶

Suitable for scenarios where you need to ask, review, or discuss around specific local content of a file, especially areas in PDF, Image, or HTML previews that cannot be expressed by line numbers.

The following points should be clearly understood before installation:

• The plugin runs with the permissions of the current dsh process; the host interface exposes the ability to read/write the workspace and generate crop images. You should open the source code and license agreement for verification before installation; the repository license is MIT.
• It only covers the right-side file preview; there is no diff view, and no precise anchoring by code line numbers.
• File content changes do not trigger automatic migration, nor are old annotations judged as expired.
• The pending list depends on DSH’s conversation, sessions, and inputTriggers client services; changes to the host interface require re-verification of compatibility.
• Multiple independent browsers modifying the storage of the same workspace may still overwrite each other; currently, there is no collaborative editing protocol.

Community directory page and repository address: https://www.skillhub.cn/plugins/DEVbyQIN/dsh-file-annotations , https://github.com/DEVbyQIN/dsh-file-annotations