Copilot 如何理解您的工作区

Copilot 智能体（Agents）会搜索您的整个代码库，以了解组件之间的关联，并提供基于您实际代码的回答。您可以使用诸如“身份验证是在哪里处理的？”或“为列表端点添加测试”这类宽泛的提示词，并根据您的代码库获得准确的答案和代码编辑。

本文介绍了 Copilot 如何理解您的代码库，包括它用于搜索代码的不同工具，以及为实现快速搜索而创建的索引。这些通用方法适用于所有规模的代码库，从只有五个文件到拥有 50 万个文件的项目皆是如此。

搜索与读取工具

当您发送提示词时，Copilot 会分析它所需的信息，并自动选择搜索工具的正确组合，以回答您的问题或开始生成代码编辑。Copilot 会为此运行多种工具，审查结果，并自动执行后续搜索，直到它对问题有充分的理解。

例如，当被要求“为支付服务添加错误处理”时，智能体可能会：

1. 使用语义搜索查找整个项目中与支付相关的代码。
2. 使用 grep 查找代码库中现有的错误处理模式。
3. 使用用法（usages）追踪支付函数是如何被调用的。
4. 使用文件搜索定位相关的配置文件和测试文件。
5. 读取相关文件并进行协调一致的更改。

这种迭代方法意味着智能体像开发人员一样收集上下文：通过从多个角度探索代码库，直到获得完整的图像。

智能体可以使用以下内置搜索工具。您也可以通过键入 # 后跟工具名称来在提示词中明确引用这些工具。

这些工具适用于任何工作区规模。对于小型项目，整个工作区可以直接读入智能体的上下文中。对于大型项目，智能体会根据您的项目规模和可用资源选择最高效的搜索策略。

搜索工作区之外的 GitHub 仓库

除了搜索当前工作区外，智能体还可以搜索其他 GitHub 仓库中的代码。当智能体需要了解未在本地打开的代码库（例如查找上游库中的 API 或比较不同仓库间的实现）时，这非常有用。

对于更高级的 GitHub 工作流程，例如搜索和管理议题（Issues）或合并请求（Pull Requests），请使用 GitHub MCP 服务器。

智能体可以访问的内容

智能体搜索的来源与开发人员在浏览代码库时使用的来源相同：

• 工作区中所有可索引的文件，但不包括 .gitignore 文件忽略的文件。
• 包含嵌套文件夹和文件名的目录结构。
• 代码符号和定义（类、函数、变量）。
• 当前处于活动编辑器中选定的文本或可见文本。
• 对话历史记录和之前的工具结果。

语义搜索

语义搜索工具 (#codebase) 是通过含义而非确切关键词来查找代码的。

语义搜索需要构建和维护索引，以便即使在非常大的代码库上也能快速运行。Copilot 会为您自动维护此索引。在后台，索引的部分内容可能存储在您的计算机上，部分可能来自远程源，但您无需管理这种区别。

您可以在 VS Code 状态栏的 Copilot 状态仪表板中查看索引状态。

语义索引源

Copilot 会自动为任何工作区构建和维护语义索引。索引源决定了索引首次可用的速度：

• GitHub 仓库：GitHub 会为您工作区中的 GitHub 仓库建立索引。使用您的 GitHub 账号登录以使用它们。此索引每个仓库只需构建一次，这意味着它通常可以立即使用。GitHub 会在需要时构建和更新此索引。对于中小型项目，速度很快；但如果您的仓库包含数十万个文件，可能需要一些时间。远程索引适用于托管在 GitHub.com 或 GitHub Enterprise Cloud 上的仓库。GitHub Enterprise Server 不支持此功能。

• Azure DevOps 仓库：索引会自动构建和维护。在 VS Code 中使用您的 Microsoft 账号登录，以便 Copilot 开始使用索引。检查 Copilot 状态栏项目以获取当前索引状态。

• 其他工作区：对于任何其他工作区，包括不由 GitHub 或 Azure DevOps 仓库支持的本地文件夹，Copilot 都会为您构建语义索引。初始构建可能需要几分钟，之后索引会在后台保持更新。此功能目前已对个人账户启用，但对于组织和企业用户，默认处于关闭状态。有关如何使用策略启用此功能的更多详情，请参阅 GitHub 文档。

若要按需为当前工作区构建或重建索引，请从命令面板运行构建代码库语义索引（Build Codebase semantic index）命令。

语义索引包含哪些内容

VS Code 会索引当前项目中相关的文本文件。这不限于特定的文件类型或编程语言。VS Code 会自动跳过一些通常不相关且常见的类型，例如 .tmp 或 .out 文件。

工作区索引还会排除通过 files.exclude 在 VS Code 中打开 在 VS Code Insiders 中打开 设置或 .gitignore 文件在 VS Code 中排除的文件。

二进制文件（如图像或 PDF）不会被索引。

获得更好结果的建议

您表述提示词的方式会影响智能体使用的工具以及结果的质量。

• 具体一点：避免使用“这有什么作用”这类含糊的词，“这”可能指代上一个答案、当前文件或整个项目。
• 使用代码术语：使用出现在代码中的函数名、类名和概念，以便智能体能找到准确的匹配项。
• 手动添加上下文：选择代码、引用文件或使用 #-提及上下文项，如调试上下文、终端输出等。
• 限定请求范围：回答可以借鉴多个参考资料，例如“查找没有 catch 块的异常”。但不要期望它能进行全面的代码库分析，例如“这个函数被调用了多少次？”。
• 针对非代码问题使用外部工具：对于“谁对此文件做出了贡献？”这类信息，请配置相关的工具或 MCP 服务器。

私有仓库

要对私有仓库使用语义搜索，Copilot 可能需要额外的权限。如果尚未授予这些权限，VS Code 会在启动时请求它们。一旦授予，会话将被安全地保存以供将来使用。

在 GitHub Copilot 信任中心中了解更多关于安全、隐私和透明度的信息。

常见问题

我需要在提示词中使用 #codebase 吗？

不需要。智能体会在合理时自动使用语义搜索。您不需要在提示词中添加 #codebase。

#codebase 工具始终是语义化的，并提供一致的结果。如果您想强制对特定提示词进行语义搜索，仍然可以添加 #codebase 作为上下文项。

如果我的工作区没有进行语义索引会怎样？

大多数工作区都会自动建立索引，但如果索引尚不可用（例如，当一个新的本地工作区仍在构建初始索引时），智能体仍可以通过使用文本搜索、grep、文件搜索和语言智能来有效地搜索您的代码。工作区索引启用了语义搜索，可以通过含义而非关键词来查找代码。如果没有它，智能体将依赖其他搜索工具，并且仍然可以为大多数提示词提供准确的结果。我们发现这些其他工具仍然可以提供很好的结果。