界面使用
3.1 布局
┌──────────────┬────────────────────────────────────┐
│ New thread │ heron ● │ ← 状态点
│ ├────────────────────────────────────┤
│ 会话 1 │ │
│ 会话 2 ◀ │ 消息流 │
│ 会话 3 │ │
│ ├────────────────────────────────────┤
│ │ [输入框] 📎 ↑ 发送 │
│ ──────────── │ agent: main · deepseek/deepseek-flash · … │
│ Settings ⌘, │ │
└──────────────┴────────────────────────────────────┘- 状态点：
Idle（灰）/Running（蓝，脉动）/Waiting for approval（黄）/Failed（红）。 - 输入框下方是当前会话的 agent、模型与思考档位，鼠标悬停可看完整信息。
3.2 会话
| 操作 | 怎么做的 |
|---|---|
| 新建 | 侧栏 New thread 或 /new |
| 切换 | 点侧栏条目 |
| 改名 | 条目右侧 ⋯（鼠标悬停出现）→ Rename |
| 删除 | 条目右侧 ⋯ → Delete |
| 中止当前轮 | 输入框里的停止按钮或 /stop |
会话历史存在 .heron/state/sessions/<id>/，重启后仍在。
有审批待处理的那条会话，标题右边会有一颗黄点 —— 即使你没开着那个会话， 也一眼能看出「有个审批在等你」。
3.3 发送与流式输出
正常输入、Enter 发送、Shift+Enter 换行。
- 工具调用显示为可展开的卡片：工具名 + 参数摘要 + 结果。
- 代码块带语法高亮。
- 输出过程中可以再发一条：旧的一轮会在安全点停下，让位给新的（抢占）。
3.4 审批卡（HITL）
当 agent 要调用被标记为 ask 的工具时，轮次会停住，输入框被一张审批卡取代：
┌────────────────────────────────────────────┐
│ ⚠ Approval required │
│ The agent is paused until you respond. │
│ │
│ write_file │
│ Requested by coder │
│ /your/project/internal/config.go │
│ │
│ [ Approve ] [ Reject ] │
└────────────────────────────────────────────┘- Approve —— 放行，agent 从 checkpoint 继续跑。
- Reject —— 写不写理由都行，但建议写：理由会回灌给模型，它据此改路； 空理由对模型等于凭空断路（服务端不强制，界面也不拦你留空）。
Requested by xxx 只在子 agent 发起时出现。根 agent（就是当前会话自己） 的审批不标 —— 那正是「当前会话」，标了只是占地方。
★ 多个审批同时出现时，一次把它们全部答掉。只答一张，其余会带着新 id 重新中断。
3.5 附件
输入框的 📎 按钮或 /attach 可以给会话加文件。文件进该会话的独立工作区
.heron/state/sessions/<id>/workspace/，agent 通过路径访问。
3.6 斜杠命令
在输入框输入 / 会弹出命令列表。
| 命令 | 类型 | 作用 |
|---|---|---|
/new |
动作 | 新建会话 |
/stop |
动作 | 中止当前轮 |
/attach |
动作 | 附件 |
/settings |
动作 | 打开配置编辑器 |
/agents [名字] |
动作 | 切换当前会话的 agent |
/skill <名字> [任务] |
提示词 | 用某个技能完成这项任务 |
/review [路径] |
提示词 | 审阅当前改动或指定路径 |
/test [路径] |
提示词 | 跑相关测试并汇总失败 |
/explain <路径或符号> |
提示词 | 解释一段代码怎么工作 |
/fix <问题> |
提示词 | 定位根因并做最小修复 |
「动作」类命令由前端直接执行；「提示词」类命令是模板，展开成一段给模型的话再发出去。
以
/开头的绝对路径（如/home/me/a.go）不会被当成命令，会原样发出。
3.7 用 @ 引用文件
在输入框输入 @ 会弹出项目文件列表，选中后把路径插进消息里：
看看 @internal/config.go 这个文件为什么不加载它只是插一段路径文本，不做别的事 —— 文件不会被自动读进上下文，agent 自己决定要不要读。
3.8 切换 agent
- 欢迎页：输入框里用
/agents或点 agent 选择器，下次新建的会话用它。 - 已有会话：
/agents会把当前会话的根 agent换掉。
每个声明了的 agent 都能当会话的 agent —— 没有「主 agent」那套推导。 会话选了谁，就以谁为第 0 层展开它自己的
subagents:。
3.9 技能（skills）
技能是放在 .heron/skills/<名字>/SKILL.md 的一组指令，用 /skill <名字> <任务> 调用：
---
name: refactor
description: 重构既有代码
---
保持行为不变的最小改动重构。- 只写
/skill（不带名字）会打开技能选择器，选一个会回填成/skill <名字>， 你再补一句任务 —— 选中不会直接发送。 - 名字写错（比如
/skill refactor但没有这个技能）也会打开选择器并用它过滤， 而不是报「命令不存在」。 - 技能实际由模型自己的
skill工具执行，服务端展开命令时只是把 「用这个技能做这件事」的话转达给模型。
description 决定模型会不会主动选它 —— 写清楚「什么时候该用我」。
技能只扫一级子目录，嵌套更深的会被忽略。
3.10 设置（配置编辑器）
侧栏底部的 Settings，或快捷键 ⌘, / Ctrl+,。
它操作的是「某一级的一个文件」，不是合并后的配置 —— 这样才不会把
${OPENAI_API_KEY} 展开成明文写回仓库。
| 能做 | 不能做 |
|---|---|
增删改 llm/ agents/ policy/ kb/ 下的配置文件 |
编辑 server/（只读 + 标注「需重启」） |
| 保存前试合并校验，明文密钥一律拒绝 | 编辑 skills/（目录结构，不在编辑器范围） |
两个要知道的细节：
- 被项目级遮蔽：如果你改的是用户级文件，而项目级有同名文件，界面会提前提示 「此文件被项目级覆盖，保存不生效」，并给出跳转入口 —— 因为同名文件是整体替换。
- 保存不等于生效：保存只做校验 + 原子写，生效由热更新 watcher 负责。
server/下的改动永远需要重启。