AIRI 桌面版开发者工具台（System → Developer）完整指南：诊断、渲染与调试实践

AIRI 桌面版开发者工具台（System → Developer）完整指南：诊断、渲染与调试实践

【免费下载链接】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 桌面应用（apps/stage-tamagotchi）在Settings → System → Developer页面集中提供了一批面向开发、排障与实验性功能验证的诊断工具。本文以官方文档 desktop-developer-tools.md 为主体，结合仓库源码逐项讲解每个工具的用途、适用场景与操作要点，帮助你快速定位渲染问题、网络异常、插件生命周期故障，并为维护者收集规范、可复现的诊断材料。

适用前提：本文仅针对桌面应用。Web 版虽然也有开发页面，但其可用功能与运行环境不同（见 webui.md）。这些工具不会改善日常聊天或角色交互，安装后无需配置，只在复现问题、开发功能或收集诊断信息时才需要使用。

::: warning 先弄清你在测试什么 部分工具会采集屏幕、使用麦克风、注册全局快捷键、打开额外窗口，或展示原始网络与插件数据。测试结束后务必停止采集流并关闭不再使用的窗口；不要公开分享包含 API 密钥、对话内容、屏幕内容或 WebSocket 数据的截图。 :::

打开页面并选择工具

在桌面应用中打开Settings → System → Developer。页面顶部是快捷操作与渲染开关，下方是各诊断页面的入口链接。其页面实现位于 developer.vue，所有入口统一映射到/devtools/*路由，并在 devtools 目录 下提供对应页面。

快捷操作与渲染诊断

打开 Developer Tools

选择Open会启动 Electron 内置的浏览器开发者工具，可用于检查控制台错误、网络请求、DOM 与性能录制——通常是排查界面问题的首选入口。源码中通过事件通道调用electronOpenMainDevtools/electronOpenDevtoolsWindow（见 developer.vue）实现。

对于可复现的问题，建议：清空控制台 → 只重复一次操作 → 仅保存相关错误。附加到 Issue 或 PR 前移除敏感信息。

Markdown Stress

在独立窗口中渲染高量级 Markdown，用于测试长段落、代码块、表格、滚动与主题样式；不会修改你的文档或对话。实现上，开发者页通过openDevtoolsWindow({ key: 'markdown-stress', route: '/devtools/markdown-stress' })打开独立窗口。

IO Tracer

IO Tracer 以时间跨度（timing spans）展示一轮交互在ASR → LLM → Streaming Control → TTS → Playback各阶段的耗时，用于定位语音-聊天管线中的延迟点或缺失阶段。它从开发者页以{ key: 'io-tracer', route: '/devtools/io-tracer', width: 1600, height: 900 }的大窗口形式打开，便于阅读完整时序。注意：轨迹数据可能包含上下文信息，仅在需要时打开，避免分享完整轨迹。

Lag Visualizer（性能可视化器）

Lag Visualizer 追踪Stage Three 运行时，可报告：

• 窗口生命周期（可见、最小化、聚焦状态与原因）
• Three.js 渲染计数与资源（renderCount、drawCalls 等）
• VRM 帧更新耗时
• hover 淡入淡出命中测试（fade-on-hover hit test）
• VRM 加载与销毁耗时
• 渲染器/资源快照

从源码看，performance-visualizer.vue 挂载时调用diagnostics.startTracing()、卸载时stopTracing()，数据来源于useStageThreeRuntimeDiagnosticsStore与useStageWindowLifecycleStore（见 stage-three-runtime-diagnostics 相关 store 目录下的 stores）。它面向 Three.js/VRM 渲染问题，不是通用的页面转场、长任务或 FPS 分析器。

Stage 与页面转场动画

• Disable Stage Transitions：关闭切换 stage 时的整体动画。排查时开启它，可把 stage 转场从变量中剔除。
• Use Page Specific Transitions：控制每个页面自身的转场，在Disable Stage Transitions开启时不可用。

这两个开关直接绑定设置中的settings.disableTransitions与settings.usePageSpecificTransitions。排查闪烁、页面不卸载或转场缓慢时，请分别测试各状态，测完恢复常规设置。

键盘、鼠标与显示器

useMagicKeys

展示键盘快捷键与修饰键状态，用于确认应用是否正确接收按键事件；没有面向用户的常规设置。如需修改 AIRI 的 Spotlight 快捷键，应使用Settings → System → Window Shortcuts（实现见 window-shortcuts.vue 与 spotlight-shortcut.ts），而非本页面。

useElectronWindowMouse、Displays 与 Relative Mouse

这三个工具展示不同坐标系下的指针位置：

• useElectronWindowMouse：指针在「所有显示器构成的桌面坐标系」中的位置。
• Displays：展示已连接的显示器及指针当前位置，用于多显示器、缩放比例或外接显示器问题（实现见 use-electron-all-displays.vue）。
• Relative Mouse：指针相对 AIRI 窗口的位置，用于测试窗口内命中区域与拖拽（实现见 use-electron-relative-mouse.vue）。

上报窗口跟随、点击偏移或多显示器定位问题时，请附上：显示器排列、缩放系数、主显示器、复现步骤。

Widgets Calling

创建悬浮小组件（overlay widgets）并校验传入组件的 props，面向 desktop-overlay 与 component-call 开发，常规使用无需打开。桌面悬浮窗相关实现可参考 desktop-overlay.vue 与 widgets.vue。

Beat Sync Visualizer

绘制节拍同步的 V-motion 目标、路径以及 Y/Z 标量变化。使用Hit beat或Hit V sequence注入测试节拍并观察结果运动；该页面没有音频输入与自动节拍检测通路（相关主进程窗口见 beat-sync/index.ts）。

聊天、实时服务与网络

Context Flow

展示进入聊天管线的上下文更新，以及发送给服务的聊天流事件。可用于确认来自插件、VS Code 等外部来源的上下文是否真正到达 AIRI。

操作方式：先打开工具，执行最小复现，再按时间顺序对比输入上下文与输出事件。上下文可能包含文件名、对话或其他隐私信息，分享前务必脱敏。

WebSocket Inspector

展示原始 WebSocket 流量，用于连接失败、事件缺失或消息格式异常的场景。只分享与问题相关的少数帧，并移除令牌、用户内容与地址信息。

Aliyun Real-time Transcriber

将系统默认麦克风的音频发送至阿里云 NLS（Alibaba Cloud NLS），并实时展示转写结果。它用于验证实时语音识别通路：默认麦克风输入 → 凭证 → 网络连通 → 转写输出。页面不提供输入设备选择器，因此请先到操作系统选择好默认麦克风再打开。仅在获得许可的环境中录音。

插件、更新与系统功能

Plugin Host Debug

展示插件是否被发现、启用、加载，并允许开发者控制其加载/卸载生命周期。排查「插件不工作」问题时，依次检查：发现（discovery）→ 启用状态（enabled）→ 加载错误 → 卸载后是否残留事件或接口状态。

底层实现中，主进程通过buildPluginHostDebugSnapshot构建调试快照，包含 registry、sessions、kits、modules 与 capabilities（见 plugins/host/debug.ts 与 plugins/host/registry.ts）。仓库还提供示例插件 devtools-sample-plugin 可参考。

修改任何状态前，先记录当前状态与错误。在没有最小复现的情况下反复加载/卸载插件，反而会让原始问题更难诊断。

Updater

展示当前版本、平台、架构、更新渠道、更新源、日志位置与更新状态，并可手动检查、下载、安装更新。用于排查更新失败、更新源异常或平台特定的安装问题。

日常更新请优先使用About窗口；除非你理解并信任该更新源，否则不要覆盖它。

屏幕与视觉采集

Screen Capture

可采集应用窗口或整个显示器，生成视频或音频流，主要用于屏幕共享与采集行为的测试页。

• 首次使用，操作系统可能请求屏幕录制权限。macOS 上若 AIRI 未出现在列表中，请在系统设置 → 隐私与安全性 → 屏幕与系统音频录制中添加/启用，重启 AIRI 后重试；Windows/Linux 的权限提示取决于操作系统、桌面环境与 Electron 版本。
• 工具中Applications列出应用窗口，Displays列出整个屏幕。当前实现不会向Devices标签提供外部源，因此该标签保持为空。
• 连接/断开显示器、打开窗口或更改权限后，使用Refetch刷新。
• 停止后确认预览已关闭，使流不再占用系统资源或权限。

页面实现见 screen-capture.vue。

Vision Capture

采集屏幕帧并展示发送到视觉管线的 payload，用于验证视觉输入是否正确采集并到达下游功能。它是一次性的诊断流程，不是配置视觉供应商后必须保持开启的全局开关。

测试屏幕视觉的完整步骤：

1. 在Settings → Providers → Vision配置视觉供应商凭证。
2. 打开Settings → Modules → Vision，选择已配置的供应商与支持图像能力的模型。
3. 打开Settings → System → Developer → Vision Capture，授予操作系统屏幕录制权限。
4. 选择一个窗口或显示器，然后选择Start ticker开始采集与分析帧。
5. 仅当你希望识别结果加入 AIRI 对话上下文时，才启用Publish to character。
6. 结束后选择Stop ticker；离开页面也会停止采集循环。

若页面停留在权限提示，请在操作系统中授权后完全退出 AIRI 并重启，再重新打开工具。切勿发布显示个人桌面、通知或其他应用内容的采集结果。

全局快捷键

Global Shortcut

注册、注销并观察系统级快捷键事件。它与日常使用的 Spotlight 快捷键（配置于Settings → System → Window Shortcuts）不同：本页面仅用于开发与验证。

选择不与操作系统或其他应用冲突的组合键；若注册失败，检查该组合是否已被占用。测试完成后务必注销快捷键，避免它持续拦截按键。

小结

AIRI 桌面版开发者工具台是一组按问题域划分的诊断工作流：界面问题从 Developer Tools 入手，渲染问题交给 Lag Visualizer，语音/聊天管线用 IO Tracer 与 Context Flow 定位，插件问题走 Plugin Host Debug，更新与权限问题则分别由 Updater、Screen Capture 和 Vision Capture 覆盖。使用时要遵循「最小复现、及时停止、分享前脱敏」三条原则，既保证诊断效率，也避免泄露隐私与凭据。相关页面源码均可从 devtools 目录 与 settings/system/developer.vue 继续深入阅读。

【免费下载链接】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