---
title: "Todos / Planning 工具"
description: "Gemini CLI todos 和 planning 工具的用途：拆解复杂任务、跟踪进度、避免长任务失控。"
verifiedAt: "2026-05-09"
---

Todos 和 planning 工具适合长任务。它们让 Gemini CLI 不只是一步一步猜，而是把任务拆开、标记状态、按计划执行。

> [!IMPORTANT]
> Todo 是执行透明度，Plan 是风险控制。不要用一串 todo 代替执行前方案审查。

这两类能力不是同一件事：`write_todos` 是当前会话里的进度清单；Plan Mode 是安全的只读规划阶段。前者管理执行透明度，后者管理风险。

## 适合场景

- 多文件重构。
- 修多个测试失败。
- 迁移依赖。
- 写一组文档。
- 接 MCP 或 GitHub Action。

## Todos 怎么用

`write_todos` 维护完整 todo 数组，每项有 `description` 和 `status`。状态包括 `pending`、`in_progress`、`completed`、`cancelled`、`blocked`，同一时间只能有一个 `in_progress`。用户可以用 `Ctrl+T` 查看完整列表。

官方 todo 状态只属于当前会话，不是项目管理系统。它适合让用户看到 agent 现在做到了哪一步，但不能代替 GitHub issue、项目计划文档或任务交接记录。

## 好的 todo 应该具体

```text
读 package.json 和 tsconfig
定位 auth 相关文件
列出修改计划
只修改 login handler
跑 auth 单测
总结 diff 和风险
```

## 不好的 todo

```text
优化项目
修所有问题
让代码更好
```

## Planning 怎么用

Plan Mode 通过 `enter_plan_mode` 进入，Gemini CLI 会切到只读的 `PLAN` approval mode。适合先读代码、理解风险、形成方案。完成方案后，`exit_plan_mode` 会提交一个 Markdown plan 给用户正式审核；用户批准后才切回可执行模式。

`exit_plan_mode` 要求 plan 文件在项目临时 plans 目录里，并且文件存在、有内容。它不是“随便说我计划好了”，而是把计划变成可审阅产物。

`enter_plan_mode` 会把 approval mode 切到 `PLAN`，并限制 agent 使用只读工具；它不适用于 YOLO 模式。`exit_plan_mode` 会把最终 Markdown plan 提交给用户确认，用户批准后才切回 `DEFAULT` 或 `AUTO_EDIT` 这类执行模式。

## 使用边界

小任务不需要复杂 planning；直接执行更快。多文件修改、高风险权限、生产发布、批量删除、跨模块迁移则应该先计划。计划阶段不要写文件或跑破坏性命令，除非用户明确批准。

| 状态 | 应该怎么用 | 常见问题 |
| --- | --- | --- |
| `pending` | 等待执行的具体步骤 | 条目太大，无法判断进度 |
| `in_progress` | 当前唯一正在做的步骤 | 同时多个进行中 |
| `completed` | 已完成且可验证 | 没跑验证就标完成 |
| `blocked` | 需要外部输入或环境修复 | 明明可继续却假装阻塞 |
| `cancelled` | 明确不再执行 | 不说明取消原因 |

好的 todo 应该能让旁观者理解当前任务卡在哪一步。计划则应该能让用户在执行前判断是否批准。

## 商业项目用法

对教程站、文档批量补齐、跨目录改版这类长任务，todo 必须覆盖“盘点、补源、改文、验证、提交”五个阶段。每个阶段完成后再更新状态，不要最后一次性标完成。

Plan Mode 更适合高风险动作：批量删除、公开发布、权限调整、生产脚本、跨仓库同步。计划里至少写清影响文件、命令、回滚方式、断点风险和验收方式。没有这些内容，用户无法判断是否应该批准执行。

## 验收方式

长任务开始后检查 todo 是否覆盖“读取、定位、修改、验证、总结”五类动作。Plan Mode 结束前检查方案是否包含影响文件、风险、回滚方式和测试命令；缺任何一项都不应进入实现。

## 接下来去哪

<Cards>
  <Card title="MCP 设置" description="规划工具用稳后，继续看如何接入外部 MCP server。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="任务规划" description="回看日常任务里如何写计划、检查 todo 和验收。" href="/docs/gemini-cli/official/01-cli-workflow/17-task-planning" />
  <Card title="Plan mode" description="高风险任务进入只读规划模式，再批准执行。" href="/docs/gemini-cli/official/01-cli-workflow/19-plan-mode" />
</Cards>

## 官方来源

- [Gemini CLI todo tool](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/todos.md)
- [Gemini CLI planning tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/planning.md)
- [Gemini CLI task planning tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/task-planning.md)
