PDF and Tika

PDF and Tika / PDF 与 Tika

← Wiki home / 手册首页 · English · 中文 · Tika 手动安装 · Troubleshooting / 故障排查

Use this page when / 适用情况： adding PDF or Tika directories, checking parser/runtime readiness, building extension indexes, or safely removing an extension source.
添加 PDF 或 Tika 目录、检查解析器与运行时状态、建立扩展索引，或安全移除扩展来源。

English

Separate extension indexes

Markdown, PDF, and Tika-backed sources keep separate index/state boundaries. Query results can be fused, but each result retains a source-family label so users can distinguish notes from external evidence.

PDF sources

PDF indexing works at page or document-derived chunk boundaries. Preflight reads lightweight metadata and page structure before a full build. Scanned PDFs without an embedded text layer may need OCR outside Caelune before useful retrieval is possible.

Tika sources

Apache Tika exposes a large catalog of file extensions. The catalog is a selection surface, not a guarantee that every file with every listed suffix will parse perfectly.

Compatibility depends on:

• the real file format matching its extension
• encryption or password protection
• corruption or incomplete downloads
• parser support in the active Tika version
• embedded objects and unusual vendor variants

Start with the formats you actually need instead of enabling the entire catalog.

Runtime

Tika uses its own Java/Tika sidecar under the active data root. Prefer installation and detection from the application UI.

If automatic installation fails because of network restrictions, see Tika 手动安装. Do not place the Tika JAR or JRE beside the main EXE unless the application explicitly reports that location.

Responsive directory actions

Preflight, build, removal, and summary refresh work run in background task paths so long extension operations do not block the Qt interface. The UI may briefly reconcile source state after a task finishes.

Removing a source

Removing a PDF/Tika source clears the app-owned extension index/state for that source and removes it from extension settings. It must not delete the original external folder or documents.

If a removal task is cancelled or fails, the source should remain registered instead of being silently dropped.

Good first test

1. Add a small directory with two or three representative files.
2. Run preflight and review the detected format/page information.
3. Build the source.
4. Search for a phrase known to exist.
5. Verify the result source and page/document identity.
6. Only then add a larger archive.

中文

独立扩展索引

Markdown、PDF 和 Tika 来源各自保留独立的索引与状态边界。查询时可以融合结果，但每条结果仍带有来源类型，方便区分个人笔记和外部资料证据。

PDF 来源

PDF 会按页面或从文档提取出的片段建库。预检会先读取轻量元信息和页结构，再进入完整建库。没有内嵌文字层的扫描 PDF，通常需要先在星野之外完成 OCR 才能得到有效检索内容。

Tika 来源

Apache Tika 会暴露大量扩展名目录，但“出现在格式选择器中”不代表每个同后缀文件都保证完美解析。

实际兼容性取决于：

• 文件真实格式是否与扩展名一致
• 是否加密或有密码
• 文件是否损坏或下载不完整
• 当前 Tika 版本的解析器支持
• 嵌入对象和特殊厂商变体

建议只启用实际需要的格式，不要一开始就选中全部目录。

运行时

Tika 使用当前数据目录下独立的 Java/Tika 组件。优先通过软件界面完成安装和检测。

如果自动安装受网络限制，请看 Tika 手动安装。除非软件明确显示该位置，否则不要把 Tika JAR 或 JRE 放在主 EXE 旁边。

不阻塞界面的目录操作

预检、建库、移除和摘要刷新通过后台任务执行，较长的扩展格式操作不应堵塞 Qt 界面。任务完成后界面可能短暂进行一次来源状态同步。

移除来源

移除 PDF/Tika 来源时，会清理该来源在软件内部的扩展索引和状态，并从扩展设置中移除；不能删除外部原始目录或文档。

如果移除任务取消或失败，来源应继续保留，不能在任务未完成时悄悄从设置中消失。

建议的第一次测试

1. 添加只包含两三个代表性文件的小目录。
2. 执行预检并检查格式、页数等信息。
3. 建立扩展索引。
4. 搜索文件中明确存在的一句话。
5. 确认结果来源和页码/文档身份。
6. 小范围验证通过后再加入大型资料目录。

---

Previous / 上一篇： ← Search and Resources / 查询与资源 · Next / 下一篇： MCP Integration / MCP 接入 →