# Maguyva 的工作原理

Canonical source: https://maguyva.ai/zh-hans/docs/how-it-works

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

连接一个 GitHub 代码仓库，Maguyva 会将其转化为多个可供你的智能体按需调用的可搜索视图。模型不再需要把整个文件塞进上下文，而是能按需访问符号、结构、文档、依赖关系和经过排序的代码片段，全部基于真实代码。

当你连接一个代码仓库时，Maguyva 会对代码、文档、清单文件、符号和依赖元数据运行云端摄取流水线。目标是一次性构建持久化的代码记忆，而不是让每次智能体运行都从零重新发现代码仓库。

这些流水线会产出多个专业数据层：精确文本搜索、语义检索、符号与引用查找、结构化视图，以及依赖关系图分析。不同的问题会被路由到不同的层。

Maguyva 提供 5 种检索能力：semantic, AST, symbol, dependency, text。intelligent_search 提供四种搜索模式：语义、文本、结构和图。 默认的 auto/balanced 会在能够高置信度判断意图时，将定义类问题路由到结构搜索，将引用或影响类问题路由到图搜索，将精确匹配类问题路由到文本搜索。其他问题使用语义搜索和已索引文本。 使用 mode=hybrid，或将 auto 与 quality=thorough 搭配，即可请求全部四种搜索模式。显式指定的 mode 优先于 quality。 language_filter 会从 auto/hybrid 中排除图搜索，与显式 mode=graph 搭配使用时会被拒绝。 来自多种模式的结果会合并，并按与查询的相关性排序。

私有代码仓库视图与所支持的 languages and text-based technologies 公开参考数据并列存在。你的智能体通过 MCP 工具访问整个系统——无论是在规划和验证阶段深度依赖它，还是在编辑过程中用作抽查校验，都可以。

### 1. 代码仓库摄取

- **代码结构分析**: 将文件解析为符号、引用和架构边界
- **依赖解析**: 映射文件、模块和符号之间的相互依赖关系
- **文档整合**: 将代码仓库文档和相关参考资料与代码一并纳入

### 路由与排序

- **相关性评分**: 根据搜索模式和质量预设选择检索依据，然后按与查询的相关性对匹配项排序
- **降噪处理**: 减少重复匹配并限制每个文件的分块数量，避免一个文件占满结果窗口
- **上下文优先级排序**: 默认保持结果有界且相关。重要性提升需通过 boost_by_importance=true 主动启用，适用于架构概览，并非默认排序策略

### 存储表示

- **语义检索**: 即使措辞不同，也能找到概念上相似的代码和文档
- **符号与结构化视图**: 支持精确符号查找、引用查询以及 AST 结构类问题
- **依赖关系图分析**: 追踪整个代码库中的调用方、导入关系和影响范围

### 安全特性

- **传输安全**: 与服务的连接使用 HTTPS/TLS
- **托管存储**: 索引数据存储在托管基础设施上，静态数据采用存储级加密
- **命名空间隔离**: 代码仓库数据在流水线和数据库查询路径中，均按工作区和命名空间进行隔离
- **访问控制**: 代码仓库访问受组织和命名空间边界限制

### 预期效果

- **更高的规划准确率**: 智能体在开始编码前，可以对照真实代码仓库验证方案
- **更安全的重构**: 影响范围和依赖检查能减少本可避免的破坏
- **更少的 token 浪费**: 只返回相关代码片段，而非整份文件
- **更快理解代码仓库**: 模型能快速获得基于真实代码的答案，而不必每次运行都重新摸索项目结构

### 自动更新

- **代码仓库同步**: 随代码变更从 GitHub 同步任务中刷新
- **增量处理**: 仅处理有变更的文件以提升效率
- **分支感知上下文**: 为每个 git 分支维护独立索引，让智能体看到与该分支匹配的正确上下文

Maguyva 以云托管 MCP 服务器的形式交付。你的智能体会调用所需视角对应的工具，而不必依赖模型从零记住你的架构。上面的四个界面是对具体工具的分组视图：语义搜索涵盖 `semantic_search` 和 `intelligent_search`；符号查找涵盖 `find_symbol` 和 `get_task_context`；结构搜索涵盖 `structural_search` 和 `text_pattern_search`；依赖关系图涵盖 `dependency_search` 和 `analyze_dependencies`——此外还有作为辅助工具的 `get_file`、`repository_context` 和 `ask_maguyva`。全部 11 个工具请参阅完整的 [MCP API 参考文档](https://maguyva.ai/docs/mcp-api)。

性能表现会因代码库规模和查询复杂度而异。Maguyva 专注于提供最相关的上下文，而不是倾倒整份文件。支持的语言和客户端请参阅[兼容性](https://maguyva.ai/docs/compatibility)。

实际效果因代码库规模、复杂度以及 AI 智能体处理的查询类型而异。

通过 Maguyva 门户连接 GitHub 仓库。代码变更后，GitHub 同步任务会刷新索引。门户还提供 API 使用情况。