开始
派第一个任务
以「给登录接口加限流」为例走一遍完整的任务：用中文描述、它先读懂项目、改文件前给你看改动、跑测试直到通过，最后看改了什么、花了多少。
- 预计用时
- 约 10 分钟
- 适用版本
- v0.5.0 及以上
- 需要准备
- 已装好 heng-agent 并配好一个服务商
先让它熟悉项目
第一次在一个项目里用，先输入 /init。它会分析项目，生成项目说明 AGENTS.md（项目里已有说明文件就更新现有的），以后每次对话都会读，回答更贴合你的项目。
项目里本来就有 CLAUDE.md、AGENTS.md、HENG.md 的，heng-agent 会直接读，不用再生成。想记一条规矩，输入以 # 开头的一句话（如 # 这个项目用 pnpm），它不发给模型，而是让你选记进项目或用户的 HENG.md。
用中文描述任务
像跟同事交代一样说清楚：要改哪、改成什么样、怎么算做完。用 @路径 直接把文件内容附上，省得它再去找。
▌ 给 @src/api/auth.py 的登录接口加限流：同一个 IP 每分钟最多 5 次，超了返回 429，补上测试 ● 读取 path=src/api/auth.py ⎿ 48 行 好的。我先看一下现有的登录接口和项目里有没有现成的限流工具，再决定怎么加。
输入框里：Enter 发送，Shift+Enter 换行（其他终端里用 Ctrl+J 或 Alt+Enter）；/ 补全命令，@ 补全文件路径。长消息可以按 Ctrl+G 用外部编辑器写。
它先读懂项目
找文件、搜代码、读文件这类只读操作直接做，不打扰你。每一步都显示成一行「● 动作 对象」，你能看到它在看什么。
● 搜索 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 夹具。
大项目里它还可能派只读的子智能体去调研，子智能体只把结论带回来，主对话不会被中间过程挤满。
改之前给你看改动
要改文件时，先弹出带红绿对比的确认框。用 ↑↓ 选，或直接按字母：
╭──────────────────────────── 要执行 修改 ────────────────────────────╮ --- 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 取消
| 选项 | 效果 |
|---|---|
这次允许 y |
只放行这一次 |
本会话一直允许 a |
这次启动期间，这个工具不再问 |
以后都允许 p |
写成一条允许规则存进用户配置，以后也不问；跑命令时规则只放行这一条命令 |
拒绝 n |
不执行这次操作；ESC 也是拒绝 |
跑测试，直到通过
改完它会自己跑测试；失败了看报错再改，直到通过。第一次跑某条命令同样会问你。
● 运行 pytest tests/api/test_auth.py -q FAILED test_login_rate_limited - assert 200 == 429 第 6 次请求没有被拦：测试客户端没带 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
方向不对随时插手：
- ESC 中断当前任务（等模型时立刻断开，跑命令时连同子进程一起停掉），不退出程序；
- 回答过程中输入框一直在：接着打字、Enter 排队，这批工具跑完时就插进这一问；不想等就按 Ctrl+X Ctrl+S 打断这一问、马上发出去；随口问一句不想打断它，用
/btw 问题（详见 输入框与快捷键）； - 前台命令跑得太久（开发服务器、watch），按 Ctrl+B 转到后台，
/tasks查看； - 上面两个快捷键目前只在 Windows 上有，macOS / Linux 用 Ctrl+C 中断。
看改了什么、花了多少
/diff：这次会话改过的文件（和第一次改之前比）；/usage（同/cost）：本会话的输入输出、缓存命中率、花费、上下文占用；- 改得不满意：
/undo撤销上一问，详见 撤销与回退； - 满意了：
/commit按仓库风格写提交信息并提交（不 push）。
做完是这样
你说了一句中文，它读了项目、改了文件、跑过测试；每次改文件、跑命令前都问过你。底部两行状态栏一直显示项目与分支、服务商与模型、上下文用量，以及权限模式。