{"meta":{"title":"通过工具搜索按需加载工具","intro":"工具搜索仅当任务需要外部工具时才允许 Copilot CLI 加载外部工具，从而保持上下文较小。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/concepts","title":"概念"},{"href":"/zh/copilot/concepts/agents","title":"智能体"},{"href":"/zh/copilot/concepts/agents/copilot-cli","title":"Copilot CLI"},{"href":"/zh/copilot/concepts/agents/copilot-cli/tool-search","title":"工具搜索"}],"documentType":"article"},"body":"# 通过工具搜索按需加载工具\n\n工具搜索仅当任务需要外部工具时才允许 Copilot CLI 加载外部工具，从而保持上下文较小。\n\n## Introduction\n\n将 MCP 服务器和其他外部工具连接到 Copilot CLI 虽然功能强大，但你添加的每个工具都会带来代价：它的定义会占用模型上下文窗口的空间，而过长的工具菜单也会让智能体更难选出正确的工具。 按需工具加载（或“工具搜索”）可防止上下文窗口被代理不使用的工具的定义所混乱。 代理起初只有其内置工具，以及一种查找其余工具的方法；然后只有在完成任务需要时，才会加载额外工具。\n\n工具搜索解决了与越来越多的工具相关的两个问题：\n\n* **浪费的上下文。** 几十个工具定义就可能在智能体还没开始任何工作之前消耗 1 万到 2 万个 token。\n* **工具选择准确性下降。** 一旦几十个工具同时出现在眼前，模型就更有可能选错工具。\n\n## 会话期间发生的情况\n\n每次输入提示时，CLI 都会检查当前工具清单，并确定是否使用工具搜索。 当工具数量少于约 30 个时，使用工具搜索带来的节省并不划算，因此 Copilot CLI 会完全跳过工具搜索，直接加载所有内容。\n\n最初，使用工具搜索时，仅加载 CLI 的内置工具。 其他一切（MCP 工具和其他外部工具）都被阻碍了。 代理可以看到这些工具存在，大致了解这些工具的用途，但它们的完整定义尚未加载。\n\n当代理达到需要它未加载的工具的步骤时，它会对可用工具运行快速搜索，并将最接近的匹配项拉取到上下文中。 然后，这些工具会在该次对话的后续过程中一直保留，因此只有在各自第一次被需要时才会进行查找。\n\n第一次查找需要与模型额外进行一次交互，但由于后续每一轮都能将上下文保持在较小规模，这个成本很快就能成倍省回来。\n\n### 始终加载的工具\n\n一些工具跳过工具搜索并立即准备就绪：\n\n* Copilot CLI的内置工具（grep、glob、bash、edit 等）。\n* 来自你使用 `deferTools: \"never\"` 配置的 MCP 服务器的工具。 请参阅本文后面的 [让 MCP 服务器的工具始终保持加载状态](#keeping-an-mcp-servers-tools-always-loaded) 部分。\n* 由自定义代理加载的工具。 请参阅本文后面的[在自定义代理中配置工具延后](#configuring-tool-deferral-in-custom-agents)。\n\n## 关闭工具搜索\n\n默认情况下，工具搜索功能处于启用状态；当你使用受支持的模型且连接了足够多的工具、足以让该功能发挥作用时，它会自动启用。 若要禁用工具搜索并返回到加载每个工具，请在个人设置中设置 `toolSearch: false` 。 请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson)”。\n\n### 支持的模型\n\n| 家庭              | 支持的版本                                          |\n| --------------- | ---------------------------------------------- |\n| 克劳德 (Anthropic) | 神话预览， Fable， Sonnet 4.0+， Opus 4.0+ （不是 Haiku） |\n| GPT （OpenAI）    | GPT-5.4 及更高版本                                  |\n\n在任何其他模型中，所有工具都会提前加载。\n\n### 让 MCP 服务器的工具始终保持加载状态\n\n有时，你可能希望特定的 MCP 服务器的工具始终位于代理的前面，例如，一个经常使用其工具的服务器，或者一个额外的搜索步骤不值得的服务器。 每个 MCP 服务器都有一个用于控制此项的 `deferTools` 设置：\n\n* `\"auto\"`（默认）——服务器工具的行为与其他工具无异，超过阈值后，其处理可能会被延后。\n* `\"never\"`- 服务器的工具始终包含在代理的工具列表中，即使工具搜索对其他所有内容都处于活动状态。\n\n设置它的最简单方法是使用 `/mcp edit` 斜杠命令。 在编辑 MCP 服务器的表单中，将 **延后工具** 切换为 **永不**。 还可以直接在 `~/.copilot/mcp-config.json` 中设置。\n\n```json\n{\n    \"mcpServers\": {\n        \"my-server\": {\n            \"type\": \"stdio\",\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"@example/mcp-server\"],\n            \"deferTools\": \"never\",\n            \"tools\": [\"*\"]\n        }\n    }\n}\n```\n\n### 在自定义代理中配置工具延后\n\n自定义代理按名称列出其工具时，始终加载这些工具，以便代理可以立即使用这些工具。 这通常是你想要的，但如果代理声明了一组大型工具，并且只在给定的运行中触及其中一些工具，则可以将该列表交回工具搜索，以便根据需要发现工具，而不是同时加载所有工具。\n\n对于 Markdown 代理（`.github/agents/*.md`），请将 `deferred-tool-loading: true` 添加到前置元数据中：\n\n```markdown\n---\nname: my-agent\ndescription: Works with a large catalog of tools\ntools:\n    - some_mcp_tool\n    - another_mcp_tool\n    # ...many more\ndeferred-tool-loading: true\n---\n\nAgent instructions here.\n```\n\n关于 `deferred-tool-loading` 设置，请注意以下事项：\n\n* 它仅在工具搜索已启用时才会生效（也就是说，在受支持的模型上，且工具数量足以达到阈值时）。\n* 这只对会为其工具命名的代理有影响。 使用通配符的 `*` 代理已使用工具搜索。\n\n## 优化用于工具搜索的工具\n\n工具搜索会将代理尝试执行的操作与每个工具的 **名称**、其 **描述**以及其 **参数名称和描述**进行匹配。 清晰、具体的措辞能让工具在合适的请求中显示出来：\n\n* 根据工具的用途为其命名，以便更容易找到它们。\n* 用人们实际搜索的单词来写描述，而不是模糊的。"}