文档划词问答 HaowenCang/dsh-document-selection-ask

dsh-document-selection-ask

DSH 客户端插件：在 DSH 文档预览中选中内容，把带出处（provenance）的引用块追加到当前会话草稿。

- 代码仓库：https://github.com/HaowenCang/dsh-document-selection-ask
- 许可证：本仓库自身代码为 MIT，见 LICENSE；随包第三方组件各自保留其许可证，权威清单为 THIRD_PARTY_NOTICES.md
- 项目状态：实施计划各阶段 Task 已完成，当前 package version 为 0.1.2，已在真实 DSH 0.1.5-rc.2 上验证。0.1.2 是 PDF 高 DPI 渲染与 TextLayer 对齐缺陷的 hotfix，完整根因与测量见仓库中的 docs/STATUS.md。该文件不随包分发，因此它不描述本包自身，而是各版本的确切分发状态与逐轮验证记录的权威来源。

项目用途

DSH 右侧的文件预览可以显示 TXT、Markdown、源码与配置文件、CSV、PDF、DOCX、PPTX 与 XLSX。该插件解决阅读过程中的一个具体问题：把「这一段」交给模型时，用户不需要先复制、另开文件，也不需要手工输入文件名、页码或工作表位置。插件工作在 DSH 客户端的文档预览面上，读取用户已经做出的选择，生成带出处的引用块，并写入当前会话的草稿输入框；发送与否由用户决定。

功能

一次完整的流程是：用户在受支持的预览中选中内容，插件把该选择捕获为格式无关的快照（文本、出处、几何信息）；浮层出现 询问 DeepSeek 按钮；按下后插件在当前草稿末尾追加一个引用块，其结构为出处行、引用内容，以及 请针对以上选中内容回答： 后缀；随后焦点回到输入框，用户补完问题并自行发送。

三条语义边界固定不变。已有草稿被保留，新引用块只做追加，第二次选择产生第二个引用块并位于其后。
插件从不自动发送消息，对输入框的唯一写入是 DSH 公开的草稿写入动作。DSH 内置的纯文本、Markdown 与代码预览不被替换，插件只读取它们产生的 DOM；PDF、DOCX、PPTX、XLSX 四类由插件注册自带渲染器。

浮层按钮只在选区所属会话与当前会话一致、且该会话的输入框已注册时出现，因此按钮不会把引用写入另一个会话的草稿。

支持格式

| 格式 | 渲染器 | 选择 | 出处 |
| TXT / 纯文本 | DSH 内置纯文本 | 真实 DOM selection | 文件；渲染器给出逐行行号时附源码行号 |
| Markdown | DSH 内置 Markdown | 真实 DOM selection | 文件（渲染结果不合成源行号） |
| 源码 / 配置 | DSH 内置代码 | 真实 DOM selection | 文件；行可证明时附源码行号 |
| CSV | DSH 内置纯文本 | 真实 DOM selection | 文件；行可证明时附源码行号 |
| PDF | pdfjs-dist@6.3.289（Canvas + TextLayer） | TextLayer 上的真实 selection | 文件 + 第 N–M 页 |
| DOCX | docx-preview@0.4.0 | 渲染后 HTML DOM 上的真实 selection | 文件 + 第 N–M 渲染页 |
| PPTX | @aiden0z/pptx-renderer@1.2.4 | HTML/SVG 文本上的真实 selection | 文件 + 第 N–M 张幻灯片 |
| XLSX | @extend-ai/react-xlsx@0.16.4 | 语义单元格区域，不是文本选择 | 文件 + <sheet>!<A1 区域> ，例如 Sheet1!A1:C3 |

完整矩阵——每种格式的渲染器版本、选择机制、出处来源属性、门禁与限制——见 docs/renderer-support.md。

安装

规范包名是 dsh-document-selection-ask，package.json 已移除 private 并声明 publishConfig.access: public。当前 package version 为 0.1.2，正式分发渠道有两条：

- npm registry：dsh-document-selection-ask
- GitHub Releases：对应版本的 tarball 附件

安装时请固定版本号，不要依赖 latest：本项目的发布验证针对确切版本，而 latest 会随新版本发布而移动。用 DSH 的 registry 安装路径装 0.1.2：

dsh plugin --profile <profile> add dsh-document-selection-ask@0.1.2

GitHub Release 的 tarball 与 npm registry 上的包应对应同一个正式 release commit；该 tarball 的 SHA-256 记录在同一次 GitHub Release 的 SHA256SUMS.txt 中。当前版本确切的发布状态、对应 commit 与校验值见 docs/STATUS.md。

从 tarball 安装

tarball 有两个来源：GitHub Release 的附件，或在本仓库检出上自行打包。自行打包的步骤是：

pnpm install
pnpm build
npm pack
pnpm verify:package ./dsh-document-selection-ask-0.1.2.tgz

npm pack 产出 dsh-document-selection-ask-0.1.2.tgz，文件名由 package.json 的 name 与 version 决定。pnpm verify:package 检查这个已产出 tarball 的实际内容，应当在安装之前通过。

npm pack 是本项目 0.1.2 artifact 的规范打包命令，该版本的 tarball SHA-256 由它复现，各版本的记录
见仓库的 docs/STATUS.md （该文件不随包分发）。当前验证环境中的 pnpm pack （11.7.0）会规范化随包的 package.json，因此产出语义等价但字节不同的 tarball，不用于复现该 SHA： Task 15UR 记录的两个 tarball 各有 92 个条目，其中 91 个逐字节相同，唯一差异在 package.json—— pnpm pack 把 scripts 移到对象末尾并去掉结尾换行符，两者的键集合与取值完全一致。该 tarball 同样通过 pnpm verify:package 的全部检查，因此本文只说明它不是该 SHA 的复现命令，不对它作为安装来源的可用性作否定判断。

随后在一个自有配置档中安装并启动：

dsh --profile dsa-dev --from-default-profile web
dsh plugin --profile dsa-dev add <tarball 的绝对路径>
dsh --profile dsa-dev --port 50120 --no-open

浏览器打开 http://127.0.0.1:<port>/?token=<token>，token 由启动输出给出。

dsh plugin --profile <name> <args...> 把参数原样转发给配置档目录中的 pnpm；安装成功后它按已安装状态自行维护配置档的 dsh.profile.bundles 列表（声明了 dsh.bundle 的包加入插件层），因此不需要手工编辑配置档清单。配置档不存在时该命令会先初始化；--from-default-profile web 用于显式地从随发行版本提供的 web 模板创建新配置档。

安装前需要明确一点：配置档必须是可丢弃的自有配置档，而不是日常使用的配置档。插件会成为该配置档的一个层，把它装进日常配置档会改变那个配置档的启动内容。

0.1.2 经过验证的是「在可丢弃配置档中安装并运行」，卸载流程不在已验证范围内。
在本次验证环境（DSH 0.1.5-rc.2，Windows）中，dsh plugin --profile <name> remove <package> 未能可靠完成 dsh.profile.bundles 的同步：6 次实测中 5 次在 1 秒内正常结束，并把包名同时从 dependencies 与 dsh.profile.bundles 中移除；另有 1 次在 dependencies 已更新之后一直没有返回，需要超时终止，该配置档的 dsh.profile.bundles 因此仍保留该包名，随后启动会以 cannot resolve profile bundle 失败，而重复执行同一条 remove 只会得到 ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS，无法修复。dsh --help 在 0.1.5-rc.2 中只提供 web 与 plugin 两个命令，没有其它公开的配置档生命周期命令。

因此本项目目前不把 remove 作为经过验证的卸载方法，也不建议依赖它。试用或验证某个版本时请使用一次性配置档：验证结束后删除该配置档目录即可，它完全位于 $DSH_HOME/profiles/<name> 之下，不需要改动 DSH 的内部清单。这是本次验证环境中的观测结果；本文不对 DSH 其它版本或其它平台的行为作断言。

npm pack 只在本地产出 tarball，不接触 registry，因此与本项目的 registry 发布互不影响；package.json 已移除 private 并声明 publishConfig，registry 侧的发布由独立的 release 流程执行。

源码检出（开发路径）

git clone https://github.com/HaowenCang/dsh-document-selection-ask.git
cd dsh-document-selection-ask
pnpm install
pnpm build

源码检出上的人工验收步骤（八种格式、草稿保全、渲染器切换、插件禁用与恢复、网络与 console 检查）见 docs/manual-acceptance.md。

使用

在右侧文件预览中打开受支持格式的文件，选中想要询问的内容——鼠标拖选与键盘选择都可以，选择必须落在同一份文档内。选择成立后浮层出现 询问 DeepSeek 按钮。按下按钮，引用块被追加到当前草稿：

已有问题

[来源：paper.pdf，第 3–4 页] 选中的内容选中的内容

请针对以上选中内容回答：

随后在输入框补完问题并自行发送。引用块只在预览属于当前会话时写入当前会话的草稿，插件不会切换会话，也不会提交消息。

安全与隐私

文档字节按不可信输入处理。插件不使用远程 Office/PDF 查看器，不上传文档，不依赖 CDN 资源，也不调用 LibreOffice、MS Office 或 COM；PDF 的 worker 与运行时资源、XLSX 的解析引擎都内嵌在客户端产物中。
DOCX、PPTX、XLSX 在进入渲染器之前一律先过共享的归档预检与解压校验。worker、object URL、观察器与查看器会话在卸载时释放，选中的内容与文档字节不写入日志。细节见 docs/security.md。

兼容性

- 已验证运行时：DSH 0.1.5-rc.2（本机 dsh --version 输出 0.1.5-rc.2），它同时是主要阻塞性真实应用运行时与主要编译契约基线。
- 契约依赖：@deepseek-ai/* 客户端契约是本项目的普通 devDependencies，精确固定到 0.1.5-rc.2；@deepseek-ai/cordis 属独立版本体系，保持 4.0.2。
- Node：^22.19.0 || >=24.0.0，由 package.json 的 engines 声明。
- 人工验证平台：Windows 11 与基于 Chromium 的 DSH Web UI。macOS、Linux 与移动端未验证，本文不对其作可用性声明。
- 未声明独立的 forward target：更新的 DSH 版本要同时通过契约门禁与真实应用验收，才谈得上支持。

支持矩阵、契约门禁的判定方式与真实应用证据见 docs/compatibility.md。

开发与验证

pnpm install
pnpm check:dsh-contracts # 契约门禁：版本固定、已安装版本、契约探针编译
pnpm typecheck
pnpm test # vitest：单元与 jsdom 客户端用例
pnpm build
pnpm verify # 只读静态门禁：源码与构建产物的启发式规则
pnpm test:browser # Playwright；需要运行中的 DSH 与 DSH_SMOKE_URL

- 每条命令的语义、判据，以及失败时先看哪条判据： docs/testing.md
- 人工验收步骤： docs/manual-acceptance.md
- 逐轮验证结果与历史记录： docs/STATUS.md

浏览器验收中有一部分依赖一个仅测试用的 companion driver（tests/browser/smoke-driver/）。它是一个独立、最小、private 的 DSH client plugin，用来让真实的内置预览 mount fixture；它不 import 被测插件，不进入主包的 files 发布集合，也不是主包的依赖，用户无需安装。

限制

- v1 不支持 DOC / PPT / XLS，不支持 OCR，不支持 Office 文档编辑，也不支持持久批注与高亮。这些能力没有降级形态。
- 引文文本的全局上限是 16,384 UTF-16 code units；XLSX 在此之上另有一次选择最多 200 cells 的上限。超过任一条上限都会被拒绝，并显示对应的用户可见错误，不会静默截断。
- 渲染保真度不作保证。DOCX 出处的「渲染页」是浏览器分页的结果，不是源文档自身的分页；PDF、DOCX、PPTX、XLSX 的版式由各自的第三方渲染器决定，人工验收程序也不以版式一致性为判据。
- 当前 package version 为 0.1.2。0.1.2 之前的 registry 版本存在 PDF 高 DPI 渲染与 TextLayer 对齐缺陷，建议使用 0.1.2 或更高版本。确切的分发状态见 docs/STATUS.md。

许可证与第三方声明

本仓库自身代码以 MIT 许可证发布，全文见 LICENSE。随包分发的第三方组件保留其各自许可证（例如 pdfjs-dist 为 Apache-2.0、docx-preview 为 Apache-2.0、@aiden0z/pptx-renderer 为 Apache-2.0、@zip.js/zip.js 为 BSD-3-Clause、@extend-ai/react-xlsx 为 MIT），完整清单与许可证文本见 THIRD_PARTY_NOTICES.md。