GitBucket
KPI 達成のための検証手順
- ゴール・KPI は 08_embedding_tract_goals_and_kpi.md に定義済み。
- 本文書はテスト実行順・合格判定・手順のみ。改修の多くは実装済み。
Phase 1：ビルド・起動（K1–K5）
1.1 改修タスク
| KPI | 現状 | 不足改修 | 担当 |
|---|---|---|---|
| K1 | Community ビルドは Cargo feature で実装済み | なし | — |
| K2 | Pro ビルドは --no-default-features --features pro で実装済み |
なし | — |
| K3 | launch「Community で起動」あり。ログに Edition 出力済み | なし | — |
| K4 | launch「Pro で起動」あり | なし | — |
| K5 | test:headless で TELOS_HEADLESS=1 起動。spawn は shell:true で対応済み |
なし | — |
Phase 1 の追加改修: 特になし。必要なら「K1–K2 のみ検証する npm スクリプト」を追加可。
1.2 テスト手順
- K1
cd src/backend && cargo build --manifest-path Cargo.toml
→ 警告のみで完了すれば合格。 - K2
cargo build --no-default-features --features pro --manifest-path src/backend/Cargo.toml
→ 同様。 - K3
launch「TelosDB: Community で起動 (tauri dev)」で F5。ログに[BOOT] Edition: communityを確認。 - K4
launch「TelosDB: Pro で起動 (tauri dev)」で F5。ログに[BOOT] Edition: proを確認。 - K5
既存の 8474/3001 使用プロセスを終了したうえでnpm run test:headless
→ MCP が 3001 で待ち受け、テストが開始されれば合格（途中で EADDRINUSE の場合はポート解放後に再実行）。
1.3 合格判定
- K1–K2: ビルド exit 0。
- K3–K4: ログに該当 Edition が 1 回以上出力。
- K5: test:headless が MCP 待機まで完了（その後の MCP テスト失敗は Phase 2 で扱う）。
Phase 2：API・検索（K6–K9）
2.1 改修タスク
| KPI | 現状 | 不足改修 | 担当 |
|---|---|---|---|
| K6 | tools/list は MCP で実装済み | なし | — |
| K7 | search_text は FTS＋LIKE フォールバック実装済み | なし | — |
| K8 | GET /heal と heal_items_fts 実装済み | なし | — |
| K9 | GET /edition と AppState.edition 実装済み | なし | — |
Phase 2 の追加改修: 特になし。
2.2 テスト手順
- K6–K7
MCP を起動した状態でnode tests/test_mcp_client.mjs
→ tools/list が 10 件前後、search_text が例外なく content 配列を返せば合格。 - K8
curl -s http://127.0.0.1:3001/heal
→ 200 かつ{"synced":n}形式なら合格。 - K9
Community 起動時:curl -s http://127.0.0.1:3001/edition→"edition":"community"。
Pro 起動時: 同様に"edition":"pro"を確認。
2.3 合格判定
- K6: test_mcp_client の「Found N tools」が 10 前後。
- K7: search_text で例外なし・content 配列が返る（0 件可）。
- K8: GET /heal が 200 で JSON の synced が存在。
- K9: GET /edition が起動したエディションと一致。
Phase 3：データ整合・ヒール（K10–K11）
3.1 改修タスク
| KPI | 現状 | 不足改修 | 担当 |
|---|---|---|---|
| K10 | init_schema 内で sync_items_fts 呼び出し済み | なし | — |
| K11 | GET /heal で heal_items_fts 実行済み | なし | — |
Phase 3 の追加改修: 特になし。必要なら「items のみ存在する DB コピー」で検証用データを用意する。
3.2 テスト手順
- K10
1) items にのみ行がある状態の DB を用意（または items_fts を手動で一部削除した状態を作る）。
2) アプリを再起動。
3) ログに[db] items_fts: synced N rows（N>0）が出る、または検索でヒットするようになることを確認。 - K11
1) items に存在するが items_fts に無い id がある状態を用意。
2)GET /healを 1 回実行。
3) 同一クエリで検索し、heal 後にヒット件数が増える（または 0→1 以上になる）ことを確認。
3.3 合格判定
- K10: 起動後、不足 FTS が同期されるか検索結果に反映される。
- K11: heal 実行後、該当クエリのヒットが増える（または 0 件から 1 件以上になる）。
Phase 4：回帰・非劣化（K12–K13）
4.1 改修タスク
| KPI | 現状 | 不足改修 | 担当 |
|---|---|---|---|
| K12 | Community の LSA・HNSW・検索は feature 分岐で維持済み | なし | — |
| K13 | db, lsa, mcp の #[cfg(test)] が存在 | なし | — |
Phase 4 の追加改修: 特になし。
4.2 テスト手順
- K12
Community で起動 → 文書を 1 件以上追加（GUI または MCP）→ LSA 学習完了を待つ → 検索でヒットすることを確認。 - K13
npm run test:rust
→ すべてのテストがパスすれば合格。
4.3 合格判定
- K12: Community で「追加 → 検索ヒット」が再現できる。
- K13:
cargo testが exit 0。
Phase 5：運用・CI 寄り（K14–K15）
5.1 改修タスク
| KPI | 現状 | 不足改修 | 担当 |
|---|---|---|---|
| K14 | test-and-heal:pro（--pro）で Pro 起動 → heal → test 実装済み | なし | — |
| K15 | --continuous で繰り返し実行実装済み | なし | — |
Phase 5 の追加改修: 特になし。必要なら「2 サイクルで自動停止」するオプションを追加（例: --cycles 2）。
5.2 テスト手順
- K14
8474/3001 を占有しているプロセスを終了したうえでnpm run test-and-heal:pro
→ exit 0 なら合格。 - K15
npm run test-and-heal:pro:continuous
→ 2 回以上「Heal → MCP test」が回ったあと、手動で Ctrl+C。両サイクルで test が完了していれば合格。
5.3 合格判定
- K14: test-and-heal:pro が exit 0。
- K15: continuous で 2 サイクル以上、いずれも test 完了。
Phase 6：Pro 埋め込みロード・ベクトル化・ANN（K16–K19 / G7）
Pro エディションでドキュメントのベクトル化と近似近傍検索が動作するようにする。前提: 埋め込みモデルを確実にロードし、テストに使えるようにする。
6.1 改修タスク
| KPI | 改修 | 内容 | 優先度 |
|---|---|---|---|
| K16 | M1: 埋め込みロードの安定化 | 実装済み: (a) 環境変数 TELOS_EMBEDDING_NO_OPTIMIZE=1 のとき into_typed().into_runnable() でロード（最適化スキップ）。(b) 最適化失敗時（エラーに "Cast" / "optim" / "optimize" 含む）は自動で同経路にフォールバック。これで量子化 ONNX の Cast ノードでもモデルを確実にロードしてテストに利用可能。 |
必須 |
| K17–K19 | M2: テスト用スタブ埋め込み（任意） | 環境変数 TELOS_EMBEDDING_STUB=1 のとき、実モデルではなく固定 768 次元ベクトルを返すスタブを使う。モデルが読めない環境でも「ベクトル化 → vec_items → HNSW → 検索」のパイプラインをテスト可能。 |
推奨 |
| — | M3: ベクトル化・ANN 利用のログ | add_item で vec_items に挿入したときに [pro] vec_items inserted id={}。検索で HNSW または vec_items を利用したときに 1 行ログ。動作確認の証跡用。 |
推奨 |
6.2 テスト手順（モデルがロードできる場合: M1 完了後）
| # | テスト | 手順 | 合格基準 | 対応 KPI |
|---|---|---|---|---|
| T1 | ベクトル化: 1 件追加 | Pro 起動 → add_item_text で 1 件追加 → DB で SELECT COUNT(*) FROM vec_items が 1 増え、該当 id で vec_to_json(embedding) が 768 要素 |
vec_items に 1 行・768 次元 | K17 |
| T2 | 起動時 HNSW | 上記のあと Pro を再起動。ログに [BOOT] Pro HNSW: inserting 1 items (768d)... および [BOOT] Pro HNSW: index built. |
ログで HNSW 構築確認 | K18 |
| T3 | ANN: 検索でベクトルヒット | 追加した文書に近いクエリで search_text を実行。結果の content にその文書が含まれ、similarity が付与される | 意味的に近い文書がヒットし類似度が妥当 | K19 |
| T4 | ANN: 複数文書で順序 | 複数文書を追加し、ある 1 文書と意味的に近いクエリで検索。その文書が上位に来る | 類似度順のランキングが妥当 | K19 |
6.3 テスト手順（スタブ利用時: M2 完了後）
| # | テスト | 手順 | 合格基準 | 対応 KPI |
|---|---|---|---|---|
| T5 | スタブで vec_items 投入 | TELOS_EMBEDDING_STUB=1 で Pro 起動 → add_item_text で 1 件追加。vec_items に 1 行・768 次元が入る |
vec_items に 1 行・768 次元（スタブ） | K17 |
| T6 | スタブで HNSW 検索 | 続けて search_text を実行。HNSW または vec_items でベクトル検索が動き、該当 id が結果に含まれる | ベクトル経路でヒット 1 件以上 | K19 |
6.4 合格判定
- K16: Pro 起動後、ログに埋め込みロード成功（またはエラーなし）。必要なら GET /model_name で pro/sonoisa 系が返る。
- K17: T1 または T5 で vec_items に 1 行・768 次元が入る。
- K18: T2 で再起動後ログに Pro HNSW 構築が出る。
- K19: T3 または T4 または T6 で検索結果にベクトル由来のヒットが含まれる。
一括実行用チェックリスト（推奨順）
実行順に並べたチェックリスト。CI や手動検証で使用する。
| # | 実施内容 | 合格目安 | 対応 KPI |
|---|---|---|---|
| 1 | npm run test:rust |
exit 0 | K13 |
| 2 | Community ビルド（cargo build in src/backend） |
exit 0 | K1 |
| 3 | Pro ビルド（cargo build --no-default-features --features pro） |
exit 0 | K2 |
| 4 | launch「Community で起動」→ ログで Edition: community 確認 | ログに 1 行 | K3 |
| 5 | launch「Pro で起動」→ ログで Edition: pro 確認 | ログに 1 行 | K4 |
| 6 | ポート 8474/3001 解放 → npm run test:headless |
MCP 待機まで完了 | K5 |
| 7 | MCP 起動中に node tests/test_mcp_client.mjs |
tools/list 成功・search_text 例外なし | K6, K7 |
| 8 | curl -s http://127.0.0.1:3001/heal |
200 + JSON | K8 |
| 9 | curl -s http://127.0.0.1:3001/edition（Community/Pro 各 1 回） |
edition 一致 | K9 |
| 10 | 起動時 FTS 同期の確認（必要なら DB をわざと不整合にして再起動） | ログまたは検索で同期確認 | K10 |
| 11 | 手動 heal 効果の確認（必要なら不整合 DB で GET /heal 前後で検索） | ヒット増加 | K11 |
| 12 | Community 起動 → 文書追加 → 検索ヒット確認 | ヒット 1 件以上 | K12 |
| 13 | npm run test-and-heal:pro |
exit 0 | K14 |
| 14 | npm run test-and-heal:pro:continuous を 2 サイクル以上実行 |
両サイクル test 完了 | K15 |
| 15 | Pro 起動 → ログで埋め込みモデルロード成功確認（または /model_name で pro 系） | ログにエラーなし or model_name が pro 系 | K16 |
| 16 | Pro で add_item_text 1 件 → vec_items に 1 行・768 次元が入ることを DB で確認 | vec_items COUNT 増加・embedding 768 次元 | K17 |
| 17 | vec_items にデータがある状態で Pro 再起動 → ログで HNSW 構築確認 | Pro HNSW: inserting N items (768d)... 等 |
K18 |
| 18 | Pro で文書追加後、意味的に近いクエリで search_text → 該当文書がヒットし類似度付与 | 検索結果に該当 content・similarity | K19 |
オプション：KPI 検証用 npm スクリプト
自動化できる範囲だけを 1 本のスクリプトにまとめる場合の例。
- 案 A
npm run test:kpi→ 順にtest:rust→ Community/Pro のcargo build→test:headless（または test-and-heal:pro）を実行し、いずれか失敗で exit 1。 - 案 B
test:kpiはtest:rust+test-and-heal:proのみ（MCP 未起動ならヘッドレスで Pro 起動してから heal → test）。K1–K2 は別途npm run build:community/npm run build:proで確認。
必要に応じて tools/run-kpi-check.mjs などを追加し、上記チェックリストの 1, 2, 3, 6, 13 をスクリプト化する。
まとめ
- 改修: Phase 1–5 は既存実装で検証可能。Phase 6（Pro 埋め込み・ベクトル化・ANN） では M1（埋め込みロード安定化） が必須。M2（スタブ）・M3（ログ）は推奨。
- テスト計画: Phase 1 → 2 → 3 → 4 → 5 のあと、Phase 6 で M1 完了後に T1–T4（実機）、M2 完了時は T5–T6（スタブ）を実施。
- 一括確認: チェックリスト 1–14 に加え、15–18 で K16–K19 を確認。モデルを確実にロードしてテストに使えるようにするため、M1 の実施を優先する。