字数

1899 字

阅读时间

8 分钟

在 VS Code 中使用 GitHub Copilot 时，@ 语法（称为 Context Mentions 或 上下文提及）是实现轻量级 RAG（检索增强生成）的核心交互方式。它允许你显式地告诉 Copilot：“请基于这个特定的文件或整个工作区的上下文来回答我的问题”，而不是让它仅凭训练数据瞎猜。

以下是 @workspace 和 @file 的详细用法、原理及实战技巧：

---

1. @file：精准定位单个文件

当你需要针对某个具体文件的代码逻辑、注释或错误进行提问时使用。

• 触发方式：
  在 Copilot Chat 输入框（或行内聊天 Ctrl+I / Cmd+I）中输入 @，然后开始输入文件名。VS Code 会弹出自动补全列表，你可以选择具体的文件（支持相对路径）。

  • 示例输入：@src/utils/auth.ts 或 @package.json

• 核心功能：

  • 全文注入：选中后，该文件的完整内容（或在上下文窗口允许范围内的最大切片）会被作为上下文发送给模型。
  • 精准问答：适合问“这个函数是怎么实现的？”、“帮我重构这个文件中的 login 函数”、“解释这个配置文件的作用”。
  • 多文件组合：你可以同时引用多个文件。
    • 示例：@src/api/user.ts @src/types/user.ts 请检查这两个文件的类型定义是否一致。

• 适用场景：

  • 代码重构（Refactoring）。
  • 查找特定文件中的 Bug。
  • 为新文件编写基于现有文件结构的代码。
  • 生成特定文件的单元测试。

---

2. @workspace：全局项目理解 (轻量级 RAG)

这是最接近传统 RAG 的功能。当你提出的问题涉及多个文件、项目架构或未知代码位置时使用。

• 触发方式：
  输入 @workspace 并回车（或从列表选择）。

• 核心原理 (向量检索)：
  当你使用 @workspace 时，Copilot 不会把你的整个项目代码（可能几百万行）全部塞给模型（这会超出上下文限制且成本极高）。
  相反，它会执行以下步骤：

  1. 语义分析：分析你的自然语言问题。
  2. 向量搜索：在本地索引（或云端索引，取决于版本配置）中对你的工作区代码进行向量相似度搜索。
  3. 片段提取：检索出与问题最相关的 代码片段（Snippets）、文件路径和符号定义。
  4. 上下文组装：将这些检索到的片段组装成 Prompt，发送给大模型。

• 核心功能：

  • 跨文件问答：例如“用户登录流程是如何贯穿整个项目的？”（模型会自动找到 Controller, Service, DB Model 等相关文件）。
  • 架构解释：例如“解释一下这个项目的目录结构和模块依赖关系”。
  • 查找用法：例如“我在哪里调用了 calculateTax 这个函数？”。
  • 全局重构建议：例如“如果我要把数据库从 MySQL 迁移到 Postgres，我需要修改哪些文件？”

• 适用场景：

  • 接手新项目，快速理解代码库。
  • 排查涉及多个模块的复杂 Bug。
  • 询问关于项目整体架构、依赖关系的问题。
  • 寻找某个功能在项目中的具体实现位置。

---

3. 其他常用的 @ 上下文对象

除了文件和 workspace，Copilot 还支持更多细粒度的上下文，进一步增强了 RAG 的精度：

表格

语法	描述	典型用途
#file (旧版写法，现多用 @)	同 @file	引用文件
@terminal	包含当前终端的输出内容	“分析刚才报错的日志”
@vscode	包含 VS Code API 文档上下文	“如何用 VS Code API 编写一个插件？”
@github	关联当前的 Pull Request 或 Issue	“总结这个 PR 的改动”
@url	(部分版本支持) 引用网页内容	“参考这个文档链接实现功能”
@selection	(隐式) 如果你在编辑器中选中了代码，它会自动作为上下文	“优化这段选中的代码”

---

4. 实战技巧与最佳实践

A. 组合拳：精确控制上下文

不要只依赖 @workspace，有时候它检索的内容不够精确。最好的方式是 @file + @workspace + 自然语言。

示例：
@src/main.py @config.yaml @workspace 我想添加一个新的环境变量配置，参考现有的模式，告诉我需要修改哪些文件，并给出代码示例。
解析：先锁定主入口和配置文件，再让 workspace 搜索类似的配置模式。

B. 解决“幻觉”问题

如果你发现 Copilot 编造了不存在的函数，强制使用 @file 指向包含该函数定义的真实文件，可以大幅减少幻觉。

示例：
@utils/helpers.ts 请基于这个文件中定义的 formatDate 函数，编写一个新的 parseDate 函数。

C. 性能与延迟

• @file 通常响应较快，因为上下文是确定的。
• @workspace 需要先进行本地/云端检索，可能会比直接提问慢 1-2 秒，但在处理大型项目时，它能提供准确得多的答案。

D. 隐私与安全

• 本地索引：较新版本的 Copilot 会在本地建立代码索引（向量嵌入），这意味着 @workspace 的检索过程部分是在本地完成的，只有检索到的相关片段和您的问题会被发送到云端模型，这在一定程度上保护了代码隐私（不会上传整个仓库）。
• 企业策略：如果是企业版，管理员可以配置哪些文件可以被索引。

5. 局限性 (需要注意的地方)

1. 上下文窗口限制：虽然 @workspace 做了检索，但如果检索出的相关片段太多，依然可能截断。对于超大型单体仓库，建议缩小范围（多用 @file 指定核心文件）。
2. 非代码文件支持：@workspace 主要对代码文件（.ts, .py, .go 等）索引效果最好。对于纯文本文档（.md, .txt）或非结构化数据，检索效果可能不如专门的文档知识库工具。
3. 实时性：如果你刚创建了一个新文件但还没保存，或者刚重命名了文件，索引可能需要几秒钟刷新，此时 @workspace 可能暂时找不到它。

总结

@file 和 @workspace 是 GitHub Copilot 内置的、无需配置的 RAG 接口。

• 想问细节，用 @file。
• 想问全局/架构，用 @workspace。
• 想最准，两者结合使用。

这种机制让你在不搭建复杂向量数据库的情况下，就能让 Copilot “读懂”你的私有代码库。

贡献者

SamuelNOTCuriousMeow

文件历史

最后编辑于 6 分钟前查看完整历史

e1ab0-更新数值生成器2.1