Skip to content

UsageGuide.md

Latest commit

 

History

History
237 lines (164 loc) · 10.2 KB

UsageGuide.md

File metadata and controls

237 lines (164 loc) · 10.2 KB
Raw

DocFinder — Usage Guide

Local file name & content search. Fast, read‑only, and multilingual.

UI is English. This guide explains how to use it (中文说明穿插其间)。

1) Quick Start

  1. Add folders: File → Manage Sources… → Add…. The Type column shows Local / Network (自动检测，可手动改)。
  2. Build index: File → Index All Sources（或 Rebuild Index (Full) 做一次全量重建）。
  3. Search: 在顶部搜索框输入关键词或语法（见下文）。
  4. Open files: 双击或按 Enter。右键可打开菜单；右侧预览面板显示文本内容（只读）。

索引与解析是只读的（read‑only），不会修改文件时间戳或内容；解析有超时保护。

2) Search Basics（搜索）

  • 直接输入会在 文件名（name）+ 内容（content） 中检索：
    • kubernetes → 命中文件名或正文。
  • 字段搜索（Fielded）：
    • Filename only: name:設計，name:"チェックリスト_07.xlsx"
    • Content only: content:"zero knowledge"
  • 通配符（Wildcard，用于文件名）：
    • name:*.xlsx、name:report-??.pdf、name:"2024* report?.docx"
    • 同时会自动添加 ext: 过滤以加速 *.ext 的检索。
  • 允许 前导通配（*.xlsx），也可直接输入 *.xlsx（无字段时默认当作文件名通配）。
  • 多语言支持：英文（Standard）、中文（SmartChinese）、日文（Kuromoji）。

精确匹配通过不分词字段 name_raw 实现；若升级后首次使用 name: 搜不到，请执行一次 Rebuild Index (Full) 以重建索引。

3) Filters（过滤）

  • Extension: 选择一个或多个文件扩展名（如 pdf, docx, xlsx, md）。
  • Time range: 按最后修改时间范围（mtime）过滤。

4) Results & Preview（结果与预览）

  • 表格列：Name, Path, Size, Created, Last Accessed, Match（name / content / name + content）。
  • Size 列右对齐，并按真实字节数进行数值排序（不是按字符串排序）；显示会自动换算为 KB/MB/GB。
  • 预览窗（右侧）：默认宽度约为窗口的 1/4（可拖拽调整）。
  • 预览开关：状态栏右侧的 👁 按钮可快速显示/隐藏。
  • 编码提示：预览会自动检测常见编码（UTF-8/UTF-16、Shift-JIS、GBK、Big5、EUC-KR 等），多语言混排文件也尽量兼容。
  • 右键菜单：Open, Open With…（记住上次选择）, Reveal in Explorer/Finder, Show Properties（高级检索详情）, Copy Path, Copy Name 等。
  • 快捷键：
    • Enter：Open
    • Ctrl+C：Copy Path
    • Ctrl+Shift+C：Copy Name

5) Manage Sources（数据源）

  • File → Manage Sources…：
    • Add…：选择文件夹。
    • Type：Local / Network（自动检测，后台异步刷新；可手动修改）。
    • Re-detect Type：重新检测所有行。
    • OK：保存到 ./.docfinder/sources.txt（格式：path|0/1，1=Network）。

Windows 下支持 UNC（\\server\share）与映射盘（如 J:\、M:\）；检测通过 PowerShell Get-PSDrive、net use、wmic 等并做缓存。

6) Building / Updating Index（建立与更新索引）

  • Index All Sources：对所有源进行索引/更新。
  • Rebuild Index (Full)：清空并重建（字段结构变更后建议执行一次）。
  • Indexing Settings…：调整解析上限、超时和 include/exclude 规则（含 maxExtractChars 与 textMaxBytes）。
  • Read‑only parsing（只读解析）：使用 Apache Tika，带超时与大小上限；文本类文件通过扩展名、MIME 与启发式判定，未知扩展名但可识别为文本也会尝试索引。

文本判定：首 4KB 无 NUL 且可打印 ASCII 比例高（≥0.85）。

7) Live Updates（实时与轮询）

  • Live Watch（本地）：对 Local 源使用 OS WatchService 增量更新。
  • Network Polling（网络）：对 Network 源按间隔轮询；
    • Poll Network Sources Now：立即轮询，后台执行，不会阻塞 UI；完成后状态栏显示统计（scanned/created/modified/deleted）。

配置轮询间隔见设置；Live Watch 与 Polling 可独立开关。

8) Global Hotkey & Tray（全局热键与托盘）

  • Global Hotkey：使用 jnativehook 注册；默认唤起/隐藏主窗口（具体组合键见代码/设置）。
  • System Tray：托盘图标支持点击/菜单，快速进入主要功能（Windows/macOS/Linux）。

9) Web Interface & Document Preview（网页界面与文档预览）

9.1) Web Server

DocFinder 提供了内置的 HTTP 服务器，允许通过浏览器访问搜索界面。

  • 启用 Web Server：File → Enable Web Server（勾选菜单项即启动服务器）
  • 打开 Web 界面：File → Open Web Interface…（在默认浏览器中打开）
  • 默认端口：7070（可在配置文件中修改）
  • 访问地址：http://127.0.0.1:7070

Web 界面功能与桌面应用基本一致，支持搜索、过滤、预览等核心功能。

9.2) Document Preview Engines

DocFinder 支持两种文档预览引擎，可在 Web 界面中切换：

JitViewer (默认)

  • 轻量级 JavaScript 文档预览库
  • 支持常见格式：PDF、Office 文档（Word、Excel、PowerPoint）、图片等
  • 纯客户端渲染，无需额外服务器
  • 适合快速预览简单文档

kkFileView

  • 功能强大的 Java 文档预览服务器
  • 支持更多文档格式和更好的渲染质量
  • 支持复杂文档：加密 PDF、复杂 Office 文档、CAD 文件等
  • 需要单独启动 kkFileView 服务器

9.3) Using kkFileView

  1. 下载 kkFileView JAR：

  2. 启用 kkFileView：

    • File → Enable kkFileView Server（勾选菜单项即启动服务器）
    • 默认端口：8012（可在配置文件中修改）
    • 启动需要几秒钟时间

  3. 在 Web 界面中切换预览引擎：

    • 点击搜索栏中的 📄J（JitViewer）或 📄K（kkFileView）按钮切换
    • 切换后当前预览会自动刷新
    • 设置会自动保存

注意事项：

  • kkFileView 需要较多内存（建议 2GB+ 可用内存）
  • 首次预览某类文档时可能需要加载额外的依赖
  • 如果预览失败，请确保 kkFileView 服务器已启动（查看日志）
  • 支持的文档格式详见 kkFileView 官方文档

9.4) API Endpoints

Web Server 提供以下 API 端点：

  • GET /api/search - 搜索查询
  • GET /api/file - 获取文件内容
  • GET /api/viewer - 获取当前预览引擎设置
  • POST /api/viewer - 设置预览引擎（{"viewer":"kkfileview"} 或 {"viewer":"jitviewer"}）
  • GET /api/kkfileview/* - kkFileView 代理端点

10) Tips & Notes（贴士）

  • Japanese Windows（¥ 路径）：内部路径已规范化；打开前会转换为 Explorer 可识别的形式。
  • 文件名中的全角斜杠 ／ 会被保留，不会被替换成目录分隔符。
  • Performance：为 *.ext 的通配增加了 ext MUST 过滤；可适度调整索引的 RAM buffer 与并发。
  • Privacy：所有数据均在本地，索引与解析均为只读。
  • Query History：下拉保留最近 100 条查询，持久化保存。
  • 从历史记录中选择查询时，会重新执行一次检索（不是结果缓存回放）。

11) Troubleshooting（排障）

  • name:チェックリスト_07.xlsx 无结果：
    • 确认索引包含 name_raw 字段；执行 Rebuild Index (Full)。
  • “Manage Sources…” 打开慢：
    • 新版已后台检测 Local/Network；若仍卡顿，请确认已更新到最新构建。
  • “Poll Network Sources Now” 无变化：
    • 确认该源被标记为 Network，并具备访问权限；网络设备可能存在索引延迟。
  • 内容预览为空：
    • 可能超时/文件过大/格式不受支持；可提升超时或加入扩展名白名单。
  • kkFileView 预览失败：
    • 确认 kkFileView JAR 已放置在正确位置（~/.docfinder/kkfileview/kkFileView.jar）
    • 确认 kkFileView 服务器已启动（查看 Help → View Log）
    • 检查系统内存是否充足（kkFileView 需要 2GB+ 可用内存）

12) Keyboard Shortcuts（快捷键总览）

  • Enter：Open selected item
  • Ctrl+C：Copy Path
  • Ctrl+Shift+C：Copy Name
  • （更多全局热键见设置/源码）

13) Data Locations（数据位置）

  • Index: ./.docfinder/index/
  • Sources: ./.docfinder/sources.txt（path|0/1）
  • Query history & app settings: ./.docfinder/…
  • kkFileView JAR: ~/.docfinder/kkfileview/kkFileView.jar

14) FAQ

Q: 会修改文件吗？

不会。索引读取使用只读句柄，Tika 解析有超时保护，不会触碰内容或修改时间戳。

Q: 支持哪些文件类型？

常见文档（pdf/docx/xlsx/pptx/html/txt/markdown 等）与大量文本类（json/yaml/xml/java/go/rs/py/js 等）。可通过设置扩展 allowlist/文本类判定扩展。

Q: Office（Excel/Word/PPT）里的文本框内容能被抽取吗？

一般情况下 Tika/POI 会尽力抽取工作表/正文及部分形状文本（best effort），但复杂模板、兼容模式对象或非常规绘图结构可能存在漏提取。

Q: 日志里出现 XSSFDrawing / DataFormatter WARN，是否影响检索？

这类日志大多是 POI 对特殊格式的非致命提示（例如旧日期值、AlternateContent 形状），通常不影响读索引流程；当前已在日志层降噪处理。

Q: 如何加速 name:*.ext？

已内置 ext 过滤优化，确保通配后缀能快速命中。

Enjoy lightning‑fast local search!

15) Logs

  • Use Help → View Log to open a live, auto-scrolling log viewer.
  • Viewer defaults to tail -f 1000 lines for readability/performance.
  • Use Show More (+1000) to load more history and Reset Tail to return to 1000.
  • Use Clear to clear current viewer text quickly (does not delete the log file).
  • Log file path: ./.docfinder/logs/docfinder.log.