diff --git a/.agent/rules/documents.md b/.agent/rules/documents.md index 238c6ad..24d7115 100644 --- a/.agent/rules/documents.md +++ b/.agent/rules/documents.md @@ -1,7 +1,7 @@ --- trigger: always_on glob: -description: 設計参照・計測・ジャーナル・コミット・ログ確認。他ルールは配布ビルド前→distribution-build.md、Issue→issue_management.md。 +description: 設計参照・計測・ジャーナル・コミット・ログ確認。調べる場面では search_text を積極的に使う。他ルールは配布ビルド前→distribution-build.md、Issue→issue_management.md。 --- 0. **着手前**: タスク着手前に、タスク種別に応じて関連ルールを確認してから作業を開始すること。推測や慣習に頼らず、ルールを読んでから着手する。 @@ -12,7 +12,7 @@ 1. toolsは.gitignoreだがアクセスは許可されています。 2. 詳細な設計がdocumentsにあるので、改造を計画する際に参照すること。 -2.1 **調べるときは search_text も使う**: 「どこでやってるか」「どういう仕様か」「他プロジェクトのやり方」を調べる文脈では、リポジトリの grep/read に加えて MCP の `search_text` でインデックスを検索すること。インデックスにモニタや add_item_text で取り込んだドキュメントがあれば、横断的にヒットする。自然な質問(例: 「PDF のソースはどこ」「アーカイブの手順」)で検索するとよい。 +2.1 **search_text を積極的に使う**: 事実・仕様・「どこでやってるか」「他プロジェクトのやり方」を調べるときは、grep/read に加えて(あるいは先に)MCP の `search_text` でインデックスを検索すること。ユーザーが「〜はある?」「〜の方法は?」と聞いた場合も、search_text の利用を検討する。自然な質問(例: 「PDF のソースはどこ」「アーカイブの手順」)で検索するとよい。 3. ソースコードの編集が完了したら、`tools/count_loc.cjs` と `tools/nesting_depth.cjs` を使用して計測を行うこと。 4. 計測の結果、ソースコードが600行以上、またはネストが7階層以上のコードについては、リファクタリングを検討すること。 diff --git a/RELEASE_v0.3.3_Community.md b/RELEASE_v0.3.3_Community.md new file mode 100644 index 0000000..6192eb3 --- /dev/null +++ b/RELEASE_v0.3.3_Community.md @@ -0,0 +1,93 @@ +# TelosDB Community 版 v0.3.3 — 商品紹介 + +## そのまま使える、ローカル完結の意味検索 + +**TelosDB Community 版**は、追加のモデルや設定なしで、すぐに意味検索を始められるデスクトップアプリです。データはすべてお使いの PC 内に留まり、クラウドへ一切送信しません。 + +--- + +## こんな方におすすめ + +- まずは手軽に意味検索を試したい +- モデルのダウンロードや GPU 環境を用意したくない +- 個人のメモやドキュメントを「意味で」探したい +- Cursor や Claude Desktop など AI ツールと MCP で連携したい + +--- + +## Community 版の特長 + +### モデル不要で動く + +LSA(潜在意味解析)により、**50 次元のベクトル**で文書を表現します。大きな AI モデルは不要。インストール後、そのまま検索できます。 + +### キーワードも自然な文も、そのまま検索 + +「春の歌」でも「桜の季節に聴きたい曲」のような文でも検索可能。結果は**文書単位**でまとめて返すため、どのドキュメントがヒットしたかが分かりやすくなっています。 + +### MCP で AI とつながる + +Model Context Protocol(MCP)に対応。Cursor や Claude Desktop から「検索」「追加」「RE-INDEX」などのツールとして TelosDB を呼び出せます。AI エージェントの「記憶」として利用するのに最適です。 + +### 自動でインデックスを整える + +ドキュメントの増減に応じて、バックグラウンドで LSA を再学習。画面上では「LSA学習中…」「ベクトル同期中…」の表示で進行状況を確認できます。必要に応じて RE-INDEX で手動再構築も可能です。 + +### ログイン時に自動起動(オプション) + +設定で「OSにログインしたときに自動で起動する」をオンにすると、Windows にサインインしたタイミングで TelosDB が起動し、トレイで待機。いつでも MCP 経由で検索できます。 + +### フォルダ監視で自動取り込み(New) + +指定したフォルダを常時監視し、ファイルの追加・更新・削除を自動検知してインデックスに反映します。テキストやマークダウンを保存するだけで、検索対象に自動登録。フォルダごとにカテゴリ名を付けられるため、検索時の分類にも活用できます。 + +--- + +## v0.3.3 の主な変更点 + +### 新機能 + +- **フォルダ監視**: 指定フォルダ内のファイル追加・更新・削除を自動検知し、インデックスに反映。設定パネルからフォルダの追加・削除・カテゴリ指定が可能。取込対象の拡張子もカスタマイズ可能(デフォルト: txt, md, json, html, css, js, mjs, ts, rs)。 +- **接続状態表示**: MCP サーバーへの接続状態を UI に表示。 + +### 改善 + +- **自動起動の安定化**: 設定ファイル読み込み失敗時にレジストリエントリが消える問題を修正。`isEnabled()` で OS の実状態と比較し、不一致時のみ登録を更新するように改善。失敗時のエラー表示を追加。 +- **バックエンドリファクタリング**: MCP ツールの登録を `registry.rs` に集約し、検索ロジックを `search.rs` に整理。DB アクセス関数を `db/mod.rs` に追加。 +- **DB マイグレーション**: ドキュメントパスの正規化マイグレーションを追加(テーブル未存在時はスキップ)。 +- **バージョン表示の安定化**: フッターのバージョン取得でサーバー未応答時のビジーウェイトとフォールバック未設定の問題を修正。 +- **E2E テスト**: 自動起動・フォルダ監視・パネル操作・文書編集のテストを追加。 + +--- + +## 含まれる機能(v0.3.3) + +- 意味検索(LSA 50 次元)+ 全文検索(FTS5)のハイブリッド検索 +- 検索結果の文書単位表示(`group_by_document`) +- **フォルダ監視**: 指定フォルダの自動取り込み・カテゴリ指定・拡張子フィルタ +- MCP ツール: `search_text` / `add_item_text` / `update_item` / `delete_item` / `get_item_by_id` / `get_document_count` / `lsa_retrain`(RE-INDEX) +- ドキュメント件数の表示(ヘッダー「X docs」・`get_document_count`) +- インデックス状態の表示(LSA学習中・ベクトル同期中) +- ログイン時の自動起動(オプション) +- トレイ常駐・バージョン表示 + +--- + +## ご利用方法 + +**インストーラ**: `TelosDB-Community_0.3.3_x64-setup.exe` を実行してインストールしてください。 + +**ソースからビルドする場合**: + +```bash +npm install +npm run build:community +``` + +- 出力: `src/backend/target/release/bundle/nsis/TelosDB-Community_0.3.3_x64-setup.exe` +- 初回起動時に vec0.dll がアプリデータフォルダへコピーされます。不具合時は `%APPDATA%\com.telosdb.app\logs\telos.log` をご確認ください。 + +--- + +より高精度な意味検索をご希望の方は **Pro 版**をご検討ください。 +→ [TelosDB Pro 版 商品紹介](RELEASE_v0.3.3_Pro.md) diff --git a/RELEASE_v0.3.3_Pro.md b/RELEASE_v0.3.3_Pro.md new file mode 100644 index 0000000..686a66a --- /dev/null +++ b/RELEASE_v0.3.3_Pro.md @@ -0,0 +1,107 @@ +# TelosDB Pro 版 v0.3.3 — 商品紹介 + +## 日本語に強い、高精度な意味検索 + +**TelosDB Pro 版**は、日本語向けの埋め込みモデル(768 次元)を**インストーラに同梱**したエディションです。インストールするだけで、言い回しの違いに強い高精度な意味検索が使えます。ビジネス文書や学術メモの検索に適し、データはすべてローカルで完結。クラウドへ送信しません。 + +--- + +## こんな方におすすめ + +- 検索精度をより高めたい +- 「似た意味の文」でしっかりヒットさせたい +- 報告書・論文・仕様書などフォーマルな日本語を扱う +- Cursor や Claude Desktop と MCP で連携し、高品質な検索結果を AI に渡したい + +--- + +## Pro 版の特長 + +### 日本語特化の埋め込みで高精度 + +**sentence-BERT 系の日本語モデル**(768 次元)で文書をベクトル化。キーワードの一致だけでなく、「言い換え」や「関連する表現」にも強く、自然な文で検索できます。結果は**文書単位**で返るため、どのドキュメントが該当したかが一目で分かります。 + +### 量子化モデルで軽く・速く(インストーラに同梱) + +推論用に **INT8 量子化した ONNX モデル**を使用。GPU は不要で、一般的な PC の CPU だけで動作します。**モデルはインストーラに含まれており、別途ダウンロードは不要**。インストール後すぐに高精度検索をご利用いただけます。 + +### MCP で AI とつながる + +Model Context Protocol(MCP)に対応。Cursor や Claude Desktop から「検索」「追加」「RE-INDEX」などのツールとして TelosDB を呼び出せます。高精度な検索結果を AI のコンテキストとしてそのまま利用できます。 + +### インデックス状態が分かる + +起動時や RE-INDEX 時に、HNSW の構築状況などが画面上で確認できます。「Pro」バッジでエディションが識別でき、モデルの読み込み状態も把握しやすくなっています。 + +### ログイン時に自動起動(オプション) + +設定で「OSにログインしたときに自動で起動する」をオンにすると、Windows にサインインしたタイミングで TelosDB が起動。トレイで待機し、いつでも MCP 経由で高精度検索を利用できます。 + +### フォルダ監視で自動取り込み(New) + +指定したフォルダを常時監視し、ファイルの追加・更新・削除を自動検知してインデックスに反映します。テキストやマークダウンを保存するだけで、高精度な意味検索の対象に自動登録。フォルダごとにカテゴリ名を付けられるため、検索時の分類にも活用できます。 + +--- + +## v0.3.3 の主な変更点 + +### 新機能 + +- **フォルダ監視**: 指定フォルダ内のファイル追加・更新・削除を自動検知し、インデックスに反映。設定パネルからフォルダの追加・削除・カテゴリ指定が可能。取込対象の拡張子もカスタマイズ可能(デフォルト: txt, md, json, html, css, js, mjs, ts, rs)。 +- **接続状態表示**: MCP サーバーへの接続状態を UI に表示。 + +### 改善 + +- **自動起動の安定化**: 設定ファイル読み込み失敗時にレジストリエントリが消える問題を修正。`isEnabled()` で OS の実状態と比較し、不一致時のみ登録を更新するように改善。失敗時のエラー表示を追加。 +- **バックエンドリファクタリング**: MCP ツールの登録を `registry.rs` に集約し、検索ロジックを `search.rs` に整理。DB アクセス関数を `db/mod.rs` に追加。 +- **DB マイグレーション**: ドキュメントパスの正規化マイグレーションを追加(テーブル未存在時はスキップ)。 +- **バージョン表示の安定化**: フッターのバージョン取得でサーバー未応答時のビジーウェイトとフォールバック未設定の問題を修正。 +- **E2E テスト**: 自動起動・フォルダ監視・パネル操作・文書編集のテストを追加。 + +--- + +## インストーラにモデル同梱 + +Pro 版のインストーラ(`TelosDB-Pro_0.3.3_x64-setup.exe`)には、**埋め込み用の量子化 ONNX モデル**が同梱されています。 + +- **利用者**: 別途モデルのダウンロードは不要。インストールするだけで、インストール先のリソースから自動的にモデルが参照され、高精度な意味検索が利用できます。 +- **同梱内容**: `model_quantized.onnx`(日本語 sentence-BERT 量子化モデル)・`vocab.txt`(語彙)。 +- モデルが読み込めない場合でも、全文検索(FTS)のみで検索は可能です。 + +--- + +## 含まれる機能(v0.3.3) + +- **埋め込みモデルのインストーラ同梱**(別途ダウンロード不要。インストール先から自動参照) +- 意味検索(埋め込み 768 次元)+ 全文検索(FTS5)のハイブリッド検索 +- 検索結果の文書単位表示(`group_by_document`) +- **フォルダ監視**: 指定フォルダの自動取り込み・カテゴリ指定・拡張子フィルタ +- MCP ツール: `search_text` / `add_item_text` / `update_item` / `delete_item` / `get_item_by_id` / `get_document_count` / `lsa_retrain`(RE-INDEX) +- ドキュメント件数の表示(ヘッダー「X docs」・`get_document_count`) +- インデックス状態の表示(ベクトル同期中・HNSW 構築状況) +- ログイン時の自動起動(オプション) +- トレイ常駐・バージョン表示 + +--- + +## ご利用方法 + +**インストーラ**: `TelosDB-Pro_0.3.3_x64-setup.exe` を実行してインストールしてください。埋め込みモデルはインストーラに含まれており、追加のダウンロードは不要です。 + +**ソースからビルドする場合**(配布用インストーラを作る開発者向け): + +1. [sentence-bert-base-ja-mean-tokens-v2-int8](https://gitbucket.tmworks.club/dtmoyaji/sentence-bert-base-ja-mean-tokens-v2-int8) から `target/` 一式(`model_quantized.onnx`・`vocab.txt`)を取得し、プロジェクトの **`embedding_model/`** に配置します。 +2. `npm run build:pro` を実行すると、それらがインストーラに同梱された Pro 版がビルドされます。 + +```bash +npm install +npm run build:pro +``` + +- 出力: `src/backend/target/release/bundle/nsis/TelosDB-Pro_0.3.3_x64-setup.exe`(モデル同梱) +- 初回起動時に vec0.dll がアプリデータフォルダへコピーされます。不具合時は `%APPDATA%\com.telosdb.app\logs\telos.log` をご確認ください。 + +--- + +モデル不要で手軽に始めたい方は **Community 版**をご利用ください。 +→ [TelosDB Community 版 商品紹介](RELEASE_v0.3.3_Community.md) diff --git a/docs/README.md b/docs/README.md index d22c708..692d859 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ | ディレクトリ | 内容 | |-------------|------| | **specification/** | システム仕様・設計。アーキテクチャ、DB、MCP API、UI、開発ガイド、埋め込み・エディション、モノリシック化、KPI・検証、UI テスト、OpenAPI / MCP スキーマ。 | -| **plans/** | 今後の実装計画。計画ごとにサブフォルダを切る(例: `plans/folder_monitor/`)。 | +| **plans/** | 今後の実装計画。機能単位でファイルまたはサブフォルダを置く。 | | **issues/** | Issue 同期用の Markdown(Git 追跡外。`node tools/scripts/sync_issues.mjs` で同期)。 | | **references/** | 調査メモ・外部資料の参照。ベクトル化手法、BM25、Elasticsearch 等。 | @@ -27,19 +27,14 @@ - **10_monolithic_dev.md** — モノリシック化(開発時アーキテクチャ) - **11_pro_vectorization_and_ann.md** — Pro ベクトル化・ANN 動作確認 - **12_ui_testing_options.md** — UI をテストに組み込む方法(E2E / Playwright 等) +- **13_autostart.md** — 自動起動仕様(ログイン時起動・設定連携・UI・テスト) +- **14_folder_monitor.md** — フォルダ監視仕様(notify・DB 連携・設定 UI) - **mcp.json**, **openapi.yaml** — MCP / API スキーマ -**plans/** は計画ごとにサブフォルダを置く。 +**plans/** は計画ごとにファイルまたはサブフォルダを置く。 -- **plans/auto_start/** — ユーザーログイン時に自動起動する仕組み。検討事項別に分割(スコープ・技術方針・UI 改造・実装ステップ・注意事項・参照)。 -- **plans/folder_monitor/** — 指定フォルダ監視(追加・削除・更新の検出→DB取り込み・ベクトル化) - - **folder_monitor.md** — 計画トップ(目的・目次) - - **folder_monitor_01_scope.md** — 01 スコープ - - **folder_monitor_02_tech.md** — 02 技術方針(notify・デバウンス・ネットワーク・Config 等) - - **folder_monitor_03_os_protocol.md** — 03 OS・ファイルプロトコル別実装方針 - - **folder_monitor_04_phases.md** — 04 実装ステップ(Phase 1〜5) - - **folder_monitor_05_considerations.md** — 05 注意事項・未決定 - - **folder_monitor_06_references.md** — 06 参照・調査元 -- **plans/lda/** — LDA(潜在的ディリクレ配分)の扱い。**v0.3.3 Community 版**で実装。LSA と LDA を切り替え、規定 128 次元・ユーザー指定で再構成。検討事項別に分割(スコープ・技術・**UI 改造**・実装ステップ・注意事項・参照)。 +- **plans/cross_platform.md** — クロスプラットフォーム検証(autostart・folder_monitor の macOS / Linux 動作確認・アンインストール時のエントリ残留) +- **plans/folder_monitor_enhancements.md** — フォルダ監視の拡張(PollWatcher フォールバック・初期スキャン改善・権限エラー UI・パス正規化) +- **plans/lda/** — LDA(潜在的ディリクレ配分)の扱い。検討事項別に分割(スコープ・技術・UI 改造・実装ステップ・注意事項・参照)。 運用ルール(Issue 管理・Git 運用など)は `.agent/rules/` にあります。 diff --git a/docs/plans/auto_start/auto_start.md b/docs/plans/auto_start/auto_start.md deleted file mode 100644 index 76e8e81..0000000 --- a/docs/plans/auto_start/auto_start.md +++ /dev/null @@ -1,29 +0,0 @@ -# 計画: ユーザーログイン時に自動起動する仕組み - -## 1. 目的 - -OS にユーザーがログインしたタイミングで TelosDB を自動的に起動し、システムトレイで待機させる。ユーザーが手動で起動しなくても MCP サーバーや検索機能を利用可能にする。 - -```mermaid -flowchart LR - subgraph ユーザー操作なし - A[OS ログイン] --> B[TelosDB 自動起動] - B --> C[トレイで待機] - C --> D[MCP / 検索 利用可能] - end -``` - ---- - -## 2. 検討事項別ドキュメント - -各検討事項は別ファイルに分割している。 - -| No. | 項目 | ファイル | 内容 | -|-----|------|----------|------| -| 01 | **スコープ** | [auto_start_01_scope.md](auto_start_01_scope.md) | 対応プラットフォーム、トリガー、起動後挙動、設定保存。 | -| 02 | **技術方針** | [auto_start_02_tech.md](auto_start_02_tech.md) | tauri-plugin-autostart、API、設定との連携。 | -| 03 | **UI 改造** | [auto_start_03_ui.md](auto_start_03_ui.md) | 設定パネルにトグル追加、配置・ラベル、仕様書更新。 | -| 04 | **実装ステップ** | [auto_start_04_phases.md](auto_start_04_phases.md) | Phase 1〜4 の実装順序。**テスト・検証**(単体・結合・UI/E2E・手動・リリース前)を含む。 | -| 05 | **注意事項・未決定** | [auto_start_05_considerations.md](auto_start_05_considerations.md) | トレイ起動、権限、競合。 | -| 06 | **参照** | [auto_start_06_references.md](auto_start_06_references.md) | プラグイン・Tauri 公式・06 仕様。 | diff --git a/docs/plans/auto_start/auto_start_01_scope.md b/docs/plans/auto_start/auto_start_01_scope.md deleted file mode 100644 index cd6d42d..0000000 --- a/docs/plans/auto_start/auto_start_01_scope.md +++ /dev/null @@ -1,16 +0,0 @@ -# 自動起動計画: 01 スコープ - -[計画トップ](auto_start.md) - ---- - -## スコープ - -| 項目 | 内容 | -|------|------| -| **対応プラットフォーム** | **Windows**(現行)、**macOS**、**Linux**。Tauri 2 の対応 OS に合わせて自動起動も各 OS で有効にする。 | -| **トリガー** | ユーザーが OS に**ログイン(サインイン)**したとき。ロック画面からの解除やスリープ復帰では発火しない。 | -| **デフォルト** | 設定キーが無い場合(初回・既存ユーザーのアップデート後)は**自動起動はオフ**とする。 | -| **起動後の挙動** | 通常起動と同様(ウィンドウまたはトレイで待機)。設定で「自動起動」のオン・オフを切り替え可能とする。 | -| **設定の保存** | 自動起動の有無はアプリ設定に永続化し、次回起動時にも反映する。 | -| **対象エディション** | **Community 版・Pro 版の両方**で利用可能とする。エディションによる差異は設けず、同一の設定項目・プラグイン API で扱う。 | diff --git a/docs/plans/auto_start/auto_start_02_tech.md b/docs/plans/auto_start/auto_start_02_tech.md deleted file mode 100644 index c5e5f00..0000000 --- a/docs/plans/auto_start/auto_start_02_tech.md +++ /dev/null @@ -1,64 +0,0 @@ -# 自動起動計画: 02 技術方針 - -[計画トップ](auto_start.md) - ---- - -## 3.1 採用: tauri-plugin-autostart - -- **プラグイン**: [tauri-plugin-autostart](https://github.com/tauri-apps/tauri-plugin-autostart)([crates.io](https://crates.io/crates/tauri-plugin-autostart))を採用する。 -- **対応 OS**: Windows / macOS / Linux でログイン時起動をサポート。Android / iOS は非対応(Tauri のデスクトップ用途と一致)。 -- **実装の裏側**(プラグインが担当): - - **Windows**: レジストリ `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` にアプリパスを登録。 - - **macOS**: Launch Agent(`~/Library/LaunchAgents/` に plist を配置)。 - - **Linux**: XDG Autostart(`~/.config/autostart/*.desktop` に .desktop ファイルを配置)。 - -- **起動引数(任意)**: プラグインの `Builder` で `.args([...])` を指定できる。自動起動時に「トレイのみで起動」など振る舞いを変えたい場合は、ここで引数(例: `--minimized`)を渡し、アプリ起動時に解釈する。 - -```mermaid -flowchart TB - subgraph プラットフォーム別の実体 - W[Windows: レジストリ Run] - M[macOS: LaunchAgents] - L[Linux: autostart .desktop] - end - P[tauri-plugin-autostart] --> W - P --> M - P --> L - U[ユーザー: enable/disable] --> P -``` - -## 3.2 導入の手順(Phase 1 で行うこと) - -- **Cargo.toml**: `tauri-plugin-autostart` を依存に追加。 -- **Rust**: `tauri::Builder` に `.plugin(tauri_plugin_autostart::init(...))` を登録。必要なら `.args([...])` で起動引数を指定。 -- **Tauri 設定**: プラグインが `tauri.conf.json` の `plugins` や capability を要求する場合は、ドキュメントに従い permission を追加。 -- **フロント**: `@tauri-apps/plugin-autostart` の `enable` / `disable` / `isEnabled` を呼ぶ。Tauri コマンド経由でも可。 - -## 3.3 API(フロント/バック) - -- **enable()**: 自動起動を有効にする。 -- **disable()**: 自動起動を無効にする。 -- **isEnabled()**: 現在自動起動が有効かどうかを返す。 - -設定 UI のトグルや起動時の読み込みで上記を呼び出す。設定の永続化(localStorage や Tauri の app 設定)と連携し、「自動起動オン」のときだけプラグインの `enable()` を呼ぶ。 - -## 3.4 設定との連携 - -- 設定項目「ログイン時に自動起動する」を追加する(現状は [06 UI 仕様](../../specification/06_ui_design_spec.md) 上で非表示のため、本機能実装時に設定パネルに表示する)。 -- オンにした場合: 設定を保存し、`tauri-plugin-autostart` の `enable()` を実行。 -- オフにした場合: 設定を保存し、`disable()` を実行。 -- アプリ起動時: 保存済み設定を読み、`isEnabled()` と一致していなければ `enable()` / `disable()` で同期する(他ツールでレジストリ等をいじった場合のずれを吸収)。 -- **アップデート後**: 再インストールで実行ファイルのパスが変わると、既存の Run キー等は無効になる。次回起動時の「設定読み込み+isEnabled() との同期」で、設定がオンの場合は `enable()` を呼び直し、新しいパスで登録し直す。 - -```mermaid -stateDiagram-v2 - [*] --> 設定読み込み - 設定読み込み --> 同期: 設定値と isEnabled() が不一致 - 設定読み込み --> 待機: 一致 - 同期 --> enableまたはdisable - enableまたはdisable --> 待機 - 待機 --> ユーザーがトグル変更 - ユーザーがトグル変更 --> 保存してenable/disable - 保存してenable/disable --> 待機 -``` diff --git a/docs/plans/auto_start/auto_start_03_ui.md b/docs/plans/auto_start/auto_start_03_ui.md deleted file mode 100644 index 31a9680..0000000 --- a/docs/plans/auto_start/auto_start_03_ui.md +++ /dev/null @@ -1,43 +0,0 @@ -# 自動起動計画: 03 UI 改造 - -[計画トップ](auto_start.md) - ---- - -本機能を有効にするには、**設定 UI の変更**が必要である。現状 [06 UI 仕様](../../specification/06_ui_design_spec.md) では「ログイン時起動・フォルダモニタリングのパネルは UI に含めない」とされているため、自動起動用の項目を表示する改造を計画に含める。 - -## 4.1 設定パネルに追加する項目 - -| 項目 | 内容 | -|------|------| -| **表示するコントロール** | 「ログイン時に自動起動する」の **トグル(スイッチ)** 1 つ。 | -| **配置** | 設定パネル内。検索まわり(スコア足切り・取得件数)の上または下に、明確に区切って配置する。 | -| **ラベル** | 短く分かりやすい文言(例: 「ログイン時に自動起動する」)。必要なら補足テキスト(「OS にサインインしたときに TelosDB を起動します」)を小さく表示。 | -| **見た目** | 既存の [06 コンセプト](../../specification/06_ui_design_spec.md)(ハイコントラスト・ミニマリズム)に合わせる。装飾を抑え、トグルは既存の設定項目とスタイルを統一する。 | -| **トグルの表示値** | 設定パネルを**開いたとき**に、保存済み設定だけでなく **`isEnabled()` の結果**も参照し、実状態に合わせてトグルを表示する。起動時同期のあとなら実状態と保存値は一致している想定だが、他ツールで登録を外した場合などに備える。 | -| **デフォルト** | 設定が無い場合は**オフ**表示([01 スコープ](auto_start_01_scope.md))。 | - -## 4.2 画面フロー - -```mermaid -flowchart LR - subgraph 設定パネル - A[設定ボタン] --> B[パネル開く] - B --> C[検索設定] - B --> D[ログイン時自動起動 トグル] - D --> E[ON: enable] - D --> F[OFF: disable] - end - E --> G[設定保存] - F --> G -``` - -## 4.3 仕様書の更新 - -- **06_ui_design_spec.md**: 「非表示: ログイン時起動・フォルダモニタリングのパネル」を、**自動起動については「表示する」** に変更する。フォルダモニタリングは別計画のため、当面は非表示のままでもよい。 -- **設定の永続化**: 自動起動のオン・オフは、既存の `telosdb_settings`(localStorage)に含めるか、別キーで保存するかを実装時に決める。いずれにしても「設定パネルを開いたとき・起動時に読み込み、トグルとプラグイン状態を一致させる」。 - -## 4.4 考慮事項 - -- **初回表示**: これまで非表示だった項目を出すため、設定パネルの高さやレイアウトが変わる。小さいウィンドウでもはみ出さないよう、スクロールや折りたたみを検討する。 -- **他計画との関係**: フォルダモニタリングもいずれ設定パネルに出す場合、同じ「起動・動作オプション」として自動起動と並べて配置する構成が分かりやすい。 diff --git a/docs/plans/auto_start/auto_start_04_phases.md b/docs/plans/auto_start/auto_start_04_phases.md deleted file mode 100644 index 411e39f..0000000 --- a/docs/plans/auto_start/auto_start_04_phases.md +++ /dev/null @@ -1,28 +0,0 @@ -# 自動起動計画: 04 実装ステップ - -[計画トップ](auto_start.md) - ---- - -## 実装ステップ(案) - -| 段階 | 内容 | -|------|------| -| **Phase 1** | `tauri-plugin-autostart` を導入。[02 技術方針の「導入の手順」](auto_start_02_tech.md#32-導入の手順phase-1-で行うこと)(Cargo.toml、プラグイン登録、capability 必要なら追加)を実施。フロントまたは Tauri コマンドから `enable` / `disable` / `isEnabled` を呼べるようにする。**動作確認**: 有効化後に OS をログアウト→ログイン(または再起動)し、TelosDB が自動起動することを手動で確認する。 | -| **Phase 2** | 設定の永続化と連携。「ログイン時自動起動」のオン・オフを保存し、起動時に設定を読み込んでプラグインの状態と同期する。 | -| **Phase 3** | **UI 改造**([03 UI 改造](auto_start_03_ui.md))。設定パネルに「ログイン時に自動起動する」トグルを追加し、表示・トグル操作で enable/disable と設定保存を行う。06 仕様の「非表示」を自動起動分だけ「表示」に更新する。 | -| **Phase 4(任意)** | macOS / Linux ビルドで自動起動の動作確認。各 OS でもログアウト→ログイン(または再起動)で自動起動することを手動確認する。 | - -**動作確認の注意**: 自動起動の検証は**手動**で行う(ログアウト→ログインまたは再起動)。CI での自動テストは難しいため、リリース前チェックリストに「自動起動オンでログインし直し、アプリが起動することを確認」を入れる。 - ---- - -## テスト・検証 - -| 種別 | 内容 | -|------|------| -| **単体** | Tauri コマンドまたはフロントから `enable()` / `disable()` / `isEnabled()` を呼び、戻り値やレジストリ・LaunchAgents の書き換えが期待どおりか検証する。プラグインをモックに差し替えて「設定保存と API 呼び出しの対応」をテストするのも可。 | -| **結合** | 起動時に保存済み設定を読み、`isEnabled()` と不一致なら `enable`/`disable` で同期する流れをテスト。設定をオフ→オン→オフと変更したときに毎回正しく API が呼ばれるか。 | -| **UI / E2E** | 既存の [E2E(WebdriverIO)](https://github.com/tauri-apps/webdriver-example) や `tests/e2e/` を使い、設定パネルを開いて「ログイン時自動起動」トグルを操作し、表示が変わること・保存されることを検証する([12 UI テスト方針](../../specification/12_ui_testing_options.md) 参照)。 | -| **手動** | 自動起動をオンにし、OS をログアウト→ログイン(または再起動)して TelosDB が起動することを確認。オフにした場合は起動しないことを確認。インストーラでインストールしたバイナリでも同様に確認する。 | -| **リリース前** | 上記に加え、アンインストール後に Run キー(または LaunchAgents / autostart)にエントリが残っていないことを確認するチェックを入れる。 | diff --git a/docs/plans/auto_start/auto_start_05_considerations.md b/docs/plans/auto_start/auto_start_05_considerations.md deleted file mode 100644 index 8f94459..0000000 --- a/docs/plans/auto_start/auto_start_05_considerations.md +++ /dev/null @@ -1,16 +0,0 @@ -# 自動起動計画: 05 注意事項・未決定 - -[計画トップ](auto_start.md) - ---- - -## 注意事項・未決定 - -- **トレイ起動**: 自動起動時にウィンドウを表示しない「トレイのみ」で起動するか、通常どおりウィンドウを出すか。仕様で決める。 -- **権限・ユーザー操作**: Windows では Run キーはユーザー単位。macOS の Launch Agent もユーザー単位。管理者権限は不要の想定。 -- **競合**: 既に別の方法(タスクスケジューラ等)で同じアプリをログイン時に起動している場合、二重起動にならないか確認する。プラグインは一般的な 1 エントリ追加なので、他で同じ実行ファイルを登録していなければ通常は 1 つだけ起動する。 -- **enable/disable の失敗**: 権限不足やプラグイン未初期化などで `enable()` / `disable()` が失敗した場合、トグル操作時にエラーメッセージを表示し、設定と実状態の不整合を防ぐ。 -- **アンインストール時**: アプリ削除時にレジストリ Run や LaunchAgents のエントリが残らないか確認する。NSIS 等のアンインストーラで Run キーを削除する処理が必要な場合、インストーラ設定に含める。 -- **リリース目標**: 本機能をどのバージョン(例: 0.3.3)に含めるか、他計画(フォルダ監視・LDA)との優先度と合わせて決める。 -- **同一マシンで Community と Pro の両方**: 両方インストールし、両方で「自動起動オン」にした場合は、ログイン時に**両方**起動する。通常は片方のみ使う想定だが、挙動として明記しておく。 -- **動作確認**: 自動起動の有無はログアウト→ログインまたは再起動でしか確認できない。テスト手順に「手動でログインし直して起動を確認」を含める([04 実装ステップ](auto_start_04_phases.md))。 diff --git a/docs/plans/auto_start/auto_start_06_references.md b/docs/plans/auto_start/auto_start_06_references.md deleted file mode 100644 index 237ca5e..0000000 --- a/docs/plans/auto_start/auto_start_06_references.md +++ /dev/null @@ -1,12 +0,0 @@ -# 自動起動計画: 06 参照 - -[計画トップ](auto_start.md) - ---- - -## 参照 - -- [tauri-plugin-autostart](https://github.com/tauri-apps/tauri-plugin-autostart) — 公式プラグイン(Builder の args / app_name、各 OS の登録先) -- [Tauri v2 Autostart プラグイン](https://v2.tauri.app/plugin/autostart/) -- Tauri 2 の **capability / permission**: プラグイン利用に必要な権限を `capabilities` に記載する必要がある場合は、プラグインのドキュメントを確認する。 -- 既存仕様: `docs/specification/06_ui_design_spec.md`(設定パネル・ログイン時起動の「非表示」記載) diff --git a/docs/plans/cross_platform.md b/docs/plans/cross_platform.md new file mode 100644 index 0000000..278db24 --- /dev/null +++ b/docs/plans/cross_platform.md @@ -0,0 +1,44 @@ +# 計画: クロスプラットフォーム検証 + +## 目的 + +Windows で実装済みの自動起動(autostart)とフォルダ監視(folder_monitor)を macOS / Linux で検証し、プラットフォーム固有の問題を解消する。 + +## 対象機能 + +| 機能 | 仕様書 | Windows 実装 | +|------|--------|-------------| +| 自動起動 | [13_autostart.md](../specification/13_autostart.md) | ✅ v0.3.3 | +| フォルダ監視 | [14_folder_monitor.md](../specification/14_folder_monitor.md) | ✅ v0.3.3 | + +## 検証項目 + +### 自動起動 + +| OS | 検証内容 | 状態 | +|----|---------|------| +| macOS | Launch Agent(`~/Library/LaunchAgents/`)で起動するか。ログアウト→ログインで確認。 | ⬜ | +| Linux | XDG Autostart(`~/.config/autostart/*.desktop`)で起動するか。ログアウト→ログインで確認。 | ⬜ | +| macOS | `--minimized` 引数でトレイのみ起動が動作するか。 | ⬜ | +| Linux | 同上。 | ⬜ | + +### フォルダ監視 + +| OS | 検証内容 | 状態 | +|----|---------|------| +| macOS | FSEvents でファイル追加・更新・削除イベントが検知されるか。 | ⬜ | +| Linux | inotify でファイル追加・更新・削除イベントが検知されるか。 | ⬜ | +| macOS | サンドボックス環境での監視パス権限。entitlement が必要か確認。 | ⬜ | +| Linux | `max_user_watches` が小さい環境で大量ファイルを監視した場合のエラーハンドリング。 | ⬜ | + +### アンインストール + +| OS | 検証内容 | 状態 | +|----|---------|------| +| Windows | NSIS アンインストーラが Run キーを自動削除するか。残留した場合の影響。 | ⬜ | +| macOS | アンインストール時に LaunchAgents の plist が残留しないか。 | ⬜ | +| Linux | アンインストール時に `.desktop` ファイルが残留しないか。 | ⬜ | + +## 優先度 + +中。Windows で動作確認済みのため、macOS / Linux ビルドを出す際に実施する。 diff --git a/docs/plans/folder_monitor/folder_monitor.md b/docs/plans/folder_monitor/folder_monitor.md deleted file mode 100644 index 2a47b71..0000000 --- a/docs/plans/folder_monitor/folder_monitor.md +++ /dev/null @@ -1,28 +0,0 @@ -# 計画: 指定フォルダ内のファイル追加・削除・更新を監視する仕組み - -## 1. 目的 - -ユーザーが指定したフォルダを監視し、以下のイベントを検知する仕組みを用意する。 - -- **ファイル追加**: フォルダ内に新規ファイルが作成されたとき -- **ファイル削除**: フォルダ内のファイルが削除されたとき -- **ファイル更新**: 既存ファイルの内容が変更されたとき - -検知した結果を TelosDB の文書取り込み(ドキュメント・チャンクの登録・更新・削除)に連携し、指定フォルダと DB の内容を同期させることを想定する。 - -**リリース目標**: **Windows 版の実装を v0.3.3 に含める**。Phase 1〜3(単一フォルダ監視・DB 連携・設定 UI・永続化)を Windows で実装し、0.3.3 で出荷する。macOS / Linux およびネットワークフォルダの検証・ポーリングフォールバックは Phase 5 として以降のバージョンに回す。 - ---- - -## 2. 検討事項別ドキュメント - -各検討事項は別ファイルに分割している。 - -| No. | 項目 | ファイル | 内容 | -|-----|------|----------|------| -| 01 | **スコープ** | [folder_monitor_01_scope.md](folder_monitor_01_scope.md) | 対応プラットフォーム、監視対象の種類・パス・深さ、対象ファイル、動作タイミング。 | -| 02 | **技術方針** | [folder_monitor_02_tech.md](folder_monitor_02_tech.md) | notify、デバウンス、ネットワーク・フォールバック、プラットフォーム別注意点、Config、既存機能連携、設定保存。 | -| 03 | **実装方針(OS・プロトコル別)** | [folder_monitor_03_os_protocol.md](folder_monitor_03_os_protocol.md) | OS × ファイルプロトコル別の Watcher 選択、判定、共通処理。 | -| 04 | **実装ステップ** | [folder_monitor_04_phases.md](folder_monitor_04_phases.md) | Phase 1〜5 の実装順序。**テスト・検証**(単体・結合・手動・UI/E2E・Phase 別)を含む。 | -| 05 | **注意事項・未決定** | [folder_monitor_05_considerations.md](folder_monitor_05_considerations.md) | 権限、パス正規化、ネットワーク制約、大容量フォルダ、UI。 | -| 06 | **参照・調査元** | [folder_monitor_06_references.md](folder_monitor_06_references.md) | notify / debouncer / inotify / macOS 等の公式ドキュメント・リンク。 | diff --git a/docs/plans/folder_monitor/folder_monitor_01_scope.md b/docs/plans/folder_monitor/folder_monitor_01_scope.md deleted file mode 100644 index 17c5d7e..0000000 --- a/docs/plans/folder_monitor/folder_monitor_01_scope.md +++ /dev/null @@ -1,17 +0,0 @@ -# フォルダ監視: 01 スコープ - -[計画トップ](folder_monitor.md) - ---- - -## スコープ - -| 項目 | 内容 | -|------|------| -| **対応プラットフォーム** | **Windows**(現行)、**macOS**、**Linux**。Tauri 2 の対応 OS に合わせて監視機能も各 OS で動作させる。 | -| **監視対象の種類** | **ローカルフォルダ**(各 OS の通常のパス)に加え、**ネットワークフォルダ**(SMB/CIFS・NFS 等でマウントされたパス)も対象とする。ネットワークパスは OS がマウント済みであれば、ローカルと同様に指定可能とする。 | -| **監視対象** | ユーザーが設定で指定する 1 つ以上のディレクトリパス(例: Windows `C:\Users\...\Documents\TelosDB-watch`、macOS `/Users/.../Documents/TelosDB-watch`、Linux `/home/.../Documents/TelosDB-watch`、ネットワーク `//server/share/watch` や `/mnt/nfs/watch` など)。 | -| **監視の深さ** | 指定フォルダ直下のみ / サブフォルダ再帰のいずれかを設定で選択可能とする(案)。 | -| **対象ファイル** | 拡張子でフィルタ(例: `.txt`, `.md`, `.json` など)。MIME 対応済みの形式を優先。 | -| **動作タイミング** | アプリ起動中の常時監視。設定で監視のオン・オフを切り替え可能とする。 | -| **MCP・API との関係** | **能動的なプッシュは不要**。監視で検出した変化は DB 取り込み・ベクトル化まで内部で完結する。MCP クライアント(Cursor 等)や HTTP API は従来どおり「検索」「件数取得」などで**現在の DB 状態を参照する(プル)**だけ。 | diff --git a/docs/plans/folder_monitor/folder_monitor_02_tech.md b/docs/plans/folder_monitor/folder_monitor_02_tech.md deleted file mode 100644 index 3dc591b..0000000 --- a/docs/plans/folder_monitor/folder_monitor_02_tech.md +++ /dev/null @@ -1,80 +0,0 @@ -# フォルダ監視: 02 技術方針 - -[計画トップ](folder_monitor.md) - ---- - -## 3.0 設計: 監視プロトコルとドライバ - -**方針**: 監視の「やり方」を共通プロトコル(トレイト/インターフェース)で定義し、OS・ファイルシステム・ネットワーク種別ごとに**ドライバ**を用意する。 - -- **プロトコル(共通インターフェース)** - - 監視の開始・停止、イベントの購読など、呼び出し側が依存する操作だけを定義する。 - - 例: `watch(path, recursive)` → ハンドル、`EventStream` またはコールバックで `Create` / `Remove` / `Modify` を受け取る、`unwatch` / `stop`。 -- **ドライバ** - - 上記プロトコルを実装する。中身は [03 OS・プロトコル別](folder_monitor_03_os_protocol.md) のマトリクスに沿い、**ネイティブ監視**(RecommendedWatcher)か**ポーリング**(PollWatcher)のどちらか+設定で表現する。 - - 実装の切り口は「OS×ネットワーク」の全組み合わせを個別クラスにする必要はなく、**バックエンド 2 種**で足りる: - - **ネイティブドライバ**: `notify::recommended_watcher()` + デバウンス。中で OS 別 API(ReadDirectoryChangesW / FSEvents / inotify)は notify が担当。 - - **ポーリングドライバ**: `PollWatcher` + `Config`(poll_interval, 必要なら compare_contents)。ネットワーク FS・WSL・擬似 FS 等で使用。 - - **ドライバ選択**(セレクタ): パスと実行環境(OS・マウント情報など)から、上記どちらのドライバ(およびオプション)を使うかを決める。選択ロジックは [03](folder_monitor_03_os_protocol.md) の「プロトコル・ストレージ種別の判定」にまとめる。 -- **効果** - - 上位(DB 連携・設定 UI)はプロトコルだけに依存し、OS やネットワークの違いを意識しない。 - - 新たな環境(別 OS や新しいネットワーク FS)への対応は、セレクタの判定と必要なら新ドライバ(または既存ドライバの設定)の追加で済む。 - ---- - -## 3.1 監視ライブラリ: notify - -- **採用**: Rust の **`notify`** クレート(現行安定版 8.x、[crates.io](https://crates.io/crates/notify)、[docs.rs](https://docs.rs/notify/latest/notify/))を採用する。クロスプラットフォームで同一 API が使え、各 OS のネイティブ API を利用する。 -- **バックエンド(プラットフォーム別)**: - - **Windows**: `ReadDirectoryChangesW` - - **macOS**: FSEvents(デフォルト)。feature `macos_kqueue` で kqueue に切り替え可能。 - - **Linux / Android**: inotify - - **BSD 系**: kqueue -- **推奨 Watcher**: `notify::recommended_watcher()` で、そのプラットフォームに最適な実装(`RecommendedWatcher`)を取得する。イベント駆動で CPU 負荷が低い。 -- **イベント種別**: `EventKind` の `Create`, `Remove`, `Modify` 等を区別して扱う。`RecursiveMode::Recursive` でサブディレクトリも監視可能。 - -## 3.2 デバウンス - -- **目的**: 同一ファイルへの短時間の連続変更(エディタの自動保存・一括書き換え等)を、1 回の「更新」にまとめる。 -- **手段**: **`notify-debouncer-mini`**([docs.rs](https://docs.rs/notify-debouncer-mini/latest/notify_debouncer_mini/))を利用する。`new_debouncer(Duration::from_secs(2), callback)` のように時間幅を指定し、その間のイベントを集約してコールバックに渡す。 -- **代替**: より高度な処理(Rename の追跡・重複 Create の除去等)が必要なら `notify-debouncer-full` を検討する。TelosDB では「追加・削除・更新」の 3 種で十分な場合は mini で足りる。 -- **注意**: debouncer-mini は内部でスレッドを使いブロッキング受信するため、Tauri の async ループからは `spawn_blocking` や専用スレッドでラップし、結果をチャンネルで async 側に渡す構成が無難。 - -## 3.3 ネットワークフォルダ・フォールバック - -- **公式の既知問題**([notify Known Problems](https://docs.rs/notify/latest/notify/)): - - **ネットワークマウント(NFS 等)**: 多くのネットワーク FS ではネイティブの変更通知が発火しない。WSL 上で Windows パスを監視する場合も同様(issue #254)。 - - **対処**: **`PollWatcher`** バックエンドを使う。`notify::Config::default().with_poll_interval(Duration::from_secs(30))` でポーリング間隔を指定し、`notify::WatcherKind::PollWatcher` で明示的に PollWatcher を生成する。デフォルトのポーリング間隔は 30 秒。大容量ツリーでは負荷が高いため、間隔の調整や「ネットワークパス用」の別ワッチャーとして扱う設計がよい。 -- **その他で PollWatcher が推奨されるケース**: Docker on macOS M1(Function not implemented)、`/proc` や `/sys` などの擬似 FS、macOS で「自分が所有していないファイル」を FSEvents で追う場合([FileSystemEventSecurity](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/FSEvents_ProgGuide/FileSystemEventSecurity/FileSystemEventSecurity.html))。 -- **実装方針**: まずは `RecommendedWatcher` で監視を開始し、ネイティブ監視が失敗するか、ネットワークパスであることを検出した場合に、同じ設定オブジェクトで `PollWatcher` に切り替えるフォールバックを用意する。ネットワークパスかどうかは、パスがマウントポイントか、または `watch` 登録時のエラー種別で判断する。 - -## 3.4 プラットフォーム別の注意点 - -- **Linux: inotify の上限** - - `max_user_watches`(デフォルト 8192、カーネルによっては 1048576)を超えると「No space left on device」や「upper limit on inotify watches reached」が出る。再帰監視では「監視対象ディレクトリ内のファイル・フォルダ数」がそのまま watch 数に効く。 - - 対処: ユーザーに `sysctl fs.inotify.max_user_watches=524288` 等の増設を案内するか、監視対象が大きい場合は初めから **PollWatcher** を使う選択肢を設ける。PollWatcher は inotify の上限に縛られない。 -- **macOS: サンドボックス** - - サンドボックス環境では、監視できるパスが権限付与された範囲に限られる。[Accessing files from the macOS App Sandbox](https://developer.apple.com/documentation/security/accessing_files_from_the_macos_app_sandbox) に従い、必要なら `com.apple.security.temporary-exception.files.home-relative-path.read-only` 等の entitlement を検討する。Tauri アプリがサンドボックスを有効にする場合、ユーザーが「監視フォルダ」を選択したパスがその例外に含まれるようにする必要がある。 -- **エディタの保存挙動** - - 編集ツールによっては「上書き保存」で truncate して書き直すため、Notify では Remove + Create や複数回の Modify に見えることがある。デバウンスと「同一パスは最後のイベントで 1 回だけ再取り込み」とする方針で吸収する。 - -## 3.5 Config とオプション(notify) - -- **`Config::with_poll_interval(dur)`**: PollWatcher 用。再スキャン間隔(デフォルト 30 秒)。ツリーが大きい場合は 60 秒などに延ばす検討。 -- **`Config::with_compare_contents(true)`**: PollWatcher 用。変更検知を mtime ではなくファイル内容のハッシュで行う。`/proc` 等で有効。通常のローカル/ネットワークではオフでよい(パフォーマンス影響大)。 -- **`Config::with_follow_symlinks(bool)`**: シンボリックリンクをたどって監視するか。デフォルトは true。同一実体の二重登録を防ぐなら false にする選択肢がある。 - -## 3.6 既存機能との連携 - -- **方向**: 監視 → DB の**一方向**。検出イベントを内部の取り込みパイプラインに渡すだけでよく、MCP や HTTP API へ「新規追加しました」などを能動的に通知(プッシュ)する仕様は設けない。クライアントは必要時に `search_text` や `get_document_count` 等で現在状態を取得すれば足りる([01 スコープ](folder_monitor_01_scope.md#スコープ))。 -- **追加**: 新規ファイル検知 → 既存の文書取り込みパイプライン(チャンク分割・ベクトル化・`documents` / `items` / `vec_items` / FTS 登録)を呼び出す。 -- **更新**: 変更検知 → 当該パスに紐づく既存ドキュメントを更新(再取り込み)する。 -- **削除**: 削除検知 → 当該パスに紐づくドキュメントを `documents` から削除(関連 `items` / `vec_items` / FTS も連動削除)。 -- **親フォルダ削除**: notify の仕様上、`/a/b/` 以下の削除イベントを受け取るには親 `/a` を watch する必要がある。再帰監視では通常その前提が満たされるが、直下のみ監視する場合は注意する([notify ドキュメント](https://docs.rs/notify/latest/notify/))。 - -## 3.7 設定の保存 - -- 監視対象フォルダパス・再帰の有無・対象拡張子・監視オン/オフは、アプリの設定(Windows は `%APPDATA%\com.telosdb.app\`、macOS/Linux は各 OS のアプリ設定ディレクトリ、または既存の localStorage と連携する API)に永続化する。 -- 設定変更時に、監視ワッチャーを再起動(購読パスの付け替え)する。 -- **パス表記**: プラットフォームごとのパス形式(Windows の `C:\`、macOS/Linux の `/`、ネットワークの `//` や `/mnt/` 等)をそのまま保存し、実行環境に応じて正しく解釈する。 diff --git a/docs/plans/folder_monitor/folder_monitor_03_os_protocol.md b/docs/plans/folder_monitor/folder_monitor_03_os_protocol.md deleted file mode 100644 index c4127ea..0000000 --- a/docs/plans/folder_monitor/folder_monitor_03_os_protocol.md +++ /dev/null @@ -1,58 +0,0 @@ -# フォルダ監視: 03 実装方針(OS タイプ・ファイルプロトコル別) - -[計画トップ](folder_monitor.md) - ---- - -監視対象を **OS** と **ファイルプロトコル(ストレージ種別)** の組み合わせで分類し、それぞれの実装方針を定める。共通の[監視プロトコルとドライバ設計](folder_monitor_02_tech.md#30-設計-監視プロトコルとドライバ)は [02 技術方針](folder_monitor_02_tech.md) に記載。本ドキュメントは「どの組み合わせでどのドライバ(ネイティブ or ポーリング)を使うか」のマトリクスと判定方針。 - -## 4.1 マトリクス概要 - -| OS | ローカル FS | SMB/CIFS(ネットワーク共有) | NFS | その他(擬似 FS・WSL 等) | -|----|-------------|------------------------------|-----|---------------------------| -| **Windows** | RecommendedWatcher(ReadDirectoryChangesW) | 要検証。失敗時は PollWatcher。 | 同上。 | WSL で Windows パス監視は PollWatcher。 | -| **macOS** | RecommendedWatcher(FSEvents)。非所有ファイルは PollWatcher。 | PollWatcher 推奨。 | PollWatcher 推奨。 | Docker M1 等は PollWatcher。 | -| **Linux** | RecommendedWatcher(inotify)。watch 数上限に注意。 | PollWatcher 推奨。 | PollWatcher 推奨。 | /proc, /sys は PollWatcher(compare_contents 検討)。 | - -## 4.2 OS タイプ別 - -### Windows - -| プロトコル・種別 | 実装方針 | 備考 | -|------------------|----------|------| -| **ローカル** | `RecommendedWatcher`(ReadDirectoryChangesW)。デバウンスは `notify-debouncer-mini`。 | ネイティブで安定。パスは `C:\` 等。 | -| **SMB/CIFS** | まず `RecommendedWatcher` で `watch`。失敗またはイベントが来ない場合は **PollWatcher** に切り替え。`with_poll_interval(Duration::from_secs(30))` 等。 | `\\server\share\...` や マッピンドライブ(`Z:\`)はネットワーク経路のため、多くの環境でネイティブ通知が発火しない。 | -| **NFS** | 同上。ネイティブが効かない前提で **PollWatcher** を優先してもよい。 | マウント済み NFS パスを指定された場合。 | -| **WSL 内で Windows パス** | **PollWatcher** を最初から使用。 | notify の既知問題(issue #254)。 | - -### macOS - -| プロトコル・種別 | 実装方針 | 備考 | -|------------------|----------|------| -| **ローカル** | `RecommendedWatcher`(FSEvents)。「自分が所有していないファイル」のみ監視する場合は **PollWatcher** にフォールバック。 | サンドボックス利用時は entitlement で監視パスを許可。 | -| **SMB/CIFS(マウント済み)** | **PollWatcher** を推奨。ネイティブは多くの場合発火しない。 | `/Volumes/ShareName` 等。 | -| **NFS** | **PollWatcher** を推奨。 | 同上。 | -| **Docker on M1 等** | **PollWatcher**。ネイティブは "Function not implemented" になる。 | コンテナ内で監視する場合。 | - -### Linux - -| プロトコル・種別 | 実装方針 | 備考 | -|------------------|----------|------| -| **ローカル** | `RecommendedWatcher`(inotify)。再帰監視時は **watch 数** が `max_user_watches` を超えないよう注意。超過時は PollWatcher に切り替えまたはユーザーに sysctl 案内。 | デフォルト 8192。大容量ツリーは PollWatcher の選択肢を用意。 | -| **SMB/CIFS(cifs-utils 等でマウント)** | **PollWatcher** を推奨。inotify は多くのネットワーク FS で効かない。 | `/mnt/smb/...` 等。 | -| **NFS** | **PollWatcher** を推奨。 | `/mnt/nfs/...` 等。 | -| **擬似 FS(/proc, /sys)** | **PollWatcher**。必要なら `with_compare_contents(true)` を検討(mtime が信用できないため)。 | 通常の文書監視では対象にしなくてよい。 | - -## 4.3 プロトコル・ストレージ種別の判定 - -- **ローカルかネットワークか**の判定は、実装時に次のいずれかで行う想定とする。 - - **パス prefix で推定**: Windows の `\\\\`(UNC)、Linux の `/mnt/` や `/media/` の下、macOS の `/Volumes/` の一部など。 - - **watch 登録結果**: `RecommendedWatcher` で `watch()` した直後や、一定時間イベントが来ない場合に「ネイティブが使えない」とみなし、PollWatcher に切り替える。 - - **OS のマウント情報**: 各 OS の API(例: Linux の `/proc/mounts`、macOS の `getfsstat`)でマウントポイント一覧を取得し、監視パスがネットワーク FS 上かどうかを判定する(任意の拡張)。 -- 判定結果に応じて **Watcher 種別**(RecommendedWatcher または PollWatcher)と **Config**(poll_interval の有無など)を決め、同一の「監視エンジン」インターフェースで扱う。 - -## 4.4 共通処理 - -- 上記どの組み合わせでも、**デバウンス**は `notify-debouncer-mini` で統一する(PollWatcher は元から間隔が空くため、デバウンス時間は 2〜5 秒程度でよい)。 -- **イベントの解釈**(Create → 追加、Modify → 更新、Remove → 削除)と **DB 連携**は、OS・プロトコルに依存せず共通ロジックとする。 -- **設定の保存**・**パス表記**は [02 技術方針 3.7](folder_monitor_02_tech.md#37-設定の保存) のとおり。プロトコル別の特別な設定項目(例: 「ネットワークパス用ポーリング間隔」)は必要に応じて追加する。 diff --git a/docs/plans/folder_monitor/folder_monitor_04_phases.md b/docs/plans/folder_monitor/folder_monitor_04_phases.md deleted file mode 100644 index 338acb8..0000000 --- a/docs/plans/folder_monitor/folder_monitor_04_phases.md +++ /dev/null @@ -1,29 +0,0 @@ -# フォルダ監視: 04 実装ステップ - -[計画トップ](folder_monitor.md) - ---- - -## 実装ステップ(案) - -| 段階 | 内容 | v0.3.3(Windows) | -|------|------|-------------------| -| **Phase 1** | 単一フォルダの監視のみ。`notify` で Create/Remove/Modify を検知し、ログ出力またはイベント送信まで。DB 連携は行わない。 | ✅ 含める | -| **Phase 2** | 検知イベントと既存の文書取り込み(MCP 経由または内部 API)を接続。追加・更新・削除それぞれのハンドラを実装。 | ✅ 含める | -| **Phase 3** | 設定 UI(監視フォルダパス・オン/オフ・対象拡張子)の追加と、設定の永続化・ワッチャー再起動。 | ✅ 含める | -| **Phase 4** | 複数フォルダ対応・再帰監視オプション・デバウンス時間の調整など、運用面の拡張。 | 以降 | -| **Phase 5(任意)** | macOS / Linux ビルドでの動作確認と、ネットワークフォルダ監視の検証。ネイティブ通知が使えない場合のポーリングフォールバック実装。[03 OS・プロトコル別方針](folder_monitor_03_os_protocol.md)のマトリクスに沿った Watcher 切り替えの実装。 | 以降 | - -**v0.3.3 の範囲**: Windows 上で Phase 1〜3 までを実装・出荷する。ローカルフォルダを RecommendedWatcher(ReadDirectoryChangesW)で監視し、設定 UI と DB 連携まで含める。 - ---- - -## テスト・検証 - -| 種別 | 内容 | -|------|------| -| **単体** | `notify` の `watch` / `unwatch` およびデバウンス(`notify-debouncer-mini`)が、指定ディレクトリ配下の Create/Modify/Remove を期待どおり集約してコールバックに渡すかを、一時ディレクトリとテスト用ファイルで検証する。 | -| **結合** | イベント受信後に DB 連携(追加・更新・削除のハンドラ)が呼ばれることを、テスト用 DB またはインメモリ DB で検証。既存の文書取り込み API をモックにしてもよい。 | -| **手動** | 監視対象フォルダにファイルを追加・編集・削除し、ログまたは UI でイベントが検知されること、および DB に文書が反映される(または削除される)ことを確認する。デバウンス時間内の連続変更が 1 回にまとまることも確認。 | -| **UI / E2E** | 設定パネルで監視フォルダパスを指定し、オン/オフを切り替えて保存できることを、既存 [E2E](https://v2.tauri.app/develop/tests/webdriver/) や [12 UI テスト方針](../../specification/12_ui_testing_options.md) に沿って検証する(実装後にスペック追加)。 | -| **Phase 別** | Phase 1: イベント検知の単体テスト。Phase 2: イベント→DB 連携の結合テスト。Phase 3: 設定 UI の表示・永続化・ワッチャー再起動のテスト。 | diff --git a/docs/plans/folder_monitor/folder_monitor_05_considerations.md b/docs/plans/folder_monitor/folder_monitor_05_considerations.md deleted file mode 100644 index b664578..0000000 --- a/docs/plans/folder_monitor/folder_monitor_05_considerations.md +++ /dev/null @@ -1,13 +0,0 @@ -# フォルダ監視: 05 注意事項・未決定 - -[計画トップ](folder_monitor.md) - ---- - -## 注意事項・未決定 - -- **権限**: 監視対象フォルダへの読み取り権限が無い場合のエラー表示と、設定画面での再指定を促す動線。ネットワークフォルダでは、マウント時やログオン時の認証・再接続が必要な場合がある。 -- **パス正規化**: Windows の短いパス・ジャンクション・シンボリックリンク、macOS/Linux のシンボリックリンク・バインドマウントの扱いをどうするか(同一ファイルの二重登録を防ぐ)。ネットワークパスは OS ごとのマウントポイントの違い(例: Windows `\\server\share`、Linux `/mnt/smb/share`)を考慮する。 -- **ネットワークフォルダの制約**: 一部のネットワーク FS は inotify/FSEvents/ReadDirectoryChangesW をサポートしない。その場合はポーリング間隔の設定や「ネットワークパスでは監視が限定的」である旨の UI 表示を検討する。 -- **大容量フォルダ**: 監視開始時に既存ファイルを一括スキャンするか、監視開始後の変更のみ扱うか。既存ファイルの初回同期は別機能(「フォルダをインポート」)に任せる案もある。 -- **UI の扱い**: 現状、設定画面の「モニター先フォルダ」は非表示。本機能を有効にする際に、当該パネルを再度表示するか、別タブ・別画面にするか。 diff --git a/docs/plans/folder_monitor/folder_monitor_06_references.md b/docs/plans/folder_monitor/folder_monitor_06_references.md deleted file mode 100644 index afa1b84..0000000 --- a/docs/plans/folder_monitor/folder_monitor_06_references.md +++ /dev/null @@ -1,16 +0,0 @@ -# フォルダ監視: 06 参照・調査元 - -[計画トップ](folder_monitor.md) - ---- - -## 参照・調査元 - -- **notify**: [notify 8.2.0 - docs.rs](https://docs.rs/notify/latest/notify/)、[Known Problems](https://docs.rs/notify/latest/notify/#known-problems)(ネットワーク FS、Docker M1、macOS 非所有ファイル、Linux 上限、エディタ挙動、親フォルダ削除)。 -- **notify Config**: [Config - docs.rs](https://docs.rs/notify/latest/notify/struct.Config.html)(poll_interval, compare_contents, follow_symlinks)。 -- **notify-debouncer-mini**: [notify-debouncer-mini - docs.rs](https://docs.rs/notify-debouncer-mini/latest/notify_debouncer_mini/)。 -- **Linux inotify**: [Watchexec - inotify limits](https://watchexec.github.io/docs/inotify-limits.html)、`max_user_watches` / `max_user_instances` の意味と増やし方。 -- **macOS**: [File System Event Security](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/FSEvents_ProgGuide/FileSystemEventSecurity/FileSystemEventSecurity.html)、[Accessing files from the macOS App Sandbox](https://developer.apple.com/documentation/security/accessing_files_from_the_macos_app_sandbox)。 -- 既存の文書取り込み: MCP ツール `add_item_text`、ドキュメント登録のフロー(`documents` / `items` の作成)。 -- データベース仕様: `docs/specification/03_database_specification.md`。 -- 設定の永続化: 現状の検索設定(localStorage)との棲み分け。 diff --git a/docs/plans/folder_monitor_enhancements.md b/docs/plans/folder_monitor_enhancements.md new file mode 100644 index 0000000..6e2bbfb --- /dev/null +++ b/docs/plans/folder_monitor_enhancements.md @@ -0,0 +1,91 @@ +# 計画: フォルダ監視の拡張 + +## 目的 + +現在の `RecommendedWatcher`(ネイティブ監視)一本の実装を拡張し、ネットワーク FS 対応・パフォーマンス改善・エラーハンドリング強化を行う。 + +関連仕様: [14_folder_monitor.md](../specification/14_folder_monitor.md) + +--- + +## 1. PollWatcher フォールバック(ネットワーク FS 対応) + +### 背景 + +多くのネットワーク FS(SMB/CIFS・NFS 等)では `RecommendedWatcher` のネイティブ通知が発火しない([notify Known Problems](https://docs.rs/notify/latest/notify/#known-problems))。WSL 上で Windows パスを監視する場合も同様。 + +### 方針 + +`RecommendedWatcher` が使えない環境では **`PollWatcher`** にフォールバックする。 + +| 条件 | Watcher | +|------|---------| +| ローカル FS | `RecommendedWatcher`(ネイティブ) | +| SMB/CIFS・NFS 等 | `PollWatcher`(`poll_interval: 30s`) | +| WSL 上の Windows パス | `PollWatcher` | + +### ネットワークパスの判定 + +以下のいずれかで判定する: + +- **パス prefix**: Windows の `\\`(UNC)、Linux の `/mnt/`・`/media/`、macOS の `/Volumes/` +- **watch 登録結果**: `RecommendedWatcher` の `watch()` 失敗時、または一定時間イベントが来ない場合にフォールバック +- **OS マウント情報**: `/proc/mounts`(Linux)、`getfsstat`(macOS)等で判定(任意の拡張) + +### notify Config + +| オプション | 用途 | 想定値 | +|-----------|------|--------| +| `with_poll_interval(dur)` | 再スキャン間隔 | 30 秒(大容量ツリーは 60 秒) | +| `with_compare_contents(bool)` | mtime が信用できない FS 向け(`/proc` 等) | 通常 false | + +--- + +## 2. 大容量フォルダの初期スキャン + +### 問題 + +モニター先追加時の初期スキャンは再帰走査 + 逐次取込のため、大量ファイルがあると長時間かかる。 + +### 対策案 + +- プログレス表示(取込済み / 全体のカウントを UI に送信) +- バッチ制御(一定数ごとに `yield` して他の処理をブロックしない) +- 初期スキャンをバックグラウンドタスク化し、監視は先に開始する + +--- + +## 3. 権限エラー時の UI フィードバック + +### 問題 + +監視対象フォルダへの読み取り権限がない場合、`watch()` や `read_dir()` がエラーを返すが、ユーザーへの通知が `log::warn` のみ。 + +### 対策案 + +- 設定保存時にパスの存在・読み取り権限をチェックし、UI にエラーを表示 +- 監視開始時のエラーをフロントに通知し、設定パネルで該当行をハイライト + +--- + +## 4. パス正規化 + +### 問題 + +シンボリックリンク・ジャンクション・バインドマウントを経由した場合、同一ファイルが異なるパスで検知され、二重登録になる可能性がある。 + +### 対策案 + +- `std::fs::canonicalize()` でパスを正規化してから DB パスと照合 +- `Config::with_follow_symlinks(false)` でリンクをたどらない選択肢 + +--- + +## 優先度 + +| 項目 | 優先度 | +|------|--------| +| PollWatcher フォールバック | 中 | +| 大容量フォルダ初期スキャン | 低 | +| 権限エラー UI | 低 | +| パス正規化 | 低 | diff --git a/docs/specification/06_ui_design_spec.md b/docs/specification/06_ui_design_spec.md index e8f704e..dbafa7b 100644 --- a/docs/specification/06_ui_design_spec.md +++ b/docs/specification/06_ui_design_spec.md @@ -16,7 +16,7 @@ ## 3. 設定パネル -- **表示する項目**: 検索まわり(スコア足切り 0〜1、取得件数)、**ログイン時自動起動**(計画 auto_start)、**モニター先フォルダ**(計画 folder_monitor)。保存はアプリ設定(settings.json)および localStorage(キー `telosdb_settings`)。 +- **表示する項目**: 検索まわり(スコア足切り 0〜1、取得件数)、**ログイン時自動起動**([13_autostart.md](13_autostart.md))、**モニター先フォルダ**([14_folder_monitor.md](14_folder_monitor.md))。保存はアプリ設定(settings.json)および localStorage(キー `telosdb_settings`)。 ## 4. ステータス・アクティビティ diff --git a/docs/specification/13_autostart.md b/docs/specification/13_autostart.md new file mode 100644 index 0000000..23aca64 --- /dev/null +++ b/docs/specification/13_autostart.md @@ -0,0 +1,239 @@ +# 自動起動仕様 (Autostart Specification) + +## 1. 概要 + +OS にユーザーがログインしたタイミングで TelosDB を自動的に起動し、システムトレイで待機させる。ユーザーが手動で起動しなくても MCP サーバーや検索機能を利用可能にする。 + +```mermaid +flowchart LR + subgraph ユーザー操作なし + A[OS ログイン] --> B[TelosDB 自動起動] + B --> C[トレイで待機] + C --> D[MCP / 検索 利用可能] + end +``` + +## 2. スコープ + +| 項目 | 仕様 | +|------|------| +| **対応プラットフォーム** | Windows / macOS / Linux。Tauri 2 の対応 OS に準拠する。 | +| **トリガー** | ユーザーが OS に**ログイン(サインイン)**したとき。ロック画面からの解除やスリープ復帰では発火しない。 | +| **デフォルト** | **オフ**(`run_on_login: false`)。設定キーが存在しない場合(初回・アップデート後)もオフとして扱う。 | +| **起動後の挙動** | 自動起動時: `--minimized` 引数によりウィンドウを非表示にし、トレイのみで待機。手動起動時: 通常どおりウィンドウを表示。いずれもウィンドウを閉じるとトレイに常駐する。 | +| **設定の保存** | `settings.json`(Tauri AppData ディレクトリ)に永続化。フロント側は `localStorage`(キー `telosdb_settings`)にもキャッシュする。 | +| **対象エディション** | Community 版・Pro 版の両方で利用可能。エディション間に差異はない。 | + +## 3. 技術構成 + +### 3.1 プラグイン + +[tauri-plugin-autostart](https://github.com/tauri-apps/tauri-plugin-autostart) を使用する。 + +| 依存 | パッケージ | バージョン | +|------|-----------|-----------| +| Rust | `tauri-plugin-autostart` | `2.5.1` | +| JS | `@tauri-apps/plugin-autostart` | `^2.5.1` | + +> Rust 側と JS 側のバージョンは揃えること。 + +### 3.2 プラットフォーム別の登録先 + +プラグインが各 OS のネイティブ機構を使って自動起動を登録する。 + +| OS | 登録先 | +|----|--------| +| Windows | レジストリ `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` | +| macOS | Launch Agent(`~/Library/LaunchAgents/` に plist を配置) | +| Linux | XDG Autostart(`~/.config/autostart/*.desktop`) | + +```mermaid +flowchart TB + subgraph プラットフォーム別の実体 + W[Windows: レジストリ Run] + M[macOS: LaunchAgents] + L[Linux: autostart .desktop] + end + P[tauri-plugin-autostart] --> W + P --> M + P --> L + U[ユーザー: enable/disable] --> P +``` + +### 3.3 Rust 側プラグイン登録 + +`tauri::Builder` に以下を登録する: + +```rust +.plugin(tauri_plugin_autostart::init(MacosLauncher::LaunchAgent, None)) +``` + +### 3.4 Tauri capability + +`capabilities/default.json` に以下の権限を追加する: + +- `autostart:allow-enable` +- `autostart:allow-disable` +- `autostart:allow-is-enabled` + +### 3.5 起動引数 + +プラグインの `Builder` で `.args([...])` を指定可能。自動起動時に `--minimized` を渡すことで、トレイのみ起動を実現する。 + +## 4. API + +フロントエンドから利用する API は以下の 3 つ。 + +| 関数 | 説明 | +|------|------| +| `enable()` | 自動起動を有効にする(OS にエントリを登録)。 | +| `disable()` | 自動起動を無効にする(OS からエントリを削除)。 | +| `isEnabled()` | 現在 OS 上で自動起動が有効かどうかを返す。 | + +## 5. 設定との連携 + +### 5.1 起動時の同期 + +アプリ起動時に保存済み設定と OS の実状態を同期する。 + +```mermaid +stateDiagram-v2 + [*] --> 設定ファイル読み込み + 設定ファイル読み込み --> スキップ: 読み込み失敗 (null) + 設定ファイル読み込み --> isEnabledチェック: 読み込み成功 + isEnabledチェック --> 同期: 設定値と isEnabled() が不一致 + isEnabledチェック --> 待機: 一致 + 同期 --> enableまたはdisable + enableまたはdisable --> 待機 + 待機 --> ユーザーがトグル変更 + ユーザーがトグル変更 --> 保存してenable/disable + 保存してenable/disable --> 待機 +``` + +| 条件 | 処理 | +|------|------| +| `loadSettingsFromFile()` が `null` を返した場合 | autostart 同期を**スキップ**する。デフォルト値 `run_on_login: false` で `disable()` を呼ぶと正常登録済みエントリを削除してしまうため。 | +| 設定値と `isEnabled()` が一致 | 何もしない。 | +| 設定値と `isEnabled()` が不一致 | 設定値に合わせて `enable()` または `disable()` を呼ぶ。 | + +### 5.2 アップデート時のパス変更 + +再インストールで実行ファイルのパスが変わると、既存の Run キー等は無効になる。次回起動時の同期処理で設定がオンの場合は `enable()` を呼び直し、新しいパスで再登録する。 + +### 5.3 エラーハンドリング + +- `enable()` / `disable()` が失敗した場合: `console.error` に出力し、UI にエラーメッセージを表示する。 +- autostart 登録失敗時の保存メッセージ: 「保存しました(自動起動の登録に失敗しました。次回起動時に再試行します)」を 5 秒間表示する。 + +## 6. UI 仕様 + +### 6.1 設定パネルの表示 + +設定パネルに「ログイン時自動起動」fieldset を表示する。 + +| 項目 | 仕様 | +|------|------| +| **コントロール** | チェックボックス(``)。既存の設定項目と統一。 | +| **配置** | 検索 fieldset の直下に独立した `