# Warp 的代理住在終端機裡。給它一張儲存庫地圖。

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

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

Warp 的代理執行指令並讀取輸出。Maguyva 為整個儲存庫建立索引並透過 MCP 提供，所以代理會直接問程式碼在哪裡，而不是反覆跑 grep 和 cat 直到碰到符合的結果。

> ~/.warp/.mcp.json 裡一筆 mcpServers 項目：一個 URL，一個 Authorization 標頭。

## 關於 Warp 你需要知道的

Warp 特有的四件事。

### ~/.warp/.mcp.json

Warp 會自動啟動這個全域檔案裡的伺服器。你也可以把同樣的 JSON 貼到 Settings → Agents → MCP servers → + Add。

### 遠端，以 URL 連線

`url` 項目透過 Streamable HTTP 或 SSE 連線。本機什麼都不執行，也不需要 Node.js。

### 直接寫在標頭裡

金鑰直接寫進 `Authorization` 標頭。把它放在全域檔案裡，不要放進你會提交的專案 `.warp/.mcp.json`。

### 從不自動啟動

Warp 會偵測複製下來的儲存庫裡的 `.warp/.mcp.json`，但每個伺服器都要等你手動啟動。開啟對應選項後，它也能讀取 Claude Code 與 Codex 設定中的伺服器。

## 專案規則是一份工作約定。善用它。

```text
# AGENTS.md
- 宣告變更完成前先執行 make test。
- 使用 bin/ 裡的腳本，不要臨時拼湊指令。
```

Warp 從 `AGENTS.md`（兩者都存在時以 `WARP.md` 為準）讀取專案規則，並在所有地方套用全域規則。用它們來寫：

- 建置、測試與部署指令。
- 代理一再弄錯的慣例。
- 代理絕對不能執行的指令。

規則告訴代理怎麼工作。它沒辦法告訴代理：你正要刪掉的那個環境變數，還有哪個服務在讀。

## 終端機裡 grep 的盡頭

shell 工作階段無法廉價學到的三件事。

### // 輸出一閃而過

代理執行的每個 grep 和 cat 都會進入對話。一次印出兩百行的搜尋，在正事開始前就燒掉了脈絡。

### // 符合不等於呼叫端

grep 分不清真正的呼叫和註解、fixture，或另一個類別裡的同名方法。

### // shell 從零開始

新的工作階段對儲存庫一無所知。Maguyva 的索引早已建好，所以第一個問題就能拿到排序後的答案。

## Maguyva 作為 Warp 中的 MCP 伺服器

一筆 mcpServers 項目為 Warp 的代理帶來：

- **針對已索引程式碼庫的 11 個工具**: 語意、結構（AST）、圖譜與文字搜尋，外加符號查找、依賴方與檔案擷取。
- **附檔案路徑與行號的答案**: 涵蓋 285+ 種語言，短到能在終端機窗格裡讀完。
- **只會讀取的工具**: Maguyva 的工具只查詢索引，既不修改檔案，也不執行指令。

> Warp 給代理*一個終端機*。
> Maguyva 給代理*一張程式碼地圖*。

## 兩種工作流程

先問地圖，再執行指令。

### 01. 把失敗的腳本追到源頭

```text
warp agent> deploy.sh 失敗：BUILD_ID 未設定。它在哪裡設定？

text_pattern_search("BUILD_ID=")
  ci/env.sh:9   export BUILD_ID=...
  docs/deploy.md:31   ← 說明文字

→ 代理 source ci/env.sh，然後重新部署。
[exit 0]
```

一次索引搜尋，取代對整個儲存庫的遞迴 grep 和它的全部輸出。

### 02. 改啟動步驟前先查呼叫端

```text
warp agent> 能不能別在啟動時跑遷移了？

dependency_search("runMigrations", dependents)
  3 個呼叫端：server.ts、worker.ts、scripts/seed.ts

→ 代理把這三處都移到發布步驟。
[exit 0]
```

呼叫端在變更之前就已到手，worker 不會對著舊 schema 啟動。

## 在 Warp 中設定

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

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

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

### 02. 把 Maguyva 加入 ~/.warp/.mcp.json

`~/.warp/.mcp.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
```

### 03. 替換預留位置，然後問一個問題

把 `mgv_xxxx` 換成你的 API 金鑰並儲存。在 Settings → Agents → MCP servers 確認伺服器正在執行，然後問一個你已經知道答案的問題。

Warp 的 [MCP 文件](https://docs.warp.dev/agents/capabilities/mcp/)說明了以檔案定義的伺服器、分享與驗證。

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

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