feat(reference): Vector embedding 検索 MVP（Phase 4-E / Refs #191）

[akiojin]

Summary

• SPEC feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella) #191 (Phase 4 umbrella) の最終サブタスク Phase 4-E として、Vector embedding 検索を MVP として land する。
• fastembed-rs (BGE-Small-EN, ONNX Runtime) で symbol 単位の embedding を生成し、線形 scan ベースの cosine 類似度検索で曖昧クエリから関連シンボルを引けるようにする。
• gwt-discussion で確定したスコープ: lib = fastembed-rs + 線形 scan / build = explicit reference embed-build / 対象 = symbol unit (Phase 2 + 4-A index 再利用) / model = BAAI/bge-small-en-v1.5 (~130MB)。

Changes

• Cargo.toml: fastembed = "4", bincode = "1" を [dependencies] に追加。fastembed は内部で ort (ONNX Runtime) / hf-hub / tokenizers を pull する。
• src/reference/embed.rs (新規):
  • Embedder trait + FastEmbedder (ONNX 実装) + test 用 MockEmbedder
  • EmbeddedSymbol / EmbeddingIndex の serde 型
  • symbol_to_text / build_embedding_index / save_embedding_index / load_embedding_index / search / cosine_similarity の純関数
  • 9 件のテスト（純関数中心、ONNX 不要）
• src/reference/mod.rs: execute_embed_build / execute_embed_search を追加し、maybe_execute_reference_tool に reference_embed_build / reference_embed_search 分岐を登録。dispatcher 経由テスト 3 件 (required query / cache missing / index missing)。
• src/cli.rs: ReferenceCommand::EmbedBuild { version } / EmbedSearch { query, version, top_k } variant。
• src/app/runner.rs::build_reference_call: 2 分岐 + 4 件のテスト。
• src/tooling/tool_catalog.rs: 2 tool を TOOL_NAMES / tool_executor::Local / is_read_only_tool (search のみ read_only、build は mutating) / tool_params_schema (required: query / なし) / parity count (127→129) に登録。
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/SKILL.md: ## Preferred Flow に embed-build / embed-search の使い分けを追記。
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/references/embed-search-playbook.md (新規): Phase 4-E の運用ガイド。
• docs/tools.md: Reference Cache (9 → 11 tools)、新 tool 行を追加。

Testing

• cargo fmt -- --check — clean
• cargo clippy --all-targets -- -D warnings — clean
• cargo test --bin unity-cli — 408 passed / 0 failed (embed 9 + dispatcher 3 + runner 4 を含む)
• cargo llvm-cov --all-targets --summary-only -- --test-threads=1 — TOTAL line coverage 90.67%
• unity-cli skills lint --severity error — 15 skills / 0 violations

ONNX 実 model を呼ぶ FastEmbedder は test 内では使わず、MockEmbedder で純関数経路をカバーするため CI でモデル download は発生しない。

Closing Issues

• None (umbrella SPEC feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella) #191 は完了せず、Refs のみ)

Related Issues / Links

• Umbrella: feat(reference): unity-csharp-reference Phase 4 - 内部実装の改善 (umbrella) #191
• Phase 4-A / B / C / D: PR feat(reference): member-level シンボル抽出 MVP（Phase 4-A / Refs #191） #197 / feat(reference): compute_line_diff を LCS / Myers 化（Phase 4-B / Refs #191） #193 / feat(reference): extract_token_at_cursor を C# lexer 化（Phase 4-C / Refs #191） #194 / feat(reference): reference fetch に zip fallback を追加（Phase 4-D / Refs #191） #196 (すべて MERGED)
• Phase 1-3: feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 / feat(reference): unity-csharp-reference Phase 2 - シンボル lookup インデックス #187 / feat(reference): unity-csharp-reference Phase 3 - バージョン差分と LSP 連携実験 #188 (MERGED)

Checklist

• Tests added/updated (16 件 / MockEmbedder で ONNX を回避)
• Lint/format passed (cargo clippy, cargo fmt, unity-cli skills lint)
• Documentation updated (skill SKILL.md / references/embed-search-playbook.md / docs/tools.md)
• Migration/backfill plan included — Not applicable: 既存 .unity-cli-index/symbols.json (Phase 2) には触らず、embeddings.bin を別ファイルとして追加する。先行 PR でも gitignore 済みの .unity-cli-index/ 配下。
• CHANGELOG impact considered — minor bump per Conventional Commits (feat)

Context

Phase 2 / 4-A で構築した symbol index は名前完全一致の lookup なので、「Animator まわりで使うコールバック型」のような曖昧な要求には応えられなかった。本 PR で reference embed-search --query "..." を提供し、LLM が自然言語クエリから関連シンボルを発見できるようにする。これで unity-csharp-reference の Phase 1-4 ロードマップ (umbrella #191 含む A/B/C/D/E) がすべて land する。

Out of Scope (umbrella #191 で継続管理)

• 多言語 model (multilingual-e5-large, ~520MB) は --model オプションで後追い
• HNSW / IVF / Annoy などの ANN は線形 scan MVP の後段に検討
• file-chunk 単位の embedding は別軸として後追い検討
• score 正規化 / re-ranking は未対応
• incremental rebuild (symbol index 更新時に embeddings.bin を patch する) は未対応

Notes

• fastembed = "4" 依存追加で Cargo.lock が大きく増えた (+~2000 lines)。ort / hf-hub / tokenizers の解決による。target binary は ONNX Runtime の dynamic load 機構を使うため、起動時 model 読み込み以外のオーバーヘッドは限定的。
• embed-build は数千 symbol 規模で数十秒〜数分。--top-k の既定値は 10。
• MockEmbedder は char コードを使った決定的なベクトルを返すだけの test double で、CI 環境で ONNX の有無に依存しない。

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9d7a6128-4359-4bf1-a1d0-aa38ff7b5db2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch work/20260511-0223

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}