我們會閱讀每一則回饋，並非常重視您的意見。
欲查看所有可用的限定詞，請參考我們的文件。
載入時發生錯誤，請重新載入此頁面。
Semantic 是一個本地 Rust 服務，用於透過符號、範圍和邏輯圖進行確定性程式碼檢索。
請使用語意優先整合指南，搭配 RooCode、KiloCode、Codex、Claude 的接線、中介軟體政策控制及端對端流程圖：
目前實作的語意層包含邏輯節點、持久化控制/資料流邊、語意節點標籤，以及基於圖形的分群與排序。
服務綁定於 $SEMANTIC_API_BASE_URL。
semantic_cli 現為主要的本地入口點。它啟動與兼容性 API 及 MCP 適配器共用的應用層。
目前最快的本地安裝路徑仍是 Rust 原生方式：
本倉庫中也提供輔助腳本：
該腳本會將 semantic 二進位檔安裝到您的 Cargo bin 目錄，讓您可以指向任何其他專案，而無需移動 Semantic 倉庫。
一般 CLI 使用預設會重用現有的本地索引。如果 .semantic/semantic.db 已有索引檔案，semantic status、semantic retrieve、semantic route 和 semantic serve 等命令會重用該索引，而非每次執行都強制刷新整個倉庫。若需明確刷新，請使用 semantic index。
semantic status 現在也避免首次執行時的索引。在未索引的倉庫中，它會報告：
這使得 status 可作為大型倉庫在完整索引前的淺層預檢。
推薦的更廣泛可靠工作流程：
status 輸出現在也直接顯示大型倉庫的上手狀態：
當尚無索引時，仍可透過以下方式進行淺層導航：
這些操作會回退至直接檔案系統檢查支援的原始碼/文件檔案，讓 Semantic 在完整索引建立前提供輕量導航上下文。
您也可以只建立您關心的第一個區域：
針對性索引只更新指定的檔案/目錄，其他部分則保持未索引，直到您明確擴展覆蓋範圍。
針對性索引後，semantic status 會透過 indexed_path_hints 顯示這些已準備好的區域，例如：
這些提示摘要僅供展示。它們會隱藏內部/產生的路徑，如 .semantic/、.claude/ 及測試工作樹內部，確保階段性上手時真實原始碼根目錄突出。覆蓋真實狀態、儲存的索引內容及 index_region_status 保持不變。
檢索與路由流程現在也直接顯示覆蓋邊界：
對於部分索引的倉庫，路由驗證現在可顯示：
這使部分索引在正常 CLI 使用中變得明確，而非僅在請求指向索引區域外時隱性降級。當缺少覆蓋時，Semantic 也會建議下一步要執行的確切命令，例如：
index_readiness 是簡潔的機器可讀摘要：
index_recovery_mode 描述 Semantic 對缺失覆蓋所採取的行動：
index_recovery_delta 彙總成功自動索引重試後新增進入索引集的項目：
changed_files 使用與 indexed_path_hints 相同的展示過濾器，避免內部執行時路徑擠壓使用者面向的恢復摘要。added_file_count 仍反映完整的索引增量。
index_recovery_target_kind 告知恢復目標類型：
若您希望 Semantic 自動修復該缺口一次，路由與檢索現在支援明確選擇加入：
當該重試確實改善覆蓋時，文字輸出會包含：
若目標仍不存在或未覆蓋，Semantic 會保留原始未索引警告，而非錯誤宣稱重試成功。當請求指定精確檔案路徑時，重試會保持檔案範圍，而非擴大至包含目錄。
這表示 Semantic 預設索引了專注於原始碼的子集，排除重量級/產生路徑。這是上手保護措施，非完整階段性/延遲索引的宣稱。
路由文字輸出現在包含即時驗證狀態。當 Semantic 判斷回傳上下文需人工檢查時，CLI 會印出簡潔的 verification: needs_review 行及建議操作。它也會印出 verification_scope 行顯示選擇的符號與頂層檔案，mutation_safety 行表示可編輯路由狀態，若變異鄰域驗證失敗，還會印出 verification_graph_issue 行，指出缺失或多餘的檔案或符號。詳細模式會增加精確驗證檢查，如 target_in_file=true、target_span=false、scope_graph=false，以及 verification_graph_diff 行，顯示完整預期與實際鄰域摘要。使用 --output json 可取得完整驗證區塊與機器可讀問題。
針對自動化密集的本地流程，路由也支援驗證門檻：
當使用門檻時，路由文字輸出會在非零退出前印出簡潔摘要行，如 verification_gate: min=needs_review actual=needs_review 與 mutation_gate: min=ready actual=blocked，讓 CI 或本地日誌仍能顯示執行被接受或拒絕的原因。
對於被阻擋的實作或重構路由，Semantic 現在也嘗試在放棄前進行確定性精確重試。若該重試能透過檔案大綱或精確符號查找確認目標，該路由會被提升為 mutation_safety: ready，且重試證據會附加於驗證元資料中。
品質狀態也可直接從 CLI 取得，無需啟動完整執行路徑：
此功能讀取本地生成的品質快照，報告當前 stable、watch、drifting 健康狀態及近期檢索/路由延遲變化。狀態輸出將頂層健康拆分為 latency_health 與 graph_drift_health，包含簡潔機器可讀診斷（如 clean、latency_only_drift、graph_only_drift、mixed_drift），並顯示行動建議（如 no_action、watch_latency、inspect_graph_drift 等）、行動優先度、分診路徑、目標、主要命令、命令分類、來源工件、具體延遲熱點與圖形漂移熱點提示及其桶 ID，還有摘要查詢提示與範圍，方便優先檢查特定項目。在不完整變異案例中，查詢範圍會縮小至 mutation_scope_bucket，來源工件清單擴展包含完整品質報告 JSON，查詢提示指向 markdown 摘要中的穩定 mutation-scope-bucket 標籤，方便本地分診直接檢查變異信任覆蓋，而非僅廣泛圖形漂移摘要。快照還包含行動檢查清單與命令列表，方便非 clean 執行直接進入下一步。本地品質匯出器會在記錄最佳延遲前，對每個路由/檢索案例進行一次未計量的預熱通過，反映已熱身的 Semantic 行為，避免冷啟動成本過度反應。本地工件寫入 docs/doc_ignore/ 目錄。
目前 --quality --output json 狀態合約包含：
身份與狀態：kind、snapshot_path、status、health、latency_health、graph_drift_health、diagnosis
行動：action_recommendation、action_priority、triage_path、action_target
可執行分診：action_checklist、action_commands、action_primary_command
命令元資料：action_command_categories、action_primary_command_category
工件元資料：action_source_artifacts、summary_lookup_hint、summary_lookup_scope
延遲分診：latency_hotspot、latency_hotspot_bucket_id、latency_severity、latency_severity_reason、latency_score、latency_score_delta_vs_trailing、latency_score_direction
圖形漂移分診：graph_drift_hotspot、graph_drift_hotspot_bucket_id、leading_graph_drift、leading_graph_drift_fixture、graph_drift_trend、graph_drift_fixture_trend、top_worsening_graph_drift_fixture、graph_drift_severity、graph_drift_severity_reason、graph_drift_score、graph_drift_score_delta_vs_trailing、graph_drift_score_direction、leading_graph_drift_delta_vs_trailing_pp、mutation_scope_incomplete_rate
計數：regression_count、threshold_failure_count、fixture_count
彙總指標：retrieval.avg_latency_ms、retrieval.p95_latency_ms、retrieval.avg_latency_delta_vs_trailing、retrieval.p95_latency_delta_vs_trailing、route.avg_latency_ms、route.p95_latency_ms、route.avg_latency_delta_vs_trailing、route.p95_latency_delta_vs_trailing
Semantic 目前不應被描述為全球或任意外部倉庫的編輯路由超過 99% 準確。
目前專案可誠實宣稱的特點：
內建回退與警示行為：
透過 CLI-first 執行時提供舊版傳輸支援：
舊版二進位檔仍可用以維持相容性：
一個伴隨的 crate（project_summariser）會在會話開始時生成緊湊且適合大型語言模型的專案地圖，無需呼叫 LLM，完全基於現有索引。
或在 ide_autoroute 時自動附加 include_summary=true：
輸出（約 400–800 字元）：每檔案目的句、頂級符號、專案敘述、模組依賴概述。支援 JSON 與 markdown 格式。
完整設計請參考 semantic_project_summariser/PLAN.md（同層資料夾）。
本倉庫中還有可選的本地伴隨工具，可追蹤 retrieve、ide_autoroute 與 edit 任務的 token 使用量。
遙測資料以 NDJSON 格式寫入 .semantic/token_tracking/events.ndjson，並匯入 .semantic/token_tracking/tracker.sqlite。
MCP 橋接（mcp_bridge）提供兩個主要工具，涵蓋所有使用案例：
所有 27 個舊版命名工具仍保留以維持向後相容（見 GET /mcp/tools → legacy_tools）。
舊版 MCP 工具別名保留相容，但現在透過 retrieve 或 ide_autoroute 路由，而非依賴獨立主要入口點。
開發 A/B 測試套件使用的示範專案：
以 autoroute_first=true、single_file_fast_path=false、provider=openai，執行 11 項核心任務套件：
主要指標現為步驟節省（估計開發者步驟減少 27.78%），非每次呼叫的 token 節省。完整分析請見 docs/AB_TEST_DEV_RESULTS.md。
2026-03-27 測試套件增強：
第 6 階段 token 控制原語部分實作：
實作的推理檢索結合邏輯節點與依賴遍歷：
實作的圖形語意包含：
實作的成熟功能包含：
本階段的生產準備收尾：
第 4.5 階段新增模組感知索引與檢索：