# Maguyva 如何運作

Canonical source: https://maguyva.ai/zh-hant/docs/how-it-works

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

連接一個 GitHub 儲存庫，Maguyva 就會將它轉換成多種可搜尋的資料檢視，供你的代理隨需取用。模型不必把整份檔案塞進脈絡視窗，而是能有憑有據地存取符號、結構、文件、依賴關係，以及經過排序的程式碼片段。

當你連接儲存庫時，Maguyva 會針對程式碼、文件、manifest 檔案、符號與依賴關係中繼資料執行雲端擷取管線。目標是一次建立持久的程式碼記憶，而不必讓每次代理執行都從零重新探索儲存庫。

這些管線會產出多個專用資料層：精確文字搜尋、語意檢索、符號與參照查找、結構檢視，以及依賴關係圖分析。不同的問題會導向不同的資料層。

Maguyva 提供 5 種檢索功能：semantic, AST, symbol, dependency, text。intelligent_search 內有四種搜尋方式：語意、文字、結構與圖。預設的 auto/balanced 會將能高度確定是在詢問定義的查詢導向結構搜尋，將參照或影響查詢導向圖搜尋，將精確比對查詢導向文字搜尋。其他查詢使用語意與已索引文字。使用 mode=hybrid，或在 auto 下設定 quality=thorough，即可要求全部四種搜尋方式；明確指定的模式優先於 quality。 language_filter 會從 auto/hybrid 排除圖搜尋，且不能搭配明確指定的圖模式，否則請求會遭拒。來自多種搜尋方式的結果會融合，並依與查詢的相關性排序。

私有儲存庫的資料檢視，與受支援languages and text-based technologies的公開參考資料一併提供。你的代理透過 MCP 工具存取整個系統，你可以在規劃與驗證階段大量仰賴它，也可以在編輯過程中拿來做抽查。

### 1. 儲存庫擷取

- **程式碼結構分析**: 將檔案剖析為符號、參照與架構邊界
- **依賴關係解析**: 對應檔案、模組與符號之間的相依關係
- **文件整合**: 將儲存庫文件與相關參考資料，一併納入程式碼旁

### 路由與排序

- **相關性評分**: 依搜尋模式與品質預設選擇檢索依據，再依與查詢的相關性排序符合項目
- **雜訊過濾**: 減少重複符合項目並限制每個檔案的區塊數量，避免單一檔案占滿結果視窗
- **脈絡優先排序**: 預設保持結果有界且相關。重要性提升需透過 boost_by_importance=true 主動啟用，適用於架構概覽，並非預設排序策略

### 儲存的資料表示

- **語意檢索**: 即使用字不同，也能找出概念相近的程式碼與文件
- **符號與結構檢視**: 支援精確符號查找、參照，以及基於 AST 結構的問題
- **依賴關係圖分析**: 追蹤整個程式碼庫中的呼叫端、匯入關係與影響範圍

### 安全功能

- **傳輸安全**: 連線至服務使用 HTTPS/TLS
- **託管儲存**: 索引資料儲存於受管理的基礎設施，並對靜態資料採用儲存層加密
- **命名空間隔離**: 儲存庫資料會透過管線與資料庫查詢路徑，依工作區與命名空間進行範圍限制
- **存取控制**: 儲存庫存取權限受組織與命名空間邊界限制

### 你可以期待什麼

- **更準確的規劃**: 代理能在開始寫程式前，先根據實際儲存庫驗證方案
- **更安全的重構**: 影響範圍與依賴關係檢查，能減少可避免的破壞
- **更少的 token 浪費**: 只回傳相關片段，而非整份檔案
- **更快理解儲存庫**: 模型能快速取得有憑有據的答案，不必每次執行都重新探索專案結構

### 自動更新

- **儲存庫同步**: 隨著程式碼變更，透過 GitHub 同步作業重新整理
- **增量處理**: 只處理變更過的檔案，以提升效率
- **分支感知脈絡**: 為每個 git 分支維護獨立索引，讓代理在每個分支都能看到正確的脈絡

Maguyva 以雲端託管的 MCP 伺服器形式提供服務。你的代理會呼叫所需檢視角度對應的工具，而不必仰賴模型從零記住你的架構。上方的四個介面是對具體工具的分組檢視：語意搜尋涵蓋 `semantic_search` 與 `intelligent_search`；符號查找涵蓋 `find_symbol` 與 `get_task_context`；結構搜尋涵蓋 `structural_search` 與 `text_pattern_search`；依賴關係圖涵蓋 `dependency_search` 與 `analyze_dependencies`——此外還有作為輔助工具的 `get_file`、`repository_context` 與 `ask_maguyva`。全部 11 個工具請參閱完整的 [MCP API 參考文件](https://maguyva.ai/docs/mcp-api)。

效能會依程式碼庫規模與查詢複雜度而異。Maguyva 專注於提供最相關的脈絡，而非將整份檔案塞進脈絡。支援的語言與用戶端請參閱[相容性](https://maguyva.ai/docs/compatibility)。

實際成效會因程式碼庫規模、複雜度，以及 AI 代理處理的查詢類型而異。

透過 Maguyva 入口網站連接 GitHub 儲存庫。程式碼變更後，GitHub 同步工作會更新索引。入口網站也提供 API 使用情況。