dsh-document-reader

完成下面的 profile 配置后启动

dsh --profile document-reader-test

必须已有上述兼容范围内的 DSH，以及 `tools`、`fs`、`subprocess` 服务。插件的 npm peerDependencies 不会替你在 profile 中注册这些服务。若使用自己的最小 profile，也需注册工具运行时依赖的 `systemPrompt`。

更新源码后执行 `pnpm install --frozen-lockfile`、`pnpm build` 并重启 profile；Python 锁文件/源码基线变化时，重新运行安装脚本。

## 0.3.4：指定图片直接同步解析

复制 `images[].read_args` 指定图片后，已完成的结果直接从缓存返回；缓存未命中则立即发起独立模型请求，等待解析成功并写入缓存后返回。该请求不进入后台图片队列，不受 `progressive.waitMs` 的短等待限制。失败、取消或超时直接返回明确错误。

同一图片、同一模式的并发读取共用一个同步请求。后台该图已排队或正在解析时，取消该图的后台任务，由同步请求接管；其他图片继续处理。`imageConcurrency` 约束后台图片，同步请求额外执行。保持 0.3.3 的 DSH 兼容范围及 Python 依赖，升级后无需新增配置。详见 [0.3.4 同步读图说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.3.4.md)。下方 0.3.1 的插队行为为历史记录，以本节为准。

## 0.3.3：放宽 DSH 宿主兼容范围

全部 DSH 宿主依赖改为 `>=0.2.0-rc.2 <0.3.0-0`，接受 0.2.0-rc.2、后续 0.2 系列正式版与预发布版，拒绝更早版本及 0.3.0 的所有预发布版和正式版。Cordis 兼容 4.0.4 与当前 4.0.5-alpha.1 系列；构建依赖仍固定原有基线，不随兼容范围自动升级。Python、读取、搜索、配置及图片优先解析逻辑未变。

停止 DSH，替换源码，执行 `pnpm install --frozen-lockfile`、`pnpm build`，再重启 DSH 并刷新页面。确认插件管理页显示 `0.3.3`。已有 Python 环境无需重装。验证范围见 [0.3.3 兼容性说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.3.3.md)。

## 0.3.2：适配 DSH 0.2.1-alpha.1

同步升级 DSH 宿主依赖、Cordis、加载器和 Schemastery，并重新生成依赖锁文件。读取、搜索、大型 Word 渐进解析和指定图片优先解析功能保持原有行为；Python 发布包版本和持久缓存格式未变。无需版本豁免，已正常工作的 Python 环境无需重装。

停止 DSH，完整替换源码，执行 `pnpm install --frozen-lockfile`、`pnpm build`，再将新包添加到实际使用的配置档并重启 DSH、刷新页面。请确认插件管理页显示 `0.3.2`。详细步骤与验证范围见 [0.3.2 升级说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.3.2.md)。

## 0.3.1：指定图片优先解析

通过图片的 `read_args` 指定图片读取时，未开始的任务自动提升优先级；尚未进入搜索批次的图片可直接插队。目标图片完成即可返回，不等待整批搜索。已运行的图片继续执行，识别并发上限保持不变。同一图片、同一模式复用已有任务。详见 [0.3.1 升级说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.3.1.md)。

## 从 0.2.2 升级到 0.3.0：大型 Word 优化

完整替换源码，执行 `pnpm install --frozen-lockfile`、`pnpm build`，重启 DSH 并刷新页面。Python 依赖版本未变，无需重装已正常工作的环境。

Word 默认先返回正文搜索结果，通过工具返回的 `next_search_args` 分批补全图片文字；搜索不再生成图片语义说明。新增有限并发、重复图片去重、持久检查点、跨重启恢复、文档变更后的图片复用、大图无损切片、稳定定位与图片目录分页。默认完整搜索；明确只查正文时传 `scope: "text"`。

图片未识别完时，结果会显示进度和缺口，不得把零命中解释成全文不存在。已有图片模型开关和手动选择保持不变。持久缓存默认 1 GiB、7 天保留期，可在新配置分组修改或关闭。

完整行为、参数、缓存位置、恢复与限制见 **[0.3.0 使用和升级说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.3.0.md)**。以下历史说明与新版本有冲突时，以该文档为准。

## 从 0.2.0 / 0.2.1 升级到 0.2.2

本次修复配置页面找不到图片模型的问题。DSH 0.1.7-rc.2 的通用会话模型目录不返回 `inputModalities`（支持的输入类型），0.2.0 错误地据此过滤了全部模型。0.2.1 通过插件只读接口读取模型注册表的实际能力。

0.2.1 的页面还缺少新接口的作用域依赖声明，导致服务商列表请求被 DSH 拒绝。0.2.2 在接口注册后创建明确依赖该接口的页面作用域，修复这一回归。详细原因及验证范围见 [0.2.2 修复说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.2.2.md)。

停止 DSH，完整更新源码，在插件目录执行 `pnpm install --frozen-lockfile`、`pnpm build`，再重启 DSH 并刷新浏览器。已有插件安装路径不变时无需重新添加插件。无需更改 `llm-pi-ai` 中的 `input: [text, image]` 配置，也无需重装 Python。详见 [0.2.1 修复说明](https://github.com/kialexdl/dsh-document-reader/blob/505dbf1bac4840e597453168f023eda7189c3d1a/docs/upgrade-0.2.1.md)。

## 从 0.1.0 / 0.1.1 升级到 0.1.2

停止 DSH，将新源码覆盖原插件目录，在该目录执行：

```powershell
pnpm install --frozen-lockfile
pnpm build
py -3.12 .\scripts\setup_python.py
dsh plugin --profile web add .
dsh --profile web

web 是示例 profile（配置档），请替换成实际名称。本次必须重新运行 Python 安装脚本：它会将专用环境中的两个源码预发布包替换为指定发布版本，并校验安装结果，不修改全局 Python。若原配置使用自定义环境，给脚本加 --venv 'D:\你的路径\venv'，或把配置的 python.executable 改为脚本输出的路径。

文档读取/搜索参数保持不变。旧版缺少统一的图片扩展接口，新增 python/stable_compat.py 做小范围适配：沿用原生正文转换，将内嵌图片交给既有识别和来源标记流程。扫描图片仍由 markitdown-ocr 0.1.0 的官方识别服务处理。

0.1.1 历史升级说明

以下“无需重装 Python”仅适用于 0.1.0 → 0.1.1；升级到 0.1.2 请执行上一节。

本次修复 DSH 0.1.7-rc.2 启动时因 peerDependencies（宿主依赖版本约束）仍为 0.1.6-alpha.2 而跳过插件的问题。同步更新宿主包、Cordis 及其加载器、Schemastery 和依赖锁文件；文档转换逻辑与 Python 依赖未变。无需授予版本豁免。

1. 停止正在运行的 DSH，保留原有配置。
2. 将新源码覆盖原插件目录，必须包含 package.json、pnpm-lock.yaml 和 pnpm-workspace.yaml。
3. 在插件目录运行以下命令；web 是示例 profile（配置档），请替换为实际使用的名称。

pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add .
dsh --profile web

再次执行添加命令用于确保该配置档引用新的本地包；仅重启不一定会刷新原先安装的副本。此次无需重建已可用的 Python 专用环境。若仍提示 dsh-document-reader@0.1.0，说明该配置档仍指向旧包，请核对当前目录和安装目标。

详细修复与验证范围见 0.1.1 兼容性说明。

配置

推荐在 DSH 侧栏进入 插件 → 已安装 → dsh-document-reader → document-reader 行的“配置”。

1. 先在 设置 → 模型 配置好服务商、地址和凭据；对应模型的输入类型必须包含“图片”。
2. 在插件页面将视觉服务来源设为 使用 DSH 已配置模型，先选择服务商，再选择图片模型。
3. 按需打开“生成图片内容说明”和“识别图片文字”。二者共用所选模型，可同时开启。
4. 点击 保存配置。新文档转换使用新配置，不需要重启 DSH，也不需要重新构建插件。

服务地址、密钥、协议和请求头由 DSH 服务商适配器处理，本插件页面不复制或展示密钥。服务商没有图片模型时会显示空列表；已保存模型被删除后保留原选择并显示“当前不可用”，不会自动换模型。图片能力依赖 DSH 的声明，实际网关是否支持仍以调用结果为准。

模型服务与附件服务只在 DSH 图片识别模式下需要；关闭图片说明与文字识别时，纯文本读取不依赖这两项服务。无前端的命令行环境仍可修改配置文件。

附件保留： DSH 图片模式使用原生附件服务。待识别图片可能经过 DSH 的尺寸规范化后存入 DSH 附件目录；DSH 0.2.1-alpha.1 不自动清理这些附件，本插件的临时缓存清理也不会删除它们。模型输入沿用服务商自身的图片限制和投影策略，细小文字识别质量受这些限制影响。

页面的高级设置可以调整 Python、转换、读取、搜索、缓存和视觉限制。保存带有配置版本检查；如果另一个窗口已修改配置，需重新加载后再编辑。当前 DSH 的共享表单可能限制远程浏览器写入，页面会显示只读状态；请使用宿主允许写入的本地连接。

如需直接编辑该配置档的 cordis.patch.yml，以下为 DSH 模式示例。文件层按行覆盖整个配置对象，手工修改时保留自己的其他设置；页面保存通过 DSH 字段修改接口完成，无需手写整段覆盖。

- id: document-reader
  config:
    vision:
      source: dsh
      enabled: true
      provider: '你的DSH服务商标识'
      model: '该服务商中支持图片的模型标识'
    ocr:
      enabled: true

0.1.2 升级后，如果旧配置中已有 vision.baseURL，默认继续使用独立模式。要迁移，请在页面显式选择 DSH 模式，再选择服务商与模型。独立模式仍使用 baseURL 和 apiKeyEnv（密钥环境变量名），只接受兼容 OpenAI 的旧调用方式，不能自动回退到另一种模式。

非渐进路径中，变更模型、图片提示词、图片开关、解析设置或 Python 配置后，新的读取不复用旧转换结果。Word 渐进路径分别管理正文、文字转录和图片说明缓存，见 0.3.0 说明。旧续读参数会明确报告版本失效，需要重新读取或搜索；不会把两套识别结果拼在一起。已开始的转换保持启动时的插件配置快照；如果 DSH 服务商注册发生变化，后续图片请求会拒绝继续，避免自动切换服务。

升级步骤与验证边界见 0.2.0 变更说明。

开关	行为
两者关闭	只提取原生文字；发现未分析图片时报告缺失
仅 OCR	请求文字转录，参与默认搜索
仅 vision	请求图像说明，供读取但不参与默认搜索
两者开启	非渐进格式一次请求返回转录与说明；Word 搜索只做转录，说明按需读取

非渐进路径中，不符合预期 JSON 字段的图像响应保留为混合说明，标为 partial 并排除搜索；Word 渐进路径标记该图片识别失败，不作为原文搜索。识别转录仍可能出错，来源标记不代表识别正确率。

所有配置及默认值见 configuration.md。配置保存后新任务生效；同名模型实际后端变化时，请修改图片缓存版本或清除持久缓存。

工具使用

{"file_path":"D:\\docs\\方案.docx"}

传给 read_document。offset 默认 1，表示转换文本行号；limit 默认及上限 2000。Word 不提供准确排版页码。后续直接复制 next_read_args；搜索后的上下文读取直接复制每个片段的 read_args。

{"file_path":"D:\\docs\\方案.pdf","keywords":["故障切换"]}

传给 search_document。多个关键词默认任一命中；同一范围内全部命中：

{"file_path":"D:\\docs\\方案.pdf","keywords":["主备","切换"],"require_all":true}

固定行为：字面包含、忽略大小写、短语不拆词；C++、a.b 按字面处理。不支持正则、全词、排除词或布尔查询语言。PDF 按物理页，PPTX 按幻灯片，Word 按转换文本块，Excel 按工作表，CSV 按记录，图片按整张图像聚合。

Word 默认首次搜索只等待正文提取，图片文字通过续查分批补全；其他格式首次搜索仍可能需要完成转换/OCR。缓存命中后不再次调用模型。默认一次最多 20 个命中范围，响应最多 50 KiB。has_more=null 表示尚未确认后面是否还有命中；若有 next_search_args，直接复制继续。cursor 分支仅接受 file_path/cursor，不能同时填写关键词或 offset。

document_revision 标识一次转换快照。源文件变化、缓存过期后旧定位可能失效，重启后旧游标不可使用；渐进 Word 的相同正文版本可从持久缓存恢复，但应从新搜索开始；重新查找，不继续使用旧行号。超长单行返回片段及不透明游标，不静默丢字。

eof=true 只代表到达转换文本末尾；scan_complete=true 只代表已扫描完可搜索内容。partial/warnings 表示已知缺失；no_known_gaps 表示未观测到缺口，不能保证所有原始对象均已提取。零结果仅表示在已扫描的已提取文字中未找到。

权限、缓存与审批

源字节全部由 ctx.fs 读取；Python 不重新打开原始路径。UNC/映射共享盘作为普通文件接受，是否能读由 DSH provider 和操作系统决定；不提供独立账号、网络挂载或共享盘凭证。远程 URL、设备路径、ADS、非普通文件和需要外部资源加载的 Office 文件会拒绝。

活动任务和游标按会话隔离；渐进 Word 成功检查点可跨会话、跨重启复用，仍逐次检查源文件权限。默认小条目留内存，大条目使用随机临时文件；闲置 30 分钟清理，已知 partial 结果创建后 5 分钟过期。session dispose、插件卸载会取消任务并清理。异常断电/SIGKILL 无法保证即时删除；本版本不会自动删除无法确认归属的旧目录。

Windows 创建临时目录后使用附带 PowerShell 脚本设置并验证 ACL，仅当前用户与 SYSTEM 可访问；失败则停止，不降级为宽松权限。POSIX 使用私有随机目录和 0600 文件。解析器内存/压缩展开仍受第三方实现影响，缓存配额不是严格 RSS 上限。

超额文件通过 DSH 原生审批，仅 allowed-once 可继续。没有审批服务、被拒绝或取消时停止，不重复转换绕过审批。源输入与结果体积分别明确后，可能分别申请有限的临时额度；已缓存结果的翻页不重复审批。硬上限只能由用户修改配置。

自定义按工具名管控读取的部署需将 read_document 和 search_document 都加入现有策略；新工具不会自动继承名为 read 的规则。

构建、测试与打包

pnpm build
pnpm test
pnpm test:package

## 配置

推荐在 DSH 侧栏进入 **插件 → 已安装 → dsh-document-reader → document-reader 行的“配置”**。

1. 先在 **设置 → 模型** 配置好服务商、地址和凭据；对应模型的输入类型必须包含“图片”。
2. 在插件页面将视觉服务来源设为 **使用 DSH 已配置模型**，先选择服务商，再选择图片模型。
3. 按需打开“生成图片内容说明”和“识别图片文字”。二者共用所选模型，可同时开启。
4. 点击 **保存配置**。新文档转换使用新配置，不需要重启 DSH，也不需要重新构建插件。

服务地址、密钥、协议和请求头由 DSH 服务商适配器处理，本插件页面不复制或展示密钥。服务商没有图片模型时会显示空列表；已保存模型被删除后保留原选择并显示“当前不可用”，不会自动换模型。图片能力依赖 DSH 的声明，实际网关是否支持仍以调用结果为准。

模型服务与附件服务只在 DSH 图片识别模式下需要；关闭图片说明与文字识别时，纯文本读取不依赖这两项服务。无前端的命令行环境仍可修改配置文件。

**附件保留：** DSH 图片模式使用原生附件服务。待识别图片可能经过 DSH 的尺寸规范化后存入 DSH 附件目录；DSH 0.2.1-alpha.1 不自动清理这些附件，本插件的临时缓存清理也不会删除它们。模型输入沿用服务商自身的图片限制和投影策略，细小文字识别质量受这些限制影响。

页面的高级设置可以调整 Python、转换、读取、搜索、缓存和视觉限制。保存带有配置版本检查；如果另一个窗口已修改配置，需重新加载后再编辑。当前 DSH 的共享表单可能限制远程浏览器写入，页面会显示只读状态；请使用宿主允许写入的本地连接。

如需直接编辑该配置档的 `cordis.patch.yml`，以下为 DSH 模式示例。文件层按行覆盖整个配置对象，手工修改时保留自己的其他设置；页面保存通过 DSH 字段修改接口完成，无需手写整段覆盖。

```yaml
- id: document-reader
  config:
    vision:
      source: dsh
      enabled: true
      provider: '你的DSH服务商标识'
      model: '该服务商中支持图片的模型标识'
    ocr:
      enabled: true

0.1.2 升级后，如果旧配置中已有 vision.baseURL，默认继续使用独立模式。要迁移，请在页面显式选择 DSH 模式，再选择服务商与模型。独立模式仍使用 baseURL 和 apiKeyEnv（密钥环境变量名），只接受兼容 OpenAI 的旧调用方式，不能自动回退到另一种模式。

非渐进路径中，变更模型、图片提示词、图片开关、解析设置或 Python 配置后，新的读取不复用旧转换结果。Word 渐进路径分别管理正文、文字转录和图片说明缓存，见 0.3.0 说明。旧续读参数会明确报告版本失效，需要重新读取或搜索；不会把两套识别结果拼在一起。已开始的转换保持启动时的插件配置快照；如果 DSH 服务商注册发生变化，后续图片请求会拒绝继续，避免自动切换服务。

升级步骤与验证边界见 0.2.0 变更说明。

开关	行为
两者关闭	只提取原生文字；发现未分析图片时报告缺失
仅 OCR	请求文字转录，参与默认搜索
仅 vision	请求图像说明，供读取但不参与默认搜索
两者开启	非渐进格式一次请求返回转录与说明；Word 搜索只做转录，说明按需读取

非渐进路径中，不符合预期 JSON 字段的图像响应保留为混合说明，标为 partial 并排除搜索；Word 渐进路径标记该图片识别失败，不作为原文搜索。识别转录仍可能出错，来源标记不代表识别正确率。

所有配置及默认值见 configuration.md。配置保存后新任务生效；同名模型实际后端变化时，请修改图片缓存版本或清除持久缓存。

工具使用

{"file_path":"D:\\docs\\方案.docx"}

传给 read_document。offset 默认 1，表示转换文本行号；limit 默认及上限 2000。Word 不提供准确排版页码。后续直接复制 next_read_args；搜索后的上下文读取直接复制每个片段的 read_args。

{"file_path":"D:\\docs\\方案.pdf","keywords":["故障切换"]}

传给 search_document。多个关键词默认任一命中；同一范围内全部命中：

{"file_path":"D:\\docs\\方案.pdf","keywords":["主备","切换"],"require_all":true}

固定行为：字面包含、忽略大小写、短语不拆词；C++、a.b 按字面处理。不支持正则、全词、排除词或布尔查询语言。PDF 按物理页，PPTX 按幻灯片，Word 按转换文本块，Excel 按工作表，CSV 按记录，图片按整张图像聚合。

Word 默认首次搜索只等待正文提取，图片文字通过续查分批补全；其他格式首次搜索仍可能需要完成转换/OCR。缓存命中后不再次调用模型。默认一次最多 20 个命中范围，响应最多 50 KiB。has_more=null 表示尚未确认后面是否还有命中；若有 next_search_args，直接复制继续。cursor 分支仅接受 file_path/cursor，不能同时填写关键词或 offset。

document_revision 标识一次转换快照。源文件变化、缓存过期后旧定位可能失效，重启后旧游标不可使用；渐进 Word 的相同正文版本可从持久缓存恢复，但应从新搜索开始；重新查找，不继续使用旧行号。超长单行返回片段及不透明游标，不静默丢字。

eof=true 只代表到达转换文本末尾；scan_complete=true 只代表已扫描完可搜索内容。partial/warnings 表示已知缺失；no_known_gaps 表示未观测到缺口，不能保证所有原始对象均已提取。零结果仅表示在已扫描的已提取文字中未找到。