# 验证记录

## 0.3.4 / 2026-10-09：指定图片同步解析

后端与前端构建、包内容检查通过；43 项 Node 测试全部通过，0 失败、0 跳过。基于 0.3.3 源码与锁文件，保持 DSH 兼容范围不变。本轮使用 DSH 0.2.1-alpha.1、Node 24.19.0、Python 3.12 和指定发布版 MarkItDown；未重复运行 DSH 下界完整功能矩阵。Python 源码与依赖未修改，未重复执行独立 Python 测试；Node 集成测试实际执行 Python 的 Word 提取、切片准备、持久恢复与 DSH 调用链。

替换原优先级读取测试，并补充验证：

- 后台单一处理名额被门控模型阻塞时，指定批次外图片或已排队图片都立即发起独立请求；不释放后台名额也能完成并返回。
- 模型未完成时不会按 `waitMs` 提前返回待处理状态；完成后返回目标结果。
- 同图同步调用合并；会话缓存、重启后的持久缓存命中；后续搜索复用同步结果，无重复模型调用。
- 指定语义说明独立于后台文字转录；后台正在处理同图时被取消，由同步请求接管，不产生失败覆盖。
- 明确失败与重试、模型超时、权限拒绝、禁用识别模式、插件卸载；取消一个调用者不影响其他调用者，取消最后一个调用者不影响其他后台图片。
- 长块内容分页保留已解析的图片结果，不连带识别同块其他图片。
- 独立兼容端点同步解析与缓存复用，以及原有读取、搜索、配置页面、兼容范围与取消行为回归。

调度测试使用可控模型替身及真实格式文件；未调用用户真实模型，未在用户 Windows 环境验证。同步返回所需时间取决于图片处理与模型响应，不承诺固定时延。

## 0.3.1 / 2026-09-29：指定图片插队

构建通过，38 项 Node 测试已验证通过。全量运行中 37 项通过；新增分页用例的首次夹具没有形成分页，改成同一表格块中的长正文和两张内联图片后，该用例单独重跑通过。Python 源码与依赖未修改，本轮没有重复运行 19 项 Python 独立测试；Node 集成用例使用真实 Word、Python 提取和 DSH 服务链路。

本轮新增 7 项测试覆盖：

- 排队任务提优先级、高优先级按进入顺序处理、不打断运行中的图片。
- 排队取消、任务失败后名额恢复、并发上限。
- 批次外指定图片直接加入、批次内指定图片提升优先级；重复请求复用任务。
- 指定图片完成即返回，同时其他后台图片仍被测试门控阻塞。
- 按需语义说明先于后台文字转录执行，两种模式共用并发上限。
- 同块只请求目标图片、不连带解析其他图片；旧快照分页结束后能刷新已完成的目标结果。

调度顺序通过可控的模型替身验证；不代表真实模型时延或识别准确率。保持 0.3.0 的 DOCX 适用范围与部署环境边界。

## 0.3.0 / 2026-09-29：大型 Word 两阶段优化

构建通过。原有及渐进路径 30 项 Node 运行时测试全部通过，另 1 项持久缓存配额/过期/校验测试通过，共 31 项；Python 19 项测试全部通过，0 项跳过。依赖锁文件离线冻结安装通过。

验证环境：Linux、Node 24.19.0、Python 3.12、DSH 官方发布包 0.1.7-rc.2。Word/PDF/Office 文件为程序生成的真实格式文件；模型输出采用确定性替身或本机兼容端点。

覆盖内容：

- 原有读取、搜索、Unicode（统一字符编码）匹配、续读、权限、审批、取消及其他格式解析回归。
- Word 正文结果不等待受阻的图片模型；图片批次与有界并发、重复图片去重、最后图片命中。
- 原生正文与图片转录在同一表格块中共同满足多关键词条件。
- 语义说明仅按需调用；改变说明提示词不使转录失效，改变转录提示词重新识别。
- 搜索过程中正文位置不变；4 KiB 返回预算下的结果与全部图片目录续页。
- 重启复用成功图片结果；修改正文仍复用相同图片；损坏正文检查点重新解析。
- 持久命中不绕过文件权限；一个并发调用取消不取消其他正文等待者。
- 独立兼容端点与 DSH 模型/附件服务两条路径。
- 已失败图片可在新搜索中重试；图片未覆盖时不报告全文完整。
- 大图无损切片覆盖至边缘、重叠、像素/切片上限；持久磁盘配额、过期、内容校验与关闭持久化。
- 编译后的插件通过真实 DSH 工具服务返回新增 Word 搜索/读取字段，原生模型配置页面回归通过。

### 可复现性能样本

运行：`DOCUMENT_READER_TEST_PYTHON=/absolute/path/python node --import tsx scripts/benchmark-word.ts`。

同一合成 Word：5001 段正文、60 个图片位置、6 张不同图片。模型替身每次固定等待 100 毫秒，仍使用真实 DSH 附件和模型服务，不是公司模型性能测试。下列为一次顺序运行结果，不是统计基准或时延承诺。

| 路径 | 首次响应 | 全部结果 | 模型调用 |
| --- | ---: | ---: | ---: |
| 关闭渐进处理，旧路径 | 29.405 秒 | 29.503 秒 | 60 |
| 渐进处理，首次提取 | 8.390 秒 | 9.647 秒 | 6 |
| 渐进处理，重启后恢复 | 1.176 秒 | 1.321 秒 | 0 |

首次响应包含本地整篇 Word 提取时间；这次测试未使用用户实际大文档。Windows 安装、访问控制列表、用户实际模型服务与识别准确率仍需在目标环境验证。切片可能有重复与跨边界连续性限制，工具会返回提示。没有声称完成所有 Word 复杂对象的完整提取。

## 0.2.2 / 2026-09-28：修复页面作用域依赖遗漏

构建与 24 项 Node 测试通过，0 项跳过。新的页面回归测试加载编译后的宿主入口与前端模块，使用真实 Cordis 插件作用域，已在修复前复现空服务商/模型列表，修复后验证服务商与图片模型选择、保存、冲突处理、错误代码展示和卸载清理。

0.2.1 的页面测试使用根上下文直接渲染组件，绕过了实际插件的依赖访问检查；现在测试调用插件注册的页面。完整边界见 [0.2.2 修复说明](upgrade-0.2.2.md)。未重跑未改动的 Python 独立回归；Node 测试中的 Python 完整转换链路已重新通过。

## 0.2.1 / 2026-09-28：修复图片能力目录丢失

构建与 24 项 Node 测试通过，0 项跳过。使用真实 `llm-pi-ai` 与用户反馈配置复现 0.2.0 的空图片列表。新增验证覆盖实际宿主/浏览器网关及序列化边界，页面组件直接消费该调用结果；另验证部分失败、未知能力、取消、卸载与无凭据泄露。详见 [0.2.1 修复说明](upgrade-0.2.1.md)。

0.2.0 的 22 项测试虽然通过，但页面测试返回了真实会话目录没有的能力字段，未覆盖本次缺陷。这一测试替身已替换为真实服务链路。Python 文件与依赖本轮未修改，沿用上一轮 17 项通过记录，不将其记作本轮重新执行。

## 0.2.0 / 2026-09-28：原生配置页面与 DSH 视觉调用

保持 DSH 0.1.7-rc.2、markitdown 0.1.7 和 markitdown-ocr 0.1.0 基线。环境为 Linux、Node 24、Python 3.12。

| 检查 | 结果 |
|---|---|
| TypeScript 与前端模块构建 | 通过，产物符合 DSH 原生模块加载协议 |
| Node 测试 | 22 项通过，0 项跳过 |
| Python 格式与独立视觉调用回归 | 17 项通过 |
| 原生配置服务 | 配置写入、可变引用更新、无需重启、版本冲突与无效配置拒绝均通过 |
| 页面组件 | 服务商联动、图片能力筛选、失效选项、保存与冲突处理通过 |
| DSH 视觉调用 | 原生模型和附件服务配合确定性测试适配器，验证图片传递、响应汇总、能力复核、超时/取消与有限重试 |
| 完整转换链路 | Python 二进制通信、DSH 模型调用、缓存命中与模型变化失效通过 |

页面交互使用模拟浏览器文档环境；真实浏览器安装包下载失败，未完成真实浏览器视觉验收。未调用公司真实网关，也未在 Windows 上验收。原生附件服务持久化行为已在说明中明确；插件缓存清理不会删除宿主附件。详细使用方法和边界见 [0.2.0 升级说明](upgrade-0.2.0.md)。

## 0.1.2 / 2026-09-28：使用指定 Python 发布包

依赖基线：`markitdown==0.1.7`、`markitdown-ocr==0.1.0`，保持 DSH 0.1.7-rc.2。环境：Linux x86_64、Python 3.12.14、Node 24.19.0。

| 检查 | 结果 |
|---|---|
| 发布包安装 | 从软件包索引安装指定版本成功，依赖版本和源文件摘要检查通过 |
| 安装包来源核验 | 两个核心 wheel（Python 分发包）摘要与 PyPI 对应版本页一致 |
| 从原专用环境迁移 | 安装脚本成功卸载 0.1.8b3 / 0.1.1b2，替换为 0.1.7 / 0.1.0，依赖检查通过 |
| 离线包准备与全新离线安装 | `build_wheels.py` 生成包目录及摘要清单；`setup_python.py --offline` 在新环境安装及依赖检查通过 |
| Python 格式与适配测试 | 17 项全部通过 |
| 插件编译与测试 | 编译通过，13 项全部通过，0 项跳过 |
| 脚本语法 | Python 编译检查与 shell 语法检查通过 |
| 纯源码归档 | 包含适配模块、脚本、锁文件与测试；不含依赖和构建产物 |

Python 测试在原有格式覆盖上新增依赖检查、Word 重复图片原文顺序、PowerPoint 图片幻灯片归属、Excel 隐藏表图片归属、关闭识别时无网络调用等验证。图片识别使用本地模拟端点验证请求和结果处理，不表示真实模型识别准确率已验收。

核心发布包摘要：

- `markitdown-0.1.7-py3-none-any.whl`：`4eca912c87c6aa6897284a7f4bf6769a23bccf8544530f5d8b175fbe3797c916`
- `markitdown_ocr-0.1.0-py3-none-any.whl`：`c43f683627b177d52dd5d97d862a71c160d3f9f9b7b16df8d66cee502e780dde`

来源：[MarkItDown 0.1.7](https://pypi.org/project/markitdown/0.1.7/)、[markitdown-ocr 0.1.0](https://pypi.org/project/markitdown-ocr/0.1.0/)。按用户要求固定为这两个版本，不表示它们是目前最新发布版本。

Windows 原生运行、对应平台离线包、完整桌面/网页配置档及真实视觉端点仍需现场确认。本次不宣称对所有 Office 特殊对象或损坏文档完整支持。

---

## 0.1.1 / 2026-09-28：DSH 0.1.7-rc.2 兼容性修复

环境：Linux x86_64、Node 24.19.0、pnpm 11.25.0、Python 3.12.14。DSH 官方标签 `dsh-v0.1.7-rc.2`，提交 `477b4f420553e8a52c2fbccc464d7561b239c443`。

| 检查 | 本次结果 |
|---|---|
| 官方兼容性检查函数 | 旧包被拒绝，恰好五项不匹配；新包通过，无版本豁免；未验证的 0.1.8 仍被拒绝 |
| 锁文件安装 | `pnpm install` 成功；再次 `pnpm install --frozen-lockfile --offline` 成功 |
| `pnpm build` | 严格类型编译通过 |
| 未指定测试 Python 的 `pnpm test` | 12 项通过，文档转换集成测试明确跳过；真实加载与卸载测试执行通过 |
| 指定专用 Python 的 `pnpm test` | 13 项通过，0 项跳过 |
| Python 环境安装及依赖检查 | 使用原有固定提交、约束文件安装成功，版本与源码哈希检查通过 |
| 纯源码归档 | 归档完整性及文件清单校验通过，不包含构建产物和依赖目录 |

集成测试使用真实的 DSH 0.1.7-rc.2 工具服务、文件服务、子进程服务、会话和审批服务，加载编译后的插件。覆盖读取、搜索、共享转换缓存、权限拒绝、旧修订拒绝、取消、超额批准/拒绝、会话清理和卸载。调用方为确定性测试对象，不调用真实语言模型。

本次未修改 `src` 或 `python` 下的生产代码，也未重新执行全部 Python 格式转换单元测试。下方 2026-09-18 的格式测试保留为历史记录，不代表本次重复执行。Windows 现场安装、完整 DSH 桌面/网页配置档、真实视觉模型端点尚未验收。

---

## 0.1.0 历史验证记录

日期：2026-09-18。环境：Linux x86_64、Node 24.19.0、pnpm 11.19.0、Python 3.12.14。使用设计指定的 DSH npm 包与 MarkItDown 源码 commit。

## 已执行

| 检查 | 结果 |
|---|---|
| `pnpm install --frozen-lockfile --offline` | 通过（使用已下载的本机包缓存） |
| `pnpm build` | TypeScript strict 编译通过 |
| `DOCUMENT_READER_TEST_PYTHON=<venv-python> pnpm test` | 12 个测试通过，0 skipped；含真实 Loader YAML 组合测试 |
| `<venv-python> -m unittest discover -s tests -p 'test_*.py' -v` | 13 个测试通过 |
| `python3 -m py_compile` 与 `bash -n` | Python 源码/脚本及 shell 包装脚本语法检查通过 |
| `setup_python.py --source-dir <pinned-checkout> --venv <new-env>` | 新建独立 venv、安装依赖、doctor 通过 |
| `build_wheels.py --source-dir <pinned-checkout> --output <wheelhouse>` | 构建完整 Linux/Python 3.12 wheelhouse 和 SHA256 清单通过 |
| `setup_python.py --offline --wheelhouse <wheelhouse> --venv <another-new-env>` | 仅本地 wheels 安装、SHA256 检查、doctor 通过 |
| 纯源码归档 | ZIP CRC、文本源文件清单和禁止项检查；包含逐文件 SHA256 manifest |
| 解压后独立复建 | 在新目录执行 frozen-lockfile/offline 安装、build、12 个 Node 测试（0 skipped）全部通过；使用另一个离线安装的 Python 环境 |

Node 测试覆盖字面符号与忽略大小写、生成说明排除、同页 ALL、跨段短语隔离、跨读取块 NFC 定位、搜索分页顺序、中文/emoji 超长行续读、末尾空行、游标会话隔离、revision 失效、取消、partial 绝对 TTL 及总输出预算。

真实 Loader 组合测试通过 `cordis.yml` 加载编译后的插件，使用真实 DSH tools、FS-local、subprocess-local 和 approval 服务。验证搜索→复制参数读取、一次转换复用、缓存命中权限撤销、源变更旧 revision 拒绝、未知参数拒绝、并发中取消单个调用、超额 allowed-once/rejected 审计、翻页不重复转换/审批、session 清理及插件注销。测试调用方为确定性 Agent fixture，没有调用真实语言模型。

Python 测试按需生成真实 DOCX、PPTX、XLSX、XLS、CSV、PDF 和 PNG。覆盖标题/表格、PPT 备注与隐藏幻灯片、隐藏工作表、空白 PDF 物理页、原生正文、外部图片关系拒绝、容器配额、视觉结构化响应、混合响应/失败、内嵌图片和扫描页。

PDF 扫描回退既覆盖普通图片提取，也通过替换官方图像提取 helper 为“返回空列表”来验证异常分支：仍能渲染整页并调用 OCR，不被合成页标题误导。这个分支是模拟图片提取失败，不宣称所有实际损坏 PDF 均可恢复。

## 未验证与边界

- Windows 11、PowerShell ACL 运行、UNC/映射共享盘、用户现有 DSH Web profile 的现场安装。
- 真实视觉模型的图片理解准确率、中文复杂扫描件识别率、外部端点吞吐。
- 大量不同厂商 Office 文档、损坏/加密输入的全部组合、500 MiB 级压力测试。
- 原生 PPT 矢量拓扑、Word 精确排版页码、Excel 打印页码不属于 V1 承诺。
- 测试没有真实 LLM 参数生成质量统计；工具说明与严格校验已实现，实际模型可用性应在用户部署后观察。

验收结果不把“转换成功”“EOF”“无已知缺口”解释为原始文档所有对象已完整提取。