Gemini CLI 工具系统全解析：工具分类清单、参数键表与 ToolRegistry 扩展机制

Gemini CLI 工具系统全解析工具分类清单、参数键表与 ToolRegistry 扩展机制【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cliGemini CLIgemini-cli通过一套结构化的工具Tools系统让模型超越纯文本生成读取与编辑文件、执行 Shell 命令、检索网络内容、调用 MCP 资源。本文基于仓库内 工具参考文档 与核心实现代码完整梳理所有内置工具的分类与参数键、自动执行时的安全确认机制、/tools管理命令以及ToolRegistry如何支持自定义工具发现discoveryCommand与 MCP 扩展帮助你在实际使用中精确控制、配置并扩展 Gemini CLI 的工具能力。工具如何被调用自动执行与安全策略工具通常由 Gemini CLI 在模型需要执行动作时自动调用。当模型请求使用某个工具时CLI 会先将该请求与自身安全策略进行比对再决定是直接执行、要求确认还是拒绝用户确认User confirmation所有会修改文件或执行 Shell 命令的变更类mutator工具都需要你手动批准。CLI 会在确认前向你展示 diff 或完整的命令文本。沙箱Sandboxing可以将工具执行放在安全的容器化环境中把变更与宿主机隔离详见 沙箱指南。受信任文件夹Trusted folders可以配置哪些目录允许模型使用系统工具详见 受信任文件夹指南。建议在允许任何工具执行前仔细审查确认提示中的 diff 或命令内容。从源码可以确认变更类工具的精确定义。在 Kind 枚举与 MUTATOR_KINDS 定义 中工具被划分为 13 种类别Read、Edit、Delete、Move、Search、Execute、Think、Agent、Fetch、Communicate、Plan、SwitchMode、Other其中有副作用、需要更严格管控的MUTATOR_KINDS正好是Edit、Delete、Move、Execute四类——这与文档中修改文件或执行 Shell 命令的工具必须手动确认完全对应。另外READ_ONLY_KINDSRead、Search、Fetch被标记为可安全并行执行的工具类别解释了为什么只读操作在 Gemini CLI 中可以无确认地并发跑。手动触发工具与!快捷语法你可以在提示词中用特殊符号直接触发关键工具文件访问后跟文件或目录路径将其内容注入提示词底层触发read_many_files工具见 文件系统工具文档。Shell 命令!!后跟系统命令直接执行触发run_shell_command工具见 Shell 工具文档。用/tools发现与管理工具使用内置命令可以查看和管理当前会话中的工具/tools列出所有已注册工具及其显示名称display name。/tools desc列出所有工具及其完整描述。这对于验证 MCP 服务器 或自定义工具是否被正确加载尤其有用。工具的行为还可以通过 settings 配置启用、禁用或调整例如为 Shell 命令设置分页器、为 Web 搜索配置浏览器详见 Settings 指南。在 设置 Schema 中可以看到对应的工具级配置项tools.excludeTool names to exclude from discovery.从发现中排除指定工具数组类型、变更需重启、tools.discoveryCommandCommand to run for tool discovery.、tools.callCommand定义调用已发现工具的自定义 Shell 命令约定以工具名作为第一个参数、从 stdin 读取 JSON 参数、向 stdout 输出 JSON 结果。可用工具全表按主要功能分类以下是仓库文档 Tools reference 中列出的全部工具按其主要功能分类。每个工具的详细参数说明见对应链接的专题文档。Execution执行工具类别Kind说明run_shell_commandExecute执行任意 Shell 命令。支持交互式会话与后台进程。需要手动确认。File System文件系统工具类别说明globSearch在工作区内查找匹配特定 glob 模式的文件。grep_searchSearch在文件内容中搜索正则表达式。遗留别名search_file_content。list_directoryRead列出指定路径下的文件名与子目录名。read_fileRead读取特定文件内容支持文本、图片、音频与 PDF。read_many_filesRead读取并拼接多个文件内容常由提示词中的符号触发。replaceEdit在文件内执行精确文本替换。需要手动确认。write_fileEdit以新内容创建或覆盖文件。需要手动确认。Interaction交互工具类别说明ask_userCommunicate通过交互式对话框请求澄清或补充缺失信息。write_todosOther维护内部子任务列表模型用它跟踪自己的进度。Task Tracker实验性注意这是正在积极开发中的实验性功能通过experimental.taskTracker配置启用。工具类别说明tracker_create_taskOther在实验性 tracker 中创建新任务。tracker_update_taskOther更新现有任务的状态、描述或依赖。tracker_get_taskOther获取特定任务的完整详情。tracker_list_tasksOther列出 tracker 中的任务可按状态、类型或父任务过滤。tracker_add_dependencyOther在两个任务之间添加依赖保证拓扑序执行。tracker_visualizeOther以 ASCII 树形式可视化当前任务图。MCPModel Context Protocol工具类别说明list_mcp_resourcesSearch列出已连接 MCP 服务器暴露的所有可用资源。read_mcp_resourceRead读取特定 Model Context ProtocolMCP资源的内容。从 ToolRegistry 源码 可以确认一个细节read_mcp_resource与list_mcp_resources只在 MCP 客户端管理器中确实存在资源时才被激活mcpManager.getAllResources().length 0时返回 false避免在空连接下向模型暴露无意义的工具。Memory记忆工具类别说明activate_skillOther从.gemini/skills目录加载专业化的流程性知识。get_internal_docsThink访问 Gemini CLI 自身文档以获得关于其自身能力的准确回答。Planning规划工具类别说明enter_plan_modePlan将 CLI 切换为安全的只读Plan Mode用于研究复杂变更。exit_plan_modePlan敲定计划、展示以供审阅并请求批准开始实现。源码层面这两个工具的可用性是互斥且与审批模式绑定的在 isActiveTool 中当ApprovalMode.PLAN激活时enter_plan_mode被停用、exit_plan_mode被启用反之亦然。此外在 getFunctionDeclarations 中Plan Mode 下write_file与replace编辑类工具的 schema 描述会被动态改写明确告知模型只能用于在 plans 目录中编写/更新 .md 计划文件不能直接修改源码。System系统工具类别说明complete_taskOther结束子代理subagent的使命并把结果返回给父代理。该工具对用户不可用。Task Tracking任务跟踪工具类别说明tracker_add_dependencyThink为 tracker 中的两个现有任务添加依赖。tracker_create_taskThink在内部 tracker 中创建新任务以监控进度。tracker_get_taskThink获取某个被跟踪任务的详情与当前状态。tracker_list_tasksThink列出所有当前被跟踪的任务。tracker_update_taskThink更新现有任务的状态或详情。tracker_visualizeThink生成当前任务依赖图的可视化表示。update_topicThink更新当前主题与状态让用户随时了解进展。说明Tracker 系列工具在文档中分实验性 Task Tracker与Task Tracking两处出现类别标记不同前者对应experimental.taskTracker开关下的实验入口update_topic的启用还受主题叙述topic narration配置控制见 工具注册表激活逻辑。Web网络工具类别说明google_web_searchSearch执行 Google 搜索以获取最新信息。web_fetchFetch抓取并处理指定 URL 的内容。警告该工具可访问本地与私有网络地址例如 localhost若配合不可信的提示词使用可能存在安全风险。在 Plan Mode 下该工具需要用户明确确认。工具参数键表与策略引擎规则在 策略引擎policy engine 中编写argsPattern规则时需要知道每个工具在 JSON 表示中的参数键。下表完整列出各工具出现的 JSON 参数键来源docs/reference/tools.md工具JSON 参数键run_shell_commandcommand,description,dir_path,is_backgroundglobpattern,dir_path,case_sensitive,respect_git_ignore,respect_gemini_ignoregrep_searchpattern,dir_path,include_pattern,exclude_pattern,names_only,case_sensitive,fixed_strings,context,after,before,no_ignore,max_matches_per_file,total_max_matcheslist_directorydir_path,ignore,file_filtering_optionsread_filefile_path,start_line,end_lineread_many_filesinclude,exclude,recursive,useDefaultExcludeswrite_filefile_path,contentreplacefile_path,old_string,new_string,instruction,allow_multipleask_userquestionsquestion、header、type、options数组write_todostodosdescription、status数组activate_skillnameget_internal_docspathenter_plan_modereasonexit_plan_modeplan_pathtracker_create_tasktitle,description,typetracker_update_taskid,title,description,status,dependenciestracker_get_taskidtracker_list_tasksstatus,type,parentIdtracker_add_dependencytaskId,dependencyIdtracker_visualize无参数update_topictitle,summary,strategic_intentgoogle_web_searchqueryweb_fetchprompt这些参数键与源码中的常量一一对应定义于 coreTools 参数常量导出如PARAM_FILE_PATH、SHELL_PARAM_COMMAND、GREP_PARAM_INCLUDE_PATTERN等。例如要写一条阻止对.env文件调用write_file的策略规则就应匹配file_path键[[rule]] toolName write_file argsPattern file_path:.*\.env decision deny priority 100 denyMessage Writing to .env files is not allowed.从源码结构看还有一组工具对参数级收窄有强制要求TOOLS_REQUIRING_NARROWING 列出了glob、grep_search、read_many_files、read_file、list_directory、write_file、replace、run_shell_command——即当你选择始终允许这类工具时策略更新要求把批准范围收窄到具体的文件路径或命令前缀而不是无条件放行。深入底层ToolRegistry 与工具扩展机制对于开发者工具系统被设计为可扩展且健壮的核心是ToolRegistry类packages/core/src/tools/tool-registry.ts。其主要机制注册表结构allKnownToolsMapstring, AnyDeclarativeTool保存所有已知工具包括当前不活跃的工具通过 getActiveTools 结合config.getExcludeTools()过滤出活跃工具这解释了tools.exclude配置的生效路径。遗留别名TOOL_LEGACY_ALIASES 将旧名search_file_content解析为新名grep_searchgetTool 在查不到工具时会尝试别名解析——保证用户自定义策略、技能与 hooks 在工具改名后仍然向后兼容。内置工具清单ALL_BUILTIN_TOOL_NAMES 汇总了上文各分类的全部内置工具名可作为当前版本工具全集的代码级核对依据。通过tools.discoveryCommand扩展自定义工具如文档所述你可以通过 settings 中的tools.discoveryCommand连接自定义工具或接入 MCP 服务器。从 discoverAndRegisterToolsFromCommand 的实现可以看到完整协议CLI 在项目根目录执行 discovery 命令将其 stdout 解析为 JSON 数组每个元素可以是带function_declarations/functionDeclarations字段的包装对象或直接是含name的函数声明parametersJsonSchema描述参数。每个发现的函数被包装为 DiscoveredTool注册名加前缀discovered_tool_见 DISCOVERED_TOOL_PREFIX并把发现命令与调用命令写进工具描述让模型知道其来源。调用时DiscoveredToolInvocation.execute 将tools.callCommand作为子进程执行参数以 JSON 写入子进程 stdin成功时返回子进程 stdout 的 JSON若出现错误、非零退出码、信号或 stderr 输出则把 Stdout/Stderr/Error/Exit Code/Signal 汇总为错误详情返回给模型。安全限制发现命令的 stdout/stderr 各有10MB 上限超限即杀死进程并报错Tool discovery command output exceeded size limit。若配置了沙箱管理器sandboxManager发现与调用命令都会先经过prepareCommand包装在沙箱中执行。其他扩展途径与源码入口MCP 工具DiscoveredMCPTool以serverName__toolName形式注册sortTools 按内置工具 → 发现工具 → MCP 工具按服务器名排序的稳定优先级排列。实现自有工具完整的 Tool API 与工具实现位于 packages/core/src/tools/ 目录每个工具如 shell.ts、grep.ts、mcp-tool.ts都遵循BaseDeclarativeToolToolInvocation的声明式契约测试用例如 tool-registry.test.ts覆盖了发现、注册、别名与排除逻辑。延伸阅读配置一个 MCP 服务器把外部能力接入工具系统。探索 Agent Skills用activate_skill加载专业化知识。查看 Slash 命令参考了解/tools等全部命令。阅读 策略引擎参考基于上文参数键表编写精细的allow/deny规则。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考