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+,安装脚本自动准备
一次任务是怎么走完的
以「给登录接口加限流」为例。点左边的步骤看每一步终端里是什么样。
▌ 给 @src/api/auth.py 的登录接口加限流:同一个 IP 每分钟最多 5 次,超了返回 429,补上测试 ● 读取 path=src/api/auth.py ⎿ 48 行 好的。我先看一下现有的登录接口和项目里有没有现成的限流工具,再决定怎么加。 ⠋ 思考中… (2s · ESC 中断)
● 搜索 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 不受影响
╭──────────────────────────── 要执行 修改 ────────────────────────────╮ --- 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 取消
● 运行 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 随时切换四种模式:
「以后都允许」会写成规则,比如 bash(npm test);拒绝规则优先于一切,
&&、管道这类组合命令不吃允许规则,照常询问。
国产模型开箱即用
设好密钥就能用,/provider 随时切换,对话历史保留。
- DeepSeek
- Kimi
- GLM
- 通义千问
- OpenRouter
- Ollama
- 中转站
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、一次性沙箱里用。
{
"default": "我的中转站",
"profiles": {
"我的中转站": {
"protocol": "anthropic",
"base_url": "https://你的中转站地址",
"model": "模型名",
"api_key_env": "MY_RELAY_KEY"
}
}
}
不想手写?对话里 /config provider 一步步引导添加,会自动取模型列表让你挑,密钥输入不回显。
产品矩阵
抓蛙师出品,覆盖智能编程、凭据安全、服务器运维、知识管理、桌面框架、全栈开发。
智码 AICoder
AI 编程助手桌面管理客户端
九家 AI 编程 CLI 统一管理 | 远程 SSH 工作区 | Token 追踪
StoryLoom 故事织机
网文作者的本地 AI 创作工作台
AI 续写救场 | Story Bible 一致性 | API Key 不出本机
RuoYi-Plus-UniApp
Spring Boot 3 + Vue 3 + UniApp 企业级全栈框架
四层架构 | 多租户 | AI 集成 | 代码生成
AI 全能工作站
一句话搞定一切 · 63 个专业模块 · 1301 AI 技能
八大领域全覆盖 | 智能路由 | 42 集视频教程
灵动桌面框架
React 19 + Rust + TypeScript · AI 驱动 · 轻量安全 · 高性能跨平台
Tauri 2.x | 44 个 AI 技能 | 三引擎协同
Sigil
AI 凭据金库 · MCP 协议代理 —— AI 用得到、看不到明文
AES-256 加密 | MCP 代理 | 审计 + 范围控制
Reeve
服务器庄园总管 · SSH 管理 + 受控 AI 接入(MCP)
SSH 管理 | MCP 受控接入 | 四重关卡 + 审计
AgileShot
AI 时代的桌面截图与标注工具
11 种标注 | AI OCR / 翻译 | MCP 扩展
本地知识库
全文搜索 · 双向链接 · 知识图谱 · 内置 MCP Server
MCP Server | 双链图谱 | 多端同步
Officia
纯自研零依赖 Java 办公套件 —— Word / Excel / PPT 无损转 PDF
Word / Excel / PPT 无损转 PDF | PDF 加密 | OCR | 仅需 JDK
技术服务 · 承接定制开发
湛江智脑科技有限公司 · 若依科技工作室(均由抓蛙师创办):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 放行或配合权限模式。