v0.21.2

Hermes Agent v0.21.2

Overview

v0.21.2 — The state.db Patch Release（state.db 补丁版）。 发布于 2026 年 9 月 11 日。自 v0.21.1 以来 947 个非合并提交 · 1,869 个改动文件（+182,504 / −15,564）· 312 个已合并 PR · 140 位贡献者。

v0.21.0 重写了会话存储的连接处理，而这次重写让一部分安装的 state.db 变得脆弱：第二个写入者会互相取消锁，健康的数据库被判成损坏，一行坏数据就足以拖垮 sessions list。v0.21.2 系统性地关闭了这一整类问题——六个 PR 一共关闭 44 个 issue，从锁的所有权、WAL 恢复到读取路径与诊断逐层修补，让数据库要么正常工作、要么明确而具体地报错，绝不静默失败，也绝不把整轮对话一起带走。

在这条主线之外，v0.21.1 之后的四天还落下了成批的多 profile 隔离加固、桌面后端启动风暴的终结、一个 agent 全程看不到明文的凭据保险库、带 SHA 固定且经审核的插件索引与 Desktop 里统一的 Plugins 页面，以及 Nous 免费额度与引导式首次启动。本页按这个顺序展开。

Highlights

1. state.db 可靠性战役：六个 PR，关闭 44 个 issue

下面每一种失效形态都被复现、修好，并留下守卫，让它不会再悄悄回来。

  • 不再有第二个写入者。 profile gateway 曾每 5 秒把托管房间状态写进根 state.db；dashboard 启动时就打开一个可写句柄；cron 生命周期守卫对活着的库做裸 open()——足以取消 gateway 持有的 POSIX 锁；doctor --fix 会在仍存在活持有者的情况下执行 checkpoint。现在托管房间存进 shared-state.db，dashboard 先以只读方式打开，守卫改走受管连接注册表，doctor --fix 会拒绝任何无法证明安全的 checkpoint（#108076）。
  • 健康的 WAL 库不再卡死。 一批“库本身没问题却被判死”的形态被逐一修掉：OpenZFS 的 (deleted) dentry、close() 与 append_message 竞争、读池在未确认 journal 模式下发放连接、WSL2 上瞬时 disk I/O error 让 get_session 第一次就失败、锁已经释放却仍在广播“state.db locked”（#108082）。
  • 搜索索引损坏不再杀死整轮对话。 此前只影响全文索引的错误会被当成整文件损坏并 fail-closed。现在它被归类为 fts_index：搜索降级、索引稍后重建、对话记录原封不动。同一个 PR 里，doctor 会如实区分结构性损坏与索引损坏；FTS 写探针能抓到“所有检查都通过但每次写入都失败”的陈旧索引形态；.recover 不再因孤儿 FTS5 shadow 表而启动失败；头部被清零的数据库可以恢复；dashboard 分析轮询返回 503，而不是每天 52 万条 traceback（#108130）。
  • 一行坏数据不再拖垮 sessions list / export / insights。 TEXT 时间戳或 1e30 epoch 曾让整个列表崩溃，畸形 marker JSON 让 json_extract 崩溃，超过 999 个 id 让批量删除与 prune 崩溃。现在每个读取方都走 coerce_epoch()——坏行显示 ? 并给出一条带会话名的 WARNING——再加上 json_valid 守卫、IN 列表分块、批量导出水合（#108086）。
  • 会话不再绑定或读取别的 profile 的数据库。 Desktop 启动后端在 HERMES_HOME 覆盖竞态下可能钉到错误 profile 的 state.db；session_search 用裸 ID 会静默扫描所有 profile 并返回别人的对话；恢复指引指向了错误的文件；删除 profile 时句柄没有关闭（WinError 32）（#108074）。
  • 无需写入时不再获取写锁。 一次性 hermes 进程在忙碌 gateway 后面打开 state.db，曾要卡 4–20 秒然后报 “database is locked”，现在只需 0.01 秒（#108067）。

如果你的 state.db 已经被 0.21.0 / 0.21.1 弄坏，从这里开始：

hermes doctor
hermes sessions recover --inspect-only

2. 多 profile 隔离加固

v0.21.2 把 profile 之间的边界从约定变成了强制：次级 profile 的机器人不再继承默认 profile 的 allow-list（#107616）；适配器不再把凭据发往默认 profile 的主机（#107617）；stdio MCP 服务器不再收到默认 profile 的 vault 密钥（#107630）；MEDIA: 投递不能再带上另一个 profile 的 .env / auth.json / state.db（#107609）；飞书 drive 回调与 /p/<profile>/ webhook 回复留在被路由到的 profile 里（#107620、#107626）；次级 profile 也不再拿到兄弟 profile 的 Nous bearer（#107611）。

合起来就一句话：只要一个进程属于某个 profile，它就既拿不到另一个 profile 的文件和密钥，也不能顶着另一个 profile 的身份发请求。

3. 桌面后端启动风暴结束

Bot Mode 曾在启动时、以及每一次 roster tick 时，为每个 profile 生成或拨号一个后端；鼠标划过 Bots 名单就会为每一行生成后端；切换 profile 还可能生成重复的 primary。现在后端的创建与复用被收敛到明确的生命周期上，roster 渲染不再有副作用，切换 profile 得到的是同一个 primary 而不是新的副本（#108069、#108107、#108118、#108134、#107969、#108112）。对用户最直接的体感是：桌面端冷启动时不再同时出现风扇起飞和网关忙音。

4. 对密码不可见的凭据保险库

agent 现在可以从 1Password、Bitwarden 或本地 Hermes vault 登录、支付、填地址，而全程看不到密钥；两步验证码来自保存的认证器密钥，或在用户自己的 UI 里询问（#106480、#107585）。私有 git 插件也能用已保存的凭据安装（#106981）。换句话说，密钥从保险库直接流向目标站点或仓库，agent 只负责编排，只看到“完成 / 失败”，看不到明文。

5. 插件目录与统一的 Plugins 页面

插件现在有了带 SHA 固定、经审核的索引：CLI、准入 CI、文档与 dashboard 一并落地（#69446）。Desktop 新增一个 Plugins 页面，把 agent 插件与 desktop 插件放到同一处管理——安装、浏览目录、按 commit 固定都在这里完成（#107212、#107314、#107321）。Radio 作为可选 SDK 插件发布（#107072）。

6. Nous 免费额度与引导式首次启动

开箱即用的免费推理与连接器，一条命令即可登录（#105258、#105260），聊天里可以直接用 /login（#105261）；连接器工具（Gmail、Linear、Notion 等）可以通过 tool_search 搜到（#106842）；把 HERMES_GUEST_ONBOARDING=1 设上后，首次启动会变成引导式流程，新用户在第一次对话之前就把账号、连接器与模型配好（#107697、#107958、#107985、#108211）。

export HERMES_GUEST_ONBOARDING=1

Improvements

v0.21.2 是一个补丁版本：下面这些改动不构成头条，但同样属于“让 state.db 不再骗人”的那批配套工作。

  • 重建与发布顺序：新建 state.db 不再在取得重建锁之前发布 FTS 表（#106311）。
  • WAL 世代与退出：丢失 WAL 世代的句柄不再在退出时 checkpoint 陈旧帧（#106315、#106840）；无法验证的库在 WAL 初始化时保持不动（#106568）。
  • 隔离而不是破坏性打开：头部被覆盖的库连同它的 WAL 一起被隔离，而不是被破坏性地打开（#106587）；被隔离的句柄拒绝 VACUUM 与 FTS optimize（#106343、#106349）。

Fixes

  • Gateway 与平台：config.yaml 里裸 display: 键不再让每轮对话崩溃（#106305）；被平台拒绝的排队车道最终消息会被记录并重投（#106316）；卡住的 WebSocket 发送不再阻塞它之后的所有事件（#106581）；首轮不再等待 Python 工具链探测（#106556）；开启 bots_require_mention 后 Telegram 机器人必须被 @mention，打断机器互刷（#106534）；Matrix 渲染 LaTeX（#106515）；Signal 渲染 Markdown 表格（#106538）；WhatsApp 对阅后即焚消息的回复保留引用（#106541）；纯媒体回复在所有平台都报 SUCCESS（#106557）。
  • Provider 与路由：/model 与 auxiliary 自动路由不会账单你没选的 provider（#107366）；绝不自动切到没有凭据的 provider（#107281）；Bedrock Claude/Converse/Mantle 模型能挺过 /model、fallback 与恢复（#107621、#107658）；Bedrock Guardrails 生效（#107815）；Codex patch 预算图片 400 会缩图重试（#106525）；无权限的主 provider 加 fallback 不再振荡（#106549）；Azure Foundry 被拒的重放推理会被分类并裁剪（#106718）；MCP OAuth 刷新不再抹掉 refresh token（#106185）；Anthropic 客户端只发送一个凭据（#107978）；Nous Portal 与 OpenRouter 选择器加入 DeepSeek V4.1 Flash（#107489）；OpenAI 与 FAL 支持 GPT Image 2.5（#105988）；原生 Anthropic 选择器加入 Opus 5 / Fable 5.1（#106636）。
  • Agent 循环与压缩：一个被阻塞的周期回调不再拖住 lease 刷新（#106308）；轮次中的 /steer 存为独立 user 行（#106317、#106344）；本地推理的内存上限拒绝改为退避，而不是压缩历史（#106307）；部分流式之后发生上下文溢出会结束本轮（#106567）；长度续写在前文已填满窗口时停止（#106571）；压缩在 aux 重试时不再静默超时（#106866）；model_thresholds 的键可以按 provider 限定（#108061）；Desktop↔TUI 切换不再重建 system prompt，从而保住 prompt cache（#105844）；CLI 保留 api_content sidecar，早期持久化也能保住缓存（#105842）。
  • CLI、TUI 与 Desktop：hermes -z --resume 能继续会话（#106313）；扩展键终端支持 Shift+字母与 Cmd+Shift+Z（#90674、#105493）；browser_exec 超时会杀掉整个进程树（#106589）；更新检查改为每天轮询一次 GitHub API，而不是每 30 分钟跑一次 git fetch（#107648）；hermes update 会说明真实原因，也不会卡在 fetch 上（#108053）；Desktop 方面：UI 语言在更新重启后保留（#106476）、过期 OAuth 授权一键重登录（#106965）、HUD 模式恢复显示对话且总能交回窗口（#107491、#107423）、后端在 Desktop 父进程退出后退出（#107977）、Windows 更新不再误报失败（#106175、#107183）、WSLg 在 Windows GPU 上渲染（#106528）、从 dashboard 移植了 Telegram 二维码快速设置（#107242）。
  • Cron 与 Kanban：非整点的“立即运行”不再取消下一次计划运行（#106306）；被杀掉的手动运行不再阻塞下一次 5 分钟（#106733）；由一次性改为周期性的任务继续触发（#106532）；未固定模型的任务按创建时快照的模型运行（#106499）；--clone-all 不再复制 cron 任务（#106478）；kanban promote 拒绝未完成的父任务（#106550）；kanban_request_review 拒绝未知的 reviewer profile（#106547）。
  • 工具与记忆：stdio MCP 服务器在调用中途死亡不再重放工具调用（#106546）；只含技能的背景评审不再能删除记忆条目（#106310）；mem0 记忆不再丢长轮次（#106542）；tool_search 宁可返回空，也不返回五个只共享一个词的无关工具（#106676）；远端 NOPASSWD sudo 不再弹审批（#107939）；RSS 与 Reddit 读取不再默认启用（#105873）。
  • 家务：config.yaml 备份集中到一个有界的 backups/config/ 目录（#106388）；hermes backup 只保留最新 3 个 zip（#106455）；hermes setup --reset 会备份真实配置（#106453）；dpaste 兜底路径上的 debug share 保留期缩到 1 天（#106531）。

Upgrade

已有安装直接更新：

hermes update

全新安装：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

托管部署应通过其部署工具使用新 tag 更新。

如果 state.db 已经被 0.21.0 / 0.21.1 损坏：先跑 hermes doctor（现在会正确区分结构性损坏与索引损坏），当重建不够时它会指向 hermes sessions recover --inspect-only（带 profile 限定）。

完整的变更对比见 v2026.9.7…v2026.9.11。

← Hermes Agent Changelog