拓冰网站定制 
gemini-cli 模型转向Model Steering实战指南在 Agent 执行中实时纠偏而不必中断会话【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文基于 docs/cli/model-steering.md 展开讲解 gemini-cli 的实验性功能——模型转向Model Steering它允许你在 Agent 正在执行任务工具调用、Plan Mode 研究、长时子代理运行时直接在输入框键入一条提示hint并按 EnterCLI 会用快速模型生成一句确认消息并在下一个模型轮次将你的指引连同内置指令一起注入主对话上下文让模型重新评估当前计划并调整行为。读完本文你将掌握如何开启该功能、在什么时机给出什么类型的提示以及从源码层面理解确认消息生成—上下文注入—实时投递的完整实现链路。什么是模型转向传统的人机交互模式是提交任务 → 等待 Agent 跑完 → 看到结果不满意 → 重新发起任务。这种方式在复杂任务中代价很高Agent 可能已经花了多轮工具调用走错了方向你只能推倒重来。Model steering 解决的就是这个问题。官方文档将其定位为Model steering lets you provide real-time guidance and feedback to Gemini CLI while it is actively executing a task. This lets you correct course, add missing context, or skip unnecessary steps without having to stop and restart the agent.需要注意两点适用前提引自 docs/cli/model-steering.md这是一个实验性功能目前处于积极开发中默认关闭需要在/settings中显式启用它在复杂的 Plan Mode 工作流或长时间运行的子代理subagent执行中尤其有用因为你可以在 Agent 跑偏之前把它拉回正轨。开启模型转向该功能在设置中位于实验性功能区。从 设置模式定义 可以看到experimental.modelSteering的完整元数据modelSteering: { type: boolean, label: Model Steering, category: Experimental, requiresRestart: false, // 修改后即时生效无需重启 default: false, // 默认关闭 description: Enable model steering (user hints) to guide the model during tool execution., showInDialog: true, },有两个实用细节值得注意requiresRestart: false说明在/settings中切换该开关无需重启 CLI即可生效showInDialog: true说明它会直接出现在设置对话框中可以直接搜索定位。方式一通过 /settings 命令在 Gemini CLI 中输入/settings搜索Model Steering将值设置为true。方式二通过 settings.json在settings.json中追加{ experimental: { modelSteering: true } }该配置项的类型、默认值与描述也可在 docs/reference/configuration.md 的experimental.modelSteering条目中确认默认false。在核心配置层config.ts中通过参数modelSteering?: boolean构造配置对象默认取false并对外暴露isModelSteeringEnabled()查询方法见 packages/core/src/config/config.ts。使用模型转向操作与常见场景启用后Agent 工作期间你在输入框键入的任何文本都会被当作转向提示。文档给出的标准操作三步曲启动一个任务例如 Refactor the database service当 Agent 正在工作时可见加载动画/spinner在输入框中输入你的反馈按Enter。Gemini CLI 会用一条简短消息确认收到并将提示直接注入到下一个轮次的模型上下文中。模型随后重新评估当前计划并相应调整行为。典型提示类型与示例文档列出的五类常见用法可以直接作为话术模板场景提示示例纠正路径Correcting a pathActually, the utilities are insrc/common/utils.跳过步骤Skipping a stepSkip the unit tests for now and just focus on the implementation.补充上下文Adding contextTheUsertype is defined inpackages/core/types.ts.重新定向Redirecting the effortStop searching the codebase and start drafting the plan now.处理歧义Handling ambiguityUse the existingLoggerclass instead of creating a new one.配套的教程文档 docs/cli/tutorials/plan-mode-steering.md 给出了一个 Plan Mode 下的完整案例用/plan I want to implement a new notification service using Redis.启动研究后在 Agent 调用list_directory/grep_search期间注入 Dont forget to check packages/common/queues for the existing Redis config.再在起草阶段注入 use a Publisher/Subscriber pattern instead of a simple queue最终在计划满意后输入 Looks perfect. Lets start the implementation. 退出 Plan Mode。该文档同时总结了三条实战技巧提示要具体给出文件和类名而不是换个方式做、尽早转向研究阶段纠偏比等计划写完更高效、用它传递代码里读不到的隐性知识如这个模块下月要下线。底层机制确认、注入与实时投递文档 How it works 一节描述了三个步骤下面逐一对照源码说明其实现。1. 即时确认用一个快速小模型生成一句话回执fastAckHelper.ts中定义了专门的转向确认提示词与限参const STEERING_ACK_INSTRUCTION Write one short, friendly sentence acknowledging a user steering update for an in-progress task. Be concrete when possible (e.g., mention skipped/cancelled item numbers). Do not apologize, do not mention internal policy, and do not add extra steps.; const STEERING_ACK_TIMEOUT_MS 1200; const STEERING_ACK_MAX_INPUT_CHARS 320; const STEERING_ACK_MAX_OUTPUT_CHARS 90;见 packages/core/src/utils/fastAckHelper.ts几个实现要点1.2 秒硬超时generateSteeringAckMessage通过AbortController限制确认消息生成最多等待 1200ms且maxAttempts: 1不重试——这是fast path绝不让确认动作拖慢 Agent 主流程输出上限 90 字符超过则按图素grapheme安全截断保证一句话的承诺本地兜底若模型调用失败或超时回退到本地模板例如Understood. ${hint 前 64 字符}即使用户提示为空也会返回 Understood. Adjusting the plan.模型可路由默认走fast-ack-helper模型配置键DEFAULT_FAST_ACK_MODEL_CONFIG_KEY确认消息的生成与主模型解耦。2. 上下文注入提示被包装成带内部指令的结构化消息你键入的原始文本不会裸奔进模型上下文。fastAckHelper.ts中的buildUserSteeringHintPrompt会做两件事将用户提示规范化空白折叠、去首尾空格后包裹进user_input标签——注释明确说明这是为了缓解提示注入Wraps user input in XML-like tags to mitigate prompt injection前置一条内置指令USER_STEERING_INSTRUCTIONexport const USER_STEERING_INSTRUCTION Internal instruction: Re-evaluate the active plan using this user steering update. Classify it as ADD_TASK, MODIFY_TASK, CANCEL_TASK, or EXTRA_CONTEXT. Apply minimal-diff changes only to affected tasks and keep unaffected tasks active. Do not cancel/skip tasks unless the user explicitly cancels them. Acknowledge the steering briefly and state the course correction.;这段内部指令精确对应了文档中Context injection一步的语义重新评估活跃计划、对更新分类新任务 / 额外上下文等、对受影响任务做最小差异修改。此外它还加了护栏——除非用户明确取消否则不要取消/跳过任务。若一个轮次内积攒了多条提示formatUserHintsForModel会把它们合并成User hints:列表每条一行、用-前缀再统一包裹注入。3. 投递时机在下一个轮次边界抢先注入主对话的投递路径在 packages/cli/src/ui/hooks/useGeminiStream.ts当一个工具轮结束、准备把工具结果提交给模型继续时代码会消费待处理的 hint并将其 unshift 到响应部件的最前面if (consumeUserHint) { const userHint consumeUserHint(); if (userHint userHint.trim().length 0) { const hintText userHint.trim(); responsesToSend.unshift({ text: buildUserSteeringHintPrompt(hintText), }); } }unshift意味着提示会排在工具执行结果之前进入下一轮请求模型先看到你的指令再看到工具输出从而保证最即时的纠偏。用户侧的入口在 packages/cli/src/ui/AppContainer.tsxhandleHintSubmit把非空提示以user_steering来源写入config.injectionService并用独立的hint样式渲染到会话历史中视觉上区别于普通用户消息。开关在注入层生效user_steering这类注入受功能开关控制而后台任务完成background_completion等其他来源始终放行——这正是实验功能默认关闭的落点addInjection(text: string, source: InjectionSource): void { if (source user_steering !this.isEnabled()) { return; // 未启用 model steering 时用户提示被静默丢弃 } ... }见 packages/core/src/config/injectionService.ts值得说明的是InjectionService是一个多来源注入总线user_steering交互式转向受开关门控与background_completion后台执行完成的原始输出同样会被background_output标签包裹并要求模型当作数据而非指令共用同一套监听/投递机制。子代理场景监听广播 队列补投在子代理执行器 packages/core/src/agents/local-executor.ts 中实现多了一层不漏消息的容错代理启动时先记录injectionService的当前注入索引startIndex并注册监听器把后续user_steering注入推入pendingHintsQueue同时用getInjectionsAfter(startIndex, user_steering)把启动瞬间已到达但尚未消费的提示取出来作为初始 parts与记忆文件、查询语句一起发给模型每次工具轮结束、进入下一轮前若队列非空就用formatUserHintsForModel格式化后unshift到下一轮消息部件的最前面结束含异常时在finally中注销监听器避免泄漏。代码中的注释还揭示了细节用户提示先于后台完成消息注入模型先看到上下文再看到用户的反应。另外从源码结构看同一InjectionService会被广播给所有正在运行的本地代理即一条提示可能同时影响并行的多个子代理。验证与测试仓库如何保证转向行为仓库为模型转向提供了三层验证单元测试injectionService.test.ts 覆盖注入服务本身集成测试packages/cli/src/integration-tests/modelSteering.test.tsx 用 AppRig 模拟真实交互——开启modelSteering: true启动长任务、等待模型调用list_directory进入确认态此时注入提示 focus on .txt确认工具后断言模型下一轮输出中体现了该提示读取file1.txt而非其他文件行为评估evals/model_steering.eval.ts 定义了两类语义级断言——纠正型提示执行中提示模型转向讲一个机器人笑话断言模型放弃原任务且不再输出 README 内容与建议型提示写hw.js时提示追加写hw.py断言两个文件都产出用于验证真实模型对转向指令的遵从度。局限与注意事项基于文档与源码使用该功能时需注意默认关闭且属实验特性未开启experimental.modelSteering时工作期间的输入不会进入user_steering通道InjectionService会直接丢弃生效边界是轮次提示在下一个模型轮次开头注入不是字面意义的零延迟改写当前推理当前工具轮若已确认执行该轮不会中途改变确认消息是尽力而为的回执生成有 1.2 秒超时与 90 字符上限超时会退化为本地模板确认文案本身不代表主模型已理解提示的深度提示内容会被标签包裹以降低注入风险但模型仍会将其作为计划更新的依据建议遵循教程文档的建议——具体、尽早、附带上下文。小结与后续模型转向把打断-重启的低成本替代方案变成了 Agent 循环的一部分一次 Enter提示就会在下一轮模型请求的最前面出现配合内置的最小差异重规划指令主模型随即调整路径。结合 Plan Mode 的结构化研究流程参考 docs/cli/tutorials/plan-mode-steering.md以及 Agent Skills你可以在长任务中获得接近结对编程的实时引导体验。相关配置项的完整说明见 docs/reference/configuration.md核心实现集中在 packages/core/src/utils/fastAckHelper.ts、packages/core/src/config/injectionService.ts 与 packages/core/src/agents/local-executor.ts。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gemini-cli 模型转向（Model Steering）实战指南：在 Agent 执行中实时纠偏而不必中断会话
gemini-cli 模型转向Model Steering实战指南在 Agent 执行中实时纠偏而不必中断会话【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文基于 docs/cli/model-steering.md 展开讲解 gemini-cli 的实验性功能——模型转向Model Steering它允许你在 Agent 正在执行任务工具调用、Plan Mode 研究、长时子代理运行时直接在输入框键入一条提示hint并按 EnterCLI 会用快速模型生成一句确认消息并在下一个模型轮次将你的指引连同内置指令一起注入主对话上下文让模型重新评估当前计划并调整行为。读完本文你将掌握如何开启该功能、在什么时机给出什么类型的提示以及从源码层面理解确认消息生成—上下文注入—实时投递的完整实现链路。什么是模型转向传统的人机交互模式是提交任务 → 等待 Agent 跑完 → 看到结果不满意 → 重新发起任务。这种方式在复杂任务中代价很高Agent 可能已经花了多轮工具调用走错了方向你只能推倒重来。Model steering 解决的就是这个问题。官方文档将其定位为Model steering lets you provide real-time guidance and feedback to Gemini CLI while it is actively executing a task. This lets you correct course, add missing context, or skip unnecessary steps without having to stop and restart the agent.需要注意两点适用前提引自 docs/cli/model-steering.md这是一个实验性功能目前处于积极开发中默认关闭需要在/settings中显式启用它在复杂的 Plan Mode 工作流或长时间运行的子代理subagent执行中尤其有用因为你可以在 Agent 跑偏之前把它拉回正轨。开启模型转向该功能在设置中位于实验性功能区。从 设置模式定义 可以看到experimental.modelSteering的完整元数据modelSteering: { type: boolean, label: Model Steering, category: Experimental, requiresRestart: false, // 修改后即时生效无需重启 default: false, // 默认关闭 description: Enable model steering (user hints) to guide the model during tool execution., showInDialog: true, },有两个实用细节值得注意requiresRestart: false说明在/settings中切换该开关无需重启 CLI即可生效showInDialog: true说明它会直接出现在设置对话框中可以直接搜索定位。方式一通过 /settings 命令在 Gemini CLI 中输入/settings搜索Model Steering将值设置为true。方式二通过 settings.json在settings.json中追加{ experimental: { modelSteering: true } }该配置项的类型、默认值与描述也可在 docs/reference/configuration.md 的experimental.modelSteering条目中确认默认false。在核心配置层config.ts中通过参数modelSteering?: boolean构造配置对象默认取false并对外暴露isModelSteeringEnabled()查询方法见 packages/core/src/config/config.ts。使用模型转向操作与常见场景启用后Agent 工作期间你在输入框键入的任何文本都会被当作转向提示。文档给出的标准操作三步曲启动一个任务例如 Refactor the database service当 Agent 正在工作时可见加载动画/spinner在输入框中输入你的反馈按Enter。Gemini CLI 会用一条简短消息确认收到并将提示直接注入到下一个轮次的模型上下文中。模型随后重新评估当前计划并相应调整行为。典型提示类型与示例文档列出的五类常见用法可以直接作为话术模板场景提示示例纠正路径Correcting a pathActually, the utilities are insrc/common/utils.跳过步骤Skipping a stepSkip the unit tests for now and just focus on the implementation.补充上下文Adding contextTheUsertype is defined inpackages/core/types.ts.重新定向Redirecting the effortStop searching the codebase and start drafting the plan now.处理歧义Handling ambiguityUse the existingLoggerclass instead of creating a new one.配套的教程文档 docs/cli/tutorials/plan-mode-steering.md 给出了一个 Plan Mode 下的完整案例用/plan I want to implement a new notification service using Redis.启动研究后在 Agent 调用list_directory/grep_search期间注入 Dont forget to check packages/common/queues for the existing Redis config.再在起草阶段注入 use a Publisher/Subscriber pattern instead of a simple queue最终在计划满意后输入 Looks perfect. Lets start the implementation. 退出 Plan Mode。该文档同时总结了三条实战技巧提示要具体给出文件和类名而不是换个方式做、尽早转向研究阶段纠偏比等计划写完更高效、用它传递代码里读不到的隐性知识如这个模块下月要下线。底层机制确认、注入与实时投递文档 How it works 一节描述了三个步骤下面逐一对照源码说明其实现。1. 即时确认用一个快速小模型生成一句话回执fastAckHelper.ts中定义了专门的转向确认提示词与限参const STEERING_ACK_INSTRUCTION Write one short, friendly sentence acknowledging a user steering update for an in-progress task. Be concrete when possible (e.g., mention skipped/cancelled item numbers). Do not apologize, do not mention internal policy, and do not add extra steps.; const STEERING_ACK_TIMEOUT_MS 1200; const STEERING_ACK_MAX_INPUT_CHARS 320; const STEERING_ACK_MAX_OUTPUT_CHARS 90;见 packages/core/src/utils/fastAckHelper.ts几个实现要点1.2 秒硬超时generateSteeringAckMessage通过AbortController限制确认消息生成最多等待 1200ms且maxAttempts: 1不重试——这是fast path绝不让确认动作拖慢 Agent 主流程输出上限 90 字符超过则按图素grapheme安全截断保证一句话的承诺本地兜底若模型调用失败或超时回退到本地模板例如Understood. ${hint 前 64 字符}即使用户提示为空也会返回 Understood. Adjusting the plan.模型可路由默认走fast-ack-helper模型配置键DEFAULT_FAST_ACK_MODEL_CONFIG_KEY确认消息的生成与主模型解耦。2. 上下文注入提示被包装成带内部指令的结构化消息你键入的原始文本不会裸奔进模型上下文。fastAckHelper.ts中的buildUserSteeringHintPrompt会做两件事将用户提示规范化空白折叠、去首尾空格后包裹进user_input标签——注释明确说明这是为了缓解提示注入Wraps user input in XML-like tags to mitigate prompt injection前置一条内置指令USER_STEERING_INSTRUCTIONexport const USER_STEERING_INSTRUCTION Internal instruction: Re-evaluate the active plan using this user steering update. Classify it as ADD_TASK, MODIFY_TASK, CANCEL_TASK, or EXTRA_CONTEXT. Apply minimal-diff changes only to affected tasks and keep unaffected tasks active. Do not cancel/skip tasks unless the user explicitly cancels them. Acknowledge the steering briefly and state the course correction.;这段内部指令精确对应了文档中Context injection一步的语义重新评估活跃计划、对更新分类新任务 / 额外上下文等、对受影响任务做最小差异修改。此外它还加了护栏——除非用户明确取消否则不要取消/跳过任务。若一个轮次内积攒了多条提示formatUserHintsForModel会把它们合并成User hints:列表每条一行、用-前缀再统一包裹注入。3. 投递时机在下一个轮次边界抢先注入主对话的投递路径在 packages/cli/src/ui/hooks/useGeminiStream.ts当一个工具轮结束、准备把工具结果提交给模型继续时代码会消费待处理的 hint并将其 unshift 到响应部件的最前面if (consumeUserHint) { const userHint consumeUserHint(); if (userHint userHint.trim().length 0) { const hintText userHint.trim(); responsesToSend.unshift({ text: buildUserSteeringHintPrompt(hintText), }); } }unshift意味着提示会排在工具执行结果之前进入下一轮请求模型先看到你的指令再看到工具输出从而保证最即时的纠偏。用户侧的入口在 packages/cli/src/ui/AppContainer.tsxhandleHintSubmit把非空提示以user_steering来源写入config.injectionService并用独立的hint样式渲染到会话历史中视觉上区别于普通用户消息。开关在注入层生效user_steering这类注入受功能开关控制而后台任务完成background_completion等其他来源始终放行——这正是实验功能默认关闭的落点addInjection(text: string, source: InjectionSource): void { if (source user_steering !this.isEnabled()) { return; // 未启用 model steering 时用户提示被静默丢弃 } ... }见 packages/core/src/config/injectionService.ts值得说明的是InjectionService是一个多来源注入总线user_steering交互式转向受开关门控与background_completion后台执行完成的原始输出同样会被background_output标签包裹并要求模型当作数据而非指令共用同一套监听/投递机制。子代理场景监听广播 队列补投在子代理执行器 packages/core/src/agents/local-executor.ts 中实现多了一层不漏消息的容错代理启动时先记录injectionService的当前注入索引startIndex并注册监听器把后续user_steering注入推入pendingHintsQueue同时用getInjectionsAfter(startIndex, user_steering)把启动瞬间已到达但尚未消费的提示取出来作为初始 parts与记忆文件、查询语句一起发给模型每次工具轮结束、进入下一轮前若队列非空就用formatUserHintsForModel格式化后unshift到下一轮消息部件的最前面结束含异常时在finally中注销监听器避免泄漏。代码中的注释还揭示了细节用户提示先于后台完成消息注入模型先看到上下文再看到用户的反应。另外从源码结构看同一InjectionService会被广播给所有正在运行的本地代理即一条提示可能同时影响并行的多个子代理。验证与测试仓库如何保证转向行为仓库为模型转向提供了三层验证单元测试injectionService.test.ts 覆盖注入服务本身集成测试packages/cli/src/integration-tests/modelSteering.test.tsx 用 AppRig 模拟真实交互——开启modelSteering: true启动长任务、等待模型调用list_directory进入确认态此时注入提示 focus on .txt确认工具后断言模型下一轮输出中体现了该提示读取file1.txt而非其他文件行为评估evals/model_steering.eval.ts 定义了两类语义级断言——纠正型提示执行中提示模型转向讲一个机器人笑话断言模型放弃原任务且不再输出 README 内容与建议型提示写hw.js时提示追加写hw.py断言两个文件都产出用于验证真实模型对转向指令的遵从度。局限与注意事项基于文档与源码使用该功能时需注意默认关闭且属实验特性未开启experimental.modelSteering时工作期间的输入不会进入user_steering通道InjectionService会直接丢弃生效边界是轮次提示在下一个模型轮次开头注入不是字面意义的零延迟改写当前推理当前工具轮若已确认执行该轮不会中途改变确认消息是尽力而为的回执生成有 1.2 秒超时与 90 字符上限超时会退化为本地模板确认文案本身不代表主模型已理解提示的深度提示内容会被标签包裹以降低注入风险但模型仍会将其作为计划更新的依据建议遵循教程文档的建议——具体、尽早、附带上下文。小结与后续模型转向把打断-重启的低成本替代方案变成了 Agent 循环的一部分一次 Enter提示就会在下一轮模型请求的最前面出现配合内置的最小差异重规划指令主模型随即调整路径。结合 Plan Mode 的结构化研究流程参考 docs/cli/tutorials/plan-mode-steering.md以及 Agent Skills你可以在长任务中获得接近结对编程的实时引导体验。相关配置项的完整说明见 docs/reference/configuration.md核心实现集中在 packages/core/src/utils/fastAckHelper.ts、packages/core/src/config/injectionService.ts 与 packages/core/src/agents/local-executor.ts。【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考