跳到正文
heng-agent v0.5.0
Esc

0.5.0已发布到 PyPI · 一条命令装好

用中文派活,
它读代码、改代码、跑命令
直到任务完成

heng-agent 是在终端里工作的编码智能体:你描述要做什么,它自己翻项目、改文件、跑测试。 DeepSeek、Kimi、GLM、通义千问开箱即用,也能接任意兼容的中转站;改文件、跑命令前都先问你。

PS> irm https://gitee.com/bkywksj/heng-agent/raw/master/install.ps1 | iex

没有 uv 会先自动装;pypi.org 连不上自动改用清华镜像;已装过就升级到最新版。

  • Apache-2.0 开源
  • Windows / macOS / Linux
  • Python 3.11+,安装脚本自动准备
heng-agent — D:\code\my-app
heng-agent 启动后的欢迎页:HENG 字标、目录、模型、版本、权限模式,下面是输入框与两行状态栏
启动先告诉你:在哪个目录、用哪个模型、权限是什么模式。v0.5.0 实拍 · Windows Terminal

一次任务是怎么走完的

以「给登录接口加限流」为例。点左边的步骤看每一步终端里是什么样。

完整教程
heng-agent — D:\code\my-app(界面示意)
▌ 给 @src/api/auth.py 的登录接口加限流:同一个 IP 每分钟最多 5 次,超了返回 429,补上测试

● 读取 path=src/api/auth.py
  ⎿ 48 行

好的。我先看一下现有的登录接口和项目里有没有现成的限流工具,再决定怎么加。

⠋ 思考中… (2s · ESC 中断)
heng-agent — D:\code\my-app(界面示意)
● 搜索 pattern=rate_limit|RateLimiter path=src
  ⎿ 3 处
● 找文件 pattern=tests/**/test_auth*.py
  ⎿ 1 个
● 读取 path=src/middleware/limits.py
  ⎿ 62 行

项目里已经有 SlidingWindowLimiter(src/middleware/limits.py),注册接口在用。
登录接口可以直接复用它,按客户端 IP 计数。测试沿用 tests/api/test_auth.py 的 client 夹具。

计划:
 1. auth.py 的 login() 加上限流装饰器(5 次 / 60 秒)
 2. 超限返回 429,带 Retry-After 头
 3. 加两个测试:第 6 次被拒、换 IP 不受影响
heng-agent — D:\code\my-app(界面示意)
╭──────────────────────────── 要执行 修改 ────────────────────────────╮
--- src/api/auth.py
+++ src/api/auth.py
 @router.post("/login")
+@limit(SlidingWindowLimiter(max_calls=5, period=60), key=client_ip)
 async def login(form: LoginForm, request: Request):
╰────────────────────────────────────────────────────────────────────╯
允许吗?
❯ [y] 这次允许
  [a] 本会话一直允许 edit_file
  [p] 以后都允许 edit_file  写进用户配置
  [n] 拒绝  ESC 也是拒绝
↑↓ 选择 · Enter 确定 · ESC 取消
heng-agent — D:\code\my-app(界面示意)
● 运行 pytest tests/api/test_auth.py -q
  FAILED test_login_rate_limited - assert 200 == 429

第 6 次请求没有被拦:测试客户端每次请求的 IP 都是 testclient,但我用的键是
X-Forwarded-For,测试里没带这个头。改成优先取 X-Forwarded-For、没有再用 client.host。

● 修改 src/api/auth.py:替换 2 行
● 运行 pytest tests/api/test_auth.py -q
  7 passed in 0.84s

完成:登录接口限流 5 次 / 分钟,超限返回 429 与 Retry-After;新增 2 个测试,全部通过。

14:20 · 用时 1 分 12 秒 · 9 轮 · 输入 38.2k / 输出 1.6k

放心交给它的几个理由

能做事之外,更要紧的是:做错了能拦住、能撤回。

改文件、跑命令前都先问你

读文件、找文件、搜内容这类只读操作直接做;写入、修改、运行命令默认都要你点头。 文件读写只能在工作目录里,越界一律拒绝。Shift+Tab 随时切换四种模式:

ask 手动确认(默认):改文件、跑命令都问
accept-edits 自动改文件:改文件不问,跑命令还问
plan 计划模式:先读代码、交出计划,你批准了再动手
auto 全部放行:都不问,只在可信环境(CI、沙箱)用

「以后都允许」会写成规则,比如 bash(npm test);拒绝规则优先于一切, &&、管道这类组合命令不吃允许规则,照常询问。

权限模式与规则

国产模型开箱即用

设好密钥就能用,/provider 随时切换,对话历史保留。

  • DeepSeek
  • Kimi
  • GLM
  • 通义千问
  • OpenRouter
  • Ollama
  • 中转站

改错了能撤回

/undo 撤销上一问改过的文件;/rewind 选一问,对话和代码一起回到它之前。

bash 造成的改动(删文件、git 操作)无法撤销。

撤销与回退

Claude Code 的配置直接能用

项目里现成的 CLAUDE.md、AGENTS.md、技能、子智能体、自定义命令、权限规则、钩子、.mcp.json 都会读,不用迁移。

技能、MCP、钩子、子智能体

内置 5 个技能(排查问题、写测试、重构、读懂项目、安全检查);能接 MCP 服务、在编辑器里用(ACP)。

支持的服务商

内置 9 个配置档;heng-agent --list-providers 看密钥是否已设置(只显示已设置 / 未设置)。

接自己的中转站
配置档 协议 密钥环境变量
deepseek DeepSeek anthropic DEEPSEEK_API_KEY
kimi Kimi(月之暗面) anthropic MOONSHOT_API_KEY
glm 智谱 GLM anthropic ZHIPU_API_KEY
qwen 通义千问(阿里云百炼) openai DASHSCOPE_API_KEY
anthropic Anthropic 官方 anthropic ANTHROPIC_API_KEY
openai OpenAI openai OPENAI_API_KEY
openrouter 一个密钥用多家模型 openai OPENROUTER_API_KEY
ollama 本机 Ollama openai 不需要
heng 本机 heng serve(自己的模型) anthropic HENG_AGENT_API_KEY

先说清楚:这些情况它不适合

  • 想用 Claude 订阅账号登录:不支持。Anthropic 条款只允许订阅凭据用在它自己的客户端里,第三方使用有封号风险。用 API 密钥或中转站。
  • 主力在 macOS / Linux,又离不开快捷键:ESC 中断、Ctrl+B 转后台、Alt+V 粘贴图片目前只在 Windows 上有,其他系统用 Ctrl+C 与 @文件路径 代替。
  • 希望不经确认全自动改生产代码:auto 模式只建议在 CI、一次性沙箱里用。
~/.heng-agent/config.json
{
  "default": "我的中转站",
  "profiles": {
    "我的中转站": {
      "protocol": "anthropic",
      "base_url": "https://你的中转站地址",
      "model": "模型名",
      "api_key_env": "MY_RELAY_KEY"
    }
  }
}

不想手写?对话里 /config provider 一步步引导添加,会自动取模型列表让你挑,密钥输入不回显。

技术服务 · 承接定制开发

湛江智脑科技有限公司 · 若依科技工作室(均由抓蛙师创办):heng-agent 与上面这些产品的作者团队,提供完整源码交付,可签订源码交付合同。

服务详情
  • 后台管理系统 / 全栈项目开发 企业管理后台、SaaS 平台、商城、物联网平台
  • 桌面软件开发 跨平台桌面应用(Tauri),覆盖 Windows / macOS / Linux
  • 微信小程序 / 公众号 微信小程序、公众号、H5、App 全端覆盖
  • 大模型与 Agent 应用 RAG 检索增强、工具调用、多智能体编排、知识库工程化
  • 项目 AI 技能体系定制 为你的项目打造 Claude Code 技能 / 命令 / 钩子,让 AI 懂你的代码、守你的规范
  • 行业解决方案 教育、政务、医疗、金融、农业、电商等

项目咨询:198 6657 9313(电话)· 770492966(微信 / QQ)· B 站 @抓蛙师

常见问题

heng-agent 收费吗?

工具本身 Apache-2.0 开源、不收费。模型的调用费用由你选的服务商按用量收。Anthropic 协议默认开启提示缓存,命中部分按 0.1 倍计价;走 OpenAI 协议的 DeepSeek、通义、Kimi、OpenAI 也会自动缓存,/cost 都能看到命中率。要按金额显示,在配置档里填 price_in / price_out,缓存价格不同的再填 price_cache_read / price_cache_write。

我的 API 密钥存在哪?

推荐放环境变量;也可以写在用户目录下的 ~/.heng-agent/config.json(不在任何项目目录里)。项目配置里不许写密钥,写了会直接报错。

它会改我工作目录以外的文件吗?

不会。文件读写统一校验路径,越出工作目录一律拒绝,auto 模式下也一样。

怎么升级?

运行 heng-agent upgrade:Windows 上它会开个新窗口,等 heng-agent 退出后再升级。有新版本时欢迎页会提示(每天最多后台查一次)。刚发版时提示「已是最新」的话,运行 uv tool install --force --upgrade --refresh-package heng-agent heng-agent。

能在编辑器里用吗?

智码、Zed、JetBrains 等支持 ACP(Agent Client Protocol)的客户端都可以:heng-agent --acp,权限确认在客户端里弹窗,改文件带改动对比。

能不能在脚本、CI 里跑?

heng-agent -p "任务" 执行完一个任务就退出;需要确认的操作一律拒绝,除非用 --allowed-tools 放行或配合权限模式。