埋め込み改修：ゴールとテスト KPI
製品概要・アーキテクチャは 01_system_overview.md・02_architecture_design.md を参照。本文書は改修ゴールとテスト KPI の定義のみ。
1. 改修のゴール（Goals）
1.1 主ゴール
| # |
ゴール |
達成条件 |
| G1 |
エディション分離の成立 |
Community 版と Pro 版が同一リポジトリから、ビルドフラグのみで別バイナリとしてビルド・配布できる。一方の実装が他方のバイナリに含まれない。 |
| G2 |
Pro 版の起動・検索の成立 |
Pro 版が起動し、検索 API（FTS ＋ 埋め込み可能時はベクトル）が動作する。埋め込みモデル未ロード時も FTS のみで検索可能である。 |
| G3 |
モデルのプロジェクト内組み込み |
埋め込みモデル（ONNX ＋ vocab）をプロジェクト内 embedding_model/ に置き、開発・配布ビルドの両方で同じパス解決で参照できる。 |
| G4 |
GUI のエディション対応 |
起動中のエディションに応じて、ヘッダー表示・RE-INDEX 文言・ステータスが切り替わる。 |
| G5 |
検索の健全性 |
既存 DB や 1 文字クエリでも、FTS または LIKE フォールバックで検索結果が返る。items_fts と items の不整合は起動時・手動 heal で解消できる。 |
| G6 |
テスト・運用の自動化 |
ヘッドレス起動と test-and-heal（heal → MCP テスト）が Pro/Community で実行可能。継続実行オプションで回し続けられる。 |
| G7 |
埋め込みモデルの確実なロード（テスト利用可能） |
Pro 起動時に埋め込みモデルがロード成功し、ベクトル化・近似近傍検索の動作確認とテストが行える状態にする。tract の最適化スキップや代替 ONNX などで Cast ノード問題を回避する。 |
1.2 副次ゴール（既知の制約内）
| # |
ゴール |
備考 |
| G8 |
既存機能の非劣化 |
Community 版の LSA 学習・HNSW・検索・追加・更新は従来どおり動作する。 |
2.1 ビルド・起動
| KPI |
指標 |
合格基準 |
測定方法 |
| K1 |
Community ビルド成功 |
cargo build（または tauri build）が警告のみで完了する |
cargo build --manifest-path src/backend/Cargo.toml |
| K2 |
Pro ビルド成功 |
cargo build --no-default-features --features pro が警告のみで完了する |
上記 + feature pro |
| K3 |
Community 起動 |
ウィンドウが開き、ログに [BOOT] Edition: community が出る |
手動 or launch「Community で起動」 |
| K4 |
Pro 起動 |
ウィンドウが開き、ログに [BOOT] Edition: pro が出る |
手動 or launch「Pro で起動」 |
| K5 |
ヘッドレス起動 |
TELOS_HEADLESS=1 でウィンドウ非表示のまま MCP が 3001 で待ち受ける |
npm run test:headless が MCP 待機まで完了 |
2.2 API・検索
| KPI |
指標 |
合格基準 |
測定方法 |
| K6 |
MCP ツール一覧 |
POST /messages で tools/list が 10 件前後のツールを返す |
tests/test_mcp_client.mjs の tools/list 成功 |
| K7 |
検索が 200 を返す |
search_text が JSON-RPC として成功し、content 配列が返る（0 件でも可） |
test_mcp_client の search_text が例外にならない |
| K8 |
Heal API |
GET /heal が 200 で { "synced": n } を返す |
test-and-heal 内の heal 呼び出し成功 |
| K9 |
エディション API |
GET /edition が community または pro を返す |
起動したバイナリの feature と一致 |
2.3 データ整合・ヒール
| KPI |
指標 |
合格基準 |
測定方法 |
| K10 |
起動時 FTS 同期 |
items に存在し items_fts に無い行が起動時に挿入される |
既存 DB で検索が 0 件だったケースが heal 後または再起動で解消 |
| K11 |
手動 Heal 効果 |
GET /heal 実行後、不足していた FTS 行が検索に反映される |
heal 前後で同一クエリのヒット件数が増える（不足があった場合） |
2.4 回帰・非劣化
| KPI |
指標 |
合格基準 |
測定方法 |
| K12 |
Community 検索 |
LSA 学習完了後、検索がベクトル＋FTS で結果を返す |
Community 起動 → 文書追加 → 検索でヒット |
| K13 |
Rust 単体テスト |
既存の cargo test が通る |
npm run test:rust（db, lsa, mcp の tests） |
2.5 運用・CI 寄り
| KPI |
指標 |
合格基準 |
測定方法 |
| K14 |
test-and-heal 1 回成功 |
npm run test-and-heal:pro が exit 0 で終わる |
スクリプト実行。MCP 未起動時はヘッドレスで Pro 起動 → heal → test |
| K15 |
継続実行の安定性 |
test-and-heal:pro:continuous が複数サイクル（例: 2 回）heal → test を繰り返す |
手動で 2 サイクル以上実行し、いずれも test が完了する |
2.6 Pro 埋め込み・ベクトル化・ANN（G7 達成のための KPI）
| KPI |
指標 |
合格基準 |
測定方法 |
| K16 |
埋め込みモデルロード成功 |
Pro 起動時に embedding_model が Some となり、ログにモデル読み込み成功が出る（またはエラーが出ない） |
Pro 起動 → ログ確認。または GET /model_name で pro/sonoisa 系の名前が返る |
| K17 |
ベクトル化: vec_items 投入 |
add_item_text で 1 件追加後、vec_items に 1 行・768 次元が入る |
DB: SELECT COUNT(*), vec_to_json(embedding) FROM vec_items で確認 |
| K18 |
起動時 HNSW 構築（Pro） |
vec_items にデータがある状態で Pro 再起動後、HNSW が構築される |
ログに [BOOT] Pro HNSW: inserting N items (768d)... および index built. |
| K19 |
ANN 検索でベクトルヒット |
追加した文書に意味的に近いクエリで search_text を実行し、その文書が結果に含まれ類似度が付与される |
MCP search_text で content 配列に該当文書が含まれる。optional: 複数文書で類似度順が妥当 |
3. まとめ
- ゴール: エディション分離・Pro 起動・モデル組み込み・GUI 対応・検索健全性・テスト自動化・埋め込み確実ロード（G7） を主目標とし、既存機能の非劣化（G8）を副次目標とする。
- KPI: ビルド/起動（K1–K5）、API/検索（K6–K9）、データ整合/ヒール（K10–K11）、回帰（K12–K13）、運用（K14–K15）、Pro 埋め込み・ベクトル化・ANN（K16–K19） の 19 項目を合格基準とし、CI または手順に沿ったテストで測定する。
