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-samas 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 ToolsThree.js 或 VRM 渲染诊断Lag Visualizer异常的转场动画动画开关Disable Stage Transitions / Use Page Specific Transitions键盘、鼠标、显示器或全局快捷键行为useMagicKeys、鼠标/显示器工具或 Global Shortcut聊天上下文、WebSocket 或实时转写Context Flow、WebSocket Inspector 或 Aliyun Real-time Transcriber插件发现、加载或卸载Plugin Host Debug更新失败或更新源异常Updater屏幕共享、视觉输入或采集权限Screen Capture 或 Vision Capture快捷操作与渲染诊断打开 Developer Tools选择Open会启动 Electron 内置的浏览器开发者工具可用于检查控制台错误、网络请求、DOM 与性能录制——通常是排查界面问题的首选入口。源码中通过事件通道调用electronOpenMainDevtools/electronOpenDevtoolsWindow见 developer.vue实现。对于可复现的问题建议清空控制台 → 只重复一次操作 → 仅保存相关错误。附加到 Issue 或 PR 前移除敏感信息。Markdown Stress在独立窗口中渲染高量级 Markdown用于测试长段落、代码块、表格、滚动与主题样式不会修改你的文档或对话。实现上开发者页通过openDevtoolsWindow({ key: markdown-stress, route: /devtools/markdown-stress })打开独立窗口。IO TracerIO 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 testVRM 加载与销毁耗时渲染器/资源快照从源码看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将系统默认麦克风的音频发送至阿里云 NLSAlibaba 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用于验证视觉输入是否正确采集并到达下游功能。它是一次性的诊断流程不是配置视觉供应商后必须保持开启的全局开关。测试屏幕视觉的完整步骤在Settings → Providers → Vision配置视觉供应商凭证。打开Settings → Modules → Vision选择已配置的供应商与支持图像能力的模型。打开Settings → System → Developer → Vision Capture授予操作系统屏幕录制权限。选择一个窗口或显示器然后选择Start ticker开始采集与分析帧。仅当你希望识别结果加入 AIRI 对话上下文时才启用Publish to character。结束后选择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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考