Просмотр исходного кода

feat(document): 支持图片 OCR、扫描件 PDF 与音视频转写

- 新增 module/document:TextExtractor 门面按类型分派(Tika / PDF 逐页 / 图片 OCR / 音视频),
  PpOcrEngine 跑 PP-OCRv4(det/cls/rec 模型随 rapidocr4j jar 内置,OpenCV 原生库从 openpnp jar
  释放到 data/native 复用),PdfPageReader 只对缺文本层的页渲染 OCR(纯文本 PDF 零额外耗时),
  MediaTranscriber 用 ffmpeg stdout 管道 + Vosk 流式转写
- 对话附件与知识库放行图片/音视频:kind 增加 IMAGE/MEDIA,大小上限按类型区分
  (maxImageMb/maxMediaMb),注入块标注「图片, OCR N 字」「音视频, 转写 N 字」
- 修 Vosk 中文乱码:JNA 默认按 sun.jnu.encoding(GBK) 解码 UTF-8 结果,加载模型前把 jna.encoding
  钉成 UTF-8;CellDll 用 Library.OPTION_STRING_ENCODING 保持客户端 DLL 的平台编码
  (基站库路径可能含中文),两边互不影响
- 新增 zsjz.ocr / zsjz.asr 配置与 deploy/install-media-deps.sh(Linux 装 ffmpeg + 中文字体、
  下载 Vosk 模型、检测 glibc ≥ 2.27),设计文档 docs/design/ai-media-ocr-asr.md
- 测试:TextExtractorTest(真实 PP-OCR 图片/扫描 PDF/纯文本 PDF 不触发 OCR)、
  MediaTranscriberTest、MediaTranscriberLiveTest(opt-in 真实中文语音转写),
  Router / ChatAttachmentService 用例同步更新
cc 3 недель назад
Родитель
Сommit
2bc56f9eda
34 измененных файлов с 2200 добавлено и 104 удалено
  1. 6 0
      .gitignore
  2. 3 0
      QUICK_START.md
  3. 7 2
      ai-electron/frontend/src/ai/components/ChatComposer.vue
  4. 3 1
      ai-electron/frontend/src/ai/components/KnowledgeDocModal.vue
  5. 67 0
      ai-server/pom.xml
  6. 8 1
      ai-server/src/main/java/com/zsjz/ai/common/utils/CellDll.java
  7. 23 12
      ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentContentRouter.java
  8. 2 2
      ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachment.java
  9. 9 0
      ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentProperties.java
  10. 53 31
      ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java
  11. 41 0
      ai-server/src/main/java/com/zsjz/ai/module/document/AsrProperties.java
  12. 67 0
      ai-server/src/main/java/com/zsjz/ai/module/document/DocumentKinds.java
  13. 15 0
      ai-server/src/main/java/com/zsjz/ai/module/document/ExtractionResult.java
  14. 365 0
      ai-server/src/main/java/com/zsjz/ai/module/document/MediaTranscriber.java
  15. 70 0
      ai-server/src/main/java/com/zsjz/ai/module/document/OcrProperties.java
  16. 109 0
      ai-server/src/main/java/com/zsjz/ai/module/document/PdfPageReader.java
  17. 237 0
      ai-server/src/main/java/com/zsjz/ai/module/document/PpOcrEngine.java
  18. 238 0
      ai-server/src/main/java/com/zsjz/ai/module/document/TextExtractor.java
  19. 1 4
      ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocIndexer.java
  20. 28 28
      ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocParser.java
  21. 19 6
      ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeProperties.java
  22. 13 5
      ai-server/src/main/java/com/zsjz/ai/module/knowledge/service/KnowledgeDocService.java
  23. 4 0
      ai-server/src/main/resources/application-dev.yaml
  24. 4 0
      ai-server/src/main/resources/application-pro.yaml
  25. 58 0
      ai-server/src/main/resources/application.yaml
  26. 18 6
      ai-server/src/test/java/com/zsjz/ai/module/agent/attachment/AttachmentContentRouterTest.java
  27. 27 1
      ai-server/src/test/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentServiceTest.java
  28. 69 0
      ai-server/src/test/java/com/zsjz/ai/module/document/MediaTranscriberLiveTest.java
  29. 49 0
      ai-server/src/test/java/com/zsjz/ai/module/document/MediaTranscriberTest.java
  30. 183 0
      ai-server/src/test/java/com/zsjz/ai/module/document/TextExtractorTest.java
  31. 32 0
      deploy/env.sh
  32. 121 0
      deploy/install-media-deps.sh
  33. 246 0
      docs/design/ai-media-ocr-asr.md
  34. 5 5
      sql/chat_attachment.sql

+ 6 - 0
.gitignore

@@ -43,5 +43,11 @@ __pycache__/
 /bge-m3/
 /.agentscope/
 
+# 媒体解析的离线资产与原生库(体积大,按文档本地放置)
+/vosk-model/
+/tools/
+/data/native/
+/ai-server/data/native/
+
 # DSH 沙箱权限诊断产物(ACL 备份/恢复脚本,不应入库)
 /.acl-recovery/

+ 3 - 0
QUICK_START.md

@@ -34,12 +34,15 @@ zsjz-ai/
 | Elasticsearch | **8.18.x**(须与 Spring Boot 3.5 托管的客户端版本匹配) | — |
 | DuckDB | 无需安装,JDBC 驱动内嵌(案件分析库) | — |
 | Neo4j | 可选,仅在配置图谱能力时需要 | — |
+| ffmpeg + Vosk 中文模型 | 可选,仅**音视频转写**需要(图片/扫描件 OCR 不需要任何外部资产) | `ffmpeg -version`;模型目录含 `am/` |
 
 > 依赖服务的硬/软关系:
 > - **Redis 是登录的硬依赖** —— `sa-token-redis-jackson` 已装配,Redis 不可用则所有 `StpUtil.*` 抛异常,无降级实现。
 > - **PostgreSQL(master)** 存平台元数据 / Agent 会话 / 模型配置 / 向量,不可用则起不来。
 > - **Elasticsearch** 供 `module/search` 全文检索(索引 `zsjz_search`)。
 > - **DuckDB(slave)** 是按案件/工作空间切换的文件库,不是常驻服务。
+> - **图片/扫描件 OCR** 用 PP-OCRv4,模型随 `rapidocr4j` jar 分发、OpenCV 原生库在 `openpnp:opencv` jar 内 —— **无需安装 tesseract、无需下载模型**;Linux 需 glibc ≥ 2.27。
+> - **音视频转写**依赖外部 ffmpeg 与 Vosk 模型目录,缺失时只有音视频上传会以可读原因失败。Linux 一键安装:`sudo bash deploy/install-media-deps.sh`;细节见 [docs/design/ai-media-ocr-asr.md](docs/design/ai-media-ocr-asr.md)。
 
 ---
 

+ 7 - 2
ai-electron/frontend/src/ai/components/ChatComposer.vue

@@ -32,7 +32,7 @@
       </div>
 
       <div class="ai-composer__bar">
-        <!-- 附件:选择即上传;支持 txt/md/json/pdf/doc/docx/csv/xls/xlsx,图片音视频不支持 -->
+        <!-- 附件:选择即上传;文档/表格走解析,图片走本地 OCR,音视频走本地转写 -->
         <button class="ai-composer__tpl" type="button" :disabled="disabled || streaming" @click="pickFile">
           <Icon icon="mdi:paperclip" :size="13" />
           附件
@@ -41,7 +41,7 @@
           ref="fileRef"
           class="ai-composer__file"
           type="file"
-          accept=".txt,.md,.json,.pdf,.doc,.docx,.csv,.xls,.xlsx"
+          accept=".txt,.md,.json,.pdf,.doc,.docx,.csv,.xls,.xlsx,.jpg,.jpeg,.png,.bmp,.gif,.tif,.tiff,.mp3,.wav,.m4a,.aac,.flac,.ogg,.opus,.wma,.amr,.mp4,.mov,.mkv,.avi,.flv,.wmv,.webm,.mpg,.mpeg"
           @change="onFilePicked"
         />
 
@@ -232,6 +232,11 @@
     if (['xls', 'xlsx', 'csv'].includes(ext)) return 'mdi:file-table-outline';
     if (['pdf'].includes(ext)) return 'mdi:file-pdf-box';
     if (['doc', 'docx'].includes(ext)) return 'mdi:file-word-outline';
+    if (['jpg', 'jpeg', 'png', 'bmp', 'gif', 'tif', 'tiff'].includes(ext)) return 'mdi:file-image-outline';
+    if (['mp3', 'wav', 'm4a', 'aac', 'flac', 'ogg', 'opus', 'wma', 'amr'].includes(ext))
+      return 'mdi:file-music-outline';
+    if (['mp4', 'mov', 'mkv', 'avi', 'flv', 'wmv', 'webm', 'mpg', 'mpeg'].includes(ext))
+      return 'mdi:file-video-outline';
     return 'mdi:file-document-outline';
   }
 

+ 3 - 1
ai-electron/frontend/src/ai/components/KnowledgeDocModal.vue

@@ -131,7 +131,9 @@
   const uploading = ref(false);
   let pollTimer: ReturnType<typeof setTimeout> | null = null;
 
-  const acceptStr = '.txt,.md,.log,.json,.xml,.yaml,.yml,.ini,.sql,.tsv,.pdf,.doc,.docx,.rtf,.odt,.wps,.html,.htm,.eml,.csv,.xls,.xlsx,.ppt,.pptx';
+  // 文档/表格走解析,图片走本地 OCR,音视频走本地转写(ffmpeg + Vosk)
+  const acceptStr =
+    '.txt,.md,.log,.json,.xml,.yaml,.yml,.ini,.sql,.tsv,.pdf,.doc,.docx,.rtf,.odt,.wps,.html,.htm,.eml,.csv,.xls,.xlsx,.ppt,.pptx,.jpg,.jpeg,.png,.bmp,.gif,.tif,.tiff,.mp3,.wav,.m4a,.aac,.flac,.ogg,.opus,.wma,.amr,.mp4,.mov,.mkv,.avi,.flv,.wmv,.webm,.mpg,.mpeg';
 
   const columns = [
     { title: '文件名', key: 'fileName', ellipsis: true },

+ 67 - 0
ai-server/pom.xml

@@ -28,6 +28,12 @@
         <pgvector.version>0.1.6</pgvector.version>
         <djl.version>0.38.0</djl.version>
         <onnxruntime.version>1.30.0</onnxruntime.version>
+        <!-- 文档解析扩展:Tika 显式钉版本;PP-OCR 走 rapidocr4j(模型内置);ASR 走 Vosk -->
+        <tika.version>3.3.1</tika.version>
+        <pdfbox.version>3.0.7</pdfbox.version>
+        <rapidocr4j.version>1.0.3</rapidocr4j.version>
+        <opencv.version>4.6.0-0</opencv.version>
+        <vosk.version>0.3.45</vosk.version>
     </properties>
     <dependencyManagement>
         <dependencies>
@@ -134,6 +140,67 @@
             <artifactId>spring-ai-tika-document-reader</artifactId>
         </dependency>
 
+        <!-- Tika 显式钉版本(原先仅经 spring-ai-tika-document-reader 传递引入),
+             图片/扫描件/音视频解析都直接依赖它 -->
+        <dependency>
+            <groupId>org.apache.tika</groupId>
+            <artifactId>tika-core</artifactId>
+            <version>${tika.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.tika</groupId>
+            <artifactId>tika-parsers-standard-package</artifactId>
+            <version>${tika.version}</version>
+        </dependency>
+
+        <!-- PP-OCRv4 本地推理(module/document):模型 det/cls/rec 直接内置在 jar 里,
+             字典在 rec 模型 metadata 中,运行期零下载。只调用 ONNX Runtime 公共 API,
+             与下方钉死的 onnxruntime 1.30.0 兼容,故排除它自带的 1.18.0 -->
+        <dependency>
+            <groupId>io.github.hzkitty</groupId>
+            <artifactId>rapidocr4j</artifactId>
+            <version>${rapidocr4j.version}</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>com.microsoft.onnxruntime</groupId>
+                    <artifactId>onnxruntime</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+        <!-- PP-OCR 前后处理依赖 OpenCV。这个 jar 一个文件内含 Windows x86_64、
+             Linux x86_64/ARMv8/ARMv7、macOS 原生库 —— Windows 上构建、Linux 上运行
+             (Linux 需 glibc ≥ 2.27) -->
+        <dependency>
+            <groupId>org.openpnp</groupId>
+            <artifactId>opencv</artifactId>
+            <version>${opencv.version}</version>
+        </dependency>
+
+        <!-- 扫描件 PDF 逐页判定:PDFBox 取每页文本层,缺文本页渲染位图交 OCR。
+             版本与 Tika 3.3.1 内部一致;jai-imageio / jbig2 用于渲染 CCITT、JBIG2 编码的扫描页 -->
+        <dependency>
+            <groupId>org.apache.pdfbox</groupId>
+            <artifactId>pdfbox</artifactId>
+            <version>${pdfbox.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.jai-imageio</groupId>
+            <artifactId>jai-imageio-core</artifactId>
+            <version>1.4.0</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.pdfbox</groupId>
+            <artifactId>jbig2-imageio</artifactId>
+            <version>3.0.4</version>
+        </dependency>
+
+        <!-- 音视频转写:jar 内置 win/linux/macOS x86_64 原生库;音频解码由外部 ffmpeg 完成 -->
+        <dependency>
+            <groupId>com.alphacephei</groupId>
+            <artifactId>vosk</artifactId>
+            <version>${vosk.version}</version>
+        </dependency>
+
         <dependency>
             <groupId>org.postgresql</groupId>
             <artifactId>postgresql</artifactId>

+ 8 - 1
ai-server/src/main/java/com/zsjz/ai/common/utils/CellDll.java

@@ -4,6 +4,8 @@ import com.sun.jna.Library;
 import com.sun.jna.Native;
 import com.sun.jna.ptr.DoubleByReference;
 
+import java.util.Map;
+
 /**
  * 基站定位动态链接库接口
  * <p>
@@ -22,8 +24,13 @@ public interface CellDll extends Library {
     /**
      * 动态链接库实例
      * 通过Native.load加载本地库,单例模式
+     *
+     * <p>显式声明字符串编码 = 平台原生编码(sun.jnu.encoding):Vosk 的 JNA 绑定为了正确解码
+     * UTF-8 的识别结果会把全局 {@code jna.encoding} 钉成 UTF-8,而本库的 {@code cell_init}
+     * 接收的是 ANSI 的 {@code char*} 路径(基站库目录可能含中文),必须保持平台编码。
      */
-    CellDll INSTANCE_DLL = Native.load(TowerUtils.dll(), CellDll.class);
+    CellDll INSTANCE_DLL = Native.load(TowerUtils.dll(), CellDll.class,
+            Map.of(Library.OPTION_STRING_ENCODING, System.getProperty("sun.jnu.encoding", "UTF-8")));
 
     /**
      * 初始化基站数据库

+ 23 - 12
ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentContentRouter.java

@@ -1,13 +1,16 @@
 package com.zsjz.ai.module.agent.attachment;
 
+import com.zsjz.ai.module.document.DocumentKinds;
+
 import java.util.Locale;
 import java.util.Set;
 
 /**
  * 附件类型路由(f.txt 步骤 2-4 的服务端部分):后缀 + MIME → 处理路径。
  *
- * <p>纯函数无状态,判据刻意只用后缀与 MIME 大类(图片/音视频/压缩包/加密二进制
- * 一律 UNSUPPORTED —— 本版本无 OCR/ASR,提取不出文本的类型给拒绝比给幻觉强)。
+ * <p>纯函数无状态,判据刻意只用后缀与 MIME 大类。图片与音视频现在可以解析:
+ * 图片走本地 PP-OCR,音视频走 ffmpeg + Vosk 转写;压缩包/加密二进制仍然拒绝
+ * —— 提取不出文本的类型给拒绝比给幻觉强。后缀清单与 {@link DocumentKinds} 共用同一份。
  */
 public final class AttachmentContentRouter {
 
@@ -19,7 +22,10 @@ public final class AttachmentContentRouter {
             "txt", "md", "log", "json", "xml", "yaml", "yml", "ini", "sql", "tsv",
             "pdf", "doc", "docx", "rtf", "odt", "wps", "html", "htm", "eml");
 
-    /** 明确拒绝的大类(无 OCR/ASR,见设计边界) */
+    /**
+     * 明确拒绝的 MIME 大类。图片/音视频仍列在这里,但只拦「后缀不在白名单」的情况
+     * (例如 webp 目前没有解码器、.dat 实为音视频);后缀命中白名单的优先放行。
+     */
     private static final Set<String> UNSUPPORTED_MIME_PREFIXES = Set.of(
             "image/", "audio/", "video/", "application/zip", "application/x-rar",
             "application/gzip", "application/x-7z", "application/octet-stream");
@@ -28,11 +34,15 @@ public final class AttachmentContentRouter {
     }
 
     public enum Kind {
-        /** 文档:Tika 提取文本 */
+        /** 文档:Tika 提取文本(PDF 逐页 OCR) */
         DOCUMENT,
         /** 表格:流式扫描行数/表头/样本 */
         TABLE,
-        /** 不支持:图片/音视频/压缩包/加密/未知 */
+        /** 图片:本地 OCR 出文字 */
+        IMAGE,
+        /** 音视频:ffmpeg 解码 + 本地转写 */
+        MEDIA,
+        /** 不支持:压缩包/加密/未知 */
         UNSUPPORTED
     }
 
@@ -51,13 +61,19 @@ public final class AttachmentContentRouter {
             return Kind.UNSUPPORTED;
         }
         // 后缀白名单优先:即使 MIME 探测为 octet-stream(部分 pdf/自定义文本会这样)也放行,
-        // 提取阶段的 Tika/扫描器自己会失败并报明确原因
+        // 提取阶段的 Tika/扫描器/OCR 自己会失败并报明确原因
         if (SHEET_SUFFIXES.contains(suffix)) {
             return Kind.TABLE;
         }
         if (DOC_SUFFIXES.contains(suffix)) {
             return Kind.DOCUMENT;
         }
+        if (DocumentKinds.isImage(suffix)) {
+            return Kind.IMAGE;
+        }
+        if (DocumentKinds.isMedia(suffix)) {
+            return Kind.MEDIA;
+        }
         if (mime != null && unsupportedMime(mime)) {
             return Kind.UNSUPPORTED;
         }
@@ -70,12 +86,7 @@ public final class AttachmentContentRouter {
 
     /** 后缀(小写、无点);无后缀返回空串 */
     public static String suffixOf(String fileName) {
-        if (fileName == null) {
-            return "";
-        }
-        int dot = fileName.lastIndexOf('.');
-        return dot < 0 || dot == fileName.length() - 1
-                ? "" : fileName.substring(dot + 1).toLowerCase(Locale.ROOT);
+        return DocumentKinds.suffixOf(fileName);
     }
 
     private static boolean unsupportedMime(String mime) {

+ 2 - 2
ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachment.java

@@ -14,7 +14,7 @@ import java.time.LocalDateTime;
  * 对话附件({@code chat_attachment}):一次输入框上传的文件登记。
  *
  * <h3>三路处理</h3>
- * {@link #kind} = DOCUMENT / TABLE / UNSUPPORTED;DOCUMENT 与 TABLE 再按规模分流:
+ * {@link #kind} = DOCUMENT / TABLE / IMAGE / MEDIA / UNSUPPORTED;DOCUMENT / IMAGE / MEDIA 与 TABLE 再按规模分流:
  * 小内容走 {@link #inlineText} 直接进消息;大表格不物化,Agent 用
  * {@code execute_python} 读 {@link #filePath} 全量计算;大文档向量化后按问题检索
  * ({@code chat_att_vec_{caseId}_d{dims}})。
@@ -58,7 +58,7 @@ public class ChatAttachment implements Serializable {
     @TableField("mime")
     private String mime;
 
-    /** DOCUMENT / TABLE / UNSUPPORTED */
+    /** DOCUMENT / TABLE / IMAGE / MEDIA / UNSUPPORTED */
     @TableField("kind")
     private String kind;
 

+ 9 - 0
ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentProperties.java

@@ -26,6 +26,12 @@ public class ChatAttachmentProperties {
     /** 表格类大小上限(MB):流式扫描对象,可比文档大 */
     private long maxSheetMb = 200;
 
+    /** 图片类大小上限(MB):本地 OCR 对象 */
+    private long maxImageMb = 30;
+
+    /** 音视频类大小上限(MB):ffmpeg 解码 + 转写对象(受 multipart 上限 200MB 约束) */
+    private long maxMediaMb = 200;
+
     /** 文档内联/RAG 的单次提取字符上限(内联截断线,也是全文提取上限) */
     private int inlineMaxChars = 30000;
 
@@ -86,6 +92,9 @@ public class ChatAttachmentProperties {
     private static List<String> mergeDefault() {
         java.util.LinkedHashSet<String> all = new java.util.LinkedHashSet<>(DEFAULT_SHEET_SUFFIXES);
         all.addAll(DEFAULT_DOC_SUFFIXES);
+        // 图片 OCR / 音视频转写的后缀与全文提取共用一份(DocumentKinds),避免两处清单漂移
+        all.addAll(com.zsjz.ai.module.document.DocumentKinds.IMAGE_SUFFIXES);
+        all.addAll(com.zsjz.ai.module.document.DocumentKinds.MEDIA_SUFFIXES);
         return List.copyOf(all);
     }
 }

+ 53 - 31
ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java

@@ -7,12 +7,11 @@ import com.baomidou.mybatisplus.core.toolkit.Wrappers;
 import com.zsjz.ai.common.context.CaseContextHolder;
 import com.zsjz.ai.common.exception.ServerException;
 import com.zsjz.ai.common.utils.Json;
+import com.zsjz.ai.module.document.ExtractionResult;
+import com.zsjz.ai.module.document.TextExtractor;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.tika.Tika;
-import org.apache.tika.metadata.Metadata;
-import org.apache.tika.parser.AutoDetectParser;
-import org.apache.tika.sax.BodyContentHandler;
 import org.springframework.scheduling.annotation.Scheduled;
 import org.springframework.stereotype.Service;
 import org.springframework.web.multipart.MultipartFile;
@@ -57,6 +56,8 @@ public class ChatAttachmentService {
 
     private final AttachmentDocIndexer docIndexer;
 
+    private final TextExtractor textExtractor;
+
     private final ChatAttachmentProperties props;
 
     private final Tika tika = new Tika();
@@ -91,15 +92,21 @@ public class ChatAttachmentService {
         String safeName = sanitizeFileName(file.getOriginalFilename());
         String suffix = AttachmentContentRouter.suffixOf(safeName);
         if (!props.effectiveSuffixes().contains(suffix)) {
-            throw new ServerException(400, "不支持的文件类型: " + suffix + "(暂支持文档与表格,图片/音视频/压缩包不支持)");
+            throw new ServerException(400, "不支持的文件类型: " + suffix
+                    + "(支持文档、表格、图片与音视频,压缩包/加密文件不支持)");
         }
         long size = file.getSize();
         String mime = detectMime(file, safeName);
         AttachmentContentRouter.Kind kind = AttachmentContentRouter.route(safeName, mime);
         if (kind == AttachmentContentRouter.Kind.UNSUPPORTED) {
-            throw new ServerException(400, "该文件类型暂不支持解析: " + safeName + "(无 OCR/ASR 能力)");
-        }
-        long limitMb = kind == AttachmentContentRouter.Kind.TABLE ? props.getMaxSheetMb() : props.getMaxDocMb();
+            throw new ServerException(400, "该文件类型暂不支持解析: " + safeName + "(压缩包/加密文件不支持)");
+        }
+        long limitMb = switch (kind) {
+            case TABLE -> props.getMaxSheetMb();
+            case IMAGE -> props.getMaxImageMb();
+            case MEDIA -> props.getMaxMediaMb();
+            default -> props.getMaxDocMb();
+        };
         if (size > limitMb * 1024 * 1024) {
             throw new ServerException(400, "文件超过大小上限(" + limitMb + "MB): " + safeName);
         }
@@ -136,7 +143,7 @@ public class ChatAttachmentService {
             if (kind == AttachmentContentRouter.Kind.TABLE) {
                 extractTable(att, target, safeName);
             } else {
-                extractDocument(att, target);
+                extractContent(att, target);
             }
             att.setStatus("READY");
         } catch (Exception e) {
@@ -171,34 +178,28 @@ public class ChatAttachmentService {
         }
     }
 
-    /** 文档:Tika 提取(writeLimit = RAG 索引上限,超限即截断),小文档同时内联 */
-    private void extractDocument(ChatAttachment att, Path target) throws Exception {
+    /**
+     * 文档 / 图片 / 音视频:统一走 {@link TextExtractor}
+     * (Tika / PDF 逐页 OCR / 图片 PP-OCR / ffmpeg + Vosk 转写),
+     * 提取上限 = RAG 索引上限;小内容内联,大内容向量化后按问题检索。
+     */
+    private void extractContent(ChatAttachment att, Path target) throws Exception {
         Path sidecar = sidecarPath(target, ".txt");
         long maxChars = (long) props.getMaxChunks() * props.getChunkSize();
-        int limit = (int) Math.min(maxChars + 1, Integer.MAX_VALUE);
-        BodyContentHandler handler = new BodyContentHandler(limit);
-        boolean truncated = false;
-        // writeLimit 超限时 Tika 抛 WriteLimitReachedException 中断解析,已提取的内容仍在 handler 里
-        try (var in = Files.newInputStream(target)) {
-            new AutoDetectParser().parse(in, handler, new Metadata());
-        } catch (Exception e) {
-            if (handler.toString().isEmpty()) {
-                throw new IllegalStateException("文档文本提取失败: " + e.getMessage());
-            }
-            truncated = true;
-        }
-        String full = handler.toString();
+        ExtractionResult result = textExtractor.extract(target, att.getFileName(), att.getMime(),
+                (int) Math.min(maxChars, Integer.MAX_VALUE));
+        String full = result.text();
         Files.writeString(sidecar, full, StandardCharsets.UTF_8);
         att.setCharCount(full.length());
         att.setSidecarPath(sidecar.toString());
-        if (truncated || full.length() >= maxChars) {
+        if (result.truncated() || full.length() >= maxChars) {
             att.setTruncated(1);
         }
         if (full.length() <= props.getInlineMaxChars()) {
-            // 小文档:全文内联
+            // 小内容:全文内联(图片 OCR / 短转写基本都是这条)
             att.setInlineText(full);
         } else {
-            // 大文档:同步 RAG 索引(超块数的部分由 indexer 截断并标注)
+            // 大内容:同步 RAG 索引(超块数的部分由 indexer 截断并标注)
             try {
                 AttachmentDocIndexer.IndexResult r = docIndexer.index(full, att.getId(), att.getSessionId(), att.getCaseId());
                 att.setIndexBlocks(r.chunks());
@@ -274,10 +275,7 @@ public class ChatAttachmentService {
         String head = "【附件 " + no + "/" + total + ":" + att.getFileName() + "】";
         if (att.getInlineText() != null && !att.getInlineText().isBlank()) {
             // 路径 A:全文/全表内联
-            String label = "TABLE".equals(att.getKind())
-                    ? "表格, " + att.getRowCount() + " 行"
-                    : "文档, " + att.getCharCount() + " 字" + (att.getTruncated() == 1 ? ", 已截断" : "");
-            sb.append(head).append("(").append(label).append(")\n");
+            sb.append(head).append("(").append(kindLabel(att)).append(")\n");
             sb.append("<<<ATTACHMENT_START>>>\n").append(att.getInlineText()).append("\n<<<ATTACHMENT_END>>>\n");
             return sb.toString();
         }
@@ -308,7 +306,7 @@ public class ChatAttachmentService {
                     att.getId(), e.getMessage());
             fragments = List.of();
         }
-        sb.append(head).append("(文档, ").append(att.getCharCount()).append(" 字, 已切片索引 ")
+        sb.append(head).append("(").append(kindName(att)).append(", ").append(att.getCharCount()).append(" 字, 已切片索引 ")
                 .append(att.getIndexBlocks()).append(" 片").append(att.getTruncated() == 1 ? ", 仅索引前部" : "")
                 .append(")\n");
         if (fragments.isEmpty()) {
@@ -328,6 +326,30 @@ public class ChatAttachmentService {
         return sb.toString();
     }
 
+    /**
+     * 内联块的类型标签。图片 OCR 与音视频转写要显式标出来 ——
+     * 模型看到的是一段文本,但用户需要知道这段文本是「识别/转写」来的,不是原件原文。
+     */
+    private static String kindLabel(ChatAttachment att) {
+        int chars = att.getCharCount() == null ? 0 : att.getCharCount();
+        String truncated = att.getTruncated() != null && att.getTruncated() == 1 ? ", 已截断" : "";
+        return switch (StrUtil.blankToDefault(att.getKind(), "DOCUMENT")) {
+            case "TABLE" -> "表格, " + (att.getRowCount() == null ? 0 : att.getRowCount()) + " 行";
+            case "IMAGE" -> "图片, OCR " + chars + " 字" + truncated;
+            case "MEDIA" -> "音视频, 转写 " + chars + " 字" + truncated;
+            default -> "文档, " + chars + " 字" + truncated;
+        };
+    }
+
+    /** RAG 片段的类型名(与 {@link #kindLabel} 同一套 kind 取值) */
+    private static String kindName(ChatAttachment att) {
+        return switch (StrUtil.blankToDefault(att.getKind(), "DOCUMENT")) {
+            case "IMAGE" -> "图片";
+            case "MEDIA" -> "音视频";
+            default -> "文档";
+        };
+    }
+
     /** 表格样本预览(markdown,前 sampleRows 行) */
     private String buildSamplePreview(ChatAttachment att) {
         AttachmentSheetScanner.SheetScan scan = "csv".equals(AttachmentContentRouter.suffixOf(att.getFileName()))

+ 41 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/AsrProperties.java

@@ -0,0 +1,41 @@
+package com.zsjz.ai.module.document;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+/**
+ * 本地语音转写配置({@code zsjz.asr})。
+ *
+ * <p>音频解码必须借助外部 {@code ffmpeg}(Tika 3.x 已无 ffmpeg 解析器,也没有本地语音识别),
+ * 转写用 Vosk(原生库随 jar 分发,模型目录需离线放置,见 docs/design/ai-media-ocr-asr.md)。
+ */
+@Data
+@Component
+@ConfigurationProperties(prefix = "zsjz.asr")
+public class AsrProperties {
+
+    /** 是否启用音视频转写(关闭后音视频上传直接拒绝) */
+    private boolean enabled = true;
+
+    /**
+     * ffmpeg 可执行文件路径。空 = 依次找 {@code {user.dir}/tools/ffmpeg/ffmpeg(.exe)} 与 PATH;
+     * Linux 部署一般直接写 /usr/bin/ffmpeg。
+     */
+    private String ffmpegPath;
+
+    /** Vosk 模型目录(含 am/、conf/);相对路径按 user.dir 解析 */
+    private String modelPath = "vosk-model";
+
+    /** 单文件最多转写的时长(秒),超出部分不转写并标注 */
+    private int maxDurationSeconds = 600;
+
+    /** ffmpeg 进程总超时(秒),防止坏文件把上传请求挂死 */
+    private int ffmpegTimeoutSeconds = 600;
+
+    /** 送入 Vosk 的采样率,必须与模型一致(中文模型均为 16000) */
+    private int sampleRate = 16000;
+
+    /** 转写文本字符上限,超出截断 */
+    private int maxChars = 200_000;
+}

+ 67 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/DocumentKinds.java

@@ -0,0 +1,67 @@
+package com.zsjz.ai.module.document;
+
+import java.util.Locale;
+import java.util.Set;
+
+/**
+ * 需要「先取内容再进上下文」的媒体类型后缀(图片 / 音频 / 视频)。
+ *
+ * <p>这里是对话附件路由({@code AttachmentContentRouter})与知识库后缀白名单共用的唯一来源,
+ * 避免同一份清单在四处各写一遍。
+ *
+ * <p>图片只列 JDK {@code ImageIO} 能解码的格式;webp 需要额外 ImageIO 插件,本期不支持。
+ * 音视频只要 {@code ffmpeg} 能解码就收,具体可用性由运行期探测决定(缺 ffmpeg 时上传会给出明确原因)。
+ */
+public final class DocumentKinds {
+
+    /** 图片:本地 OCR 出文字 */
+    public static final Set<String> IMAGE_SUFFIXES = Set.of(
+            "jpg", "jpeg", "png", "bmp", "gif", "tif", "tiff");
+
+    /** 音视频:ffmpeg 解码 16k 单声道后交 Vosk 转写 */
+    public static final Set<String> MEDIA_SUFFIXES = Set.of(
+            "mp3", "wav", "m4a", "aac", "flac", "ogg", "opus", "wma", "amr",
+            "mp4", "mov", "mkv", "avi", "flv", "wmv", "webm", "mpg", "mpeg");
+
+    private DocumentKinds() {
+    }
+
+    public static boolean isImage(String suffix) {
+        return IMAGE_SUFFIXES.contains(normalize(suffix));
+    }
+
+    public static boolean isMedia(String suffix) {
+        return MEDIA_SUFFIXES.contains(normalize(suffix));
+    }
+
+    public static boolean isPdf(String suffix, String mime) {
+        return "pdf".equals(normalize(suffix))
+                || (mime != null && mime.toLowerCase(Locale.ROOT).startsWith("application/pdf"));
+    }
+
+    public static boolean isImageMime(String mime) {
+        return mime != null && mime.toLowerCase(Locale.ROOT).startsWith("image/");
+    }
+
+    public static boolean isMediaMime(String mime) {
+        if (mime == null) {
+            return false;
+        }
+        String m = mime.toLowerCase(Locale.ROOT);
+        return m.startsWith("audio/") || m.startsWith("video/");
+    }
+
+    /** 后缀(小写、无点);无后缀返回空串 */
+    public static String suffixOf(String fileName) {
+        if (fileName == null) {
+            return "";
+        }
+        int dot = fileName.lastIndexOf('.');
+        return dot < 0 || dot == fileName.length() - 1
+                ? "" : fileName.substring(dot + 1).toLowerCase(Locale.ROOT);
+    }
+
+    private static String normalize(String suffix) {
+        return suffix == null ? "" : suffix.toLowerCase(Locale.ROOT);
+    }
+}

+ 15 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/ExtractionResult.java

@@ -0,0 +1,15 @@
+package com.zsjz.ai.module.document;
+
+/**
+ * 一次文本提取的结果。
+ *
+ * @param text            提取到的全文(已包含来源标注行,如「【图片 OCR 提取】」)
+ * @param truncated       是否因字符/页数/时长上限被截断
+ * @param durationSeconds 音视频时长(秒);非音视频为 0
+ */
+public record ExtractionResult(String text, boolean truncated, int durationSeconds) {
+
+    public static ExtractionResult of(String text) {
+        return new ExtractionResult(text, false, 0);
+    }
+}

+ 365 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/MediaTranscriber.java

@@ -0,0 +1,365 @@
+package com.zsjz.ai.module.document;
+
+import cn.hutool.core.util.StrUtil;
+import cn.hutool.json.JSONObject;
+import cn.hutool.json.JSONUtil;
+import jakarta.annotation.PreDestroy;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.vosk.LibVosk;
+import org.vosk.LogLevel;
+import org.vosk.Model;
+import org.vosk.Recognizer;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Deque;
+import java.util.List;
+import java.util.Locale;
+import java.util.concurrent.TimeUnit;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * 音视频转写:外部 ffmpeg 解码成 16k 单声道 PCM,流式喂 Vosk。
+ *
+ * <h3>为什么自己调 ffmpeg</h3>
+ * Tika 3.3.1 已经没有 ffmpeg 解析器,也没有任何本地语音识别实现(其转写桥只有云端 Amazon Transcribe);
+ * 它对音频只给容器/ID3 元数据。要拿到可用文本只能自己解码 + 本地识别。
+ *
+ * <h3>实现要点</h3>
+ * <ul>
+ *   <li>PCM 走 stdout 管道,不落临时文件;stderr 单独线程排空(不排空会让 ffmpeg 写满缓冲卡死);</li>
+ *   <li>时长上限用 {@code -t} 交给 ffmpeg 截断,避免长视频把上传请求挂住;</li>
+ *   <li>Vosk {@link Model} 单实例懒加载(加载慢、占内存),{@link Recognizer} 每文件一个;</li>
+ *   <li>进程超时 {@code destroyForcibly},坏文件不会一直占着线程。</li>
+ * </ul>
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class MediaTranscriber {
+
+    /** ffmpeg 输入信息里的时长行,如 "Duration: 00:03:21.12" */
+    private static final Pattern DURATION = Pattern.compile("Duration:\\s*(\\d+):(\\d+):(\\d+(?:\\.\\d+)?)");
+
+    private static final int STDERR_KEEP_LINES = 20;
+
+    private final AsrProperties props;
+
+    private volatile Path ffmpeg;
+
+    private volatile Model model;
+
+    private volatile String unavailableReason;
+
+    private volatile boolean probed;
+
+    /**
+     * @param text            转写文本(每个 final 段一行)
+     * @param durationSeconds 媒体时长(秒);解析不到为 0
+     * @param truncated       是否因时长/字符上限截断
+     */
+    public record Transcript(String text, int durationSeconds, boolean truncated) {
+    }
+
+    public boolean isAvailable() {
+        probe();
+        return ffmpeg != null && model != null;
+    }
+
+    public String unavailableReason() {
+        probe();
+        return unavailableReason;
+    }
+
+    /**
+     * 转写一个音视频文件。
+     *
+     * @throws IllegalStateException 未启用 / 未就绪 / 无音频轨道 / 解码失败(消息可直接展示给用户)
+     */
+    public Transcript transcribe(Path file) {
+        if (!props.isEnabled()) {
+            throw new IllegalStateException("音视频转写未启用(zsjz.asr.enabled=false)");
+        }
+        if (!isAvailable()) {
+            throw new IllegalStateException("本地语音转写未就绪:" + unavailableReason
+                    + "(见 docs/design/ai-media-ocr-asr.md)");
+        }
+        int maxDuration = Math.max(1, props.getMaxDurationSeconds());
+        List<String> command = new ArrayList<>(List.of(
+                ffmpeg.toString(), "-hide_banner", "-nostdin",
+                "-i", file.toAbsolutePath().toString(),
+                "-vn", "-sn", "-dn",
+                "-ac", "1", "-ar", String.valueOf(props.getSampleRate()),
+                "-acodec", "pcm_s16le", "-f", "s16le",
+                "-t", String.valueOf(maxDuration), "pipe:1"));
+
+        StringBuilder text = new StringBuilder();
+        boolean truncated = false;
+        Process process = null;
+        StderrSink stderr = null;
+        try {
+            process = new ProcessBuilder(command).redirectErrorStream(false).start();
+            stderr = new StderrSink(process.getErrorStream());
+            Thread stderrThread = Thread.ofVirtual().name("asr-ffmpeg-stderr").start(stderr);
+
+            try (Recognizer recognizer = new Recognizer(model, props.getSampleRate());
+                 InputStream pcm = process.getInputStream()) {
+                recognizer.setWords(false);
+                byte[] buffer = new byte[8192];
+                long deadline = System.currentTimeMillis()
+                        + Math.max(30, props.getFfmpegTimeoutSeconds()) * 1000L;
+                int read;
+                while ((read = pcm.read(buffer)) > 0) {
+                    if (System.currentTimeMillis() > deadline) {
+                        truncated = true;
+                        break;
+                    }
+                    if (recognizer.acceptWaveForm(buffer, read)) {
+                        appendSegment(text, recognizer.getResult());
+                        if (text.length() >= props.getMaxChars()) {
+                            truncated = true;
+                            break;
+                        }
+                    }
+                }
+                appendSegment(text, recognizer.getFinalResult());
+            }
+
+            if (!process.waitFor(10, TimeUnit.SECONDS)) {
+                process.destroyForcibly();
+                // destroyForcibly 是异步的:不等它落地就 exitValue() 会抛 IllegalThreadStateException
+                process.waitFor(5, TimeUnit.SECONDS);
+            }
+            stderrThread.join(3000);
+
+            int exitCode = process.isAlive() ? -1 : process.exitValue();
+            String result = text.toString().strip();
+            int duration = stderr.durationSeconds();
+            if (duration > maxDuration) {
+                truncated = true;
+            }
+            if (result.isEmpty()) {
+                // 视频没有音轨、编码不支持等都在这里:把 ffmpeg 的错误尾巴交给用户可比「空文本」有用得多
+                String detail = stderr.tail();
+                if (exitCode != 0 || !detail.isBlank()) {
+                    throw new IllegalStateException("音视频未识别出语音内容"
+                            + (detail.isBlank() ? "" : "(ffmpeg: " + StrUtil.maxLength(detail, 300) + ")"));
+                }
+                throw new IllegalStateException("音视频未识别出语音内容");
+            }
+            if (result.length() > props.getMaxChars()) {
+                result = result.substring(0, props.getMaxChars());
+                truncated = true;
+            }
+            return new Transcript(result, Math.max(duration, 0), truncated);
+        } catch (IOException e) {
+            throw new IllegalStateException("ffmpeg 启动失败: " + e.getMessage(), e);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("音视频转写被中断");
+        } finally {
+            if (process != null && process.isAlive()) {
+                process.destroyForcibly();
+            }
+        }
+    }
+
+    @PreDestroy
+    void shutdown() {
+        Model current = model;
+        model = null;
+        if (current != null) {
+            try {
+                current.close();
+            } catch (Exception e) {
+                log.debug("关闭 Vosk 模型失败(忽略): {}", e.getMessage());
+            }
+        }
+    }
+
+    // ==================== 初始化 ====================
+
+    private synchronized void probe() {
+        if (probed) {
+            return;
+        }
+        probed = true;
+        try {
+            // Vosk 的 JNA 绑定把 native 返回的 UTF-8 JSON 转成 Java String;JNA 默认用
+            // sun.jnu.encoding(中文 Windows 是 GBK)解码,中文会变成「杞﹁締」这类乱码。
+            // jna.encoding 是每次转换现读的系统属性,这里钉成 UTF-8(不覆盖运维已有的设置)。
+            if (System.getProperty("jna.encoding") == null) {
+                System.setProperty("jna.encoding", "UTF-8");
+            }
+            ffmpeg = resolveFfmpeg();
+            verifyFfmpeg(ffmpeg);
+            Path modelDir = modelDir();
+            LibVosk.setLogLevel(LogLevel.WARNINGS);
+            model = new Model(modelDir.toString());
+            log.info("[ASR] Vosk 就绪: model={}, ffmpeg={}", modelDir, ffmpeg);
+        } catch (Throwable e) {
+            // UnsatisfiedLinkError(原生库与平台不匹配)同样要转成可读原因
+            unavailableReason = e.getClass().getSimpleName()
+                    + (StrUtil.isBlank(e.getMessage()) ? "" : ": " + e.getMessage());
+            log.warn("[ASR] 本地语音转写不可用: {}", unavailableReason);
+        }
+    }
+
+    private Path resolveFfmpeg() throws IOException {
+        if (StrUtil.isNotBlank(props.getFfmpegPath())) {
+            Path configured = resolve(props.getFfmpegPath());
+            if (!Files.isRegularFile(configured)) {
+                throw new IOException("zsjz.asr.ffmpeg-path 指向的文件不存在: " + configured);
+            }
+            return configured;
+        }
+        String exe = System.getProperty("os.name", "").toLowerCase(Locale.ROOT).contains("win")
+                ? "ffmpeg.exe" : "ffmpeg";
+        Path bundled = Paths.get(System.getProperty("user.dir"), "tools", "ffmpeg", exe)
+                .toAbsolutePath().normalize();
+        if (Files.isRegularFile(bundled)) {
+            return bundled;
+        }
+        Path onPath = findOnPath(exe);
+        if (onPath != null) {
+            return onPath;
+        }
+        throw new IOException("未找到 ffmpeg(已检查 zsjz.asr.ffmpeg-path、tools/ffmpeg/ 与 PATH)");
+    }
+
+    private static Path findOnPath(String exe) {
+        String pathEnv = System.getenv("PATH");
+        if (pathEnv == null) {
+            return null;
+        }
+        for (String dir : pathEnv.split(java.io.File.pathSeparator)) {
+            if (dir.isBlank()) {
+                continue;
+            }
+            Path candidate = Paths.get(dir, exe);
+            if (Files.isRegularFile(candidate)) {
+                return candidate.toAbsolutePath().normalize();
+            }
+        }
+        return null;
+    }
+
+    /** 确认挑中的文件真的能执行:PATH 上同名但损坏/不是 ffmpeg 的情况并不罕见 */
+    private static void verifyFfmpeg(Path ffmpeg) throws IOException, InterruptedException {
+        Process process = new ProcessBuilder(ffmpeg.toString(), "-version")
+                .redirectErrorStream(true).start();
+        try (InputStream in = process.getInputStream()) {
+            in.readAllBytes();
+        }
+        if (!process.waitFor(10, TimeUnit.SECONDS) || process.exitValue() != 0) {
+            process.destroyForcibly();
+            throw new IOException("不是可用的 ffmpeg 可执行文件: " + ffmpeg);
+        }
+    }
+
+    private Path modelDir() throws IOException {
+        Path dir = resolve(props.getModelPath());
+        if (!Files.isDirectory(dir)) {
+            throw new IOException("Vosk 模型目录不存在: " + dir + "(应包含 am/ 与 conf/)");
+        }
+        if (!Files.isDirectory(dir.resolve("am"))) {
+            throw new IOException("Vosk 模型目录结构不完整: " + dir + "(缺 am/)");
+        }
+        return dir;
+    }
+
+    private static Path resolve(String path) {
+        Path p = Paths.get(path);
+        return p.isAbsolute() ? p.normalize()
+                : Paths.get(System.getProperty("user.dir")).resolve(p).toAbsolutePath().normalize();
+    }
+
+    // ==================== 工具 ====================
+
+    /** Vosk 每段结果都是 {"text": "..."},空段跳过,其余一行一段(模型不输出标点,换行能明显提升可读性) */
+    static void appendSegment(StringBuilder sb, String json) {
+        if (StrUtil.isBlank(json)) {
+            return;
+        }
+        try {
+            JSONObject obj = JSONUtil.parseObj(json);
+            String line = StrUtil.trimToEmpty(obj.getStr("text"));
+            if (!line.isEmpty()) {
+                sb.append(line).append('\n');
+            }
+        } catch (Exception e) {
+            // 解析不出来说明库的输出格式变了:宁可丢掉这一段,也不把 JSON 原文塞进正文
+        }
+    }
+
+    /** 从 ffmpeg 的 "Duration: HH:MM:SS.ss" 行解析秒数;解析不到返回 0 */
+    static int parseDuration(String line) {
+        if (line == null) {
+            return 0;
+        }
+        Matcher matcher = DURATION.matcher(line);
+        if (!matcher.find()) {
+            return 0;
+        }
+        int hours = Integer.parseInt(matcher.group(1));
+        int minutes = Integer.parseInt(matcher.group(2));
+        double seconds = Double.parseDouble(matcher.group(3));
+        return (int) Math.round(hours * 3600 + minutes * 60 + seconds);
+    }
+
+    /** 排空 ffmpeg stderr:保留尾部若干行(错误原因)并解析时长 */
+    private static final class StderrSink implements Runnable {
+
+        private final InputStream err;
+
+        private final Deque<String> lines = new ArrayDeque<>();
+
+        private volatile int durationSeconds;
+
+        private StderrSink(InputStream err) {
+            this.err = err;
+        }
+
+        @Override
+        public void run() {
+            try (BufferedReader reader = new BufferedReader(
+                    new InputStreamReader(err, StandardCharsets.UTF_8))) {
+                String line;
+                while ((line = reader.readLine()) != null) {
+                    synchronized (lines) {
+                        if (durationSeconds == 0) {
+                            durationSeconds = parseDuration(line);
+                        }
+                        lines.addLast(line);
+                        if (lines.size() > STDERR_KEEP_LINES) {
+                            lines.removeFirst();
+                        }
+                    }
+                }
+            } catch (Exception e) {
+                // 进程被杀时流会异常关闭,忽略
+            }
+        }
+
+        int durationSeconds() {
+            return durationSeconds;
+        }
+
+        String tail() {
+            synchronized (lines) {
+                return String.join(" | ", lines);
+            }
+        }
+    }
+}

+ 70 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/OcrProperties.java

@@ -0,0 +1,70 @@
+package com.zsjz.ai.module.document;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+/**
+ * 本地 OCR 配置({@code zsjz.ocr}):PP-OCRv4 推理参数 + 扫描件 PDF 的逐页判据。
+ *
+ * <p>模型(det/cls/rec)与字典随 {@code rapidocr4j} 打进 jar,默认无需任何外部资产;
+ * 只有想把移动端模型换成 server 大模型时,才需要填 {@code *-model-path} 绝对路径。
+ * 依赖的 OpenCV 原生库同样在 {@code openpnp:opencv} jar 内(Windows/Linux/macOS 全平台),
+ * 首次使用会抽到 {@code {user.dir}/data/native/} 下复用。
+ */
+@Data
+@Component
+@ConfigurationProperties(prefix = "zsjz.ocr")
+public class OcrProperties {
+
+    /** 是否启用 OCR(关闭后图片/扫描件上传直接拒绝) */
+    private boolean enabled = true;
+
+    /**
+     * OpenCV 原生库路径覆盖。空 = 从依赖 jar 自动抽出(推荐);
+     * 部署在非标准平台时才需要手工指定,见 docs/design/ai-media-ocr-asr.md。
+     */
+    private String opencvLibPath;
+
+    /** 单行识别结果的最低置信度,低于该值丢弃 */
+    private float textScore = 0.5f;
+
+    /** 检测模型输入的最小边(PP-OCR det 的 limit_side_len,limit_type=min) */
+    private int detLimitSideLen = 736;
+
+    /** 单张图片 OCR 前的最大边(超过则先等比缩放,控制耗时与内存) */
+    private int maxSideLen = 2000;
+
+    /** 单张图片的最大像素数,超过先等比缩小(手机原图常见 5000×4000) */
+    private long imageMaxPixels = 40_000_000L;
+
+    /** 检测模型路径;空 = 用 jar 内置的 ch_PP-OCRv4_det_infer.onnx */
+    private String detModelPath;
+
+    /** 方向分类模型路径;空 = 用 jar 内置的 ch_ppocr_mobile_v2.0_cls_infer.onnx */
+    private String clsModelPath;
+
+    /** 识别模型路径;空 = 用 jar 内置的 ch_PP-OCRv4_rec_infer.onnx */
+    private String recModelPath;
+
+    /**
+     * 字典文件路径。空 = 读识别模型 metadata 里的 character 列表(内置模型自带);
+     * 只有换成不含该 metadata 的第三方模型时才需要补 ppocr_keys_v1.txt。
+     */
+    private String recKeysPath;
+
+    /** 扫描件渲染 DPI:太低识别率差,太高耗时与内存翻倍 */
+    private int pdfDpi = 200;
+
+    /**
+     * 页文本少于该字符数视为「无文本层」,对该页做 OCR。
+     * 默认 10:扫描页通常 0~2 字(只有页眉/页码),而正常的短文页不该被误判。
+     */
+    private int pageMinChars = 10;
+
+    /** 单文件最多 OCR 的页数(纯文本页不计数、不占用该预算) */
+    private int maxPages = 30;
+
+    /** 单次提取的 OCR 时间预算(秒),超出后剩余页跳过并标注 */
+    private int totalBudgetSeconds = 240;
+}

+ 109 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/PdfPageReader.java

@@ -0,0 +1,109 @@
+package com.zsjz.ai.module.document;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.rendering.ImageType;
+import org.apache.pdfbox.rendering.PDFRenderer;
+import org.apache.pdfbox.text.PDFTextStripper;
+import org.springframework.stereotype.Component;
+
+import java.awt.image.BufferedImage;
+import java.nio.file.Path;
+
+/**
+ * 扫描件 PDF 逐页读取:有文本层的页直接用文本,缺文本的页渲染成位图交 {@link PpOcrEngine}。
+ *
+ * <p>纯文本 PDF 一页都不 OCR(不付额外耗时),混合型 PDF(正文 + 扫描插页)也能逐页补上。
+ * 页数/时间预算只约束 OCR —— 文本层提取仍按字符上限走完全部页,不会因为「只允许 OCR 30 页」
+ * 把 500 页的文本 PDF 截到 30 页。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class PdfPageReader {
+
+    private final OcrProperties props;
+
+    private final PpOcrEngine ocrEngine;
+
+    /**
+     * @param text             逐页拼接的正文(每页带 {@code [第N页]} 标记)
+     * @param truncated        是否因字符上限被截断
+     * @param ocrPages         实际 OCR 的页数
+     * @param skippedOcrPages  缺文本但没 OCR 的页数(页数或时间预算耗尽、或 OCR 单页失败)
+     */
+    public record PdfText(String text, boolean truncated, int ocrPages, int skippedOcrPages) {
+    }
+
+    /**
+     * @throws Exception PDFBox 解析失败(加密、损坏)时抛给调用方,由 {@link TextExtractor} 回退 Tika
+     */
+    public PdfText read(Path file, int maxChars) throws Exception {
+        boolean ocrAvailable = props.isEnabled() && ocrEngine.isAvailable();
+        try (PDDocument document = Loader.loadPDF(file.toFile())) {
+            int total = document.getNumberOfPages();
+            PDFRenderer renderer = new PDFRenderer(document);
+            StringBuilder sb = new StringBuilder();
+            int ocrPages = 0;
+            int skipped = 0;
+            boolean truncated = false;
+            long deadline = System.currentTimeMillis() + Math.max(1, props.getTotalBudgetSeconds()) * 1000L;
+
+            for (int page = 1; page <= total; page++) {
+                if (sb.length() >= maxChars) {
+                    truncated = true;
+                    break;
+                }
+                String text = pageText(document, page);
+                if (text.strip().length() < props.getPageMinChars()) {
+                    boolean budgetOk = ocrAvailable
+                            && ocrPages < Math.max(1, props.getMaxPages())
+                            && System.currentTimeMillis() < deadline;
+                    if (!budgetOk) {
+                        skipped++;
+                    } else {
+                        try {
+                            BufferedImage image = renderer.renderImageWithDPI(page - 1,
+                                    Math.max(72, props.getPdfDpi()), ImageType.RGB);
+                            String ocrText = ocrEngine.recognize(image);
+                            ocrPages++;
+                            // 只有 OCR 结果确实更完整才替换:文本层即使很短也是矢量文字,比识别结果可靠
+                            if (ocrText.strip().length() > text.strip().length()) {
+                                text = ocrText;
+                            }
+                        } catch (IllegalStateException e) {
+                            // 单页失败不拖垮整篇:保留文本层(可能为空),继续后面的页
+                            log.warn("PDF 第 {} 页 OCR 失败: {}", page, e.getMessage());
+                            skipped++;
+                        }
+                    }
+                }
+                sb.append("[第").append(page).append("页]\n").append(text.strip()).append("\n\n");
+            }
+
+            String full = sb.toString().strip();
+            if (full.length() > maxChars) {
+                full = full.substring(0, maxChars);
+                truncated = true;
+            }
+            return new PdfText(full, truncated, ocrPages, skipped);
+        }
+    }
+
+    /** 单页文本层;取不到就当空串(交给 OCR) */
+    private String pageText(PDDocument document, int page) {
+        try {
+            PDFTextStripper stripper = new PDFTextStripper();
+            stripper.setSortByPosition(true);
+            stripper.setStartPage(page);
+            stripper.setEndPage(page);
+            String text = stripper.getText(document);
+            return text == null ? "" : text;
+        } catch (Exception e) {
+            log.debug("PDF 第 {} 页文本层读取失败,按无文本处理: {}", page, e.getMessage());
+            return "";
+        }
+    }
+}

+ 237 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/PpOcrEngine.java

@@ -0,0 +1,237 @@
+package com.zsjz.ai.module.document;
+
+import cn.hutool.core.util.StrUtil;
+import io.github.hzkitty.RapidOCR;
+import io.github.hzkitty.entity.OcrConfig;
+import io.github.hzkitty.entity.OcrResult;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import java.awt.Color;
+import java.awt.Graphics2D;
+import java.awt.RenderingHints;
+import java.awt.image.BufferedImage;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.StandardCopyOption;
+import java.util.Locale;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * 本地 OCR 引擎:PP-OCRv4(PaddleOCR 中文模型),经 RapidOCR4j 在进程内推理。
+ *
+ * <h3>为什么不用 Tesseract</h3>
+ * Tesseract 的 Windows 原生库依赖 MSVC 运行库、Linux 必须装系统 libtesseract 并配 dev 软链,
+ * 两个平台各自要一套部署步骤;PP-OCR 的模型直接打在 jar 里、原生库(OpenCV)在一个 jar 内
+ * 覆盖 Windows/Linux/macOS,构建一次三平台可用,中文识别也明显更好。
+ *
+ * <h3>生命期与并发</h3>
+ * RapidOCR 重复 {@code create()} 会泄漏 ONNX Runtime session,必须缓存单实例;
+ * 引擎内部 det/cls/rec 共享缓冲区,非线程安全,识别调用一律串行(上传/索引都是单文档流程,
+ * 串行化的吞吐损失可以接受)。首次调用才加载模型与原生库,避免拖慢启动。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class PpOcrEngine {
+
+    /** 依赖 jar(openpnp:opencv)里的原生库根路径 */
+    private static final String OPENCV_RESOURCE_ROOT = "nu/pattern/opencv/";
+
+    private final OcrProperties props;
+
+    private final ReentrantLock lock = new ReentrantLock();
+
+    private volatile RapidOCR engine;
+
+    /** 探测失败原因(null 且 engine 为 null 表示尚未探测) */
+    private volatile String unavailableReason;
+
+    private volatile boolean probed;
+
+    /** OCR 是否可用(不可用时 {@link #unavailableReason()} 给出具体原因) */
+    public boolean isAvailable() {
+        return init() != null;
+    }
+
+    public String unavailableReason() {
+        init();
+        return unavailableReason;
+    }
+
+    /**
+     * 识别一张图片。
+     *
+     * @throws IllegalStateException OCR 未启用 / 未就绪 / 识别失败(消息可直接展示给用户)
+     */
+    public String recognize(BufferedImage image) {
+        if (!props.isEnabled()) {
+            throw new IllegalStateException("本地 OCR 未启用(zsjz.ocr.enabled=false)");
+        }
+        RapidOCR ocr = init();
+        if (ocr == null) {
+            throw new IllegalStateException("本地 OCR 未就绪:" + unavailableReason
+                    + "(见 docs/design/ai-media-ocr-asr.md)");
+        }
+        BufferedImage prepared = prepare(image);
+        lock.lock();
+        try {
+            OcrResult result = ocr.run(prepared);
+            String text = result == null || result.getStrRes() == null ? "" : result.getStrRes().trim();
+            return text;
+        } catch (Exception e) {
+            throw new IllegalStateException("OCR 识别失败: " + e.getMessage(), e);
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    // ==================== 初始化 ====================
+
+    private RapidOCR init() {
+        if (engine != null) {
+            return engine;
+        }
+        if (probed) {
+            return null;
+        }
+        synchronized (this) {
+            if (engine != null) {
+                return engine;
+            }
+            if (probed) {
+                return null;
+            }
+            probed = true;
+            try {
+                engine = RapidOCR.create(buildConfig());
+                log.info("[OCR] PP-OCR 引擎就绪(模型随 jar 内置,OpenCV 原生库已加载)");
+                return engine;
+            } catch (Throwable e) {
+                // UnsatisfiedLinkError / ExceptionInInitializerError(OpenCV 或 ONNX native 加载失败)也要落到可读原因
+                unavailableReason = e.getClass().getSimpleName()
+                        + (StrUtil.isBlank(e.getMessage()) ? "" : ": " + e.getMessage());
+                log.warn("[OCR] 本地 OCR 不可用: {}", unavailableReason);
+                return null;
+            }
+        }
+    }
+
+    private OcrConfig buildConfig() throws IOException {
+        OcrConfig config = new OcrConfig();
+        config.Global.setOpencvLibPath(opencvNativePath().toString());
+        config.Global.setTextScore(props.getTextScore());
+        config.Global.setMaxSideLen(props.getMaxSideLen());
+        config.Global.setPrintVerbose(false);
+        config.Det.setLimitSideLen(Math.max(320, props.getDetLimitSideLen()));
+        applyPath(props.getDetModelPath(), config.Det::setModelPath);
+        applyPath(props.getClsModelPath(), config.Cls::setModelPath);
+        applyPath(props.getRecModelPath(), config.Rec::setModelPath);
+        applyPath(props.getRecKeysPath(), config.Rec::setRecKeysPath);
+        return config;
+    }
+
+    private void applyPath(String configured, java.util.function.Consumer<String> setter) {
+        if (StrUtil.isNotBlank(configured)) {
+            setter.accept(resolve(configured).toString());
+        }
+    }
+
+    /**
+     * OpenCV 原生库路径:显式配置优先;否则从依赖 jar 抽出到 {@code {user.dir}/data/native/}。
+     *
+     * <p>不是直接用 openpnp 的 {@code OpenCV.loadLocally()}:它每次启动都会把 63MB 的 .so/.dll
+     * 解压到临时目录;我们自己落盘一次,进程重启也复用。
+     */
+    private Path opencvNativePath() throws IOException {
+        if (StrUtil.isNotBlank(props.getOpencvLibPath())) {
+            Path configured = resolve(props.getOpencvLibPath());
+            if (!Files.isRegularFile(configured)) {
+                throw new IOException("zsjz.ocr.opencv-lib-path 指向的文件不存在: " + configured);
+            }
+            return configured;
+        }
+        String resource = opencvResourcePath();
+        if (resource == null) {
+            throw new IOException("当前平台(" + System.getProperty("os.name") + "/"
+                    + System.getProperty("os.arch") + ")没有内置 OpenCV 原生库,请配置 zsjz.ocr.opencv-lib-path");
+        }
+        Path dir = Paths.get(System.getProperty("user.dir"), "data", "native").toAbsolutePath().normalize();
+        Path target = dir.resolve(Paths.get(resource).getFileName().toString());
+        // 1MB 只是「明显不完整」的粗判:正常 .so/.dll 都在 19MB 以上
+        if (Files.isRegularFile(target) && Files.size(target) > 1024 * 1024) {
+            return target;
+        }
+        Files.createDirectories(dir);
+        try (InputStream in = getClass().getClassLoader().getResourceAsStream(resource)) {
+            if (in == null) {
+                throw new IOException("OpenCV 原生库资源不存在: " + resource);
+            }
+            Path tmp = Files.createTempFile(dir, "opencv-", ".part");
+            Files.copy(in, tmp, StandardCopyOption.REPLACE_EXISTING);
+            Files.move(tmp, target, StandardCopyOption.REPLACE_EXISTING);
+        }
+        log.info("[OCR] 已释放 OpenCV 原生库: {}", target);
+        return target;
+    }
+
+    /** 依赖 jar 内的原生库相对路径(按 OS/架构选择) */
+    static String opencvResourcePath() {
+        String os = System.getProperty("os.name", "").toLowerCase(Locale.ROOT);
+        String arch = System.getProperty("os.arch", "").toLowerCase(Locale.ROOT);
+        boolean arm = arch.contains("aarch") || arch.contains("arm");
+        if (os.contains("win")) {
+            boolean x64 = arch.contains("64") || arch.equals("amd64");
+            return OPENCV_RESOURCE_ROOT + "windows/" + (x64 ? "x86_64" : "x86_32")
+                    + "/opencv_java460.dll";
+        }
+        if (os.contains("mac") || os.contains("darwin")) {
+            return OPENCV_RESOURCE_ROOT + "osx/" + (arm ? "ARMv8" : "x86_64") + "/libopencv_java460.dylib";
+        }
+        if (os.contains("linux")) {
+            if (arm) {
+                return OPENCV_RESOURCE_ROOT + "linux/" + (arch.equals("arm") ? "ARMv7" : "ARMv8")
+                        + "/libopencv_java460.so";
+            }
+            return OPENCV_RESOURCE_ROOT + "linux/x86_64/libopencv_java460.so";
+        }
+        return null;
+    }
+
+    private static Path resolve(String path) {
+        Path p = Paths.get(path);
+        return p.isAbsolute() ? p.normalize()
+                : Paths.get(System.getProperty("user.dir")).resolve(p).toAbsolutePath().normalize();
+    }
+
+    // ==================== 图像预处理 ====================
+
+    /**
+     * 统一转 RGB 并把超大图等比缩到像素上限内:PP-OCR 内部还会按 maxSideLen 再缩放,
+     * 这里只负责不让一张 8000×6000 的照片把堆内存顶爆。
+     */
+    private BufferedImage prepare(BufferedImage src) {
+        long pixels = (long) src.getWidth() * src.getHeight();
+        long maxPixels = Math.max(1_000_000L, props.getImageMaxPixels());
+        double scale = pixels > maxPixels ? Math.sqrt((double) maxPixels / pixels) : 1.0;
+        int width = Math.max(1, (int) Math.round(src.getWidth() * scale));
+        int height = Math.max(1, (int) Math.round(src.getHeight() * scale));
+        BufferedImage out = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB);
+        Graphics2D g = out.createGraphics();
+        try {
+            g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR);
+            g.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY);
+            // 透明 PNG 铺白底:黑底会让 OCR 完全失效
+            g.setColor(Color.WHITE);
+            g.fillRect(0, 0, width, height);
+            g.drawImage(src, 0, 0, width, height, null);
+        } finally {
+            g.dispose();
+        }
+        return out;
+    }
+}

+ 238 - 0
ai-server/src/main/java/com/zsjz/ai/module/document/TextExtractor.java

@@ -0,0 +1,238 @@
+package com.zsjz.ai.module.document;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.tika.metadata.Metadata;
+import org.apache.tika.metadata.TikaCoreProperties;
+import org.apache.tika.parser.AutoDetectParser;
+import org.apache.tika.sax.BodyContentHandler;
+import org.springframework.stereotype.Component;
+
+import javax.imageio.ImageIO;
+import javax.imageio.ImageReader;
+import javax.imageio.stream.ImageInputStream;
+import java.awt.image.BufferedImage;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * 文档文本提取门面:按类型分派到 Tika / PDF 逐页 OCR / 图片 OCR / 音视频转写。
+ *
+ * <p>调用方(对话附件、知识库)只需关心「给我一段文本」,具体走哪条路、以及各条路的
+ * 上限与来源标注都在这里收口;提取失败时抛 {@link IllegalStateException},消息可直接展示给用户。
+ *
+ * <h3>与 Tika 的关系</h3>
+ * 普通文档仍走 Tika(行为不变);PDF 与图片/音视频是 Tika 给不出内容的两类:
+ * 前者需要逐页判断有无文本层,后两者需要 OCR / ASR。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class TextExtractor {
+
+    private final OcrProperties ocrProps;
+
+    private final PpOcrEngine ocrEngine;
+
+    private final PdfPageReader pdfPageReader;
+
+    private final MediaTranscriber mediaTranscriber;
+
+    /**
+     * 提取文本。
+     *
+     * @param file     已落盘的原件(PDF / 音视频必须是真实文件)
+     * @param fileName 原始文件名,用于后缀判型
+     * @param mime     Tika 探测的 MIME(可空,后缀为空时兜底)
+     * @param maxChars 提取字符上限(超限截断而非报错)
+     * @throws IllegalStateException 提取失败 / OCR 或 ASR 未就绪 / 无内容可提取
+     */
+    public ExtractionResult extract(Path file, String fileName, String mime, int maxChars) {
+        String suffix = DocumentKinds.suffixOf(fileName);
+        if (DocumentKinds.isImage(suffix) || (suffix.isBlank() && DocumentKinds.isImageMime(mime))) {
+            return extractImage(file, maxChars);
+        }
+        if (DocumentKinds.isMedia(suffix) || (suffix.isBlank() && DocumentKinds.isMediaMime(mime))) {
+            return extractMedia(file);
+        }
+        if (DocumentKinds.isPdf(suffix, mime)) {
+            return extractPdf(file, maxChars);
+        }
+        return extractWithTika(file, maxChars);
+    }
+
+    // ==================== 图片 ====================
+
+    private ExtractionResult extractImage(Path file, int maxChars) {
+        int maxFrames = Math.max(1, ocrProps.getMaxPages());
+        List<BufferedImage> frames = readImages(file, maxFrames + 1);
+        if (frames.isEmpty()) {
+            throw new IllegalStateException("图片解码失败(不支持的编码): " + file.getFileName());
+        }
+        boolean truncated = frames.size() > maxFrames;
+        if (truncated) {
+            frames = new ArrayList<>(frames.subList(0, maxFrames));
+        }
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < frames.size(); i++) {
+            String text = ocrEngine.recognize(frames.get(i));
+            if (text.isBlank()) {
+                continue;
+            }
+            if (frames.size() > 1) {
+                sb.append("[第").append(i + 1).append("页]\n");
+            }
+            sb.append(text).append("\n\n");
+            if (sb.length() >= maxChars) {
+                truncated = true;
+                break;
+            }
+        }
+        String text = sb.toString().strip();
+        if (text.isEmpty()) {
+            throw new IllegalStateException("图片中没有识别到文字");
+        }
+        if (text.length() > maxChars) {
+            text = text.substring(0, maxChars);
+            truncated = true;
+        }
+        return new ExtractionResult("【图片 OCR 提取】\n" + text, truncated, 0);
+    }
+
+    /**
+     * 读取图片的所有帧(多页 TIFF 常见于扫描仪输出)。帧数受 maxFrames 限制,
+     * 不支持多帧的格式(如 JPEG)走单帧回退。
+     */
+    private static List<BufferedImage> readImages(Path file, int maxFrames) {
+        List<BufferedImage> frames = new ArrayList<>();
+        try (ImageInputStream iis = ImageIO.createImageInputStream(file.toFile())) {
+            if (iis == null) {
+                return frames;
+            }
+            Iterator<ImageReader> readers = ImageIO.getImageReaders(iis);
+            if (!readers.hasNext()) {
+                return frames;
+            }
+            ImageReader reader = readers.next();
+            try {
+                reader.setInput(iis, false, false);
+                int count;
+                try {
+                    count = Math.min(reader.getNumImages(true), maxFrames);
+                } catch (Exception e) {
+                    count = 1;
+                }
+                for (int i = 0; i < count; i++) {
+                    try {
+                        BufferedImage image = reader.read(i);
+                        if (image != null) {
+                            frames.add(image);
+                        }
+                    } catch (Exception e) {
+                        break;
+                    }
+                }
+            } finally {
+                reader.dispose();
+            }
+        } catch (IOException e) {
+            log.debug("图片解码失败: file={}, err={}", file.getFileName(), e.getMessage());
+        }
+        return frames;
+    }
+
+    // ==================== PDF ====================
+
+    private ExtractionResult extractPdf(Path file, int maxChars) {
+        boolean ocrReady = ocrProps.isEnabled() && ocrEngine.isAvailable();
+        if (!ocrReady) {
+            // 没有 OCR 能力时保持改造前行为:文本 PDF 照常提取,扫描件落到「无可提取文本」
+            return extractWithTika(file, maxChars);
+        }
+        PdfPageReader.PdfText result;
+        try {
+            result = pdfPageReader.read(file, maxChars);
+        } catch (Exception e) {
+            // 加密/结构异常等:交给 Tika 再试一次,失败信息由 Tika 侧给出
+            log.warn("PDFBox 逐页解析失败,回退 Tika: file={}, err={}", file.getFileName(), e.getMessage());
+            return extractWithTika(file, maxChars);
+        }
+        if (result.text().isBlank()) {
+            throw new IllegalStateException("文档无可提取文本(可能是扫描件/图片型 PDF,OCR 未识别出文字)");
+        }
+        String header = pdfHeader(result);
+        return new ExtractionResult(header + result.text(), result.truncated(), 0);
+    }
+
+    private static String pdfHeader(PdfPageReader.PdfText result) {
+        if (result.ocrPages() == 0 && result.skippedOcrPages() == 0) {
+            return result.truncated() ? "【PDF 已达字符上限,后续页未提取】\n" : "";
+        }
+        StringBuilder sb = new StringBuilder("【扫描件 PDF:");
+        sb.append("已 OCR ").append(result.ocrPages()).append(" 页");
+        if (result.skippedOcrPages() > 0) {
+            sb.append(";另有 ").append(result.skippedOcrPages()).append(" 页因页数/时间预算未识别");
+        }
+        if (result.truncated()) {
+            sb.append(";已达字符上限,后续页未提取");
+        }
+        return sb.append("】\n").toString();
+    }
+
+    // ==================== 音视频 ====================
+
+    private ExtractionResult extractMedia(Path file) {
+        MediaTranscriber.Transcript transcript = mediaTranscriber.transcribe(file);
+        StringBuilder header = new StringBuilder("【音视频转写");
+        if (transcript.durationSeconds() > 0) {
+            header.append(",时长 ").append(clock(transcript.durationSeconds()));
+        }
+        if (transcript.truncated()) {
+            header.append(",已截断");
+        }
+        header.append("】\n");
+        return new ExtractionResult(header + transcript.text(), transcript.truncated(),
+                transcript.durationSeconds());
+    }
+
+    /** 秒 → mm:ss(超过 1 小时用 h:mm:ss) */
+    static String clock(int seconds) {
+        int h = seconds / 3600;
+        int m = (seconds % 3600) / 60;
+        int s = seconds % 60;
+        return h > 0 ? String.format("%d:%02d:%02d", h, m, s) : String.format("%02d:%02d", m, s);
+    }
+
+    // ==================== 通用文档(Tika) ====================
+
+    private ExtractionResult extractWithTika(Path file, int maxChars) {
+        int limit = (int) Math.min((long) maxChars + 1, Integer.MAX_VALUE);
+        BodyContentHandler handler = new BodyContentHandler(limit);
+        Metadata metadata = new Metadata();
+        metadata.set(TikaCoreProperties.RESOURCE_NAME_KEY, file.getFileName().toString());
+        boolean truncated = false;
+        // writeLimit 超限时 Tika 抛 WriteLimitReachedException 中断解析,已提取内容仍在 handler 里
+        try (InputStream in = Files.newInputStream(file)) {
+            new AutoDetectParser().parse(in, handler, metadata);
+        } catch (Exception e) {
+            if (handler.toString().isBlank()) {
+                throw new IllegalStateException("文档文本提取失败: " + e.getMessage());
+            }
+            truncated = true;
+        }
+        String text = handler.toString();
+        if (text.isBlank()) {
+            throw new IllegalStateException("文档无可提取文本(可能是扫描件/图片型 PDF)");
+        }
+        if (text.length() > maxChars) {
+            text = text.substring(0, maxChars);
+            truncated = true;
+        }
+        return new ExtractionResult(text, truncated, 0);
+    }
+}

+ 1 - 4
ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocIndexer.java

@@ -131,10 +131,7 @@ public class KnowledgeDocIndexer {
                 return new String(in.readAllBytes(), StandardCharsets.UTF_8);
             }
         }
-        String fullText;
-        try (InputStream in = storageUtil.download(doc.getFilePath())) {
-            fullText = docParser.extract(in, maxChars);
-        }
+        String fullText = docParser.extract(doc.getFilePath(), doc.getFileName(), doc.getMime(), maxChars);
         String sidecarPath = KnowledgeDocParser.sidecarPathOf(doc.getFilePath());
         storageUtil.uploadString(fullText, sidecarPath);
         doc.setSidecarPath(sidecarPath);

+ 28 - 28
ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocParser.java

@@ -1,50 +1,50 @@
 package com.zsjz.ai.module.knowledge;
 
+import com.zsjz.ai.common.utils.LocalFileStorageUtil;
+import com.zsjz.ai.module.document.ExtractionResult;
+import com.zsjz.ai.module.document.TextExtractor;
+import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
-import org.apache.tika.metadata.Metadata;
-import org.apache.tika.parser.AutoDetectParser;
-import org.apache.tika.sax.BodyContentHandler;
 import org.springframework.stereotype.Component;
 
-import java.io.InputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
 
 /**
- * 知识库文档文本抽取(Tika AutoDetect)。
+ * 知识库文档文本抽取:按类型分派到 Tika / PDF 逐页 OCR / 图片 PP-OCR / 音视频转写
+ * (具体判定与上限见 {@link TextExtractor})。
  *
  * <p>上传链路(KnowledgeDocService)用它提取全文落 sidecar .txt;
  * 索引链路(KnowledgeDocIndexer)在 sidecar 缺失(提取失败后重试)时兜底重抽。
- * writeLimit 超限时 Tika 中断解析,已提取内容仍在 handler 里 —— 诚实截断,不报错丢弃
- * (与对话附件的文档提取同一套处理)。
+ *
+ * <p>入参是存储相对路径而不是输入流:PDF 逐页渲染与音视频解码都需要真实文件。
  */
 @Slf4j
 @Component
+@RequiredArgsConstructor
 public class KnowledgeDocParser {
 
+    private final LocalFileStorageUtil storageUtil;
+
+    private final TextExtractor textExtractor;
+
     /**
-     * 从原件输入流提取全文。
+     * 从原件提取全文。
      *
-     * @param in       原件输入流(调用方负责关闭)
-     * @param maxChars 提取字符上限(超限截断)
-     * @return 提取的全文
-     * @throws IllegalStateException 内容为空/解析彻底失败
+     * @param relativePath 原件存储相对路径({@code LocalFileStorageUtil} 根目录下)
+     * @param fileName     原始文件名(后缀判型)
+     * @param mime         上传时的 MIME(可空)
+     * @param maxChars     提取字符上限(超限截断)
+     * @return 提取的全文(含「图片 OCR / 扫描件 OCR / 音视频转写」来源标注行)
+     * @throws IllegalStateException 原件缺失/内容为空/解析失败/OCR 或 ASR 未就绪
      */
-    public String extract(InputStream in, int maxChars) {
-        int limit = (int) Math.min((long) maxChars + 1, Integer.MAX_VALUE);
-        BodyContentHandler handler = new BodyContentHandler(limit);
-        try {
-            new AutoDetectParser().parse(in, handler, new Metadata());
-        } catch (Exception e) {
-            // 超限中断时已提取的内容仍在 handler 里:非空则视为成功(截断),为空才是真失败
-            if (handler.toString().isEmpty()) {
-                throw new IllegalStateException("文档文本提取失败: " + e.getMessage());
-            }
-            log.warn("文档提取超限截断: err={}", e.getMessage());
-        }
-        String full = handler.toString();
-        if (full.isBlank()) {
-            throw new IllegalStateException("文档无可提取文本(可能是扫描件/图片型 PDF)");
+    public String extract(String relativePath, String fileName, String mime, int maxChars) {
+        Path file = storageUtil.resolve(relativePath);
+        if (!Files.isRegularFile(file)) {
+            throw new IllegalStateException("文档原件不存在: " + relativePath);
         }
-        return full;
+        ExtractionResult result = textExtractor.extract(file, fileName, mime, maxChars);
+        return result.text();
     }
 
     /** sidecar 存储相对路径:与原件同目录同名,扩展名替换为 .txt */

+ 19 - 6
ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeProperties.java

@@ -1,9 +1,11 @@
 package com.zsjz.ai.module.knowledge;
 
+import com.zsjz.ai.module.document.DocumentKinds;
 import lombok.Data;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.stereotype.Component;
 
+import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -20,9 +22,12 @@ public class KnowledgeProperties {
     /** 是否启用知识库功能(关闭后列表页与工具注册一并降级) */
     private boolean enabled = true;
 
-    /** 单文件大小上限(MB) */
+    /** 单文件大小上限(MB):文档/图片 */
     private long maxFileMb = 50;
 
+    /** 音视频文件大小上限(MB):ffmpeg 解码 + 转写对象,可比文档大(受 multipart 上限约束) */
+    private long maxMediaMb = 200;
+
     /** 单用户在单个知识库下的文档数上限 */
     private int maxDocsPerUser = 200;
 
@@ -50,11 +55,19 @@ public class KnowledgeProperties {
     /** 接受的后缀白名单(小写;空 = 用默认清单) */
     private List<String> acceptSuffixes;
 
-    /** 默认文档后缀(Tika 可解析的文本类文档与常见表格) */
-    public static final List<String> DEFAULT_SUFFIXES = List.of(
-            "txt", "md", "log", "json", "xml", "yaml", "yml", "ini", "sql", "tsv",
-            "pdf", "doc", "docx", "rtf", "odt", "wps", "html", "htm", "eml",
-            "csv", "xls", "xlsx", "ppt", "pptx");
+    /** 默认文档后缀(Tika/OCR/ASR 可解析的文档、表格、图片与音视频) */
+    public static final List<String> DEFAULT_SUFFIXES = defaults();
+
+    private static List<String> defaults() {
+        List<String> all = new ArrayList<>(List.of(
+                "txt", "md", "log", "json", "xml", "yaml", "yml", "ini", "sql", "tsv",
+                "pdf", "doc", "docx", "rtf", "odt", "wps", "html", "htm", "eml",
+                "csv", "xls", "xlsx", "ppt", "pptx"));
+        // 图片(本地 OCR)与音视频(ffmpeg + Vosk)的后缀与对话附件共用一份清单
+        all.addAll(DocumentKinds.IMAGE_SUFFIXES);
+        all.addAll(DocumentKinds.MEDIA_SUFFIXES);
+        return List.copyOf(all);
+    }
 
     /** 生效的后缀白名单 */
     public List<String> effectiveSuffixes() {

+ 13 - 5
ai-server/src/main/java/com/zsjz/ai/module/knowledge/service/KnowledgeDocService.java

@@ -84,10 +84,11 @@ public class KnowledgeDocService extends ServiceImpl<KnowledgeDocMapper, Knowled
         String safeName = sanitizeFileName(file.getOriginalFilename());
         String suffix = suffixOf(safeName);
         if (!props.effectiveSuffixes().contains(suffix)) {
-            throw new ServerException(400, "不支持的文件类型: " + suffix + "(仅支持可解析文本的文档/表格)");
+            throw new ServerException(400, "不支持的文件类型: " + suffix
+                    + "(支持文档、表格、图片与音视频,压缩包/加密文件不支持)");
         }
-        if (file.getSize() > props.getMaxFileMb() * 1024 * 1024) {
-            throw new ServerException(400, "文件超过大小上限(" + props.getMaxFileMb() + "MB): " + safeName);
+        if (file.getSize() > limitMb(suffix) * 1024 * 1024) {
+            throw new ServerException(400, "文件超过大小上限(" + limitMb(suffix) + "MB): " + safeName);
         }
         Long mine = lambdaQuery().eq(KnowledgeDoc::getKbId, kbId)
                 .eq(KnowledgeDoc::getUserId, userId).count();
@@ -115,8 +116,9 @@ public class KnowledgeDocService extends ServiceImpl<KnowledgeDocMapper, Knowled
         doc.setCreateTime(LocalDateTime.now());
         doc.setUpdateTime(LocalDateTime.now());
         boolean extracted;
-        try (InputStream in = file.getInputStream()) {
-            String fullText = docParser.extract(in, props.getMaxChunks() * props.getChunkSize());
+        try {
+            String fullText = docParser.extract(filePath, safeName, file.getContentType(),
+                    props.getMaxChunks() * props.getChunkSize());
             String sidecarPath = KnowledgeDocParser.sidecarPathOf(filePath);
             storageUtil.uploadString(fullText, sidecarPath);
             doc.setSidecarPath(sidecarPath);
@@ -244,4 +246,10 @@ public class KnowledgeDocService extends ServiceImpl<KnowledgeDocMapper, Knowled
         int dot = name.lastIndexOf('.');
         return dot >= 0 && dot < name.length() - 1 ? name.substring(dot + 1).toLowerCase() : "";
     }
+
+    /** 按类型选大小上限:音视频是解码+转写对象,允许比文档大 */
+    private long limitMb(String suffix) {
+        return com.zsjz.ai.module.document.DocumentKinds.isMedia(suffix)
+                ? props.getMaxMediaMb() : props.getMaxFileMb();
+    }
 }

+ 4 - 0
ai-server/src/main/resources/application-dev.yaml

@@ -85,3 +85,7 @@ zsjz:
   embedding:
     enabled: "${ZSJZ_EMBEDDING_ENABLED:true}"
     model-path: "${ZSJZ_EMBEDDING_MODEL_PATH:E:/workspace/zsjz-ai/bge-m3}"
+  # Vosk 中文模型同样放在仓库根(E:/workspace/zsjz-ai/vosk-model),user.dir=ai-server
+  # 时相对路径解析不到;未放模型时只有音视频上传会提示模型目录缺失,其他类型不受影响。
+  asr:
+    model-path: "${ZSJZ_ASR_MODEL_PATH:E:/workspace/zsjz-ai/vosk-model}"

+ 4 - 0
ai-server/src/main/resources/application-pro.yaml

@@ -54,6 +54,10 @@ zsjz:
   embedding:
     enabled: "${ZSJZ_EMBEDDING_ENABLED:true}"
     model-path: "${ZSJZ_EMBEDDING_MODEL_PATH:E:/workspace/zsjz-ai/bge-m3}"
+  # Vosk 中文模型与 embedding 同样放在仓库根;Linux 部署用 deploy/env.sh 里的
+  # ZSJZ_ASR_MODEL_PATH(/opt/zsjz-ai/vosk-model)覆盖。
+  asr:
+    model-path: "${ZSJZ_ASR_MODEL_PATH:E:/workspace/zsjz-ai/vosk-model}"
 
 # ========================================
 # Sa-Token 认证配置

+ 58 - 0
ai-server/src/main/resources/application.yaml

@@ -153,6 +153,10 @@ zsjz:
     max-sheet-mb: "${ZSJZ_CHAT_ATTACHMENT_MAX_SHEET_MB:200}"
     # 文档内联/RAG 的提取字符上限(超过截断并标注;也是 sidecar 写入上限)
     inline-max-chars: "${ZSJZ_CHAT_ATTACHMENT_INLINE_MAX_CHARS:30000}"
+    # 图片大小上限(MB,本地 OCR 对象)
+    max-image-mb: "${ZSJZ_CHAT_ATTACHMENT_MAX_IMAGE_MB:30}"
+    # 音视频大小上限(MB,解码+转写对象,受 spring.servlet.multipart 上限约束)
+    max-media-mb: "${ZSJZ_CHAT_ATTACHMENT_MAX_MEDIA_MB:200}"
     # 表格内联行数上限(超过走 Python 直读)
     inline-max-rows: "${ZSJZ_CHAT_ATTACHMENT_INLINE_MAX_ROWS:200}"
     # RAG 分块/重叠/块数上限/检索条数
@@ -161,6 +165,60 @@ zsjz:
     max-chunks: "${ZSJZ_CHAT_ATTACHMENT_MAX_CHUNKS:500}"
     top-k: "${ZSJZ_CHAT_ATTACHMENT_TOP_K:8}"
 
+  # 本地 OCR(module/document):图片与扫描件 PDF。
+  # PP-OCRv4 模型(det/cls/rec)随 rapidocr4j 打进 jar,字典在 rec 模型 metadata 里 ——
+  # 运行期不需要下载模型、不需要 tessdata、不需要 tesseract。
+  # OpenCV 原生库在 openpnp:opencv jar 内(Windows/Linux/macOS 同一个 jar),首次使用释放到
+  # {user.dir}/data/native/ 复用;Linux 要求 glibc ≥ 2.27(Ubuntu 18.04+/Debian 10+/Rocky 8+)。
+  # 扫描件 PDF 逐页判断:该页文本少于 page-min-chars 才 OCR,纯文本 PDF 完全不触发 OCR。
+  # 能力不可用(原生库加载失败/模型缺失)时,图片与扫描件上传会以可读原因失败,文本类文档不受影响。
+  ocr:
+    enabled: "${ZSJZ_OCR_ENABLED:true}"
+    # OpenCV 原生库路径覆盖;空 = 自动从依赖 jar 释放(推荐)
+    opencv-lib-path: "${ZSJZ_OCR_OPENCV_LIB_PATH:}"
+    # 单行识别结果的最低置信度,低于该值丢弃
+    text-score: "${ZSJZ_OCR_TEXT_SCORE:0.5}"
+    # 检测模型输入的最小边(PP-OCR det 的 limit_side_len)
+    det-limit-side-len: "${ZSJZ_OCR_DET_LIMIT_SIDE_LEN:736}"
+    # 单张图片 OCR 前的最大边(超过由引擎内部缩放)
+    max-side-len: "${ZSJZ_OCR_MAX_SIDE_LEN:2000}"
+    # 单张图片最大像素数,超过先等比缩小(手机原图常见 5000×4000)
+    image-max-pixels: "${ZSJZ_OCR_IMAGE_MAX_PIXELS:40000000}"
+    # 模型路径覆盖:空 = 用 jar 内置 PP-OCRv4;填绝对路径可换 server 大模型
+    det-model-path: "${ZSJZ_OCR_DET_MODEL_PATH:}"
+    cls-model-path: "${ZSJZ_OCR_CLS_MODEL_PATH:}"
+    rec-model-path: "${ZSJZ_OCR_REC_MODEL_PATH:}"
+    # 换外部识别模型(不含 character metadata)时补字典 ppocr_keys_v1.txt
+    rec-keys-path: "${ZSJZ_OCR_REC_KEYS_PATH:}"
+    # 扫描件渲染 DPI:太低识别率差,太高耗时与内存翻倍
+    pdf-dpi: "${ZSJZ_OCR_PDF_DPI:200}"
+    # 页文本少于该字符数视为「无文本层」,对该页做 OCR
+    page-min-chars: "${ZSJZ_OCR_PAGE_MIN_CHARS:10}"
+    # 单文件最多 OCR 的页数(纯文本页不计数、不占用该预算)
+    max-pages: "${ZSJZ_OCR_MAX_PAGES:30}"
+    # 单次提取的 OCR 时间预算(秒),超出后剩余页跳过并标注
+    total-budget-seconds: "${ZSJZ_OCR_TOTAL_BUDGET_SECONDS:240}"
+
+  # 本地音视频转写(module/document)。
+  # Tika 3.x 没有 ffmpeg 解析器、也没有任何本地语音识别实现(其转写桥只有云端 Amazon Transcribe),
+  # 所以音频解码由外部 ffmpeg 完成、识别由本机 Vosk 模型完成。
+  # Vosk 模型目录需离线放置(含 am/ 与 conf/),获取方式见 docs/design/ai-media-ocr-asr.md。
+  # ffmpeg 缺失或模型缺失时,音视频上传会以可读原因失败,其他类型不受影响。
+  asr:
+    enabled: "${ZSJZ_ASR_ENABLED:true}"
+    # ffmpeg 可执行文件路径;空 = {user.dir}/tools/ffmpeg/ffmpeg(.exe) → PATH
+    ffmpeg-path: "${ZSJZ_ASR_FFMPEG_PATH:}"
+    # Vosk 模型目录(相对路径按 user.dir 解析)
+    model-path: "${ZSJZ_ASR_MODEL_PATH:vosk-model}"
+    # 单文件最多转写的时长(秒),超出部分不转写并标注
+    max-duration-seconds: "${ZSJZ_ASR_MAX_DURATION_SECONDS:600}"
+    # ffmpeg 进程总超时(秒)
+    ffmpeg-timeout-seconds: "${ZSJZ_ASR_FFMPEG_TIMEOUT_SECONDS:600}"
+    # 送入 Vosk 的采样率,必须与模型一致(中文模型均为 16000)
+    sample-rate: "${ZSJZ_ASR_SAMPLE_RATE:16000}"
+    # 转写文本字符上限
+    max-chars: "${ZSJZ_ASR_MAX_CHARS:200000}"
+
   # 登录安全(module/plat)。
   auth:
     # 「账号正在使用」判定窗口(分钟):账号有有效会话且该窗口内活跃过,

+ 18 - 6
ai-server/src/test/java/com/zsjz/ai/module/agent/attachment/AttachmentContentRouterTest.java

@@ -15,7 +15,7 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 class AttachmentContentRouterTest {
 
     @Test
-    @DisplayName("后缀白名单路由:表格 TABLE / 文档 DOCUMENT")
+    @DisplayName("后缀白名单路由:表格 / 文档 / 图片 / 音视频")
     void routesBySuffix() {
         assertEquals(AttachmentContentRouter.Kind.TABLE,
                 AttachmentContentRouter.route("流水.csv", null));
@@ -25,21 +25,33 @@ class AttachmentContentRouterTest {
                 AttachmentContentRouter.route("合同.pdf", null));
         assertEquals(AttachmentContentRouter.Kind.DOCUMENT,
                 AttachmentContentRouter.route("说明.txt", null));
+        // 图片:后续走本地 PP-OCR
+        assertEquals(AttachmentContentRouter.Kind.IMAGE,
+                AttachmentContentRouter.route("截图.PNG", "image/png"));
+        assertEquals(AttachmentContentRouter.Kind.IMAGE,
+                AttachmentContentRouter.route("扫描件.tif", "application/octet-stream"));
+        // 音视频:后续走 ffmpeg + Vosk
+        assertEquals(AttachmentContentRouter.Kind.MEDIA,
+                AttachmentContentRouter.route("录音.mp3", "audio/mpeg"));
+        assertEquals(AttachmentContentRouter.Kind.MEDIA,
+                AttachmentContentRouter.route("录像.mp4", "video/mp4"));
     }
 
     @Test
-    @DisplayName("图片/音视频/压缩包/加密一律拒绝(无 OCR/ASR)")
+    @DisplayName("压缩包/加密/未知二进制仍拒绝;webp 等无解码器格式按 MIME 拒绝")
     void rejectsUnsupported() {
-        assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
-                AttachmentContentRouter.route("图.png", "image/png"));
-        assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
-                AttachmentContentRouter.route("录音.mp3", "audio/mpeg"));
         assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
                 AttachmentContentRouter.route("包.zip", "application/zip"));
         assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
                 AttachmentContentRouter.route("数据.dat", "application/octet-stream"));
         assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
                 AttachmentContentRouter.route("密.docx", "application/vnd.encrypted"));
+        // webp 不在图片白名单里(JDK 无解码器),MIME 是 image/ 大类 → 拒绝
+        assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
+                AttachmentContentRouter.route("图.webp", "image/webp"));
+        // 无后缀的音频:后缀判据缺席,只按 MIME 大类 → 拒绝
+        assertEquals(AttachmentContentRouter.Kind.UNSUPPORTED,
+                AttachmentContentRouter.route("无后缀", "audio/mpeg"));
     }
 
     @Test

+ 27 - 1
ai-server/src/test/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentServiceTest.java

@@ -1,6 +1,7 @@
 package com.zsjz.ai.module.agent.attachment;
 
 import com.zsjz.ai.common.exception.ServerException;
+import com.zsjz.ai.module.document.TextExtractor;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
@@ -37,13 +38,15 @@ class ChatAttachmentServiceTest {
 
     private ChatAttachmentMapper mapper;
     private AttachmentDocIndexer indexer;
+    private TextExtractor textExtractor;
     private ChatAttachmentService service;
 
     @BeforeEach
     void setUp() {
         mapper = mock(ChatAttachmentMapper.class);
         indexer = mock(AttachmentDocIndexer.class);
-        service = new ChatAttachmentService(mapper, indexer, new ChatAttachmentProperties());
+        textExtractor = mock(TextExtractor.class);
+        service = new ChatAttachmentService(mapper, indexer, textExtractor, new ChatAttachmentProperties());
     }
 
     private static ChatAttachment att(long id, long userId, long caseId, long sessionId, String kind) {
@@ -135,6 +138,29 @@ class ChatAttachmentServiceTest {
         assertTrue(block.contains("12 片"), block);
     }
 
+    @Test
+    @DisplayName("图片内联块:标注 OCR 来源与字数(模型与用户都要知道这是识别文本)")
+    void imageBlockLabelsOcr() {
+        ChatAttachment a = att(60L, 1L, 1L, 1L, "IMAGE");
+        a.setInlineText("【图片 OCR 提取】\nPOLICE 2026 123");
+        a.setCharCount(24);
+        when(mapper.selectById(60L)).thenReturn(a);
+        String block = service.buildBlocks(List.of(60L), 1L, 1L, 1L, "问题").getFirst();
+        assertTrue(block.contains("图片, OCR 24 字"), block);
+    }
+
+    @Test
+    @DisplayName("音视频内联块:标注转写来源、字数与截断")
+    void mediaBlockLabelsTranscript() {
+        ChatAttachment a = att(61L, 1L, 1L, 1L, "MEDIA");
+        a.setInlineText("【音视频转写,时长 03:12,已截断】\n通话内容");
+        a.setCharCount(30);
+        a.setTruncated(1);
+        when(mapper.selectById(61L)).thenReturn(a);
+        String block = service.buildBlocks(List.of(61L), 1L, 1L, 1L, "问题").getFirst();
+        assertTrue(block.contains("音视频, 转写 30 字, 已截断"), block);
+    }
+
     @Test
     @DisplayName("处理失败的附件直接拒绝,不进消息")
     void failedAttachmentRejected() {

+ 69 - 0
ai-server/src/test/java/com/zsjz/ai/module/document/MediaTranscriberLiveTest.java

@@ -0,0 +1,69 @@
+package com.zsjz.ai.module.document;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+
+/**
+ * 真实音频转写(opt-in):需要本机的 ffmpeg 与 Vosk 模型,缺任何一项都跳过。
+ *
+ * <p>使用方式(音频路径通过环境变量传入,避免把测试音频提交进仓库):
+ * <pre>
+ * ASR_TEST_WAV=/path/to/speech.wav mvn -pl ai-server test -Dtest=MediaTranscriberLiveTest
+ * </pre>
+ * 默认在仓库根查找 {@code tools/ffmpeg/ffmpeg(.exe)} 与 {@code vosk-model/},
+ * 可用 {@code ASR_FFMPEG_PATH} / {@code ASR_MODEL_PATH} 覆盖。
+ */
+class MediaTranscriberLiveTest {
+
+    @Test
+    @DisplayName("真实音频:ffmpeg 解码 → Vosk 转写出非空文本并解析出时长")
+    void transcribesRealAudio() throws Exception {
+        String wav = System.getenv("ASR_TEST_WAV");
+        assumeTrue(wav != null && Files.isRegularFile(Path.of(wav)),
+                "未设置 ASR_TEST_WAV,跳过真实转写");
+        Path repo = Path.of(System.getProperty("user.dir")).toAbsolutePath().getParent();
+        Path ffmpeg = Path.of(System.getenv().getOrDefault("ASR_FFMPEG_PATH",
+                repo.resolve("tools/ffmpeg/ffmpeg").toString() + (isWindows() ? ".exe" : "")));
+        Path model = Path.of(System.getenv().getOrDefault("ASR_MODEL_PATH",
+                repo.resolve("vosk-model").toString()));
+        assumeTrue(Files.isRegularFile(ffmpeg), "未找到 ffmpeg: " + ffmpeg);
+        assumeTrue(Files.isDirectory(model.resolve("am")), "未找到 Vosk 模型: " + model);
+
+        AsrProperties props = new AsrProperties();
+        props.setFfmpegPath(ffmpeg.toString());
+        props.setModelPath(model.toString());
+        MediaTranscriber transcriber = new MediaTranscriber(props);
+        assumeTrue(transcriber.isAvailable(), transcriber.unavailableReason());
+
+        MediaTranscriber.Transcript transcript = transcriber.transcribe(Path.of(wav));
+
+        // 控制台编码在 Windows 上会把中文打成乱码,落一份 UTF-8 便于核对识别质量
+        Path dump = Path.of("target", "asr-transcript.txt");
+        Files.createDirectories(dump.getParent());
+        Files.writeString(dump, transcript.text());
+        System.out.println("ASR transcript file = " + dump.toAbsolutePath());
+        System.out.println("ASR duration   = " + transcript.durationSeconds() + "s");
+        assertFalse(transcript.text().isBlank(), "转写文本为空");
+        assertTrue(transcript.durationSeconds() > 0, "未从 ffmpeg 解析出时长");
+
+        // 再走一遍门面:验证「音视频」分支的正文标注(时长/截断)与字符上限
+        OcrProperties ocrProps = new OcrProperties();
+        TextExtractor extractor = new TextExtractor(ocrProps, new PpOcrEngine(ocrProps),
+                new PdfPageReader(ocrProps, new PpOcrEngine(ocrProps)), transcriber);
+        Path audio = Path.of(wav);
+        ExtractionResult result = extractor.extract(audio, audio.getFileName().toString(), "audio/wav", 100_000);
+        assertTrue(result.text().startsWith("【音视频转写,时长 "), result.text());
+        assertTrue(result.text().contains("登记") || result.text().contains("车辆"), result.text());
+    }
+
+    private static boolean isWindows() {
+        return System.getProperty("os.name", "").toLowerCase().contains("win");
+    }
+}

+ 49 - 0
ai-server/src/test/java/com/zsjz/ai/module/document/MediaTranscriberTest.java

@@ -0,0 +1,49 @@
+package com.zsjz.ai.module.document;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 音视频转写里的纯逻辑:Vosk 结果解析、ffmpeg 时长行解析、未配置时的降级原因。
+ * 真实音频的端到端验证需要 ffmpeg 与 Vosk 模型(离线资产),见 docs/design/ai-media-ocr-asr.md。
+ */
+class MediaTranscriberTest {
+
+    @Test
+    @DisplayName("Vosk 结果 JSON → 一行一段;空段丢弃,坏 JSON 不污染正文")
+    void appendVoskSegments() {
+        StringBuilder sb = new StringBuilder();
+        MediaTranscriber.appendSegment(sb, "{\"text\": \"你好 世界\"}");
+        MediaTranscriber.appendSegment(sb, "{\"text\": \"   \"}");
+        MediaTranscriber.appendSegment(sb, "{\"text\": \"第二段\"}");
+        MediaTranscriber.appendSegment(sb, "not-json");
+        MediaTranscriber.appendSegment(sb, null);
+        assertEquals("你好 世界\n第二段\n", sb.toString());
+    }
+
+    @Test
+    @DisplayName("ffmpeg 的 Duration 行解析成秒")
+    void parsesFfmpegDuration() {
+        assertEquals(192, MediaTranscriber.parseDuration(
+                "  Duration: 00:03:12.12, start: 0.000000, bitrate: 128 kb/s"));
+        assertEquals(3723, MediaTranscriber.parseDuration("Duration: 01:02:03.00"));
+        assertEquals(0, MediaTranscriber.parseDuration("Stream #0:0: Audio: pcm_s16le"));
+        assertEquals(0, MediaTranscriber.parseDuration(null));
+    }
+
+    @Test
+    @DisplayName("ffmpeg 未配置:不可用原因点名配置项")
+    void unavailableNamesConfigKey() {
+        AsrProperties props = new AsrProperties();
+        props.setFfmpegPath("/nonexistent/ffmpeg");
+        MediaTranscriber transcriber = new MediaTranscriber(props);
+
+        assertFalse(transcriber.isAvailable());
+        assertTrue(transcriber.unavailableReason().contains("ffmpeg-path"),
+                transcriber.unavailableReason());
+    }
+}

+ 183 - 0
ai-server/src/test/java/com/zsjz/ai/module/document/TextExtractorTest.java

@@ -0,0 +1,183 @@
+package com.zsjz.ai.module.document;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.PDPageContentStream;
+import org.apache.pdfbox.pdmodel.common.PDRectangle;
+import org.apache.pdfbox.pdmodel.font.PDType1Font;
+import org.apache.pdfbox.pdmodel.font.Standard14Fonts;
+import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import javax.imageio.ImageIO;
+import java.awt.Color;
+import java.awt.Font;
+import java.awt.Graphics2D;
+import java.awt.RenderingHints;
+import java.awt.image.BufferedImage;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+
+/**
+ * 文本提取门面的集成测试:真实 Tika、真实 PP-OCR(模型随 jar 内置)、真实 PDFBox。
+ *
+ * <p>OCR 相关用例用 {@code assumeTrue} 守卫:机器上没有 OpenCV 原生库(如非 x86_64 平台)时跳过,
+ * 而不是把整个构建拖红。
+ */
+class TextExtractorTest {
+
+    private final OcrProperties ocrProps = new OcrProperties();
+
+    private final PpOcrEngine ocrEngine = new PpOcrEngine(ocrProps);
+
+    private final PdfPageReader pdfPageReader = new PdfPageReader(ocrProps, ocrEngine);
+
+    private final AsrProperties asrProps = new AsrProperties();
+
+    private final MediaTranscriber mediaTranscriber = new MediaTranscriber(asrProps);
+
+    private final TextExtractor extractor = new TextExtractor(
+            ocrProps, ocrEngine, pdfPageReader, mediaTranscriber);
+
+    @Test
+    @DisplayName("普通文本文件仍走 Tika,内容原样返回")
+    void plainTextViaTika(@TempDir Path dir) throws Exception {
+        Path file = dir.resolve("说明.md");
+        Files.writeString(file, "# 标题\n车辆登记信息 2026", StandardCharsets.UTF_8);
+
+        ExtractionResult result = extractor.extract(file, "说明.md", "text/markdown", 10_000);
+
+        assertTrue(result.text().contains("车辆登记信息"), result.text());
+        assertFalse(result.truncated());
+    }
+
+    @Test
+    @DisplayName("图片 OCR:PP-OCR 能识别出图中数字")
+    void imageOcr(@TempDir Path dir) throws Exception {
+        assumeTrue(ocrEngine.isAvailable(), () -> "本地 OCR 不可用: " + ocrEngine.unavailableReason());
+        Path png = writeTextImage(dir.resolve("scan.png"), "POLICE 2026 123", latinFont());
+
+        ExtractionResult result = extractor.extract(png, "scan.png", "image/png", 10_000);
+
+        assertTrue(result.text().startsWith("【图片 OCR 提取】"), result.text());
+        assertTrue(result.text().replace(" ", "").contains("2026"), result.text());
+        assertTrue(result.text().replace(" ", "").contains("123"), result.text());
+    }
+
+    @Test
+    @DisplayName("中文图片 OCR:PP-OCRv4 能识别中文(选它替代 Tesseract 的主要原因)")
+    void chineseImageOcr(@TempDir Path dir) throws Exception {
+        assumeTrue(ocrEngine.isAvailable(), () -> "本地 OCR 不可用: " + ocrEngine.unavailableReason());
+        Font cjk = new Font("Microsoft YaHei", Font.BOLD, 56);
+        assumeTrue(cjk.canDisplay('车'), "本机没有中文字体,跳过");
+        Path png = writeTextImage(dir.resolve("cn.png"), "车辆登记信息 2026", cjk);
+
+        String text = extractor.extract(png, "cn.png", "image/png", 10_000)
+                .text().replace(" ", "");
+
+        assertTrue(text.contains("车辆") || text.contains("登记"), text);
+    }
+
+    @Test
+    @DisplayName("扫描件 PDF:无文本层的页走 OCR,并带页码标记")
+    void scannedPdfOcr(@TempDir Path dir) throws Exception {
+        assumeTrue(ocrEngine.isAvailable(), () -> "本地 OCR 不可用: " + ocrEngine.unavailableReason());
+        Path png = writeTextImage(dir.resolve("page.png"), "POLICE 2026 123", latinFont());
+        Path pdf = dir.resolve("扫描件.pdf");
+        try (PDDocument doc = new PDDocument()) {
+            PDPage page = new PDPage(PDRectangle.A4);
+            doc.addPage(page);
+            PDImageXObject image = PDImageXObject.createFromFile(png.toString(), doc);
+            try (PDPageContentStream cs = new PDPageContentStream(doc, page)) {
+                cs.drawImage(image, 72, 500, 400, 120);
+            }
+            doc.save(pdf.toFile());
+        }
+
+        ExtractionResult result = extractor.extract(pdf, "扫描件.pdf", "application/pdf", 100_000);
+
+        assertTrue(result.text().contains("[第1页]"), result.text());
+        assertTrue(result.text().contains("扫描件 PDF"), result.text());
+        assertTrue(result.text().replace(" ", "").contains("2026"), result.text());
+    }
+
+    @Test
+    @DisplayName("纯文本 PDF:不触发 OCR,也不带扫描件标注")
+    void textPdfSkipsOcr(@TempDir Path dir) throws Exception {
+        Path pdf = dir.resolve("digital.pdf");
+        try (PDDocument doc = new PDDocument()) {
+            PDPage page = new PDPage(PDRectangle.A4);
+            doc.addPage(page);
+            try (PDPageContentStream cs = new PDPageContentStream(doc, page)) {
+                cs.beginText();
+                cs.setFont(new PDType1Font(Standard14Fonts.FontName.HELVETICA), 14);
+                cs.newLineAtOffset(72, 700);
+                cs.showText("POLICE 2026 DIGITAL TEXT");
+                cs.endText();
+            }
+            doc.save(pdf.toFile());
+        }
+
+        ExtractionResult result = extractor.extract(pdf, "digital.pdf", "application/pdf", 100_000);
+
+        assertTrue(result.text().contains("[第1页]"), result.text());
+        assertTrue(result.text().contains("DIGITAL"), result.text());
+        assertFalse(result.text().contains("扫描件 PDF"), result.text());
+    }
+
+    @Test
+    @DisplayName("OCR 原生库不可用:给出可读原因,而不是 UnsatisfiedLinkError")
+    void ocrUnavailableHasReadableReason() {
+        OcrProperties broken = new OcrProperties();
+        broken.setOpencvLibPath("/nonexistent/opencv_java460.dll");
+        PpOcrEngine engine = new PpOcrEngine(broken);
+
+        assertFalse(engine.isAvailable());
+        String reason = engine.unavailableReason();
+        assertTrue(reason != null && reason.contains("opencv-lib-path"), reason);
+
+        BufferedImage image = new BufferedImage(10, 10, BufferedImage.TYPE_INT_RGB);
+        IllegalStateException e = assertThrows(IllegalStateException.class, () -> engine.recognize(image));
+        assertTrue(e.getMessage().contains("本地 OCR 未就绪"), e.getMessage());
+    }
+
+    @Test
+    @DisplayName("时长格式化")
+    void clockFormat() {
+        assertEquals("00:05", TextExtractor.clock(5));
+        assertEquals("03:12", TextExtractor.clock(192));
+        assertEquals("1:02:03", TextExtractor.clock(3723));
+    }
+
+    /** 生成白底黑字图片,模拟扫描件 */
+    private static Path writeTextImage(Path target, String text, Font font) throws Exception {
+        BufferedImage image = new BufferedImage(900, 240, BufferedImage.TYPE_INT_RGB);
+        Graphics2D g = image.createGraphics();
+        try {
+            g.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,
+                    RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
+            g.setColor(Color.WHITE);
+            g.fillRect(0, 0, image.getWidth(), image.getHeight());
+            g.setColor(Color.BLACK);
+            g.setFont(font);
+            g.drawString(text, 40, 150);
+        } finally {
+            g.dispose();
+        }
+        ImageIO.write(image, "png", target.toFile());
+        return target;
+    }
+
+    private static Font latinFont() {
+        return new Font(Font.SANS_SERIF, Font.BOLD, 64);
+    }
+}

+ 32 - 0
deploy/env.sh

@@ -164,6 +164,38 @@ ZSJZ_CHAT_ATTACHMENT_CHUNK_SIZE="1000"
 ZSJZ_CHAT_ATTACHMENT_CHUNK_OVERLAP="100"
 ZSJZ_CHAT_ATTACHMENT_MAX_CHUNKS="500"
 ZSJZ_CHAT_ATTACHMENT_TOP_K="8"
+ZSJZ_CHAT_ATTACHMENT_MAX_IMAGE_MB="30"
+ZSJZ_CHAT_ATTACHMENT_MAX_MEDIA_MB="200"
+
+# ---------------------------------------------------------------------------
+# zsjz.ocr(本地 PP-OCR:图片与扫描件 PDF)
+# 模型随 jar 分发,无需放置任何文件;OpenCV 原生库首次使用会释放到
+# {user.dir}/data/native/。Linux 要求 glibc ≥ 2.27(Ubuntu 18.04+/Debian 10+/Rocky 8+),
+# CentOS 7 不支持。要换 server 大模型时用 ZSJZ_OCR_*_MODEL_PATH 指定绝对路径。
+# ---------------------------------------------------------------------------
+ZSJZ_OCR_ENABLED="true"
+ZSJZ_OCR_TEXT_SCORE="0.5"
+ZSJZ_OCR_DET_LIMIT_SIDE_LEN="736"
+ZSJZ_OCR_PDF_DPI="200"
+ZSJZ_OCR_PAGE_MIN_CHARS="10"
+ZSJZ_OCR_MAX_PAGES="30"
+ZSJZ_OCR_TOTAL_BUDGET_SECONDS="240"
+# 非标准平台可手工指定 OpenCV 原生库(一般留空即可)
+ZSJZ_OCR_OPENCV_LIB_PATH=""
+
+# ---------------------------------------------------------------------------
+# zsjz.asr(音视频转写:ffmpeg 解码 + Vosk 识别)
+# 【按环境修改】ffmpeg 路径与模型目录。模型目录须含 am/ 与 conf/,
+#              下载与解压见 deploy/install-media-deps.sh。
+# Vosk jar 内置 x86_64 原生库;ARM64 服务器需改用 whisper.cpp 方案。
+# ---------------------------------------------------------------------------
+ZSJZ_ASR_ENABLED="true"
+ZSJZ_ASR_FFMPEG_PATH="/usr/bin/ffmpeg"
+ZSJZ_ASR_MODEL_PATH="/opt/zsjz-ai/vosk-model"
+ZSJZ_ASR_MAX_DURATION_SECONDS="600"
+ZSJZ_ASR_FFMPEG_TIMEOUT_SECONDS="600"
+ZSJZ_ASR_SAMPLE_RATE="16000"
+ZSJZ_ASR_MAX_CHARS="200000"
 
 # ---------------------------------------------------------------------------
 # zsjz.auth(登录安全)

+ 121 - 0
deploy/install-media-deps.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# ============================================================================
+# 媒体解析依赖安装(仅 Linux):ffmpeg + 中文字体 + Vosk 离线模型。
+#
+# OCR 不需要本脚本:PP-OCRv4 模型(det/cls/rec)随 rapidocr4j jar 分发,
+# OpenCV 原生库也在 openpnp:opencv jar 内,首次使用自动释放到 data/native/。
+# 本脚本只解决「音视频转写」的两项外部依赖。
+#
+# 用法:
+#   sudo bash deploy/install-media-deps.sh                 # 小模型(42MB,识别快)
+#   sudo bash deploy/install-media-deps.sh --model large   # 大模型(1.3GB,更准)
+#   sudo bash deploy/install-media-deps.sh --prefix /opt/zsjz-ai
+#
+# 幂等:已装包会跳过,模型目录已存在则不再下载。
+# 许可证:ffmpeg 用发行版仓库版本(Debian/Ubuntu 为 LGPL 构建);
+#        若要换静态包,商用请选 LGPL 变体(BtbN FFmpeg-Builds 的 lgpl 产物)。
+# ============================================================================
+set -euo pipefail
+
+PREFIX="${ZSJZ_PREFIX:-/opt/zsjz-ai}"
+MODEL_SIZE="small"
+MODEL_BASE="https://alphacephei.com/vosk/models"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --model) MODEL_SIZE="${2:-small}"; shift 2 ;;
+    --prefix) PREFIX="${2:-/opt/zsjz-ai}"; shift 2 ;;
+    -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+    *) echo "未知参数: $1" >&2; exit 2 ;;
+  esac
+done
+
+case "$MODEL_SIZE" in
+  small) MODEL_ZIP="vosk-model-small-cn-0.22.zip" ;;
+  large) MODEL_ZIP="vosk-model-cn-0.22.zip" ;;
+  *) echo "--model 只支持 small / large" >&2; exit 2 ;;
+esac
+
+MODEL_DIR="$PREFIX/vosk-model"
+
+log() { printf '\033[1;34m[media-deps]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[media-deps]\033[0m %s\n' "$*" >&2; }
+
+[[ "$(id -u)" -eq 0 ]] || { warn "需要 root(sudo)安装系统包"; exit 1; }
+
+# ---------------------------------------------------------------------------
+# 1. glibc 版本:OpenCV 原生库(PP-OCR 依赖)要求 ≥ 2.27
+# ---------------------------------------------------------------------------
+GLIBC_VER="$(ldd --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+' | head -1 || true)"
+if [[ -n "$GLIBC_VER" ]]; then
+  if printf '%s\n2.27\n' "$GLIBC_VER" | sort -V -C; then
+    log "glibc $GLIBC_VER OK(PP-OCR 的 OpenCV 原生库要求 ≥ 2.27)"
+  else
+    warn "glibc $GLIBC_VER 低于 2.27:图片/扫描件 OCR 无法运行(音视频转写不受影响)"
+  fi
+else
+  warn "无法检测 glibc 版本,跳过检查(若 OCR 报 UnsatisfiedLinkError,多半是这里)"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. 安装 ffmpeg 与中文字体
+# ---------------------------------------------------------------------------
+if command -v ffmpeg >/dev/null 2>&1; then
+  log "ffmpeg 已安装: $(command -v ffmpeg)"
+else
+  if command -v apt-get >/dev/null 2>&1; then
+    log "apt-get 安装 ffmpeg + fonts-noto-cjk + unzip"
+    export DEBIAN_FRONTEND=noninteractive
+    apt-get update -y
+    apt-get install -y ffmpeg fonts-noto-cjk unzip curl ca-certificates
+  elif command -v dnf >/dev/null 2>&1; then
+    log "dnf 安装 ffmpeg(需要 EPEL/RPM Fusion)+ 中文字体"
+    dnf install -y ffmpeg google-noto-sans-cjk-fonts unzip curl || {
+      warn "ffmpeg 安装失败:RHEL 系需要先启用 EPEL 与 RPM Fusion,或改用静态包"
+      warn "  静态包(商用选 LGPL):https://github.com/BtbN/FFmpeg-Builds/releases"
+      warn "  解压后把 ffmpeg 放到 $PREFIX/tools/ffmpeg/ffmpeg 并 chmod +x"
+    }
+  elif command -v yum >/dev/null 2>&1; then
+    log "yum 安装(老发行版)"
+    yum install -y ffmpeg google-noto-sans-cjk-fonts unzip curl || {
+      warn "ffmpeg 安装失败:请手工安装或改用静态包"
+    }
+  else
+    warn "未识别的包管理器:请手工安装 ffmpeg 与中文字体"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Vosk 中文模型(离线,一次下载)
+# ---------------------------------------------------------------------------
+if [[ -f "$MODEL_DIR/am/final.mdl" ]]; then
+  log "Vosk 模型已存在: $MODEL_DIR"
+else
+  mkdir -p "$PREFIX"
+  tmp="$(mktemp -d)"
+  trap 'rm -rf "$tmp"' EXIT
+  log "下载 $MODEL_ZIP($( [[ "$MODEL_SIZE" == large ]] && echo '约 1.3GB' || echo '约 42MB' ))"
+  curl -fL --retry 3 -o "$tmp/model.zip" "$MODEL_BASE/$MODEL_ZIP"
+  unzip -q "$tmp/model.zip" -d "$tmp"
+  rm -rf "$MODEL_DIR"
+  mv "$tmp/${MODEL_ZIP%.zip}" "$MODEL_DIR"
+  log "模型已解压到 $MODEL_DIR"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. 验证
+# ---------------------------------------------------------------------------
+log "验证:"
+command -v ffmpeg >/dev/null 2>&1 && ffmpeg -version | head -1 || warn "ffmpeg 不可用"
+[[ -d "$MODEL_DIR/am" && -d "$MODEL_DIR/conf" ]] && echo "  Vosk 模型结构 OK: $MODEL_DIR" \
+  || warn "Vosk 模型结构不完整(应含 am/ 与 conf/): $MODEL_DIR"
+
+cat <<EOF
+
+完成。把下面两项写进部署环境(deploy/env.sh 已有同名变量):
+  ZSJZ_ASR_FFMPEG_PATH="$(command -v ffmpeg || echo /usr/bin/ffmpeg)"
+  ZSJZ_ASR_MODEL_PATH="$MODEL_DIR"
+
+未安装/不想启用音视频转写时,设 ZSJZ_ASR_ENABLED="false",
+音视频上传会直接拒绝,其他文件类型不受影响。
+EOF

+ 246 - 0
docs/design/ai-media-ocr-asr.md

@@ -0,0 +1,246 @@
+# 图片 / 扫描件 / 音视频解析(本地 OCR + 本地转写)
+
+> 覆盖:对话附件(`module/agent/attachment`)与知识库(`module/knowledge`)。
+> 代码:`ai-server/src/main/java/com/zsjz/ai/module/document/`。
+> 配置:`zsjz.ocr` / `zsjz.asr`(见 `application.yaml`)。
+
+---
+
+## 1. 能力边界
+
+| 输入 | 处理 | 依赖 |
+|---|---|---|
+| 文本类文档(txt/docx/pptx/html/eml…) | Tika 提取(行为与改造前一致) | 无 |
+| PDF(有文本层) | PDFBox 逐页取文本 + `[第N页]` 标记,**不 OCR** | 无 |
+| PDF(扫描件/混合) | 缺文本的页渲染 200DPI 位图交 PP-OCR | 无(模型在 jar 内) |
+| 图片(jpg/png/bmp/gif/tif/tiff) | PP-OCRv4 识别(多页 TIFF 逐帧) | 无(模型在 jar 内) |
+| 音视频(mp3/wav/m4a/aac/flac/ogg/opus/wma/amr/mp4/mov/mkv/avi/flv/wmv/webm/mpg/mpeg) | ffmpeg 解码 16k 单声道 → Vosk 转写 | **ffmpeg + Vosk 模型** |
+| 压缩包 / 加密文件 / webp / 未知二进制 | 拒绝(上传即 400 或附件行 FAILED) | — |
+
+不做:压缩包解压、图片视觉理解(多模态描述)、视频画面 OCR、表格结构还原(图片表格只出文字)、语种自动检测。
+
+---
+
+## 2. 结构
+
+```
+TextExtractor(门面,按后缀/MIME 分派)
+├─ Tika AutoDetectParser        普通文档
+├─ PdfPageReader + PpOcrEngine  PDF 逐页判定
+├─ PpOcrEngine                  图片 OCR(PP-OCRv4)
+└─ MediaTranscriber             音视频转写(ffmpeg + Vosk)
+```
+
+提取结果在正文第一行写入来源标注,随 sidecar 落库,模型和用户都能看出内容来源与截断事实:
+
+- `【图片 OCR 提取】`
+- `【扫描件 PDF:已 OCR 3 页;另有 2 页因页数/时间预算未识别】`
+- `【音视频转写,时长 03:12,已截断】`
+
+**没有新增表字段**:`chat_attachment.kind` 增加 `IMAGE` / `MEDIA` 两个取值;时长、页数等信息只存在于正文标注里。
+
+---
+
+## 3. OCR:为什么选 PP-OCR,怎么落地
+
+### 3.1 选型对比
+
+| 方案 | Linux | Windows | 结论 |
+|---|---|---|---|
+| **PP-OCRv4(rapidocr4j)** | 纯 jar,无系统依赖 | 纯 jar | **采用**。模型(det 4.7MB / cls 0.6MB / rec 10.9MB)打在 jar 里,运行期零下载;中文精度最好 |
+| Tess4J + Tesseract | 需 `libtesseract-dev` + `libleptonica-dev`(无版本号 `.so` 软链) | 需 MSVC 2015-2022 运行库 | 否掉:两平台各自的系统依赖,且中文精度一般 |
+| `mymonstercat:rapidocr-onnx-platform` | 原生 jar 由 **Maven OS profile** 选入 | 同左 | 否掉:Windows 上构建的产物不含 Linux 原生库,部署即挂 |
+
+`rapidocr4j` 只调用 ONNX Runtime 的公开 API(`OrtEnvironment`/`OrtSession`/`OnnxTensor`),
+我们把 pom 里 `onnxruntime` 排除后统一用项目已钉的 **1.30.0**(已逐一核对所用方法在 1.30 存在)。
+OpenCV 原生库来自 `org.openpnp:opencv:4.6.0-0`:**一个 103MB jar** 内含
+`windows/x86_64`、`linux/x86_64`、`linux/ARMv8`、`linux/ARMv7`、macOS,
+所以 Windows 上构建、Linux 上运行是同一份产物。
+
+### 3.2 两个实现细节
+
+- **OpenCV 原生库自己落盘**:Java ≥ 12 时 `OpenCV.loadShared()` 的反射被模块系统拦住,
+  openpnp 会回退到「每次启动把 63MB 的 `.so/.dll` 解压到临时目录」。
+  `PpOcrEngine` 改为从依赖 jar 抽出到 `{user.dir}/data/native/`,只做一次,
+  再通过 `OcrConfig.Global.setOpencvLibPath()` 显式加载。
+- **串行执行**:引擎内部 det/cls/rec 共享缓冲区、非线程安全;`PpOcrEngine` 用锁串行化,
+  吞吐约 1 页/秒级。需要更高吞吐时再改引擎池(上传/索引都是单文档流程,当前够用)。
+
+### 3.3 扫描件 PDF 的判据
+
+- 页文本 `strip().length() < page-min-chars`(默认 10)才视为「无文本层」→ 渲染 + OCR;
+- OCR 结果只有比文本层更长才替换:短文本页保留矢量文字(更可靠);
+- `max-pages`(默认 30)只约束 **OCR 页数**,文本层仍按字符上限走完全部页 ——
+  不会把 500 页的文本 PDF 截到 30 页;
+- `total-budget-seconds`(默认 240)到点后剩余无文本页跳过并标注;
+- PDFBox 整体失败(加密、结构损坏)回退 Tika,失败信息由 Tika 侧给出。
+
+### 3.4 可选的更高精度
+
+默认用移动端 PP-OCRv4。扫描质量差、字小、表格密集时,可换成 PP-OCRv4 **server** 大模型
+(det ≈ 113MB、rec ≈ 90MB):把 `.onnx` 放到部署机,配置
+`zsjz.ocr.det-model-path` / `rec-model-path` 为绝对路径;若模型不含 `character` metadata,
+再补 `rec-keys-path`(`ppocr_keys_v1.txt`)。
+
+---
+
+## 4. 音视频:为什么不能只靠 Tika
+
+已核对 Tika 3.3.1:
+
+- **没有** `FFmpegParser`/`FFmpegConfig`(`tika-parser-audiovideo` 只有 `AudioParser`、
+  `Mp3Parser`、`MP4Parser`、`FLVParser`);
+- `AudioParser` 对 wav/aiff **只出元数据,正文为空**;
+- 标准包里没有任何语音转写实现(Tika 的转写桥只有云端 Amazon Transcribe,且不在标准包)。
+
+Tika 里唯一和 ffmpeg 有关的是 `CompositeExternalParser` 的**外部命令探测**:
+`new Tika()` → `TikaConfig` → `DefaultParser` → ServiceLoader 实例化它 →
+读 tika-core 内置的 `tika-external-parsers.xml` → 依次 `ffmpeg -version`、`exiftool -ver`、
+`sox --version`。缺命令时 JDK 抛的 `Cannot run program "ffmpeg"` 被 Tika 以 **DEBUG** 吞掉,
+不影响功能;root logger 是 debug 时启动日志里能看到。
+
+所以音频解码必须自己调 ffmpeg,识别用本地 Vosk:
+
+```
+ffmpeg -hide_banner -nostdin -i <file> -vn -sn -dn -ac 1 -ar 16000 \
+       -acodec pcm_s16le -f s16le -t <max-duration-seconds> pipe:1
+        │ stdout = 16k 单声道 PCM(不落临时文件)
+        ▼
+Vosk Recognizer.acceptWaveForm(byte[], len) → 每段 final 结果一行
+```
+
+- stderr 用独立虚拟线程排空(不排空会把 ffmpeg 卡在写缓冲上),并从中解析 `Duration:`;
+- 进程超时 `destroyForcibly`;`-t` 先把超长音频截断,避免上传请求被挂住;
+- Vosk `Model` 懒加载单例(小模型约 300MB 内存),`@PreDestroy` 关闭;
+- 转写无标点(模型特性),按 final 段换行提升可读性。
+
+---
+
+## 5. 配置项
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `zsjz.ocr.enabled` | true | 关闭后图片/扫描件上传拒绝 |
+| `zsjz.ocr.opencv-lib-path` | 空 | 空 = 从 jar 释放到 `data/native/` |
+| `zsjz.ocr.text-score` | 0.5 | 单行识别置信度下限 |
+| `zsjz.ocr.det-limit-side-len` | 736 | 检测模型最小边 |
+| `zsjz.ocr.max-side-len` | 2000 | 单图 OCR 最大边 |
+| `zsjz.ocr.image-max-pixels` | 40000000 | 超像素先等比缩小 |
+| `zsjz.ocr.det/cls/rec-model-path` | 空 | 空 = jar 内置模型 |
+| `zsjz.ocr.rec-keys-path` | 空 | 换外部模型时补字典 |
+| `zsjz.ocr.pdf-dpi` | 200 | 扫描页渲染 DPI |
+| `zsjz.ocr.page-min-chars` | 10 | 少于该值视为无文本层 |
+| `zsjz.ocr.max-pages` | 30 | 单文件最多 OCR 页数 |
+| `zsjz.ocr.total-budget-seconds` | 240 | OCR 时间预算 |
+| `zsjz.asr.enabled` | true | 关闭后音视频上传拒绝 |
+| `zsjz.asr.ffmpeg-path` | 空 | 空 = `tools/ffmpeg/ffmpeg(.exe)` → PATH |
+| `zsjz.asr.model-path` | `vosk-model` | Vosk 模型目录 |
+| `zsjz.asr.max-duration-seconds` | 600 | 单文件最多转写时长 |
+| `zsjz.asr.ffmpeg-timeout-seconds` | 600 | ffmpeg 总超时 |
+| `zsjz.asr.sample-rate` | 16000 | 必须与模型一致 |
+| `zsjz.asr.max-chars` | 200000 | 转写文本上限 |
+| `zsjz.chat-attachment.max-image-mb` / `max-media-mb` | 30 / 200 | 上传大小上限 |
+| `zsjz.knowledge.max-media-mb` | 200 | 知识库音视频上限 |
+
+---
+
+## 6. 部署
+
+### Windows(开发机)
+
+1. 不需要任何 OCR 资产(模型随 Maven 依赖下发)。
+2. ffmpeg:`winget install Gyan.FFmpeg`,或把 `ffmpeg.exe` 放到仓库根 `tools/ffmpeg/`。
+3. Vosk 模型:下载 `vosk-model-small-cn-0.22.zip`(42MB)解压到仓库根 `vosk-model/`
+   (dev/pro profile 已把 `zsjz.asr.model-path` 指到 `E:/workspace/zsjz-ai/vosk-model`)。
+4. 大模型 `vosk-model-cn-0.22.zip`(1.3GB)更准,改 `ZSJZ_ASR_MODEL_PATH` 即可。
+
+### Linux(部署机)
+
+```bash
+sudo bash deploy/install-media-deps.sh              # 小模型
+sudo bash deploy/install-media-deps.sh --model large
+```
+
+脚本做四件事:检测 glibc、装 `ffmpeg` + `fonts-noto-cjk`、下载解压 Vosk 模型到
+`/opt/zsjz-ai/vosk-model`、验证。环境变量(`deploy/env.sh` 已含):
+
+```bash
+ZSJZ_ASR_FFMPEG_PATH="/usr/bin/ffmpeg"
+ZSJZ_ASR_MODEL_PATH="/opt/zsjz-ai/vosk-model"
+```
+
+系统要求:
+
+- **glibc ≥ 2.27**(OpenCV 原生库;Ubuntu 18.04+/Debian 10+/Rocky 8+ 满足,CentOS 7 不行);
+- Windows 需要 **VC++ 2015-2022 运行库**(`vcruntime140.dll`,绝大多数机器已有;缺失时 OCR 会报
+  `本地 OCR 未就绪:UnsatisfiedLinkError ...`,装运行库即可);
+- ffmpeg 可执行(发行版仓库版即可;静态包商用请选 LGPL 变体);
+- 中文字体(`fonts-noto-cjk`)—— 扫描页是位图不需要,但矢量文字页渲染更稳。
+
+离线环境:三个资产都是本地目录/单个二进制,直接从同版本联网机器拷贝
+(`/opt/zsjz-ai/vosk-model`、ffmpeg、`deploy/install-media-deps.sh` 里对应的 apt 包)。
+
+---
+
+## 7. 降级矩阵
+
+| 情况 | 行为 |
+|---|---|
+| OpenCV 原生库加载失败 / glibc 过低 / 模型文件缺失 | 图片、扫描件上传失败,消息为 `本地 OCR 未就绪:<具体原因>`;文本类 PDF 照常提取 |
+| ffmpeg 缺失 / Vosk 模型目录缺失 | 音视频上传失败,消息点名 `zsjz.asr.ffmpeg-path` / `zsjz.asr.model-path` |
+| `enabled=false` | 对应类型回到「后缀不在白名单即拒绝」 |
+| 页数/时长/字符超限 | 截断 + `truncated=1` + 正文标注,不静默丢内容 |
+| 加密 PDF | PDFBox 失败 → 回退 Tika → 现有「提取失败」路径 |
+| ffmpeg 进程超时 | `destroyForcibly`,附件行 FAILED,原因可读 |
+
+---
+
+## 8. 已知限制
+
+1. OCR 串行,30 页扫描件约 30~60 秒(`max-pages` / 预算可调)。
+2. Vosk 输出无标点,中文小模型准确率中等;要更好效果切大模型,或后续换 whisper.cpp。
+3. Vosk jar 内置 **x86_64** 原生库(win/linux/mac);**Linux ARM64 未内置**,
+   ARM 部署需改用外部 ASR 程序(`MediaTranscriber` 的「外部可执行 + 模型目录」抽象可复用)。
+4. **JNA 字符串编码**:Vosk 通过 JNA 把 native 返回的 UTF-8 JSON 转成 `String`;中文 Windows 上
+   JNA 默认按 `sun.jnu.encoding`(GBK)解码,中文会变成「杞﹁締」式乱码。`MediaTranscriber`
+   在加载模型前把 `jna.encoding` 钉成 UTF-8(运维已显式设置时不覆盖)。因为这是全局属性,
+   依赖 `char*` 路径的 `CellDll`(基站库)用 `Library.OPTION_STRING_ENCODING` 单独钉回平台编码,
+   两边互不影响。
+5. 中文小模型对专有名词/车牌字母的准确率有限(实测「京A」被识别成「经纬」、「张伟」被拆成「将 为」),
+   业务上要精确到号牌时建议切大模型或结合上下文人工核对。
+6. 首次 OCR 会从 jar 释放 OpenCV 原生库(约 51MB Windows / 63MB Linux),只发生一次。
+7. 音视频是同步提取:10 分钟音频约 1~2 分钟出结果(与机器 CPU 相关)。
+8. 手机照片的 EXIF 旋转未处理(ImageIO 不读 EXIF),横拍证件可能识别效果差;
+   可在上传前旋转,或后续加 metadata-extractor 支持。
+
+---
+
+## 9. 测试与验证
+
+```bash
+mvn -pl ai-server test -Dtest='TextExtractorTest,MediaTranscriberTest,AttachmentContentRouterTest,ChatAttachmentServiceTest'
+```
+
+- `TextExtractorTest`:真实 Tika 回归、真实 PP-OCR(生成图片/扫描 PDF 断言识别结果)、
+  纯文本 PDF 不触发 OCR、OCR/ASR 不可用时的可读报错;
+- OCR 用例用 `assumeTrue` 守卫,非 x86_64 平台自动跳过而不是把构建拖红。
+- 真实音频转写是 opt-in:`ASR_TEST_WAV=/path/to/speech.wav mvn -pl ai-server test -Dtest=MediaTranscriberLiveTest`
+  (默认在仓库根找 `tools/ffmpeg/ffmpeg(.exe)` 与 `vosk-model/`,可用 `ASR_FFMPEG_PATH` / `ASR_MODEL_PATH` 覆盖;
+  转写文本会落到 `ai-server/target/asr-transcript.txt`,方便核对中文编码与识别质量)。
+
+### 实测记录(2026-10-30,Windows / vosk-model-small-cn-0.22 / BtbN ffmpeg LGPL)
+
+| 用例 | 结果 |
+|---|---|
+| 中文文字图片(“车辆登记信息 2026”) | 识别出「车辆」「登记」等中文 |
+| 英文数字图片(“POLICE 2026 123”) | `2026`、`123` 命中 |
+| 图片嵌 PDF(A4 扫描页) | 输出 `[第1页]` + OCR 文本,头部标注「已 OCR 1 页」 |
+| 纯文本 PDF | 走文本层,不触发 OCR、无扫描件标注 |
+| 中文 TTS 语音(“车辆登记信息,车牌号码是京A一二三四五,车主姓名张伟。”) | 转写为「车辆 登记 信息 车牌 号码 是 经纬 一二三四五 车主 姓名 将 为」,时长解析 7s,正文头「【音视频转写,时长 00:07】」 |
+
+手工验证:
+
+1. 传一张手机截图 / 扫描件 PDF → 附件 chip 显示字数,模型回答能引用图中文字;
+2. 传一段中文录音(mp3)→ 转写文本进入上下文,标注含时长;
+3. 把 `zsjz.ocr.opencv-lib-path` 指向不存在文件 → 图片上传报 `本地 OCR 未就绪`;
+4. 知识库里上传扫描件 PDF → 文档列表 `READY`,`char_count` 明显大于 0。

+ 5 - 5
sql/chat_attachment.sql

@@ -2,13 +2,13 @@
 -- 对话附件(module/agent/attachment)元数据表
 --
 -- 落在 **master PG**(与 chat/message 管理表同库)。附件问答三路的登记与归属锚点:
---   A 内联     小文档/小表格 → 提取文本进消息
+--   A 内联     小文档/小表格/图片 OCR/短转写 → 提取文本进消息
 --   B Python   大表格 → 流式扫描(行数/表头/样本),Agent 用 execute_python 直读文件
---   C RAG      大文档 → sidecar 全文 + 分块向量化(chat_att_vec_{caseId}_d{dims})
+--   C RAG      大文档/长转写 → sidecar 全文 + 分块向量化(chat_att_vec_{caseId}_d{dims})
 --
 -- 隔离:user_id/case_id/session_id 三重归属,loadForSession 校验不过即拒绝;
 -- 向量侧另按会话过滤(payload 里带 sessionId,检索 SQL 强制 WHERE)。
--- 设计文档:输入框附件问答设计(2026-09)
+-- 设计文档:输入框附件问答设计(2026-09)、docs/design/ai-media-ocr-asr.md
 -- ============================================================================
 
 create table if not exists chat_attachment
@@ -19,9 +19,9 @@ create table if not exists chat_attachment
     session_id      bigint       not null,                 -- 归属会话(加载校验 + RAG 检索过滤)
     file_name       varchar(500) not null,                 -- 原始文件名(展示用)
     file_path       varchar(1000) not null,                -- 原件落盘路径(路径 B 的 execute_python 读它)
-    sidecar_path    varchar(1000),                         -- 衍生文本:文档全文 .txt / xlsx 转 .csv
+    sidecar_path    varchar(1000),                         -- 衍生文本:全文 .txt / xlsx 转 .csv
     mime            varchar(100),                          -- Tika 探测的 MIME
-    kind            varchar(20)   not null,                -- DOCUMENT / TABLE / UNSUPPORTED
+    kind            varchar(20)   not null,                -- DOCUMENT / TABLE / IMAGE / MEDIA / UNSUPPORTED
     size_bytes      bigint       default 0,
     char_count      integer      default 0,                -- 提取文本字符数(文档)
     row_count       integer      default 0,                -- 数据行数(表格,不含表头)