DocuBrowse バージョン 0.9.0 リリースノート

📦 概要

対応プラットフォーム: Linux (RPM, DEB, tarball)、Windows (zip)、macOS (dmg)。インターフェースは安定しており、破壊的な変更を可能な限り回避しています。

DocuBrowse は、雑然としたドキュメントの山を、実際に検索できる状態に変換します。PDF、電子書籍、Word ドキュメント、ノートなど、あらゆるファイルを指し示すだけで、キーワードだけでなく「意味」を理解するスマートなインデックスを作成します。「リース更新に関する契約書」といった指示を出しても、その言葉がファイルに現れていなくても見つけることができます。結果をクリックすると、ファイルを開く前に即席で AI がサマリー（概要）を表示します。また、個人識別情報 (PII) への対応ができ、複数のドキュメントディレクトリを処理することも可能です。

DocuBrowse は完全にあなたのローカルマシン上で動作し、ローカル AI モデルを使用するため、インターネット接続や API キーの心配は一切ありません。あなたのデータ。あなたの AI。

仕組み: SQLite FTS5 キーワード検索に加え、Ollama (nomic-embed-text + dolphin3) を活用した AI による意味的類似度検出とサマリー生成機能を搭載しています。

🗺️ ナビゲーション

• 機能
• スクリーンショット
• クイックスタート
• CLI リファレンス
• 設定
• アーキテクチャ
• API エンドポイント
• 検索アルゴリズム
• セキュリティ
• ファイル構造
• トラブルシューティング
• 既知の制限事項
• ロードマップ

🚀 機能

🔍 二重検索モード

• キーワード検索: SQLite FTS5 を通じた高速フルテキスト検索（タイトル、著者、サブジェクト、タグ、スニペット）。
• 意味的検索: Ollama エンベッディング（nomic-embed-text:latest）を活用した AI による類似度検出。
• ハイブリッドモード (デフォルト): 70% の意味的スコアと 30% のキーワードスコアを合成し、再ランク付けされます。

📖 AI サマリー

• ドキュメントタイトルのいずれかをクリックすると、Ollama (dolphin3:latest) を使用してオンデマンド生成される Kindle 風の本表紙のようなサマリーが表示されます。
• 初回生成後: データベースにキャッシュされるため、高速化されます。
• 役割分担: 意味的検索用エンベッディングは別のローカルモデル (nomic-embed-text:latest) が担当します。

📚 ドキュメントインデックス化

• 形式: PDF, DOCX, PPTX, XLSX, EPUB, MOBI, AZW3, AZW, HTML, TXT, Markdown
• PDF の高度な解析:
  • 優先的に

    pdfplumber

    を使用 (

    bloated-object

    ファイルには

    pypdf

    でフォールバック)。
  • 複雑なレイアウトに対して

    layout=False

    で再試行。
  • スキャン済み（画像のみ）PDF は検出され

    ocr_list_pdfs.txt

    へルーティングされます。
• Word/プレゼン/スプレッドシート:
  • Word (

    python-docx

    ): パラグラフ、テーブル、主要な属性（タイトル、著者、サブジェクト）の抽出。
  • プレゼン (

    python-pptx

    ): スライドテキスト、ノート、および主要な属性の抽出。
  • スプレッドシート (

    openpyxl

    ): セル値とシート名の抽出。
• 電子書籍:
  • EPUB:

    ebooklib

    / MOBI/AZW3:

    mobi package

    +

    Calibre

    フォールバック。
  • DRM 暗号化 AZW: メタデータのみインデックス化（タイトル/著者は表示可能、本文は検索不可）。
• PII 保護: スキャナーが SSN クレジットカード情報、銀行振込元/口座番号、生年月日、MRN、免許証、パスポートのパターンを検出し、該当するドキュメントを削除し、永続的にブラックリストに載せます。

🎨 ユーザーインターフェース

• ダークモード/ライトモードテーマ切り替え
• ページネーションされた結果（1 ページ 50 ドキュメント）とナビゲーション
• 文字順インデックスバー (A–Z, 0–9): クイックナビゲーションが可能で、ページ読み込み間で状態が保持されます。
• トピックによるフィルタリング用のタグクラウド
• 各結果カード上の関連度スコアバッジ（0-100%）
• 「開く」ボタン:

  xdg-open

  を介してデフォルトアプリでファイルを起動。
• アクション: クリックすると AI サマリーを表示; 📋 クリップボードにパスをコピー; 🗑 ファイルをディスクとインデックスから削除（確認が必要）。

⚙️ 設定 (

/settings

)

• 全般パネル: ドキュメントディレクトリ（ライブブラウザ付き）、追加のスキャンディレクトリの管理、ワーキングディレクトリ、ポート設定。
• 無視ディレクトリパネル:

  ignore_dirs.txt

  をブラウザから管理可能。削除前に確認プロンプトが表示されます。

⚡ パフォーマンス

• 検索レイテンシ: 通常で <150ms
• 並列処理: プロセスプールエグゼキューターを使用した並列 PDF 抽出（物理コア数の感知されたワーカー数）。
• メモリ安全: カーネル強制 RLIMIT_AS (6 GB/ワーカー) + フリー RAM しきい値でのポーズ/再開。

📸 スクリーンショット

• ダークモード
• ライトモード

縮小画像をクリックしてフルサイズを表示します。

⚡ クイックスタート

必須要件

• Python 3.9+
• Ollama (起動時不足の場合は自動インストール)
  • モデル:

    nomic-embed-text:latest

    (エンベッディング),

    dolphin3:latest

    (サマリー生成)
• ブラウザ (Chrome, Firefox, Safari, Edge)
• Calibre (電子書籍用): Linux では

  sudo apt install calibre

  など

詳細な手順については INSTALL.md を参照してください。

インストール（推奨）

Releases ページから適切なパッケージをダウンロードしてください。

Fedora / RHEL

sudo dnf install ./docubrowser-foss-0.9.0-7.noarch.rpm

Debian / Ubuntu / Mint

sudo apt install ./docubrowser-foss_0.9.0-7_all.deb

任意の Linux (tarball)

tar xzf docubrowser-foss-0.9.0-7.tar.gz
cd docubrowser-foss-0.9.0-7
sudo ./install.sh

Windows

1. zip ファイルを解凍します。

2. Install.bat

   をダブルクリックしてください。
   • 事前インストール:Python 3.9+ と Ollamaが必要です。
   • インストール先:

     %USERPROFILE%\DocuBrowse

macOS

1. dmg を開きます。

2. Install.command

   をダブルクリック（初回の場合は右クリック→「開く」が必要）します。
   • 事前インストール:**Python 3.9+**が必要です。
   • インストール先:

     ~/Applications/DocuBrowse/

コマンドの使用

インストール後、CLI は

docubrowser

docubrowser rescan      # ドキュメントのスキャンおよびインデックス化
docubrowser start       # サーバーの起動
docubrowser open        # UI の表示

注意: 開発環境やクローンしたリポジトリでは

./docubrowser.py <コマンド>

と記述する必要があります。

アンインストール

• RPM:

  sudo dnf remove docubrowser-foss

• DEB:

  sudo apt remove docubrowser-foss

• Tarball:

  sudo ./uninstall.sh

• Windows:

  Uninstall.bat

  をダブルクリック
• macOS:

  Uninstall.command

  をダブルクリック

🔧 設定ファイル

設定は

/settings

デフォルト値と優先順位

設定は以下の順序で読み取ります:

1. /etc/docubrowse.config

   (システム全体)

2. ./docubrowse.config

   (docubrowser.py の隣に)
3. Web UI の設定ギアアイコン

インストール後

• CLI コマンド (

  rescan

  ,

  report

  ) はドキュメントディレクトリが設定されるまでエラーになります。
• Web UI でもドキュメントディレクトリの構成が必要です（ギアアイコンまたは

  docubrowse.config

  経由）。

docubrowse.config

doc_dir      = /mnt/data/Documents
db_path      = /home/user/DocuBrowse/du-docs.db
port         = 8643
work_dir     = /home/user/DocuBrowse

⌨️ CLI リファレンス

使用方法:

docubrowser.py <command> [options]

start

stop

restart

status

scan [TYPE ...]

rescan [TYPE ...]

scan-file --file PATH

embed

open

purge

ignore add|remove|list DIR

report

scan-missing [--dry-run]

duplist

dupclean

グローバルオプション

• --db PATH

  : SQLite データベースパス（設定を上書き）

• --port PORT

  : サーバーポート（設定を上書き）

• --config FILE

  : 設定ファイルパス

コマンド例

サーバー管理

docubrowser start --port 9000
docubrowser status
docubrowser stopall

スキャン (Type フィルター)

./docubrowser.py scan              # すべてのサポートされたタイプ
./docubrowser.py rescan pdf        # PDF のみ
./docubrowser.py rescan --no-embed # エンベッディングステップなし

単一ファイルインデックス化 (ブラックリスト解除用)

docubrowser scan-file --file /path/to/problem.pdf

重複検出

docubrowser duplist                # 正確な SHA256 の duplicates
docubrowser dupclean               # インタラクティブ TUI (Keep A/B)

🏗️ アーキテクチャ

DocuBrowse は以下のスクリプトから構成されます。

docubrowser.py

ensure_ollama.py

doc_search.py

scan_docs.py

pdf_extractor.py

pdfplumber

pypdf

embed_docs.py

purge_pii.py

dup_detect.py

du-docs.db

ブラックリストファイル

• scan_blacklist.txt

  : 抽出失敗したファイル（再試行時に除外）。

• pii_blacklist.txt

  : PII を含むため削除されたファイル（永続的）。

• ocr_list_pdfs.txt

  : OCR が必要な画像のみ PDF。

• ignore_dirs.txt

  : スキャンから除外されるディレクトリ。

🌐 API エンドポイント

ベース URL:

http://localhost:8643

/

/settings

/api/stats

/api/search

/api/synopsis

/api/open

xdg-open

/api/delete

/api/config

検索レスポンス例:

{
  "documents": [
    {
      "id": 1,
      "name": "doc.pdf",
      "score": 0.95,
      "sem_score": 0.98,
      "fts_score": 0.8
    }
  ],
  "total": 312,
  "count": 50
}

CSRF セキュリティ:

/api/open

,

/api/delete

などの変化系エンドポイントは、プロセス固有の

X-CSRF-Token

とループバック Origin を必要とします。UI から呼び出す限り安全です。

🧠 検索アルゴリズム

スコアリングは以下の通りです: $$ \text{final_score} = 0.3 \times \text{keyword_score} + 0.7 \times \text{semantic_score} $$

• キーワード (FTS5 BM25):
  • SQLite FTS5 インデックスを使用（単純なサブstring スキャンではない）。
  • タイトル・著者などフィールド優先度に基づく正規化スコア。
• 意味的:
  • クエリとドキュメントの余弦類似度 (768 次元ベクトル)。
  • ミニマスしきい値:

    SEM_FLOOR=0.30

    (これ未満は無視)。

🔒 セキュリティ

DocuBrowse はローカル使用を前提に強化されています。

• ホストヘッダー許可リスト: すべてリクエストは

  localhost/127.0.0.1/[::1]

  のみ受理され、DNS リバインディング対策が行われます。
• CSRF 保護:

  /api/delete

  ,

  /api/open

  は

  X-CSRF-Token

  とループバック Origin を必須としています（UI からしかアクセスできない）。
• XSS 防御: HTML エスケープとデータ属性ベースのイベントリスナーを使用。
• PII 検証: SSN、クレジットカードなどは規則やチェックサムで厳密に検証してから削除します。

📂 ファイル構造

DocuBrowse/
├── docubrowser.py            # CLI エントリポイント
├── doc_search.py             # HTTP サーバー
├── du-docs.db                # データベース (gitignored)
├── scan_blacklist.txt        # 抽出失敗リスト
├── pii_blacklist.txt         # PII 削除リスト (永続的)
├── ignore_dirs.txt           # 除外ディレクトリ
└── index.html                # フロントエンド UI

⚠️ トラブルシューティング

inotify watch limit exceeded

大規模ドキュメントコレクションでエラーが起きた場合、

/etc/sysctl.conf

fs.inotify.max_user_instances

256

sudo sysctl -p

PDF がフリーズする (Hang)

• pdfinfo

  でオブジェクト数が 8000 を超えている場合、ExifTool メタデータ更新起因の可能性があります。自動的に

  pypdf

  で処理されますが、必要であれば

  scan-file --file ...

  で再試行してください。
• スキャン済み PDF (OCR 必要) は検索には一致しません（OCR が必要か

  ocr_list_pdfs.txt

  を確認）。

Ollama が起動しない

ollama serve
ollama list                    # モデルがあるか確認
ollama pull nomic-embed-text:latest
ollama pull dolphin3:latest

📝 既知の制限事項

scan-missing

rescan

🔄 最近の変更点 (Changelog)

v0.9.0 (2026-07-05)

• ネイティブパッケージング: Linux (RPM/DEB/tarball), Windows (zip), macOS (dmg) を対応。
• Windows 完全サポート:

  Install.bat

  /

  install.ps1

  による簡易インストール、レジストリショートカット作成。
• クロスプラットフォーム: 新しい

  platform_paths.py

  で OS 固有の処理を一元管理。
• UI/UX 改良: ダークモードパレット刷新、ダッシュボードレイアウト最適化。

v0.8.x (2026-06-13 ~ 2026-07-02)

• v0.8.4: コードベースクリーンアップ（不使用機能削除）、サーバーコード約 300 ライン削減。
• v0.8.3: 「Show 🙈」トグルによる非表示ドキュメント管理、UI パレット完全リデザイン。
• v0.8.2: Open ボタンがファイルパスリンクを置き換え、

  xdg-open

  連携強化。
• v0.8.1: DB スキーマミグレーションのバグ修正。

🚀 ロードマップ

👨‍💻 AI 支援開発

DocuBrowse は Claude をコーディングパートナーとして利用しています。プロジェクトの状態を知るには以下のファイルを参照してください。

• .claude/CLAUDE.md

  (ルールと学習)

• status_docs/project_status.md

  (進捗状況)

• status_docs/DECISIONS.md

  (意思決定ログ)

全状況を AI に投与するには:

cat .claude/CLAUDE.md status_docs/project_status.md status_docs/DECISIONS.md

⚖️ ライセンス

GNU General Public License v3.0 以降 (GPL-3.0-or-later)

Copyright (C) 2026 James Sparenberg。詳細は LICENSE を参照してください。