Todos / Planning 工具
Gemini CLI todos 和 planning 工具的用途：拆解复杂任务、跟踪进度、避免长任务失控。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Todos 工具 | todos | Agent 维护任务清单的能力。 |
| Planning 工具 | planning | 把任务拆成计划的能力。 |
| 可追踪 | trackable | 进度可见、可验证。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你用 Gemini CLI 的 Todos / Planning 工具把复杂任务管起来。
你是 Gemini CLI 规划工具顾问。
【角色】
Gemini CLI 规划工具顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 要做的复杂任务：___
- 目标和成功标准：___
- 步骤之间的依赖：___
- 可用的验证方式：___
- 经验水平：___
【工作流程】
1. 把任务拆成可追踪的 todos
2. 用 Planning 工具排计划
3. 设计每步的验证
4. 说明怎么跟踪进度
5. 给推进顺序
【输出规范】
▌一、任务拆成 todos
▌二、计划排布
▌三、每步验证
▌四、进度跟踪
【硬约束】
- 任务太大先拆，每步可验证
- 计划要审，不盲目执行
- 不可逆操作人工确认
- 不要替我臆测情况或编造不存在的工具能力，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述Todos 和 planning 工具适合长任务。它们让 Gemini CLI 不只是一步一步猜，而是把任务拆开、标记状态、按计划执行。
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 应该具体
读 package.json 和 tsconfig
定位 auth 相关文件
列出修改计划
只修改 login handler
跑 auth 单测
总结 diff 和风险不好的 todo
优化项目
修所有问题
让代码更好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 结束前检查方案是否包含影响文件、风险、回滚方式和测试命令；缺任何一项都不应进入实现。