P8 routing baseline → P9-B FixedLayoutModel + lightweight-default-bundle direction

INSTALL.md

@@ -97,9 +97,9 @@ release/trans2former-2.0.0/RELEASE_MANIFEST.json
 ## 当前限制
 
 1. PDF 当前支持程序化二进制输出，不再依赖浏览器打印作为主要路径。
-2. DOCX、XLSX、EPUB、PDF text extraction、PPTX input 已完成 P3；DOCX/PDF output 已完成 P4/P6 基线；OFD 和本地 OCR 增强进入核心本地路线。
-3. 不需要安装 Office、LibreOffice、Pandoc、Playwright 或桌面壳程序。
-4. 不提供远程 OCR、远程转写、远程 AI 增强或云端文档处理；本地模型和 OFD 高保真渲染必须保持本地、可删除、可禁用、可回滚。
+2. DOCX、XLSX、EPUB、PDF text extraction、PPTX input 已完成 P3；DOCX/PDF output 已完成 P4/P6 基线；OFD 和本地 OCR 增强代码核心内置，OCR 模型资源不预装，首次启用 OCR 时本地下载到 model-cache。
+3. 不需要安装 Office、LibreOffice、Pandoc、Playwright 或桌面壳程序。默认安装包目标 30–80 MB，不内置 PaddleOCR-VL / Qwen-VL / MinerU 等 GB 级模型。
+4. 不提供远程 OCR、远程转写、远程 AI 增强或云端文档处理；OCR 模型与 OFD 高保真渲染必须保持本地执行、可删除、可禁用、可回滚；高级 OCR 资源（PaddleOCR-VL / MinerU 等）作为独立本地资源按需获取。
 
 ## 升级
 

README.md

@@ -17,7 +17,7 @@ Trans2Former 是一个专业级的桌面文档转换工具，支持 12 种输入
 - 📦 **零依赖** - 不需要安装 Office、LibreOffice 或 Pandoc
 - 🎨 **实时预览** - 转换前后实时预览文档
 - 📝 **结构化编辑** - 支持编辑转换后的文档结构
-- 🧩 **核心内置增强** - OFD、OCR、版面分析等能力进入核心本地路线
+- 🧩 **核心内置增强** - OFD、OCR、版面分析等能力代码核心内置；OCR 模型资源按需本地下载到 model-cache，不进入默认安装包
 - 🌍 **多语言** - 支持中英文、RTL 文本等
 - ⚡ **无大小限制** - 不设置人为文件大小上限
 
@@ -127,12 +127,14 @@ Trans2Former/
 
 ## 🧩 核心本地增强
 
-Trans2Former 不再提供插件安装模式，增强能力直接并入核心本地模块：
+Trans2Former 不再提供插件安装模式，增强能力代码直接并入核心本地模块；默认安装包目标 30–80 MB，不内置 GB 级模型，相关模型资源按需本地下载到 model-cache：
 
 - **OFD 支持** - 政务格式支持
-- **本地 OCR** - 扫描文档识别
+- **本地 OCR** - 扫描文档识别（首次启用时下载本地 OCR 模型到 model-cache，识别全程本机执行）
 - **版面分析** - 复杂布局识别
 - **表格恢复** - PDF 表格提取
+- **转换后检验** - 规则 diff + SSIM 视觉对比 + OCR 回读三层组合写入 QualityReport
+- **高级 OCR**（规划中）- PaddleOCR-VL / MinerU 等大模型作为独立本地资源按需获取
 
 这些能力不通过插件包分发；后续实现必须继续保持本地执行、无上传、可解释降级和资源预算约束。
 

docs/CONVERSION_PATHS.md

@@ -18,16 +18,17 @@ Trans2Former 区分两件事：
 | --- | --- | --- |
 | Markdown | Markdown、HTML、TXT、JSON、CSV、XML、DOCX、XLSX、PDF、EPUB、PPTX | 作为结构化轻量源，可导出文档、网页、表格和演示；文档到图片输出等待真实视觉渲染器。 |
 | HTML | Markdown、HTML、TXT、JSON、CSV、XML、DOCX、XLSX、PDF、EPUB、PPTX | 作为结构化轻量源，可转为常见发布和办公格式。 |
-| TXT | Markdown、HTML、TXT、JSON、DOCX、PDF、EPUB | 纯文本不直接导出表格或演示，避免误导。 |
+| TXT | Markdown、HTML、TXT、JSON、XML、DOCX、PDF、EPUB | 纯文本不直接导出表格或演示，XML 输出仅表达可读文本结构，避免误导为复杂标记恢复。 |
 | JSON | Markdown、HTML、TXT、JSON、CSV、XML、DOCX、XLSX、PDF、EPUB、PPTX | 仅当 JSON 可进入 DocumentModel 时适合多目标导出。 |
-| CSV | Markdown、CSV、XLSX、HTML、TXT、JSON、PDF | 表格源只提供表格、网页、文本和 PDF 路径。 |
-| XLSX | Markdown、CSV、XLSX、HTML、TXT、JSON、PDF | 表格源不提供 PPTX/DOCX 等不可靠跨类型输出。 |
-| DOC / DOCX | Markdown、HTML、TXT、JSON、DOCX、PDF | 文档源不直接转 PPTX，避免把正文文档错误包装成演示稿。 |
-| EPUB | Markdown、HTML、TXT、JSON、DOCX、PDF、EPUB | 电子书源保留文档和发布路径。 |
-| PDF | Markdown、HTML、TXT、JSON、DOCX、PDF | 当前主要是文本型 PDF 抽取，不提供表格/演示高保真输出。 |
-| PPTX | Markdown、HTML、TXT、JSON、PDF、PPTX | 演示源可抽取为文档；PPTX 写出仅为重新生成的基础演示，不是原稿保真写回。 |
+| XML | Markdown、HTML、TXT、JSON、XML、PDF | XML 源保留可读结构、原始结构化表达和基础发布路径，不自动推断办公专属模型。 |
+| CSV | Markdown、CSV、XLSX、HTML、TXT、JSON、XML、PDF | 表格源只提供表格、网页、文本、XML 和 PDF 路径。 |
+| XLSX | Markdown、CSV、XLSX、HTML、TXT、JSON、XML、PDF | 表格源不提供 PPTX/DOCX 等不可靠跨类型输出。 |
+| DOC / DOCX | Markdown、HTML、TXT、JSON、XML、DOCX、PDF | 文档源不直接转 PPTX，避免把正文文档错误包装成演示稿。 |
+| EPUB | Markdown、HTML、TXT、JSON、XML、DOCX、PDF、EPUB | 电子书源保留文档和发布路径。 |
+| PDF | Markdown、HTML、TXT、JSON、XML、DOCX、PDF | 当前主要是文本型 PDF 抽取，不提供表格/演示高保真输出。 |
+| PPTX | Markdown、HTML、TXT、JSON、XML、PDF、PPTX | 演示源可抽取为文档；PPTX 写出仅为重新生成的基础演示，不是原稿保真写回。 |
 | PNG | HTML、TXT、JSON、PDF | 图片源进入资产/预览路径，OCR 和图片重渲染进入核心本地增强路线。 |
-| OFD | Markdown、HTML、TXT、JSON、PDF | 核心包提供 L0 级本地解析路径，高保真继续并入核心本地增强。 |
+| OFD | Markdown、HTML、TXT、JSON、XML、PDF | 核心包提供 L0 级本地解析路径，高保真继续并入核心本地增强。 |
 
 ## 路径分级
 

docs/CONVERSION_ROUTING.md

@@ -125,6 +125,31 @@ P8-B 已引入真实 mapper 执行证据字段 `executedMappers` 并接入 `Sema
 - 新增格式时必须声明 reader/writer 的真实模型能力，并在新增推荐路径时同步产品矩阵与测试。
 - [scripts/conversion-capability-audit-test.js](../scripts/conversion-capability-audit-test.js) 用 Planner 输出做矩阵稳定性断言
 
+## Repair Cycle（S2 落地）
+
+S2 在 `ConverterRegistry.convert()` 内、writer 输出之后增加 Repair Cycle，让转换从「读 → 路由 → 写」扩展为「读 → 路由 → 写 → 复核 → 必要时修复 → 再复核 → 输出」。完整步骤：
+
+1. **propose**：`defaultRepairEngine.proposeActions(model, ctx)` 跑两个默认 validator —— `detectLossyRepairHints` 提取 `metadata.warnings[*].details.repairAction` 中的结构化建议；`detectRouteClassDegradation` 对 `routeClass ∈ {generated, restricted}` 路径建议更保守的输出。
+2. **apply**：对每个候选 action 校验 `confidence ≥ MIN_CONFIDENCE (0.6)` 后查表派发到 handler。`replaceTextRun` 改写 SemanticDoc block 字符串字段；`selectFallbackRoute` 默认仅写入 `autoRepair.recommendations`，需 `options.repair.applyFallback === true` 才真正切换 writer 并替换 output；其余 5 类动作目前注册为占位 reject。
+3. **reverify (model-level)**：cycle 用 `ensureDocumentAudit` 重算 `qualityReport`，要求 `warningCount` / `downgradeCount` 不超过 repair 之前。
+4. **reverify (round-trip)**：当 `from === to` 且格式属于 `md/html/json/csv/txt/xml` 自映射白名单时，cycle 把 writer 输出反读回模型并比对指纹；非白名单路径写 `roundTripDelta.skipped = "format-not-round-trip-safe"`，不阻塞输出。
+5. **finalDecision**：`verified`（无动作或复核通过）/ `degraded`（候选全被 reject）/ `failed-quality-gate`（apply 后复核失败）写入 `autoRepair.finalDecision` 和 `qualityReport.finalDecision`。
+
+`convert()` 返回结构变为 `{ ...writerOutput, quality: { qualityReport, modelReview, autoRepair, conversion } }` 的非破坏性 superset。`options.repair === false` 跳过整个 cycle 并返回原 writer payload，给 legacy 测试和未来需要纯净输出的调用方留口子。S2 阶段所有 validator/handler 仍是规则驱动，真实模型审核由 S3 接入。
+
+P9-A.3 之后，PNG 输入路径建议走 `convertContentAsync(payload)` —— 在 `prepareConversionModel` 与 `write` 之间插入 `runOCRStage(model, ctx)`，让 OCR 识别文本作为 paragraph blocks 写入 SemanticDoc；之后走同一 `_wrapWithRepairCycle` helper。Repair Engine 自动激活 `detectOCRLowConfidence` validator，把 `metadata.ocr.lines` 中 confidence < 0.55 的行转成 `replaceTextRun` 候选 action。同步 `convert()` 保留不变以保证现有调用方与 18+ 测试脚本零回归。
+
+P9-A.4 之后，扫描 PDF 输入路径在 `convertAsync` 的 PDF 分支自动检测（`isScannedPdf(content)`）并走 `runScannedPdfOCRStage(model, ctx)`：rasterizer 渲染每页 → enhanceWithOCR → 多页合并；文本 PDF 沿用 P8-B 既有文本提取路径，不动。
+
+P9-B 之后，扫描 PDF 路径的输出携带完整 FixedLayoutModel + SemanticDoc 双视图：`mergeOCRResultsToFixedLayout` 把每页 OCR 结果按 bbox.y → bbox.x 排序合并 + 携带 confidence，写入 `model.fixedLayout`；`fixedLayoutToSemantic` 派生 `model.blocks`；发 `MODEL_VISUAL_FIDELITY_LOST` + `MODEL_TEXT_ORDER_HEURISTIC` info warning。`defaultPdfPageRasterizer` 现在在浏览器/Tauri 自动 dynamic import `pdf-rasterizer-browser.js` + vendor pdfjs + canvas.toDataURL；Node 测试仍用 stub。
+
 ## 后续增强
 
-P8-B 的首批执行链已闭环。后续由 P9 补齐 `slide` / `fixedLayout` 路径的 writer 能力、公开 fixture 与视觉质量证据；在证据成立前不将规划边提升为实际 mapper 执行。
+P8-B 的首批执行链已闭环。后续按 2026-05-28 [lightweight-default-bundle-direction](superpowers/specs/2026-05-28-lightweight-default-bundle-direction.md) 决策推进 P9-A/B/C/D：
+
+- **P9-A OCR 基线**：PNG 与扫描 PDF 接入轻量 OCR（Tesseract.js / 轻量 PaddleOCR），OCR 模型资源按需下载到 model-cache，不进入默认安装包。
+- **P9-B OCR → FixedLayoutModel**：OCRResult → FixedLayoutModel → SemanticDoc，保留 bbox / confidence / page index / reading order，让 Repair Engine 的 `fixedLayoutToSemantic` 路径获得真实证据。
+- **P9-C 转换后检验**：规则 diff + SSIM 视觉对比 + OCR 回读三层组合统一写入 QualityReport，作为核心差异化能力提升。
+- **P9-D 高级 OCR**：PaddleOCR-VL / MinerU 等大模型作为独立本地资源按需下载，明确体积、运行内存、降级路径。
+
+在 P9-A 启动前必须先完成 **S3 按需下载与本地缓存治理**：定义 model-cache 目录结构、manifest、checksum、可清理入口、断网降级提示和首次启用下载提示流程。`slide` / `fixedLayout` 路径的 writer 能力和视觉质量证据在 P9-B/C 推进过程中补齐；在证据成立前不将规划边提升为实际 mapper 执行。

docs/DESKTOP_APP_ARCHITECTURE.md

@@ -14,8 +14,12 @@ Tauri desktop shell
 + TypeScript conversion core
 + Web Worker / WASM
 + core local enhancement modules
++ on-demand local OCR/layout model resources (downloaded to model-cache on first enable)
++ Repair Engine
 ```
 
+默认安装包目标体积 30–80 MB；默认包不含 PaddleOCR-VL / Qwen-VL / MinerU 等 GB 级模型。OCR / 版面 / 表格能力的代码核心内置，模型资源仅在用户首次启用对应能力时下载到本地 model-cache，可清理、可禁用，处理阶段不联网、不上传任何文档内容。
+
 当前浏览器 Web 应用继续作为 GUI 和转换核心验证底座。桌面化不是推翻现有实现，而是把现有 Web-GUI 放入 Tauri 壳，并补齐文件系统、版本历史和桌面权限隔离。
 
 ## 选择判断
@@ -28,7 +32,7 @@ Tauri + Web-GUI 是当前最合理的桌面路线。
 - 高体验上限：Web-GUI 更适合做现代工作台、分栏编辑、实时预览、虚拟滚动、质量报告和 diff。
 - 本地安全：Tauri 的能力边界更适合做最小文件系统权限和显式目录授权。
 - 技术连续性：当前浏览器转换核心、Worker、DocumentModel、前端工作台和测试可以继续复用。
-- 核心模块友好：重格式、高保真渲染器、本地 OCR/OFD 可以本地按需加载，不必进入首屏启动路径。
+- 核心模块友好：重格式、高保真渲染器、本地 OCR/OFD、文档图像文字专用模型和 Repair Engine 代码核心内置，模型资源按需本地下载到 model-cache，不必进入首屏启动路径。
 
 主要风险：
 
@@ -49,7 +53,7 @@ Tauri + Web-GUI 是当前最合理的桌面路线。
 - 可恢复：转换失败、重能力失败、预览失败时，用户的输入、编辑和输出状态不丢。
 - 信息密度合理：主界面服务操作，不堆说明文案；复杂解释放入 warnings、quality report 和详情面板。
 - 安全可见：local-only、no-upload、核心本地处理、历史保存状态在关键位置可见。
-- 资源可控：默认核心轻，重格式和模型本地按需加载，可禁用、清理、回滚。
+- 资源可控：默认安装包轻量（目标 30–80 MB），重格式与 OCR 等增强模块代码核心内置；OCR 模型资源不进入默认安装包，首次启用时下载到本地 model-cache，可禁用、可清理、可回滚。
 - 数据可控：版本历史默认只在会话内；持久保存必须 opt-in，并提供清除入口。
 
 ## GUI 边界
@@ -86,6 +90,7 @@ Tauri + Web-GUI 是当前最合理的桌面路线。
 | QualityReportPanel | 结构保真、视觉保真、资源保真、可读性和 chunked 等价 |
 | VersionHistory | session undo/redo、checkpoint、diff、持久历史 opt-in |
 | SecurityCenter | local-only 状态、权限、缓存、历史和清除入口 |
+| Repair Engine | 执行已注册的结构化修复动作，修复后重新写出并复核，不让用户承担质量修复 |
 
 ## 安全模式
 
@@ -126,7 +131,9 @@ Tauri + Web-GUI 是当前最合理的桌面路线。
 | 50MB+ 文件 | Worker + 渐进预览 |
 | 100MB+ 文件 | 分块 / 降级预览 |
 | 重格式 | 核心本地按需加载 |
-| 本地模型 | 手动安装、手动启用 |
+| 默认安装包 | 30–80 MB，不打包 GB 级模型 |
+| OCR 模型 | 不进入默认安装包；首次启用时本地下载到 model-cache，可清理、可禁用 |
+| 高级 OCR（PaddleOCR-VL / MinerU 等） | 独立本地资源，按需获取，明确体积与硬件要求 |
 
 ## 当前实现
 

docs/DESKTOP_RELEASE_PLAN.md

@@ -48,7 +48,9 @@ Trans2Former_<version>_checksums.sha256
 - 应用可启动到主窗口。
 - Markdown -> HTML、TXT -> PDF、CSV -> XLSX 基础路径可转换并下载。
 - OFD、PNG/image、PDF、OOXML 等核心本地能力在无插件安装入口的情况下可见。
-- 文档处理阶段不发起网络请求。
+- 默认安装包体积控制在 30–80 MB；不内置 PaddleOCR-VL / Qwen-VL / MinerU 等 GB 级模型。
+- OCR 启用后必须可触发首次本地下载，并展示 manifest、checksum、缓存路径、分项体积报告、可清理入口和断网降级提示。
+- 文档处理阶段不发起网络请求；OCR 模型下载是显式动作，仅在用户首次启用 OCR 时联网，下载完成后所有识别在本机执行。
 - 关闭再打开后不会自动恢复用户文档，除非用户显式开启历史持久化。
 
 ## 文件关联和权限
@@ -71,7 +73,11 @@ Trans2Former_<version>_checksums.sha256
 - 新增格式转换能力优先并入核心本地模块，必要时通过本地 worker、vendor 或 WASM 按需加载。
 - Release 包不得包含 `plugin-patches` 或 `.t2f-plugin.json`。
 - OFD、OCR、版面分析、表格恢复等能力必须声明资源预算、fallback 和兼容说明。
-- 本地模型资源必须手动安装、可删除、可禁用，不得上传数据。
+- OCR 模型资源不进入默认安装包；首次启用时本地下载到 model-cache，必须提供 manifest、checksum、缓存路径、可清理入口、体积报告、断网降级提示和失败 fallback，处理过程不上传任何文档内容。
+- `release:prepare` 必须依次执行 `sync-pdfjs-vendor` 与 `sync-tesseract-vendor`；后者在 `tesseract.js` optionalDependency 缺失时退出 0，不阻塞 CI/发布流程。
+- Tauri CSP 必须保留 `'wasm-unsafe-eval'`（让本地 tesseract.js wasm 在 WebView 中可实例化），且 `connect-src 'self'` 不可放开 —— 模型资源仅同源 vendor 与本地 IndexedDB，禁止任何远程 URL。
+- 高级 OCR 资源（PaddleOCR-VL / MinerU 等大模型）作为独立本地资源按需获取，启用前展示体积、运行内存、降级路径和失败提示。
+- 转换后检验三层（规则 diff、SSIM 视觉对比、OCR 回读）必须可在断网状态运行，验证 Repair Engine 修复后的输出质量并写入 QualityReport。
 - 文档处理模式始终禁止网络访问。
 
 ## 当前 P7 边界