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

Canonical source: https://maguyva.ai/zh-hant/for-vscode

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

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

> .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 可以逐一開關工具。

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

```text
# .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 給代理*儲存庫的地圖*。

## 兩種工作流程

先問地圖，再動手編輯。

### 01. 改剖析器之前先找到測試

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

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

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

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

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

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

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

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

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

## 在 VS Code 中設定

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

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

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

### 02. 把 Maguyva 加入 .vscode/mcp.json

`.vscode/mcp.json`

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

### 03. 設定金鑰並啟動伺服器

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

VS Code 的 [MCP 文件](https://code.visualstudio.com/docs/agent-customization/mcp-servers)說明了輸入變數、可攜式 .mcp.json 格式與伺服器信任。

## 索引一個你已經熟悉的程式碼庫。

透過 MCP 連接 VS Code，再問一個你能查證的問題。