https://blog.kalend.top/tags/%E5%8D%87%E7%BA%A7%E6%8C%87%E5%8D%97/Recent content in 升级指南 on Kalend's BlogHugo -- gohugo.iozhFri, 29 May 2026 10:00:00 +0800https://blog.kalend.top/2026/05/29/hermes-v0.15.1-upgrade-guide.html/Fri, 29 May 2026 10:00:00 +0800https://blog.kalend.top/2026/05/29/hermes-v0.15.1-upgrade-guide.html/ <blockquote> <p>2026年5月，Hermes Agent 两周内连发三版：v0.14.0 → v0.15.0 → v0.15.1。第三版是隔天紧急修复——Dashboard 无限重载，新装用户直接无法使用。</p> </blockquote> <h2 id="先说结论">先说结论 </h2><p><strong>所有用户直接升级到 v0.15.1。</strong> 不用停在 v0.15.0，它的 Dashboard 有 P0 级缺陷。</p> <p>一张表看全貌：</p> <table> <thead> <tr> <th>版本</th> <th>日期</th> <th>代号</th> <th>一句话定位</th> </tr> </thead> <tbody> <tr> <td>v0.14.0</td> <td>5.16</td> <td>Foundation</td> <td>全平台基础版本</td> </tr> <tr> <td>v0.15.0</td> <td>5.28</td> <td>Velocity</td> <td>1302 commits 大重构</td> </tr> <tr> <td>v0.15.1</td> <td>5.29</td> <td>Hotfix</td> <td>隔天紧急修复</td> </tr> </tbody> </table> <h2 id="v0140--v0150大版本跳跃">v0.14.0 → v0.15.0：大版本跳跃 </h2><p>这不是小更新。v0.15.0 是 Hermes 历史上最大的单版本变更——747 个 PR、1302 个 commit、321 位贡献者。</p> <h3 id="核心代码大瘦身">核心代码大瘦身 </h3><p><code>run_agent.py</code> 从 <strong>16,000 行</strong>重构到 <strong>3,800 行</strong>，缩减 76%。不是删功能，是把职责拆分到独立模块。</p> <p><strong>性能实测数据：</strong></p> <table> <thead> <tr> <th>指标</th> <th>变化</th> </tr> </thead> <tbody> <tr> <td>每轮工具调用</td> <td>-195ms</td> </tr> <tr> <td>每轮函数调用</td> <td>-240ms（-47%）</td> </tr> </tbody> </table> <h3 id="session_search-重写4500x-提速">session_search 重写：4500x 提速 </h3><p>会话搜索引擎从 LLM 驱动改为纯 FTS5 实现。搜索速度快了 <strong>4500 倍</strong>，而且不再消耗 token。</p> <h3 id="kanban-演进为多-agent-平台">Kanban 演进为多 Agent 平台 </h3><p>Kanban 模块经过 <strong>104 个 PR</strong> 打磨，从任务看板变成了多 Agent 协作平台。支持任务分解、子 Agent 分发、跨 Agent 依赖管理。</p> <h3 id="安全防护promptware-defense">安全防护：Promptware Defense </h3><p>新增 promptware 防御机制，防止恶意提示词注入攻击 Agent 系统提示。</p> <h3 id="新集成">新集成 </h3><ul> <li><strong>Bitwarden Secrets Manager</strong>：密钥管理集成</li> <li><strong>Krea 2 + FAL 插件</strong>：两个新图像生成提供商</li> <li><strong>Nous 官方 MCP 目录</strong>：审核过的 MCP 服务目录</li> <li><strong>ntfy 平台</strong>：第 23 个消息平台</li> <li><strong>mTLS 支持</strong>：MCP 连接支持 TLS 客户端证书</li> </ul> <h3 id="breaking-changes">Breaking Changes </h3><table> <thead> <tr> <th>变更</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>API_SERVER_KEY</code> 强制</td> <td>API Server 现在强制要求 Key，无 Key 不再允许请求</td> </tr> <tr> <td><code>web_crawl</code> 移除</td> <td>该工具及相关 provider 已被移除</td> </tr> <tr> <td>context engine</td> <td>新增外部上下文引擎接口，需配合新配置</td> </tr> </tbody> </table> <h2 id="v0150--v0151为什么隔天就发补丁">v0.15.0 → v0.15.1：为什么隔天就发补丁 </h2><p>v0.15.0 发布后隔天社区报告了多个阻断性问题。</p> <h3 id="-dashboard-无限重载循环p0">🔴 Dashboard 无限重载循环（P0） </h3><p><strong>这是 v0.15.1 存在的唯一理由。</strong></p> <p>在 loopback 模式下（Docker 部署 / 托管环境 / 全新安装），Dashboard 的 SPA 在 token 过期后陷入死循环：401 → 重新登录 → 又 401 → 无限刷新。用户看到页面不停闪烁，完全无法使用。</p> <p>修复方式：<code>/api/auth/me</code> 返回 401 时不再触发整页重载，改为 SPA 内部处理 token 刷新。</p> <h3 id="-kanban-worker-sigterm-不终止">🔴 Kanban Worker SIGTERM 不终止 </h3><p>发送 SIGTERM 后进程没有正确终止，任务超时或手动取消时僵尸进程堆积。</p> <h3 id="-其他修复">🟡 其他修复 </h3><table> <thead> <tr> <th>问题</th> <th>影响</th> </tr> </thead> <tbody> <tr> <td><code>/model</code> 和模型选择器列表不统一</td> <td>CLI 和 gateway 显示不同模型列表</td> </tr> <tr> <td><code>/yolo</code> 模式未绕过 session</td> <td>yolo 模式实际没生效</td> </tr> <tr> <td>Skills 目录不完整</td> <td>858 → 19,932，只拉取了部分条目</td> </tr> <tr> <td><code>.md</code> 媒体投递被误拦截</td> <td>Gateway 把正常 Markdown 附件也拦了</td> </tr> <tr> <td>Web URL 被误脱敏</td> <td>URL 参数被错误替换</td> </tr> </tbody> </table> <h3 id="docker-安全加固">Docker 安全加固 </h3><ul> <li><code>--insecure</code> 标志必须通过环境变量<strong>显式启用</strong></li> <li>MCP bare command（<code>npx</code>/<code>npm</code>/<code>node</code>）明确解析到 <code>/usr/local/bin</code></li> <li>arm64 CI 缓存问题修复</li> </ul> <h2 id="升级指南">升级指南 </h2><h3 id="从-v0140-升级推荐">从 v0.14.0 升级（推荐） </h3><p>直接跳到 v0.15.1，不需要中间停 v0.15.0：</p> <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code><span class="lnt">1 </span><span class="lnt">2 </span><span class="lnt">3 </span><span class="lnt">4 </span><span class="lnt">5 </span><span class="lnt">6 </span><span class="lnt">7 </span></code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># 源码安装（推荐）</span> </span></span><span class="line"><span class="cl">git clone https://github.com/NousResearch/hermes-agent </span></span><span class="line"><span class="cl"><span class="nb">cd</span> hermes-agent </span></span><span class="line"><span class="cl">pip install -e . </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="c1"># 或 PyPI</span> </span></span><span class="line"><span class="cl">pip install --upgrade hermes-agent </span></span></code></pre></td></tr></table> </div> </div><h3 id="从-v0150-升级到-v0151必须">从 v0.15.0 升级到 v0.15.1（必须） </h3><p>v0.15.0 的 Dashboard 无限重载是影响所有新装和 Docker 用户的 P0 问题：</p> <div class="highlight"><div class="chroma"> <table class="lntable"><tr><td class="lntd"> <pre tabindex="0" class="chroma"><code><span class="lnt">1 </span></code></pre></td> <td class="lntd"> <pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">pip install --upgrade hermes-agent </span></span></code></pre></td></tr></table> </div> </div><h3 id="升级后检查清单">升级后检查清单 </h3><table> <thead> <tr> <th>检查项</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td>Gateway 重启</td> <td>升级后必须 <code>hermes gateway restart</code></td> </tr> <tr> <td><code>API_SERVER_KEY</code></td> <td>v0.15.0+ 强制要求，检查 <code>~/.hermes/.env</code></td> </tr> <tr> <td>Browser Use 配置</td> <td>需配置 <code>BEARER_TOKEN</code> 匹配 <code>API_SERVER_KEY</code></td> </tr> <tr> <td>Kanban 备份</td> <td>并发加固后更稳定，但建议备份 <code>~/.hermes/kanban.db</code></td> </tr> <tr> <td>Docker <code>--insecure</code></td> <td>必须显式设置环境变量</td> </tr> </tbody> </table> <h2 id="版本号背后的逻辑">版本号背后的逻辑 </h2><p>v0.15.1 不是计划内版本。大版本（v0.15.0）涉及 1300+ commits 变更，回归测试不可能覆盖所有部署环境。Dashboard 无限重载只在 loopback/Docker 场景触发，CI 没覆盖到。</p> <p>发现问题后团队在隔天内发布修复——这是健康开源项目的标准响应速度。</p> <p><strong>建议所有用户直接使用 v0.15.1。</strong></p> <section style="margin:20px 0;padding:16px 20px;background:linear-gradient(135deg,#4a90d9,#357abd);border-radius:8px;text-align:center;"> <p style="margin:0 0 8px 0;color:#fff;font-size:16px;font-weight:bold;line-height:1.6;">关注 varkm，一起学习，一起成长</p> <p style="margin:0;color:rgba(255,255,255,0.85);font-size:13px;line-height:1.6;">更多 AI Agent 实战经验和踩坑记录，持续更新中</p> </section>