AIRI v0.7 开发日志深度解析：Windows 全平台支持、Fade on hover 交互、本地 ASR/STT 与构建工程化升级-港品优选

AIRI v0.7 开发日志深度解析：Windows 全平台支持、Fade on hover 交互、本地 ASR/STT 与构建工程化升级

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

AIRI（Tamagotchi 桌面陪伴应用、Web/Mobile Web 版本所在的 monorepo）在 v0.7 中完成了从"实验性原型"到"可日常陪伴的全平台桌面应用"的关键跨越：补齐 Windows 兼容性、引入 Fade on hover 窗口交互范式、落地本地 ASR/STT 引擎，并在工程侧用 buildless + tsdown + rolldown-vite + turborepo 把构建时间从 4 分钟压到 25 秒。本文以官方 DevLog（docs/content/en/blog/DevLog-2025.08.05/index.md）为骨架，结合仓库源码与测试，逐项拆解这些能力的动机、实现原理与使用方式。

v0.7 发布概况：一次迟到的、影响深远的大版本

v0.7 原定于 2025 年 7 月初发布，但由于在 Windows 上发现了多个关键 bug、以及本次改动范围远超预期，最终推迟到 8 月初才正式放出。从版本对比看，这次迭代的体量相当可观：

391 commits（对比 v0.6.1 → v0.7.0）
1017 files changed
74,548 lines added
13,930 lines removed

作者也坦诚这些数字对软件行业从业者而言并不代表什么，只是说明这一版本影响面很大。与 v0.7 同期达成的里程碑包括：GitHub 1850+ stars、40+ contributors、300+ Discord 成员，并在 2025 年 7 月 17 日登上 GitHub Trending 榜首（以上数字为 DevLog 发布时作者自述，非仓库代码可验证数据）。

Desktop（Tamagotchi）：从实验品到常驻桌面伴侣

Tamagotchi 是 AIRI 桌面版的代号——一个独立运行的、常驻桌面的 AI 陪伴窗口。v0.6 及更早版本中，桌面端 UI/UX 尚不精致，本地 ASR/STT 不可用，音频输入设备设置缺失。v0.7 对这些问题做了系统性补齐，其中最核心的是围绕"透明置顶窗口如何与普通应用共存"的一整套交互设计。

Fade on hover™：解决"常驻伴侣"与"阻挡鼠标"的根本矛盾

如果你把 AIRI 当作 VTuber 应用来用（类似 VTuber Studio、Warudo 对接 OBS 串流），模型窗口永远在底层、由采集驱动捕获，窗口层级由 OBS 的场景编排决定，自然没有遮挡问题。但一旦你想让模型作为虚拟伴侣常驻在桌面上，就会立刻撞上两个痛点：

窗口置顶会阻挡下方应用的鼠标事件；
手动切换窗口可见性在专注工作时非常打断心流。

Fade on hover 的思路很直接：当鼠标悬停在 AIRI 窗口上时，整个角色淡出，并把鼠标点击事件透传给下层应用。这样角色可以随时"陪在你身边"，却不干扰你操作任何应用。

默认快捷键：Shift+Alt+I（作者戏称该功能为 "Fade on hover™"，但项目以 MIT 协议开源，并未注册任何商标）。

源码级原理：采样透明 + 指针穿透的协同

核心交互决策实现在 apps/stage-tamagotchi/src/renderer/utils/fade-on-hover.ts 的resolveFadeOnHoverInteraction中，它接收四个输入：

cursorInsideWindow：鼠标是否在窗口内；
enabled：Fade on hover 是否开启；
transparentForFade：淡出检测所用的采样区域是否已透明；
transparentForPointer：原生指针命中测试所在像素是否透明。

const fadeStage = params.enabled && params.cursorInsideWindow && !params.transparentForFade return { fadeStage, ignoreMouseEvents: params.enabled && (fadeStage || params.transparentForPointer), }

源码注释揭示了两个关键设计决策：

淡出检测使用采样区域而非精确像素——避免角色边缘抖动导致频繁闪烁；而原生指针命中测试用精确像素，保证可见的模型像素仍可交互；
一旦整个舞台淡出，命中测试报告的"不透明像素"可能仍是已不可见的模型，因此淡出判定必须同时启用点击穿透（click-through），守住"不可见的舞台内容不能阻挡下方应用"的契约。

配套的单元测试 fade-on-hover.test.ts 覆盖了三条核心场景：可见模型淡出时指针透传、未淡出的透明舞台保持点击穿透、关闭 Auto Hide 后舞台完全可交互。

何时采样透明度：仅限 VRM 且已挂载

透明度采样并不是无时无刻都在进行的。apps/stage-tamagotchi/src/renderer/utils/stage-three-transparency.ts 中的shouldSampleStageTransparency要求四个条件同时满足才采样：Fade on hover 已开启、舞台未暂停（stagePaused === false）、组件状态为mounted、且渲染器为vrm。对应测试见 stage-window-lifecycle.test.ts，它验证了loading状态、live2d渲染器、暂停状态都不会触发采样，从实现层面解释了"采样是精确且节制的"。

状态持久化与引导通知

用户偏好通过 Pinia store 持久化到 localStorage：controls-island.ts 中fadeOnHoverEnabled使用useLocalStorage('controls-island/fade-on-hover-enabled', false)默认关闭，另有dontShowItAgainNoticeFadeOnHover记录"不再显示引导提示"。首次开启时，桌面端会弹出独立的引导窗口 notice/fade-on-hover.vue，内置深浅两套教程视频，并提供"不再显示"复选框与 Confirm 按钮。

在 Controls Island（桌面端悬浮控制面板）中，controls-island/index.vue 通过<ControlsIslandFadeOnHover />提供了一个一键开关按钮，与设置页、全局快捷键三处入口互通。

Move：移动模式

Fade on hover 让鼠标事件透传后，你仍需要把模型窗口摆到合适的位置（右下角、底部居中……）。v0.7 优化了拖拽区域的外观——圆角设计以匹配整体主题。

默认快捷键：Shift+Alt+N
进入移动模式后会出现可拖拽区域，除鼠标拖拽外，还可以用系统托盘菜单中的Position > Center / Bottom Left / Bottom Right快速定位窗口。

Resize：缩放模式

不同角色的模型尺寸各异，窗口缩放能力同样关键。与 Move 模式一致，缩放边框指示器应用了圆角；角色边缘也被裁剪出圆角效果。

默认快捷键：Shift+Alt+R

桌面端这些快捷键背后是全局快捷键服务。从实现看，主进程通过 global-shortcut-uiohook.test.ts 所测试的 uiohook 驱动监听 OS 级键盘事件，并会抑制系统自动重复（auto-repeat）、精确匹配修饰键组合；快捷键 accelerator 结构（如cmd-or-ctrl/alt/shift修饰符 + key）定义在 global.ts 的shortcutAcceleratorSchema中，设置页对应入口见 window-shortcuts.vue。

Resource Island：下载进度的可视化

加载 ASR/STT 与 VAD 模型需要下载大量文件，等待过程必须可视化。借鉴 iOS Dynamic Island 的交互，v0.7 设计了一套名为Resource Island的悬浮组件：

浮动、可悬停的 widget，展示各模块及所需文件的下载/安装进度；
下载完成后自动消失；
每个模块项内嵌链接，点击可跳转到对应模块的设置页，了解该模型/文件为什么是必需的。

本地 ASR/STT：从 candle 到 ONNX Runtime 的务实迁移

桌面端此前本地语音转文字不可用，v0.7 借助社区实验仓库 candle-examples 的经验，实现了在 Windows、macOS、Linux 三平台均可工作的本地 ASR/STT 引擎。

技术选型上经历了重要调整：最初尝试直接使用 huggingface/candle 推理引擎，但无法为 Windows 与 Linux 构建找到干净利落地嵌入 candle 运行时（含/不含 CUDA）的方案，于是切换到ort（ONNX Runtime for Rust）——在保持相近性能与精度的同时，兼容性更好、接入更简单。

在设置页的 Hearing（听觉）配置中，你可以选择音频输入设备，并自由切换 ASR/STT 提供方：既可使用 OpenAI 的云端语音服务，也可切换到本地 provider 实现完全离线的语音识别（DevLog 中的演示视频默认使用 OpenAI 服务，但切换本地 provider 是可行的）。

Web：引导页与更精准的 VRM 渲染

Onboarding 引导页

AIRI 的配置项较多（相比需要理解代码结构才能配置的纯 Python 方案仍然简单），为了让新用户第一次上手更顺畅，v0.7 为 Web 版本加入了完整的 onboarding 引导页。

VRM：更精确的相机与渲染

感谢社区贡献者 Lilia-Chen 的持续工作，v0.7 中 VRM 模型以更精确的相机实现与渲染机制呈现：

从仓库结构看，VRM 能力由 packages/stage-ui-three（three.js 渲染）、packages/stage-ui-live2d（Live2D）以及桌面端透明度采样逻辑共同支撑；DevLog 中明确提到透明度采样目前仅对 VRM 渲染器启用，正是为了保证"渲染精确"与"命中精确"能同时成立。

Mobile Web：Onboarding 与主场景重构

Onboarding

移动端同样获得了 onboarding 引导，首次使用体验与 Web 版对齐。

Scene：主场景重设计与 Live2D 偏移微调

移动端主场景被完全重写。得益于 LemonNekoGH 的贡献，现在可以更直观地调整场景中 Live2D 模型的偏移（Offset）。设计灵感来自 iOS 侧边音量控制，期望让用户更快上手：

提供 X、Y、Scale 的调节按钮；
双击 X、Y 或 Scale 按钮即可重置为默认值。

双端共享：一批新的 UI 组件

v0.7 为 Web 与桌面双端补充了大量可复用组件：

更好的文本动画：聊天气泡的文本动画全面改进（由 sumimakito 实现，并在 DevLog 2025.08.01 中详细解释了其特殊实现动机与 i18n 兼容性考量）；
Level meter：用于展示音频输入检测电平或实时系统负载的可视化组件；

Time series chart：与 Level meter 类似面向变化值，但更适合历史数据可视化；
其他新增组件：<Progress />、<FieldSelect />、<Alert />、<ErrorContainer />、新的侧边栏导航设计、Toaster 通知、以及检测到新版本时提示用户更新。

Community：新文档站点与 i18n 翻译工作流

新的文档站点

AIRI 拥有了全新的文档站点，它基于 Reka UI 的设计体系重写，并叠加了大量自有功能：博客文章列表、多语言切换，以及适配 VitePress 的大量样式。博客页也配上了由 lynzrand 设计的新封面。该文档站的内容源正是本仓库的 docs/content 目录（en/ja/ko/zh-Hans 等多语言版本并存）。

翻译工作流变更：i18n 独立成包

v0.7 把原本散落的i18n/locales 文件拆分到 monorepo 内的独立包中。贡献新语言、新增翻译或修正既有翻译时，请先导航到 packages/i18n/src/locales（当前仓库中已包含 en、es、fr、ja、ko、ru、vi、zh-Hans、zh-Hant 等多个语言目录）。

以英文为例，目录结构如下：

└── en ├── docs ├── tamagotchi ├── base.yaml ├── settings.yaml ├── stage.yaml └── index.ts

各部分的职责：

docs/：文档站点 UI 字符串（非文章正文），编辑其中的theme.yaml即可；
tamagotchi/：仅桌面版（Tamagotchi）使用的特殊翻译，其余桌面字符串都在根目录各 yaml 中；
base.yaml：语言基础字符串、按钮基础状态；
settings.yaml：设置页字符串；
stage.yaml：舞台（模型展示 UI）字符串。

完整结构示意（en 与 zh-Hans 为例）：

packages/i18n/src ├── index.ts └── locales ├── en │ ├── base.yaml │ ├── docs │ │ ├── index.ts │ │ └── theme.yaml │ ├── index.ts │ ├── settings.yaml │ ├── stage.yaml │ └── tamagotchi │ ├── index.ts │ ├── settings.yaml │ └── stage.yaml └── zh-Hans ├── base.yaml ├── docs │ ├── index.ts │ └── theme.yaml ├── index.ts ├── settings.yaml ├── stage.yaml └── tamagotchi ├── index.ts ├── settings.yaml └── stage.yaml

新增语言的方法：复制一个现有语言目录，重命名为新语言代码（例如把en复制为fr），然后编辑base.yaml、settings.yaml、stage.yaml与index.ts添加翻译。部分翻译也是可接受的，可以在 Pull Request 评审过程中逐步补齐。语言代码请参照 IETF 语言标签规范（BCP 47），可用 Language subtag lookup 或 IANA 的语言子标签注册表查询确认。

DevLog 同时发出 Help wanted：希望有经验的人帮助将 i18n 包接入 Crowdin 或 Weblate 等翻译自动化工具（此为社区协作邀请，非已实现功能）。

Engineering：把构建从 4 分钟压到 25 秒

v0.7 在工程侧做了一整套工具链升级，作者将其概括为：

大量包转向buildless架构；
移除unbuild的stub；
从vite切换到rolldown-vite（工作流提速约 2 倍）；
用tsdown替代unbuild（带来约 4.2 倍提速，每个子包构建时间降至 250ms 以内，并额外获得未使用依赖检查、CSS 打包、Vue SFC 打包能力）；
集成turborepo做带依赖感知的构建缓存，平均构建时间从 4 分钟降至 25 秒。

仓库证据：根目录存在 turbo.json 与 package.json 的 workspace 配置；packages 下各子包普遍存在tsdown.config.ts（如 stage-shared、core-agent 等），与 DevLog 描述一致。

buildless：为什么能跳过最大包的构建

此前采用 monorepo 架构时，依赖postinstall脚本通过 stub（jitiexports 与.d.ts模块）引导依赖安装，避免贡献者必须理解 monorepo 才能参与开发。但每次pnpm install都触发 re-build/re-stub 显然不明智。buildless 改造后，此前耗时最长的stage-ui包可以被直接跳过，且不会引入类型检查或依赖解析问题；同时移除 unbuild 的 stub 也消除了The requested module './dist/index.mjs' does not provide an export named 'foo'这类恼人错误。

Nix 支持：一条命令跑起来

v0.7 加入了 Nix flake 构建支持（在 macOS 上同样可用）。仓库根目录的 flake.nix、default.nix 以及 nix 目录（含 pnpm-deps-hash、assets-hash 等哈希锁定）印证了这一点。可以这样尝试：

nix run --extra-experimental-features 'nix-command flakes' github:moeru-ai/airi

统一构建管道：每晚验证发布路径

此前测试、预发布、正式发布的构建管道各不相同，导致每次发版前都无法确定管道能否成功。v0.7 将三者统一为同一条管道，并引入定时构建（canary/nightly）——每天以与正式发布完全相同的脚本和工作流步骤运行一遍。这意味着：如果你在最新正式版上遇到问题，可以随时尝试 main 分支的最新构建，验证问题是否已修复。

新包与周边项目

v0.7 期间诞生了一批新包与周边项目：

[@proj-airi/chromatic] 与@proj-airi/unocss-preset-chromatic（sumimakito 贡献，配色体系及 UnoCSS preset）；
@moeru-ai/jem（LemonNekoGH 贡献）——统一模型目录（model catalog）；
clustr（sumimakito 贡献，即前文"更好的文本动画"的实现基础）；
@proj-airi/drizzle-orm-browser（作者本人贡献）；
HuggingFace Inspector、更多 candle/whisper/VAD 实验示例（candle-examples）、以及 Inventory 模型目录提交（moeru-ai/inventory）。

若想追踪本次未能在 DevLog 中一一展开的全部改动，可以查阅 v0.7 的 Roadmap issue（DevLog 末尾附有链接）。

小结：v0.7 意味着什么

从用户体验看，v0.7 让 AIRI 桌面版第一次具备"常驻陪伴"的完整形态——Fade on hover + Move + Resize 构成一套自洽的透明窗口交互体系，Resource Island 与本地 ASR/STT 消除了"能不能用"的疑虑；从工程治理看，buildless + tsdown + rolldown-vite + turborepo 与统一 nightly 构建管道，把 monorepo 的迭代成本压到了可接受的范围；从社区协作看，i18n 独立成包与全新文档站，为多语言贡献者铺平了道路。想要继续深入，推荐按以下路径阅读源码：交互核心 fade-on-hover.ts 与配套测试 fade-on-hover.test.ts、状态持久化 controls-island.ts、全局快捷键 schema global.ts，以及完整的开发日志原文 DevLog-2025.08.05/index.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析