給 VS Code 使用者

Copilot 看得見你的工作區。Maguyva 畫出儲存庫的地圖。

VS Code 裡的代理只讀你附加的檔案和它自己搜到的檔案。Maguyva 為整個儲存庫建立索引並透過 MCP 提供，所以代理在編輯之前，會先問某個符號在哪裡、誰在呼叫它。

Free 方案：3 個儲存庫, 最多索引 5 萬行儲存庫程式碼，免信用卡。

.vscode/mcp.json 裡一筆 servers 項目：一個 URL，一個 Authorization 標頭。

關於 VS Code 你需要知道的

VS Code 特有的四件事。

// 設定檔

.vscode/mcp.json

伺服器放在 servers 底下，而不是 mcpServers。想在所有工作區使用，執行 MCP: Open User Configuration，把同一筆項目加到你設定檔的 mcp.json。

// 傳輸

type: http

VS Code 透過 Streamable HTTP 連線到 Maguyva 的端點，只有伺服器不支援時才退回 SSE。本機什麼都不執行。

// 金鑰

環境變數參照

標頭是 Bearer ${env:MAGUYVA_API_KEY}，VS Code 會從啟動它的環境解析這個值，所以金鑰不會進到你提交的檔案。比較想被詢問？用輸入變數就好，只問一次並儲存金鑰。

// 信任

工作區信任

一旦你信任該工作區，.vscode/mcp.json 裡的伺服器就會直接啟動，不另外詢問；在受限模式下則永遠不會啟動。聊天輸入框的 Configure Tools 可以逐一開關工具。

自訂指示是一份工作約定，請善用它。

# .github/copilot-instructions.md
- 宣告變更完成前先執行 npm test。
- 永遠不要編輯 src/gen/ 底下的產生檔案。

VS Code 從 .github/copilot-instructions.md 或 AGENTS.md 讀取全專案指示，從帶有 applyTo 模式的 .github/instructions/*.instructions.md 檔案讀取針對性指示。用它們來寫：

建置、測試與 lint 指令。
代理一再弄錯的慣例。
代理不該碰的資料夾。

指示告訴代理怎麼工作。它沒辦法告訴代理：四千個檔案裡，哪些匯入了它正要重新命名的那個型別。

工作區視野的盡頭

代理從開啟的檔案學不到的三件事。

// 附加的不是全部

代理依據你附加的內容與它搜尋回傳的結果工作。變更後會壞掉的、另一個套件裡的呼叫端，兩份清單裡都沒有。

// 文字比對不是參照

工作區搜尋能找到字串，卻分不清真正的呼叫和註解、mock，或另一個類別裡的同名方法。

// 每次讀取都在消耗脈絡

代理為了摸清狀況而開啟的每個檔案，都在消耗變更所需的脈絡。一個附帶 file:line 的排序答案，比十次探索性讀取更省。

Maguyva 作為 VS Code 中的 MCP 伺服器

一筆 servers 項目為代理帶來：

針對已索引程式碼庫的 11 個工具 語意、結構（AST）、圖譜與文字搜尋，外加符號查找、依賴方與檔案擷取。
附檔案路徑與行號的答案 涵蓋 285+ 種語言，代理第一次就能開對檔案。
只會讀取的工具 Maguyva 的工具只查詢索引，沒有一個會修改你的檔案，所以每次核准都只關乎讀取，不涉及寫入。

VS Code 給代理你的工作區。
Maguyva 給代理儲存庫的地圖。

兩種工作流程

先問地圖，再動手編輯。

// workflow 01

改剖析器之前先找到測試

vscode agent> 哪些測試會經過 parseConfig？

dependency_search("parseConfig", dependents)
  tests/config/parse.test.ts:12
  tests/cli/flags.test.ts:88

→ 改完後，代理只執行這兩個檔案，而不是整套測試。
[exit 0]

答案點名了觸及剖析器的兩個測試檔，代理就在可能出問題的地方驗證變更。

// workflow 02

第一次編輯前先評估重新命名的規模

vscode agent> 把 OrderStatus.PENDING 重新命名為 OrderStatus.QUEUED

find_symbol("OrderStatus", references)
  9 個檔案中有 23 處參照

→ 代理規劃一次改完這九個檔案。
[exit 0]

參照數量在編輯之前就到手，而不是等型別檢查失敗之後。

在 VS Code 中設定

三個步驟。Free 方案：3 個儲存庫, 最多索引 5 萬行儲存庫程式碼，免信用卡。

// step 01

在 maguyva.ai 索引一個程式碼庫

挑一個你已經熟悉的，這樣你才能評分答案。

// step 02

把 Maguyva 加入 .vscode/mcp.json

.vscode/mcp.json

{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

// step 03

設定金鑰並啟動伺服器

在你啟動 VS Code 的環境中設定 MAGUYVA_API_KEY，再用項目上方的「啟動」操作啟動伺服器。問代理一個你已經知道答案的問題。