# Copilot 看得见你的工作区。Maguyva 画出整个仓库的地图。

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

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

VS Code 里的智能体只读你附加的文件和它自己搜到的文件。Maguyva 为整个仓库建立索引并通过 MCP 提供，所以智能体在编辑之前，会先问某个符号在哪里、谁在调用它。

> .vscode/mcp.json 里一条 servers 条目：一个 URL，一个 Authorization 头。

## VS Code 需要知道的事

VS Code 特有的四件事。

### .vscode/mcp.json

服务器放在 `servers` 下，而不是 `mcpServers`。想在所有工作区使用，运行 `MCP: Open User Configuration`，把同一条目加到你配置文件的 `mcp.json` 里。

### type: http

VS Code 通过 Streamable HTTP 连接 Maguyva 的端点，只有服务器不支持时才回退到 SSE。本地什么都不运行。

### 环境变量引用

请求头是 `Bearer ${env:MAGUYVA_API_KEY}`，VS Code 从启动它的环境中解析该值，所以密钥不会进入你提交的文件。更想被提示输入？用输入变量即可，只问一次并保存密钥。

### 工作区信任

一旦你信任该工作区，`.vscode/mcp.json` 里的服务器就会直接启动，不再单独询问；在受限模式下则永远不会启动。聊天输入框里的 Configure Tools 可以逐个开关工具。

## 自定义指令是一份工作约定，请善用它。

```text
# .github/copilot-instructions.md
- 宣布改动完成前先运行 npm test。
- 永远不要编辑 src/gen/ 下的生成文件。
```

VS Code 从 `.github/copilot-instructions.md` 或 `AGENTS.md` 读取全项目指令，从带 `applyTo` 模式的 `.github/instructions/*.instructions.md` 文件读取定向指令。用它们来写：

- 构建、测试和 lint 命令。
- 智能体反复弄错的约定。
- 智能体不该碰的目录。

指令告诉智能体怎么干活。它没法告诉智能体：四千个文件里，哪些导入了它马上要重命名的那个类型。

## 工作区视野的尽头

智能体从打开的文件里学不到的三件事。

### // 附加的不是全部

智能体依据你附加的内容和它搜索返回的结果工作。改动后会坏掉的、另一个包里的调用方，两份清单里都没有。

### // 文本匹配不是引用

工作区搜索能找到字符串，却分不清真正的调用和注释、mock，或另一个类里的同名方法。

### // 每次读取都消耗上下文

智能体为摸清情况而打开的每个文件，都在消耗改动所需的上下文。一条带 file:line 的排序答案，比十次探索性读取更省。

## Maguyva 作为 VS Code 中的 MCP 服务器

一条 servers 条目为智能体带来：

- **面向已索引仓库的 11 个工具**: 语义、结构（AST）、图和文本搜索，外加符号查找、依赖方和文件检索。
- **带文件路径和行号的答案**: 覆盖 285+ 种语言，智能体第一次就能打开正确的文件。
- **只读的工具**: Maguyva 的工具只查询索引，没有一个会修改你的文件，所以每次批准都只关乎读取，不涉及写入。

> VS Code 给智能体*你的工作区*。
> Maguyva 给智能体*仓库的地图*。

## 两种工作流

先问地图，再动手编辑。

### 01. 改解析器之前先找到测试

```text
vscode agent> 哪些测试会走到 parseConfig？

dependency_search("parseConfig", dependents)
  tests/config/parse.test.ts:12
  tests/cli/flags.test.ts:88

→ 改完后，智能体只运行这两个文件，而不是整套测试。
[exit 0]
```

答案点名了触及解析器的两个测试文件，智能体就在可能出问题的地方验证改动。

### 02. 第一次编辑前先评估重命名规模

```text
vscode agent> 把 OrderStatus.PENDING 重命名为 OrderStatus.QUEUED

find_symbol("OrderStatus", references)
  9 个文件中有 23 处引用

→ 智能体计划一次性改完这九个文件。
[exit 0]
```

引用数量在编辑之前就到手，而不是等类型检查失败之后。

## 在 VS Code 中配置

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

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

挑一个你已经熟悉的，这样你能给答案打分。

### 02. 把 Maguyva 加入 .vscode/mcp.json

`.vscode/mcp.json`

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

### 03. 设置密钥并启动服务器

在你启动 VS Code 的环境中设置 `MAGUYVA_API_KEY`，然后用条目上方的“启动”操作启动服务器。问智能体一个你已经知道答案的问题。

VS Code 的 [MCP 文档](https://code.visualstudio.com/docs/agent-customization/mcp-servers)介绍了输入变量、可移植的 .mcp.json 格式和服务器信任。

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

通过 MCP 连接 VS Code，然后问一个你能核实的问题。