# Cursor 编辑文件。Maguyva 看见整个仓库。

Canonical source: https://maguyva.ai/zh-hans/for-cursor

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

Cursor 是编辑器。在 monorepo 里，智能体依然需要一张“哪个文件重要”的地图。Maguyva 索引你的代码库，并通过 MCP 提供语义、AST、图谱和文本检索，于是“鉴权发生在哪里”返回的是真实的鉴权流程，而不是七个测试桩。

> Cursor 编辑你指向的内容。Maguyva 告诉智能体该指向哪个文件。

## 每一层各自的作用

四个部件，各司其职。

### Cursor

你实际写代码的地方。

### @ 提及 + pin 文件

手动维护上下文很管用，直到仓库变大为止。

### Maguyva

通过 MCP 自动提供代码库真实情况。

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

智能体不需要付坐席费。[查看定价](https://maguyva.ai/zh-hans/pricing)

## Cursor 是编辑器，好好用它。

IDE 本身不是问题。Cursor 的 Tab 补全、AI 编辑、多文件编辑，以及 `.cursor/rules` 都非常出色，你已经在用它们做这些事：

- 在当前打开的文件里做内联建议和 AI 编辑。
- 当改动是局部的时候做多文件编辑。
- 用 `.cursor/rules` 定义代码仓库规范和风格护栏。
- 用 `@` 提及把某个特定文件拉进上下文。

继续这样用，这些都不会消失。

但在真实的 monorepo 里（有工作区依赖的 TypeScript、Python 服务、混合包结构），一旦相关文件还没进入你的视野，智能体的上下文就会崩掉。

## 你已经试过的手动办法，以及它们失效的地方

四种手动方法及其失效模式。左边 = 你今天在做的事。右边 = 它失效的地方。

### // pin 住文件

你 `@` 提及你认为重要的三个文件。Cursor 能在里面干净利落地编辑。

### // pin 住本质上是猜测

只有当你已经知道涉及哪些文件时，pin 住才管用。上下文工具存在的意义，恰恰是把你根本不知道该 pin 住的文件找出来。

### // 粘贴代码片段

你把另一个包里的 200 行代码粘贴进对话，好让智能体获得足够的上下文。

### // 粘贴的代码会过期

你早上 9 点粘贴的代码片段，反映不出队友 11 点 rebase 之后的样子。智能体正在对着一个幽灵版本的包做编辑。

### // 写一份上下文文档

你写了一个 `.cursor/rules` 文件或一篇架构 markdown。今天看它是对的。

### // 文档漂移的速度比代码快

任何手写的东西都会漂移。代码才是唯一的真相来源。一篇解释队列层的文档能正确一周，然后就永远错下去了。

### // 保留规则文件

你添加 `.cursor/rules` 来定义命名、lint、构建命令。对约束行为很好用。

### // 规则 ≠ 索引

`.cursor/rules` 正适合写“提交前必须运行 pnpm tsc -b”这类规则。但它不是你 monorepo 里每一个符号、文件和调用点的可查询索引。

## Maguyva 是底下的那一层

不是要取代 Cursor，而是挂在 Cursor 的 MCP 支持之下的那层仓库上下文。

- **语义 + AST + 图谱 + 文本**: 按含义、结构、依赖关系或字面文本搜索。每个命中结果都会返回文件路径和行号。
- **默认跨包**: 覆盖 monorepo 中每一个包的调用点和引用方，而不只是当前打开的那个包。
- **分支感知**: Maguyva 看到的是 Cursor 正在编辑的那个版本的代码。
- **互补而非竞争**: `.cursor/rules` 继续做它该做的事，`@` 提及继续做它该做的事。Maguyva 填补的是它们都填补不了的空白。

> Cursor 编辑你指向的文件。
> Maguyva 告诉智能体*该指向哪个文件。*

## 三种 monorepo 工作流

跨包、跨语言，基于真实的调用图谱，而不是 Cursor 的 grep。

### 01. 在不 pin 住任何文件的情况下，跨包找到鉴权流程

```text
cursor> 这个 monorepo 里，身份验证发生在哪里？

graph::query("authentication flow")
  packages/web/src/auth/session.ts:42       中间件
  packages/api/src/auth/jwt.ts:88           令牌校验
  packages/shared/src/auth/types.ts:12      AuthContext
  packages/admin/src/auth/admin-only.ts:31  权限门禁

→ 4 个包中的 4 个入口点，按调用点密度排序。
[exit 0]
```

你没有 pin 住任何文件，也没有粘贴任何代码片段。智能体拿到的是真正重要的四个文件，排序也是对的，可以据此做出有根据的编辑。

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

```text
cursor> normalizePhoneNumber 是怎么处理 E.164 格式的？

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

名字会骗人，mock 会遮住真实代码。Maguyva 会在所有包范围内，把真实实现排在测试 mock 之上。

### 03. 重构前先看清影响范围

```text
cursor> 整个 monorepo 里，谁调用了 QueueDispatcher.publish？

graph::callers(QueueDispatcher.publish)
  3 处在 packages/billing/*
  1 处在 packages/audit/*
  1 处在 packages/notifications/*
  1 处在 services/python-worker/*  ← 通过 gRPC 桩跨语言调用
[exit 0]
```

跨包，如果是多语言仓库还能跨语言，调用点直接内联展示出来。改动依据的是真实的引用方，而不是 Cursor 的 grep。

## 在 Cursor 中配置

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

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

选那个上下文问题最让你头疼的 monorepo。

### 02. 在 Cursor 设置中把 Maguyva 添加为 MCP 服务器

`~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

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

别一上来就把整个公司丢进去。先从一个代码仓库和一个可验证的问题开始，比如“跨包范围内，谁调用了 `formatInvoice`？”

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

测试一个你能自行验证答案的问题。