mini-swe-agent 入门完全指南：100 行代码的极简 AI 编程代理设计与实战

人工智能大模型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 是 SWE-bench / SWE-agent 团队普林斯顿与斯坦福背景推出的极简 AI 编程代理核心 Agent 类仅约 100 行 Python不依赖任何工具调用tool-calling接口只用 bash 就能在 SWE-bench verified 上取得超过 74% 的成绩。本文基于官方文档与仓库源码系统讲解 mini-swe-agent 的设计哲学、控制流、安装方式、CLI 与 Python 绑定用法、配置体系与模型接入帮助你快速上手并用它完成本地命令行任务或 SWE-bench 类基准评测。一、为什么是100 行极简设计的三根支柱在 2024 年SWE-bench 与 SWE-agent 推动了编码代理革命。一年之后随着大模型能力大幅提升团队提出一个核心问题如果我们的代理比原来简单 100 倍还能不能保持几乎相同的效果mini-swe-agentmini就是对这个问题的回答。它的设计可以归结为三条关键决策见 docs/index.md 与 docs/faq.md唯一工具是 bash甚至不使用 LM 的工具调用接口。这意味着你可以用任意模型运行它只要能输出文本在沙箱环境中也无需安装任何额外包——只需要 bash 存在。想让代理做某件具体的事比如打开 PR直接告诉模型让它自己用 shell 搞定而不是为代理实现一个专用工具。完全线性的历史linear history每一步只是把消息追加到 messages 列表再无其他。因此轨迹trajectory与传给 LM 的消息没有任何区别这对调试和微调fine-tuning / RL都极为友好。用subprocess.run执行动作每个动作完全独立不维护有状态的 shell 会话。这让沙箱化执行变得极其简单把subprocess.run换成docker exec即可也易于大规模并行扩展。这三点共同支撑起两个典型使用场景作为研究基线系统把注意力放在语言模型本身而非代理脚手架可在 SWE-bench bash-only 排行榜上对比不同 LM 的表现与作为可 hack 的日常工具简单到一眼能看懂、方便到能融入日常工作流、灵活到可扩展。源码级印证真的只有 100 行核心 Agent 类src/minisweagent/agents/default.py本地环境bash 执行src/minisweagent/environments/local.py模型封装litellmsrc/minisweagent/models/litellm_model.py运行脚本src/minisweagent/run/hello_world.py在 src/minisweagent/environments/local.py 中可以看到_run的实现用subprocess.Popen以shellTrue执行命令start_new_sessionTrue保证超时后能os.killpg杀掉整个进程组避免孤儿进程——这就是每个动作独立执行的底层实现。为什么不需要常驻 shell 会话是件大事FAQ 专门解释了这一点传统代理维护一个持续运行的 shell 会话随之而来的是三大难题——无法可靠判断命令何时结束各种启发式都很不可靠、LM 的坏命令可能直接杀死整个会话、中断命令会搞乱会话状态并污染后续输出。mini 完全绕开了这些问题每个动作是一次独立的subprocess.run/os.system/docker exec调用。代价是代理不能持久地cd或export环境变量但这完全可以通过给每个动作加前缀解决例如cd /path/to/project ...事实上 Claude 等模型即使你不要求也会主动这么做。二、整体架构Agent、Model、Environment 三组件从 src/minisweagent/init.py 可以看到项目通过Protocol协议与鸭子类型定义了三类核心组件组件Protocol核心职责默认实现AgentAgent循环调度调模型、执行动作、处理异常与结束条件DefaultAgentdefault.pyModelModel查询 LM、格式化消息与观察结果、解析动作、统计成本LitellmModellitellm_model.pyEnvironmentEnvironment执行动作bash 命令、提供模板变量、检查是否完成LocalEnvironmentlocal.py三者之间通过少量方法约定协作model.query(messages)、model.format_message(...)、model.format_observation_messages(...)、env.execute(action)、env.get_template_vars()、agent.run(task)等。得益于 Protocol 鸭子类型你可以几乎无视这些接口直到需要静态类型检查或自定义组件时才去关注。Agent 控制流run → step → query → execute_actionsDefaultAgent.run 的核心是一个 while 循环不断调用step()直到消息列表中最后一条的role exit才返回结果字典含exit_status、submission等键。step()本身只有一行def step(self) - list[dict]: return self.execute_actions(self.query())query()先检查 step 数限制step_limit、成本限制cost_limit、墙钟时间限制wall_time_limit_seconds再调用model.query(self.messages)并把结果加入 messages。execute_actions()对消息中extra.actions里的每个动作调用env.execute(action)然后通过model.format_observation_messages把执行输出格式化成观察消息再追加进 messages。异常即控制流是本项目的一大特色InterruptAgentFlow的子类异常携带消息被run()捕获后直接追加到轨迹中循环在出现roleexit消息时终止。关键异常包括Submitted环境检查到命令输出以魔术字符串COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT开头且返回码为 0时抛出表示任务完成并提交最终输出见 local.pyLimitsExceeded达到 step 或 cost 上限FormatErrorLM 输出不符合预期格式解析失败会累计连续错误次数超过max_consecutive_format_errors后以RepeatedFormatError结束TimeExceeded/TimeoutError动作执行超时。完整流程图与逐步说明可参考 控制流文档。三、安装与快速上手三种安装方式方式一只想快速试 CLI隔离环境不装进当前环境pip install uv uvx mini-swe-agent # 或 pip install pipx pipx ensurepath pipx run mini-swe-agent方式二安装到当前环境CLI Python 绑定pip install mini-swe-agent mini # 运行 CLI mini-extra # 额外工具配置、检查器等方式三从源码安装开发者模式git clone https://github.com/SWE-agent/mini-swe-agent.git cd mini-swe-agent pip install -e . mini # 运行 CLI更多安装细节见 quickstart.md使用 uv 时也可用uv tool install mini-swe-agent永久安装用 pipx 则推荐pipx install mini-swe-agent。若想参与开发还需要pip install -e .[dev]并安装 pre-commit 钩子pip install -e .[full]会安装全部可选依赖extra/目录下的内容。模型配置首次运行模型应在第一次运行mini时通过设置向导配置。如果错过了运行mini-extra config setup即可。两个关键点建议在模型名中包含提供商例如anthropic/claude-sonnet-4-5-20250929模型名存储在配置环境的MSWEA_MODEL_NAME变量中可用mini-extra config set MSWEA_MODEL_NAME anthropic/claude-sonnet-4-5-20250929永久设置FAQAPI key 可用export OPENAI_API_KEYsk-test123临时设置或用mini-extra config set OPENAI_API_KEY sk-test123永久写入配置文件。全局配置存放在配置目录的.env文件中键值对格式由dotenv读取具体位置在运行mini --help时打印。从 src/minisweagent/init.py 可以看到全局配置目录由platformdirs.user_config_dir(mini-swe-agent)决定也可用MSWEA_GLOBAL_CONFIG_DIR环境变量覆盖。示例任务官方推荐的练手 promptquickstart.mdImplement a Sudoku solver in python in thesudokufolder. Make sure the codebase is modular and well tested with pytest.Please run pytest on the current project, discover failing unittests and help me fix them. Always make sure to test the final solution.Help me document type my codebase by adding short docstrings and type hints.四、CLI 用法mini命令核心参数mini是默认的可执行入口实现于 src/minisweagent/run/mini.py基于 typer rich 构建。核心命令行参数如下均为可选未提供时走交互提示或配置默认值参数说明-m, --model指定模型如anthropic/claude-...--model-class指定模型类如litellm或minisweagent.models.litellm_model.LitellmModel--agent-class指定 Agent 类如interactive或minisweagent.agents.interactive.InteractiveAgent--environment-class指定环境类如local或minisweagent.environments.local.LocalEnvironment-t, --task任务/问题描述-y, --yolo无需确认直接运行-l, --cost-limit成本上限设为 0 禁用-c, --config配置文件/文件名/键值对列表多个配置会递归合并注意设置了该选项后默认配置文件将不再使用-o, --output轨迹输出文件默认写到全局配置目录下的last_mini_run.traj.json--exit-immediately代理想结束时立即退出而非询问高级选项-c的典型组合用法多个配置递归合并mini -c mini.yaml -c model.model_kwargs.temperature0.5 mini -c swebench.yaml agent.modeyolo注意一旦使用-c就必须显式包含默认配置文件如mini.yaml否则默认配置不会生效。五、Python 绑定五步跑起一个代理除了 CLImini-swe-agent 也是一等公民的 Python 库。最简示例python_bindings.mdimport logging from minisweagent.agents.default import DefaultAgent from minisweagent.models import get_model from minisweagent.environments.local import LocalEnvironment logging.basicConfig(levellogging.DEBUG) task Write a hello world program model_name anthropic/claude-sonnet-4-5-20250929 agent DefaultAgent( get_model(input_model_namemodel_name), LocalEnvironment(), ) # 运行代理 agent.run(task)更简化的手工组装版hello_world.pyagent DefaultAgent( LitellmModel(model_namemodel_name), LocalEnvironment(), ) agent.run(task)agent.run()返回包含exit_status、submission键的字典。你还可以用agent.save(path)把完整轨迹含模型配置、环境配置、消息列表、trajectory_format: mini-swe-agent-1.1以 JSON 保存供 inspector 轨迹浏览器 回放。更深入的子类化与组件混搭见 cookbook。六、配置体系默认 YAML 与模板变量默认配置 default.yaml配置按agent/environment/model三段组织agent.system_template系统提示词。规定每条响应必须恰好包含一个 bash 代码块mswea_bash_command命令前要有 THOUGHT 推理说明并给出format_example格式示例agent.instance_template任务提示词。包含推荐的 6 步工作流分析代码库 → 写复现脚本 → 改源码 → 重跑脚本验证 → 测试边界情况 → 用echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT提交并结束并明确目录/环境变量变更不持久每个动作都在新的子 shell 中执行还内置了sed编辑、nl -ba | sed -n 10,20p查看文件、MacOS 下sed -i 等实用命令示例agent.step_limit最大步数0 表示不限agent.cost_limit成本上限超过即停止environment.env为子进程注入的环境变量PAGERcat、MANPAGERcat、LESS-R、PIP_PROGRESS_BARoff、TQDM_DISABLE1model.observation_template执行输出格式化模板——输出超过 10000 字符时只保留头尾各 5000 字符并提示输出过长请换用更精简的命令防止上下文被刷爆model.format_error_template格式错误时的反馈模板例如根据finish_reason区分是输出 token 截断还是格式错误。AgentConfig 参数编程方式配置在 default.py 中AgentConfig定义了所有可编程配置项参数默认值含义system_template必填系统消息模板instance_template必填首个用户消息任务模板step_limit0最大步数0 不限cost_limit3.0超过此成本即停止wall_time_limit_seconds0墙钟时间上限0 不限max_consecutive_format_errors3连续格式错误次数上限0 不限output_pathNone轨迹保存路径模板是Jinja2 StrictUndefined渲染的default.py可用变量来自 agent 配置、环境cwd、env、timeout以及platform.uname()的系统信息、模型配置以及n_model_calls、model_cost、elapsed_seconds等运行时统计。未定义的变量会直接报错避免静默吞错。七、环境支持从本地到沙箱mini默认在本机 bash 执行LocalEnvironment超时默认 30 秒可用timeout配置。同时官方还提供多种沙箱环境见 src/minisweagent/environmentsdocker / podmandocker.pysingularity / apptainersingularity.pybubblewrapextra/bubblewrap.pycontreeextra/contree.pyswerex_docker / swerex_modalextra/swerex_docker.py、extra/swerex_modal.py环境文档见 docs/reference/environments 下的对应页面。因为每个动作都是独立子进程沙箱化只需把执行后端换成容器运行时这正是可部署性的来源。八、模型接入litellm 与更多提供商LitellmModel 是默认模型封装通过litellm.completion查询任意 litellm 支持的模型带BASH_TOOL工具声明与drop_params: true等参数并具备成本统计用litellm.cost_calculator计算每次调用成本失败时可通过cost_tracking: ignore_errors或环境变量MSWEA_COST_TRACKINGignore_errors忽略用于本地模型等未注册模型自动重试内置retry装饰器对认证失败、参数不支持、上下文超限等异常中止重试多模态multimodal_regex支持从输出中提取图片等多模态内容openai_multimodal.py缓存控制set_cache_control可为 Anthropic 模型设置缓存标记cache_control.py错误响应持久化格式解析失败时会把原始响应与成本信息一并写入异常消息的extra保证 spec 契约响应必须被持久化无条件成立。除 litellm 外项目还提供openrouteropenrouter_model.py、portkeyportkey_model.py、requestyrequesty_model.py等封装并支持/completion与/response端点、交错思考interleaved thinking等能力。模型能力总览见 docs/reference/models/overview.md。本地模型的使用见 models/local_models.md。九、选择指南mini-swe-agent vs swe-agent官方建议把mini-swe-agent作为默认选择docs/index.md 与 FAQ用 mini-swe-agent 当你的默认选择特别是当你只想要一个在本地快速工作的命令行工具你希望控制流极其简单你需要更快、更简单、更稳定的沙箱化与基准评测你在做 FT 或 RL不想过拟合某个特定的代理脚手架。仍然可以考虑 swe-agent 当你想尝试不同的工具集每个工具各自有独立接口你想尝试不同的历史处理器history processor你想要不碰代码、非常强大的 YAML 配置。两者都能获得出色的 SWE-bench 表现 轨迹浏览器。十、v2 迁移与后续学习路径当前仓库对应mini-swe-agent v2版本号见 src/minisweagent/init.py 中的__version__。如果你从 v1 升级务必阅读 v2 迁移指南。官方推荐的学习路径安装与快速开始CLI 用法mini 命令全局配置YAML 配置详解控制流详解cookbook扩展与子类化Python 绑定轨迹浏览器 inspectorSWE-bench / ProgramBench 基准评测、docs/usage/programbench.mdFAQ结语mini-swe-agent 用只保留 bash、线性历史、无状态子进程执行三条极简原则把编码代理从复杂脚手架中解放出来让语言模型本身成为注意力的中心。无论是作为本地命令行助手mini、Python 库集成DefaultAgentLitellmModelLocalEnvironment还是作为 SWE-bench 类基准的评测基线它都以简单到可以一眼看懂、灵活到可以随手 hack的姿态成为值得上手研究的开源实现。赞分享人工智能大模型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约 100 行代码的极简 AI 软件工程智能体核心设计与上手实战mini swe agent约 100 行代码的极简 AI 软件工程智能体核心设计与上手实战 mini swe agent仓库内包名为 miniswea人工智能大模型AI Agent代码智能体PocketFlow 极简 LLM 框架深度解析100 行代码的图抽象、设计理念与实战入门PocketFlow 极简 LLM 框架深度解析100 行代码的图抽象、设计理念与实战入门 PocketFlow 是一个把 LLM 框架的核心抽象压缩进 10人工智能大模型AI Agent工作流自动化RAG零代码门槛用SWE-agent极速运行SWE-bench Lite数据集的完整指南零代码门槛用SWE agent极速运行SWE bench Lite数据集的完整指南 你是否在为SWE bench Lite数据集的复杂配置而头疼还在手动处理AI AgentAgent 框架代码智能体后端开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考