mini-agent
终端里的编码 Agent,面向会写配置的开发者。模型、MCP、权限都写在一个 mini-agent.json 里,
skill 用和 Claude Code / Codex / opencode 相同的 SKILL.md 格式。依赖只有 mcp、prompt_toolkit(交互输入)和 rich(渲染)。
Agent = LLM + 工具 + 循环
第一次用建议先看 上手指南:5 分钟上手、常用操作速查、配置示例、常见问题。
安装
三种方式任选,装完都是 mini-agent 命令。需要先有 uv(curl -LsSf https://astral.sh/uv/install.sh | sh 或 brew install uv),它会自动准备 Python 3.13:
uv tool install mini-agent-cli # PyPI(包名带 -cli,命令是 mini-agent)
npm i -g @chesterzhao/mini-agent # npm(启动器,内部用 uvx 跑同版本的 PyPI 包)
uvx --from mini-agent-cli mini-agent # 不安装,直接跑
首次运行会把包里的 mini-agent.example.json 复制到 ~/.config/mini-agent/mini-agent.json,改这份就行。
开发时用 uv tool install -e .,改代码即时生效。
登录模型厂商
mini-agent --login # 或者进去以后 /login,/logout 删掉
| 方式 | 厂商 |
|---|---|
| 填官方 API Key | DeepSeek、阿里云百炼、OpenAI、Anthropic、Kimi、智谱 GLM、Google Gemini、OpenRouter |
| 浏览器登录 | ChatGPT Plus/Pro 订阅(非官方接入,借用 Codex CLI 的 OAuth;远程机器可用设备码)、OpenRouter(授权后生成一个 API Key) |
凭证存在 ~/.config/mini-agent/auth.json(权限 600)。登录过的内置厂商不用再写 provider 配置;
配置里写了的以配置为准。取 key 的顺序:auth.json(/login 存的)→ 环境变量;想退回环境变量就 /logout。ChatGPT 的 token 过期会自动刷新。
Claude Pro/Max 订阅不支持:Anthropic 已明确禁止第三方工具使用订阅登录,用 Claude 请填 Anthropic API Key。
使用
mini-agent # 交互模式,在哪个目录启动就在哪干活
mini-agent -c # 接着这个项目最近一次的会话
mini-agent -r 20260930-003217 # 接着指定的会话(退出时会打印编号)
mini-agent -p "@src/app.py 这个文件有什么问题" > out.md # 问一句就退出;stdout 只有答案
mini-agent -m bailian-anthropic/qwen3.8-flash
mini-agent --yes # ask 类操作全部放行(deny 仍然禁止)
mini-agent -p "总结这个仓库" --json # JSONL 事件流,给脚本 / CI 用
--json 每行一个事件:text / thinking(增量)、tool_start、tool_end、todos、note,
最后一条 done(带最终回答和上下文 token)或 error。stdout 上不会有别的东西。
交互
-
输入
/弹出命令菜单,输入@弹出项目文件(git ls-files,尊重 .gitignore)。Tab 补全,↑ ↓ 翻历史 -
图片和 Claude Code 一样放进同一句话里:Ctrl+V 贴剪贴板里的截图(或在访达里 Cmd+C 复制的图片文件), 把图片拖进终端也行,都会变成
[Image #1]占位符,接着打字提问,一起发出去。编号整个会话有效, 后面可以说「再看下 [Image #1]」 -
回答按 Markdown 渲染:一段写完整就定格显示,代码块高亮;底部一行状态显示
✻ 思考中…/✻ 回答中… -
工具调用显示成一行,下面是结果摘要,失败的标红:
● read app.py ⎿ 1 def greet(name): -
审批按一个键:
y允许、a记住放行、n/ Esc 拒绝、Ctrl+C 中断这一轮。改文件时显示彩色 diffa的范围:命令按开头的词(git ...);带;&&|$()这类拼接的命令只放行完全相同的那一条- 命令、网页、MCP 工具、外部目录按
a会按项目记住,下次启动不再问,/permissions查看和撤销; 改文件按a只管本次会话 - 只读命令(
git status/diff/log/show/branch、ls、pwd,且没有拼接和重定向)不用确认 - 危险命令(
rm -rf、sudo、git push --force、git reset --hard、curl … | sh等)每次单独确认, 不提供「都允许」,配置里allow也挡不住;只有--yes能跳过
-
限流(429)、服务过载(5xx / 529)、连不上时自动退避重试(最多 3 次,按服务端的 Retry-After 等),状态行下显示
⟳ -
当前模型因为 key / 余额 / 模型名用不了时,弹出列表换一个模型自动重发,可以顺手设为默认
-
Shift+Tab 切换模式:默认(逐项询问)→ 自动改文件(改文件不问,命令仍问)→ 计划(只读,只出方案不动手)
-
多行输入:Alt+Enter 换行,或者行尾打
\再回车;粘贴多行原样保留 -
任务清单:三步以上的任务,模型用
todo工具列出步骤并随进度打勾(☐ ◐ ☑) -
输入框下的状态行:模型 · 目录 · 模式 · 上下文(配了窗口大小时带百分比)· 缓存命中 · 累计费用 · 任务进度
-
有新版本时,启动的欢迎框里提示一行升级命令(每天最多查一次 PyPI,后台进行不拖慢启动;配置
"updateCheck": false关掉) -
!命令直接执行 shell 命令(不经过模型),输出附到下一条消息里 -
Esc 打断正在进行的回答;Ctrl+R 搜输入历史;Ctrl+G 用
$EDITOR写长消息 -
回答过程中可以接着打字,回车排进队列(状态行显示「排队 N 条」),这一轮结束后自动发
-
一轮超过 30 秒,结束时发系统通知(配置
"notify": false关掉)
| 命令 | 作用 |
|---|---|
/model [provider/model] |
切换模型,对话保留,可以跨厂商、跨协议。不带参数弹出可搜索列表(↑↓ 选、打字过滤、回车切换),候选含启动后向各家实时拉取的模型 |
/resume |
选一个这个项目之前的会话接着聊 |
/clear |
开始新会话(旧的还能 /resume 找回) |
/undo |
撤销上一轮:恢复它 write / edit 改过的文件(新建的删掉),删掉这轮对话,问题放回输入框。bash 命令造成的改动撤销不了 |
/diff |
看工作区相对 HEAD 的改动(彩色 git diff,不经过模型) |
/review [范围] |
审查未提交的改动(或指定文件 / 分支),只读,按严重程度列问题 |
/init |
分析项目,生成或更新 AGENTS.md |
/thinking off|low|high|default |
思考强度,按协议翻成各家参数(见下),换模型也保留 |
/session |
当前会话:文件位置、消息数、上下文、累计 token(含子 agent)和费用 |
/compact [重点] |
把对话压缩成交接摘要,腾出上下文;历史超出预算时也会自动压缩 |
/permissions |
看这个项目记住的放行,Tab 勾选要撤销的 |
/reload |
重新读配置、skills、MCP、项目说明、自定义命令,对话保留 |
/<命令名> |
自定义命令(见下);skill 也能直接 /<skill 名> 调用 |
/skills |
可搜索的 skill 列表,回车看完整说明、位置和用法 |
/tools /help /exit |
|
| Ctrl+C | 回答中:打断这一轮,已写出的部分留在历史里;有字时:清空这一行;空输入时连按两次:退出 |
| Ctrl+D | 退出。退出时打印这次的轮数、用时、token 和费用,以及 mini-agent -r <编号> 续接命令 |
自定义命令
和 Claude Code 同一个格式:一个 md 文件就是一条命令,文件名即命令名。
<项目>/.agents/commands/review.md → /review(也认 .claude/commands/)
~/.config/mini-agent/commands/*.md 全局;~/.agents/commands/*.md 和其他 Agent 共用
---
description: 用三句话点评一个文件
---
读 $ARGUMENTS,用三句话点评它:写得好的、可以改进的、风险。
$ARGUMENTS 换成命令后面的参数(/review app.py);同名时项目的覆盖全局的,内置命令优先。
项目说明
和 Codex / Claude Code 一样,从 git 根目录到当前目录,每层的 AGENTS.md、CLAUDE.md、.claude/CLAUDE.md
都会读进 system prompt(越靠近当前目录越靠后);全局的写在 ~/.config/mini-agent/AGENTS.md。
不读 ~/.claude/CLAUDE.md:那是 Claude Code 的私人配置,常带本机密码之类,读进来会发给第三方模型。
思考强度
| 协议 | off | low | high |
|---|---|---|---|
| openai-chat(百炼) | enable_thinking: false |
开,thinking_budget 2048 |
开,16384 |
| openai-chat(其他) | 不传 | reasoning_effort: low |
reasoning_effort: high |
| openai-responses | reasoning.effort: none |
effort: low |
effort: high |
| anthropic | thinking.type: disabled |
预算 2048 | 预算 16000 |
对不上的厂商在配置里覆盖,写了就用配置的:
"provider": { "deepseek": { "...": "...", "thinking": { "off": {...}, "low": {...}, "high": {...} } } }
项目信任
项目里的 mini-agent.json 能启动 MCP 命令、改写 provider 地址(你的 API Key 会发过去),所以第一次遇到
(或内容变了)会先问你信不信任;不信任就不加载,非交互模式(-p)一律不加载。信任记录按「路径 + 内容哈希」
存在 ~/.local/state/mini-agent/trusted.json。
精简 skill 清单
skill 的名字和描述每次请求都会带上。和 Claude Code 共用 ~/.agents/skills 时,里面有不少只对 Claude Code
有用的 skill,排除掉能让弱一点的模型更专注:
"skills": { "exclude": ["memmy-*", "understand*", "test-desktop-app"] } // 也可以用 include 只留想要的
本地状态
~/.local/state/mini-agent/ 下:sessions/<项目>/ 会话和记住的放行(permissions.json)、update.json 版本检查、history 输入历史、models.json 用过的模型、trusted.json 信任过的项目配置、mcp.log MCP server 日志。
配置:mini-agent.json
完整带注释的示例见 mini_agent/mini-agent.example.json。
| 位置 | 作用 |
|---|---|
~/.config/mini-agent/mini-agent.json |
全局($MINI_AGENT_CONFIG 可改) |
项目里的 mini-agent.json |
从 git 根目录到当前目录逐层深度合并,越近优先级越高 |
{
"model": "deepseek/deepseek-flash",
"provider": {
"deepseek": { "api": "openai-chat", "baseURL": "https://api.deepseek.com", "apiKey": "{env:DEEPSEEK_API_KEY}" }
},
"mcp": {
"memory": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-memory"] },
"amap": { "type": "remote", "url": "https://mcp.amap.com/mcp?key={env:AMAP_MAPS_API_KEY}" }
},
"permission": { "bash": "ask", "edit": "ask", "external": "ask", "mcp": "ask" }
}
协议(api 字段),baseURL 的写法和各家 SDK 一致:
| api | 请求 | baseURL 示例 |
|---|---|---|
openai-chat |
POST {baseURL}/chat/completions |
https://api.deepseek.com |
openai-responses |
POST {baseURL}/responses |
https://api.openai.com/v1 |
anthropic |
POST {baseURL}/v1/messages |
https://api.anthropic.com |
options 原样并进请求体(enable_thinking、max_tokens、temperature…),
models.<id>.options 只对某个模型生效。models.<id>.contextWindow 写上模型的上下文窗口(token 数,
如 { "deepseek-flash": { "contextWindow": 128000 } }),输入框下的状态行就会显示占用百分比;OpenRouter 这类在模型列表里带 context_length 的厂商会自动填上,不用手写。
models.<id>.price 填每百万 token 的美元单价({ "input": 0.27, "output": 1.1, "cached": 0.07 }),/session
和状态行就会算出费用;OpenRouter 的模型自动用它列表里的标价。
密钥写 {env:变量名};配置文件支持整行 // 注释。
让模型改配置:直接说「加一个 xxx MCP」。内置的 mini-agent-config skill 会引导模型
用 edit 改文件、校验 JSON,然后你输入 /reload 就生效。
工具
| 工具 | 说明 | 权限类别 |
|---|---|---|
bash |
执行命令;awk / sed / jq 都走它 | bash |
read |
带行号,默认 2000 行,offset 分段 |
工作目录外归 external |
write / edit |
整体写入 / 精确字符串替换,确认时显示 diff | edit |
grep |
有 ripgrep 就用 ripgrep,没有就用 grep -rn | 工作目录外归 external |
fetch |
抓网页转纯文字(去掉脚本 / 导航,有 <main> 只取正文),查文档用 |
web(a 放行整个域名) |
glob |
按通配符找文件,最近修改的在前 | 工作目录外归 external |
skill |
按需读取 skill 正文 | — |
explore |
只读子 agent:独立上下文,用 glob / grep / read 查代码库,只把结论(带 文件:行号)交回主对话。同一轮里派多个会并行跑(最多 4 个同时),界面上一个子 agent 一行,实时显示在查什么 | 只能读工作目录,不用确认 |
| MCP 工具 | 名字以 create / delete / send / run … 开头的 | mcp |
权限:ask 先问,allow 直接放行,deny 禁止。非交互模式(管道或 -p)下没加 --yes 时,ask 一律按拒绝处理。
Skills
一个目录加一个 SKILL.md(frontmatter 写 name、description),脚本和参考资料放在同一目录,
正文里让模型用 bash / read 去调用。启动时只把描述放进 system prompt,正文由模型按需读取。
查找顺序,同名的先找到先用:
- 项目:从当前目录往上到 git 根目录,每层的
.agents/skills、.claude/skills、.opencode/skills - 全局:
~/.config/mini-agent/skills、~/.agents/skills、~/.claude/skills、~/.config/opencode/skills - 内置:
mini_agent/skills/
中途换模型
参考 pi-ai 的 cross-provider handoff 设计。历史用中立格式保存,每条 assistant 消息都记着它是由哪个协议、哪个模型产生的:
- 同一个模型产生的:原样回放协议原文,thinking 签名、加密 reasoning 都不会丢
- 其他模型产生的:只用中立字段重建。thinking 转成
<thinking>文本,签名丢弃, 工具调用 id 规范成[A-Za-z0-9_-]{1,64}(Anthropic 的要求) - 中断后留下的"有调用没结果"的工具调用:补一条占位结果,保证每家接口都接受这段历史
上下文预算
- 工具结果超过 3 万字符就截断
- 只有最新一条消息保留图片
- 历史超过 40 万字符,就从最旧的一轮开始整轮丢弃
代码
mini_agent/
__main__.py 命令行 / REPL agent.py 装配、权限、循环、上下文预算
config.py 配置加载与合并 llm.py 三种协议,标准库 urllib
tools.py 内置工具 mcp.py MCP 连接
skills.py skill 发现与加载 images.py 剪贴板 / 文件 → 多模态
test_agent.py 不调模型的自检:uv run python test_agent.py
排查用:uv run python -m mini_agent.mcp、uv run python -m mini_agent.skills。
早期的教学版(step1–3、extras/)在 git 历史里:git show c619ecb。
发布
版本号要在三个地方保持一致:pyproject.toml、npm/package.json 和 git tag。推送 tag 后,由
.github/workflows/release.yml 依次完成:检查版本号 → 自检 → 验证 wheel 能装 → 发布 PyPI → 发布 npm。
两边都用 Trusted Publishing(OIDC),仓库里不存任何 token。
# 改好两处 version 之后
git tag v0.2.1 && git push origin v0.2.1
许可证
Metadata
Release files for mini-agent-cli 0.7.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mini_agent_cli-0.7.2.tar.gz | 91.9 kB | Without provenance | Details for mini_agent_cli-0.7.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mini_agent_cli-0.7.2-py3-none-any.whl | Python 3 | none | any | Details for mini_agent_cli-0.7.2-py3-none-any.whl |
Total release size: 189.0 kB
Release files / mini_agent_cli-0.7.2.tar.gz
| Download URL | mini_agent_cli-0.7.2.tar.gz |
|---|---|
| Size | 91.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c41062c5bffa7aca8484462125c61054b8959eaf5f295e2c39b568699e76d263
|
|
BLAKE2b-256 checksum How to use checksums |
931b7da00694b4ad48c89c20b1321ecb65fb38cb1c3cccb3ce4bbee85edde75d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.20 {"installer":{"name":"uv","version":"0.12.20","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mini_agent_cli-0.7.2-py3-none-any.whl
| Download URL | mini_agent_cli-0.7.2-py3-none-any.whl |
|---|---|
| Size | 97.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b15ab56209567faadc3e2f5f0759bb8b5583a0150b2f9f43f50b0ecfb6b0a729
|
|
BLAKE2b-256 checksum How to use checksums |
ae1ddbcd33832f3bf9844ef6033e97dd752565744c3dbb2a165b79dfb2e27ff6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.20 {"installer":{"name":"uv","version":"0.12.20","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mini-agent-cli 0.7.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.