# AGENTS.md 告訴 OpenCode 你的規則。Maguyva 讓它看見程式碼。

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

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

OpenCode 從 AGENTS.md 讀取工作方式，其餘一切都呼叫 MCP 伺服器。Maguyva 是一個遠端 MCP 伺服器，為 OpenCode 提供一張可查詢的程式碼庫地圖，附檔案路徑與行號。

> 在 mcp 底下加一筆遠端項目。本機什麼都不用跑。

## 關於 OpenCode 你需要知道的

四項 OpenCode 專屬事實。

### opencode.json

在專案的 `opencode.json` 中把伺服器加到 `mcp` 底下；若要所有專案都用，就加到 `~/.config/opencode/opencode.json`。

### type: remote

OpenCode 透過 HTTP 連到 Maguyva 的端點。本機什麼都不執行，也不需要 Node.js。

### 環境變數參照

OpenCode 會替換設定中的環境變數，所以標頭寫成 `Bearer {env:MAGUYVA_API_KEY}`，金鑰不會出現在你提交的檔案裡。

### 依代理限定範圍

每個 MCP 伺服器都會往脈絡裡加入工具定義。OpenCode 可以用 `"maguyva*": false` 這類 glob 在全域關閉某個伺服器的工具，再只為需要的代理重新開啟。

## AGENTS.md 是一份工作約定，儘管用。

```text
> /init
# 掃描程式碼庫並寫出 AGENTS.md
```

OpenCode 會讀取專案根目錄的 `AGENTS.md`，以及存放個人規則的 `~/.config/opencode/AGENTS.md`。沒有 `AGENTS.md` 時，會退回讀取 `CLAUDE.md`。適合寫進去的有：

- 建置、測試與 lint 指令。
- 代理應該遵守的慣例與界線。
- 指向重要文件的連結。

`/init` 當下的掃描是一份摘要，不是索引。它不會告訴 OpenCode 誰在呼叫昨天新增的函式。

## AGENTS.md 不夠用的地方

OpenCode 靠 grep 和耐心補上的三個缺口。

### // 摘要不是索引

AGENTS.md 可以點出重要的套件。它沒辦法列出每個符號和呼叫點，也不該嘗試。

### // grep 找到的是字串，不是呼叫端

文字比對分不清真正的呼叫、註解、測試替身，以及另一個類別上的同名方法。

### // 檔案會走樣

AGENTS.md 在寫成那天是對的。程式碼一直在變，檔案只有在有人想起來時才會更新。

## 作為 OpenCode 中遠端 MCP 伺服器的 Maguyva

在 mcp 底下加一筆項目，OpenCode 就能獲得：

- **針對已索引程式碼庫的 11 個工具**: 語意、結構（AST）、圖譜與文字搜尋，外加符號查找、依賴方與檔案擷取。
- **附檔案路徑與行號的答案**: 涵蓋 285+ 種語言。
- **每個模型都得到同樣的答案**: OpenCode 支援眾多模型供應商。不論哪個模型來問，Maguyva 回傳的都是同一張地圖。

> AGENTS.md 告訴 OpenCode *怎麼工作*。
> Maguyva 給 OpenCode *可以依據的東西*。

## 兩種工作流程

在同一個終端機裡問地圖。

### 01. 跨套件重新命名一個共用型別

```text
opencode> 把 OrderStatus 重新命名為 FulfillmentStatus

dependency_search("OrderStatus", dependents)
  分布在 8 個套件中的 23 處參照
structural_search(switch_statement, "OrderStatus")
  4 個窮舉式 switch

→ OpenCode 編輯完整清單，switch 也包含在內。
[exit 0]
```

正是這些窮舉式 switch，文字搜尋會漏掉，編譯器則很晚才抓到。

### 02. 分清程式碼和文件

```text
opencode> FEATURE_BULK_EXPORT 在哪裡被讀取？

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← 只有文件

→ 兩條程式碼路徑，一份過時的文件。
[exit 0]
```

精確比對連同路徑一起回傳，OpenCode 在編輯之前就能分清哪個是程式碼、哪個是文件。

## 在 OpenCode 中設定

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

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

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

### 02. 在 opencode.json 的 mcp 底下加入 Maguyva

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. 匯出金鑰並檢查連線

在啟動 OpenCode 的 shell 中設定 `MAGUYVA_API_KEY`。`opencode mcp list` 會列出每個已設定的伺服器；接著問一個你已經知道答案的問題。

OpenCode 的 [MCP 文件](https://opencode.ai/docs/mcp-servers/) 說明了逾時、OAuth 與依代理設定的工具存取。

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

透過 MCP 連接 OpenCode，然後問一個你能查證的問題。