面向 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 找到的是字符串，不是调用方

文本匹配分不清真正的调用、注释、mock，以及另一个类上的同名方法。

// 文件会跑偏

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 会列出每个已配置的服务器；然后问一个你已经知道答案的问题。