Gemini CLI 怎么完成一个任务

Gemini CLI 完成任务不是"一次回答结束"。更准确的模型是：它在一个 agent loop（代理循环：边推理边调用工具的循环）里不断读取上下文、选择工具、观察结果，再决定下一步。

读懂 agent loop 之后，你就能判断什么时候该让 Gemini CLI 只读、什么时候该让它规划、什么时候才允许它写文件或跑命令。

任务循环

flowchart LR
    A["用户目标"] --> B["读取上下文"]
    B --> C["形成计划"]
    C --> D["选择工具"]
    D --> E["执行或请求确认"]
    E --> F["观察结果"]
    F --> G{"目标完成?"}
    G -- "否" --> C
    G -- "是" --> H["总结和交付"]

这个循环里，模型不是唯一变量。工具权限、上下文质量、项目配置和你的确认策略同样重要。

上下文来自哪里

Gemini CLI 可以从这些地方理解任务：

当前对话。
当前工作目录。
GEMINI.md。
settings.json。
memory。
文件系统工具读取到的文件。
MCP、extensions 或 web 工具返回的外部信息。

上下文越杂，越需要明确“以哪个文件为准”。否则 agent 容易把临时讨论、旧文档和真实源码混在一起。

工具调用意味着什么

工具调用是 Gemini CLI 和普通聊天的核心差异。模型可以不只是“建议你运行命令”，而是请求执行读文件、写文件、shell、web fetch、MCP 等工具。

这带来两个结果：

它可以完成真实工作。
它也可能造成真实副作用。

所以要先区分只读工具、写入工具和外部副作用工具。

三类任务模式

模式	Gemini CLI 应该怎么做	适合场景
只读解释	读取文件、梳理结构、指出风险，不写入	新仓库、报错定位前、并发协作
计划优先	先给文件范围、步骤、验证和停止条件	多文件改动、迁移、发布、安全任务
执行验证	小批量修改、看 diff、跑检查、总结影响	边界清楚、可回退、能验证的任务

这三种模式不要混用。你说“先分析”，它就不应该改文件；你说“直接执行”，也要先确认任务边界已经足够清楚。

什么时候让它规划

复杂任务先规划，尤其是：

要改多个文件。
要跑迁移或发布。
涉及密钥、账号、账单、远程服务器。
当前仓库有并发编辑。
你还不确定目录职责。

规划阶段的输出应该包括文件范围、验证方式、风险边界和回滚点。

什么时候让它执行

执行适合边界清楚、可验证、失败可恢复的任务：

补一页文档。
改一个小 bug。
运行只读检查。
生成测试草案。
根据官方文档更新配置。

如果一个任务无法说明验收标准，就不应该直接执行。

观察结果为什么重要

Agent loop 的关键不只是“会调用工具”，而是每次调用后会根据结果调整下一步。比如测试失败时，它不应该继续大改，而应该读失败信息、缩小范围、修最小问题，再重新验证。

一个健康的循环通常长这样：

提出假设 -> 读取证据 -> 最小改动 -> 验证 -> 根据结果继续或停止

如果它开始在没有证据的情况下连续改文件，说明任务边界或权限策略需要收紧。

判断循环是否健康

健康的 agent loop 会先拿证据，再做小动作，再验证。异常循环通常有三个信号：不读文件就下结论，测试失败后连续大改，没有说明下一步风险。遇到这三种情况，应该收回写权限，回到只读分析或 Plan mode。

理解这点后，你就能把“模型回答不好”拆成具体问题：上下文不足、工具权限过宽、计划不清、验证缺失，还是模型能力不够。

观察结果怎么用

每次工具调用后，都应该把输出变成下一步依据。read_file 的结果决定是否需要继续读上下文；shell 的 exit code 决定是否继续修改；web fetch 的来源决定事实是否可引用；MCP resource 的内容决定是否允许后续写工具。

如果 agent 忽略工具输出，继续按原计划执行，说明循环已经失真。此时应要求它重新总结证据，再决定下一步，而不是继续追加新需求。

这也是商业级教程必须写验证的原因：没有观察和验证，agent loop 只是更长的聊天。

官方资料

官方 docs index：docs/index.md
Plan mode 🔬（计划模式）：docs/cli/plan-mode.md
Checkpointing：docs/cli/checkpointing.md
Tools reference：docs/reference/tools.md

最小可控提示

可以用一句话把循环拉回可控状态：

先说明你已经读取了哪些证据，再给下一步计划，不要在没有证据时修改文件。

这句话能逼 agent 把“观察结果”显式说出来。它答不上来，就说明还没到执行阶段。

如果它只能给结论，不能列出文件路径、命令输出或官方来源，就先让它回到只读证据采集。真实项目里，证据链比回答速度更重要。