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

指定 `image_id`（图片标识）的 `read_document`（文档读取工具）现在直接同步执行，不再提交高优先级队列、等待后台名额或先返回“处理中”。本次在 0.3.3 源码上修改，保留 `>=0.2.0-rc.2 <0.3.0-0` 的 DSH 兼容范围。

## 行为

1. 复制工具返回的 `images[].read_args`（图片读取参数）调用读取工具。
2. 已有相同文档命名空间、图片内容、模型、模式与提示词对应的成功结果时，直接复用会话缓存或持久缓存。
3. 缓存未命中时直接发起模型请求；解析成功后保存结果并返回。后续搜索与读取共用该结果。同图不同位置、相同模式可复用；文字转录与语义说明分别缓存。
4. 该图在后台排队或解析中时，取消它的后台任务，由同步请求接管；不等待后台任务完成，也不取消其他图片。取消已发出的模型请求不能保证服务端停止计费，但插件会阻止旧任务覆盖新结果；已经保存的成功切片可复用。
5. 相同图片、相同模式的多个同步读取合并为一个请求。某个调用者取消时，其他调用者继续等待；全部调用者取消则取消该同步任务。
6. 模型失败、超时、识别模式未开启时返回明确错误，成功缓存不写入失败结果。再次调用可重试。

指定图片的调用会等待模型完成，可能比原来的短响应更久；不会为了后台队列轮到它而等待。超长返回内容仍通过 `next_read_args`（续读参数）分页，这表示结果分页，不表示图片尚未解析。全篇的 `partial`（部分覆盖）与图片处理进度仍描述文档整体，可用 `images[].status`（图片状态）确认目标已完成。

## 参数与边界

无需新增参数或开关。`progressive.waitMs`（渐进短等待时间）仅继续用于搜索与块读取；`imageConcurrency`（后台图片并发数）仅约束后台队列。指定图片同步请求独立执行，因此后台和同步请求的总并发可以高于该值；同时读取不同图片会分别发起请求。

同步请求使用自己的文档转换总超时、模型单次请求超时和调用预算，不继承活动后台批次剩余的超时或调用额度；重试与大图切片仍计入预算。每次访问仍检查源文件权限和版本。模型变更、会话清理、插件卸载会取消相关任务。

`block_id`（块标识）读取仍按原来的有界批次与短等待方式处理。首次读取仍需提取 Word 正文和图片位置；本次不改变初始文档提取流程。同步行为适用于启用渐进处理的 Word 文档。

默认开启持久缓存，成功结果可跨重启复用；手动关闭持久缓存时仍有会话内缓存。持久缓存格式、Python 版本及依赖保持不变。

## 升级

完整替换源码，执行以下命令并重启 DSH：

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

已有 Python 环境无需重装。验证范围见 [验证记录](validation.md)。