# 当前实现补充：0.3.4

当前指定图片读取以 [upgrade-0.3.4.md](upgrade-0.3.4.md) 为准；其余 Word 路径以 [upgrade-0.3.0.md](upgrade-0.3.0.md) 和 [upgrade-0.3.1.md](upgrade-0.3.1.md) 为准；下方旧版本章节保留供历史参考。

| 模块 | 作用 |
| --- | --- |
| `src/progressive.ts` | Word 正文优先、图片有界批次、指定图片同步解析与共享缓存、续查、稳定块快照、会话取消 |
| `src/image-queue.ts` | 非抢占式优先级队列、全局图片并发上限、排队取消；块读取优先于后台搜索；指定图片走独立同步路径 |
| `src/durable.ts` | 正文/图片检查点、内容哈希、原子发布、恢复校验、磁盘清理 |
| `src/standalone-vision.ts` | 渐进路径的独立兼容端点，超时、重试、限额、禁止重定向 |
| `python/prepare_image.py` | 原始分辨率大图切片、像素和切片上限 |
| `python/markitdown_bridge.py` | 原有正文转换中记录延迟图片占位符、去重保存图片与位置清单 |
| `src/cache.ts` | 原有缓存与稀疏行索引，加位置记录顺序读取窗口 |

原始文档仍只通过 DSH 文件服务传入 Python；新增 Python 图片工作器仅打开插件自己提取的缓存图片。渐进任务和旧格式转换使用不同入口，避免修改原有 PDF/PowerPoint/Excel 的解析语义。

# 实现与设计对照

本文件描述已实现代码。`design-v1.md` 保留开发前设计作为历史依据，当前行为以本文件、README 和代码为准。

0.2.2 页面在远程接口挂载后，通过 `ctx.inject(["remote.documentReaderModels"], ...)` 创建消费作用域，并在该作用域注册配置页面。不能从仅声明 `remote` 的父作用域读取这个命名空间，也不能把尚未自注册的命名空间列为外层必需依赖。前端回归使用编译后的插件及真实依赖作用域。

| 设计事项 | 实现 |
|---|---|
| 两个简洁 Tool | read_document / search_document；cursor 为复制式续调分支，严格拒绝混传及未知字段 |
| 原生 DSH 接口 | named exports、defineTool 结构化输出、ctx.fs、ctx.subprocess、可选 approval、session/disposed 与 effect cleanup |
| Python 通信 | 已授权二进制输入、ready/release 握手、正文与 NDJSON 映射分离；长度、UTF-8、映射连续性和退出状态验证 |
| 位置映射 | PDF 单页投影后使用原生 PdfConverter；PPTX 注入随机开始/结束标记；XLSX 临时随机表名；XLS 捕获官方逐表输出；DOCX 转换段落/表记录；CSV 按解析记录 |
| PDF OCR 风险 | 不使用有页标题回退缺口的全文 OCR converter；原生文字/表格保持来自 PdfConverter，另复用官方图像提取 helper 和 OCR service；无正文时按真实页面内容触发整页回退 |
| 内容来源 | 原生、OCR 转录、图像说明、混合未知、合成元数据分别映射；说明/混合内容不进入默认搜索 |
| 视觉 API | 复用官方 LLMVisionOCRService；固定 endpoint/model；无自动路由；转录和说明用结构化 prompt 一次返回 |
| 缓存 | 会话隔离、源版本键、每次转换新 revision、内存/磁盘 ByteStore、TTL/LRU、并发合并、一个调用取消不影响其他等待者 |
| 超额审批 | 源大小与正文/映射大小明确后申请有限额度；批准后同一子进程继续传输；缓存读取不重复申请 |
| 超长行 | 码点完整的字节片段，后续工具参数由工具生成，有限预算下仍可读完 |
| 搜索范围 | 固定按页/slide/块/sheet/记录/image，ANY/ALL；只返回各词代表命中；大范围可暂停续查 |
| Windows 共享盘 | UNC/映射盘作为普通文件交给 DSH 和 OS；拒绝 URL/设备/ADS，Python 不重新打开共享盘路径 |

为了避免复制上游整个解析器，位置适配采用已验证的固定版本包装：PDF 按页传给官方转换器，Office 沿用官方正文转换。PPTX/XLSX 的临时修改只发生在已授权字节的内存/私有暂存副本，绝不写回源文档。随机标记不是可由原文固定字符串触发的控制语法。

PDF 的单页投影使原本可能因全局表格分支造成的页序混排不跨页传播；开启 OCR 不替换原生正文。但扫描图像与原生文字混杂时可能存在内容重复，不能声称完成复杂版面去重。PPT 原生矢量关系仍为未知覆盖。

CSV 为保持空记录及多行字段的原始记录号，使用标准 csv parser（记录解析器）与插件自有的最小表格转义函数（0.1.7 没有该官方辅助函数）。这是范围有限的定位适配，没有实现另一套 Office parser。私有上游 helper 受 `upstream-hashes.json` 约束，依赖变化时 doctor 拒绝启动。

所有源读取通过 ctx.fs。它与 subprocess 管理都不是恶意解析器的内核沙箱。本实现拒绝 Office 外部资源关系，禁用自动 converter/plugin discovery；更严格隔离仍应由部署层的进程沙箱提供。

本版本没有自动删除崩溃遗留目录，没有真正按需只转换一个请求页，也没有独立搜索索引服务。当前编译输出有 10 个 TypeScript 模块（包含类型与错误模块），一个 Python bridge；拆分用于保持缓存、搜索和协议职责可维护。

## 0.1.2 发布包兼容适配

当前 Python 基线是 PyPI 的 `markitdown==0.1.7` 与 `markitdown-ocr==0.1.0`。不再依赖 Git 提交安装；`upstream-hashes.json` 更新为对应发布包中的 Python 源文件摘要。

`stable_compat.py` 仅补足旧版图片入口和表格转义：Word 使用 Mammoth 的图片回调保持文档顺序；PowerPoint 在原生图片提取处插入随机标记，保留原生正文、表格与备注处理；Excel 使用原生表格输出并在唯一工作表标记范围内追加该表图片结果。上述处理发生于输入字节的内存副本，图片转录、生成说明与原文继续分别标记。0.1.2 的图像识别复用官方 `LLMVisionOCRService`，不会加载其他第三方转换插件或继承主会话模型。

安装脚本与离线包准备脚本共用 `requirements.txt`，移除 `--source-dir` 源码路径选项。旧专用环境运行安装脚本即可替换为指定发布版本。


## 0.2.0 DSH 视觉服务与配置界面

- `src/config.ts` 保留普通数据定义，另导出各组可变引用的插件配置；`src/index.ts` 对外公开该定义，通过可选设置服务声明自有页面，不调用旧设置注册接口。
- `src/client/` 使用原生插件行配置插槽，页面调用 DSH 现有模型目录和配置表单，前端不获取服务商凭据，也不自行实现配置文件写入接口。
- `src/vision.ts` 使用 DSH 模型和附件服务，在精确模型绑定后检查图片能力、发送图片并收集最终文本；失败终态、取消、输出截断、输出超限均不能当成完整识别成功。
- `src/python.ts` 在现有源文件/转换结果管道中增加图片请求帧。图片与响应正文使用定长二进制负载，元数据帧保持 64 KiB 上限；父子进程均检查长度和请求编号。
- `python/markitdown_bridge.py` 继续负责解析、定位与来源分类。DSH 模式将图像交给宿主；独立模式才使用旧 OpenAI 客户端和 markitdown-ocr 服务。
- 插件配置保存不重启转换进程，运行中的转换固定使用旧快照；新转换使用新快照。服务商注册变化增加缓存代际，跨代转换明确拒绝后续图片调用。
- 视觉请求是独立辅助请求，只提供图片与识别提示词，不携带主会话历史或工具列表。不会向主会话写入外部自定义事件，以免旧版本的持久化读取器拒绝恢复会话。
- 附件由 DSH 保存与投影，插件不删除共享附件；临时缓存和附件的生命周期不同，页面与使用说明明确区分。

前端发布产物是 DSH 的模块加载器格式，React 从宿主共享模块获取，不内置第二份 React。源码包保留构建脚本，不包含构建产物。
# 0.2.1 模型目录修复补充

`src/model-catalog.ts` 提供只读模型目录；`src/model-catalog-contract.ts` 定义两端共用的传输结构和方法描述。页面显式挂载该方法，通过 DSH 模型服务解析输入能力，替代不包含输入能力的通用会话目录。服务绑定与描述注册均归插件生命周期所有，不另建共享通信通道。回归测试使用真实 `llm-pi-ai`、宿主/浏览器网关和页面组件，见 `tests/model-catalog.test.ts` 与 `tests/client.test.ts`。