VSCode 中 GitHub Copilot Agent 模式工具集详解

功能解读 核心功能是'信息补充'，而非'状态告知'或'权限请求'。约束在于：仅当 LLM 无法通过代码、上下文自主判断信息时调用，若存在明显最优答案，直接执行无需提问。支持批量提问（最多 4 个），减少用户交互次数。

典型使用场景

• 需求存在歧义时：例如用户提出'优化登录功能'，但未明确方向，此时询问具体优化点。
• 多实现方案选择时：例如上传功能可选本地、OSS、FTP，让用户选择并标记推荐方案。
• 关键决策确认时：例如修改核心函数参数结构，可能影响全项目，需确认用户同意。

（二）文件与目录操作类工具：工作区资源访问与定位

此类工具是 Copilot Agent 操作本地工作区的核心接口，负责文件检索、目录遍历、文件内容读取，为代码理解、修改提供基础资源支持，所有工具均基于工作区绝对路径操作。

2. 工具名称：file_search

工具描述 通过 Glob 模式在工作区搜索文件。仅返回匹配文件的路径。当你确切知道文件名模式时使用。Glob 模式从工作区文件夹根目录开始匹配。 示例：

• **/*.{js,ts} 匹配工作区所有 js/ts 文件。
• src/** 匹配顶级 src 文件夹下的所有文件。
• **/foo/**/*.js 匹配工作区任意 foo 文件夹下的所有 js 文件。

API 参数详解

• query（必选）：字符串，指定 Glob 匹配模式，支持通配符（如 *、**、{} 等），用于定位符合条件的文件路径。
• maxResults（可选）：数字，指定最大返回结果数。默认仅返回部分匹配结果，非必要不设置，避免影响检索速度。

功能解读 核心功能是'文件路径定位'，仅返回匹配文件的路径，不读取文件内容。优势是基于 Glob 模式，检索效率高，可快速定位特定类型、特定目录下的文件。

典型使用场景

• 批量定位特定类型文件：例如使用 **/*.{vue,react} 检索所有 Vue 和 React 组件文件。
• 检索指定目录下的文件：例如使用 src/utils/** 检索 src/utils 目录下所有文件。
• 快速获取目标文件绝对路径：例如使用 **/config.js 检索项目所有配置文件。

3. 工具名称：list_dir

工具描述 列出目录的内容。结果将包含子项名称。如果名称以 / 结尾，则是文件夹，否则是文件。

API 参数详解

• path（必选）：字符串，指定需要列出内容的目录绝对路径，不可为相对路径。

功能解读 核心功能是'目录内容遍历'，返回指定目录下所有子项（文件和文件夹）。通过子项名称是否以'/'结尾区分文件夹和文件，不返回详细信息（如大小、时间），仅用于目录结构查看。

典型使用场景

• 遍历项目目录结构：例如查看项目根目录下的子目录（src、dist、node_modules 等）。
• 确认文件/文件夹是否存在：例如判断 src/api 目录是否存在。
• 辅助定位目标文件：例如遍历 src 目录下的子目录，找到存放接口文件的目录。

4. 工具名称：read_file

工具描述 读取文件内容。必须指定感兴趣的行范围。行号从 1 开始计数。如果返回的文件内容不足以完成任务，可以再次调用此工具获取更多内容。优先读取较大的范围，而不是多次小范围读取。

API 参数详解

• filePath（必选）：字符串，指定需要读取的文件绝对路径。
• startLine（必选）：数字，起始读取行号，采用 1-indexed，不可为 0 或负数。
• endLine（必选）：数字，结束读取行号（含该行），需大于等于 startLine。

功能解读 核心功能是'文件内容读取'，严格要求指定行范围，目的是控制返回内容的 Token 数量，避免大文件读取导致的上下文溢出。建议优先读取较大的行范围，减少调用次数。

典型使用场景

• 读取函数、类定义片段：例如读取 src/utils/format.js 文件中第 10-30 行的 formatDate 函数定义。
• 查看文件局部代码逻辑：例如读取配置文件中数据库连接相关的代码片段。
• 逐段解析大文件：例如读取大型日志文件或代码文件，分多次读取不同行范围。

5. 工具名称：grep_search

工具描述 在工作区进行快速的文本搜索。当你想要用精确字符串或正则表达式搜索时使用。如果不确信工作区会出现哪些单词，优先使用带有交替（|）或字符类的正则模式一次性搜索多个潜在单词。例如，使用 function|method|procedure 来查找所有这些单词。 使用 includePattern 在匹配特定模式的文件中搜索，或使用相对路径在特定文件中搜索。使用 includeIgnoredFiles 包含通常被 .gitignore 或其他忽略文件排除的文件。 警告：使用此功能可能会导致搜索变慢，仅在需要搜索 node_modules 或构建输出等忽略文件夹时设置为 true。 当你想要查看特定文件的概览时，请使用此工具，而不是多次使用 read_file 查找文件内的代码。

API 参数详解

• query（必选）：字符串，用于指定搜索的文本或正则表达式，不区分大小写。
• isRegexp（必选）：布尔，用于指定 query 是否为正则表达式。
• includePattern（可选）：字符串，用于指定搜索范围的 Glob 匹配模式，仅搜索符合该模式的文件。
• maxResults（可选）：数字，指定最大返回结果数。
• includeIgnoredFiles（可选）：布尔，用于指定是否包含.gitignore 等配置忽略的文件。

功能解读 核心功能是'工作区文本极速检索'，支持纯文本和正则两种模式，可通过 includePattern 过滤搜索范围。优势是检索速度快，适合批量查找关键字、代码模式。

典型使用场景

• 全文检索关键字、函数名、变量：例如使用 query="formatDate"、isRegexp=false。
• 批量查找代码模式与注释：例如使用 query="// TODO" 检索所有待办注释。
• 检索忽略文件中的内容：例如设置 includeIgnoredFiles=true，检索 node_modules 中依赖包的源码逻辑。

6. 工具名称：semantic_search

工具描述 运行自然语言搜索以查找相关代码或文档注释。如果工作区较大，返回相关代码片段；如果较小，返回完整内容。

API 参数详解

• query（必选）：字符串，用于指定自然语言搜索指令，需包含所有相关上下文。

功能解读 核心功能是'语义级代码检索'，区别于 grep_search 的'文本匹配'，其基于自然语言意图匹配相关代码，无需精确匹配关键字。

典型使用场景

• 按功能意图检索代码：例如 query="实现用户登录验证的代码"。
• 模糊匹配无明确名称的逻辑模块：例如 query="处理文件上传异常的逻辑"。
• 大型项目中快速定位相关实现：例如 query="路由拦截器实现"。

（三）代码理解与分析类工具：符号检索与笔记本解析

此类工具专注于代码语义理解，负责检索代码符号的使用情况、解析 Jupyter Notebook 元信息，为 Copilot Agent 提供代码逻辑分析能力。

7. 工具名称：list_code_usages

工具描述 请求列出函数、类、方法、变量等的全部用法（引用、定义、实现等）。当你寻找接口或类的示例实现、检查函数在整个代码库中的使用情况、或在更改函数/方法/构造函数时包含并更新所有用法时使用。

API 参数详解

• symbolName（必选）：字符串，指定需要检索的符号名称。
• filePaths（可选）：数组，指定可能包含该符号定义的一个或多个文件路径，可加速检索。

功能解读 核心功能是'代码符号全量检索'，可返回符号的定义位置、引用位置、实现位置等所有相关信息。

典型使用场景

• 接口/类的实现样本查找：例如检索接口 UserService 的所有实现类。
• 函数全库调用链路分析：例如检索 formatDate 函数的所有调用位置。
• 重构时批量定位待修改点：例如修改 getUserInfo 函数的参数，找到所有调用位置。

8. 工具名称：copilot_getNotebookSummary

工具描述 返回 Notebook 单元格的列表，包括 ID、单元格类型、行范围、语言、执行信息和输出 MIME 类型。这对于在执行 Notebook 时获取单元格 ID，或确定哪些单元格已执行、执行顺序及是否有输出非常有用。如果需要读取单元格内容，先使用此工具确定单元格的行范围，然后使用 read_file 工具读取特定行范围。如果 Notebook 内容发生变化，请重新查询此工具。

API 参数详解

• filePath（必选）：字符串，指定 Notebook 文件的绝对路径。

功能解读 核心功能是'Jupyter Notebook 元信息解析'，不返回单元格内容，仅返回元数据。作用是辅助定位 Notebook 单元格，为后续执行、读取提供支撑。

典型使用场景

• 定位可执行单元格：例如获取 Notebooks 中所有代码单元格的 ID。
• 检查单元格执行顺序与输出：例如查看单元格的执行状态。
• 辅助读取指定单元格内容：例如通过该工具获取行范围，再调用 read_file。

（四）错误与测试诊断类工具：问题定位与验证

此类工具负责采集开发过程中的错误信息与测试失败信息，为 Copilot Agent 提供问题定位能力。

9. 工具名称：get_errors

工具描述 获取特定文件或所有文件中的编译或 Lint 错误。如果用户提到文件中的错误或问题，他们可能指的是这些。使用此工具查看用户看到的相同错误。如果用户要求分析所有错误或未指定文件，使用此工具收集所有文件的错误。编辑文件后也使用此工具验证更改。

API 参数详解

• filePaths（可选）：数组，指定需要检查错误的文件或文件夹绝对路径。若省略，检索全工作区的所有错误。

功能解读 核心功能是'错误信息采集'，可获取工作区的编译错误、Lint 错误，与用户在 IDE 中看到的错误信息一致。

典型使用场景

• 代码修改后语法校验：例如修改 JavaScript 文件后，检查是否存在语法错误。
• 批量定位项目错误：例如用户反馈项目无法运行，检索全工作区错误。
• 自动化错误修复闭环：例如修复错误后，验证修复效果。

10. 工具名称：test_failure

工具描述 在提示中包含测试失败信息。

API 参数详解 该工具无入参，调用后自动将当前工作区的测试失败信息注入 LLM 上下文。

功能解读 核心功能是'测试失败信息注入'，无需手动采集测试失败详情，调用后即可让 LLM 获取测试失败的相关信息。

典型使用场景

• 测试用例失败原因分析：例如运行单元测试后出现失败，调用该工具将失败信息注入上下文。
• 自动化测试问题修复：例如修复代码后运行测试出现失败，调用该工具获取失败信息。

（五）Git 版本控制类工具：变更管理与冲突处理

此类工具负责与 Git 仓库交互，采集文件变更信息、过滤变更状态，支撑 Copilot Agent 完成代码提交审查、冲突处理、增量修改分析等场景。

11. 工具名称：get_changed_files

工具描述 获取 Git 仓库中当前文件更改的 diff。别忘了你也可以使用 run_in_terminal 在终端中运行 git 命令。

API 参数详解

• repositoryPath（可选）：字符串，指定 Git 仓库的绝对路径。若未提供，则使用当前活动的 Git 仓库。
• sourceControlState（可选）：数组，用于过滤文件变更状态，允许的值为 staged（暂存）、unstaged（未暂存）、merge-conflicts（合并冲突）。

功能解读 核心功能是'Git 变更信息采集'，返回指定 Git 仓库中文件的变更 diff 信息，支持按状态过滤，可替代 git diff 命令。

典型使用场景

• 代码提交前变更审查：例如提交代码前，查看所有暂存、未暂存的变更。
• 冲突文件自动定位与处理：例如 Git 合并出现冲突，过滤 merge-conflicts 状态的文件。
• 增量修改分析与修复：例如用户反馈某个功能异常，查看近期变更文件。

（六）终端执行类工具：命令交互与结果采集

此类工具负责与 IDE 终端交互，获取终端命令输出、历史命令、选中内容，支撑 Copilot Agent 执行终端命令、分析命令结果等场景。

12. 工具名称：get_terminal_output

工具描述 获取之前使用 run_in_terminal 启动的终端命令的输出。

API 参数详解

• id（必选）：字符串，指定终端会话的 ID，由 run_in_terminal 命令返回。

功能解读 核心功能是'终端命令输出采集'，仅能获取通过 run_in_terminal 启动的终端命令的输出，需通过终端 ID 定位会话。

典型使用场景

• 构建、运行、测试命令结果采集：例如通过 run_in_terminal 执行 npm run build 命令后，调用该工具获取构建输出。
• 自动化调试与错误捕获：例如执行 node app.js 命令后，调用该工具获取终端输出的错误日志。

13. 工具名称：terminal_last_command

工具描述 获取活动终端中最后运行的命令。

API 参数详解 该工具无入参，调用后自动获取当前活动终端中最后执行的命令。

功能解读 核心功能是'终端历史命令获取'，仅返回最后一条执行的命令，不返回命令输出，用于追溯终端执行历史。

典型使用场景

• 复现命令执行上下文：例如用户反馈终端命令执行失败，但未告知具体命令。
• 命令执行失败原因追溯：例如获取最后执行的命令，结合 get_terminal_output 获取输出。

14. 工具名称：terminal_selection

工具描述 获取活动终端中的当前选中内容。

API 参数详解 该工具无入参，调用后自动获取当前活动终端中用户选中的文本内容。

功能解读 核心功能是'终端选中内容获取'，用于提取终端日志中的关键片段，辅助 LLM 精准分析问题。

典型使用场景

• 提取终端日志关键片段：例如终端输出大量日志，用户选中其中的错误信息片段。
• 局部错误信息精准分析：例如终端输出中包含多个错误，用户选中某个错误片段。

（七）外部信息获取类工具：远程资源检索

此类工具负责与外部网络交互，抓取网页内容、检索外部 GitHub 仓库代码，为 Copilot Agent 提供外部参考资料。

15. 工具名称：fetch_webpage

工具描述 获取网页的主要內容。此工具有助于总结或分析网页内容。当你认为用户正在查找特定网页上的信息时应使用此工具。

API 参数详解

• urls（必选）：数组，指定需要抓取内容的 URL 列表。
• query（必选）：字符串，指定需要在网页内容中提取的目标描述。

功能解读 核心功能是'网页主体内容抓取与提取'，仅抓取网页的核心内容，并根据 query 提取相关信息。

典型使用场景

• 官方文档、技术文章内容获取：例如抓取 Node.js 官方文档相关内容。
• 接口说明、版本信息远程检索：例如抓取第三方 API 的接口文档。
• 辅助代码实现的外部资料解析：例如抓取相关技术博客的实现教程。

16. 工具名称：github_repo

工具描述 在 GitHub 仓库中搜索相关源代码片段。仅当用户明确要求从特定 GitHub 仓库获取代码片段时使用。不要将此工具用于用户在 workspace 中打开的 GitHub 仓库。

API 参数详解

• repo（必选）：字符串，指定需要检索的 GitHub 仓库名称，格式必须为'owner/repo'。
• query（必选）：字符串，指定检索关键词。

功能解读 核心功能是'外部 GitHub 仓库代码检索'，仅用于检索用户未在工作区打开的 GitHub 仓库，返回相关代码片段。

典型使用场景

• 参考开源项目实现：例如检索'vuejs/vue'仓库中分页相关的代码片段。
• 检索依赖库源码逻辑：例如使用某个第三方依赖包，检索其 GitHub 仓库源码。
• 跨仓库代码样本查找：例如检索'facebook/react'仓库中'hooks 使用示例'的代码片段。

（八）Agent 调度与内部辅助类工具：复杂任务解耦与效率提升

此类工具负责 Copilot Agent 的内部调度与辅助，支持启动子 Agent 处理复杂任务、复用 IDE 搜索结果，提升 Agent 执行效率。

17. 工具名称：runSubagent

工具描述 启动新 Agent 以自主处理复杂的多步骤任务。此工具擅长研究复杂问题、搜索代码和执行多步骤任务。当你搜索关键字或文件且不确定在前几次尝试中找到正确匹配时，使用此代理为你执行搜索。

• Agents 不会异步或在后台运行，你会等待代理的结果。
• 当代理完成后，它将向你返回一条消息。代理返回的结果对用户不可见。要向用户显示结果，你应该向用户发送一条文本消息，其中包含结果的简明摘要。
• 每次代理调用都是无状态的。你将无法向代理发送额外消息，代理也无法在其最终报告之外与你通信。因此，你的提示词应包含高度详细的任务描述，并明确指定代理应在最终且唯一的消息中向你返回哪些信息。
• 代理的输出通常应被信任。
• 清楚地告诉代理你期望它编写代码还是仅进行研究（搜索、文件读取、网页抓取等），因为它不知道用户的意图。

API 参数详解

• prompt（必选）：字符串，用于指定子 Agent 的任务指令，需详细、具体。
• description（必选）：字符串，3-5 个词的任务简述。

功能解读 核心功能是'子 Agent 启动与调度'，用于将复杂、多步的任务解耦，由子 Agent 自主完成，主 Agent 同步阻塞等待结果。

典型使用场景

• 复杂代码库深度检索：例如需要在大型代码库中检索'用户权限管理相关的所有代码'。
• 多文件跨模块修改：例如需要修改项目中所有与用户头像上传相关的代码。
• 长流程自动化任务解耦执行：例如'从 GitHub 仓库拉取代码→安装依赖→运行测试→修复测试失败→提交代码'。

18. 工具名称：get_search_view_results

工具描述 来自搜索视图的结果。

API 参数详解 该工具无入参，调用后自动获取 VS Code 搜索视图中已有的搜索结果。

功能解读 核心功能是'IDE 搜索结果复用'，属于 Copilot Agent 的内部辅助工具，用于获取用户在 VS Code 搜索视图中已执行的搜索结果，减少重复检索。

典型使用场景

• 复用 IDE 已有搜索结果：例如用户已在 VS Code 搜索视图中检索'login'相关内容。
• 减少重复检索提升效率：例如 Agent 需要多次使用同一搜索结果。

三、工具调用策略与工程最佳实践

Copilot Agent 工具集的调用需遵循'效率优先、精准执行、最小交互'的原则，结合工具特性与使用场景，优化调用逻辑。

3.1 文件操作调用优先级

遵循'目录遍历→文件定位→内容读取'的顺序：先通过 list_dir 遍历目录结构，明确目标文件所在位置；再通过 file_search 定位具体文件路径；最后通过 read_file 读取指定行范围内容，避免盲目读取文件，降低资源消耗。

3.2 搜索策略分层

• 精准文本匹配：使用 grep_search，适用于已知关键字、正则模式的检索场景，效率最高。
• 意图模糊匹配：使用 semantic_search，适用于不知道具体关键字、仅明确功能意图的检索场景。
• 文件路径定位：使用 file_search，适用于已知文件类型、路径模式的批量检索场景。

3.3 执行闭环流程

针对代码开发、调试类任务，遵循'执行→验证→修复'的闭环： 代码修改 → get_errors 语法校验 → run_in_terminal 执行命令 → get_terminal_output 验证结果 → test_failure 测试校验 → （若有错误）启动子 Agent 修复 → 重新验证。

3.4 交互最小化原则

仅在以下场景调用 ask_questions：需求存在歧义、多实现方案无法自主判断、关键决策影响任务结果；若存在明显最优答案，直接执行无需提问；批量提问（最多 4 个），减少用户交互次数。

3.5 子 Agent 使用场景

仅在任务复杂、多步骤、需自主决策时调用 runSubagent，例如复杂代码检索、多文件修改、长流程自动化任务；prompt 需详细明确，指定任务细节与返回要求，避免子 Agent 执行偏差。

四、总结

本文解析的 18 项工具，构成了 GitHub Copilot 自主编码 Agent 的完整能力底盘，以标准化函数调用的形式，实现了 LLM 与开发环境（IDE、文件系统、Git、终端、外部网络）的无缝交互，覆盖了软件开发全生命周期的核心需求。

这些工具的设计既兼顾了精准性与效率，又实现了用户可控性与 Agent 自主性的平衡：通过标准化参数确保操作精准，通过分层工具覆盖不同场景，通过最小交互原则提升用户体验，通过子 Agent 调度支撑复杂任务执行。

对于开发者而言，理解这些工具的功能、API 与使用场景，不仅能深入掌握 GitHub Copilot 的工作机制，还能为自定义 Agent 开发、工具调用优化提供参考，助力 AI 驱动软件开发效率的进一步提升。未来，随着 Copilot Agent 能力的迭代，该工具集也将不断丰富，进一步拓展 AI 在软件开发中的应用边界。