ARTICLE / 开源项目
补充版本更新引导循环特性的研究
PR 地址：NousResearch/hermes-agent#81580 · 更新后的 What’s New 循环：发现 → 理解 → 确认
研究摘要
Hermes 每个版本携带约 3,650 个 commit 和 58,000 字符的发布说明，但这些内容搁置在 GitHub 上，产品内部没有任何机制告诉用户"这个版本改了什么、什么时候该用、怎么用"。用户更新完就完事，新特性靠社区口耳相传才能被发掘。本 PR 补齐"发现 → 理解 → 确认"的闭环（+886/-1，7 个文件）：更新成功后（以及首次运行时）自动展示当前版本的结构化简报，提供 /whats-new 斜杠命令主动查看，并用确认状态（seen-state）记住用户已读，确认过的版本不再打扰。
设计上刻意避开同类历史 PR 的失败模式：简报展示只是成功更新的副作用，绝不是更新流程的门槛；不耦合更新状态机、不改 /update 行为、不用 LLM 生成简报（防幻觉）、不加子进程与 shell 调用。自测 29 + 81 + 28 + 49 个测试全部通过，ruff 干净。
一、问题背景：发布内容与产品之间的断层
1.1 信息在，通道没有
每个 release 都有详尽的发布说明，数据量不小（约 3,650 commit、58,000 字符），但通道是单向的：内容发布在 GitHub，用户更新 Hermes 时不会路过 GitHub。产品内没有"版本变更"的呈现面，用户对"更新后我能做什么"一无所知。
1.2 社区反复要求的未竟之事
社区对版本变更可见性的诉求由来已久，仓库里躺着多个只做了"展示"这一小块的尝试：
- 桌面端更新变更日志屏幕（#57731，打开中）；
/update升级前展示变更日志（#13588，打开中）；- 变更日志驱动更新的 PR（#13684，打开中、有冲突、
salvageability=low，被打上消息投递、兼容性、Windows 平台三类风险标签）； - 桌面端启动变更日志（#48284，打开中）。
这些尝试的共同问题是只覆盖"展示"切片，且 #13684 的失败教训尤其值得研究：把展示与更新状态机耦合——更新流程被展示逻辑拖累，一旦展示出问题就波及更新本身。本 PR 在继承"变更可见"这一意图的同时，明确绕开了这条失败路径。
二、特性设计：版本简报文件 + 加载器 + 斜杠命令 + 更新后通知
2.1 结构化版本简报：人类可写、可 diff、无数据库
新增 docs/whats-new/<version>.md 约定：每个版本一份结构化简报，frontmatter 加特性条目，每条特性带四个字段——一句话说明（one-line）、何时使用（use-when）、怎么用（how）、相关资源（related）。简报是人类手写的纯文档：可读、可 git diff、无需数据库 schema，版本演进自然留在 git 历史里。
2.2 加载器与确认状态：离线安全、损坏不藏新
hermes_cli/whats_new.py 实现加载器与确认状态管理，几个关键设计：
- 离线优先：正常路径直接读仓库内的简报文件；GitHub release body 只是兜底，且带 3 秒超时与 50KB 上限，网络不可用绝不阻塞；
- 原子确认状态：seen 状态用
os.replace原子写，写一半的损坏文件按"什么都没看过"处理——损坏的确认状态永远不会掩盖新特性； - 遍历安全：版本号用
^\d+\.\d+\.\d+$严格校验，简报文件路径不接受任意字符串拼接。
2.3 /whats-new 斜杠命令：CLI / 网关 / TUI 三端一致
命令通过注册表持有的执行器模式在 CLI、网关与 TUI 三端注册：无参数显示当前版本简报并自动确认；带版本号显示指定版本简报；--seen 手动标记当前版本已确认。网关端 Slack 通过 /hermes whats-new 路由（受 50 斜杠命令上限约束）。
2.4 更新后通知：两个更新路径、同一个静默原则
git 与 zip 两条更新路径都接入更新完成后的简报通知，模式与既有 curator 通知一致。三个"永不"：永不抛错（每次通知调用都被包裹）、永不阻塞（展示是更新的副作用，不是前置条件）、永不重复打扰（已确认或无简报时静默）。
2.5 面向的用户分层
- 新用户：首次运行看到本版本简报，完成第一轮产品认知；
- 存量用户：每次更新看到一次简报，然后安静直到下个版本；
- 管理员/进阶用户：
whats_new.enabled: false彻底关闭。
三、实测结果
3.1 测试套件
| 测试组 | 结果 |
|---|---|
tests/hermes_cli/test_whats_new.py（加载、确认状态、命令、边界） | 29 passed |
tests/hermes_cli/test_commands.py + test_commands_execute.py | 81 passed |
tests/hermes_cli/test_cmd_update.py + test_update_check.py | 28 passed |
tests/agent/test_turn_context.py + test_system_prompt.py | 49 passed |
| ruff check | 全部干净（PLW1514 已遵守） |
测试矩阵覆盖了设计承诺的关键不变量：默认配置即安全基线、绕过与边界场景验证、无网络正常路径、原子写入、遍历防护、无子进程假设的 Windows CI。
四、平台兼容性与能力边界
| 平台 | 支持 |
|---|---|
| macOS | 全支持（本机测试） |
| Linux | 全支持（纯标准库） |
| Windows | 全支持（无子进程、无信号、无 shell，所有打开操作带编码声明） |
| Docker | 简报文件随镜像存在，GitHub 兜底优雅跳过 |
| 网关（飞书/Telegram/Discord/Slack 等） | /whats-new 走共享执行器；Slack 经 /hermes whats-new 路由 |
能力边界与已知约束：
- 无简报文件即无通知：安装版本没有对应
docs/whats-new/<version>.md时加载器按设计保持沉默，需要/whats-new手动检查； - 确认状态不跨设备同步：seen 状态是本地文件，多设备各自确认（PR 明确把跨设备同步推迟给联邦工作）；
- v1 不生成简报：简报靠人工编写，覆盖度取决于维护节奏；LLM 起草 + 人工审查被列为 v2 方向，明确拒绝无审查的自动生成（幻觉风险）；
- 桌面 GUI 缺席：本 PR 不包含桌面图形界面，桌面端是下一阶段消费同一加载器的候选面；
- PR 状态为 open，自测数据为开发记录，尚未合入主线。
五、PR 信息
- PR 地址：https://github.com/NousResearch/hermes-agent/pull/81580
- 改动规模：+886 / -1，7 个文件
- PR 状态：open
- 提交时间：2026-08-08
本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。