# 实用手册

Canonical source: https://maguyva.ai/zh-hans/docs/cookbook

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

面向日常 Maguyva MCP 工作的实用操作指南。每份指南都会列出工具和顺序，但不是完整的参数参考。工具参数请参阅 [MCP API 参考](https://maguyva.ai/docs/mcp-api)；首次设置请参阅 [快速入门](https://maguyva.ai/docs/quickstart)。

### 选择合适的工具

大多数问题只需一次调用即可开始。只有首个答案范围太宽或信息不足时，才进一步调用工具。

- `intelligent_search` — 用自然语言询问代码库问题时，从这里开始。 默认的 auto/balanced 会在能够高置信度判断意图时，将定义类问题路由到结构搜索，将引用或影响类问题路由到图搜索，将精确匹配类问题路由到文本搜索。其他问题使用语义搜索和已索引文本。 使用 mode=hybrid，或将 auto 与 quality=thorough 搭配，即可请求全部四种搜索模式。显式指定的 mode 优先于 quality。
- `find_symbol` — 你已经知道函数、类或变量的名称。
- `dependency_search` — 评估影响范围：调用方、依赖该符号的代码，以及编辑前后的影响。
- `get_task_context` — 面对陌生区域时，根据任务描述获取限定范围的一组文件、符号和依赖项。
- `repository_context` — 列出可访问的仓库，或检查仓库名称如何解析。
- 带 `operation="guidance"` 的 `ask_maguyva` — 在本地获取工具选择和 Maguyva 使用帮助（不会修改仓库）。

这些 JSON 块是 MCP tools/call 的输入。请将 owner/repo、分支名称和符号名称替换为你自己的仓库中的值。

### 安装并验证客户端

将 Maguyva 接入你的 MCP 客户端，并通过真实仓库列表确认连接。

1. 在 [app.maguyva.ai](https://app.maguyva.ai) 中创建 API 密钥（密钥以 `mgv_` 开头）。
2. 连接并索引至少一个你已经熟悉的 GitHub 仓库。
3. 按照 [安装指南](https://maguyva.ai/docs/installation) 配置客户端（Claude Code 插件，或 Cursor、VS Code、Devin Desktop、Zed 等的原生远程配置）。
4. 向智能体询问 "我连接了哪些仓库？"，这会端到端验证身份认证和 `repository_context`。
5. 针对该仓库提出一个你能评判答案的真实问题。结果应包含索引树中的文件路径和行号。

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}
```

卡在密钥、桥接或仓库缺失问题上？请参阅 [故障排除](https://maguyva.ai/docs/troubleshooting)。

### 编辑之前先询问

修改共享代码前，先梳理符号和影响范围。Maguyva 工具不会修改仓库，而是为客户端在本地执行的编辑提供依据。

1. 如果知道符号名称，调用 `find_symbol` 定位定义和使用位置。
2. 如果只有任务描述（如“添加 SSO”或“修复账单 Webhook”），从 `get_task_context` 或 `intelligent_search` 开始。
3. 编辑共享符号前，调用 `dependency_search` 进行 dependents/impact 分析，查看依赖它的代码和影响（也可传入变更路径进行 PR 式影响分析），以看清影响范围。
4. 打开引用的文件（磁盘上的文件在本地读取；远程或跨仓库路径使用 `get_file`），并对照真实代码确认计划。
5. 编辑后，使用 `dependency_search`，指定 verify_after_edit=true 以及 targets 或 changed_paths，重新检查相同的符号。它读取的是已索引的图，而不是尚未提交的本地更改：将其视为新修订版本的依据前，请检查 indexed_commit_sha 和索引的新鲜度，并运行本地测试。

```json
{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}
```

完整参数：[MCP API 参考](https://maguyva.ai/docs/mcp-api)。

### 先搜索，再修改

默认智能体循环：探索 → 锁定符号 → 基于证据编辑。

1. 从 `intelligent_search` 和自然语言查询开始（如“会话过期如何工作”或“重试逻辑在哪里”）。
2. 如果首批结果噪声较多，可用语言或路径筛选器缩小范围。language_filter 会从 auto/hybrid 中排除图搜索；仅路由到图搜索的 auto 查询会回退到语义和文本搜索。显式图模式与 language_filter 不能搭配使用。查看 routing_decision.modalities_used 了解所选搜索计划；warnings 仅在服务器发出警告时才会出现。
3. 将有价值的命中交给 `find_symbol` 或 `dependency_search` 深挖，不要重复提出同一个模糊问题。
4. 只有在需要磁盘上不存在的特定已索引路径时才使用 `get_file`。
5. 使用常规客户端工具进行编辑。Maguyva 用于发现和验证，不负责写入。

```json
{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}
```

此循环有效的原因：[工作原理](https://maguyva.ai/docs/how-it-works)。

### 结果为空或信息不足

工具没有返回有用内容时，先修复仓库名称解析和索引问题，不要无休止地改写查询。

1. 在 [app.maguyva.ai](https://app.maguyva.ai) 中确认仓库已连接并完成索引。
2. 检查仓库字符串：`"owner/repo"` 使用默认分支；`"owner/repo:branch"` 固定分支。匹配不区分大小写，但不是模糊匹配，拼写错误不会自动纠正。
3. 使用 `action="info"` 调用 `repository_context`，检查仓库名称解析的元数据（例如 `metadata.resolution_reason`）。
4. 仅当 MCP 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，才省略 `repository`；否则请明确传入。
5. 使用更具体的查询、通过 `find_symbol` 查找已知符号，或添加语言/路径过滤器重试。如果连接本身有问题，请参阅 [故障排除](https://maguyva.ai/docs/troubleshooting)。

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}
```

设置故障：[故障排除](https://maguyva.ai/docs/troubleshooting)。

### 跨多个仓库工作

当一个密钥能看到多个仓库时，准确定位目标已索引仓库。

1. 使用 `action="list"` 调用一次 `repository_context`，了解该密钥可以搜索的确切仓库标识。
2. 需要非默认仓库时，在搜索和符号工具中明确传入 `repository`（例如 `"owner/other-repo"` 或 `"owner/other-repo:develop"`）。
3. 除非有意在不同调用中跨仓库比较，否则一个问题只对应一个仓库。
4. 文件位于已索引仓库而非当前工作树时，使用 `get_file`。
5. 请记住：工具绝不会写回 GitHub；多仓库上下文只用于读取和规划。

仓库格式详情：[MCP API 参考](https://maguyva.ai/docs/mcp-api)。

首次设置？从[快速入门](https://maguyva.ai/docs/quickstart)开始，再用这些操作指南处理日常任务。