功能介绍

Steam 页面

插件安装并配置完成后，访问 /steam 即可查看内置 Steam 信息页面。页面数据主要由后台定时预热，访问时读取缓存，因此日常打开不需要等待 Steam API 实时响应。

页面包含：

• 用户资料卡片：头像、昵称、在线状态、Steam 等级、上次在线时间
• 统计数据：游戏总数、总游玩时长、最近两周游玩时长
• 热力图：可视化展示每日游戏投入，需启用时长追踪
• 最近游玩：最近两周游玩的游戏，可选显示成就进度和库外标识
• 游戏库：分页浏览、按游玩时长或名称排序，可隐藏指定游戏并限制显示数量

游戏库

游戏库来自 Steam IPlayerService/GetOwnedGames，并通过 IStoreBrowseService/GetItems 批量补全本地化名称和真实封面。

• 支持分页浏览，每页数量可配置；REST API 最大 size 为 100
• 默认按总游玩时长排序，也可按名称排序
• 支持隐藏指定 AppID
• 支持是否包含免费游戏
• 可设置游戏库总显示数量，设为 0 表示不限制

封面与不可用标识

新游戏封面位于带内容哈希的 store_item_assets 路径，不能再靠 AppID 拼接 header.jpg。插件会通过 GetItems 获取真实封面，并在配置了「游戏图片加速域名」时只替换图片 URL 的域名部分。

delisted=true 只在 GetItems 明确返回 visible=false 时设置，表示当前地区或状态下商店不可见，页面会显示「不可用」徽章并使用占位图。GetItems 没有返回某个 AppID 只表示本次未覆盖到它，不会被判定为不可用。

最近游玩

最近游玩来自 Steam IPlayerService/GetRecentlyPlayedGames，同样会用 GetItems 补全真实封面和本地化名称。

最近游玩条目包含：

• 游戏封面、名称、图标
• 最近两周游玩时长
• 总游玩时长
• 商店不可见标识 delisted
• 是否在当前游戏库缓存中 inLibrary
• 可选成就进度

成就进度

开启「显示最近游玩成就进度」后，后台刷新最近游玩缓存时会为每个最近游玩的游戏额外请求成就 API，并把结果随最近游玩列表一起缓存。页面命中缓存时不会再逐个游戏实时请求成就 API。

• 显示格式：已完成/总数
• 隐私设置导致成就不可用时显示锁定状态
• 游戏没有成就系统时不显示成就内容
• 开启后会增加后台预热耗时和 Steam API 调用量，最近游玩较多时建议适当调大「活跃信息刷新间隔」

徽章系统

徽章信息来自 Steam IPlayerService/GetBadges。

• 游戏徽章默认显示游戏图标样式
• 系统徽章、活动徽章可在「徽章配置」中按 Badge ID 映射自定义图片和名称
• 页面会显示玩家等级、经验值、升级所需经验和等级进度

热力图

热力图通过插件自定义资源记录每日游戏时长变化。

• 定时任务每小时第 59 分钟追踪一次游戏时长
• 可手动触发一次追踪用于测试
• 支持 4 种颜色主题：Steam 蓝色、GitHub 绿色、火焰橙色、紫色梦幻
• 可配置显示天数、图例和数据保留天数

Steam API 不提供历史每日数据，热力图只能从启用时长追踪后开始记录。首次启用后通常需要等待至少 1 小时产生第一个数据点。

富文本游戏卡片

插件为 Halo 富文本编辑器提供 Steam 游戏卡片扩展。输入 AppID 或 Steam 商店链接后，会调用 /game-detail/{appId} 获取详情并渲染卡片。

游戏卡片可显示：

• 游戏封面、名称、简介
• 开发商、发行商、类型标签
• 价格、发行日期、商店链接
• 是否拥有该游戏
• 拥有时的总游玩时长、最后游玩日期和成就进度

游戏卡片详情使用 Steam Store /api/appdetails，不是列表用的 GetItems。二者职责不同：GetItems 用于批量补全列表名称和封面，appdetails 用于获取详情字段。

当某个 AppID 在商店取不到详情（appdetails 返回 success:false）时，卡片会用 GetItems 的 visible=false 二次确认：确认不可见则显示「该游戏不可用（已下架、区域限制或 ID 无效）」提示（保留商店链接、不显示重试）；若只是临时取不到（如接口限流），仍按「加载失败」处理并可重试。

多语言与图片加速

「游戏显示语言」作用于页面列表和编辑器游戏卡片：

• 自动模式下，页面列表按 Halo 后台首选语言；游戏卡片按访客浏览器语言
• 指定语言时，所有场景都使用该语言

图片加速通过「游戏图片加速域名」统一处理封面、图标和头像，只替换域名，保留 Steam 原始路径。图标仍使用 iconImageTemplate 拼接；封面来自 GetItems 或 appdetails 返回的真实地址。

数据缓存

页面列表数据依赖后台预热刷新：

页面列表读取 getStale 缓存，即使缓存按 TTL 已过期，也会继续返回旧数据作为失败兜底；真正的新鲜度由活跃信息/库藏信息刷新间隔控制。按需游戏详情使用「缓存过期时间」控制。

点击「刷新缓存」会清空缓存并在后台触发一次预热。刚刷新后的短时间内，页面可能暂无数据，等待预热完成即可恢复。

代理支持

如果服务器无法直连 Steam，可以配置：

• HTTP 代理：用于访问 Steam API 和 Store API
• 自定义 API 地址：替换 api.steampowered.com / Store 相关路径的代理入口
• 游戏图片加速域名：用于加速封面、图标、头像等图片资源

自定义 API 代理需透传 Steam API 路径和查询参数，并同时支持 api.steampowered.com 的 Web API 路径与 store.steampowered.com/api/appdetails。