diff --git a/document/01_system_overview.md b/document/01_system_overview.md index 66e7a30..dd2a003 100644 --- a/document/01_system_overview.md +++ b/document/01_system_overview.md @@ -1,41 +1,33 @@ -# システム概要仕様書 (System Overview Specification) +# システム概要 (System Overview) -## 1. 概要 +## 1. 開発背景と目的 -本システム「TelosDB」は、**sqlite-vec** 拡張機能を活用したローカル完結型のセマンティック検索基盤です。Tauri 2 を基盤とし、Model Context Protocol (MCP) を通じて外部エージェントに高度なデータ抽出能力を提供します。 +**TelosDB** は、プライバシーを重視したローカル専用の「意味検索（Vector Search）基盤」を提供するために開発されました。 -## 2. 目的 +現代の AI 活用において、外部クラウド（OpenAI 等）へのデータ送信はセキュリティ上の大きな懸念事項です。本システムは、LLM（Embedding モデル）とベクトルエンジンをすべてユーザーのローカル環境（Windows Desktop）で動作させることにより、以下の価値を提供します。 -- **プライバシー保護**: 外部 API を使用せず、ローカル環境で Embedding 生成とベクトル検索を完結。 -- **データ管理**: 高速かつ型安全なメタデータ管理と、セマンティック検索の統合。 -- **拡張性**: MCP 準拠により、Cursor や Claude などの AI エージェントからプラグイン不要で利用可能にする。 +- **絶対的なプライバシー**: 文章データやベクトルデータがネットワークを介して外部に送信されることはありません。 +- **オフライン動作**: サーバーメンテナンスやインターネット接続環境に左右されず、常に高速な検索が可能です。 +- **コストゼロ**: 推論はローカル GPU/CPU で行われるため、月額費用や API トークン費用が発生しません。 -## 3. 主要機能 +## 2. 主要機能詳説 -| 機能種別 | 機能名称 | 概要 | +| 機能 | 解説 | 技術的実装 | | :--- | :--- | :--- | -| **データ登録** | 文章自動ベクトル化 | 文章とメタデータを入力すると、内蔵 LLM がベクトルを生成し、保存。 | -| **検索** | セマンティック検索 | 自然言語による類似度検索。**sqlite-vec** を用いた高速な近傍探索。 | -| **インターフェース** | MCP Server (SSE) | SSE プロトコルを用いた JSON-RPC 2.0 インターフェースの提供。 | -| **自動復旧** | セルフヒーリング | モデル変更によるベクトル次元数の不一致を自動検知し、バックグラウンドで補完。 | -| **常駐モード** | システムトレイ | ウィンドウを閉じてもバックグラウンドで MCP サーバーが稼働を継続。 | -| **GUI** | 管理コンソール | ガラスモーフィズムを採用した UI でのデータ閲覧、検索、ログ監視。 | +| **ローカル・セマンティック検索** | キーワードの一致だけでなく、文脈や意味に基づいた検索を実現。 | `sqlite-vec` + `Gemma-3` (Local) | +| **MCP (Model Context Protocol)** | AI エージェント（Cursor, Claude Desktop, IDE 等）が本ツールを「外部知識」として呼び出すための標準規格。 | SSE Transport (Port 3001) | +| **GPU 加速推論** | モデルの推論計算を GPU で高速化。低スペック PC でも快適な動作を実現。 | Vulkan / llama-server | +| **セルフヒーリング (Self-healing)** | DB 内のテキストとベクトルの不一致を検出し、バックグラウンドで自動同期。 | `db::sync_vectors` | +| **常駐・軽量 UI** | システムトレイに常駐し、SSE を使った非同期通信でバックグラウンドログをリアルタイム表示。 | Tauri 2 + HTML/JS/Axum | -## 4. システム特性 +## 3. システム特性 (Technical Highlights) -- **Hermetic Build**: `build.rs` により依存する DLL (**sqlite-vec**) を自動管理。 -- **マルチプロセス**: Tauri コア、MCP サーバー (Axum)、推論サイドカーの協調動作。 -- **省メモリ**: Rust による効率的なプロセス管理と軽量な Gemma-3 モデルの採用。 +- **Hermetic Design**: Sidecar (`llama-server`) や必要な DLL 群をパッケージ内に封入し、ユーザー環境（MinGW や Python 等）のインストール状況に依存せず「置いてすぐ動く」ことを重視しています。 +- **Gemma-3 統合**: Google の最新軽量モデル Gemma-3 270m を採用。640 次元の高精度な埋め込み（Embedding）を、わずかなリソースで提供します。 -## 5. 動作環境要件 +## 4. 動作環境 -- **OS**: Windows 10/11 (x64) -- **CPU/GPU**: Vulkan 1.2+ 対応（推奨）または CPU 推論。 -- **Model**: Gemma-3 270m it (Q4_K_M) - 640次元。 -- **Storage**: ~500MB (モデルファイル含む) - -## 6. ユースケース - -- 個人的なナレッジベース構築。 -- プロジェクトドキュメントの高度なリファレンス検索。 -- AI エージェントに対する、コンテキストデータのセキュアな提供。 +- **OS**: Windows 10/11 (64-bit) +- **CPU**: AVX2 命令セット対応推奨 +- **GPU**: Vulkan 対応ハードウェア (オプション、自動検出) +- **モデル**: Gemma-3 270m (640 dimensions) diff --git a/document/02_architecture_design.md b/document/02_architecture_design.md index de6acb2..6005b18 100644 --- a/document/02_architecture_design.md +++ b/document/02_architecture_design.md @@ -1,76 +1,62 @@ # アーキテクチャ設計仕様書 (Architecture Design Specification) -## 1. 全体構造 +## 1. 全体構造図 -本システムは、Tauri 2 をホストとしたマルチプロセス・マルチレイヤー・アーキテクチャを採用しています。 +本システムは、OS のシステムトレイに常駐する「ホストプロセス（Tauri 2）」と、推論を担う「サイドカープロセス（llama-server）」、および外部エージェントとの通信を担う「MCP サーバ（Axum）」の 3 つが有機的に連携する構造です。 ```mermaid graph TD subgraph "Presentation Layer (Webview2)" UI["Glassmorphism UI (Vanilla JS)"] - SSE_Monitor["Activity Log / SSE Update"] + SSE_Monitor["Activity Log View (SSE)"] end subgraph "Application Layer (Rust / Tauri 2)" - Tauri["Tauri Core & Command Handlers"] - Tray["System Tray / Resident Mode"] - Axum["Axum (MCP SSE Server)"] - Broadcast["Tokio Broadcast (Internal Bus)"] + Tauri["Tauri Core (Main Process)"] + Tray["System Tray Controller"] + Axum["Axum (MCP SSE Server - Port 3001)"] + Broadcast["Tokio Broadcast Bus"] end subgraph "Infrastructure Layer" - DB["SQLite + sqlite-vec"] - LS["Sidecar: llama-server"] - M["Gemma-3 GGUF (640d)"] + DB["SQLite + sqlite-vec (telos.db)"] + LS["Sidecar: llama-server (Port 8080)"] + M["Gemma-3 Model (Local inference)"] end UI -- "IPC: Invoke" --> Tauri - Tauri -- "IPC: Invoke" --> UI - Axum -- "SSE: Update Events" --> UI - Axum -- "Broadcast Bus" --> Broadcast - Broadcast -- "Broadcast Bus" --> Axum + Tauri -- "IPC: UI Update" --> UI + Axum -- "SSE: Status Events" --> UI + Axum -- "Internal Notif" --> Broadcast + Broadcast -- "Internal Notif" --> Axum Tauri -- "SQL" --> DB DB -- "SQL" --> Tauri Axum -- "SQL" --> DB DB -- "SQL" --> Axum - Tauri -- "reqwest" --> LS - Axum -- "reqwest" --> LS + Tauri -- "HTTP/Embedding" --> LS LS -- "Inference" --> M - Tray -- "Control" --> UI + Tray -- "Command" --> UI ``` -## 2. 各層の定義 +## 2. プロセス間通信とデータフロー -### 2.1 Presentation Layer +### 2.1 Tauri Core と Axum (MCP) の連携 -- **技術**: Vanilla HTML, CSS, JavaScript (Vite 5+) -- **役割**: システムステータスの可視化、セマンティック検索 GUI、MCP アクティビティ監視。 -- **通信**: `invoke` コマンドおよび `EventSource` (SSE) によるリアルタイム同期。 +本システムの最大の特徴は、デスクトップアプリとしての GUI 管理を Tauri が行い、外部通信インターフェース（MCP）を Axum が担当する「デュアルサーバ」構成にあります。 +両者はメモリを共有していますが、非同期なデータ操作通知（例：エージェントが MCP 経由でデータを登録した際に UI の件数を増やす）には **Tokio Broadcast Channel** を使用し、疎結合な連携を実現しています。 -### 2.2 Application Layer +### 2.2 推論サイドカー (llama-server) の制御 -- **Tauri Core**: プロセスのライフサイクル管理、システムトレイ、サイドカー制御。 -- **Axum (MCP Server)**: ポート 3001 で稼働する MCP SSE サーバー。セッション管理と JSON-RPC ディスパッチを担当。 -- **Data Bus**: `tokio::sync::broadcast` を使用し、データ変更やツール呼び出しを UI へリアルタイム通知。 +Embedding 計算を行う `llama-server` は、Tauri のサイドカー機能によって起動・管理されます。 -### 2.3 Infrastructure Layer +- **起動時**: `lib.rs` の `setup` フックでサイドカーをスポーン。 +- **通信**: Rust バックエンドが `reqwest` を用いてローカルポート 8080 へ HTTP 要求を送信。 +- **終了時**: Tauri のプロセスマネージャにより、アプリ終了と同時にサイドカーも安全にクリーンアップされます。 -- **SQLite**: メタデータ（`items`）の管理。 -- **sqlite-vec (vec0)**: 仮想テーブルによるベクトル検索。動的な次元検知（640次元）に対応。 -- **Sidecar (llama-server)**: `llama.cpp` ベースの推論サーバー。埋め込み生成 API を提供。 +## 3. 各レイヤーの役割分担 -## 3. プロセス同期モデル - -| 処理 | 同期/非同期 | 説明 | -| :----------------- | :------------------- | :---------------------------------------------------------- | -| **データ更新通知** | 非同期 (SSE) | DB 変更時にブロードキャストし、UI を自動リロード。 | -| **埋め込み生成** | 非同期 (HTTP) | llama-server への POST リクエストによるベクトル取得。 | -| **一貫性制御** | 原子性 (Transaction) | `items` と `vec_items` を同一トランザクション内でコミット。 | - -## 4. ライフサイクル管理 - -1. **Setup**: 起動時にモデル・DLL・DB パスを確定。 -2. **Spawn**: `llama-server` を Sidecar として起動し、`/health` で準備完了を確認。 -3. **Sync**: DB のベクトル不整合（欠落や次元違い）をチェックし、必要に応じて自動修復。 -4. **Running**: MCP サーバーが外部接続を待機。トレイ常駐によるバックグラウンド動作。 -5. **Shutdown**: トレイメニューからの終了時、全子プロセスをクリーンに停止。 +| レイヤー | 主要コンポーネント | 役割と責務 | +| :--- | :--- | :--- | +| **Presentation** | フロントエンド (index.html) | 設定状況の表示、アクティビティログ（SSE）の可視化、システム操作。 | +| **Application** | Rust コア (`lib.rs`, `mcp.rs`) | ビジネスロジック。MCP 要求のパース、サイドカーとの通信、DB 操作のオーケストレーション。 | +| **Infrastructure** | SQLite, llama-server | データの永続化、ベクトル空間の管理、LLM 推論エンジンの実行。 | diff --git a/document/03_database_specification.md b/document/03_database_specification.md index c4018e0..233d4ff 100644 --- a/document/03_database_specification.md +++ b/document/03_database_specification.md @@ -1,71 +1,60 @@ # データベース・ベクトル検索仕様書 (Database & Search Specification) -## 1. 物理構造 +## 1. データベース設計思想 -データベースは単一の SQLite ファイル (`telos.db`) として管理されます。メタデータ管理用の標準テーブルと、**sqlite-vec** によるベクトル演算用の仮想テーブルの 2 つで構成されます。 +本システムでは、SQLite を単なるメタデータストレージとしてだけでなく、**「ベクトル検索エンジン」**としても活用しています。これにより、ACID 特性（データの整合性保証）を維持しながら、高速なセマンティック検索を実現しています。 + +### 1.1 sqlite-vec の役割 + +`sqlite-vec` エクステンションを採用することで、標準的な SQL クエリの中でベクトル間の「距離計算」が可能になります。 + +- **メリット**: 文書（Text）と特徴量（Vector）を別々のデータベースに分けずに済み、トランザクションの一貫性が保たれます。 +- **距離指標**: 本システムでは「L2 距離（二乗和の平方根）」を使用し、値が小さいほど類似度が高いと判断します。 ## 2. エンティティ関係定義 (ERD) ```mermaid erDiagram - items ||--|| vec_items : "1:1 Mapping (id)" - + items ||--|| vec_items : "Reference by ID (1:1)" + items { - integer id PK "Primary Key (Autoincrement)" - text content "文書本文" - text path "ファイルパス / 出典識別子" - datetime created_at "作成日時" - datetime updated_at "更新日時 (Auto-trigger)" + integer id PK "文書ID (自動採番)" + text content "原文テキスト" + text path "出典・メタデータ" + datetime created_at "作成日" } - + vec_items { - integer id PK "items.id と同一" - blob embedding "640-dim Vector (f32)" + integer id PK "items.id と紐付け" + blob embedding "640次元ベクトルデータ(f32)" } ``` -## 3. 詳細テーブル定義 +## 3. ベクトル検索とセルフヒーリング -### 3.1 `items` テーブル +### 3.1 `search_text` のロジック -| カラム | 型 | NULL | 初期値 | 説明 | -| :--- | :--- | :--- | :--- | :--- | -| `id` | INTEGER | NO | AUTOINC | 保存文書のユニーク ID | -| `content` | TEXT | NO | - | 元のテキストデータ | -| `path` | TEXT | YES | - | ドキュメントの出典メタデータ | +検索クエリが入力されると、システムは以下の手順を踏みます。 -### 3.2 `vec_items` (Virtual Table) +1. クエリを `llama-server` に送り、ベクトル化する。 +2. SQLite 上で `vec_items` テーブルをスキャンし、クエリベクトルに近い順（L2距離順）に `items.id` を取得。 +3. `items` テーブルから実際のテキストを取得して結合。 -**sqlite-vec** (vec0) モジュールを使用した仮想テーブルです。 +### 3.2 セルフヒーリング (Self-healing) の必要性 -- **ID**: `items.id` と同期。 -- **ベクトル構成**: - - **次元数**: **640次元** (Gemma-3 270m モデルの仕様)。 - - **データ型**: `FLOAT[640]` (内部的には BLOB) - - **L2距離**: `MATCH` 演算子による高速な近傍探索。 +モデルの変更や、インポート時の中断などにより、`items` にテキストはあるが `vec_items` に対応するベクトルが存在しない「不整合状態」が稀に発生し得ます。 +本システムは `db::sync_vectors` ロジックを備えており： -## 4. 検索仕様 +- 起動時または特定のトリガーで `items` を全走査。 +- ベクトルが欠落している行を自動検出し、サイドカー経由で再生成・補完。 +これにより、常に検索結果の網羅性を保証します。 -### 4.1 セマンティック探索クエリ +## 4. テーブル詳細 -```sql -SELECT - i.id, - i.content, - v.distance -FROM items i -JOIN vec_items v ON i.id = v.id -WHERE v.embedding MATCH :query_vector -- ベクトル近傍マッチング - AND k = :k -- 返却件数 (LIMIT とは別に必要) -ORDER BY distance; -``` +### 4.1 `items` (メタデータ管理) -### 4.2 フォールバック検索 +文書の本体と、それに付随する情報を保持します。`path` カラムは、将来的なローカルパス連携や URL 参照を想定した自由形式の文字列です。 -LLM サーバーが停止している場合、`sqlite-vec` による検索が不可能なため、`content LIKE %?%` による全文検索へ自動的にフォールバックします。 +### 4.2 `vec_items` (ベクトル演算用仮想テーブル) -## 5. 動的維持管理 (Self-Healing) - -1. **次元検知**: 起動時に内蔵 LLM サーバーからダミー埋め込みを取得し、期待される次元（640）を確認。 -2. **テーブル整合性**: `vec_items` 側のデータが不足している、または次元が異なる場合、バックグラウンドで `items` からベクトルを再生成し修復します（`db::sync_vectors`）。 -3. **トランザクション**: `items` と `vec_items` への登録はアトミックに行われ、片方のみの登録が残らないよう制御されています。 +`sqlite-vec` によって定義された仮想テーブルです。`dimensions=640` として設定されており、Gemma-3 の出力層と完全一致させています。 diff --git a/document/04_mcp_api_specification.md b/document/04_mcp_api_specification.md index a4e6a65..b3badc5 100644 --- a/document/04_mcp_api_specification.md +++ b/document/04_mcp_api_specification.md @@ -1,84 +1,55 @@ # MCP・APIインターフェース仕様書 (MCP & API Specification) -## 1. プロトコル定義 +## 1. プロトコル設計思想 -本システムは Model Context Protocol (MCP) に準拠し、外部エージェントに対してデータベース操作インターフェースを公開します。 +本システムは、Anthropic が提唱する **Model Context Protocol (MCP)** に準拠しています。これにより、IDE（Cursor 等）や外部エージェントが、本システムを単なる「静的なドキュメント」としてではなく、対話可能な「インテリジェントな知識ベース」として認識できるようになります。 -- **トランスポート**: SSE (Server-Sent Events) -- **ポート**: 3001 +### 1.1 なぜ SSE (Server-Sent Events) なのか + +MCP には Stdio と SSE の 2 つのトランスポートがありますが、本システムでは **SSE** を採用しています。 + +- **UIとの親和性**: GUI を持つデスクトップアプリでは、Stdio は標準入出力の競合が発生しやすいため、HTTP ベースの SSE が適しています。 +- **多重接続**: 同時に複数のエージェント（例：IDE と ブラウザ拡張）からの要求を並行して処理することが可能です。 + +## 2. インターフェース定義 + +- **ポート**: 3001 (固定) - **エンドポイント**: - - **Connection**: `GET /sse` - - **Message**: `POST /messages?session_id={uuid}` - - 接続時にサーバーから通知される `endpoint` イベント内のパスを使用。 + - **Connection**: `GET /sse` (接続維持・通知受取) + - **Message**: `POST /messages?session_id={uuid}` (コマンド送信) -## 2. 提供ツール定義 (Tools) +## 3. 提供ツール (Capabilities) -### 2.1 `add_item_text` (登録) +本システムのリソースへアクセスするための具体的なコマンド群です。 -文章を自動ベクトル化して登録します。 +| ツール名 | 役割 | 解説 | +| :--- | :--- | :--- | +| `add_item_text` | 文書の永続化 | テキストを Embedding 化して DB へ保存。 | +| `search_text` | 意味検索 | 記述内容の類似度に基づいたベクトル検索。 | +| `update_item` | 知識の更新 | ID 指定による既存データの書き換え。 | +| `delete_item` | 知識の抹消 | ID 指定による物理削除。 | +| `get_item_by_id` | 生データ取得 | メタデータを含むレコードの直接参照。 | -- **引数**: `content` (string, 必須), `path` (string, 任意) -- **戻り値**: 成功通知と生成された ID。 +## 4. 通信シーケンスとレスポンス形式 -### 2.2 `search_text` (意味検索) - -**sqlite-vec** を用いた自然言語検索。 - -- **引数**: `content` (string, 必須), `limit` (number, デフォルト 10) -- **戻り値**: 距離（Distance）順の検索結果リスト。 - -### 2.3 `update_item` (更新) - -既存データのテキストとベクトルを再生成して更新。 - -- **引数**: `id` (integer, 必須), `content` (string, 必須), `path` (string, 任意) - -### 2.4 `delete_item` (削除) - -指定 ID のデータを物理削除。 - -- **引数**: `id` (integer, 必須) - -### 2.5 `get_item_by_id` (取得) - -ID 指定により、メタデータを含む生データを取得。 - -- **引数**: `id` (integer, 必須) - -## 3. データ形式 (JSON-RPC) - -### 3.1 ツール呼び出し例 (Request) - -```json -{ - "jsonrpc": "2.0", - "method": "tools/call", - "params": { - "name": "search_text", - "arguments": { "content": "量子コンピュータについて" } - }, - "id": "123" -} -``` - -### 3.2 応答形式 (Response) - -MCP 規格に従い、ツールの戻り値は `content` 配列内にラップされます。 +ツール呼び出しは JSON-RPC 2.0 に準拠しており、結果は常に MCP 規格の `content` 配列形式で返されます。 ```json { "jsonrpc": "2.0", "result": { "content": [ - { "type": "text", "text": "[ID: 1, Distance: 0.12]\n検索結果の内容..." } + { + "type": "text", + "text": "[結果メッセージ]" + } ] }, - "id": "123" + "id": "req-123" } ``` -## 4. エラー定義 +## 5. 開発者向けデバッグ情報 -- `-32601`: `Method not found` (未定義ツールの呼び出し) -- `-32000`: `Internal error` (モデルサーバー不通、DB エラー) -- `422`: パラメータ不足、または形式エラー。 +- `/status` エンドポイントにアクセスすることで、現在の MCP セッション数やシステム負荷状況を確認できます。 +- エラーコード `-32000` が返された場合は、バックグラウンドの `llama-server` との通信エラー（タイムアウト等）の可能性が高いです。 diff --git a/document/05_sidecar_integration.md b/document/05_sidecar_integration.md index 92e9206..1e24bf4 100644 --- a/document/05_sidecar_integration.md +++ b/document/05_sidecar_integration.md @@ -1,43 +1,36 @@ # サイドカー統合仕様書 (Sidecar Integration Specification) -## 1. コンセプト +## 1. サイドカーの役割と設計思想 -本システムは、Tauri の Sidecar 機能を活用し、内蔵された `llama-server` バイナリを動的に制御することで、外部 LLM サービスに依存しないローカル嵌入環境を提供します。 +本システムにおける **llama-server** は、外部プロセスとして動作する「推論エンジン」です。Rust コアにライブラリとして組み込むのではなく、サイドカー（別プロセス）として分離することで、以下の設計上の利点を得ています。 -## 2. Sidecar 管理仕様 +- **安定性の隔離**: 万が一推論エンジンがメモリ不足などでクラッシュしても、メインの GUI や MCP サーバー、データベースは影響を受けず、安全に再起動を行えます。 +- **更新の柔軟性**: モデルバイナリやランタイムを Rust コードの再コンパイルなしでアップデート可能です。 -### 2.1 実行バイナリ +## 2. プロセス管理 -- **名称**: `llama-server` (Windows x64 用サイドカー) -- **モデル**: `Gemma-3-270m-it-Q4_K_M.gguf` -- **依存拡張**: **sqlite-vec** (`vec0.dll`) +### 2.1 ライフサイクル制御 -### 2.2 DLL 供給体制 (Hermetic Build) +Tauri の `Command` API を使用して管理されます。 -Windows 環境での実行を確実にするため、以下の自動化を行っています。 +- **自動起動**: アプリ起動時に `--embedding` モードでバックグラウンド実行されます。 +- **孤立防止**: メインプロセスが異常終了した場合でも、プロセスグループ管理によりサイドカーがゾンビプロセスとして残らないよう設計されています。 -1. **自動コピー**: ビルド時 (`build.rs`) に、`sqlite-vec` の DLL を開発ノードから抽出し、実行ディレクトリ（および `bin`）へ自動配置します。 -2. **位置解決**: Tauri の `resource_dir` 基点に、`bin/` フォルダ内のモデルと、実行ルート直下の `vec0.dll` を動的にバインドします。 +### 2.2 起動引数の詳細 -## 3. 推論エンジン設定 (llama-server) +現状、以下のパラメータで最適化されています。 -起動時に以下のパラメータを指定します。 +- `--pooling mean`: Embedding 精度の向上のための設定。 +- `--embedding`: 入力テキストから特徴ベクトルを抽出する機能を有効化します。 -| 引数 | 値 | 説明 | -| :--- | :--- | :--- | -| `--model` | {path} | モデルファイルへの絶対パス。 | -| `--port` | 8080 | 内部通信用。 | -| `--embedding` | (flag) | 埋め込み生成 API を有効化。 | -| `--pooling` | `mean` | ベクトル集約方式の指定（推奨設定）。 | +## 3. Hermetic Build (自己完結型ビルド) -## 4. ライフサイクル +Windows 環境における DLL 地獄を防ぐため、以下の設計を徹底しています。 -1. **Spawn**: `lib.rs` 内でアプリ起動時に `sidecar("llama-server")` を呼び出し。 -2. **Health Check**: `/health` エンドポイントが `running` を返すまで待機。 -3. **Inbound Notification**: `llama-server` の Stdout/Stderr を Rust 側のロガーへパイプし、一元管理。 -4. **Cleanup**: アプリ終了時にチャイルドプロセスを Kill 処理。 +- **DLL 自動配置**: ビルドおよびリリース時に、`vec0.dll` (sqlite-vec) などの依存ライブラリを実行ファイルと同階層に自動的にコピーします。 +- **パス解決**: アプリ実行時に `LdgLibrary` 等の仕組みを介さず、カレントディレクトリから優先的に DLL をロードするよう `build.rs` で制御しています。 -## 5. 推論最適化 +## 4. トラブルシューティング -- **Vulkan 支援**: 互換 DLL が存在する場合、自動的にハードウェア加速が適用されます。 -- **ログ隔離**: 生成時の一時的なノイズ（`post_embedding` 等）は、Rust 側でフィルタリングしてログの視認性を確保。 +- **ポート 8080 の競合**: 他のアプリがポート 8080 を使用している場合、サイドカーの起動に失敗します。このステータスは UI 上のインジケーターで確認可能です。 +- **モデル未検出**: `resources` フォルダ内に適切な GGUF モデルが存在しない場合、ログにエラーが出力され、検索機能が無効化されます。 diff --git a/document/06_development_guide.md b/document/06_development_guide.md index 1bfaec2..87fa6cc 100644 --- a/document/06_development_guide.md +++ b/document/06_development_guide.md @@ -1,81 +1,43 @@ -# 💻 開発ガイド (Development Guide) +# 開発者ガイド (Development Guide) -本ドキュメントでは、本プロジェクトの開発環境構築、コードの変更、新しいツールの追加、およびテストの手順について解説します。 +## 1. 開発の基本コンセプト ---- +TelosDB の開発においては、**「確信の持てるコード」**と**「自動化された環境」**を重視します。Windows 環境特有の DLL 競合やビルドエラーを避けるため、環境構築手順を簡略化しています。 -## 🛠️ 開発環境のセットアップ +## 2. 環境構築の手順 -### プログラミング言語・ランタイム +### 2.1 必要なツール -- **Rust**: 最新の Stable 版。`tauri-cli` を使用。 -- **Bun**: フロントエンドのパッケージ管理、およびテストランナー。 +- **Rust**: 最新の Stable ツールチェーン。 +- **Node.js**: フロントエンド資材の管理用。 +- **VS Code**: 推奨エディタ（Tauri / Rust 拡張機能）。 -### 依存関係のインストール +### 2.2 初回セットアップ + +1. リポジトリをクローン。 +2. `npm install` を実行（`sqlite-vec` などのバイナリ等が含まれます）。 +3. `src-tauri/resources/` に指定の推論モデル（Gemma-3 GGUF）を配置。 + +## 3. ビルドと実行 ```bash -bun install +# 開発モード（ホットリロード有効） +npm run tauri dev ``` ---- +> [!NOTE] +> 開発時に DLL のエラーが出る場合は、一度 `cargo clean` を行い、`build.rs` による DLL 再生成を促してください。 -## 📁 主要なディレクトリ構成と責務 +## 4. 拡張手順 (MCP ツールの追加) -- `src/`: フロントエンド (Vanilla JS / CSS) -- `src-tauri/src/mcp.rs`: **MCP サーバー実装 & ツールロジック**。 -- `src-tauri/src/db.rs`: **sqlite-vec** スキーマ管理・データアクセス。 -- `src-tauri/src/lib.rs`: Tauri エントリポイント・サイドカー起動・トレイ制御。 -- `src-tauri/bin/`: 推論バイナリとモデルファイル。 -- `document/`: 設計書・仕様書。 -- `journals/`: Rule 13 に基づく集約された作業記録。 +新しい機能を MCP 経由で公開する場合は、以下のファイルを修正します。 ---- +1. **`mcp.rs`**: JSON-RPC ハンドラーに新しいメソッドを追加。 +2. **`document/mcp.json`**: ツールのスキーマ（引数定義）を記述。エージェントがこの定義を読み取ります。 +3. **`04_mcp_api_specification.md`**: 仕様書を更新。 -## ➕ 新しい MCP ツールの追加手順 +## 5. コーディング規約とテスト -### 1. ツール定義の追加 - -`src-tauri/src/mcp.rs` 内の `tools/list` ハンドラ内に、新しいツールの名称、説明、パラメータスキーマを追加します。 - -### 2. ハンドラの実装 - -`mcp_messages_handler` 内の `match actual_method` 文に新しい `case` を追加し、DB 操作や LLM 連携ロジックを記述します。 - -### 3. UI 通知の統合 - -必要に応じて `state.tx.send` を使用し、ツール呼び出しを UI のアクティビティログに通知するように設定します。 - ---- - -## 🧪 テストの実行 - -### バックエンド (Rust) - -```bash -cd src-tauri -cargo test -``` - -### フロントエンド / API - -```bash -bun run dev # 開発サーバー起動 -``` - ---- - -## 🚀 リリース手順 - -1. **バージョン更新**: `package.json`, `tauri.conf.json`, `Cargo.toml` のバージョンを同期。 -2. **ビルド**: - - ```bash - bun run tauri build - ``` - -3. **成果物**: `src-tauri/target/release/bundle/` 配下にインストーラーが生成されます。 - -## 📝 コーディング規約 - -- **名称統一**: ベクトル検索エンジンは **「sqlite-vec」** と呼びます。 -- **ジャーナル記録**: 作業完了後は必ず `journals/` に Rule 9 形式で記録を残してください。 +- **非同期処理**: SQLite 操作や通信はすべて `tokio` ランタイム上で行い、UI をブロックしないようにします。 +- **ログ**: `log::info!` / `log::error!` を使用してください。ログは `src-tauri/logs/` に自動出力されます。 +- **テスト**: ロジックの変更後は必ず `scripts/test_mcp_client.mjs` を実行し、既存ツールが壊れていないか確認してください。 diff --git a/document/07_ui_design_spec.md b/document/07_ui_design_spec.md index 03d9803..5a7540e 100644 --- a/document/07_ui_design_spec.md +++ b/document/07_ui_design_spec.md @@ -1,42 +1,39 @@ -# 07 UIデザイン仕様書 +# UI デザイン仕様書 (UI Design Specification) -## 1. デザインコンセプト +## 1. コンセプト: Glassmorphism -- **Glassmorphism**: 透過、ブラー（backdrop-filter）、および淡いボーダーによる奥行きのある質感。 -- **Color Palette**: ダークネイビーを基調とした、深みのあるプレミアムな配色。 -- **Interaction**: Hover 効果やフェードアニメーションによる生き生きとした応答性。 +TelosDB の UI は、Apple の macOS や Microsoft の Windows 11 のトレンドを取り入れた **「ガラスモーフィズム (Glassmorphism)」** をテーマにしています。 +これは、デスクトップアプリという「OSとの調和」が求められる環境において、透明感と高級感を演出するためです。 -## 2. レイアウト構造 (Grid System) +### 1.1 デザインの構成要素 -1. **Header**: ブランドロゴ、モデル名、システムステータス（dot + text）、ドキュメント件数。 -2. **Search Center**: インデックス検索入力、および検索実行ボタン。 -3. **Main Content**: カード形式で展開される検索結果リスト。 -4. **Activity Sidebar**: MCP 経由のツール呼び出しをリアルタイム表示するサイドログ領域。 -5. **Action Bar**: MCP 設定、スキーマコピー等の機能ボタン一式。 +- **背景**: すりガラスのようなブラー効果（`backdrop-filter: blur`）。 +- **ボーダー**: 光の屈折を表現する微細なセミ透明の境界線。 +- **タイポグラフィ**: 視認性の高い、モダンなサンセリフ体。 -## 3. 技術仕様 (Frontend Stack) +## 2. インタラクティブ・フィードバック -- **Engine**: Tauri 2 (Webview2) -- **Style**: カスタム CSS 変数による一元管理（`styles.css`）。 -- **Data Sync**: - - **SSE (Server-Sent Events)**: サーバー側からの `update` イベントを購読し、UI を自動リフレッシュ。 - - **JSON-RPC Over HTTP**: 検索や CRUD 操作のディスパッチ。 +### 2.1 ステータス・インジケーター -## 4. 特筆すべきデザイン要素 +画面右上のドットは、システムの「生存確認」を行います。 -- **Status Dot**: 起動（緑）、待機（橙）、停止（赤）のカラーインジケーター。 -- **Glass Panel**: +- `Green`: 全システム正常稼働中。 +- `Red`: サイドカーまたは MCP サーバーの停止。 +- `Click`: 詳細な接続ステータスをポップオーバー表示。 - ```css - background: rgba(255, 255, 255, 0.05); - backdrop-filter: blur(15px); - border: 1px solid rgba(255, 255, 255, 0.1); - ``` +### 2.2 アクティビティ・ログ (SSE Listener) -- **Log Animation**: 新しいログが上部からスライドインしてフェードインするアニメーション。 +検索や登録が発生した際、画面下部にアニメーションと共にログが流れます。 +これは **SSE (Server-Sent Events)** によってバックエンドから「プッシュ」される仕組みになっており、ユーザーはアプリがバックグラウンドで何を行っているかをリアルタイムに把握できます。 -## 5. UI フロー +## 3. フロントエンド技術スタック -1. アプリ起動 -> llama-server 状態確認（待機中 -> 起動中）。 -2. MCP ツール呼び出し（外部） -> SSE 経由でアクティビティログに項目が追加（アニメーション）。 -3. データ変更 -> SSE `data_changed` 受信 -> ドキュメント件数を自動再取得して更新。 +あえて重量級のフレームワークを避け、**Vanilla JS** と **Vanilla CSS** で構成しています。 + +- **理由**: Tauri の WebView2 は非常に高速であり、余計なレイヤーを挟まないことでメモリ消費を抑え、起動速度を最大化するためです。 +- **SSE 実装**: `EventSource` API をネイティブに使用し、低遅延な通知受け取りを実現。 + +## 4. レイアウト構造 + +メインエリアには現在のドキュメント登録数（Docs Count）が強調表示され、システムの「知識の蓄積状況」を直感的に確認できる設計になっています。 +ログエリアは最大 5 件まで履歴を表示し、それ以上は滑らかにフェードアウトします。