首页 / 开源热榜 / mini-swe-agent / 使用教程

mini-swe-agent 中文教程：安装、执行环境与 SWE-agent 对比

更新于 2026-09-23 · NGJOO AI 实验室 · 约 8 分钟

mini-swe-agent 用很短的 Agent 循环处理 GitHub issue 和命令行开发任务。它只把 bash 当作工具，不要求模型支持专门的 tool-calling 接口。官方所说的“100 行”指核心 Agent 类，环境、模型适配和运行脚本仍是项目的一部分。

当前版本：主文档是 v2；GitHub 最新正式 release 为 v2.4.6，发布于 2026-07-23。旧版配置请查 v1 分支和 v2 migration guide，不要混用教程。

1. 安装前先确认环境

官方 pyproject.toml 要求 Python 3.10+。只想试 CLI 时优先使用隔离安装，避免把依赖直接塞进业务项目环境。

python3 --version
uvx mini-swe-agent

# 或持久安装
pipx install mini-swe-agent
mini --help

需要 Python API 时可以在明确的虚拟环境中运行 pip install mini-swe-agent。从源码开发则克隆官方仓库并执行 pip install -e .。

2. 它实际怎样工作

代码分为四块：Agent 保存线性消息历史；model 模块请求模型；environment 执行 bash 动作；run script 把这三者组合起来。默认本地环境使用 subprocess.run，每个动作独立执行，不保持一个长期 shell 会话。

这种结构的优点是容易读、容易替换环境，也更适合比较不同模型。代价是没有为每类操作准备专门工具；模型需要通过 shell 完成读取、编辑、测试和版本控制。

3. 第一次任务怎么做

创建一个不含生产密钥、可以随时丢弃的测试仓库。
新建分支或工作树，先运行 mini --help，按官方文档配置模型。
给一个边界清楚的小任务，例如修复已有测试覆盖的格式问题。
检查 diff、命令记录、测试结果和费用，再决定是否扩大任务。

权限边界：bash-only 不等于自动隔离。本地环境执行的命令继承当前用户权限。仓库含密钥、部署凭据或生产网络权限时，应先切换到 Docker/Podman 等受限环境，并限制挂载目录与网络。

4. 官方 benchmark 应该怎样看

官方 README 报告 SWE-bench Verified 成绩超过 74%，并提供 bash-only 排行榜入口。这证明某些模型和配置能在该基准上取得结果，不能直接推出你的仓库也会有相同成功率。模型版本、预算、任务难度、测试环境和停止条件都会改变结果。

5. 与 SWE-agent 的区别

维度	mini-swe-agent	SWE-agent
工具接口	只用 bash，不依赖模型 tool calling	强调 Agent-Computer Interface 与更丰富的工具
配置与代码面	核心循环短，线性历史，适合作为简单基线	配置和研究功能更丰富
官方建议	SWE-agent README 建议新用户优先采用 mini	适合仍需研究复杂接口的场景

对比依据为 mini-swe-agent README 和 SWE-agent README，核对日期 2026-09-23。

6. 本次验证边界

验证状态：本次核对了官方 README、pyproject.toml、Quick Start、environments 目录、SWE-agent README 和 GitHub Releases，没有在当前工作区安装包、连接模型或执行 Agent。

确认内容：Python 3.10+、uvx/pipx/pip 安装路径、mini CLI、bash-only 设计、线性历史、可替换执行环境和 v2.4.6 release 均能在官方材料中对应。

没有验证：模型费用、输出质量、容器隔离效果和 SWE-bench 成绩均未由本站复跑。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

适合谁用

适合研究不同模型在同一简单 Agent 循环中的表现、处理边界清楚的 GitHub issue、搭建可读的教学基线，或把执行环境切到容器后批量运行。生产仓库仍需要分支、权限限制、测试和人工审查。

原教程未展开的系统信息

核心功能

bash-only Agent 循环
Agent 不依赖模型的工具调用接口，主要让模型生成 bash 动作，再由环境执行。

架构与数据流

代码按 agents、models、environments 和 run scripts 拆分。Agent 维护线性消息历史；模型模块生成下一步动作；environment 执行命令并返回结果；run script 选择一组实现并启动任务。这个结构便于替换模型或沙箱，也意味着本地环境中的命令会继承当前用户权限。

常见问题

mini-swe-agent 当前需要哪个 Python 版本？

官方 pyproject.toml 要求 Python 3.10 或更新版本。

mini-swe-agent 只有 100 行代码吗？

不是整个项目只有 100 行。官方说的是核心 Agent 类约 100 行；环境、模型适配和运行脚本还有额外代码。

mini-swe-agent 会安全地隔离 bash 命令吗？

不一定。本地环境继承当前用户权限。需要隔离时应选择容器或其他沙箱环境，并限制密钥、目录和网络。

mini-swe-agent 和 SWE-agent 怎么选？

想要简单、可读的 bash-only 基线时选 mini；研究更复杂的工具接口和配置时再看 SWE-agent。SWE-agent 官方也建议新用户优先使用 mini。