# AGENTS.md 告诉 OpenCode 你的规则。Maguyva 让它看到代码。

Canonical source: https://maguyva.ai/zh-hans/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 找到的是字符串，不是调用方

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

### // 文件会跑偏

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，然后问一个你能核实的问题。