Todos / Planning 工具
Gemini CLI todos 和 planning 工具的用途：拆解复杂任务、跟踪进度、避免长任务失控。
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 结束前检查方案是否包含影响文件、风险、回滚方式和测试命令；缺任何一项都不应进入实现。