# 0.3.0：大型 Word 渐进搜索和持久检查点

## 升级

停止 DSH，在原插件目录完整替换本次源码，执行：

```powershell
pnpm install --frozen-lockfile
pnpm build
```

重启原配置档并刷新页面。安装路径未变且原配置档仍引用该目录时，无需重新添加插件。Python 依赖仍为 `markitdown==0.1.7`、`markitdown-ocr==0.1.0`，无需重建已正常工作的专用环境；必须同时更新本包的 `python`、`prompts`、`src` 和 `scripts` 目录。

渐进处理默认开启，仅对 DOCX 生效；PDF、PowerPoint、Excel 和独立图片保留原有转换路径。模型选择仍由用户手动指定，不继承主会话、不自动切换服务商。图片文字识别开关沿用原配置；关闭时明确报告图片未搜索。

## 行为变化

- Word 首次搜索先完成本地正文提取和图片清单，不等待图片模型返回。
- 默认 `scope="all"`（全部可搜索文字），正文结果先返回，随后原样复制 `next_search_args`（下一次搜索参数）分批补全图片。`scope="text"`（仅正文）完全不启动图片模型。
- 首次响应仍须读取、解析整份 Word；本版本没有把 Mammoth 改成流式解析器，不保证任意大文件首次秒级返回。
- 图片说明与 OCR（Optical Character Recognition，光学字符识别）分离。搜索只请求转录；仅开启图片说明时，搜索也不会调用说明模型。
- 每批默认 16 张不同图片，插件实例内图片工作并发默认 2，续查最多等待图片批次 1000 毫秒，再进行有界文字扫描。首次正文解析、磁盘读写时间不包含在该等待预算内。
- 一次响应结束后，已启动批次可继续完成；后续批次由续查驱动。当前调用取消会停止相关活动批次；会话销毁或插件停止也会终止任务。每张成功图片、每个成功切片立即写检查点。
- 重新搜索同一文件、换关键词或重启后，复用已成功的检查点。新搜索可以重试失败图片；同一条续查链不无限重试已失败图片。

## 搜索示例和完成语义

```json
{"file_path":"D:\\docs\\大型方案.docx","keywords":["故障切换"]}
```

明确只需要正文时：

```json
{"file_path":"D:\\docs\\大型方案.docx","keywords":["故障切换"],"scope":"text"}
```

续查仅复制返回的 `file_path` 和 `cursor`（续查令牌），不要再加关键词或范围。模型不需要自行填写图片编号、任务编号、分页偏移。

| 字段 | 含义 |
| --- | --- |
| `image_progress.total` | 文档内图片出现位置数量，重复图片仍计入各个位置 |
| `completed / failed / pending / skipped` | 已完成、已失败、待处理、因范围或开关跳过的图片位置数 |
| `running` | 当前是否有活动批次 |
| `scan_complete` | 本次选择的可搜索内容是否已扫描完，不代表没有提取缺口 |
| `extraction_complete` | 没有待处理、失败、跳过或已知/未知提取缺口时才为真；仍不保证模型识别准确率 |
| `partial / warnings / extraction_coverage` | 缺口、失败和来源范围提示，必须与零命中一起解释 |
| `result_id` | 当前文档版本内稳定的 Word 块标识 |
| `update=true` | 按相同 `result_id` 更新已有命中；不能累加成重复条目 |

正文结果先按文档顺序返回，图片补充再按图片所在块的顺序返回；整个跨响应结果流不是最终全文排序。调用方可以按块编号合并、更新和排序。多关键词的全部命中判断会把同一 Word 块内的原生文字与图片转录合并；不会把不同段落强行拼成同一块。

没有命中但 `pending>0` 时，只能说“已扫描部分未找到”。`failed>0` 或 `skipped>0` 时，不能说“全文不存在”。已生成的图片说明始终不参与关键词搜索。

## 稳定定位和按需读图

正文中的图片占位符固定不变，后续识别不会插入正文并改变后面的行号。`offset`（行偏移）仍是正文转换行号，Word 仍不提供准确物理页码。

- 搜索后复制片段中的 `read_args`（读取参数）。图片补充命中使用稳定块位置，不依赖会变化的全篇拼接行号。
- 正文读取返回 `images`（当前窗口内的图片位置）。复制其中的 `read_args` 按需生成/读取图片内容。
- 图片位置过多时，复制 `next_images_args`（下一页图片目录参数）继续列出图片；它与正文的 `next_read_args` 是两条独立分页链。
- 图片文字使用 `image_mode="transcription"`（文字转录）；语义解释使用 `description`（图片说明）。这些参数由工具结果生成；通常不必手写。
- 一个超长块的读取使用不可变快照续页，不会在中途因新图片结果到达而改变行位置。
- 图片补充命中的 `start_line / end_line` 是该块快照内的行号，必须使用关联 `read_args` 定位，不能当成正文全局行号。
- 正文 `eof=true`（正文已到末尾）不表示所有图片都已读取。

## 缓存和恢复

默认在当前操作系统用户的缓存目录启用持久检查点：

- Windows：`%LOCALAPPDATA%\dsh-document-reader\v3`
- Linux/macOS：`${XDG_CACHE_HOME:-$HOME/.cache}/dsh-document-reader/v3`

可在插件配置的“大型 Word 渐进处理与持久缓存”中指定绝对目录或关闭持久化。默认磁盘配额 1024 MiB（Mebibyte，二进制兆字节）、闲置保留期 7 天。检查点访问会刷新访问时间；过期检查点不再复用，实际磁盘回收在后续写入时执行。需要立即清除时，停止 DSH 后删除该目录。

持久目录保存正文、内嵌原图、位置映射及识别结果，不保存源文件路径或模型密钥。Windows 复用当前用户和 SYSTEM 的访问控制设置，其他系统使用私有目录。缓存是明文的本机派生数据，不是加密存储。操作系统账户和 DSH 原文件权限仍是访问边界。

源文件每次访问和结果返回前仍由 DSH 文件服务检查；命中持久缓存也不能绕过权限。文档结构按源版本缓存，图片结果按源目标、图片内容、模型、处理模式、提示词和切片配置分别缓存。修改正文但保留同一图片时可以复用识别；修改语义说明提示词不会使文字转录失效。

重启后从**新搜索**恢复，不复用旧进程的游标。正文修订标识在相同源版本和解析设置下保持稳定。进程中断时，仅已原子提交的成功检查点可恢复；正在进行的模型请求需要重做。损坏的正文检查点会被校验并重新提取。磁盘不足时给出警告，本次可继续，重启后的复用不再保证。

若 DSH 中保留相同服务商/模型名称但更换了实际后端，公共模型接口不能给出可跨重启验证的端点指纹，请修改 `progressive.cacheVersion`（图片缓存版本），或清除持久目录，避免沿用旧后端识别结果。运行中的服务商注册变更会中止旧代际任务。

原生 DSH 附件服务仍可能另行保留送入模型的图片；本插件缓存回收不删除共享附件。

## 大图与资源限制

- 默认以 1800 像素边长、96 像素重叠，无损输出 PNG 切片；没有把大图统一缩小来换速度。
- 一张图片默认最多 64 个切片、1 亿像素；不支持的格式或超限明确算作失败，不静默跳过。
- 切片按从上到下、从左到右拼接。重叠处可能重复，跨切片词句或完整图形拓扑不保证连续；出现切片时返回范围警告。
- 服务商或 DSH 附件适配器可能进一步规范化图片尺寸，实际识别质量仍需使用公司模型验收。
- 图片总调用预算沿用 `vision.maxCallsPerDocument`，在渐进 Word 中按每次活动批次计算（包含插件自身重试）；其余格式仍按整篇转换计算。预算用尽会标记失败，新搜索可利用已保存切片继续。
- `conversion.timeoutMs` 分别约束正文转换与每批图片处理；`conversion.maxConcurrent` 约束同时进行的正文解析。`progressive.imageConcurrency` 约束插件实例内图片工作数量。
- 识别文本落入临时磁盘文件，累计结果受 `conversion.maxResultMiB` 限制，不把整个文档所有转录文本常驻内存。切片临时文件在单张图片处理结束或失败时删除；活动切片工作项有独立的输出字节上限（单项为 `conversion.maxResultMiB / imageConcurrency`），不与持久配额混用。正文采用现有稀疏行索引，位置记录增加顺序读取窗口，避免每条记录重复读大块磁盘数据。本版本没有新增向量数据库或独立检索服务。

## 验证范围

见 [validation.md](validation.md)。测试使用真实 Word 文件、固定 Python 依赖、DSH 文件/子进程/附件/模型服务，以及确定性模型替身或本机模拟端点。未使用用户实际大文档、公司模型端点，也未声称已在 Windows 上完整联调。