UI version display

UI version display 指产品有意识地把“当前运行的到底是哪一版”暴露给用户或操作者查看，而不是把版本号藏在构建日志或开发者工具里。它通常包含一个稳定的人类可读显示位点，以及一条由运行时或构建链提供的版本真相路径，用于支持排障、远程协作和发布确认（projects/codex-vibe-monitor.md、projects/dockrev.md、projects/display-ambient-light-desktop.md、projects/loadlynx.md）。

这个 Topic 的重点不在“页面角落多了一串文字”，而在于 UI、后端、构建链和 release 语义之间是否真的对齐。若版本显示是假的、过期的或只来自前端 bundle 自报，那它就没有达到本 Topic 的维护价值。

当项目明确在 Web UI、桌面 UI、About 页、设置页、页脚或控制台中显示版本信息，并且改动会影响版本来源、展示位置、构建注入、后端版本 API、release 值传递或 support/debug 流程时使用。尤其在 self-hosted 服务、桌面应用和设备 UI 中，这个 Topic 常常直接关系到“用户到底跑的是哪个构建”。

如果只是开发阶段临时打印版本、测试页偶尔露出 hash，或版本信息与正式运行无关，不应提升到本 Topic。这里关心的是稳定可依赖的运营/排障语义。

在 style playbook 里，UI version display 的默认做法不是只记录“用了什么技术”，而是记录维护者真正需要反复执行的约束、验证和组合方式。现有样本反复出现以下习惯：

• UI always has a place to read the version without devtools (About window / Settings / footer) (projects/display-ambient-light-desktop.md)
• Backend exposes a stable API endpoint for version info, so “UI version” is not coupled to the UI build toolchain (projects/dockrev.md, projects/codex-vibe-monitor.md, projects/display-ambient-light-desktop.md)
• “Effective version” is computed once in CI and propagated via a single env var (commonly APP_EFFECTIVE_VERSION), with safe fallbacks like CARGO_PKG_VERSION / package.json version (projects/dockrev.md, projects/codex-vibe-monitor.md, projects/loadlynx.md)
• UI version can include build metadata that helps support: dev vs release flag, git SHA/tag, build time (projects/display-ambient-light-desktop.md, projects/loadlynx.md)
• 对 PR-local VERSION 发布链路，开发 identity 应从同一 VERSION 派生 nextPatch(VERSION)-dev.<short-sha>，release identity 读取文件精确文本；UI、CLI、/health、bundle 与 manifest 共同消费该 resolver，而不是从 package metadata 或最新 tag 各自猜测（projects/flux-purr.md、topics/pr-label-release.md）。
• 版本真相应尽量从单一来源产生，再向 UI 分发。常见做法是 CI 先计算 APP_EFFECTIVE_VERSION，后端和前端都消费同一个值；这样用户看到的版本、容器标签、构建产物与日志语义才能对上。
• 对 Web / Pages / desktop hybrid surface，优先把 effective version 在 CI 或 release pipeline 里只算一次，然后原样注入 UI。不要让前端再补 v、去 v、截断 metadata 或按环境二次拼接；UI 应展示 raw effective version，而不是自创一套格式化规则。
• mainline/default surface 与 release-tag surface 可以故意显示不同语义，但必须在 contract 里写明，并都来自同一条 effective-version 注入链。常见做法是 owner-facing main / preview surface 显示 main+<shortsha> 或等价 mainline build id，tag/release build 显示完整 tag；区别应来自 CI 选择值，不应由 UI 组件自己猜。
• UI 最好提供一个不依赖开发者工具的查看位置，例如 About、设置页或控制台页脚。对 operator surface 来说，这不是装饰，而是排障入口：用户反馈问题时，先确认版本比先猜环境更高效。
• 对前后端一体项目，优先让运行时或后端暴露版本，再由 UI 消费，而不是让前端单独从 package.json 读一个可能与真实部署脱节的值。projects/dockrev.md、projects/codex-vibe-monitor.md、projects/display-ambient-light-desktop.md 都体现了这种思路。
• 版本信息最好包含足够的诊断语义，例如 release tag、git SHA、dev/release 形态、构建时间或 artifact variant，但不要把它做成难以阅读的原始元数据倾倒。
• 验证时不仅要看“有没有显示”，还要看显示值是否真的从当前运行产物来、release 之后是否自动更新、开发模式和正式模式是否有安全 fallback。这些才是 Topic 的长期维护重点。

• projects/codex-vibe-monitor.md：代表 self-hosted 服务如何通过构建脚本和运行时把 effective version 送到 dashboard，适合说明版本显示为何是运维支持面的一部分。
• projects/dockrev.md：代表 operator console 场景。这里的版本显示直接影响 self-hosted 用户判断自己部署的是哪一版，也影响发布和排障对话。
• projects/display-ambient-light-desktop.md：代表桌面应用场景，说明 About UI 与原生 info/version path 的搭配能把桌面产物和展示层对齐。
• projects/loadlynx.md：代表设备/本地 UI 也需要版本可见性，特别是在 Web demo、设备页面和 release 流程并存时，版本号是识别 firmware/web 组合态的重要线索。
• projects/flux-purr.md：代表多语言设备产品从一个 checked-in VERSION 同时产生开发显示、release build-info、CLI、/health、bundle 和 manifest identity。
• skills/style-ui-version-display/SKILL.md：group Skill 强调消费时应核对版本来源、展示位点和 release 传递路径，而不是只说“页面上有版本号”。

• UI 上展示的版本如果来自错误来源，反而比不显示更糟，因为它会误导排障与发布判断。
• 把版本值分别在前端、后端、Dockerfile、CI 中各算一遍，是最常见的漂移根源；最后用户看到的值与实际运行 artifact 往往对不上。
• 只在 release build 有版本、dev build 什么都不显示，会让日常联调和 issue 反馈失去最基本的上下文。
• 把本 Topic 当成单纯视觉细节，不验证版本 API、构建注入和 release 传递链，就会出现“UI 有占位，实际没有真相”的假完成。
• UI 组件对版本值强行加前缀、去前缀或覆盖 metadata，会把 CI 已经算好的 effective version 再次篡改；结果常见表现就是 main+<sha>、v1.2.3-preview.4、desktop build id 等真实值在页面上被错误归一化。
• 没有把 mainline/default surface 和 release-tag surface 的显示语义分开写清时，默认站点很容易错误显示“最新 release tag”而不是当前 main build，或反过来让正式 release 仍显示开发态 hash。
• 开发显示若通过改写源文件来获得版本，会把日常构建污染成发布状态。PR-local VERSION 发布链路必须保持文件只读，并将 short SHA 限定为开发 qualifier（topics/pr-label-release.md）。

• projects/codex-vibe-monitor.md
• projects/display-ambient-light-desktop.md
• projects/dockrev.md
• projects/loadlynx.md
• projects/flux-purr.md
• topics/pr-label-release.md
• skills/style-ui-version-display/SKILL.md
• skills/style-playbook/references/data/topics/ui-version-display.json