給 OpenCode 使用者

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

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

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

在 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 是一份工作約定，儘管用。

> /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 可以依據的東西。

兩種工作流程

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

// workflow 01

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

opencode> 把 OrderStatus 重新命名為 FulfillmentStatus

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

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

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

// workflow 02

分清程式碼和文件

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 萬行儲存庫程式碼，免信用卡。

// step 01

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

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

// step 02

在 opencode.json 的 mcp 底下加入 Maguyva

opencode.json

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

// step 03

匯出金鑰並檢查連線

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