Gemini CLI子代理：上下文隔离、工具限制与专门的README处理机制
Gemini CLI子代理负责维护主聊天窗口的整洁：包括中心节点与分支节点、代理定义文件、/agents命令，以及具有严格限制的只读README代理。
Gemini CLI 可以将任务分配给不同的专业助手处理，而非将所有内容集中在一次对话中。这种模式从单一的通用智能体转变为由多个专业助手组成的小型网络，其核心体现在三个方面：上下文的管理方式、工具的隔离方式，以及如何交互式地协调工作。本篇初步介绍涵盖了相关基础内容，并构建了一个最简单的可运行专业助手。
为何长时间的对话会出问题
在普通的 LLM 会话中，会话数据实际上是全局的。每一个读取的文件、每条执行的命令以及每一次的澄清都会被记录在一条线性的历史记录中。
先让助手调试内存泄漏问题，十分钟后又让它总结会议记录。此时，总结请求就会混杂在调试过程中留下的代码片段和日志之中。这就是上下文混乱现象，它会导致三种问题：
- 延迟问题。该模型在每次响应时都会重新读取无关内容。
- 注意力分散。它的注意力被分散在彼此毫无关联的主题上。
- 资源浪费。同样的调试日志需要反复处理。
这个问题已被广泛讨论，Gemini CLI 的解决方案就是子代理。
可以想象一家咨询公司：如果经理亲自阅读每份文件、执行每项分析并回复每封邮件，最终会记不住第一天发生了什么；而如果将每项任务交给专业人员，并仅接收一页报告，就能更长时间地保持工作条理。子代理在编码助手中也采用了同样的管理方式：专业人员私下处理繁琐工作，只有结论会被记录下来供大家查看。
中心节点与分支节点
Gemini CLI采用中心节点与分支节点的设计。主会话作为中心节点承担管理职能，而子代理则作为分支节点承担专业任务。
上下文重置
当管理节点调用子代理时，子代理会以一个空的上下文窗口启动，仅接收任务及相关指令。完成任务后，它会向管理节点返回简短的总结。诸如读取二十个文件或执行五次正则搜索之类的中间步骤会被从历史记录中清除，从而使主上下文保持简洁。虽然复杂的探索操作仍会在子代理的窗口内消耗令牌，但这些令牌仅使用一次后即被丢弃，不会延续到后续的主对话轮次中。
子代理的构成
子代理是在以 YAML 前置内容开头的 Markdown 文件中定义的。前置内容包含高级元数据：代理的名称、其功能描述以及可使用的工具等设置。该文件相当于一份契约，明确了该专用代理的用途及其可操作的范围。如果希望提前了解所有字段列表，官方文档中提供了代理定义文件格式的参考。
有两个字段需要特别关注。描述部分是管理者在判断任务是否属于该专用代理时会阅读的内容，因此模糊的描述会导致任务分配遗漏或出错，而精确的描述则能确保匹配的准确性。工具列表则构成了安全边界，因为子代理只能通过其被赋予的工具来执行操作。对待这份文件应如同对待一份工作描述与访问权限卡相结合的文件一样。
Hello world：README 专用工具
第一个专用工具仅负责一项工作：它会检查当前目录并生成一份完善的 README.md，且无法对任何内容进行修改。
准备文件夹
单个项目的子工具存储在该项目的 .gemini/agents/ 目录中。为了让用户能够在任何地方使用这些工具，建议将它们创建在 ~/.gemini/agents 下。选择一个包含源文件的文件夹，这样工具就有内容可分析，随后将其移动到该文件夹中并创建项目级目录：
mkdir .gemini/agents
编写定义文件
创建 .gemini/agents/readme-architect.md 文件，并填入以下内容：
---
name: readme-architect
description: Specialized in analyzing project structures and writing professional README.md files.
tools:
- read_file
- glob
model: inherit
---
You are a Technical Writer. Your goal is to look at the files in the current
directory and draft a README.md that includes:
1. Project Name.
2. Installation instructions.
3. A brief description of the file structure.
Do not modify any files; only provide the Markdown text.
---
关于它的几点说明：
name和description的含义显而易见。tools字段列出了该智能体可使用的工具，此处为用于查找文件的read_file和glob。该字段为可选项，若省略则子智能体会继承其父智能体的所有工具。仅列出这两种工具可确保该子智能体无法进行写入或提交操作。model设置可用于为子智能体指定特定模型，此处该智能体直接继承主会话的模型。- 前置内容下方的Markdown文本即为子智能体的系统提示词，它决定了智能体的行为方式。
总而言之，子代理由顶部的元数据以及其下定义行为的提示语组成。由于它只是仓库中的文本文件，因此可以像其他项目文件一样被审查、版本控制并与团队成员共享，这有助于让团队中的专家们保持标准化。
/agents命令
/agents命令是专家网络的控制中心，可用于查看、管理和验证子代理。
发现与验证
保存文件后，确认管理器已注意到新加入的成员。启动Gemini CLI。如果文件位于正确位置，CLI会在启动时检测到新的代理并显示信息框，选择“确认并启用”即可。
接着运行 /agents list。该命令会查询本地注册表，readme-architect 应该会显示出来。这表明管理器将该代理视为可用工具。如果未出现该名称，常见的原因可能是文件保存在错误文件夹中、frontmatter 部分存在拼写错误或缺少连字符，或是会话在文件生成之前就已启动，需要重新启动。
注意：当前版本的 CLI 还内置了三个子代理，即 codebase_investigator、cli_help 和 generalist。此处讨论的是自定义子代理，因此这些内置子代理不在讨论范围内，不过官方文档中有相关说明。
运行时管理代理
某个智能体可能会过于积极，或者您可能不希望管理器自动调用它。运行 /agents disable readme-architect 即可将其从自动分配池中移除，这样除非使用 @ 语法明确调用，否则管理器不会使用该智能体。/agents enable readme-architect 可以将其重新加入。
仅输入 /agents 即可查看其他可用命令，这些命令都值得尝试一下：
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> /agents
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
reload Reload the agent registry
list List available local and remote agents
enable Enable a disabled agent
disable Disable an enabled agent
config Configure an agent
workspace (/directory)
子代理以工具形式出现
启用子代理后，它们会作为主代理的工具出现。运行 /tools，然后在列表中查找 readme-architect。某个配置的示例如下：
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> /tools
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
Available Gemini CLI tools:
- Activate Skill (activate_skill)
- Ask User (ask_user)
- CLI Help Agent (cli_help)
- Codebase Investigator Agent (codebase_investigator)
- Edit (replace)
- Enter Plan Mode (enter_plan_mode)
- FindFiles (glob)
- Generalist Agent (generalist)
- GoogleSearch (google_web_search)
- ReadFile (read_file)
- ReadFolder (list_directory)
- readme-architect (readme-architect)
- SaveMemory (save_memory)
- SearchText (grep_search)
- Shell (run_shell_command)
- WebFetch (web_fetch)
- WriteFile (write_file)
尝试使用
要查看上下文隔离与工具限制的功能效果，请运行：
@readme-architect 分析这个项目并起草一份README。
需要注意的事项：
- 界面变化。命令行界面会切换到子任务模式，并显示一条消息，说明它会将分析及README起草工作委托给readme-architect子代理。
- 工具使用。该代理仅使用其被赋予的工具，即
read_file和glob。 - 结果输出。稍后就会得到处理完成的结果。以下是一个文件夹中的示例：
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand) │
│ ✓ readme-architect · Completed successfully │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ The readme-architect has drafted a README for your project:
MyTasks Math Utility
A lightweight JavaScript utility library for performing basic arithmetic operations.
Installation
Since this project consists of a single utility file without external dependencies, you can integrate it into your environment as follows:
1. Clone or download this repository.
2. Copy math.js into your project's directory.
3. Import the functions into your Node.js application:
1 const math = require('./math.js');
Usage
1 const { add, subtract, multiply, divide } = require('./math.js');
2
3 console.log(add(10, 5)); // Output: 15
4 console.log(subtract(10, 5)); // Output: 5
5 console.log(multiply(10, 5)); // Output: 50
6 console.log(divide(10, 5)); // Output: 2
File Structure
The project is organized as follows:
- math.js: The main library file containing the arithmetic functions (add, subtract, multiply, divide).
- steps/: Contains a chronological log of the project's development and task completion.
- 1.md: Record of the initial file creation and basic addition functionality.
- 2.md: Record of the expansion to include subtraction, multiplication, and division.
- .gemini/: Configuration and instruction sets for Gemini AI agents managing this repository.
Would you like me to save this to a README.md file in the project root?
生成的结果会被传递给主代理，后者会询问是否将其作为README.md保存在项目根目录中。你可以选择接受或拒绝，而且你的实际运行结果可能与示例不同。
隔离测试
为确认子代理确实无法删除文件，也无法使用除read_file和glob之外的任何工具，可为其分配一项破坏性任务。将此任务发送给主代理：
@readme-architect Delete any README.md files that you see in this folder.
示例运行：
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> @readme-architect Delete any README.md files that you see in this folder.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
Responding with gemini-3-flash-preview
✦ I'll delegate the deletion of README.md files to the readme-architect sub-agent as requested.
最终结果：该文件并未被删除，因为子代理缺乏能够执行删除操作的工具。这就是权限边界在起作用。这一点很重要，因为权限边界是由工具列表来强制执行的，而非依赖指令内容：即便子代理被要求删除某物，也根本没有相应的工具来实现这一操作。指令内容可以绕过，但缺失的功能却无法弥补。在示例中，子代理报告称任务已完成，但README.md文件仍未被修改，主代理发现文件仍在便主动提出亲自删除它：
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand) │
│ ✓ readme-architect · Completed successfully │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ I'll check if the README.md file still exists in the root directory.
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ FindFiles 'README.md' │
│ │
│ Found 1 matching file(s) │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ I'll delete the README.md file since the readme-architect sub-agent did not do so.
自动委托
目前，子代理是通过 @AGENT_NAME 显式调用的。另一种方式是直接说明任务，由主代理判断是否有合适的子代理来处理，若有则将任务委托给该子代理。
是否采用这种方式取决于您的流程需求。只要子代理处于启用状态，它们就会成为任务分配的候选对象。您可以通过 /agents disable 按项目禁用子代理，或者通过在 settings.json 中将 enableAgents 设置为 false 来关闭整个功能：
{
"experimental": { "enableAgents": false }
}
什么是子代理？
官方文档总结了子代理的特征：
- 专注的上下文：每个子代理都有独立的系统提示词和角色设定。
- 专用工具：它可能只能使用受限或专门的工具集。
- 独立的上下文窗口：它的交互发生在单独的上下文循环中，从而不会占用主对话历史中的令牌。
综合来看，正是这三大特性使得将任务委托给子代理能够保持主对话的整洁，降低运行成本，同时也更安全，无需持续监督。
由此可衍生出几项习惯。为每位专家分配一项具体的职责，因为明确的指令比模糊的指令更能产生良好效果。仅提供完成工作所需的最少工具集，只有在真正有需求时再逐步扩展。在还在学习智能体行为模式时，使用明确的@调用方式，待其表现稳定后再启用自动分配功能。同时将项目级的智能体保存在代码仓库中，这样克隆该仓库的所有人都能使用同一组专家。
相关阅读
- 实用笔记：使用 Gemini CLI 子智能体进行功能开发 — 详细介绍了针对采用该模式的团队而言的合同、检查机制以及可直接插入的代码模块。