Kimi Code CLI 计划模式Plan Mode全解析从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读Kimi Code CLI 内置了一套先规划、后执行的计划模式Plan Mode让 Agent 在动手改代码前先产出可评审的实现方案并通过ExitPlanMode工具将方案提交给用户审批。本文以 ExitPlanMode 工具描述文档 为核心结合 EnterPlanMode 实现、ExitPlanMode 实现注实际为__init__.py见下文与 plan_mode 动态注入 等源码完整讲解计划模式的工作机制、options多方案参数、Yolo/Afk 模式下的自动审批行为以及 AskUserQuestion 与计划审批的边界。读完本文你将掌握如何在 Kimi Code CLI 的 Agent 会话中正确驱动一次探索 → 设计 → 写方案 → 审批 → 执行的完整规划闭环。ExitPlanMode计划审批的入口工具ExitPlanMode是计划模式的核心收尾工具其官方描述位于 src/kimi_cli/tools/plan/description.md定义如下Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.也就是说只有当你处于计划模式、且已经把完整方案写入 plan 文件、准备请求用户批准时才调用该工具。它的行为在 src/kimi_cli/tools/plan/init.py 中实现工具名常量NAME ExitPlanMode描述直接由load_desc(Path(__file__).parent / description.md)从该 Markdown 文件加载第 28-31 行 为 EnterPlanMode 的对应加载方式ExitPlanMode 同理。工作原理方案从文件读取而非参数传入文档明确强调了一条关键设计该工具不接收计划内容作为参数——它从你写入的 plan 文件中读取方案用户在评审时看到的就是你 plan 文件中的完整内容。源码印证了这一设计ExitPlanMode.__call__首先通过plan_path self._plan_file_path_getter()拿到当前会话的 plan 文件路径然后读取其文本内容src/kimi_cli/tools/plan/init.py#L121-L132plan_path self._plan_file_path_getter() plan_content: str | None None if plan_path and await asyncio.to_thread(plan_path.exists): plan_content await asyncio.to_thread(plan_path.read_text, encodingutf-8) if not plan_content: return ToolError( messagefNo plan file found. Write your plan to {plan_path} first, then call ExitPlanMode., briefNo plan file, )如果 plan 文件不存在或为空工具会直接返回错误没有找到 plan 文件请先把方案写入{plan_path}再调用 ExitPlanMode。这意味着在调用 ExitPlanMode 之前Agent 必须已经用 WriteFile 或 StrReplaceFile 创建并写好了 plan 文件。使用时机只用于实现类任务文档对何时使用给出了明确限定应当使用需要规划实现步骤的任务如新功能开发、多文件改动、架构决策绝不使用纯研究类任务搜索文件、阅读代码、理解代码库这类任务不应调用 ExitPlanMode。这与 src/kimi_cli/agents/default/plan.yaml 中 plan 子代理subagent的定位完全一致plan 子代理被描述为Read-only implementation planning and architecture design用于在改动代码前产出分步实现计划、关键文件识别与架构权衡分析。options 参数向用户呈现多个候选方案当你的计划中包含多种可选的实现路径时文档要求通过options参数把它们传给 ExitPlanMode让用户在审批时直接选择执行哪一条每个 option 需要有一个简洁的标签label和简短的权衡说明description如果你推荐其中某个方案在其标签后追加(Recommended)用户会同时看到所有 option以及系统自动追加的 Reject 和 Revise 选项最多提供 2-3 个方案系统会自动追加一个 Reject 选项所以用户最终看到 3-4 个选项严禁使用 Reject、Revise、Approve 作为 option 的标签——这些是系统保留标签。参数模型与校验规则源码中Params模型定义了options字段src/kimi_cli/tools/plan/init.py#L58-L78class PlanOption(BaseModel): label: str Field( description( Short name for this option (1-8 words). Append (Recommended) if you recommend this option. ), ) description: str Field( default, descriptionBrief summary of this approach and its trade-offs., ) class Params(BaseModel): options: list[PlanOption] | None Field( defaultNone, max_length3, description( When the plan contains multiple alternative approaches, list them here so the user can choose which one to execute. 2-3 options. Do not use Reject, Revise, Approve, or Reject and Exit as labels. ), )同时有两道内置校验保留标签校验PlanOption.label_not_reserved会把标签小写化后与_RESERVED_LABELS {reject, revise, approve, reject and exit}比对命中即报错第 30 行唯一性校验options_labels_unique要求所有 option 标签互不相同重复会触发ValueError。有无 options 时审批界面的差异源码展示了两种截然不同的审批呈现方式src/kimi_cli/tools/plan/init.py#L167-L214有 options≥2 个has_options params.options is not None and len(params.options) 2界面列出每个 option 作为可选按钮并追加 Reject留在计划模式与 Reject and Exit退出计划模式两个选项无 options界面显示 Approve退出计划模式并开始执行、Reject、Reject and Exit 三个按钮无论哪种情况都通过other_labelRevise提供一个自由文本修订入口用户可输入反馈要求 Agent 留在计划模式中继续修改方案。用户选择后的六种结果分支ExitPlanMode对用户响应做了完整的分类处理src/kimi_cli/tools/plan/init.py#L234-L339用户选择行为返回类型Approve单选方案退出计划模式返回完整已批准方案所有工具恢复可用ToolReturnValue选中某个 option退出计划模式只执行被选中的方案忽略计划中的其他方案ToolReturnValueReject and Exit退出计划模式等待用户下一条消息ToolRejectedErrorReject留在计划模式等待用户反馈后修订ToolRejectedErrorRevise带/不带反馈留在计划模式根据反馈修订方案ToolReturnValue直接关闭dismissed计划模式保持激活可继续完善方案或再次调用ToolReturnValue特别值得注意的是当用户批准的是某个具体 option 时工具返回的输出中会明确写入IMPORTANT: Execute ONLY the selected approach {chosen_option}. Ignore other approaches in the plan.——这是为了让执行阶段严格收敛到用户选择的路径上避免 Agent 混用多个方案。使用前须知Yolo、Afk 与 AskUserQuestion 的边界文档在 Before Using 一节定义了计划审批与其他机制的关键边界这些规则全部在源码中有对应实现Yolo 模式不豁免计划审批Yolo 模式只绕过权限审批不会让会话变成非交互在 Yolo 模式下EnterPlanMode 会被自动批准但ExitPlanMode 仍会把方案呈现在用户面前等待批准。源码中 EnterPlanMode 将is_yolo作为自动进入的判定src/kimi_cli/tools/plan/enter.py#L49-L55self._is_auto_approve is_auto_approve or is_yolo而 ExitPlanMode 的自动批准只绑定should_auto_approve_exit回调src/kimi_cli/tools/plan/init.py#L91-L104并不会因为 Yolo 而跳过用户审批。Afk 模式下的自动批准Afk 模式同时绕过权限审批且非交互在 Afk 模式下不要使用 AskUserQuestion而是基于现有上下文做最佳决策EnterPlanMode 与 ExitPlanMode 在 Afk 模式下都会被自动批准因为此时没有用户在场。源码中 ExitPlanMode 的自动批准分支会直接调用_toggle_callback()退出计划模式并返回Plan approved (auto-approved)及完整方案内容src/kimi_cli/tools/plan/init.py#L134-L150。AskUserQuestion 的职责边界文档给出了非常明确的提示词纪律如果尚未进入 Afk 且还有未解决的问题先用 AskUserQuestion 澄清如果有多个方案且尚未收敛考虑先用 AskUserQuestion 让用户选方向然后只为被选中的方向写方案绝不能用 AskUserQuestion 问这个方案可以吗或我该继续吗——那正是 ExitPlanMode 的职责方案被拒绝后根据反馈修订然后再次调用 ExitPlanMode。这套纪律在 plan_mode 动态注入提醒 中被反复强化Never ask about plan approval via text or AskUserQuestion、Do NOT use AskUserQuestion to ask about plan approval or reference the plan——the user cannot see the plan until you call ExitPlanMode。EnterPlanMode进入计划模式的前置工具完整的规划闭环从 EnterPlanMode 开始其使用说明在 enter_description.md 中。文档建议当你即将开始一项非平凡的实现任务时主动使用它在写代码前先获得用户对方案的认可避免返工。适用条件满足任意一条即建议使用新功能实现——例如给 API 增加缓存层存在多个有效方案——例如优化数据库查询索引 vs 重写 vs 缓存代码改造——例如重构 auth 模块以支持 OAuth架构决策——例如添加 WebSocket 支持多文件改动——涉及超过 2-3 个文件需求不明确——需要探索来确定范围用户偏好会影响实现——用户的输入会实质性地改变实现路径。何时不要使用单行或几行的修复拼写错误、明显 bug、小调整用户已给出非常具体、详细的指示纯研究/探索类任务。进入计划模式后的标准工作流enter_description.md定义了进入计划模式后 Agent 应当遵循的五步流程识别 2-3 个对方案至关重要的代码库关键问题如果对代码库结构或相关路径没有把握优先用Agent(subagent_typeexplore)去调查对非平凡任务强烈推荐用 Glob、Grep、ReadFile 等只读工具快速查证剩余问题基于调查结果设计实现方案将方案写入 plan 文件通过ExitPlanMode 向用户呈交方案并等待批准。这一流程与 plan 子代理plan.yaml的建议一脉相承在产出实现计划前先明确已知道什么与还需要 explore 调查什么。交互实现确认对话框与自动进入EnterPlanMode的实现细节src/kimi_cli/tools/plan/enter.py#L57-L197重复进入防护若已在计划模式返回错误Already in plan mode. Use ExitPlanMode when your plan is ready.自动进入在 Yolo/Afk 等自动审批场景下直接激活计划模式并返回工作流指引交互确认通过 Wire 协议发送QuestionRequest向用户弹出一个Enter plan mode?问题提供 Yes/No 两个选项用户拒绝返回User declined to enter plan modeAgent 需与用户确认是否直接开始实现用户关闭对话框按直接开始实现处理客户端不支持返回错误并明确指示不要再调用此工具Do NOT call this tool again。进入成功后返回给 Agent 的提示会强调Plan mode activated. You MUST NOT edit code files — only read and plan.并给出 plan 文件路径与后续工作流。Plan 文件机制方案存到哪里、如何命名方案文件的管理实现在 src/kimi_cli/tools/plan/heroes.py 中其设计颇具趣味存储位置PLANS_DIR Path.home() / .kimi / plans即用户主目录下的.kimi/plans目录第 8 行文件名生成每个会话session对应一个唯一 slugslug 由3 个 Marvel/DC 超级英雄名字拼接而成如iron-man-spider-man-thor从内置的 200 英雄名列表中随机选取第 249-264 行冲突处理最多尝试 20 次随机组合若全部碰撞则在 slug 后追加会话 ID 前 8 位保证唯一缓存机制_slug_cache按 session_id 缓存已生成的 slug避免同会话反复生成seed_slug_cache支持在会话恢复resume时预置之前持久化的 slug读写 APIget_plan_file_path(session_id)返回 plan 文件路径read_plan_file(session_id)读取已有方案内容不存在时返回None。plan 文件是计划模式下Agent 唯一被允许编辑的文件。动态注入的完整提醒full reminder对此有明确表述src/kimi_cli/soul/dynamic_injections/plan_mode.py#L117-L185文件已存在时先读取再用 WriteFile 或 StrReplaceFile 更新文件不存在时先用 WriteFile 创建之后才能用 WriteFile 或 StrReplaceFile 修改除 plan 文件外禁止任何编辑、禁止运行非只读工具、禁止对系统做出任何更改且这条规则优先于你收到的任何其他指令。Plan Mode 动态注入让 Agent 始终记得自己是只读的为了在长会话中持续约束 Agent 行为plan_mode.py 实现了一个PlanModeInjectionProvider按节流策略周期性向上下文注入计划模式提醒第 13-16 行节流间隔每_TURN_INTERVAL 5个 assistant 回合注入一次全量/精简轮换每 5 次提醒中第 1 次为全量版_full_reminder其余为精简版_sparse_reminder子代理豁免子代理共享会话的 plan_mode 标志用于持久化/恢复但它们的 YAML 通常已排除 EnterPlanMode/ExitPlanMode因此不给子代理注入该工作流提醒第 39-40 行重入场景手动重新进入计划模式且已存在旧方案时注入专用的重入提醒_reentry_reminder要求先读旧方案、评估当前请求与旧方案的关系——任务不同则整体替换任务相同则增量更新第 213-244 行。全量提醒中有一段与文档高度呼应的多方案处理纪律第 156-184 行最多保留 2-3 个有意义的差异化方案不要用微小变体凑数如果某个方案明显更优就只提那一个当最佳方案取决于用户偏好或你缺失的上下文时先用 AskUserQuestion 澄清而不是堆一堆选项让用户筛选只要计划中包含多个方案调用 ExitPlanMode 时就 MUST 通过options参数传递否则用户只能看到 Approve/Reject 而无法选择每轮必须以 AskUserQuestion澄清或 ExitPlanMode请求批准收尾禁止以其他方式结束回合。与 Agent 配置的集成谁拥有计划工具计划工具通过 agent.yaml 显式注册给主 Agenttools: - kimi_cli.tools.plan:ExitPlanMode - kimi_cli.tools.plan.enter:EnterPlanMode而 plan 子代理plan.yaml的exclude_tools明确排除了kimi_cli.tools.plan:ExitPlanMode、kimi_cli.tools.plan.enter:EnterPlanMode同时排除了 AskUserQuestion、Shell、WriteFile、StrReplaceFile 等工具其allowed_tools仅保留 ReadFile、ReadMediaFile、Glob、Grep、SearchWeb、FetchURL 等只读工具——这与plan 子代理只读规划、审批权归主 Agent的架构完全吻合也与动态注入中不给子代理注入 plan 提醒的设计互为印证。源码与测试验证行为有据可依计划模式的各项行为都有测试用例背书tests/core/test_plan_mode.py英雄名 slug 生成TestHeroSlug系列用例验证随机 slug 生成、会话级缓存同一会话复用同一 slug、不同会话 slug 不同、以及 20 次碰撞后的回退逻辑守卫条件TestExitPlanModeGuards验证不在计划模式时调用报错、工具未正确初始化报错、plan 文件不存在时报错等防御分支审批快乐路径TestExitPlanModeHappyPaths覆盖 Approve退出并返回方案、Reject返回ToolRejectedError且留在计划模式、Revise 带/不带反馈、用户直接关闭、客户端不支持 Question 协议、Question 请求异常等全部分支动态注入验证手动切换进入计划模式时激活注入延迟到下一个 LLM 步骤、子代理在根 Agent 处于计划模式时不接收注入等行为。这些测试与 description.md 中的每一条规则一一对应读者可以通过阅读测试了解工具在各种边界条件下的精确行为。实战要点速查进入非平凡实现任务开始前调用EnterPlanMode通过用户确认或自动审批进入只读规划状态调研用 explore 子代理 Glob/Grep/ReadFile 摸清代码库必要时用 AskUserQuestion 澄清需求或收敛方向写方案将方案写入~/.kimi/plans/英雄名组合.md唯一可编辑文件多方案计划含 2-3 个候选路径时必须通过options参数传递并标注(Recommended)且不得使用系统保留标签提交调用ExitPlanMode等待用户 Approve / 选择方案 / Reject / Revise执行批准后计划模式退出、所有工具恢复若用户选了具体方案只执行该方案被拒后根据反馈修订 plan 文件再次调用 ExitPlanMode边界Yolo 不豁免 ExitPlanMode 审批Afk 下两者均自动批准AskUserQuestion 只用于澄清绝不用来问方案行不行。通过以上流程Kimi Code CLI 的 Agent 能够在改代码前与用户对齐实现方案将返工成本降到最低——这正是 plan 工具族 与 plan_mode 动态注入 协同工作的核心价值。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kimi Code CLI 计划模式（Plan Mode）全解析：从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流
Kimi Code CLI 计划模式Plan Mode全解析从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读Kimi Code CLI 内置了一套先规划、后执行的计划模式Plan Mode让 Agent 在动手改代码前先产出可评审的实现方案并通过ExitPlanMode工具将方案提交给用户审批。本文以 ExitPlanMode 工具描述文档 为核心结合 EnterPlanMode 实现、ExitPlanMode 实现注实际为__init__.py见下文与 plan_mode 动态注入 等源码完整讲解计划模式的工作机制、options多方案参数、Yolo/Afk 模式下的自动审批行为以及 AskUserQuestion 与计划审批的边界。读完本文你将掌握如何在 Kimi Code CLI 的 Agent 会话中正确驱动一次探索 → 设计 → 写方案 → 审批 → 执行的完整规划闭环。ExitPlanMode计划审批的入口工具ExitPlanMode是计划模式的核心收尾工具其官方描述位于 src/kimi_cli/tools/plan/description.md定义如下Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.也就是说只有当你处于计划模式、且已经把完整方案写入 plan 文件、准备请求用户批准时才调用该工具。它的行为在 src/kimi_cli/tools/plan/init.py 中实现工具名常量NAME ExitPlanMode描述直接由load_desc(Path(__file__).parent / description.md)从该 Markdown 文件加载第 28-31 行 为 EnterPlanMode 的对应加载方式ExitPlanMode 同理。工作原理方案从文件读取而非参数传入文档明确强调了一条关键设计该工具不接收计划内容作为参数——它从你写入的 plan 文件中读取方案用户在评审时看到的就是你 plan 文件中的完整内容。源码印证了这一设计ExitPlanMode.__call__首先通过plan_path self._plan_file_path_getter()拿到当前会话的 plan 文件路径然后读取其文本内容src/kimi_cli/tools/plan/init.py#L121-L132plan_path self._plan_file_path_getter() plan_content: str | None None if plan_path and await asyncio.to_thread(plan_path.exists): plan_content await asyncio.to_thread(plan_path.read_text, encodingutf-8) if not plan_content: return ToolError( messagefNo plan file found. Write your plan to {plan_path} first, then call ExitPlanMode., briefNo plan file, )如果 plan 文件不存在或为空工具会直接返回错误没有找到 plan 文件请先把方案写入{plan_path}再调用 ExitPlanMode。这意味着在调用 ExitPlanMode 之前Agent 必须已经用 WriteFile 或 StrReplaceFile 创建并写好了 plan 文件。使用时机只用于实现类任务文档对何时使用给出了明确限定应当使用需要规划实现步骤的任务如新功能开发、多文件改动、架构决策绝不使用纯研究类任务搜索文件、阅读代码、理解代码库这类任务不应调用 ExitPlanMode。这与 src/kimi_cli/agents/default/plan.yaml 中 plan 子代理subagent的定位完全一致plan 子代理被描述为Read-only implementation planning and architecture design用于在改动代码前产出分步实现计划、关键文件识别与架构权衡分析。options 参数向用户呈现多个候选方案当你的计划中包含多种可选的实现路径时文档要求通过options参数把它们传给 ExitPlanMode让用户在审批时直接选择执行哪一条每个 option 需要有一个简洁的标签label和简短的权衡说明description如果你推荐其中某个方案在其标签后追加(Recommended)用户会同时看到所有 option以及系统自动追加的 Reject 和 Revise 选项最多提供 2-3 个方案系统会自动追加一个 Reject 选项所以用户最终看到 3-4 个选项严禁使用 Reject、Revise、Approve 作为 option 的标签——这些是系统保留标签。参数模型与校验规则源码中Params模型定义了options字段src/kimi_cli/tools/plan/init.py#L58-L78class PlanOption(BaseModel): label: str Field( description( Short name for this option (1-8 words). Append (Recommended) if you recommend this option. ), ) description: str Field( default, descriptionBrief summary of this approach and its trade-offs., ) class Params(BaseModel): options: list[PlanOption] | None Field( defaultNone, max_length3, description( When the plan contains multiple alternative approaches, list them here so the user can choose which one to execute. 2-3 options. Do not use Reject, Revise, Approve, or Reject and Exit as labels. ), )同时有两道内置校验保留标签校验PlanOption.label_not_reserved会把标签小写化后与_RESERVED_LABELS {reject, revise, approve, reject and exit}比对命中即报错第 30 行唯一性校验options_labels_unique要求所有 option 标签互不相同重复会触发ValueError。有无 options 时审批界面的差异源码展示了两种截然不同的审批呈现方式src/kimi_cli/tools/plan/init.py#L167-L214有 options≥2 个has_options params.options is not None and len(params.options) 2界面列出每个 option 作为可选按钮并追加 Reject留在计划模式与 Reject and Exit退出计划模式两个选项无 options界面显示 Approve退出计划模式并开始执行、Reject、Reject and Exit 三个按钮无论哪种情况都通过other_labelRevise提供一个自由文本修订入口用户可输入反馈要求 Agent 留在计划模式中继续修改方案。用户选择后的六种结果分支ExitPlanMode对用户响应做了完整的分类处理src/kimi_cli/tools/plan/init.py#L234-L339用户选择行为返回类型Approve单选方案退出计划模式返回完整已批准方案所有工具恢复可用ToolReturnValue选中某个 option退出计划模式只执行被选中的方案忽略计划中的其他方案ToolReturnValueReject and Exit退出计划模式等待用户下一条消息ToolRejectedErrorReject留在计划模式等待用户反馈后修订ToolRejectedErrorRevise带/不带反馈留在计划模式根据反馈修订方案ToolReturnValue直接关闭dismissed计划模式保持激活可继续完善方案或再次调用ToolReturnValue特别值得注意的是当用户批准的是某个具体 option 时工具返回的输出中会明确写入IMPORTANT: Execute ONLY the selected approach {chosen_option}. Ignore other approaches in the plan.——这是为了让执行阶段严格收敛到用户选择的路径上避免 Agent 混用多个方案。使用前须知Yolo、Afk 与 AskUserQuestion 的边界文档在 Before Using 一节定义了计划审批与其他机制的关键边界这些规则全部在源码中有对应实现Yolo 模式不豁免计划审批Yolo 模式只绕过权限审批不会让会话变成非交互在 Yolo 模式下EnterPlanMode 会被自动批准但ExitPlanMode 仍会把方案呈现在用户面前等待批准。源码中 EnterPlanMode 将is_yolo作为自动进入的判定src/kimi_cli/tools/plan/enter.py#L49-L55self._is_auto_approve is_auto_approve or is_yolo而 ExitPlanMode 的自动批准只绑定should_auto_approve_exit回调src/kimi_cli/tools/plan/init.py#L91-L104并不会因为 Yolo 而跳过用户审批。Afk 模式下的自动批准Afk 模式同时绕过权限审批且非交互在 Afk 模式下不要使用 AskUserQuestion而是基于现有上下文做最佳决策EnterPlanMode 与 ExitPlanMode 在 Afk 模式下都会被自动批准因为此时没有用户在场。源码中 ExitPlanMode 的自动批准分支会直接调用_toggle_callback()退出计划模式并返回Plan approved (auto-approved)及完整方案内容src/kimi_cli/tools/plan/init.py#L134-L150。AskUserQuestion 的职责边界文档给出了非常明确的提示词纪律如果尚未进入 Afk 且还有未解决的问题先用 AskUserQuestion 澄清如果有多个方案且尚未收敛考虑先用 AskUserQuestion 让用户选方向然后只为被选中的方向写方案绝不能用 AskUserQuestion 问这个方案可以吗或我该继续吗——那正是 ExitPlanMode 的职责方案被拒绝后根据反馈修订然后再次调用 ExitPlanMode。这套纪律在 plan_mode 动态注入提醒 中被反复强化Never ask about plan approval via text or AskUserQuestion、Do NOT use AskUserQuestion to ask about plan approval or reference the plan——the user cannot see the plan until you call ExitPlanMode。EnterPlanMode进入计划模式的前置工具完整的规划闭环从 EnterPlanMode 开始其使用说明在 enter_description.md 中。文档建议当你即将开始一项非平凡的实现任务时主动使用它在写代码前先获得用户对方案的认可避免返工。适用条件满足任意一条即建议使用新功能实现——例如给 API 增加缓存层存在多个有效方案——例如优化数据库查询索引 vs 重写 vs 缓存代码改造——例如重构 auth 模块以支持 OAuth架构决策——例如添加 WebSocket 支持多文件改动——涉及超过 2-3 个文件需求不明确——需要探索来确定范围用户偏好会影响实现——用户的输入会实质性地改变实现路径。何时不要使用单行或几行的修复拼写错误、明显 bug、小调整用户已给出非常具体、详细的指示纯研究/探索类任务。进入计划模式后的标准工作流enter_description.md定义了进入计划模式后 Agent 应当遵循的五步流程识别 2-3 个对方案至关重要的代码库关键问题如果对代码库结构或相关路径没有把握优先用Agent(subagent_typeexplore)去调查对非平凡任务强烈推荐用 Glob、Grep、ReadFile 等只读工具快速查证剩余问题基于调查结果设计实现方案将方案写入 plan 文件通过ExitPlanMode 向用户呈交方案并等待批准。这一流程与 plan 子代理plan.yaml的建议一脉相承在产出实现计划前先明确已知道什么与还需要 explore 调查什么。交互实现确认对话框与自动进入EnterPlanMode的实现细节src/kimi_cli/tools/plan/enter.py#L57-L197重复进入防护若已在计划模式返回错误Already in plan mode. Use ExitPlanMode when your plan is ready.自动进入在 Yolo/Afk 等自动审批场景下直接激活计划模式并返回工作流指引交互确认通过 Wire 协议发送QuestionRequest向用户弹出一个Enter plan mode?问题提供 Yes/No 两个选项用户拒绝返回User declined to enter plan modeAgent 需与用户确认是否直接开始实现用户关闭对话框按直接开始实现处理客户端不支持返回错误并明确指示不要再调用此工具Do NOT call this tool again。进入成功后返回给 Agent 的提示会强调Plan mode activated. You MUST NOT edit code files — only read and plan.并给出 plan 文件路径与后续工作流。Plan 文件机制方案存到哪里、如何命名方案文件的管理实现在 src/kimi_cli/tools/plan/heroes.py 中其设计颇具趣味存储位置PLANS_DIR Path.home() / .kimi / plans即用户主目录下的.kimi/plans目录第 8 行文件名生成每个会话session对应一个唯一 slugslug 由3 个 Marvel/DC 超级英雄名字拼接而成如iron-man-spider-man-thor从内置的 200 英雄名列表中随机选取第 249-264 行冲突处理最多尝试 20 次随机组合若全部碰撞则在 slug 后追加会话 ID 前 8 位保证唯一缓存机制_slug_cache按 session_id 缓存已生成的 slug避免同会话反复生成seed_slug_cache支持在会话恢复resume时预置之前持久化的 slug读写 APIget_plan_file_path(session_id)返回 plan 文件路径read_plan_file(session_id)读取已有方案内容不存在时返回None。plan 文件是计划模式下Agent 唯一被允许编辑的文件。动态注入的完整提醒full reminder对此有明确表述src/kimi_cli/soul/dynamic_injections/plan_mode.py#L117-L185文件已存在时先读取再用 WriteFile 或 StrReplaceFile 更新文件不存在时先用 WriteFile 创建之后才能用 WriteFile 或 StrReplaceFile 修改除 plan 文件外禁止任何编辑、禁止运行非只读工具、禁止对系统做出任何更改且这条规则优先于你收到的任何其他指令。Plan Mode 动态注入让 Agent 始终记得自己是只读的为了在长会话中持续约束 Agent 行为plan_mode.py 实现了一个PlanModeInjectionProvider按节流策略周期性向上下文注入计划模式提醒第 13-16 行节流间隔每_TURN_INTERVAL 5个 assistant 回合注入一次全量/精简轮换每 5 次提醒中第 1 次为全量版_full_reminder其余为精简版_sparse_reminder子代理豁免子代理共享会话的 plan_mode 标志用于持久化/恢复但它们的 YAML 通常已排除 EnterPlanMode/ExitPlanMode因此不给子代理注入该工作流提醒第 39-40 行重入场景手动重新进入计划模式且已存在旧方案时注入专用的重入提醒_reentry_reminder要求先读旧方案、评估当前请求与旧方案的关系——任务不同则整体替换任务相同则增量更新第 213-244 行。全量提醒中有一段与文档高度呼应的多方案处理纪律第 156-184 行最多保留 2-3 个有意义的差异化方案不要用微小变体凑数如果某个方案明显更优就只提那一个当最佳方案取决于用户偏好或你缺失的上下文时先用 AskUserQuestion 澄清而不是堆一堆选项让用户筛选只要计划中包含多个方案调用 ExitPlanMode 时就 MUST 通过options参数传递否则用户只能看到 Approve/Reject 而无法选择每轮必须以 AskUserQuestion澄清或 ExitPlanMode请求批准收尾禁止以其他方式结束回合。与 Agent 配置的集成谁拥有计划工具计划工具通过 agent.yaml 显式注册给主 Agenttools: - kimi_cli.tools.plan:ExitPlanMode - kimi_cli.tools.plan.enter:EnterPlanMode而 plan 子代理plan.yaml的exclude_tools明确排除了kimi_cli.tools.plan:ExitPlanMode、kimi_cli.tools.plan.enter:EnterPlanMode同时排除了 AskUserQuestion、Shell、WriteFile、StrReplaceFile 等工具其allowed_tools仅保留 ReadFile、ReadMediaFile、Glob、Grep、SearchWeb、FetchURL 等只读工具——这与plan 子代理只读规划、审批权归主 Agent的架构完全吻合也与动态注入中不给子代理注入 plan 提醒的设计互为印证。源码与测试验证行为有据可依计划模式的各项行为都有测试用例背书tests/core/test_plan_mode.py英雄名 slug 生成TestHeroSlug系列用例验证随机 slug 生成、会话级缓存同一会话复用同一 slug、不同会话 slug 不同、以及 20 次碰撞后的回退逻辑守卫条件TestExitPlanModeGuards验证不在计划模式时调用报错、工具未正确初始化报错、plan 文件不存在时报错等防御分支审批快乐路径TestExitPlanModeHappyPaths覆盖 Approve退出并返回方案、Reject返回ToolRejectedError且留在计划模式、Revise 带/不带反馈、用户直接关闭、客户端不支持 Question 协议、Question 请求异常等全部分支动态注入验证手动切换进入计划模式时激活注入延迟到下一个 LLM 步骤、子代理在根 Agent 处于计划模式时不接收注入等行为。这些测试与 description.md 中的每一条规则一一对应读者可以通过阅读测试了解工具在各种边界条件下的精确行为。实战要点速查进入非平凡实现任务开始前调用EnterPlanMode通过用户确认或自动审批进入只读规划状态调研用 explore 子代理 Glob/Grep/ReadFile 摸清代码库必要时用 AskUserQuestion 澄清需求或收敛方向写方案将方案写入~/.kimi/plans/英雄名组合.md唯一可编辑文件多方案计划含 2-3 个候选路径时必须通过options参数传递并标注(Recommended)且不得使用系统保留标签提交调用ExitPlanMode等待用户 Approve / 选择方案 / Reject / Revise执行批准后计划模式退出、所有工具恢复若用户选了具体方案只执行该方案被拒后根据反馈修订 plan 文件再次调用 ExitPlanMode边界Yolo 不豁免 ExitPlanMode 审批Afk 下两者均自动批准AskUserQuestion 只用于澄清绝不用来问方案行不行。通过以上流程Kimi Code CLI 的 Agent 能够在改代码前与用户对齐实现方案将返工成本降到最低——这正是 plan 工具族 与 plan_mode 动态注入 协同工作的核心价值。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考