多轮持久会话
每个会话一条常驻运行线，随时接着聊；历史落盘，关掉浏览器再打开还在
Capabilities
九项核心能力
不是「一问一答」的聊天窗口，而是一个能被打断、能恢复、能被审批卡掐住的多轮运行时。
抢占
Agent 回答途中你又发一条，旧的一轮在安全点让位给新的
中止
立刻停掉当前这一轮
人工审批（HITL）
写文件、执行命令等动作在执行前挂起，你批准后从 checkpoint 恢复
多 agent 委派
一个主 agent 把活分给子 agent（只读检索 / 改代码 / 审阅），可并行
知识库
把自己的语料建成索引，agent 用 kb_search 检索并给出来源
配置热更新
改 llm/ agents/ policy/ 保存即生效，不用重启
图形化配置编辑器
界面里直接编辑配置文件，写入前自动校验
斜杠命令与技能
/review、/explain、/fix 等开箱可用；技能可自建
Rules
多 agent 运行时最容易出的问题，heron 把它变成硬规则
「谁还能干什么，说不清」是多 agent 系统最常见的翻车方式。这五条是出厂就成立的约束。
- 01
工具边界分层，永不合并
外层
policy/permissions.yaml定全局ask/deny， 内层每个 agent 用自己的disabled_tools收窄。 外层的deny对所有 agent 生效，子 agent 放松不了它。 - 02
委派有深度上限
入口 agent 是第 0 层，深度 d 的 agent 当且仅当
d < max_depth才能再生子 agent； 拓扑超限启动期就报错，不静默截断。 - 03
一个会话能同时跑多个 agent
互不依赖的活并行分派；用量按 agent 分账。
- 04
配置是文件
模型档案、提示词、审批策略都是能读能改的文件：要 review 就 review， 要提交进版本库就提交 —— 全放本地、只你自己看，同样跑得好好的。
- 05
一个二进制，扔哪都能跑
前端嵌在 41MB 的单文件里，跨平台静态编译，运行时没有额外依赖要一起装。
Architecture
架构示意
一条消息从你手里到工具箱，中间只隔几层；干完的动静再沿事件流回到浏览器。 层与层之间的事你基本不用管 —— 只有「要不要点头」这一件需要你参与。
你浏览器里对话 · 审批 · 传附件
请求
接口层一条会话一条常驻运行线 · 事件流式回传
编排
运行时多轮常驻 · 抢占与中止 · 从断点恢复
装配
agent提示词 · 模型 · 工具 · 子 agent
调用
读代码检索、追调用链
改文件 · 执行命令默认要先点头
委派子 agent并行或串行
检索知识库带出处引用
事件流回到浏览器
需要你点头的动作走到「改文件 · 执行命令」这类动作时，这一轮当场停住，界面弹出审批卡； 你批准，它从断点继续；你拒绝，理由写不写都行，写了会回灌给它让它换条路走。
Human in the loop
它要动手，会先停下来问
当 agent 要调用被标记为 ask 的工具时，轮次会停住， 输入框被一张审批卡取代。批准后从 checkpoint 继续；拒绝的理由写不写都行，写了会回灌给模型。
- 工具三档：
allow放行 /ask要点头 /deny不可用 - 判定顺序：
deny → ask → 兜底 allow - 外层
deny是全局禁令，子 agent 无法放松
下面是用户手册里那张卡的真实形态，可以直接点。
审批模型细节 →你
把 internal/config.go 里的端口改成 9090
coder
先确认一下当前实现。
read_fileinternal/config.go✓
⚠
Approval required
The agent is paused until you respond.
write_file
/your/project/internal/config.gocoder
✓ 已批准 · 从 checkpoint 恢复，继续执行
write_fileinternal/config.go✓
端口已改为 9090，其余配置未动。
coder
✕ 已拒绝 · 理由已回灌给模型
收到，那这个端口我不动了 —— 你说的对，它由 config.yaml 统一管理。要我改那边吗？
Multi-agent
出厂就两个 agent，一套
heron init 写出 main 与 task 两个 agent ——main 的 subagents: [task] 引用 task， 少一个就是启动期硬错误，所以总是两个一起写。
「谁能写」靠两层控制：外层 policy/permissions.yaml 的deny（谁都别想用）＋ 内层各 agent 自己的 disabled_tools。 手册里还有一组更细的四角色样例。
| 角色 | 干什么 | 能写文件吗 |
|---|---|---|
main | 只做决策与委派，不自己写文件 | 否 |
task | 按任务单执行 | 能 |
Get started
五分钟，跑起来
前置只有三样：一个 OpenAI 兼容端点、Go 1.27.1+、bun 1.3+。 出厂默认 deepseek，DeepSeek、Kimi、通义、vLLM、Ollama 都行， 只要兼容 /chat/completions。
- heron init 只补继承链上确实缺的东西，不会覆盖你已有的配置
- 密钥只从环境变量读，yaml 里只放
${ENV}引用；出厂默认端点是deepseek - 改 llm/ agents/ policy/ 保存即生效，server/ 则需要重启
终端
# 构建（前端 + 单文件二进制）
make build
# 在你的项目里生成最小可运行配置
cd /your/project && heron init
# 密钥只从环境变量读（出厂默认端点是 deepseek）
export DEEPSEEK_API_KEY=sk-...
# 启动，打开 http://localhost:8080
heronTutorial
使用教程
手册全文按章拆开，左侧目录可直接跳到某一节。下面是最常用的几章， 剩下的（知识库、故障排查、HTTP 接口）在手册首页。