Hazzel

这个 Agent 能做什么，适合哪些场景？

Hazzel 是一个用 Python 编写的终端编码代理，约 1 万行代码，核心循环集中在 agent/core.py，所有可执行动作都在 tools/ 下，撤销系统在 safety.py 中。它通过 repl 接收提示、@file 引用和斜杠命令，先由 agent/fastpath.py 处理无需调用模型的本读取操作，再交由 agent/dispatch.py 分发到 16 个工具。任何写文件或执行命令的动作都要经过 safety.py 的审批、沙箱和检查点三道关口：修改以 diff 形式展示、由你确认后才写入，写入前的原始字节快照保存在 ~/.config/hazzel/undo/。它支持 Groq、OpenAI、Anthropic、Mistral、Gemini、DeepSeek、OpenRouter 以及本地 Ollama 共 8 个后端，费用由你自己的密钥直接结算。此外还提供最小化的 MCP stdio 客户端、SKILL.md 技能加载，以及 hazzel -p 与 --output-format json 的非交互管道模式。项目当前版本为 v1.6.2，采用 Apache-2.0 许可，定位于早期阶段。

启动后在终端进入 REPL：输入提示、用 @path 把文件钉入上下文、用 / 触发命令补全。核心循环读取仓库文件（read_file、搜索、列表、glob 如 **/*.py）、预览并应用编辑（edit_file）、以超时限制执行 shell（run_command），以及用 !cmd & 启动后台任务并通过 /jobs 管理。只读操作由 fastpath 本地直接回答而不走模型。每次写入前先给出 diff 并要求 y/N 确认，同一轮内一次决定即生效；ls、cat、git status 等只读命令走允许列表直接执行。每次写入前把旧内容快照进 ~/.config/hazzel/undo/（200 条事件，每文件 20 条），/undo 只回滚代理产生的片段并保留你之后的编辑，/redo 重新应用。git 相关命令 /status、/diff、/review、/commit（自动起草 Conventional 提交信息）、/log 均在本地即时执行。会话内可用 /usage、/budget 查看按提供商报告的 token 折算成美元的费用；/session save|list|restore 持久化每个项目的会话。非交互模式下 hazzel -p "prompt" --output-format json 输出 {success, response, model, usage} 或带 exit_code 的错误对象。

1. 习惯在终端工作、不想离开编辑器的开发者，希望让代理改代码但先看 diff 再决定。
2. 需要在无订阅成本下使用自有 Groq 或 OpenAI 密钥的个人开发者。
3. 在无外网环境里跑 Ollama 本地模型的团队，用 keyless 方式完成读代码与改代码。
4. 把 Hazzel 接入 CI：用 hazzel -p "prompt" --output-format json 解析结构化结果与退出码。
5. 想在提交前用 /review --staged 与 /commit 自动起草规范提交信息的工程师。
6. 需要在代理改错后只回滚它的改动、保留自己后续编辑的用户（/undo 与 /redo）。

如何安装或部署这个 Agent？

无需安装即可试用（不会触碰 venv）：

uvx hazzel

或：

pipx run hazzel

长期使用可安装：

pip install hazzel

或：

uv tool install hazzel

pipx install hazzel

安装后至少配置一个提供商的密钥，例如：

export GROQ_API_KEY="..."

也可以跳过密钥，启动后在会话内用 /model 选择提供商；使用本地 Ollama 时无需密钥，可用 OLLAMA_HOST 覆盖地址。

如何使用这个 Agent？

进入你的项目目录并启动：

cd your-project
hazzel

在 REPL 中可直接用自然语言描述任务，例如修复失败的测试：

❯ Fix the failing test in tests/test_agent.py

常用命令：

❯ /review --staged
❯ /commit
❯ @screenshot.png make the nav match this
❯ /model
❯ /plan on
❯ /undo

单轮非交互执行：

hazzel -p "prompt" --output-format json

查看内置模型目录（无需密钥或网络）：

hazzel --list-models

可选环境变量：

export HAZZEL_CODE_THEME=monokai
export HAZZEL_NO_UPDATE_CHECK=1

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

常见问题