专家配专模
每个 Agent 在 agents/*.md 里声明自己的 model:，简单检索不为不需要的推理能力付费，复杂任务也不将就小模型。
openheron本地优先多 Agent
Agent 即工具 多 Agent 运行时
每个专家 Agent 绑定适合自己的模型，父 Agent 只做编排与合成。省 token 不是靠压缩提示词，是靠边界让不该跨界的内容不跨界 —— 隔离是完全的：专家的中间过程不进父的任何一轮上下文。
名字来自苍鹭（heron）：长久静立、瞬间精准出手。
$ openheron [main] config loaded: version=3f2a1b9c8d0e [main] frontend: embedded from web/dist > 帮我看看这个仓库的顶层目录 …
How it saves
三条机制拿到「省 token」
省 token 有三种做法，openheron 走的是第三条。
工具即隔离
专家 Agent 作为一个有界能力被调用：它自己的工具循环与中间推理留在自己的上下文里，父 Agent 只拿到它写的那份结构化总结。
结构即节省
边界让不该跨界的内容不跨界 —— 隔离是完全的：专家的中间过程不进父的任何一轮上下文。
Boundaries
边界先说清楚，比事后解释便宜
省 token 在可分解、工具输出冗长的任务上最显著；顺序依赖强的任务，单 Agent 反而可能更快更准。
「省 41%」是 openheron 自带基准的实测口径：三类编码任务、同一张价格表下，多 Agent 拓扑花了「一个强模型直干」的 0.587 倍；同一轮它通过 6/9（基线 9/9，其中两次失败是端点超时）—— 省钱和可靠性要一起看。
「高性能」指单位 token 的有效产出，不承诺零延迟或无限并发。
专家配专模要配对才划算：出厂配置里两个 Agent 共用一个模型，配错模型比不配更浪费。
可观测性同样是完全的 —— 专家的思考与工具调用实时出现在界面上（带归属），也留在记录里。
Rules
多 Agent 运行时最容易出的问题，openheron 把它变成硬规则
「谁还能干什么，说不清」是多 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
一个二进制，扔哪都能跑
前端嵌进单文件，跨平台静态编译，运行时没有额外依赖要一起装。
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
Agent 已暂停，等你回应。
write_file
/your/project/internal/config.gocoder
✓ 已批准 · 从 checkpoint 恢复，继续执行
write_fileinternal/config.go✓
端口已改为 9090，其余配置未动。
coder
✕ 已拒绝 · 理由已回灌给模型
收到，那这个端口我不动了 —— 你说的对，它由 config.yaml 统一管理。要我改那边吗？
Capabilities
核心能力
不是「一问一答」的聊天窗口，而是一个能被打断、能恢复、能被审批卡掐住的多轮运行时。
多轮持久会话
每个会话一条常驻运行线，随时接着聊；历史落盘，关掉浏览器再打开还在。
上下文压缩
对话到 Agent 的阈值（默认窗口的 80%）自动压成摘要，也可以 /compact 立刻压。压的是上下文，记录仍然读得到。
一个会话一轮
同一会话同时只跑一轮；另一个窗口再发会被拒（409 session_busy），正在跑的那轮不受影响 —— 停止它才能接管。
中止
立刻停掉当前这一轮。
人工审批（HITL）
写文件、执行命令等动作在执行前挂起，你批准后从 checkpoint 恢复。
多 Agent 委派
一个主 Agent 把活分给子 Agent（只读检索 / 改代码 / 审阅），可并行。
知识库
把自己的语料建成索引，Agent 用 kb_search 检索并给出来源。
配置热更新
改 llm/ agents/ policy/ 保存即生效，不用重启。
图形化配置编辑器
界面里直接编辑配置文件，写入前自动校验。
斜杠命令与技能
/review、/explain、/fix 等开箱可用；技能可自建。
Multi-agent
出厂就两个 Agent
openheron init 写出 main 与 task 两个 Agent —— main 的 subagents: [task] 引用 task，少一个就是启动期硬错误，所以总是两个一起写。
| 角色 | 干什么 | 能写文件 |
|---|---|---|
main | 只做决策与委派，不自己写文件 | 否 |
task | 按任务单执行 | 能 |
quickstart
# 构建（前端 + 单文件二进制）
make build
# 在你的项目里生成最小可运行配置
cd /your/project && openheron init
# 密钥只从环境变量读（出厂默认端点是 deepseek）
export DEEPSEEK_API_KEY=sk-...
# 启动，打开 http://localhost:8080
openheronManual
完整使用手册
十章，按需查阅。每一章都能直达小节。