20260212 TelosDB Development Journal

20260212-0001-プロジェクト名変更 (sqlitevector -> TelosDB)

概要

プロジェクト名を sqlitevector から TelosDB に変更する。これに伴い、設定ファイル、ドキュメント、およびルートフォルダ名の更新を行う。

検討事項

• package.json の name フィールドの変更。
• tauri.conf.json の productName, identifier, title の変更。
• README.md のタイトルおよび説明文の更新。
• ルートフォルダ名の変更 (Windows command: move).

構造図 (変更前)

graph TD
    Root["sqlitevector/"]
    Root --> PKG["package.json (name: sqlitevector)"]
    Root --> README["README.md (Title: SQLite Vector)"]
    Root --> Backend["src/backend/"]
    Backend --> Tauri["tauri.conf.json (productName: sqlitevector)"]

構造図 (変更後)

graph TD
    Root["TelosDB/"]
    Root --> PKG["package.json (name: telosdb)"]
    Root --> README["README.md (Title: TelosDB)"]
    Root --> Backend["src/backend/"]
    Backend --> Tauri["tauri.conf.json (productName: TelosDB)"]

作業手順

1. implementation_plan.md の作成 (完了)
2. package.json の変更
3. tauri.conf.json の変更
4. README.md の更新
5. ディレクトリ名の変更
6. lint および test の実行
7. コミット

メモ

ルートフォルダの変更は、エージェントが動作しているパスに影響するため慎重に行う必要がある。 プログラム内部で sqlitevector という文字列をハードコードしている箇所がないか再度確認する。

ビルドエラー修正: target-dir パス不整合

日時: 2026-02-12 21:06 対象: src-backend/.cargo/config.toml

問題

フォルダ構成変更（src-tauri → src-backend）後、tauri dev ビルドが失敗。

resource path `..\..\bin\llama-server-x86_64-pc-windows-msvc.exe` doesn't exist

原因分析

graph TD
    A["src-backend/.cargo/config.toml"] -->|"target-dir = ../../target"| B["%DEV_ROOT%/target ❌"]
    A -->|"target-dir = ../target"| C["%PROJECT_ROOT%/target ✅"]
    D["tauri.conf.json externalBin"] -->|"../bin/llama-server"| E["パス解決が target-dir 基準でずれる"]
    E --> F["../../bin/llama-server として解決 ❌"]

修正内容

検証

• cargo check: ✅ 成功（Exit code: 0）
• cargo clippy: ✅ 成功（既存のwarning 6件のみ、エラーなし）

SQLiteテーブルビューア機能の追加

日時: 2026-02-12 21:18 対象: src-frontend/index.html, src-backend/src/lib.rs

案件概要

ユーザーがGUI上でSQLiteのテーブル構成（スキーマ）や登録内容（データ）を直接確認できるように、左サイドバーとテーブルビューを追加する。

修正・追加内容

1. バックエンド (Rust / Tauri)

• 新規Tauriコマンドの追加:
  • get_table_list: sqlite_masterからテーブル一覧を取得。
  • get_table_schema: PRAGMA table_infoから定義を取得。
  • get_table_data: ページネーション対応のレコード取得（SQLインジェクション対策済み）。
• リファクタリング:
  • analyze_nesting.jsの指摘に基づき、diagnose_environment関数のネストをガード条件を用いて解消。

2. フロントエンド (HTML / CSS / JS)

• レイアウト刷新:
  • CSS Gridを用いた「左サイドバー + メインパネル」構成。
  • ダークモード、CSS変数、グラスモーフィズムを採用したモダンな配色。
• 機能実装:
  • サイドバーでのテーブル一覧表示。
  • Schemaタブによるカラム定義の表示。
  • Dataタブによる20件ずつのページネーション表示。
  • MCP設定表示機能の統合。

図解 (Mermaid)

graph LR
    subgraph Frontend
        Sidebar["サイドバー (テーブル選択)"]
        Tabs["メイン (Data/Schema)"]
    end
    
    subgraph Backend
        CmdList["get_table_list"]
        CmdData["get_table_data"]
        CmdSchema["get_table_schema"]
    end
    
    subgraph Data
        DB[("SQLite (items, vec_items)")]
    end
    
    Sidebar --> CmdList
    Tabs --> CmdSchema
    Tabs --> CmdData
    CmdList & CmdSchema & CmdData --> DB

検証結果

• cargo check: ✅ 成功
• cargo clippy: ✅ 成功 (既存警告のみ)
• analyze_nesting.js: lib.rs の最大ネストが 5 -> 4 に改善。
• tauri dev: GUI上で全テーブルの表示、ページネーション、タブ切替が正常に動作することを確認。

sqlite-vec → sqlite-vector 移行実装

日時: 2026-02-12 21:40 対象: src-backend/src/db.rs, src-backend/src/lib.rs, src-backend/src/mcp/handlers.rs, src-backend/src/entities/items.rs

案件概要 (移行)

ベクトル検索エンジンを Alex Garcia 版 (sqlite-vec) から sqliteai 版 (sqlite-vector) へ移行した。 これにより、仮想テーブルを使用しない BLOB カラム方式への統合と、より安定した API (vector_quantize_scan) の利用が可能になった。

変更内容

1. データベース・スキーマ

• vec_items 仮想テーブルを廃止。
• items テーブルに embedding BLOB カラムを追加。
• 初期化時に vector_init を実行してカラムをベクトルとして認識させる。

2. ベクトル検索

• MATCH 句から vector_quantize_scan による JOIN 方式に変更。
• 検索ベクトルをバイト列（f32 LE）に変換してクエリに渡すロジックに統一。

3. DLL管理

• npmパッケージ @sqliteai/sqlite-vector-win32-x86_64 から vector.dll を取得し bin/ に配置。
• バックエンドのパス解決ロジックを vector.dll および新パッケージ構成に対応。

graph LR
    subgraph "Before"
        items[items table]
        vec_items[vec_items virtual table]
        items -- JOIN -- vec_items
    end
    subgraph "After"
        items_new[items table + embedding BLOB]
    end

課題と解決

• cargo check 時、handlers.rs で embedding_bytes 変数が未定義のまま使用されていた問題を修正。
• lib.rs の resolve_extension_path において不要な可変変数 mut 警告を解消。

検証結果 (移行)

• cargo check: Pass
• ネストレベル解析: lib.rs で Level 5 (既存ロジック由来) を確認したが、移行ロジック自体は平易。
• count_lines: 各ファイルとも許容範囲内。

20260212-0005-sqlite-vector拡張機能のロード不具合調査

概要 (不具合調査)

sqlite-vec (Alex Garcia版) から sqlite-vector (sqliteai/sqlite-vector版) への移行に伴い、SQLite拡張機能 (vector.dll) が正常にロードできず、アプリケーションがランタイムでクラッシュ（Panic）する問題を調査した。

経緯

1. 移行背景: 安定性と機能性を求め、仮想テーブルを必要としない sqlite-vector (BLOB保存方式) への移行を決定。
2. 不具合発生: db.rs で load_extension を実行した際、「指定されたモジュールが見つかりません」というエラー（Windowsエラーコード 0x7E）が発生。
3. 調査結果:
   • プリビルドDLL: npmパッケージ内のバイナリは libgcc_s_seh-1.dll などの外部ランタイムに依存しており、標準的な環境ではロードに失敗しやすい。
   • ソースビルドの試行:
     • sqliteai/sqlite-vector の公式リポジトリを tmp/sqlite-vector にクローン。
     • zig cc (Clang) を用いたビルドを試みたが、AVX2命令の定数初期化や MSVC ABI 固有の関数衝突でコンパイルエラーが発生。
     • 以下のソースコードを修正してビルドを成功させた：
       • distance-avx2.c: popcount_lut の初期化をインライン化。
       • libs/fp16/bitcasts.h: Clangビルド時の MSVC 組み込み関数使用を回避し Union 方式にフォールバック。
       • sqlite-vector.c: strcasecmp マクロを Windows 用に定義。
4. 現状:
   • 自前で -static 指定ビルドした vector.dll を bin/ に生成したが、依然として SQLite 側からロードした際に「モジュールが見つからない」と判定される。
   • これは DLL 自体の不足ではなく、DLL がインポートしている SQLite のシンボル解釈、あるいは 依存 DLL (C Runtime 等) が実行時に見つかっていない可能性が高い。

課題

• シンボル解決: DLL が sqlite3_... 関数の実体を見つけられていない。
• デバッグ手法: sqlx のワーカースレッド内で落ちるため、詳細なエラーメッセージの取得が困難。
• 配置: tauri dev 実行時のカレントディレクトリと DLL サーチパスの一致。

注意点

• 仮想テーブルは不要: 新しい sqlite-vector は CREATE VIRTUAL TABLE ではなく、通常のテーブルに BLOB 型で保存する。
• エントリポイント: ロード時の指定は sqlite3_vector_init である必要がある（自動認識されない場合は明示が必要）。
• ビルド成果物: 現在 bin/vector.dll に自前ビルド版、node_modules にプリビルド版がある。

修正方針（VS Codeでの対応用）

1. sqlite3.dll を bin/ に配置し、拡張機能がリンクできるようにする。
2. db.rs でのロードパスを、環境変数などを利用した堅牢な絶対パス指定に変更する。
3. dumpbin /IMPORTS 等で、生成した DLL が何を外部に求めているか最終確認する。

graph TD
    A[App Start] --> B[Initialize DB]
    B --> C{Load extension}
    C -- Failed --> D[Runtime Panic]
    C -- Target --> E[vector.dll]
    E -- depends on --> F[sqlite3.dll]
    E -- depends on --> G[VCRuntime]
    F -- Missing? --> D

20260212-0006-sqlite-vectorビルド・導入手順のドキュメント化

概要 (ドキュメント)

vector.dll ロード不具合の解決策と、Windows 環境特有のビルド・配置手順を公式ドキュメントおよび README に記録した。

実施内容

1. ドキュメントの作成

• docs/sqlite-vector-build.md を作成。
  • Windows における依存関係（libgcc 等）の課題を記述。
  • sqlite3.dll を自前ビルドしてリンクする解決策を詳述。
  • zig cc を使用したビルドコマンドを記録。
  • アプリ起動時に PATH を更新する実装意図を解説。

2. README.md の更新

• エンジン移行の完了を反映。
• 「ネイティブモジュール (DLL) について」セクションを追加し、bin/ フォルダの重要性とビルドドキュメントへのリンクを明記。
• 重複していた「システム構造」セクションを整理。

構成図 (Mermaid)

graph TD
    subgraph "Development"
        Src["sqlite-vector Source"] -- "zig cc + link sqlite3.dll" --> VectorDLL["vector.dll"]
        SqliteSrc["sqlite3.c"] -- "zig cc" --> SqliteDLL["sqlite3.dll"]
    end
    
    subgraph "Runtime (TelosDB)"
        App["TelosDB.exe"] -- "Add bin/ to PATH" --> Env["Runtime Environment"]
        Env -- "load_extension" --> VectorDLL
        VectorDLL -- "symbol lookup" --> SqliteDLL
    end

成果

将来の保守担当者が、なぜ bin/ に sqlite3.dll が存在するのか、また DLL を更新する際にどのような手順が必要なのかを容易に把握できるようになった。