Kimi Code CLI 规划模式Plan Mode实战指南EnterPlanMode 工具的触发时机与规划工作流【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKimi Code CLI 的规划模式Plan Mode是一种只读式前置规划机制在动笔写代码之前Agent 先通过EnterPlanMode工具申请进入规划模式用只读工具探索代码库、设计方案并把方案写入专门的 plan 文件最后经ExitPlanMode提交给你审批。本文以 Agent 侧的工具描述文档 enter_description.md 为骨架结合 enter.py、ExitPlanMode 实现 与 plan_mode.py 注入逻辑 等源码完整讲解 EnterPlanMode 的使用边界、YOLO/AFK 自动批准语义、plan 文件机制与完整规划工作流帮助你理解并驾驭这套先规划、后编码的 Agent 协作模式。一、为什么需要 EnterPlanMode先对齐方案再写代码enter_description.md开宗明义在开始一个非平凡non-trivial的实现任务之前应该主动调用EnterPlanMode。核心理由是Getting user sign-off on your approach before writing code prevents wasted effort——在写代码之前先让用户确认方案可以避免把精力浪费在错误的方向上。这背后是 Kimi Code CLI 的规划模式设计interaction.md 文档 描述其为只读规划模式在规划模式下 Agent 只能使用只读工具Glob、Grep、ReadFile探索代码库不能修改任何文件或执行命令Agent 把方案写入专门的 plan 文件后提交给你审批你可以批准、拒绝或给出修改意见。从源码看EnterPlanMode是注册在 enter.py 中的一个CallableTool2工具其描述文本正是通过load_desc直接加载enter_description.md生成的见 enter.py 第 23 行。也就是说这份文档就是喂给 LLM 的工具使用说明书——它决定了模型什么时候该申请进入规划模式的决策边界是整个规划工作流的触发入口。二、使用条件什么情况下应该调用 EnterPlanMode根据enter_description.md只要满足以下任意一条就应该考虑调用EnterPlanMode场景典型示例核心特征1. 新功能实现New Feature Implementation给 API 增加一个缓存层有明确的功能增量但实现路径不唯一2. 存在多种有效方案Multiple Valid Approaches优化数据库查询索引 vs 重写 vs 缓存方案选择会显著影响结果3. 代码修改Code Modifications重构 auth 模块以支持 OAuth涉及对既有代码结构的改动4. 架构决策Architectural Decisions增加 WebSocket 支持影响面广、牵一发动全身5. 多文件改动Multi-File Changes涉及超过 2-3 个文件改动面越大越值得先对齐6. 需求不明确Unclear Requirements需要探索才能确定范围先探索、再规划、后编码7. 用户偏好会影响实现User Preferences Matter用户的输入会实质改变实现方式用 EnterPlanMode 结构化决策第 7 条尤其关键当用户输入会实质性地改变实现方式时应当用EnterPlanMode把决策结构化。这与规划模式下先问清需求再写方案的原则一脉相承——plan_mode.py 注入的完整提醒 中明确要求当最佳方案取决于你不掌握的用户偏好、约束或上下文时先用AskUserQuestion澄清而不是把多个选项一股脑丢给用户筛选。三、反面清单什么情况下不要用 EnterPlanModeenter_description.md同样给出了明确的反面清单防止 Agent 把规划机制滥用在小事上单行或几行的修复拼写错误、显而易见的 bug、小的调整——直接改不值得进入规划流程用户已给出非常具体、详细的指令方案空间已经被用户锁死规划没有增量价值纯研究/探索类任务查文件、读代码、理解代码库——这些是规划模式内部的动作而不是规划模式本身的适用场景。这一点在 ExitPlanMode 的工具描述 description.md 中也有呼应该工具只用于需要规划实现步骤的任务对于研究类任务搜索文件、阅读代码、理解代码库不要使用本工具。值得强调的是enter_description.md中的一句话Use EnterPlanMode only when planning itself adds value.——只有当规划本身能创造价值时才使用。这是整个决策逻辑的最高准则。四、自动批准模式YOLO 与 AFK 的语义差异enter_description.md专门用一节说明自动批准模式下的行为差异这是最容易踩坑的地方YOLO 模式只绕过权限审批不会让会话变成非交互式。YOLO 模式下EnterPlanMode会被自动批准但ExitPlanMode仍然会把方案呈现给用户审批——即进入规划可以自动但方案拍板仍然要用户点头。AFK 模式同时绕过权限审批且是非交互的。AFK 模式下不要使用AskUserQuestion要从已有上下文中做出最佳决策。AFK 模式下EnterPlanMode/ExitPlanMode都会被自动批准因为没有用户在现场。这条语义在源码中有清晰的落点。看 enter.py 第 42-55 行的bind方法def bind( self, toggle_callback: Callable[[], Awaitable[bool]], plan_file_path_getter: Callable[[], Path | None], plan_mode_checker: Callable[[], bool], is_auto_approve: Callable[[], bool] | None None, *, is_yolo: Callable[[], bool] | None None, ) - None: ... self._is_auto_approve is_auto_approve or is_yolois_auto_approve由 AFK 状态提供is_yolo是显式 YOLO 标志二者取或后决定EnterPlanMode是否自动获批。而 ExitPlanMode 的实现 只绑定should_auto_approve_exit来自 AFK 状态与工具描述中YOLO 不自动批准 ExitPlanMode完全一致。AFK 的注入逻辑见 afk_mode.py 的_AFK_PROMPT_ROOT其中明确写有You CAN use EnterPlanMode / ExitPlanMode normally. They will be auto-approved. Planning still helps you think before acting; use it for non-trivial tasks, then exit and execute.——即使无人值守规划仍然是有价值的先思考后行动机制只是审批环节被跳过。五、进入规划模式后发生什么五步规划工作流enter_description.md的最后一节 What Happens in Plan Mode 定义了规划模式下的标准流程提出关键问题识别 2-3 个对方案至关重要的代码库问题如果你对代码库结构或相关代码路径不够自信先用Agent(subagent_typeexplore)调查这些问题——对非平凡任务强烈推荐这样做只读探索使用Glob、Grep、ReadFile全部只读做剩余的快速查找设计方案基于探索结果设计实现方案写入 plan 文件把方案写到 plan 文件提交审批通过ExitPlanMode把方案呈现给用户审批。这套流程在运行时会被 plan_mode.py 的_full_reminder以动态注入的形式周期性提醒 Agent每 5 个 assistant 轮次注入一次每 5 次提醒中 1 次为完整版、其余为精简版完整提醒的内容为Plan mode is active. You MUST NOT make any edits (with the exception of the plan file below), run non-readonly tools, or otherwise make changes to the system. This supersedes any other instructions you have received. Workflow: 1. Understand — explore the codebase with Glob, Grep, ReadFile 2. Design — converge on the best approach; consider trade-offs but aim for a single recommendation 3. Review — re-read key files to verify understanding 4. Write Plan — modify the plan file with WriteFile or StrReplaceFile. Use WriteFile if the plan file does not exist yet 5. Exit — call ExitPlanMode for user approval注意提醒中Plan file: ... (This is the only file you are allowed to edit)——规划模式下 plan 文件是唯一允许编辑的文件。另外当用户手动如/plan重新进入规划模式且已存在旧 plan 文件时会注入_reentry_reminder先读旧方案、对照当前请求判断是同一任务更新方案还是不同任务重写方案再决定如何修改。六、源码视角EnterPlanMode 的完整调用链从 enter.py 可以看到EnterPlanMode.__call__的完整逻辑理解它能帮你掌握整个机制的可靠性设计1. 前置守卫Guard如果当前已在规划模式_plan_mode_checker()返回 True直接返回错误 Already in plan mode. Use ExitPlanMode when your plan is ready.如果回调未正确初始化_toggle_callback或_plan_file_path_getter为空返回 Not initialized。2. 自动批准路径当_is_auto_approve()为真YOLO 或 AFK直接调用_toggle_callback()激活规划模式并返回包含完整工作流指引的 ToolReturnValueidentify key questions → use Agent(explore) → design approach → modify the plan file with WriteFile or StrReplaceFile → call ExitPlanMode同时埋点plan_enter_resolved: auto_approved。3. 用户确认路径通过 wire 协议发送QuestionRequest问题为 Enter plan mode?选项为 Yes/No等待用户回答。若客户端不支持QuestionNotSupported返回错误 The connected client does not support plan mode. Do NOT call this tool again.若用户直接关闭面板返回 User dismissed without choosing. Proceed with implementation directly.选择 Yes 则激活规划模式并返回一段明确约束You MUST NOT edit code files — only read and plan同时提醒Use AskUserQuestion only to clarify missing requirements or choose between approaches. Do NOT use AskUserQuestion to ask about plan approval.这里体现了规划模式的一个关键纪律你的回合必须以 AskUserQuestion澄清需求或 ExitPlanMode请求审批结束不得以其他方式结束回合见 plan_mode.py 的_full_reminder。状态管理位于 kimisoul.py_set_plan_mode负责切换self._plan_mode并把状态持久化到session.state.plan_mode工具回调通过bind在 KimiSoul 构造完成后延迟注入late-bind。工具描述还提到规划模式的激活有手动切换和工具触发两种来源手动切换会安排一次性的激活提醒注入。七、Plan 文件机制英雄命名与持久化规划模式的产出物是 plan 文件其路径管理在 heroes.pyPLANS_DIR Path.home() / .kimi / plans def get_or_create_slug(session_id: str) - str: ... words [secrets.choice(HERO_NAMES) for _ in range(3)] slug -.join(words)plan 文件存放在~/.kimi/plans/目录文件名由3 个漫威/DC 超级英雄名拼接而成如thor-spider-man-wolverine.md用secrets.choice保证随机性若 20 次尝试都撞名则追加session_id前缀保证唯一见 heroes.py 第 249-264 行。每个会话的 slug 缓存在进程内_slug_cache并在会话恢复时通过seed_slug_cache预热确保重启后沿用同一个 plan 文件。按>default_plan_mode true # 新会话默认进入规划模式默认 false--plan标志与default_plan_mode的区别在于前者对恢复的会话也会强制开启规划模式后者只影响新建会话。十、Wire 协议视角能力协商与客户端支持规划模式工具是否对 LLM 可见取决于客户端的能力协商。按 wire-mode.md 文档客户端必须在initialize时声明capabilities.supports_plan_mode: trueAgent 才会启用EnterPlanMode/ExitPlanMode两个工具否则这两个工具会从 LLM 的工具列表中自动隐藏wire 协议提供set_plan_mode请求客户端可主动把规划模式设置到指定状态Agent 随后通过StatusUpdate事件广播新状态plan_mode: true/false客户端不支持时工具调用会返回 The connected client does not support plan mode. Do NOT call this tool again.防止 Agent 反复重试浪费轮次。也就是说规划模式的可用性同时受会话状态是否已开启审批模式YOLO/AFK/普通客户端能力wire 协商三重条件约束这也是 kimisoul.py 中_bind_plan_mode_tools与 wire 层共同维护的运行时事实。十一、子代理与规划模式边界与例外规划模式的提醒注入有明确的根代理专属规则plan_mode.py 中PlanModeInjectionProvider.get_injections在soul.is_subagent时直接返回空——子代理虽然共享会话的plan_mode标志用于持久化/恢复但它们的 YAML 通常已排除EnterPlanMode/ExitPlanMode工具因此不会向子代理上下文注入工作流指引。与此对应的还有内置plan子代理plan.yaml 的when_to_use说明其用于父代理需要在代码改动前获得分步实现计划、关键文件清单与架构权衡分析的场景其exclude_tools中明确移除了Shell、WriteFile、StrReplaceFile、ExitPlanMode、EnterPlanMode等工具只保留只读工具与网络工具——与规划模式只读探索的精神一致。按 agents.md 文档 的说明内置plan子代理的可允许工具为ReadFile、ReadMediaFile、Glob、Grep、SearchWeb、FetchURL无 Shell、无写入工具。十二、最佳实践小结综合工具描述文档、源码与用户文档可以提炼出规划模式的实践准则判断先行非平凡任务新功能、多方案、架构决策、多文件改动、需求模糊、用户偏好敏感才调用EnterPlanMode单行修复、指令明确、纯研究任务直接跳过——只有当规划本身能创造价值时才使用。探索要深对代码库不够自信时优先派explore子代理调查 2-3 个关键问题再进入方案设计。方案要聚焦最多 2-3 个真正有差异的方案不要用微调凑数如果某个方案明显更优只提那一个。文件是唯一出口方案必须写入 plan 文件~/.kimi/plans/英雄名.mdExitPlanMode只负责把文件内容呈现给用户不接收内联方案。多方案必传 options方案含多个路径时必须通过options参数传递否则用户只能看到 Approve/Reject无法选择标签避开保留字推荐项标注 (Recommended)。分清审批语义YOLO 只自动批准进入规划方案提交仍需用户审批AFK 下两者都自动批准且不要使用AskUserQuestion。回合纪律规划模式下的回合必须以AskUserQuestion澄清需求或ExitPlanMode请求审批结束绝不通过对话文本询问方案行不行——那正是ExitPlanMode的职责。被拒就修订方案被拒后留在规划模式根据用户反馈修订 plan 文件然后再次调用ExitPlanMode。规划模式的本质是把先思考、后编码从口头约定变成 Agent 侧的硬性工作流用只读探索换取对代码库的准确理解用 plan 文件承载可追溯的方案用一次显式的用户审批避免方向性返工。理解EnterPlanMode的触发边界与完整闭环是让 Kimi Code CLI 在你自己的项目里高效、安全地协作的第一步。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
