@dylanl1/dsh-plugin-pdf 0.1.2 → 0.1.3

package/NATIVE_V1.md

@@ -51,7 +51,9 @@ npm run check
 
 保存与授权仍在 Host。helper 通过进程隔离避免在 Host V8 中直接运行 PDFium；本版没有新增操作系统级沙箱。
 
-内置书签写入不经原生 helper：UI 与 `pdf_outline_edit` 共用目录操作领域和工作副本修订检查，撤销／重做及草稿恢复沿用原事务，最终由 pdf-lib 修改 `/Outlines`。重命名或移动保留既有目的地、外链和样式；显式修改目标页改为页面适合目的地。
+文字质量检测区分 PDFium 的换行断字标记（`U+0002` 且 `FPDFText_IsHyphen()` 为真）和真正的控制字符／Unicode 映射错误。合法断字不再触发警告或无必要的整页 OCR；真实映射错误仍报告。回归测试同时覆盖这两类字符，以及 Reader 与模型读取正常断字时均不启动 OCR。此修复不猜测缺失的符号字体映射，也不改变原生文字或定位偏移。
+
+内置书签写入不经原生 helper：UI 与 `pdf_bookmark_edit` 共用目录操作领域和工作副本修订检查，撤销／重做及草稿恢复沿用原事务，最终由 pdf-lib 修改 `/Outlines`。重命名或移动保留既有目的地、外链和样式；显式修改目标页改为页面适合目的地。
 
 ## 性能假设和测量
 

package/README.md

@@ -2,152 +2,92 @@
 
 English | [中文](README.zh.md)
 
-Read a PDF alongside your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) conversation. Ask a rough question, find the relevant passage, mark it in the document, and return to where you were reading.
+Read PDFs alongside your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) conversation. Let the model find relevant passages, annotate them, navigate to the source, and return to your previous reading position.
 
-I built this plugin because I often read papers and books in PDF form. The readers I tried were missing small but important conveniences—especially a way back after several jumps—while the ones with AI explanation and translation often required another subscription. This is the reader I wanted for my own DSH workspace.
+I read papers and books in PDF form. The readers I tried lacked multi-step back navigation, while AI explanation and translation often required another subscription. I built this plugin for my own DSH workspace.
 
-## What it does
+## Features
 
-- **Read and find.** Continuous scrolling, zoom and fit modes, page thumbnails, text selection, and text search.
-- **Navigate and return.** Jump through pages, links, bookmarks, or annotations, then choose an earlier position from multi-step back history.
-- **Annotate.** Add highlights, underlines, strikeouts, comments and draggable, resizable page notes; edit colors and comment threads.
-- **Edit bookmarks.** Add, rename, delete, reorder and nest the PDF's built-in bookmarks, then save them into the document.
-- **Fill forms.** Fill existing AcroForm controls manually or let the model inspect numbered controls and fill one page at a time.
-- **Save your work.** Undo/redo, recover drafts, save or save as, and detect source-file conflicts. User and model edits share the same draft; model-requested saves require approval.
-- **Translate selections.** Get pronunciation, meanings, parts of speech and examples for words; meanings and examples for phrases; direct translations for sentences.
-- **Ask in context.** Select several text passages or single-page image regions, attach a question to each, and send them together to the current conversation.
-- **Capture and recognize.** Copy or download a page region, run OCR on a page or region, and use the configured image-understanding backend.
-- **Let the model work with the PDF.** Read unread pages, find related passages, mark evidence, edit forms and bookmarks, and navigate an already visible Reader.
-- **Extend AI engines.** Register OCR, image-understanding, translation and embedding implementations through plugin APIs; available engines appear in PDF settings.
-- **Search by meaning (experimental).** Combine keyword matching with a local embedding model to find paraphrases and cross-language passages. Results remain original text references; incomplete indexing and image-only pages are reported explicitly. Embedding is off by default.
+- **Read and navigate**: continuous scrolling, zoom, thumbnails, text search, and multi-step back history with selectable destinations.
+- **Annotate and bookmark**: highlights, underlines, strikeouts, comments, draggable and resizable notes, and editing of the PDF's built-in bookmark tree.
+- **Translate and explain**: word meanings, pronunciation and examples; phrase and sentence translations; questions attached to multiple text passages or image regions, sent together to the current conversation.
+- **Agent control**: read, search, annotate, edit bookmarks and fill existing AcroForm fields in the same draft as the user.
+- **Save and recover**: undo/redo, draft recovery, save/save as, and source-file conflict detection.
+- **OCR and retrieval**: region capture, text recognition and experimental semantic search with your own embedding service. Indexes can include scanned-page text and image descriptions.
 
-## Agent tools
+![Agent highlights a passage and adds a comment](docs/screenshots/01-ai-edits-pdf.png)
 
-The bundle provides the following tools. Image/OCR availability depends on the current model and selected backend; navigation requires an already visible Reader. See the [tool contracts](docs/AI_READER_TOOLS.md) for inputs and limits.
+![Multi-step navigation and back history](docs/screenshots/04-multilevel-back-history.png)
 
-- `pdf_current` — List PDFs visible in the current conversation and their page hints.
-- `pdf_open` — Open a PDF in the background and obtain its shared document reference.
-- `pdf_close` — Release the model's document reference; Reader tabs keep their own references.
-- `pdf_status` — Inspect revisions, unsaved changes, conflicts and available capabilities.
-- `pdf_read_page` — Read a bounded text window from a specified page.
-- `pdf_search` — Search for exact text and return source references.
-- `pdf_find_related` — Find passages related to a question or concept and return source references.
-- `pdf_locate` — Locate a quoted passage in the original page text.
-- `pdf_context` — Read surrounding text for a position, quote or source reference.
-- `pdf_render_page` — Return a page image or derived text from the configured image-understanding backend.
-- `pdf_ocr_page` — Recognize text on a page using the selected OCR backend.
-- `pdf_image_context` — Retrieve previously recorded image or OCR evidence after revalidation.
-- `pdf_form_inspect_page` — Return a page image with numbered writable controls and their types/options.
-- `pdf_fill_form` — Fill one inspected page atomically in the shared draft.
-- `pdf_page_annotations` — List a page's annotations, comments and exact IDs.
-- `pdf_annotate` — Add a highlight, underline, strikeout or page note; text ranges can span pages.
-- `pdf_annotation_update` — Update text-mark colors or the text of a mark, note or comment reply.
-- `pdf_annotation_delete` — Delete an editable annotation or comment reply by ID.
-- `pdf_bookmarks` — Read the PDF's built-in bookmark tree and IDs.
-- `pdf_outline_edit` — Add, rename, delete, reorder or reparent built-in bookmarks.
-- `pdf_navigate` — Jump to a verified passage or page in a visible Reader, preserving back history.
-- `pdf_save` — Request user approval and save the current draft over its source PDF.
-- `ocr_recognize` — Transcribe a session-scoped image handle; provided by the bundled OCR plugin.
+## Install
 
-## Preview
+Validated with DSH `0.2.1-rc.5`; other supported versions are declared in [package.json](package.json).
 
-The agent can mark a passage and add a comment directly to the PDF draft:
+**GUI**: open **Plugins → Add plugin**, enter `@dylanl1/dsh-plugin-pdf`, install, then click **Enable now**.
 
-![Agent adds a highlight and comment to the PDF](docs/screenshots/01-ai-edits-pdf.png)
+**CLI**: replace `<profile>` with your profile:
 
-After several jumps, pick any earlier reading position from the back-history menu:
+```sh
+dsh plugin --profile <profile> add @dylanl1/dsh-plugin-pdf
+```
 
-![Multi-step PDF reading history](docs/screenshots/04-multilevel-back-history.png)
+For Desktop, install its bundled CLI through **Manage dsh Command…** in the app menu. Launch Desktop once, fully quit it, install with `--profile desktop`, then reopen it. A separately npm-installed CLI cannot manage Desktop's plugins.
 
-See also [bookmarks and outline](docs/screenshots/02-bookmarks-and-outline.png) and [notes and annotations](docs/screenshots/03-notes-and-annotations.png).
+Native components install automatically; no local compilation is needed. Supported platforms: macOS (Apple Silicon/Intel), Windows x64, and glibc Linux (x64/arm64).
 
-## Install
+Open a local PDF from DSH's file sidebar. AI features use your configured models or extension engines. Semantic retrieval requires a separately configured embedding service and is off by default. PDFs with an enabled active policy prepare their index in the background on open; OCR and image descriptions can be enabled independently and may call remote services and incur charges. See [SPEC](SPEC.md) for limits.
 
-Validated with DSH `0.2.1-rc.3`. Supported runtime versions are declared in [package.json](package.json); the test SDK and browser-test host are pinned to the validated release.
+Settings save automatically. Select engines in **PDF settings**; each PDF independently enables OCR and image-description indexing under **Search → Current PDF index**. Update indexes when needed to reuse cached results; disabling semantic search takes effect immediately.
 
-In DSH's plugin manager, add **`@dylanl1/dsh-plugin-pdf`**, then install and enable it. The main package automatically selects the prebuilt native package for your OS and CPU; no compiler or install-time build script is needed. Supported targets are `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64` and `win32-x64`; Linux builds require glibc.
-
-You can also use the CLI. Replace `<profile>` with the profile you actually use:
+## Agent tools
 
-```sh
-dsh plugin --profile <profile> add @dylanl1/dsh-plugin-pdf
-```
+- Documents: `pdf_current`, `pdf_open`, `pdf_close`, `pdf_info`, `pdf_status`.
+- Reading: `pdf_page_read`, `pdf_page_render`.
+- Search and evidence: `pdf_keyword_search`, `pdf_semantic_search`, `pdf_evidence_read`.
+- Annotations: `pdf_annotation_list`, `pdf_annotation_create`, `pdf_annotation_update`, `pdf_annotation_delete`.
+- Bookmarks: `pdf_bookmark_list`, `pdf_bookmark_edit`.
+- Forms: `pdf_form_inspect`, `pdf_form_fill`.
+- Navigation and saving: `pdf_page_jump`, `pdf_save`.
+- Images: `ocr_recognize`, `image_understand`.
 
-For Desktop, use its own CLI installed through **Manage dsh Command…** in the app menu. A separately installed npm `dsh` command does not manage the Desktop profile. Reopen or reload DSH after installing if the plugin is not activated immediately.
+`pdf_open` opens documents in the background; navigation requires a visible Reader. Agent edits go straight into the draft; overwriting the source still requires user approval. See the [tool documentation](docs/AI_READER_TOOLS.md) for parameters and examples.
 
-If you previously installed `@local/dsh-pdf`, save pending PDF changes and back up the old plugin storage before switching. Disable the old bundle before enabling the new package; do not run both together. Settings, drafts and reading positions from the old package need separate migration checks, even though the `pdf-*` patch row IDs remain unchanged.
+## Extend engines
 
-Open an accessible local PDF from DSH's file sidebar to start reading. The plugin uses your configured DSH models and credentials; it does not provide a free model. Image understanding and OCR depend on the selected model or a separately configured backend.
+OCR, image understanding, translation and embedding support third-party implementations. Build an independent DSH Host plugin, declare this package as a peer dependency, register your backend with the corresponding service through the public SDK, and install it in the same Host profile. It then appears in PDF settings.
 
-Pages with broken character mappings are repaired locally for selection and reading, without uploading or rewriting the PDF. This is an approximate OCR fallback, not automatic OCR for scanned documents.
+Start with [`http-engines`](examples/http-engines) in [`examples/`](examples/README.md), an independent plugin providing HTTP OCR and image-understanding backends. See [engine extensions](docs/ENGINE_EXTENSIONS.md) for API and lifecycle contracts.
 
 ## Architecture
 
 ```mermaid
 flowchart TB
-  subgraph Client["Client · Presentation"]
-    Reader["PDF Reader"]
-    Settings["PDF settings<br/>Live engine catalog and configuration"]
+  Reader["Client · PDF Reader"] <--> RPC
+  Model["DSH conversation model"] -- "Tool calls" --> Features
+  subgraph Host
+    RPC["Authenticated RPC"] --> Features["PDF domain capabilities"]
+    Features --> Copy["Shared working copy · Drafts and undo"]
+    Features --> Search["Retrieval and evidence"]
+    Features --> Engines["Extensible AI engines"]
+    Search --> Copy
+    Search --> Engines
+    Copy --> PDF["PDFium · pdf-lib"]
+    Copy --> Storage["Files and draft storage"]
   end
-  subgraph Host["Host · Authority"]
-    RPC["Authenticated RPC"]
-    Tools["Agent tools"]
-    Features["PDF and AI use cases"]
-    Copy["Shared working copy<br/>Drafts, revisions, undo, save"]
-    AI["Typed services<br/>OCR · Image understanding · Translation · Embedding"]
-    Retrieval["Text retrieval<br/>BM25 + embeddings · Rebuildable cache"]
-    Evidence["Existing evidence references<br/>Revalidate before marking or navigation"]
-    Catalog["Read-only engine catalog<br/>Change notifications"]
-    Config["Per-feature engine bindings<br/>Configuration and credential references"]
-    Backends["Default and contributor engines<br/>Same registration / Fiber-owned disposal"]
-    Native["PDF adapters<br/>pdf-lib · Native PDFium"]
-    Files["Files and draft storage"]
-    RPC --> Features
-    Tools --> Features
-    Features --> Copy
-    Features --> AI
-    Features --> Retrieval
-    Retrieval --> AI
-    Retrieval --> Evidence
-    Evidence --> Copy
-    Copy --> Native
-    Copy --> Files
-    AI --> Backends
-    AI --> Config
-    AI -. "Descriptor changes" .-> Catalog
-    Catalog --> RPC
-    RPC --> Config
-  end
-  Reader <--> RPC
-  Settings <--> RPC
-  Model["DSH conversation model"] <--> Tools
-  Backends --> Dependencies["DSH LLM · Local workers · Remote APIs"]
 ```
 
-The Client and agent tools share one Host-side working copy per resource session and canonical path. A background-opened PDF can later be adopted by the Reader with the same document ID, draft and undo history; changes synchronize in both directions. Closing a view releases its reference, not the draft. Idle resource eviction keeps the document identity and restores its working set on demand. Reading does not open a sidebar tab, and an agent-requested overwrite still requires approval. The native worker handles rendering and text extraction behind the Host boundary.
-
-Host plugins can register OCR, image-understanding, translation and embedding engines. The settings catalog updates on registration and removal; unloaded selections remain visible. Requests capture their engine/configuration, and unloading cancels that engine's active work. Each service retains its typed API; the catalog is not another execution registry. Only retrieval's explicit `auto` mode may report a lexical fallback. See [engine extensions](docs/ENGINE_EXTENSIONS.md) for contributor contracts. Automatic character-map repair remains a separate local-only path, never routed to a selected remote OCR engine.
-
-The `pdf_search` and `pdf_find_related` tools start with a document, query and options, then return `searchId` and `hasMore`. To continue, the model passes only that ID to the same tool; Host retains the query and progress. Related results are ranked only after the requested scope is fully indexed. See the [tool contracts](docs/AI_READER_TOOLS.md) for coverage and search-session lifetime rules.
-
-Bookmark edits use the shared outline domain and the existing pdf-lib save transaction. The agent can obtain exact `outlineId` values with `pdf_bookmarks`, then submit an atomic draft edit through `pdf_outline_edit`. New outline-edit interactions still need real Desktop and external-reader acceptance testing.
-
-See the [architecture](docs/ARCHITECTURE_V2.md), [AI reader tools](docs/AI_READER_TOOLS.md), and [specification](SPEC.md) for contracts and implementation status. Some advanced tool interactions still need real Desktop and model-based acceptance testing.
-
-Form inspection returns a numbered page image and the writable controls on that page, including their types, options and positions. Each small translucent F label sits inside its control. The calling model matches those controls to the printed content; inspection does not make an additional model or OCR request.
+The Reader and agent tools share Host business logic and a working copy within the same resource session; edits synchronize both ways. A native PDFium worker handles rendering and text extraction. See the [architecture](docs/ARCHITECTURE_V2.md).
 
 ## Development
 
-For a source checkout, run `npm ci`, `npm run native:build`, and `npm run build`, then install the directory with `dsh plugin --profile <profile> add .` using your actual profile. Source development stages the worker in `dist/native/`; installing the published package obtains a matching native dependency automatically. Run `npm run check` for type and Node tests, `npm run test:web` for browser interactions, and `npm run test:coverage:project` for project coverage.
-
-Semantic retrieval uses an **embedding model you configure**, independently of the current conversation model. In PDF settings, select an available semantic search engine and configure its service URL, model name and other required parameters. The built-in **Local Qwen3 embedding** engine is a local integration example; other models or services can be added through [engine extensions](docs/ENGINE_EXTENSIONS.md).
-
-See the [experiment setup and measurements](docs/RETRIEVAL_EXPERIMENT.md) for the MLX/Qwen3 startup example, dependencies and benchmark commands. Semantic retrieval is experimental and off by default; availability depends on the build or release you install. Images, charts and formula layout are not indexed by the text retriever.
-
-Ordinary AcroForm fields can be filled in the Reader or by the model. Inspection puts small IDs inside controls on a base-page image without widget appearances or annotations; current draft values are available through `includeValues:true` metadata, not the deliberately blank-looking image. Each fill atomically updates one page of the shared undoable draft using a single inspection ID and label/value entries; the Host restores the page. Inspect multiple pages together, then fill independent pages in separate calls. Shared-field and declared-dependency conflicts require reinspection. The model can supply explicit conditional and exclusive-choice checks; the Host validates those supplied rules and field types without inferring business meaning. Inspection needs a vision-capable model; overwriting the PDF still requires approval. PDF scripts and actions are not executed; signed PDFs remain read-only and signatures are not verified. XFA and encrypted PDFs are not supported. Text search does not automatically index scanned pages, and a background `pdf_open` tool call does not open a Reader tab. See [SPEC.md](SPEC.md) for the remaining limits.
+```sh
+npm ci
+npm run native:build
+npm run build
+```
 
-Draft storage still uses `format: 1`, but older binaries do not understand the new outline operations or ID-targeted form edits. Before downgrading, save or discard form/outline drafts and back up both the PDF and plugin storage. This is not a claim of compatibility with old binaries for new operation types.
+Checks and tests: `npm run check`, `npm run test:web`, `npm run test:coverage:project`. See also [retrieval configuration and benchmarks](docs/RETRIEVAL_EXPERIMENT.md) and [packaging and releases](docs/RELEASING.md).
 
 ## License
 
-[MIT](LICENSE). The main package includes `dist/THIRD_PARTY_NOTICES.md`; each platform native package includes its third-party licenses beside the native binaries.
+[MIT](LICENSE). Published packages include the third-party licenses for their native components and dependencies.

package/README.zh.md

@@ -2,152 +2,92 @@
 
 [English](README.md) | 中文
 
-在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的会话旁阅读 PDF：提出一个模糊的问题，找到相关原文、标记证据，需要时跳过去，再回到刚才的阅读位置。
-
-我经常用 PDF 阅读论文和书籍。用过的阅读器总缺少一些顺手但重要的功能，尤其是连续跳转后的多级回退；带 AI 解读和翻译的产品又常常需要额外订阅。于是我借助 DSH 做了这个符合自己阅读习惯的插件。
-
-## 能做什么
-
-- **阅读与查找。** 连续滚动、缩放与适应页面、页面缩略图、文字选择和文本搜索。
-- **跳转与回退。** 通过页码、链接、书签或标注定位，并从多级回退历史中选择之前的阅读位置。
-- **标注与便签。** 高亮、下划线、删除线、批注和可拖动、调整尺寸的页面便签，支持颜色修改与多条评论。
-- **编辑内置书签。** 新增、改名、删除、排序和调整父子层级，保存后写入 PDF。
-- **填写表单。** 手动填写已有 AcroForm 控件，或让模型检查带编号的控件并逐页填写。
-- **保存阅读成果。** 撤销／重做、草稿恢复、保存／另存为及源文件冲突检测。用户和模型共用一份草稿，模型请求保存时需要批准。
-- **选区翻译。** 单词提供音标、词性、释义与例句，短语提供多义项和例句，句子直接翻译。
-- **对着内容提问。** 收集多段文字或单页图像区域，分别附上问题，再一起发送给当前会话。
-- **截图与识别。** 复制或下载区域截图，对整页或区域进行 OCR，并使用配置的图像理解后端。
-- **让模型操作 PDF。** 补读未读页面、查找相关段落、标记证据、编辑表单与书签，并跳转已显示的阅读器。
-- **扩展 AI 引擎。** 通过插件接口注册 OCR、图像理解、翻译和 embedding 实现，在 PDF 设置中选择可用引擎。
-- **按含义寻找原文（实验功能）。** 结合关键词与本地 embedding，检索同义表达和跨语言段落。结果保留原文引用，索引尚未完成及图片页未覆盖都会明确报告；embedding 默认关闭。
-
-## 提供给模型的工具
-
-插件提供以下工具。图像与 OCR 的可用性取决于当前模型及所选后端，导航要求已有可见的阅读器。参数与限制详见[工具契约](docs/AI_READER_TOOLS.md)。
-
-- `pdf_current`：获取当前会话中可见的 PDF 及页码提示。
-- `pdf_open`：在后台打开 PDF，取得共享文档引用。
-- `pdf_close`：释放模型持有的文档引用，阅读器标签保留各自的引用。
-- `pdf_status`：查询修订、未保存修改、冲突及可用能力。
-- `pdf_read_page`：读取指定页面的一段文字。
-- `pdf_search`：搜索精确文本，返回原文引用。
-- `pdf_find_related`：查找与问题或概念相关的段落，返回原文引用。
-- `pdf_locate`：定位一段引文在原文中的范围。
-- `pdf_context`：读取指定位置、引文或引用的周边上下文。
-- `pdf_render_page`：获取页图，或由配置的图像理解后端返回文字结果。
-- `pdf_ocr_page`：使用所选 OCR 后端识别整页文字。
-- `pdf_image_context`：重新验证并取回之前记录的图像或 OCR 证据。
-- `pdf_form_inspect_page`：返回填写框内带编号的页图，以及控件类型与选项。
-- `pdf_fill_form`：依据检查结果，原子填写单页的共享草稿。
-- `pdf_page_annotations`：读取指定页的标注、评论及精确 ID。
-- `pdf_annotate`：新增高亮、下划线、删除线或便签，支持跨页原文范围。
-- `pdf_annotation_update`：修改文字标记的颜色，或标注、便签和评论回复的文本。
-- `pdf_annotation_delete`：按 ID 删除可编辑标注或评论回复。
-- `pdf_bookmarks`：读取 PDF 内置书签树及 ID。
-- `pdf_outline_edit`：新增、改名、删除、排序或调整内置书签层级。
-- `pdf_navigate`：在可见阅读器中跳转到已验证的段落或页面，并保留回退历史。
-- `pdf_save`：请求用户批准后，将当前草稿保存到原 PDF。
-- `ocr_recognize`：识别当前会话的图像句柄，由 bundle 内的 OCR 子插件提供。
-
-## 功能预览
-
-模型可以直接在 PDF 草稿中高亮原文并添加批注：
-
-![模型高亮 PDF 原文并添加批注](docs/screenshots/01-ai-edits-pdf.png)
-
-连续跳转后，可以从回退历史中直接选择之前的阅读位置：
-
-![PDF 多级回退历史](docs/screenshots/04-multilevel-back-history.png)
-
-另见[书签与目录](docs/screenshots/02-bookmarks-and-outline.png)、[便签与标注](docs/screenshots/03-notes-and-annotations.png)。
+在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 中一边对话，一边阅读 PDF。让模型查找相关原文、添加标注、跳转定位，再回到之前的阅读位置。
+
+我常用 PDF 读论文和书。常用阅读器缺少多级回退，带 AI 解读和翻译的产品又常需额外订阅，于是借助 DSH 写了这个插件。
+
+## 功能
+
+- **阅读与导航**：连续滚动、缩放、缩略图、文字搜索，以及可选择历史位置的多级回退。
+- **标注与书签**：高亮、下划线、删除线、批注、可拖动和调整尺寸的便签；编辑 PDF 内置书签及其层级。
+- **翻译与解释**：单词释义、音标和例句；短语与句子翻译；收集多段文字或图像区域，分别提问后发送给当前会话。
+- **模型操作**：读页、检索、标注、编辑书签和填写已有 AcroForm 表单，与用户共用草稿。
+- **保存与恢复**：撤销／重做、草稿恢复、保存／另存为和源文件冲突检测。
+- **OCR 与检索**：区域截图、文字识别，以及基于自配 embedding 模型的语义搜索（实验功能）。索引可加入扫描页文字和图像描述。
+
+![模型高亮原文并添加批注](docs/screenshots/01-ai-edits-pdf.png)
+
+![多级跳转与回退](docs/screenshots/04-multilevel-back-history.png)
 
 ## 安装
 
-已验证 DSH `0.2.1-rc.3`。支持的运行时版本在 [package.json](package.json) 中声明，测试 SDK 与浏览器测试宿主固定到已验证版本。
+已验证 DSH `0.2.1-rc.5`，其他支持版本见 [package.json](package.json)。
 
-在 DSH 插件管理器中添加 **`@dylanl1/dsh-plugin-pdf`**，安装并启用即可。主包会自动选择对应系统和 CPU 的预构建原生包，无需编译器或安装时构建脚本。支持 `darwin-arm64`、`darwin-x64`、`linux-arm64`、`linux-x64` 和 `win32-x64`；Linux 构建要求 glibc。
+**GUI**：打开 **插件 → 添加插件**，输入 `@dylanl1/dsh-plugin-pdf`，安装后点击 **立即启用**。
 
-也可以使用 CLI，将 `<profile>` 替换为你实际使用的 profile：
+**CLI**：将 `<profile>` 替换为所用 profile：
 
 ```sh
 dsh plugin --profile <profile> add @dylanl1/dsh-plugin-pdf
 ```
 
-Desktop 用户应通过应用菜单中的**管理 dsh 命令…**使用桌面版自带的 CLI。单独通过 npm 安装的 `dsh` 命令不能管理 Desktop profile；安装后若未立即激活，可重新打开或重载 DSH。
-
-如果此前安装过 `@local/dsh-pdf`，切换前先把未保存修改写入 PDF，并备份旧插件存储。启用新包前停用旧 bundle，不要同时启用两者。即使 `pdf-*` patch 行 ID 保持不变，旧包的设置、草稿和阅读位置仍需单独核对迁移情况。
+Desktop 用户需通过应用菜单的 **管理 dsh 命令…** 安装自带 CLI。先启动一次 Desktop，再完全退出，以 `--profile desktop` 安装后重新打开；单独通过 npm 安装的 CLI 不能管理桌面版插件。
 
-在 DSH 文件栏打开有权访问的本地 PDF，即可开始阅读。插件使用你在 DSH 中配置的模型和凭据，不提供免费模型；图像理解与 OCR 是否可用取决于所选模型或另行配置的后端。
+安装包自动匹配原生组件，无需本地编译。支持 macOS（Apple Silicon／Intel）、Windows x64 和 Linux glibc（x64／arm64）。
 
-字符映射异常的页面会在本地恢复可选择、可读取的文字层，不上传或改写 PDF。恢复结果是近似 OCR，不等于自动识别所有扫描文档。
+安装后从 DSH 文件栏打开本地 PDF。AI 功能使用已配置的模型或扩展引擎；语义检索需单独配置 embedding 服务，默认关闭。文档的生效策略启用后，打开时会后台建立索引；OCR 与图像描述可分别开启，可能调用远程服务并产生费用。更多限制见 [SPEC](SPEC.md)。
 
-## 架构
-
-```mermaid
-flowchart TB
-  subgraph Client["Client · 展示与交互"]
-    Reader["PDF 阅读器"]
-    Settings["PDF 设置<br/>动态引擎列表与配置"]
-  end
-  subgraph Host["Host · 业务与状态权威"]
-    RPC["鉴权 RPC"]
-    Tools["模型工具"]
-    Features["PDF 与 AI 功能用例"]
-    Copy["共享工作副本<br/>草稿、修订、撤销、保存"]
-    AI["类型化服务<br/>OCR · 图像理解 · 翻译 · Embedding"]
-    Retrieval["文字检索<br/>BM25 + 向量 · 可重建缓存"]
-    Evidence["既有证据引用<br/>标注与跳转前重新验证"]
-    Catalog["只读目录聚合<br/>引擎变化通知"]
-    Config["各功能的引擎绑定<br/>配置与凭据引用"]
-    Backends["默认与第三方引擎<br/>同一注册接口 · Fiber 生命周期"]
-    Native["PDF 适配层<br/>pdf-lib · 原生 PDFium"]
-    Files["文件与草稿存储"]
-    RPC --> Features
-    Tools --> Features
-    Features --> Copy
-    Features --> AI
-    Features --> Retrieval
-    Retrieval --> AI
-    Retrieval --> Evidence
-    Evidence --> Copy
-    Copy --> Native
-    Copy --> Files
-    AI --> Backends
-    AI --> Config
-    AI -. "描述与目录变化" .-> Catalog
-    Catalog --> RPC
-    RPC --> Config
-  end
-  Reader <--> RPC
-  Settings <--> RPC
-  Model["DSH 会话模型"] <--> Tools
-  Backends --> Dependencies["DSH LLM · 本地进程 · 远程 API"]
-```
+设置自动保存。引擎统一在 **PDF 设置**中选择；每份 PDF 在**搜索 → 当前 PDF 索引**中独立开启文字识别索引和视觉描述索引。由你决定何时更新，已有结果会尽量复用，关闭语义检索则立即生效。
 
-Client 与模型工具按资源会话和规范路径，共用 Host 侧的一份工作副本。后台打开的 PDF 随后可由阅读器接管，沿用同一文档 ID、草稿与撤销历史，修改双向同步。关闭视图只释放引用，不丢弃草稿；空闲回收保留文档身份，使用时按需恢复资源。读取不会自动打开侧栏标签，模型覆盖原 PDF 仍需单独批准。原生 worker 在 Host 边界之后负责渲染与文字提取。
+## 模型工具
 
-Host 插件可注册 OCR、图像理解、翻译和 embedding 引擎，设置列表会随注册与卸载自动更新，已卸载的选择仍会保留。任务固定使用启动时的实现与配置，卸载会取消该引擎的在途任务。各服务保留类型化接口，聚合目录不维护另一套执行注册表；只有检索的显式 `auto` 模式会报告词法回退。扩展契约见[引擎扩展](docs/ENGINE_EXTENSIONS.md)。字符映射自动修复仍走本地专用通道，不会因选择远程 OCR 而上传页面。
+- 文档：`pdf_current`、`pdf_open`、`pdf_close`、`pdf_info`、`pdf_status`。
+- 阅读：`pdf_page_read`、`pdf_page_render`。
+- 检索与证据：`pdf_keyword_search`、`pdf_semantic_search`、`pdf_evidence_read`。
+- 标注：`pdf_annotation_list`、`pdf_annotation_create`、`pdf_annotation_update`、`pdf_annotation_delete`。
+- 书签：`pdf_bookmark_list`、`pdf_bookmark_edit`。
+- 表单：`pdf_form_inspect`、`pdf_form_fill`。
+- 导航与保存：`pdf_page_jump`、`pdf_save`。
+- 图像：`ocr_recognize`、`image_understand`。
 
-`pdf_search` 和 `pdf_find_related` 首次接收文档、查询及选项，返回 `searchId` 和 `hasMore`；继续时只需向同一工具传回该 ID，查询和进度由 Host 保存。相关检索仅在所请求范围完成索引后返回排名。覆盖边界及搜索会话的有效期规则见[工具契约](docs/AI_READER_TOOLS.md)。
+`pdf_open` 只在后台打开文档；跳转需要阅读器已显示。模型编辑直接写入草稿，覆盖保存原文件仍需用户确认。参数和示例见[工具文档](docs/AI_READER_TOOLS.md)。
 
-书签编辑复用同一套目录领域规则和现有 pdf-lib 保存事务。模型可通过 `pdf_bookmarks` 获取精确的 `outlineId`，再用 `pdf_outline_edit` 提交一组原子的草稿修改。新增目录编辑的真实 Desktop 和外部阅读器验收仍待完成。
+## 扩展引擎
 
-接口与实现状态详见[架构文档](docs/ARCHITECTURE_V2.md)、[AI 阅读工具设计](docs/AI_READER_TOOLS.md)和[功能规格](SPEC.md)。部分高级工具交互仍需真实 Desktop 与模型场景验收。
+OCR、图像理解、翻译和 embedding 均支持第三方实现。将扩展写成独立的 DSH Host 插件，在 `peerDependencies` 中声明本包，通过公开 SDK 向对应服务注册后端，并安装到相同 Host profile，即可在 PDF 设置中选择。
 
-表单检查返回编号页图及本页可写控件的类型、选项和位置，透明底小编号放在每个控件内。调用模型根据页图理解印刷内容与控件的对应关系；检查工具不会另行调用模型或 OCR。
+参考 [`examples/`](examples/README.md) 中的 [`http-engines`](examples/http-engines)：一个提供 HTTP OCR 和图像理解后端的独立插件。接口与生命周期约定见[引擎扩展](docs/ENGINE_EXTENSIONS.md)。
 
-## 开发
+## 架构
 
-从源码运行时，依次执行 `npm ci`、`npm run native:build`、`npm run build`，再通过 `dsh plugin --profile <profile> add .` 安装本地目录，使用你实际的 profile。源码开发将 worker 暂存到 `dist/native/`；安装发布包时则自动取得匹配的原生依赖。类型与 Node 测试使用 `npm run check`，浏览器交互测试使用 `npm run test:web`，项目级覆盖率使用 `npm run test:coverage:project`。
+```mermaid
+flowchart TB
+  Reader["Client · PDF 阅读器"] <--> RPC
+  Model["DSH 会话模型"] -- "工具调用" --> Features
+  subgraph Host
+    RPC["鉴权 RPC"] --> Features["PDF 领域能力"]
+    Features --> Copy["共享工作副本 · 草稿与撤销"]
+    Features --> Search["检索与证据"]
+    Features --> Engines["可扩展 AI 引擎"]
+    Search --> Copy
+    Search --> Engines
+    Copy --> PDF["PDFium · pdf-lib"]
+    Copy --> Storage["文件与草稿存储"]
+  end
+```
 
-语义检索使用你自行配置的 **embedding 模型**，与当前会话模型独立。在 PDF 设置中选择可用的语义检索引擎，并按引擎要求配置服务地址、模型名称等参数。内置的 **Local Qwen3 embedding** 是本地接入示例；其他模型或服务可通过[引擎扩展](docs/ENGINE_EXTENSIONS.md)接入。
+阅读器与模型工具共用 Host 业务能力和同一资源会话内的工作副本，修改双向同步。原生 PDFium worker 负责渲染和文字提取。详见[架构文档](docs/ARCHITECTURE_V2.md)。
 
-MLX/Qwen3 的启动示例、所需依赖及基准测试命令见[实验配置及实测记录](docs/RETRIEVAL_EXPERIMENT.md)。语义检索属于实验功能，默认关闭；具体可用性以安装的构建或发布版本为准。图片、图表和公式版面不在文字索引的覆盖范围内。
+## 开发
 
-普通 AcroForm 字段可由用户或模型填写。检查工具将小编号放在填写框内，页图不绘制控件外观和批注；当前草稿值通过 `includeValues:true` 元数据读取，不能从空白图判断字段状态。填写只传单个检查 ID 和编号／值，Host 恢复页号，原子更新该页的共享可撤销草稿。可先批量检查多页，再分别填写独立页；共享字段或声明的依赖冲突时仍需重新检查。模型可显式提供条件和互斥选项检查；Host 校验这些传入规则及字段类型，不推断业务含义。检查页图要求视觉模型，模型覆盖保存仍需单独批准。不会执行 PDF 脚本或动作。签名 PDF 仍只读预览，且不验证签名真伪；XFA 与加密 PDF 不支持。文字搜索不会自动索引扫描页，Host 后台调用 `pdf_open` 也不会打开阅读器标签。其他边界见 [SPEC.md](SPEC.md)。
+```sh
+npm ci
+npm run native:build
+npm run build
+```
 
-草稿仍使用 `format: 1`，但旧二进制不理解新增的目录操作或按 ID 定位的表单操作。降级前须先保存或丢弃表单及目录草稿，并备份 PDF 与插件存储；不能把格式号未变理解为新操作可由旧二进制回读。
+检查与测试：`npm run check`、`npm run test:web`、`npm run test:coverage:project`。另见[语义检索配置与基准测试](docs/RETRIEVAL_EXPERIMENT.md)、[打包与发布](docs/RELEASING.md)。
 
 ## 许可证
 
-[MIT](LICENSE)。主包包含 `dist/THIRD_PARTY_NOTICES.md`，各平台原生包在二进制文件旁附带对应的第三方许可文本。
+[MIT](LICENSE)。发布包附带所用原生组件及依赖的第三方许可证。