# 操作手冊

Canonical source: https://maguyva.ai/zh-hant/docs/cookbook

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).

Maguyva MCP 日常工作的實用操作指南。每份指南都列出所用工具與操作順序，而不是完整的參數說明。工具參數請參閱 [MCP API 參考](https://maguyva.ai/docs/mcp-api)；首次設定請參閱 [快速入門](https://maguyva.ai/docs/quickstart)。

### 選擇正確的工具

大多數問題都是從一次工具呼叫開始的。只有在第一個答案太寬泛或資訊太少時才升級。

- `intelligent_search` — 以自然語言詢問程式碼庫時，從這裡開始。預設的 auto/balanced 會將能高度確定是在詢問定義的查詢導向結構搜尋，將參照或影響查詢導向圖搜尋，將精確比對查詢導向文字搜尋。其他查詢使用語意與已索引文字。使用 mode=hybrid，或在 auto 下設定 quality=thorough，即可要求全部四種搜尋方式；明確指定的模式優先於 quality。
- `find_symbol` — 你已經知道函式、類別或變數名稱。
- `dependency_search` — 影響範圍：呼叫端、依賴該符號的程式碼，以及編輯前後的影響。
- `get_task_context` — 面對陌生的程式碼區域時，依任務描述取得一組範圍有限的檔案、符號與依賴關係。
- `repository_context` — 列出可存取的儲存庫或檢查儲存庫名稱的解析方式。
- `ask_maguyva` 搭配 `operation="guidance"` — 工具內的使用說明，協助選擇工具與使用 Maguyva（不會修改儲存庫）。

這些 JSON 區塊是 MCP tools/call 的輸入。請將 owner/repo、分支名稱與符號名稱替換為你儲存庫中的值。

### 安裝並驗證用戶端

將 Maguyva 接入你的 MCP 用戶端，並取得真實的儲存庫清單以確認連線正常。

1. 在 [app.maguyva.ai](https://app.maguyva.ai) 中建立 API 金鑰（金鑰以 `mgv_` 開頭）。
2. 連接並索引至少一個你已經了解的 GitHub 儲存庫。
3. 使用 [安裝指南](https://maguyva.ai/docs/installation)（Claude Code 外掛或 Cursor、VS Code、Devin Desktop、Zed 等的原生遠端連線設定）連接你的用戶端。
4. 詢問你的代理 "我連接了哪些儲存庫？" — 端對端執行身份驗證和 `repository_context`。
5. 詢問一個有關該儲存庫的真實問題，你可以對其答案進行評分。你應該會看到索引樹中的檔案路徑和行號。

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}
```

遇到 API 金鑰、橋接設定或找不到儲存庫的問題？ [疑難排解](https://maguyva.ai/docs/troubleshooting)。

### 編輯前詢問

更改共用程式碼之前掌握符號及其影響範圍。 Maguyva 工具不會修改你的儲存庫 - 它們為用戶端在本機套用的編輯提供依據。

1. 如果你知道符號名稱，請呼叫 `find_symbol` 來了解定義和用途。
2. 如果你只有任務描述（「新增 SSO」、「修復計費 Webhook」），請從 `get_task_context` 或 `intelligent_search` 開始。
3. 編輯共用符號前，請呼叫 `dependency_search` 分析依賴該符號的程式碼或變更影響（也可傳入變更路徑，進行 PR 式影響分析），以了解影響範圍。
4. 開啟引用的檔案（本機讀取磁碟上的檔案；`get_file` 用於遠端/跨儲存庫路徑）並根據實際程式碼確認計畫。
5. 編輯後，使用 `dependency_search`，指定 verify_after_edit=true 以及 targets 或 changed_paths，重新檢查相同符號。它讀取的是已索引的圖，而不是尚未提交的本機變更：將其視為新修訂版本的依據前，請檢查 indexed_commit_sha 與索引的新鮮度，並執行本機測試。

```json
{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}
```

完整參數：[MCP API 參考](https://maguyva.ai/docs/mcp-api)。

### 搜尋，然後更改

預設代理循環：探索→鎖定符號→依據證據進行編輯。

1. 從 `intelligent_search` 和簡單語言查詢開始（「會話過期如何運作」、「重試邏輯在哪裡」）。
2. 若第一批結果有過多無關資訊，可用語言或路徑篩選器縮小範圍。language_filter 會從 auto/hybrid 排除圖搜尋；若 auto 查詢原本僅導向圖搜尋，則會退回語意與文字搜尋。明確指定圖模式並搭配 language_filter 時，請求會遭拒。查看 routing_decision.modalities_used 即可了解選定的搜尋計畫；warnings 只有在伺服器提出警告時才會出現。
3. 針對看來有用的搜尋結果，進一步使用 `find_symbol` 或 `dependency_search`，而不是重複提出同一個模糊問題。
4. 僅當你需要不在磁碟上的特定索引路徑時才使用 `get_file`。
5. 在普通用戶端工具中進行編輯。 Maguyva 用於發現和驗證——而不是寫入。

```json
{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}
```

為什麼這個循環有效：[運作原理](https://maguyva.ai/docs/how-it-works)。

### 結果為空或資訊不足

工具沒有傳回有用結果時，先修正儲存庫名稱解析與索引問題，別只是不斷重寫查詢。

1. 確認儲存庫已連線並完成 [app.maguyva.ai](https://app.maguyva.ai) 中的索引。
2. 檢查儲存庫字串：`"owner/repo"` 使用預設分支；`"owner/repo:branch"` 指定分支。匹配不區分大小寫，而不是模糊 - 拼寫錯誤不會自動更正。
3. 使用 `action="info"` 呼叫 `repository_context` 並檢查解析元資料（例如 `metadata.resolution_reason`）。
4. 只有當你的 MCP 用戶端提供請求預設值或金鑰只能存取一個儲存庫時，才省略 `repository`；否則明確傳遞它。
5. 使用更具體的查詢、透過 `find_symbol` 的已知符號名稱或語言/路徑過濾器重試。如果連接本身損壞，請使用[疑難排解](https://maguyva.ai/docs/troubleshooting)。

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}
```

設定失敗：[疑難排解](https://maguyva.ai/docs/troubleshooting)。

### 跨多個儲存庫工作

當一個 API 金鑰可存取多個儲存庫時，以正確的索引儲存庫為目標。

1. 使用 `action="list"` 呼叫 `repository_context` 一次，以了解你的金鑰可以搜尋的確切的儲存庫識別名稱。
2. 當你需要非預設儲存庫（例如 `"owner/other-repo"` 或 `"owner/other-repo:develop"`）時，在搜尋和符號工具上明確傳遞 `repository`。
3. 保持一個問題=一個儲存庫，除非你有意在單獨的呼叫中跨儲存庫進行比較。
4. 當檔案位於不是目前工作樹的索引儲存庫中時，請使用 `get_file`。
5. 請記住：工具永遠不會寫回 GitHub - 多儲存庫上下文僅用於閱讀和規劃。

儲存庫格式詳細資訊：[MCP API 參考](https://maguyva.ai/docs/mcp-api)。

首次設定？從[快速入門](https://maguyva.ai/docs/quickstart)開始，再用這些操作指南處理日常任務。