mini-swe-agent 交互式 Agent 完全指南：InteractiveAgent 三种模式、确认机制与 `mini` CLI 实战

人工智能大模型AI Agent代码智能体【免费下载链接】mini-swe-agentThe 100 line AI agent that solves GitHub issues or helps you in your command line. Radically simple, no huge configs, no giant monorepo—but scores 74% on SWE-bench verified!项目地址https://gitcode.com/gh_mirrors/mi/mini-swe-agent点击查看免费下载InteractiveAgent 是 mini-swe-agent 中负责人机共驾的核心组件它把默认的 DefaultAgent 泛化成一个把用户带进循环的交互式代理你可以让模型自主执行、也可以要求每条命令都经过你的确认、还可以完全接管终端自己敲命令。本文以 interactive.md 为主线结合 interactive.py 源码、mini.py 启动脚本、mini.yaml 默认配置与 test_interactive.py 测试用例完整讲解三种工作模式、斜杠命令、确认/白名单机制、限额续跑与中断处理读完即可熟练驾驭mini交互式命令行。一、InteractiveAgent 是什么在 mini-swe-agent 的架构里DefaultAgent 是一个纯粹的自动化循环查询模型 → 执行动作 → 追加观测消息 → 再查询直到模型输出echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT提交任务。这个控制流的可视化讲解见 control_flow.md。InteractiveAgent定义于 src/minisweagent/agents/interactive.py则是默认 Agent 的一个小泛化把用户放进循环里human人类模式用户发出的命令被立即执行confirm确认模式模型发出但未列入白名单的命令需要用户确认后才执行yolo极速模式模型发出的命令立即执行无需确认。从源码结构看InteractiveAgent直接继承自DefaultAgentclass InteractiveAgent(DefaultAgent)只重写了query、step、execute_actions三个关键方法和若干内部辅助方法因此它天然拥有 DefaultAgent 的全部能力成本/步数/墙钟时间限制、轨迹序列化保存、模板渲染等又在其上叠加了人机交互逻辑。这个类正是mini命令行工具的引擎。运行mini时启动脚本 mini.py 会调用get_agent(..., default_typeinteractive)默认就把InteractiveAgent实例化出来。完整的命令行用法见 usage/mini.md。二、配置参数详解InteractiveAgentConfigInteractiveAgent使用自己的配置类InteractiveAgentConfig它继承自AgentConfig定义在 default.py在父类基础上新增了三个交互专属字段参数类型默认值说明modeLiteral[human, confirm, yolo]confirm是否确认动作即当前工作模式whitelist_actionslist[str][]匹配这些正则表达式的动作永远不需要确认confirm_exitboolTrue当 Agent 想结束时是否向用户请求确认同时它继承了父类的通用限制参数参数类型默认值说明system_templatestr—系统消息第一条消息的模板instance_templatestr—第一条用户消息任务描述的模板step_limitint0最大步数0 表示不限cost_limitfloat3.0超过该成本后停止0 表示不限wall_time_limit_secondsint0墙钟时间上限秒0 表示不限max_consecutive_format_errorsint3连续格式错误达到该次数即退出0 表示不限output_pathPath | NoneNone轨迹保存路径默认配置里的实际取值默认交互式配置位于 src/minisweagent/config/mini.yaml其中与交互相关的关键行是agent: step_limit: 0 cost_limit: 3. mode: confirm也就是说mini默认以confirm模式启动步数不限、成本上限 3 美元仅示例值可按需调整。注意默认配置还包含完整的系统提示词模板Recommended Workflow、Command Execution Rules 等、环境变量PAGERcat、PIP_PROGRESS_BARoff等和模型观测模板这些共同构成了交互式会话的上下文。三、三种工作模式与斜杠命令mini提供三种运行模式你可以通过斜杠命令随时切换命令模式行为/cconfirm模型提出的动作在执行前需要你确认/yyolo模型提出的动作立即执行无需确认/uhuman用户接管直接输入并执行 shell 命令源码中通过映射表实现_MODE_COMMANDS_MAPPING {/u: human, /c: confirm, /y: yolo}confirm 模式默认mini默认以confirm模式启动。模型每提出一个动作终端都会打印Execute N action(s)? Enter to confirm, type comment to reject, or /h to show available commands直接按Enter确认执行输入/y确认并顺便切到 yolo 模式输入/u拒绝执行并切到 human 模式产生UserRejection中断输入其他任何内容作为拒绝理由注入对话Commands not executed. The user rejected your commands with the following message: ...。实现位于_ask_confirmation_or_interrupt它先判断这批命令里是否有任何一个需要确认_should_ask_confirmation只有存在需要确认的命令时才弹提示。yolo 模式模型的动作无需确认立即执行适合信任模型或无人值守场景。命令行加-y/--yolo即可在启动时直接进入 yolo 模式对应 mini.py 中mode: yolo if yolo else UNSET的配置注入逻辑。human 模式在 human 模式下query()被重写用户输入的每一条命令都会被包装成一条用户消息注入对话extra里带上{actions: [{command: command}]}由execute_actions立即执行模型完全不会被调用——测试 test_human_mode_basic_functionality 验证了这一点human 模式下agent.n_calls 0。其他斜杠命令/h显示帮助内容包含当前模式以及/y、/c、/u、/m的说明显示后重新进入当前提示/m进入多行输入模式适合粘贴多行命令或长任务描述。多行模式下按Esc 再回车提交、上下箭头浏览历史、CtrlR搜索历史见 prompt_user.py。_prompt_and_handle_slash_commands是所有这些命令的中央处理器它负责解析输入、显示帮助、切换模式并且如果尝试切换到当前已处于的模式例如 confirm 模式下输入/c会提示Already in confirm mode.并重新询问。随时 CtrlC 打断无论 Agent 处于什么阶段你都可以按CtrlC中断它。step()捕获KeyboardInterrupt后进入中断处理提示输入评论/命令Interrupted. Type a comment/command (/h for available commands)若输入为空或只是模式切换命令记录为Temporary interruption caught.若输入了内容则以Interrupted by user: 你的输入注入对话让模型看到你的实时反馈并调整计划。这正是把用户放进循环的体现你可以用 CtrlC 打断模型当前的思路插入方向性意见再让模型继续。四、动作确认与白名单机制确认逻辑的核心在execute_actions它被重写为三层结构def execute_actions(self, message: dict) - list[dict]: actions message.get(extra, {}).get(actions, []) commands [action[command] for action in actions] outputs [] try: self._ask_confirmation_or_interrupt(commands) for action in actions: outputs.append(self.env.execute(action)) except Submitted as e: self._check_for_new_task_or_submit(e) finally: result self.add_messages( *self.model.format_observation_messages(message, outputs, self.get_template_vars()) ) return result这里有三个值得注意的工程细节try/finally 保护部分输出即使执行中途被中断已经产生的outputs也会通过finally块被格式化成观测消息追加到对话里不会丢失已完成步骤的轨迹单个确认批量执行确认是针对这一批命令len(commands)条一次性询问的确认后按序执行全部动作Submitted 转交如果某个动作触发了完成条件命令输出以COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT开头Submitted异常会被转交给_check_for_new_task_or_submit处理见下一节。白名单免确认的正则集合whitelist_actions是一个正则表达式列表凡是匹配的动作一律跳过确认def _should_ask_confirmation(self, action: str) - bool: return self.config.mode confirm and not any(re.match(r, action) for r in self.config.whitelist_actions)注意两点只有mode confirm时才谈得上需要确认yolo 模式天然跳过用re.match从头匹配而非re.search因此写白名单正则时要考虑前缀匹配语义。例如recho.*会让所有echo开头的命令免确认见测试 test_whitelisted_actions_skip_confirmation而rls.*只豁免ls开头的命令。确认测试三种模型格式统一验证test_interactive.py 用参数化 fixture 同时覆盖了 text、toolcall、response_api 三种模型输出格式逐一验证确认后正常完成、拒绝后模型恢复、yolo 激活、白名单跳过确认、非白名单仍需确认、help 命令、以及复杂的多模式切换序列。这说明交互确认逻辑与底层模型调用格式解耦无论模型以文本工具调用还是原生 function calling 返回交互流程都一致。五、任务完成后的交互confirm_exit 与新任务当模型提交任务抛出Submitted且confirm_exitTrue时Agent 不会直接退出而是询问用户Agent wants to finish. Type new task or Enter to quit (/h for commands)直接Enter结束保留提交结果输入/u切到 human 模式继续输入其他模式命令重新询问输入新任务描述以The user added a new task: 描述中断类型UserNewTask注入对话Agent 会在同一个会话里继续执行新任务。这一机制让mini可以连续完成多个任务而无需重启测试 test_continue_after_completion_with_new_task 验证了这一点。如果你希望模型提交后立即退出例如无人值守脚本启动时加--exit-immediately即可它在 mini.py 中被映射为confirm_exit: False。六、限额处理交互式续跑与优雅停止query()重写了父类的限额检查流程对两类限额做了不同处理LimitsExceeded交互式续跑步数/成本超限时如果标准输入是交互式终端_stdin_is_interactive()判定sys.stdin.isatty()则打印当前消耗并提示Limits exceeded. Limits: 10 steps, $3.0. Current spend: 5 steps, $2.10. New step limit:用户输入新的step_limit和cost_limit后Agent 会带着放宽的限额继续运行而不是直接终止。测试 test_limits_exceeded_with_user_continuation 展示了成本超限 → 用户把cost_limit从 0.5 提到 5.0 → 任务继续完成的全过程test_limits_exceeded_multiple_times_with_continuation 则验证了可以多次续跑。非交互场景干净停止如果没有可用终端例如 CI、沙箱里 stdin 被重定向自 /dev/null 的--yolo运行继续调用input()会抛EOFError崩溃。因此_stdin_is_interactive()返回False时限额超限会直接以LimitsExceeded退出状态干净停止轨迹照常保存。测试 test_limits_exceeded_non_interactive_stops_cleanly 断言此时input()绝不被调用。TimeExceeded永远直接停止墙钟时间超限TimeExceeded是个特例——它不能被提高步数/成本限额所解除因为下一次query()会再次检查时钟并再次抛出如果提示用户输入新限额就会陷入无限循环。因此源码里明确注释Always stop cleanly instead即使有交互终端也直接抛出、不弹提示。测试 test_time_exceeded_never_prompts 验证了这一点。这与异常继承关系一致TimeExceeded(LimitsExceeded)但处理分支完全独立。七、mini命令行启动与常用选项mini是打包后的交互式可执行命令入口脚本为 src/minisweagent/run/mini.py。常用选项如下选项说明-h/--help显示帮助-t/--task指定任务否则启动时用多行输入提示你输入-c/--config指定配置文件默认使用mini.yaml或环境变量MSWEA_MINI_CONFIG_PATH指向的配置。可以只写文件名如-c mini.yaml也支持keyvalue键值对多个 config 会递归合并-m/--model指定模型否则使用环境变量MSWEA_MODEL_NAME-y/--yolo以 yolo 模式启动-l/--cost-limit设置成本限额设为 0 禁用-o/--output输出轨迹文件默认last_mini_run.traj.json--agent-class/--model-class/--environment-class高级选项指定 Agent/模型/环境类--exit-immediately模型提交后立即退出不再询问一个典型的启动命令mini -t 修复 tests 目录下失败的测试用例 -c mini.yaml -m litellm/anthropic/claude-3-5-sonnet配置合并规则mini遵循命令行参数覆盖配置文件的合并策略启动脚本把所有-c解析出的配置与命令行选项构造的 dict 通过recursive_merge深度合并命令行给出的agent.mode、agent.cost_limit、agent.output_path等会覆盖配置文件中的对应键。例如mini -c mini.yaml agent.modeyolo即以 mini.yaml 为基础但强制进入 yolo 模式。注意一旦指定了-c默认配置文件将不再自动加载需要显式带上如上面的例子。会话历史与轨迹保存mini会把最近一次运行的完整历史保存到你的全局配置目录路径在启动时打印交互输入的历史含多行模式保存在全局配置目录下的interactive_history.txt由 prompt_user.py 中的FileHistory管理因此你可以在新会话里用上下箭头翻出旧命令完整对话轨迹含每次模型调用、每一条动作与观测、最终exit_status与submission默认写入last_mini_run.traj.json格式为mini-swe-agent-1.1可直接用于回放与分析。八、源码级流程总结把以上机制串起来一次完整的mini交互会话的运行时流程是启动mini.py解析命令行 → 合并配置 →get_agent(..., default_typeinteractive)实例化InteractiveAgent任务输入若无-t用多行提示EscEnter 提交让用户输入任务主循环继承自DefaultAgent.run反复调用step()直到对话中出现role exit的消息单步重写后的 step若非 human 模式query()检查限额 → 调用模型 → 把模型消息加入对话若是 human 模式直接读取用户命令注入对话execute_actions()确认或白名单豁免→ 逐个执行动作 →finally中格式化观测消息并追加若动作触发Submitted走_check_for_new_task_or_submit询问新任务或退出中断/异常KeyboardInterrupt→ 中断评论注入LimitsExceeded→ 交互式续跑或干净停止TimeExceeded→ 直接停止收尾轨迹保存到输出文件打印保存路径。整个交互层的异常体系都建立在 exceptions.py 的InterruptAgentFlow之上Submitted、LimitsExceeded、TimeExceeded、UserInterruption、FormatError都是它的子类异常携带的消息会被加入轨迹这也是 DefaultAgent 控制流的核心设计——用异常而非状态标志来管理流程使InteractiveAgent的子类化扩展变得非常轻量。九、实践建议日常开发默认 confirm 模式即可既能看到模型的每一步动作又能及时拦截危险命令批量/无人值守使用--yolo并配合--cost-limit设好成本护栏同时记得限额超限时非交互环境会干净停止并保存轨迹不会崩溃精准豁免把git diff、echo等低风险命令写进whitelist_actions减少频繁确认的打扰把rm -rf、sudo等高危操作留在确认流程里多任务接力利用完成任务后输入新任务继续的特性在同一个会话里串联多个子任务避免反复冷启动限流兜底交互式会话中成本超限可以现场调高限额续跑但墙钟时间限制无法解除需要预留充足时间预算。通过本文的配置参数、模式切换、确认机制与源码级实现剖析你应该已经能够在mini交互式终端中自如控制 Agent 的自主程度让它在全自动与全程确认之间按需切换。赞分享人工智能大模型AI Agent代码智能体【免费下载链接】mini-swe-agentThe 100 line AI agent that solves GitHub issues or helps you in your command line. Radically simple, no huge configs, no giant monorepo—but scores 74% on SWE-bench verified!项目地址https://gitcode.com/gh_mirrors/mi/mini-swe-agent点击查看免费下载相关推荐mini-swe-agent Trajectory Inspector 完全指南用 mini-e i 交互式浏览 .traj.json 运行轨迹mini swe agent Trajectory Inspector 完全指南用 mini e i 交互式浏览 .traj.json 运行轨迹 mini s人工智能大模型AI Agent代码智能体Bytebase 页面 Agent 前端模块Page Agent架构解析与扩展开发指南Bytebase 页面 Agent 前端模块Page Agent架构解析与扩展开发指南 导读 Bytebase 控制台内置了一个面向数据库日常运维的“页面人工智能大模型AI Agent代码智能体在 LinuxUbuntu上安装 Google ChromeThe Odin Project 课程 wget apt 安装 .deb 实战指南在 LinuxUbuntu上安装 Google ChromeThe Odin Project 课程 wget apt 安装 .deb 实战指南 Goo人工智能大模型AI Agent代码智能体上一篇Vim终极多窗口工作流指南高效管理Windows与Tabs的完整教程下一篇Redux Thunk测试覆盖率工具Istanbul与Jest集成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考