跳转到内容

面向 Gemini CLI 用户

GEMINI.md 告诉 Gemini 你的规则。
但不会告诉它你的代码。

GEMINI.md 设定工作上下文。MCP 让 Gemini 能够调用工具。Maguyva 是那台 MCP 服务器，为 Gemini 提供一张可查询的代码仓库地图，让第一次编辑不再是对文件结构的猜测。

免费开始查看 Gemini 配置说明

Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。

GEMINI.md 是上下文，MCP 是通道，Maguyva 是地图。

分层的技术栈

四个概念，各司其职。

// 上下文

GEMINI.md

Gemini 在这个代码仓库里该如何表现。

// 传输通道

MCP

Gemini 如何获取外部工具和上下文。

// 代码库

Maguyva

那台返回基于真实代码库事实的 MCP 服务器。

// 谁付钱

按工作区计费，而非按坐席

智能体不需要付坐席费。查看价格

GEMINI.md 是一份工作上下文，好好用它。

持久化的指令应该放进 GEMINI.md。它正适合承载：

  • Gemini 应该运行的构建、测试和 lint 命令。
  • 限定在某个目录范围内的“永远做 X / 永远别做 Y”护栏。
  • 命名规范和重构偏好。
  • 指向权威决策日志和架构说明的指引。

保持简洁，划定范围，提交它。

但 GEMINI.md 从来就不是为了充当你代码仓库中每一个符号、文件和调用点的可查询索引而设计的。

光靠 GEMINI.md 就力不从心的地方

四种失效模式，每张卡片一种。

// 上下文不是索引

告诉 Gemini 该怎么工作，不等于告诉它有什么存在。在陌生的包上做第一次编辑，还是得靠猜文件路径和函数名。GEMINI.md 没法列出每一个符号，你也不会希望它这么干。

// 文档会偏离代码

一段描述你队列拓扑结构的 GEMINI.md 内容，在有人引入新的消费者之前都是对的。此后代码才是唯一的真相来源，文档则自信满满地过时了。Gemini 读到的是错的那一份。

// 重命名是个图谱问题

“什么引用了这个类？”这个问题，markdown 文件是回答不了的。Gemini 要么在整个 monorepo 里 grep 一把碰运气，要么让你把调用点粘贴进对话。

// 上下文窗口不是免费的

上下文窗口大，不等于可查询索引。把 GEMINI.md 塞到 Gemini “知道得够多”为止，依然是在用推理预算去换取静态上下文的体积。

三层是如何配合的

Gemini 用户其实早就这么想问题了，这个页面只是把它说明白。

GEMINI.md

上下文

Gemini 如何表现

MCP

传输通道

如何获取信息

Maguyva

代码库事实

它看到了什么

  • GEMINI.md Gemini 在这个代码仓库里如何表现。
  • MCP Gemini 如何获取工具和上下文。（规范）
  • Maguyva 当 Gemini 向代码库提问时看到的东西。语义、AST、图谱和文本搜索的结果，都带着文件路径和行号返回。

GEMINI.md 告诉 Gemini 该怎么工作。

Maguyva 给 Gemini 提供可以据以工作的东西。

三种工作流

Gemini 专属场景，基于真实的调用图谱，而不是 Gemini 的 grep。

// workflow 01

重命名共享类之前，先找出所有依赖方

gemini> rename PaymentClient → BillingClient

graph::callers(PaymentClient)            跨 7 个包，共 12 处引用
graph::importers(src/payments/client.ts)  9 个引用方
graph::extends(PaymentClient)             2 个子类（RetryClient、MockClient）

→ Gemini 提出一份包含 21 处编辑的迁移方案，文件清单直接内联展示。
[exit 0]

Gemini 在开始编辑之前，先向 Maguyva 询问依赖方。返回的迁移清单基于真实图谱，而不是 Gemini 的记忆。

// workflow 02

找到真正的实现，而不是测试桩

gemini> normalizePhoneNumber 是怎么处理 E.164 格式的？

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← 真实实现
  test/util/phone.spec.ts:14  jest.mock(...)      ← 测试桩
[exit 0]

名字会骗人，mock 会遮住真实代码。Maguyva 会把真实实现排在测试 mock 之上。

// workflow 03

重构前先看清影响范围

gemini> 谁调用了 QueueDispatcher.publish？

graph::callers(QueueDispatcher.publish)
  3 处在 src/billing/*    1 处在 src/audit/*    1 处在 src/notifications/*
[exit 0]

跨包的调用点直接内联展示出来。改动依据的是真实的引用方，而不是 Gemini 的 grep。

在 Gemini CLI 中配置

三个步骤。Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。

  1. // step 01

    在 maguyva.ai 索引一个代码仓库

    选一个你熟悉的，方便你验证答案。

  2. // step 02

    在你的 Gemini CLI 设置中把 Maguyva 添加为 MCP 服务器

    // ~/.gemini/settings.json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

  3. // step 03

    问一个你已经知道答案的问题

    别一上来就把整个公司丢进去。先从一个代码仓库和一个可验证的问题开始。

自助注册已开放。

索引一个你已经熟悉的代码仓库。

通过 MCP 连接 Gemini，问一个你能自行验证答案的问题。

索引你的第一个仓库查看兼容性文档

免费方案：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。