chore(docs): reorganize guides and refresh provider docs (#2081)

2026-08-14 08:52:42 +00:00 · 2026-07-20 16:12:01 +08:00
parent 2bf8cb1f7f
commit 0460a6cf14
103 changed files with 1159 additions and 1008 deletions
@@ -281,6 +281,15 @@ export default defineConfig<ThemeConfig>({
              { text: '有关 AI VTuber', link: withBase('/zh-Hans/docs/overview/about-ai-vtuber') },
              { text: '有关 Neuro-sama', link: withBase('/zh-Hans/docs/overview/about-neuro-sama') },
              { text: '其他类似项目', link: withBase('/zh-Hans/docs/overview/other-similar-projects') },
+              {
+                text: '编年史',
+                collapsed: true,
+                items: [
+                  { text: '首次公开 v0.1.0', link: withBase('/zh-Hans/docs/chronicles/version-v0.1.0/') },
+                  { text: '先前的故事 v0.0.1', link: withBase('/zh-Hans/docs/chronicles/version-v0.0.1/') },
+                ],
+              },
+              { text: '角色', link: withBase('/zh-Hans/characters/') },
            ],
          },
          {
@@ -303,17 +312,19 @@ export default defineConfig<ThemeConfig>({
                items: [
                  { text: '配置指南', link: withBase('/zh-Hans/docs/manual/config/') },
                  { text: '通用说明', link: withBase('/zh-Hans/docs/manual/config/common') },
-                  { text: '聊天模型', link: withBase('/zh-Hans/docs/manual/config/llm') },
-                  { text: '语音输入与输出', link: withBase('/zh-Hans/docs/manual/config/audio') },
-                  { text: '视觉理解', link: withBase('/zh-Hans/docs/manual/config/vision') },
-                  { text: '艺术创作', link: withBase('/zh-Hans/docs/manual/config/providers/artistry/') },
-                  { text: '支持的服务商目录', link: withBase('/zh-Hans/docs/manual/config/providers/catalog') },
-                  { text: '配置服务来源', collapsed: true, items: [
-                    { text: '聊天', collapsed: true, items: [
+                  { text: '功能配置', collapsed: true, items: [
+                    { text: '聊天模型', link: withBase('/zh-Hans/docs/manual/config/llm') },
+                    { text: '语音输入与输出', link: withBase('/zh-Hans/docs/manual/config/audio') },
+                    { text: '视觉理解', link: withBase('/zh-Hans/docs/manual/config/vision') },
+                    { text: '网络搜索', link: withBase('/zh-Hans/docs/manual/config/web-search') },
+                  ] },
+                  { text: '服务商', collapsed: true, items: [
+                    { text: '聊天服务商', collapsed: true, items: [
                      { text: 'AIRI 官方提供商', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/official') },
                      { text: 'AIHubMix', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/aihubmix') },
                      { text: 'Amazon Bedrock', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/amazon-bedrock') },
                      { text: 'Anthropic', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/anthropic') },
+                      { text: 'Atlas Cloud', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/atlascloud') },
                      { text: 'Azure AI Foundry', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/azure-ai-foundry') },
                      { text: 'Azure OpenAI', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/azure-openai') },
                      { text: 'BytePlus', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/byteplus') },
@@ -324,12 +335,13 @@ export default defineConfig<ThemeConfig>({
                      { text: 'xAI', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/xai') },
                      { text: 'Cloudflare Workers AI', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/cloudflare-workers-ai') },
                      { text: 'LM Studio（本地模型）', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/lm-studio') },
+                      { text: 'OpenPaths', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/openpaths') },
                      { text: 'OpenRouter', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/openrouter') },
                      { text: 'Ollama', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/ollama') },
                      { text: '深度求索 DeepSeek', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/deepseek') },
-                      { text: 'OpenAI (和兼容 API)', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/openai') },
+                      { text: 'OpenAI 与兼容 API', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/openai') },
                      { text: '302.ai', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/302ai') },
-                      { text: 'fireworks', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/fireworks') },
+                      { text: 'Fireworks AI', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/fireworks') },
                      { text: 'Featherless.ai', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/featherless') },
                      { text: 'Groq', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/groq') },
                      { text: 'MiniMax', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/minimax') },
@@ -338,7 +350,7 @@ export default defineConfig<ThemeConfig>({
                      { text: '小米 MiMo', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/mimo') },
                      { text: 'ModelScope', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/modelscope') },
                      { text: '月之暗面', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/moonshot') },
-                      { text: 'Nvidia NIM', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/nvidia') },
+                      { text: 'NVIDIA NIM', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/nvidia') },
                      { text: 'n1n', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/n1n') },
                      { text: 'Novita', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/novita') },
                      { text: 'Perplexity', link: withBase('/zh-Hans/docs/manual/config/providers/consciousness/perplexity') },
@@ -360,7 +372,7 @@ export default defineConfig<ThemeConfig>({
                      { text: 'Microsoft Azure Speech', link: withBase('/zh-Hans/docs/manual/config/providers/speech/azure-speech') },
                      { text: 'MiniMax Speech', link: withBase('/zh-Hans/docs/manual/config/providers/speech/minimax') },
                      { text: '小米 MiMo', link: withBase('/zh-Hans/docs/manual/config/providers/speech/mimo') },
-                      { text: 'OpenAI (和兼容 API)', link: withBase('/zh-Hans/docs/manual/config/providers/speech/openai') },
+                      { text: 'OpenAI 与兼容 API', link: withBase('/zh-Hans/docs/manual/config/providers/speech/openai') },
                      { text: 'OpenRouter', link: withBase('/zh-Hans/docs/manual/config/providers/speech/openrouter') },
                      { text: 'Player2 Speech', link: withBase('/zh-Hans/docs/manual/config/providers/speech/player2') },
                      { text: '火山引擎', link: withBase('/zh-Hans/docs/manual/config/providers/speech/volcengine') },
@@ -373,60 +385,66 @@ export default defineConfig<ThemeConfig>({
                      { text: 'CometAPI', link: withBase('/zh-Hans/docs/manual/config/providers/transcription/comet-api') },
                      { text: '桌面端本地语音识别', link: withBase('/zh-Hans/docs/manual/config/providers/transcription/desktop-local') },
                      { text: '小米 MiMo', link: withBase('/zh-Hans/docs/manual/config/providers/transcription/mimo') },
-                      { text: 'OpenAI (和兼容 API)', link: withBase('/zh-Hans/docs/manual/config/providers/transcription/openai') },
+                      { text: 'OpenAI 与兼容 API', link: withBase('/zh-Hans/docs/manual/config/providers/transcription/openai') },
                    ] },
-                    { text: '艺术创作', collapsed: true, items: [
+                    { text: '艺术创作服务商', collapsed: true, items: [
                      { text: 'ComfyUI（本地工作流）', link: withBase('/zh-Hans/docs/manual/config/providers/artistry/comfyui') },
-                      { text: 'Replicate', link: withBase('/zh-Hans/docs/manual/config/providers/artistry/replicate') },
                      { text: 'Nano Banana', link: withBase('/zh-Hans/docs/manual/config/providers/artistry/nanobanana') },
+                      { text: 'Replicate', link: withBase('/zh-Hans/docs/manual/config/providers/artistry/replicate') },
                    ] },
                  ] },
                ],
              },
+            ],
+          },
+          {
+            text: '集成服务',
+            icon: 'lucide:plug',
+            items: [
              {
-                text: '贡献指南',
-                icon: 'lucide:users',
+                text: '游戏',
                items: [
-                  {
-                    text: '基础配置与开发',
-                    items: [
-                      { text: '环境配置与基础准备', link: withBase('/zh-Hans/docs/contributing/') },
-                      { text: '桌面端', link: withBase('/zh-Hans/docs/contributing/tamagotchi') },
-                      { text: '网页端', link: withBase('/zh-Hans/docs/contributing/webui') },
-                      { text: '文档站', link: withBase('/zh-Hans/docs/contributing/docs') },
-                    ],
-                  },
-                  {
-                    text: '游戏与社交平台',
-                    items: [
-                      { text: 'Minecraft', link: withBase('/zh-Hans/docs/contributing/services/minecraft') },
-                      { text: 'Satori Bot', link: withBase('/zh-Hans/docs/contributing/services/satori') },
-                      { text: 'Telegram Bot', link: withBase('/zh-Hans/docs/contributing/services/telegram') },
-                      { text: 'Discord Bot', link: withBase('/zh-Hans/docs/contributing/services/discord') },
-                    ],
-                  },
-                  {
-                    text: '设计指南',
-                    items: [
-                      { text: '介绍', link: withBase('/zh-Hans/docs/contributing/design-guidelines/') },
-                      { text: '艺术家与开发者 (参考资源)', link: withBase('/zh-Hans/docs/contributing/design-guidelines/resources') },
-                      { text: '工具', link: withBase('/zh-Hans/docs/contributing/design-guidelines/tools') },
-                    ],
-                  },
+                  { text: 'Minecraft 智能体', link: withBase('/zh-Hans/docs/integrations/minecraft') },
+                  { text: '异星工厂', link: withBase('/zh-Hans/docs/integrations/factorio') },
                ],
              },
              {
-                text: '编年史',
-                icon: 'lucide:calendar-days',
+                text: '消息平台',
                items: [
-                  { text: '首次公开 v0.1.0', link: withBase('/zh-Hans/docs/chronicles/version-v0.1.0/') },
-                  { text: '先前的故事 v0.0.1', link: withBase('/zh-Hans/docs/chronicles/version-v0.0.1/') },
+                  { text: 'Satori 机器人', link: withBase('/zh-Hans/docs/integrations/satori') },
+                  { text: 'Telegram 机器人', link: withBase('/zh-Hans/docs/integrations/telegram') },
+                  { text: 'Discord 机器人', link: withBase('/zh-Hans/docs/integrations/discord') },
+                  { text: 'X / Twitter', link: withBase('/zh-Hans/docs/integrations/x') },
+                ],
+              },
+            ],
+          },
+          {
+            text: '开发者指南',
+            icon: 'lucide:code-2',
+            items: [
+              {
+                text: '参与贡献',
+                items: [
+                  { text: '开发环境与首次贡献', link: withBase('/zh-Hans/docs/contributing/') },
+                  { text: '桌面端', link: withBase('/zh-Hans/docs/contributing/tamagotchi') },
+                  { text: '网页端', link: withBase('/zh-Hans/docs/contributing/webui') },
+                  { text: '文档站', link: withBase('/zh-Hans/docs/contributing/docs') },
                ],
              },
              {
-                text: '角色',
-                icon: 'lucide:scan-face',
-                link: withBase('/zh-Hans/characters/'),
+                text: '桌面端调试',
+                items: [
+                  { text: '开发者工具', link: withBase('/zh-Hans/docs/contributing/desktop-developer-tools') },
+                ],
+              },
+              {
+                text: '设计指南',
+                items: [
+                  { text: '介绍', link: withBase('/zh-Hans/docs/contributing/design-guidelines/') },
+                  { text: '艺术家与开发者 (参考资源)', link: withBase('/zh-Hans/docs/contributing/design-guidelines/resources') },
+                  { text: '工具', link: withBase('/zh-Hans/docs/contributing/design-guidelines/tools') },
+                ],
              },
            ],
          },
@@ -0,0 +1,140 @@
+---
+title: 桌面端开发者工具
+description: 理解和使用 AIRI 桌面端「系统 → 开发者」中的诊断与验证工具
+---
+
+桌面版的「系统 → 开发者」是一组为开发、排障和验证实验功能准备的工具。它们不会改善日常聊天或角色体验，也不需要在首次安装后配置；只有在复现问题、开发功能，或维护者要求收集诊断信息时才需要打开。
+
+本页只说明桌面版。网页端虽也有开发相关页面，但可用的功能和运行环境不同。
+
+::: warning 使用前先确认目的
+部分工具会读取屏幕、使用麦克风、注册全局快捷键、打开额外窗口，或显示原始网络及插件数据。测试结束后请关闭不再使用的窗口和捕获流；不要把包含 API Key、聊天内容、屏幕画面或 WebSocket 数据的截图直接公开。
+:::
+
+## 如何进入与选择工具
+
+在桌面端打开「设置 → 系统 → 开发者」。页面上半部分是快捷操作和渲染开关；下半部分则是不同的诊断页面。
+
+选择工具前，可以先按问题类型判断：
+
+| 想确认什么 | 优先使用 |
+| --- | --- |
+| 页面报错、元素样式或网络请求 | 打开开发者工具 |
+| 页面卡顿、切换动画异常 | Lag 可视化、动画开关 |
+| 按键、鼠标、显示器或全局快捷键 | useMagicKeys、鼠标／显示器工具、Global Shortcut |
+| 聊天上下文、WebSocket 或实时转写 | Context Flow、WebSocket Inspector、Aliyun Real-time Transcriber |
+| 插件发现、加载或卸载 | Plugin Host Debug |
+| 更新失败或更新源异常 | Updater |
+| 屏幕共享、视觉输入或权限问题 | Screen Capture、Vision Capture |
+
+## 快捷操作与渲染诊断
+
+### 打开开发者工具
+
+点击「打开」会打开 Electron 内置的浏览器开发者工具。它适合查看控制台错误、网络请求、DOM 结构和性能记录，是定位界面问题的首选入口。
+
+如果问题可以稳定复现，建议先清空控制台，重复一次操作，再保存相关的错误信息；提交 issue 或 PR 时应移除敏感内容。
+
+### Markdown 压力测试
+
+此工具会在独立窗口渲染高负载 Markdown，用来检查长文、代码块、表格和样式在较大内容量下的表现。它适用于排查 Markdown 渲染卡顿、滚动异常或主题样式错误，不会修改你的文档或聊天记录。
+
+### IO Tracer
+
+IO Tracer 会打开输入输出事件的诊断窗口。它用于观察调试期间的事件流向，适合检查一次操作是否产生了预期的输入、输出或状态变化。事件内容可能包含上下文数据，因此仅在需要时开启，并避免共享完整记录。
+
+### Lag 可视化
+
+Lag 可视化用于查看界面性能和帧时间。当窗口移动、舞台切换、角色渲染或动画出现明显卡顿时，可先用它确认问题是否与渲染负载有关。它帮助定位问题，不会自动优化性能；记录复现步骤、设备环境和帧时间变化会比单独的截图更有帮助。
+
+### 舞台切换与页面过场动画
+
+「是否开启舞台切换动画」控制舞台切换时的总体动画；关闭后可减少动画对测试的干扰。「是否使用页面特定过场动画」控制各页面自己的过场效果，并且在总体舞台切换动画关闭时不可用。
+
+排查闪烁、页面未卸载或切换卡顿时，可以分别测试两种状态。完成测试后，建议恢复你平时使用的设置。
+
+## 输入、鼠标与显示器
+
+### useMagicKeys
+
+这是键盘快捷键状态的调试页，用于确认应用是否正确接收修饰键和按键状态。当前没有面向普通用户的配置项；若只想更改 AIRI 的 Spotlight 快捷键，请使用「系统 → 窗口快捷方式」。
+
+### useElectronWindowMouse、Displays 与 Relative Mouse
+
+这三个工具分别帮助检查不同坐标系中的鼠标位置：
+
+- **useElectronWindowMouse**：查看鼠标在所有屏幕组成的桌面坐标系中的位置；
+- **Displays**：查看当前连接的显示器及鼠标所在位置，适合多显示器、缩放比例或外接屏幕问题；
+- **Relative Mouse**：查看鼠标相对于 AIRI 窗口的位置，适合检查窗口内部命中区域和拖拽行为。
+
+报告窗口跟随、点击偏移或多屏定位问题时，请一并说明显示器排列、缩放比例、主显示器和复现步骤。
+
+### Widgets Calling
+
+Widgets Calling 用于创建覆盖层小组件并验证传入的组件参数。它主要服务于桌面浮层和组件调用开发；如果只是使用 AIRI，不需要在这里进行任何操作。
+
+### Beat Sync Visualizer
+
+Beat Sync Visualizer 会绘制同步音律的 V-motion 目标、轨迹以及 Y/Z 标量变化。它用于确认声音或节拍驱动的角色运动是否连续、稳定，并协助比较不同输入下的运动数据。
+
+## 聊天、实时服务与网络
+
+### Context Flow
+
+Context Flow 用于检查进入聊天管道的上下文更新，以及发往服务端的聊天流事件。它很适合验证插件、VS Code 等外部来源提供的上下文是否按预期抵达 AIRI。
+
+推荐的排查方式是：先打开工具，再执行一次最小复现操作，最后根据时间顺序检查输入上下文与输出事件是否成对出现。上下文可能包含正在编辑的文件名、聊天内容或其他私密信息，分享日志前务必脱敏。
+
+### WebSocket Inspector
+
+WebSocket Inspector 显示原始 WebSocket 流量。它适用于连接建立失败、事件未送达、消息格式不符合预期等问题。因为它展示的是底层协议数据，通常应只截取与问题直接相关的少量帧，并删除令牌、用户内容和地址信息。
+
+### Aliyun Real-time Transcriber
+
+这个页面将麦克风音频流发送到阿里云 NLS，并显示实时转写结果。它用于验证实时语音识别链路，包括麦克风输入、凭据、网络和转写输出。开始前请确认已选择正确输入设备，并只在你有权录音的环境中测试。
+
+## 插件、更新与系统功能
+
+### Plugin Host Debug
+
+Plugin Host Debug 用于检查插件是否被发现、启用和加载，并可控制插件的加载与卸载生命周期。插件未生效时，依次检查：插件是否被发现、是否已启用、加载过程中是否出现错误，以及卸载后是否仍残留事件或界面状态。
+
+不要为了“修复”一个普通使用问题随意反复加载和卸载插件；先记录状态和错误信息，再进行最小改动测试，结果会更容易复现。
+
+### Updater
+
+Updater 展示当前版本、平台、架构、更新通道、更新源、日志位置和更新状态，也可以手动检查、下载和安装更新。它主要用于排查更新失败、错误的更新源或特定平台的安装问题。
+
+日常升级优先使用「关于」窗口；在开发者工具中覆盖更新源前，请确认自己了解该来源的可信性和影响范围。
+
+## 屏幕与视觉捕捉
+
+### Screen Capture
+
+Screen Capture 可捕获应用窗口、整块显示器或系统暴露的其他设备，并创建视频或音频流。它主要用于验证屏幕共享和捕获链路。
+
+首次使用时，系统会要求授权屏幕录制权限。若 macOS 没有列出 AIRI，可在「系统设置 → 隐私与安全性 → 屏幕与系统音频录制」中手动添加或启用 AIRI，然后重启应用再测试。Windows 和 Linux 的可用设备与权限提示会随系统、桌面环境和浏览器／Electron 版本而变化。
+
+工具中的 `applications` 用于选择某个应用窗口，`displays` 用于选择整块显示器，`devices` 列出系统报告的可捕获设备；连接或断开显示器、打开新窗口、修改权限后，可使用 `refetch` 刷新列表。停止捕获后应确认预览已关闭，避免继续占用权限或资源。
+
+### Vision Capture
+
+Vision Capture 会捕获屏幕帧，并显示提交给视觉处理流程的输出载荷。它用于验证视觉输入是否成功取得、帧数据是否正确，以及下游视觉功能是否获得预期内容。它不是一个持久开启的全局开关：仅配置视觉服务商和模型时，不需要打开此页。
+
+使用屏幕视觉时，依次完成以下步骤：
+
+1. 在「设置 → 服务商 → 视觉」中选好视觉服务商和支持图像输入的模型；
+2. 打开「系统 → 开发者 → Vision Capture」，完成系统的屏幕录制授权；
+3. 选择窗口或显示器，再点击「Start ticker」开始捕获和分析；
+4. 仅在希望将识别结果加入 AIRI 对话上下文时，开启「Publish to character」；
+5. 测试完成后点击「Stop ticker」。离开此页面也会停止捕获循环。
+
+若页面一直停在权限提示，先在操作系统中完成授权、完全退出并重新启动 AIRI，再重新打开此工具；不要把包含个人桌面、通知或其他应用内容的捕获结果上传到公开位置。
+
+## 全局快捷键
+
+### Global Shortcut
+
+Global Shortcut 用于注册、注销和观察系统级快捷键事件。它与「系统 → 窗口快捷方式」中给普通用户设置的 Spotlight 快捷键不同：前者用于开发与验证，后者用于日常使用。
+
+测试前选择一个不与操作系统或常用应用冲突的组合键。若注册失败，先检查该组合键是否已经被占用；测试结束后注销快捷键，避免它继续在后台拦截按键。
@@ -1,14 +1,23 @@
 ---
-title: 文档站
-description: 参与并贡献 Project AIRI
+title: 文档站开发
+description: 在本地编写、预览和验证 VitePress 文档
 ---

-### 文档站
+文档站位于 `docs`，内容按语言存放在 `docs/content/<locale>`。从仓库根目录运行：

 ```shell
 pnpm dev:docs
 ```

+仅检查文档站时，可运行：
+
+```shell
+pnpm -F @proj-airi/docs typecheck
+pnpm -F @proj-airi/docs build
+```
+
+新增中文页面时，请同时在 `docs/.vitepress/config.ts` 的 `zh-Hans` sidebar 中添加入口；否则页面虽能通过 URL 打开，却不会出现在导航中。
+
 ::: tip

 如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
@@ -1,56 +1,41 @@
 ---
-title: 环境配置与基础准备
-description: 参与并贡献 Project AIRI
+title: 开发环境与首次贡献
+description: 从本地运行 Project AIRI 到提交第一个拉取请求
 ---

-你好呀！感谢你有兴趣参与这个项目。本指南将帮助你快速上手
+你好呀！感谢你有兴趣参与 Project AIRI。本页说明如何建立本地开发环境、创建分支并提交第一个 Pull Request。
+
+::: info 适用范围
+本节面向需要修改源码、文档或设计资源的贡献者。若只是使用 AIRI，请从「用户手册」开始；应用内的调试工具请参阅[开发者工具](./desktop-developer-tools)。
+:::

 ## 前置准备

 - [Git](https://git-scm.com/downloads)
- [Node.js 23+](https://nodejs.org/en/download/)
- [corepack](https://github.com/nodejs/corepack)
- [pnpm](https://pnpm.io/installation)
+- [Node.js 当前 LTS 版本](https://nodejs.org/en/download/)
+- [Corepack](https://github.com/nodejs/corepack)（随较新的 Node.js 一同提供）

 <details>
 <summary>Windows 平台相关设置</summary>

-0. 下载 [Visual Studio](https://visualstudio.microsoft.com/downloads/), 根据这个教程安装 https://rust-lang.github.io/rustup/installation/windows-msvc.html#walkthrough-installing-visual-studio-2022
-
-   > 安装时请确保勾选了 Windows SDK 和 MSVC C++ build tools
-
-::: tip
-
-建议使用Visual Studio 2022 版以达到更好的兼容性
-
-:::
-
-1. 打开 PowerShell
-2. 安装 [`scoop`](https://scoop.sh/)
+1. 打开 PowerShell。
+2. 安装 [`scoop`](https://scoop.sh/)。

   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
   ```

-3. 通过 `scoop` 安装 `git`, Node.js, `rustup` 和 `msvc`
+3. 通过 `scoop` 安装 `git` 和 Node.js。

   ```powershell
-   scoop install git nodejs rustup
-
-   # Rust 相关依赖
-   # 如果你不打算涉及 crates 或者 apps/tamagotchi 的开发，该步骤可跳过
-   scoop install main/rust-msvc
-   # Windows 平台所需内容
-   rustup toolchain install stable-x86_64-pc-windows-msvc
-   rustup default stable-x86_64-pc-windows-msvc
+   scoop install git nodejs
   ```

-4. 通过 `corepack` 安装 `pnpm`
+4. 通过 Corepack 启用仓库指定的 pnpm 版本：

   ```powershell
   corepack enable
-   corepack prepare pnpm@latest --activate
   ```

 </details>
@@ -65,11 +50,10 @@ description: 参与并贡献 Project AIRI
   brew install git node
   ```

-2. 通过 `corepack` 安装 `pnpm`
+2. 通过 Corepack 启用仓库指定的 pnpm 版本：

   ```shell
   corepack enable
-   corepack prepare pnpm@latest --activate
   ```

 </details>
@@ -77,25 +61,14 @@ description: 参与并贡献 Project AIRI
 <details>
 <summary>Linux setup</summary>

-0. 打开 Terminal
-1. 请按照该说明的内容 [nodesource/distributions: NodeSource Node.js Binary Distributions](https://github.com/nodesource/distributions?tab=readme-ov-file#table-of-contents) 安装 `node`
+0. 打开 Terminal。
+1. 从 [Node.js 官网](https://nodejs.org/en/download/) 安装当前 LTS 版本。
 2. 请参考该页面 [Git](https://git-scm.com/downloads/linux) 安装 `git`
-3. 通过 `corepack` 安装 `pnpm`
+3. 通过 Corepack 启用仓库指定的 pnpm 版本：

   ```shell
   corepack enable
-   corepack prepare pnpm@latest --activate
   ```
-4. 如果你想进行桌面端的开发，你还需要下载如下依赖：
-   ```shell
-   sudo apt install \
-      libssl-dev \
-      libglib2.0-dev \
-      libgtk-3-dev \
-      libjavascriptcoregtk-4.1-dev \
-      libwebkit2gtk-4.1-dev
-   ```
-
 </details>

 ## 如果你之前已经参与并贡献过本项目
@@ -106,18 +79,18 @@ description: 参与并贡献 Project AIRI

 :::

-请确保你的本地仓库与主仓库保持最新同步：
+请先获取上游更新，再把自己的分支变基到最新 `main`：

 ```shell
 git fetch --all
-git checkout main
+git switch main
 git pull upstream main --rebase
 ```

 如果你有自己的开发/工作分支，请按照如下方式同步至主分支：

 ```shell
-git checkout <your-branch-name>
+git switch <your-branch-name>
 git rebase main
 ```

@@ -135,7 +108,7 @@ cd airi
 ## 创建你自己的工作分支

 ```shell
-git checkout -b <your-branch-name>
+git switch -c <your-branch-name>
 ```

 ## 安装依赖项
@@ -143,10 +116,6 @@ git checkout -b <your-branch-name>
 ```shell
 corepack enable
 pnpm install
-
-# Rust相关依赖
-# 如果你不打算涉及 crates 或者 apps/tamagotchi 的开发，该步骤可跳过
-cargo fetch
 ```

 ::: tip
@@ -166,32 +135,15 @@ npm i -g @antfu/ni
 你无需费心选择包管理器， `ni` 会自动适配。
 :::

-::: warning Visual Studio 2026 兼容提示
-
-如果你使用的 Visual Studio 为 2026 版，安装依赖时可能会报错
-
-```shell
-gyp ERR! stack Error: Could not find any Visual Studio installation to use
-gyp ERR! stack Error: Could not find any Visual Studio installation to use
-```
-
-这是因为编译工具链使用的 node-gyp 暂未兼容新版 Visual Studio 2026。在 Powershell 中按如下操作强制指定新版 node-gyp 即可通过编译
-
-```shell
-npm i -g "node-gyp@>=12.2.0"
-$env:npm_config_node_gyp = (Join-Path (npm root -g) "node-gyp\bin\node-gyp.js")
-```
-
-:::
-
 ## 提交代码（Commit）

-### 提交前请检查
+### 提交前验证

 提交前请确保代码已通过 Lint（静态分析器）和 类型安全检查：

 ```shell
-pnpm lint && pnpm typecheck
+pnpm lint
+pnpm typecheck
 ```

 ::: tip
@@ -207,14 +159,14 @@ nr lint && nr typecheck
 ### 执行提交

 ```shell
-git add .
+git add <changed-files>
 git commit -m "<your-commit-message>"
 ```

 ### 将你的代码推送（push）至先前 fork 或者拥有写入权限的 AIRI 仓库

 ```shell
-git push origin <your-branch-name> -u
+git push -u origin <your-branch-name>
 ```

 现在，你应该可以在 GitHub 上看到你的分支。
@@ -1,34 +0,0 @@
---
-title: Discord Bot
-description: 参与并贡献 Project AIRI
---
-
-### Discord Bot / 机器人
-
-```shell
-cd services/discord-bot
-```
-
-配置 `.env` 文件：
-
-```shell
-cp .env .env.local
-```
-
-编辑 `.env.local` 中的各类密钥和配置信息。
-
-启动机器人：
-
-```shell
-pnpm -F @proj-airi/discord-bot start
-```
-
-::: tip
-
-如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
-
-```shell
-nr -F @proj-airi/discord-bot dev
-```
-
-:::
@@ -1,36 +0,0 @@
---
-title: Minecraft
-description: 参与并贡献 Project AIRI
---
-
-### Minecraft（我的世界）Agent / NPC
-
-```shell
-cd services/minecraft
-```
-
-启动 Minecraft（我的世界）客户端并导出世界到指定的端口。请在 `.env.local` 中配置端口。
-
-配置 `.env` 文件：
-
-```shell
-cp .env .env.local
-```
-
-编辑 `.env.local` 中的各类密钥和配置信息。
-
-启动机器人：
-
-```shell
-pnpm -F @proj-airi/minecraft-bot start
-```
-
-::: tip
-
-如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
-
-```shell
-nr -F @proj-airi/minecraft-bot dev
-```
-
-:::
@@ -1,34 +0,0 @@
---
-title: Satori Bot
-description: 参与并贡献 Project AIRI
---
-
-### Satori Bot / 机器人
-
-```shell
-cd services/satori-bot
-```
-
-配置 `.env` 文件：
-
-```shell
-cp .env .env.local
-```
-
-编辑 `.env.local` 中的各类密钥和配置信息。
-
-启动机器人：
-
-```shell
-pnpm -F @proj-airi/satori-bot dev
-```
-
-::: tip
-
-如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
-
-```shell
-nr -F @proj-airi/satori-bot dev
-```
-
-:::
@@ -1,44 +0,0 @@
---
-title: Telegram Bot
-description: 参与并贡献 Project AIRI
---
-
-### Telegram Bot / 机器人
-
-需要使用 pgvector（基于 Postgres）数据库。
-
-```shell
-cd services/telegram-bot
-docker compose up -d
-```
-
-配置 `.env` 文件：
-
-```shell
-cp .env .env.local
-```
-
-编辑 `.env.local` 中的各类密钥和配置信息。
-
-执行数据库迁移：
-
-```shell
-pnpm -F @proj-airi/telegram-bot db:generate
-pnpm -F @proj-airi/telegram-bot db:push
-```
-
-启动机器人：
-
-```shell
-pnpm -F @proj-airi/telegram-bot start
-```
-
-::: tip
-
-如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
-
-```shell
-nr -F @proj-airi/telegram-bot dev
-```
-
-:::
@@ -1,14 +1,25 @@
 ---
-title: 桌面端
-description: 参与并贡献 Project AIRI
+title: 桌面端开发
+description: 运行、检查和构建 Electron 桌面端
 ---

-### Stage Tamagotchi (桌面端)
+桌面端位于 `apps/stage-tamagotchi`，开发时从仓库根目录运行：

 ```shell
 pnpm dev:tamagotchi
 ```

+它会启动 Electron 开发环境。修改桌面端页面前，先查看共享组件和状态是否已在 `packages/stage-ui` 中实现；网页端和桌面端共用的逻辑应优先放在共享包中。
+
+## 验证
+
+```shell
+pnpm -F @proj-airi/stage-tamagotchi typecheck
+pnpm -F @proj-airi/stage-tamagotchi build
+```
+
+应用内的「系统 → 开发者」菜单及其每一项调试用途，请参阅[开发者工具](./desktop-developer-tools)。
+
 ::: tip

 如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
@@ -1,14 +1,27 @@
 ---
-title: 网页端
-description: 参与并贡献 Project AIRI
+title: 网页端开发
+description: 运行、检查和构建 AIRI 网页端
 ---

-### 网页端 ([airi.moeru.ai](https://airi.moeru.ai))
+网页端位于 `apps/stage-web`，对应 [airi.moeru.ai](https://airi.moeru.ai)。从仓库根目录运行：

 ```shell
 pnpm dev
 ```

+也可以使用更明确的命令：
+
+```shell
+pnpm dev:web
+```
+
+## 验证
+
+```shell
+pnpm -F @proj-airi/stage-web typecheck
+pnpm -F @proj-airi/stage-web build
+```
+
 ::: tip

 如果你使用 [@antfu/ni](https://github.com/antfu-collective/ni)，你可以：
@@ -0,0 +1,35 @@
+---
+title: Discord 机器人
+description: 使用 Discord 应用与模型服务运行 AIRI 语音和消息机器人
+---
+
+Discord 机器人连接 Discord 服务器中的消息和语音频道，并使用配置的模型服务生成回复。
+
+## 前提条件
+
+* 已在仓库根目录安装依赖：**pnpm i**。
+* 在 [Discord Developer Portal](https://discord.com/developers/home) 创建应用和 Bot。
+* 在 Bot 设置中启用 **Server Members Intent** 与 **Message Content Intent**。
+* 已准备聊天模型和语音服务的凭据。
+
+::: warning 凭据安全
+Discord Bot Token、Client ID 和模型 API Key 只应保存在本地 **.env.local** 文件中。不要提交、截图或发送这些配置。
+:::
+
+## 配置
+
+~~~bash
+cp services/discord-bot/.env services/discord-bot/.env.local
+~~~
+
+编辑 **services/discord-bot/.env.local**，填写 **DISCORD_TOKEN**、**DISCORD_BOT_CLIENT_ID**、聊天模型与语音服务配置。Discord Token 丢失或泄露时，应立即在开发者控制台重置。
+
+## 启动
+
+~~~bash
+pnpm -F @proj-airi/discord-bot start
+~~~
+
+## 注意事项
+
+邀请机器人加入服务器前，确认应用权限仅覆盖所需的频道和能力。不要将 Bot Token 或其他服务凭据提交到仓库。
@@ -0,0 +1,30 @@
+---
+title: 异星工厂
+description: 将 AIRI 连接到受信任的 Factorio 服务器
+---
+
+Factorio 集成让 AIRI 使用游戏服务器地址、端口和玩家名称连接外部游戏服务。AIRI 桌面端提供连接配置；你仍需要自行准备可访问的 Factorio 服务器和与之配套的服务端集成。
+
+## 前提条件
+
+* 可访问的 Factorio 服务器。
+* 服务器管理员已允许你的账号和所使用的服务端集成连接。
+* 服务器地址、端口和游戏内用户名。
+
+::: warning 仅连接受信任的服务器
+该集成会让 AIRI 与游戏服务器交换上下文和操作请求。不要将它用于不受信任的公共服务器，也不要在公共聊天、截图或 Issue 中公开服务器地址、令牌或账号信息。
+:::
+
+## 在 AIRI 中配置
+
+1. 打开 **设置 → 机体模块 → 异星工厂（Factorio）**。
+2. 启用 Factorio 集成。
+3. 填写服务器地址、端口和你的游戏内用户名；默认端口为 `34197`。
+4. 点击 **保存**。页面显示“已配置”仅代表三个字段已填写；是否能实际连接仍取决于服务器和服务端集成。
+
+## 排查
+
+* 检查服务器地址和端口能否从运行 AIRI 的设备访问。
+* 确认防火墙、VPN 和服务器白名单没有阻止连接。
+* 确认用户名与服务器中的玩家名称一致。
+* 如果配置已保存但仍不能交互，检查服务端集成的日志；AIRI 桌面端不随附一个可直接部署的 Factorio 机器人服务。
@@ -0,0 +1,36 @@
+---
+title: Minecraft 智能体
+description: 在受信任的 Minecraft 服务器上运行 AIRI 的本地游戏智能体
+---
+
+Minecraft 集成会通过 Mineflayer 连接 AIRI 与 Minecraft 服务器，让智能体接收上下文、执行游戏内动作并回传状态。它面向本地开发和维护；当前实现正计划迁移到 Fabric 运行时，不建议围绕它开发新的长期功能。
+
+## 前提条件
+
+* 已在仓库根目录安装依赖：**pnpm i**。
+* 可访问的本地或受信任 Minecraft 服务器；连接地址与端口由环境配置提供。
+* 可用的 AIRI 与模型服务配置。
+
+::: warning 凭据安全
+API Key、服务地址和 Minecraft 服务器凭据只应保存在本地 **.env.local** 文件中。不要提交、截图或发送这些配置。
+:::
+
+## 配置
+
+~~~bash
+cp services/minecraft/.env services/minecraft/.env.local
+~~~
+
+编辑 **services/minecraft/.env.local**，填写 Minecraft 服务器、AIRI 与模型服务所需的配置。
+
+## 启动
+
+~~~bash
+pnpm -F @proj-airi/minecraft-bot dev
+~~~
+
+启动后，智能体会连接 AIRI 和 Minecraft 服务器。开发环境可查看终端日志确认连接和动作状态。
+
+## 安全与限制
+
+不要将该智能体连接到不受信任的公共服务器。它会驱动本地 Minecraft 会话和网络连接；即使动作计划在隔离环境中执行，恶意服务器仍可能造成非预期行为。
@@ -0,0 +1,34 @@
+---
+title: Satori 机器人
+description: 通过 Satori 协议和 Koishi 桥接多个消息平台
+---
+
+Satori 机器人通过 Koishi 的 Satori 服务接入 QQ、Telegram、Discord、Lark 等消息平台。当前独立运行的核心是过渡实现，适合实验和维护，不应被视为稳定的 AIRI Core 集成。
+
+## 前提条件
+
+* 已在仓库根目录安装依赖：**pnpm i**。
+* 已运行启用 **server-satori** 插件的 Koishi 实例。
+* 支持 OpenAI 兼容接口的模型服务。
+
+::: warning 凭据安全
+Satori Token、消息平台凭据和模型 API Key 只应保存在本地 **.env.local** 文件中。不要提交、截图或发送这些配置。
+:::
+
+## 配置
+
+~~~bash
+cp services/satori-bot/.env services/satori-bot/.env.local
+~~~
+
+编辑 **services/satori-bot/.env.local**，填写 **SATORI_WS_URL**、**SATORI_API_BASE_URL**、可选的 **SATORI_TOKEN**，以及 LLM 的地址、密钥和模型。
+
+## 启动
+
+~~~bash
+pnpm -F @proj-airi/satori-bot dev
+~~~
+
+## 注意事项
+
+消息平台连接地址、令牌和模型凭据都属于敏感配置，不要提交 **.env.local** 或将其内容发送给他人。
@@ -0,0 +1,44 @@
+---
+title: Telegram 机器人
+description: 使用 Telegram Bot、Postgres 与模型服务运行 AIRI 消息机器人
+---
+
+Telegram 机器人需要 Telegram Bot Token、Postgres（含 pgvector）和模型服务。它面向从源码运行的集成场景。
+
+## 前提条件
+
+* 已在仓库根目录安装依赖：**pnpm i**。
+* 已从 [@BotFather](https://t.me/BotFather) 创建 Telegram Bot 并取得 Token。
+* Docker 可用于启动仓库提供的 Postgres 与 pgvector 服务。
+* 可用的聊天模型和嵌入模型服务。
+
+::: warning 凭据安全
+Telegram Bot Token、数据库连接和模型 API Key 只应保存在本地 **.env.local** 文件中。不要提交、截图或发送这些配置。
+:::
+
+## 配置
+
+~~~bash
+cp services/telegram-bot/.env services/telegram-bot/.env.local
+~~~
+
+编辑 **services/telegram-bot/.env.local**，填写 **TELEGRAM_BOT_TOKEN**、数据库连接、聊天模型与嵌入模型配置。
+
+## 初始化数据库
+
+~~~bash
+cd services/telegram-bot
+docker compose up -d
+cd ../..
+pnpm -F @proj-airi/telegram-bot db:push
+~~~
+
+## 启动
+
+~~~bash
+pnpm -F @proj-airi/telegram-bot start
+~~~
+
+## 注意事项
+
+数据库、Telegram Token 和模型凭据都属于敏感信息。不要提交 **.env.local**；首次部署前也应确认数据库备份和访问控制。
@@ -0,0 +1,32 @@
+---
+title: X / Twitter
+description: 使用 X Developer Platform 凭据启用 AIRI 的 X / Twitter 集成
+---
+
+X / Twitter 集成使用 X Developer Platform 应用的四项凭据，让 AIRI 的服务通道能够请求 X / Twitter 功能。凭据由你自己的 X 开发者账号签发；是否具备读取、发布或其他能力取决于该应用已获授的权限和 X 的套餐限制。
+
+## 前提条件
+
+* 一个可使用 [X Developer Portal](https://developer.x.com/en/portal/dashboard) 的 X 开发者账号。
+* 一个已创建的 X 应用，并已生成 API Key、API Secret、Access Token 和 Access Token Secret。
+* 应用拥有你要使用的 API 权限。
+
+::: warning 凭据安全
+API Key、API Secret、Access Token 与 Access Token Secret 等同于应用的访问凭据。只在 AIRI 的本机设置中填写它们；不要提交到仓库、放进截图、贴到 Issue 或发送给他人。怀疑泄露时，请立即在 X Developer Portal 中重新生成对应凭据。
+:::
+
+## 在 AIRI 中配置
+
+1. 打开 **设置 → 机体模块 → X / Twitter**。
+2. 启用 X / Twitter 集成。
+3. 分别填写 API Key、API Secret、Access Token 与 Access Token Secret。
+4. 点击 **保存**。四项字段均非空时，页面会显示“已配置”。
+
+“已配置”表示 AIRI 已保存凭据，并不保证所有请求都能成功；X 会根据应用权限、账号状态、访问套餐和速率限制决定实际结果。
+
+## 排查
+
+* 重新复制四项凭据，确认没有多余空格或把 Key 与 Secret 填反。
+* 在 X Developer Portal 检查应用的权限是否覆盖当前操作。
+* 检查应用、项目和开发者账号是否处于可用状态，以及当前套餐是否允许该 API 请求。
+* 请求被拒绝或被限速时，查看 X 返回的错误信息并等待其限制窗口结束；不要通过重复请求绕过限速。
@@ -38,4 +38,4 @@ description: 为 AIRI 配置语音合成（TTS）和语音识别（ASR/STT）

 ## 下一步

-如需了解 API Key、Base URL 和验证流程的含义，请阅读[通用配置说明](./common.md)。
+如需了解 API Key、Base URL 和验证流程的含义，请阅读[通用配置说明](./common.md)。如需了解如何配置服务商，可展开侧栏“服务商→ 语音合成/语音识别”，并选择您想要的提供商。
@@ -18,8 +18,8 @@ description: 为 Project AIRI 配置聊天、视觉、语音合成和语音识
 * **[配置聊天模型](./llm.md)**：配置 LLM，并在“意识”中选择模型。
 * **[配置语音输入与输出](./audio.md)**：配置 TTS 和 ASR/STT，并在“发声”和“听觉”中启用它们。
 * **[配置视觉理解](./vision.md)**：让 AIRI 使用已配置聊天服务商中支持图像输入的模型。
-* **[配置艺术创作](./providers/artistry/index.md)**：选择本地 ComfyUI 或云端图像生成服务商。
-* **[支持的服务商目录](./providers/catalog.md)**：查看当前版本已注册的聊天、视觉、语音合成和语音识别服务商。
+* **[配置网络搜索](./web-search.md)**：使用 Tavily 让 AIRI 在需要时联网搜索最新信息。
+* **服务商**：从侧栏中展开“服务商”菜单，按聊天、语音合成、语音识别或艺术创作进入对应配置指南。艺术创作需要本地工作流时选择 ComfyUI；需要云端生成时选择 Replicate 或 Nano Banana。

 > [!TIP]
 > 如果你只想先验证 AIRI 能否工作，请先配置聊天服务商。TTS 和 ASR 可以在聊天正常后再添加，这样更容易定位问题。
@@ -15,7 +15,7 @@ description: 为 AIRI 配置聊天服务商和模型

 1. 打开 **设置 → 服务商 → 聊天**，选择你要使用的服务商。

-   不确定选哪个时，可先从已有的详细指南中选择：[OpenRouter](./providers/consciousness/openrouter.md)、[DeepSeek](./providers/consciousness/deepseek.md)、[OpenAI 兼容 API](./providers/consciousness/openai.md)，或本地的 [Ollama](./providers/consciousness/ollama.md)。完整列表见[支持的服务商目录](./providers/catalog.md)。
+   不确定选哪个时，可先从已有的详细指南中选择：[OpenRouter](./providers/consciousness/openrouter.md)、[DeepSeek](./providers/consciousness/deepseek.md)、[OpenAI 兼容 API](./providers/consciousness/openai.md)，或本地的 [Ollama](./providers/consciousness/ollama.md)。其他聊天服务商可从侧栏“服务商 → 聊天服务商”展开查看。

 2. 填写 API Key。若服务商提供了专用的 API 地址，再在高级设置中填写 Base URL；否则保留默认值。

@@ -27,12 +27,13 @@ ComfyUI 让 AIRI 使用你本机或可信局域网中的图像生成工作流。
 4. 在“工作流”区域上传 API 工作流 JSON，填写名称，并选择要让 AIRI 暴露的输入字段。
 5. 保存工作流，并将它设为活动工作流。

-### 3. 配置校验
+## 第三步：验证配置

-1. 打开 **设置 → 艺术**，选择 **ComfyUI**。
-2. 选择刚保存的工作流，使用一条不含敏感信息的提示词发起生成。
-3. ComfyUI 完成任务并返回图片，即表示连接、工作流和可暴露字段配置成功。
+1. 在 **设置 → 意识（Consciousness）** 中选择支持 Tool Calling / Function Calling（工具／函数调用）的聊天模型。AIRI 需要由该模型调用 ComfyUI 图像生成工具。
+2. 打开 **设置 → 艺术**，选择 **ComfyUI**。
+3. 选择刚保存的工作流，使用一条不含敏感信息的提示词发起生成。
+4. 在 ComfyUI 的 Queue 或 History 中确认任务出现；工作流完成并返回图片，即表示连接、工作流、聊天模型和可暴露字段配置成功。

 ## 排查

-测试连接失败时，检查 ComfyUI 是否运行、Server URL、端口和网络访问。浏览器报跨域错误时，按 ComfyUI 设置页显示的 CORS 启动参数重新启动服务。工作流无法执行时，确认导入的是 API 格式 JSON，所用节点和模型已在 ComfyUI 中安装。
+测试连接失败时，检查 ComfyUI 是否运行、Server URL、端口和网络访问。浏览器报跨域错误时，按 ComfyUI 设置页显示的 CORS 启动参数重新启动服务。工作流无法执行时，确认导入的是 API 格式 JSON，所用节点和模型已在 ComfyUI 中安装。若 ComfyUI Queue 中没有新任务，检查当前聊天服务商与模型是否支持并启用了 Tool Calling / Function Calling；仅支持文本对话的模型无法触发生成工具。
@@ -1,10 +0,0 @@
---
-title: 艺术创作服务商
-description: 为 AIRI 的艺术模块配置图像生成服务商
---
-
-艺术模块用于让 AIRI 生成图片。当前支持 [ComfyUI](./comfyui.md)、[Replicate](./replicate.md) 和 [Nano Banana](./nanobanana.md)。先配置一个服务商，再到 **设置 → 艺术** 选择它。
-
-::: info 如何选择？
-希望自定义工作流或在本地运行，选择 ComfyUI；希望使用云端模型，选择 Replicate 或 Nano Banana。
-:::
@@ -25,7 +25,7 @@ Nano Banana 使用 Google AI Studio API Key 生成图片。完成配置后，可
 2. 选择默认模型：`gemini-3.1-flash-image-preview`、`gemini-3-pro-image-preview` 或 `gemini-2.5-flash-image`。
 3. 选择默认分辨率：1K、2K 或 4K。

-### 3. 配置校验
+## 第三步：验证配置

 1. 打开 **设置 → 艺术**，选择 **Nano Banana**。
 2. 使用一条不含敏感信息的提示词生成图片。
@@ -26,7 +26,7 @@ Replicate 让 AIRI 使用云端图像生成模型。完成配置后，可在 **
 3. 填写默认模型 ID。AIRI 默认值为 `black-forest-labs/flux-schnell`；请以 Replicate 模型页面显示的精确 ID 为准。
 4. 根据需要设置默认画面比例（默认 `16:9`）和推理步数（默认 4）。

-### 3. 配置校验
+## 第三步：验证配置

 1. 打开 **设置 → 艺术**，选择 **Replicate**。
 2. 使用一条不含敏感信息的提示词生成图片。
@@ -1,72 +0,0 @@
---
-title: 支持的服务商目录
-description: 查看当前版本 AIRI 支持的聊天、视觉、语音合成与语音识别服务商
---
-
-本页根据 AIRI 当前的服务商注册表整理。服务商会随版本变化，以 **设置 → 服务商** 页面实际显示的列表为准。先在该页面完成凭据配置，再在“意识”“发声”或“听觉”模块中选用它。
-
-## 聊天模型
-
-下列服务商在 AIRI 中注册为聊天服务商：
-
-| 服务商 | 类型 | 配置说明 |
-| --- | --- | --- |
-| AIRI 官方提供商 | 托管 | [查看指南](./consciousness/official.md) |
-| 302.AI、DeepSeek、Fireworks AI、Groq、MiniMax、Mistral、Moonshot、NVIDIA NIM、Novita、OpenRouter、Perplexity、Together.ai、Z.ai | 云端 API | 已提供各自的中文指南；从侧栏“聊天”分类进入。 |
-| MiniMax Global | 云端 API | [查看指南](./consciousness/minimax-global.md) |
-| OpenAI、OpenAI 兼容 API | 云端 API | [查看指南](./consciousness/openai.md) |
-| Anthropic | 云端 API | [查看指南](./consciousness/anthropic.md) |
-| Google Gemini | 云端 API | [查看指南](./consciousness/google-gemini.md) |
-| xAI | 云端 API | [查看指南](./consciousness/xai.md) |
-| Cloudflare Workers AI | 账户级云端 API | [查看指南](./consciousness/cloudflare-workers-ai.md) |
-| Ollama、LM Studio | 本地服务 | [Ollama](./consciousness/ollama.md)；[LM Studio](./consciousness/lm-studio.md) |
-| AIHubMix | 云端 API | [查看指南](./consciousness/aihubmix.md) |
-| Amazon Bedrock | 账户级云端 API | [查看指南](./consciousness/amazon-bedrock.md) |
-| Azure AI Foundry | 账户级云端 API | [查看指南](./consciousness/azure-ai-foundry.md) |
-| Azure OpenAI | 账户级云端 API | [查看指南](./consciousness/azure-openai.md) |
-| BytePlus | 云端 API | [查看指南](./consciousness/byteplus.md) |
-| BytePlus Coding Plan | 云端 API | [查看指南](./consciousness/byteplus-coding-plan.md) |
-| Cerebras | 云端 API | [查看指南](./consciousness/cerebras.md) |
-| CometAPI | 云端 API | [查看指南](./consciousness/comet-api.md) |
-| Featherless.ai | 云端 API | [查看指南](./consciousness/featherless.md) |
-| 小米 MiMo | 云端 API | [查看指南](./consciousness/mimo.md) |
-| ModelScope | 云端 API | [查看指南](./consciousness/modelscope.md) |
-| n1n | 云端 API | [查看指南](./consciousness/n1n.md) |
-| 火山引擎 Coding Plan | 云端 API | [查看指南](./consciousness/volcengine-coding-plan.md) |
-
-## 语音合成（TTS）
-
-当前注册的语音合成服务商包括云端服务、本地服务和浏览器内置能力。具体可用项目仍以 **设置 → 服务商 → 语音合成** 为准。
-
-* [AIRI 官方语音合成](./speech/official.md)、[阿里云百炼](./speech/alibaba-cloud-model-studio.md)、[ElevenLabs](./speech/elevenlabs.md)、[Deepgram](./speech/deepgram.md)、[Microsoft Azure Speech](./speech/azure-speech.md)、[MiniMax Speech](./speech/minimax.md)、[小米 MiMo](./speech/mimo.md)、[CometAPI](./speech/comet-api.md) 和 [火山引擎](./speech/volcengine.md)。
-* [Google Gemini](./speech/google-gemini.md)、[OpenAI 与兼容 API](./speech/openai.md)、[OpenRouter](./speech/openrouter.md)。
-* [Index-TTS](./speech/index-tts.md)、[Kokoro](./speech/kokoro.md)、[Player2 Speech](./speech/player2.md)、[浏览器本地语音合成](./speech/browser-local.md) 和 [桌面端本地语音合成](./speech/desktop-local.md)。
-
-## 语音识别（ASR/STT）
-
-当前注册的语音识别服务商包括云端 API、浏览器内置识别与本地识别。具体可用项目仍以 **设置 → 服务商 → 语音识别** 为准。
-
-* [AIRI 官方语音识别](./transcription/official.md)、[阿里云 NLS](./transcription/aliyun.md)、[CometAPI](./transcription/comet-api.md)、[小米 MiMo](./transcription/mimo.md) 与 [OpenAI 和兼容 API](./transcription/openai.md)。
-* [浏览器 Web Speech API](./transcription/web-speech-api.md)、[浏览器本地语音识别](./transcription/browser-local.md) 和 [桌面端本地语音识别](./transcription/desktop-local.md)。
-
-## 视觉理解
-
-视觉理解服务从已配置的聊天服务商派生，不需要单独申请另一套 API Key。选择支持图像输入的模型后，即可让 AIRI 分析图片。
-
-* [查看视觉理解配置指南](../vision.md)。
-
-## 艺术创作
-
-艺术模块使用所选服务商生成图片。当前注册的艺术服务商如下：
-
-| 服务商 | 类型 | 配置说明 |
-| --- | --- | --- |
-| ComfyUI | 本地工作流 | [查看指南](./artistry/comfyui.md) |
-| Replicate | 云端图像生成 | [查看指南](./artistry/replicate.md) |
-| Nano Banana | 云端图像生成 | [查看指南](./artistry/nanobanana.md) |
-
-## 选择建议
-
-* 想快速开始：先选择一个已提供详细指南的聊天服务商。
-* 重视隐私或离线使用：选择 Ollama 或 LM Studio，并确认本地服务已启动。
-* 需要完整语音交互：在聊天正常后，再分别配置 TTS 与 ASR/STT。
@@ -26,10 +26,10 @@ is_openai_compatible: true
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.302.ai/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API 密钥是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API 密钥是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -13,12 +13,19 @@ AIHubMix 在 AIRI 中提供聊天模型，并可列出账户可用模型。

 1. 打开并登录 [AIHubMix](https://aihubmix.com/)，在控制台创建 API Key。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → AIHubMix**，填写 **API Key**。默认 Base URL 为 `https://aihubmix.com/v1/`。
-2. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-3. **选择模型**：测试成功后，选择你想使用的具体模型；然后到 **设置 → 意识** 启用它。
-
 ::: warning API Key 安全
 不要将 API Key 提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → AIHubMix**，填写 **API Key**。默认 Base URL 为 `https://aihubmix.com/v1/`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，选择你想使用的具体模型；然后到 **设置 → 意识** 启用它。
+
+## 排查
+
+Ping API 失败时，检查 API Key、账户余额与网络连接。模型列表无法加载时，确认 Base URL 保持为默认值，或在“意识”页面输入 AIHubMix 提供的精确模型 ID。
@@ -13,13 +13,20 @@ Amazon Bedrock 使用 AWS 凭据和区域来访问已获授权的基础模型。

 1. 打开并登录 [AWS Management Console](https://console.aws.amazon.com/bedrock/)，创建具备 Bedrock 权限的访问凭据。

+::: warning AWS 凭据安全
+不要公开 AWS 访问密钥。请使用权限最小化的凭据，并在不再使用时撤销。
+:::
+
 ## 第二步：在 AIRI 中配置

 1. 打开 **设置 → 服务商 → 聊天 → Amazon Bedrock**，填写 AWS **API Key**，并选择区域；默认区域为 `us-east-1`。
 2. 确认该 AWS 账户已在对应区域获得目标模型的访问权限。只有在使用自定义 Bedrock Endpoint 时才填写自定义地址。
-3. **Ping API**：点击此按钮测试凭据、区域和网络是否正确。
-4. **选择模型**：测试成功后，选择账户已授权的模型，再到 **设置 → 意识** 启用。

-::: warning AWS 凭据安全
-不要公开 AWS 访问密钥。请使用权限最小化的凭据，并在不再使用时撤销。
-:::
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试凭据、区域和网络是否正确。
+2. **选择模型**：测试成功后，选择账户已授权的模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+验证失败时，检查 AWS 凭据、所选区域与模型访问权限是否属于同一账户。模型无法选择时，先在 Bedrock 控制台为该区域申请并启用对应模型。
@@ -11,7 +11,7 @@ Anthropic 服务商让 AIRI 使用 Claude 聊天模型。AIRI 使用 Anthropic

 ## 第一步：创建 API Key

-1. 在 Anthropic 控制台创建一个 API Key，并确认账户已开通 API 使用权限。
+1. 打开并登录 [Anthropic 控制台](https://platform.claude.com/settings/keys)，创建 API Key，并确认账户已开通 API 使用权限。
 2. 为密钥设置适当的名称、有效期和额度限制。
 3. 复制密钥并妥善保存。

@@ -25,10 +25,10 @@ Anthropic 服务商让 AIRI 使用 Claude 聊天模型。AIRI 使用 Anthropic
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.anthropic.com/v1/`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -0,0 +1,35 @@
+---
+title: Atlas Cloud
+description: 在 AIRI 中配置 Atlas Cloud 作为大模型服务商
+is_openai_compatible: true
+---
+
+Atlas Cloud 是一个兼容 OpenAI 格式的聊天 API 服务商。完成本页配置后，AIRI 可以在"意识"中使用 Atlas Cloud 提供的聊天模型。
+
+::: info 为什么选择 Atlas Cloud？
+如果你已经拥有 Atlas Cloud API Key，或希望使用其提供的模型，可以直接选择此服务商。
+:::
+
+## 第一步：获取 API 密钥
+
+1. 前往 [Atlas Cloud](https://api.atlascloud.ai/) 注册账号并创建 API Key。
+2. 复制密钥并妥善保存。
+
+::: warning API Key 安全
+不要将 API Key 提交到仓库、放入截图，或发送给他人。密钥泄露后，请立即在 Atlas Cloud 控制台撤销它并创建新密钥。
+:::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → Atlas Cloud**。
+2. 将 API Key 粘贴到基础设置。
+3. 保留默认 Base URL：`https://api.atlascloud.ai/v1`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。
+
+## 排查
+
+如果 Ping API 失败，请检查 API Key、账户额度和网络连接。模型列表无法加载时，可在"意识"页面手动输入 Atlas Cloud 提供的精确模型 ID。
@@ -13,13 +13,20 @@ Azure AI Foundry 需要资源名称、模型部署信息和 API Key。

 1. 打开并登录 [Azure AI Foundry](https://ai.azure.com/)，创建或打开目标项目并取得 API Key、资源名称和模型部署信息。

+::: warning API Key 安全
+不要将 Azure API Key 提交到仓库、截图或发送给他人。
+:::
+
 ## 第二步：在 AIRI 中配置

 1. 打开 **设置 → 服务商 → 聊天 → Azure AI Foundry**，填写 **API Key**、资源名称和模型 ID。
 2. 如控制台要求特定 API 版本，请在界面中填写；不要将普通模型名误作部署名。
-3. **Ping API**：点击此按钮测试网络、资源名称和 API Key 是否正确。
-4. **选择模型**：测试成功后，选择可用部署，再到 **设置 → 意识** 启用。

-::: warning API Key 安全
-不要将 Azure API Key 提交到仓库、截图或发送给他人。
-:::
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络、资源名称和 API Key 是否正确。
+2. **选择模型**：测试成功后，选择可用部署，再到 **设置 → 意识** 启用。
+
+## 排查
+
+验证失败时，检查 API Key、资源名称、部署名和 API 版本是否都来自同一 Azure AI Foundry 项目。请使用部署名，不要使用仅用于展示的模型名称。
@@ -13,13 +13,20 @@ Azure OpenAI 通过你的 Azure 资源端点和部署访问模型。

 1. 打开并登录 [Azure Portal](https://portal.azure.com/)，创建或打开 Azure OpenAI 资源并取得端点和 API Key。

+::: warning API Key 安全
+不要将 Azure API Key 提交到仓库、截图或发送给他人。
+:::
+
 ## 第二步：在 AIRI 中配置

 1. 打开 **设置 → 服务商 → 聊天 → Azure OpenAI**，填写 **API Key** 和 Azure OpenAI 端点。
 2. 建议填写控制台提供的完整 Chat Completions 地址；如果地址中包含部署名与 `api-version`，AIRI 会据此识别配置。
-3. **Ping API**：点击此按钮测试网络、端点和 API Key 是否正确。
-4. **选择模型**：测试成功后，选择对应部署，再到 **设置 → 意识** 启用。

-::: warning API Key 安全
-不要将 Azure API Key 提交到仓库、截图或发送给他人。
-:::
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络、端点和 API Key 是否正确。
+2. **选择模型**：测试成功后，选择对应部署，再到 **设置 → 意识** 启用。
+
+## 排查
+
+验证失败时，检查 API Key、端点、部署名和 `api-version` 是否都来自同一 Azure OpenAI 资源。请使用部署名，不要使用仅用于展示的模型名称。
@@ -13,12 +13,19 @@ BytePlus Coding Plan 在 AIRI 中以独立服务商卡片提供。

 1. 打开并登录 [BytePlus Console](https://console.byteplus.com/)，在 Coding Plan 对应页面取得凭据和端点信息。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → BytePlus Coding Plan**，按 BytePlus 控制台填写该计划的凭据和端点信息。
-2. **Ping API**：点击此按钮测试网络与凭据是否正确。
-3. **选择模型**：测试成功后，在 **设置 → 意识** 选择可用模型。
-
 ::: warning API Key 安全
 不要将 API Key 或端点凭据提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → BytePlus Coding Plan**，按 BytePlus 控制台填写该计划的凭据和端点信息。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络与凭据是否正确。
+2. **选择模型**：测试成功后，在 **设置 → 意识** 选择可用模型。
+
+## 排查
+
+验证失败时，检查凭据和端点是否属于同一 BytePlus Coding Plan。模型无法加载时，确认该计划已开通目标模型的访问权限。
@@ -13,13 +13,20 @@ BytePlus 在 AIRI 中使用 Ark 兼容的聊天服务配置。

 1. 打开并登录 [BytePlus Console](https://console.byteplus.com/)，创建或查看 Ark 端点及其访问凭据。

+::: warning API Key 安全
+不要将 API Key 或端点凭据提交到仓库、截图或发送给他人。
+:::
+
 ## 第二步：在 AIRI 中配置

 1. 打开 **设置 → 服务商 → 聊天 → BytePlus**，按照 BytePlus 控制台填写 API Key、端点或模型信息。
 2. 不要猜测 Endpoint ID；请复制控制台中已创建端点的实际标识。
-3. **Ping API**：点击此按钮测试网络与凭据是否正确。
-4. **选择模型**：测试成功后，到 **设置 → 意识** 选择该服务商与模型。

-::: warning API Key 安全
-不要将 API Key 或端点凭据提交到仓库、截图或发送给他人。
-:::
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络与凭据是否正确。
+2. **选择模型**：测试成功后，到 **设置 → 意识** 选择该服务商与模型。
+
+## 排查
+
+验证失败时，检查 API Key、Endpoint ID 与模型信息是否来自同一 BytePlus Ark 项目。不要手动猜测 Endpoint ID；请从控制台复制实际标识。
@@ -13,12 +13,19 @@ Cerebras 在 AIRI 中通过其兼容 API 提供聊天模型。

 1. 打开并登录 [Cerebras Cloud](https://cloud.cerebras.ai/)，创建 API Key。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → Cerebras**，填写 **API Key**。默认 Base URL 为 `https://api.cerebras.ai/v1/`。
-2. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-3. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
-
 ::: warning API Key 安全
 不要将 API Key 提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → Cerebras**，填写 **API Key**。默认 Base URL 为 `https://api.cerebras.ai/v1/`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+Ping API 失败时，检查 API Key、账户状态与网络连接。模型列表无法加载时，确认 Base URL 保持为默认值，或在“意识”页面输入 Cerebras 提供的精确模型 ID。
@@ -11,9 +11,9 @@ Cloudflare Workers AI 使用账户级凭据。除 API Token 外，AIRI 还需要

 ## 第一步：准备凭据

-1. 在 Cloudflare 控制台创建具有 Workers AI 访问权限的 API Token。
+1. 打开 [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens)，创建具有 Workers AI 访问权限的 API Token。
 2. 复制该 Token。
-3. 在 Cloudflare 控制台中找到并复制 Account ID。
+3. 在 [Cloudflare 控制台](https://dash.cloudflare.com/)中找到并复制 Account ID。

 ::: warning 安全提醒
 API Token 与账户权限绑定。请遵循最小权限原则，只授予 AIRI 所需的 Workers AI 权限；不要将 Token 或 Account ID 与公开日志一同发布。
@@ -24,10 +24,10 @@ API Token 与账户权限绑定。请遵循最小权限原则，只授予 AIRI
 1. 打开 **设置 → 服务商 → 聊天 → Cloudflare Workers AI**。
 2. 填写 **API Token** 与 **Account ID**。

-### 3. 配置校验
+## 第三步：验证配置

 1. 确认基础凭据验证通过。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -13,12 +13,19 @@ CometAPI 在 AIRI 中提供聊天模型，也有独立的 TTS 与 STT 服务商

 1. 打开并登录 [CometAPI 控制台](https://www.cometapi.com/console/token)，创建 API Key。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → CometAPI**，填写 **API Key**。默认 Base URL 为 `https://api.cometapi.com/v1/`。
-2. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-3. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
-
 ::: warning API Key 安全
 不要将 API Key 提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → CometAPI**，填写 **API Key**。默认 Base URL 为 `https://api.cometapi.com/v1/`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+Ping API 失败时，检查 API Key、账户额度与网络连接。模型列表无法加载时，确认 Base URL 保持为默认值，或在“意识”页面输入 CometAPI 提供的精确模型 ID。
@@ -26,10 +26,10 @@ DeepSeek 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIRI
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.deepseek.com/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -13,12 +13,19 @@ Featherless.ai 在 AIRI 中通过兼容 API 提供聊天模型。

 1. 打开并登录 [Featherless.ai](https://featherless.ai/)，在账户控制台创建 API Key。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → Featherless.ai**，填写 **API Key**。默认 Base URL 为 `https://api.featherless.ai/v1/`。
-2. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-3. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
-
 ::: warning API Key 安全
 不要将 API Key 提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → Featherless.ai**，填写 **API Key**。默认 Base URL 为 `https://api.featherless.ai/v1/`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+Ping API 失败时，检查 API Key、账户状态与网络连接。模型列表无法加载时，确认 Base URL 保持为默认值，或在“意识”页面输入 Featherless.ai 提供的精确模型 ID。
@@ -26,10 +26,10 @@ Fireworks AI 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，A
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.fireworks.ai/inference/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -11,7 +11,7 @@ Google Gemini 服务商使用 Google Generative Language API 的 OpenAI 兼容

 ## 第一步：创建 API Key

-1. 在 Google AI 的开发者控制台创建 Gemini API Key。
+1. 打开并登录 [Google AI Studio API Keys](https://aistudio.google.com/app/apikey)，创建 Gemini API Key。
 2. 确认密钥所属项目已启用 Gemini API，且可使用目标模型。
 3. 复制 API Key。

@@ -25,10 +25,10 @@ Google Gemini 服务商使用 Google Generative Language API 的 OpenAI 兼容
 2. 填写 API Key。
 3. 保留默认 Base URL：`https://generativelanguage.googleapis.com/v1beta/openai/`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -26,10 +26,10 @@ Groq 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIRI 可
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.groq.com/openai/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -11,7 +11,7 @@ LM Studio 可以在本机运行模型并提供本地 API。它适合希望在自

 ## 第一步：启动本地服务

-1. 在 LM Studio 中下载并加载一个聊天模型。
+1. 从 [LM Studio 下载页](https://lmstudio.ai/download)安装并打开 LM Studio，然后下载并加载一个聊天模型。
 2. 打开 **Local Server**，启动本地服务器。
 3. 如果 AIRI 无法访问本地服务，请在 LM Studio 的服务器设置中启用 CORS。

@@ -21,10 +21,10 @@ LM Studio 可以在本机运行模型并提供本地 API。它适合希望在自
 2. 保留默认 Base URL：`http://localhost:1234/v1/`。
 3. 如你的 LM Studio 服务需要鉴权，再填写 API Key；否则留空。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试 AIRI 能否连接本地服务。
-2. **选择模型**: 测试成功后，点击此处选择已加载的模型。
+1. **Ping API**：点击此按钮测试 AIRI 能否连接本地服务。
+2. **选择模型**：测试成功后，点击此处选择已加载的模型。

 ## 排查

@@ -13,12 +13,19 @@ description: 在 AIRI 中配置小米 MiMo 聊天模型

 1. 打开并登录 [小米 MiMo 平台](https://platform.xiaomimimo.com/)，创建 API Key。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → Xiaomi MiMo**，填写 **API Key**。默认 Base URL 为 `https://api.xiaomimimo.com/v1/`。
-2. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-3. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
-
 ::: warning API Key 安全
 不要将 API Key 提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → Xiaomi MiMo**，填写 **API Key**。默认 Base URL 为 `https://api.xiaomimimo.com/v1/`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+Ping API 失败时，检查 API Key、账户状态与网络连接。模型列表无法加载时，确认 Base URL 保持为默认值，或在“意识”页面输入小米 MiMo 提供的精确模型 ID。
@@ -26,7 +26,7 @@ is_openai_compatible: true
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.minimax.io/v1/`。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型**：测试成功后，点击此处选择你想使用的具体模型。
@@ -26,10 +26,10 @@ is_openai_compatible: true
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.minimaxi.com/v1/`。中国大陆和海外平台的 API Key、计费与 Base URL 不能混用。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -26,10 +26,10 @@ Mistral 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIRI
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.mistral.ai/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -13,12 +13,19 @@ ModelScope 在 AIRI 中通过其推理 API 提供聊天模型。

 1. 打开并登录 [ModelScope](https://modelscope.cn/)，在账户控制台创建 API Key。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → ModelScope**，填写 **API Key**。默认 Base URL 为 `https://api-inference.modelscope.cn/v1/`。
-2. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-3. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
-
 ::: warning API Key 安全
 不要将 API Key 提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → ModelScope**，填写 **API Key**。默认 Base URL 为 `https://api-inference.modelscope.cn/v1/`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+Ping API 失败时，检查 API Key、账户状态与网络连接。模型列表无法加载时，确认 Base URL 保持为默认值，或在“意识”页面输入 ModelScope 提供的精确模型 ID。
@@ -26,10 +26,10 @@ Moonshot 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIRI
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.moonshot.cn/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -13,13 +13,20 @@ n1n 在 AIRI 中提供兼容 API 的聊天模型接入。

 1. 打开并登录 [n1n](https://n1n.ai/)，确认你的服务地址及是否需要 API Key。

+::: warning 凭据安全
+即使 API Key 为可选项，也不要公开你的私有服务地址、访问令牌或网关配置。
+:::
+
 ## 第二步：在 AIRI 中配置

 1. 打开 **设置 → 服务商 → 聊天 → n1n**。默认 Base URL 为 `https://api.n1n.ai/v1/`。
 2. 按 n1n 当前服务要求填写 API Key；如果你的部署允许匿名访问，则按部署方说明保留为空。
-3. **Ping API**：点击此按钮测试网络、服务地址和凭据是否正确。
-4. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。

-::: warning 凭据安全
-即使 API Key 为可选项，也不要公开你的私有服务地址、访问令牌或网关配置。
-:::
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络、服务地址和凭据是否正确。
+2. **选择模型**：测试成功后，选择模型，再到 **设置 → 意识** 启用。
+
+## 排查
+
+验证失败时，检查服务地址、API Key 与部署方的访问策略。若服务允许匿名访问，请按部署方说明留空 API Key，并确认该地址可从运行 AIRI 的设备访问。
@@ -26,10 +26,10 @@ Novita AI 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIRI
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.novita.ai/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -26,10 +26,10 @@ NVIDIA NIM 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIR
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://integrate.api.nvidia.com/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -34,10 +34,10 @@ Ollama 是开源的本地大模型运行框架。它可以在自己的设备上
 2. 保留默认 Base URL：`http://localhost:11434/v1/`；如果 Ollama 运行在其他设备上，填写该设备可访问的地址。
 3. 在“意识”中选择 Ollama 与刚才下载的模型。

-### 4. 配置校验
+## 第四步：验证配置

-1. **Ping API**: 点击此按钮测试 AIRI 能否连接本地服务。
-2. **选择模型**: 测试成功后，点击此处选择已下载的模型。
+1. **Ping API**：点击此按钮测试 AIRI 能否连接本地服务。
+2. **选择模型**：测试成功后，点击此处选择已下载的模型。

 ## 排查

@@ -12,7 +12,7 @@ is_openai_compatible: true

 ## 第一步：获取 API 密钥

-1. 登录所选服务商的管理控制台。
+1. 使用 OpenAI 官方服务时，打开 [OpenAI API Keys](https://platform.openai.com/api-keys) 创建 API Key；使用兼容服务时，打开对应服务商的管理控制台。
 2. 在 API 密钥或开发者设置页面创建 API Key。
 3. 复制密钥并妥善保存。

@@ -26,10 +26,10 @@ is_openai_compatible: true
 2. 将 API Key 粘贴到基础设置。
 3. 使用 OpenAI 官方服务时，保留默认 Base URL：`https://api.openai.com/v1`；使用兼容服务时，填写服务商文档提供的 API 根地址，不要附加 `/chat/completions` 路径。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -0,0 +1,35 @@
+---
+title: OpenPaths
+description: 在 AIRI 中配置 OpenPaths 作为大模型服务商
+is_openai_compatible: true
+---
+
+OpenPaths 是一个兼容 OpenAI 格式的聊天 API 服务商。完成本页配置后，AIRI 可以在"意识"中使用 OpenPaths 提供的聊天模型。
+
+::: info 为什么选择 OpenPaths？
+如果你已经拥有 OpenPaths API Key，或希望使用其提供的模型，可以直接选择此服务商。
+:::
+
+## 第一步：获取 API 密钥
+
+1. 前往 [OpenPaths](https://openpaths.io/) 注册账号并创建 API Key。
+2. 复制密钥并妥善保存。
+
+::: warning API Key 安全
+不要将 API Key 提交到仓库、放入截图，或发送给他人。密钥泄露后，请立即在 OpenPaths 控制台撤销它并创建新密钥。
+:::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → OpenPaths**。
+2. 将 API Key 粘贴到基础设置。
+3. 保留默认 Base URL：`https://openpaths.io/v1`。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。
+
+## 排查
+
+如果 Ping API 失败，请检查 API Key、账户额度和网络连接。模型列表无法加载时，可在"意识"页面手动输入 OpenPaths 提供的精确模型 ID。
@@ -27,10 +27,10 @@ OpenRouter 是一个聚合式 API 服务商。完成本页配置后，AIRI 可
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://openrouter.ai/api/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API 密钥是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型（如 **google/gemini-pro-1.5**）。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API 密钥是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型（如 **google/gemini-pro-1.5**）。

 ## 排查

@@ -26,10 +26,10 @@ Perplexity 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AIR
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.perplexity.ai`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -26,10 +26,10 @@ Together AI 提供兼容 OpenAI 格式的聊天 API。完成本页配置后，AI
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://api.together.xyz/v1`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -13,12 +13,19 @@ description: 在 AIRI 中配置火山引擎 Coding Plan 聊天模型

 1. 打开并登录[火山引擎控制台](https://console.volcengine.com/)，在 Coding Plan 对应页面取得 API Key、端点和模型信息。

-## 第二步：在 AIRI 中配置
-
-1. 打开 **设置 → 服务商 → 聊天 → Volcengine Coding Plan**，按火山引擎控制台填写该计划的 API Key、端点和模型信息。
-2. **Ping API**：点击此按钮测试网络与凭据是否正确。
-3. **选择模型**：测试成功后，在 **设置 → 意识** 选择可用模型。
-
 ::: warning API Key 安全
 不要将 API Key 或端点凭据提交到仓库、截图或发送给他人。
 :::
+
+## 第二步：在 AIRI 中配置
+
+1. 打开 **设置 → 服务商 → 聊天 → Volcengine Coding Plan**，按火山引擎控制台填写该计划的 API Key、端点和模型信息。
+
+## 第三步：验证配置
+
+1. **Ping API**：点击此按钮测试网络与凭据是否正确。
+2. **选择模型**：测试成功后，在 **设置 → 意识** 选择可用模型。
+
+## 排查
+
+验证失败时，检查 API Key、端点与模型信息是否属于同一火山引擎 Coding Plan。模型无法加载时，确认该计划已开通目标模型的访问权限。
@@ -11,7 +11,7 @@ xAI 服务商让 AIRI 使用 Grok 聊天模型。其配置方式与常见 API Ke

 ## 第一步：创建 API Key

-1. 在 xAI 开发者控制台创建 API Key。
+1. 打开并登录 [xAI 开发者控制台](https://console.x.ai/)，创建 API Key。
 2. 确认账户已开通 API 用量并有可用额度。
 3. 复制密钥。

@@ -25,10 +25,10 @@ xAI 服务商让 AIRI 使用 Grok 聊天模型。其配置方式与常见 API Ke
 2. 填写 API Key。
 3. 保留默认 Base URL：`https://api.x.ai/v1/`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -26,10 +26,10 @@ is_openai_compatible: true
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://open.bigmodel.cn/api/paas/v4/`。

-### 3. 配置校验
+## 第三步：验证配置

-1. **Ping API**: 点击此按钮测试网络是否连通以及 API Key 是否填写正确。
-2. **选择模型**: 测试成功后，点击此处选择你想要使用的具体模型。
+1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
+2. **选择模型**：测试成功后，点击此处选择你想要使用的具体模型。

 ## 排查

@@ -24,7 +24,7 @@ description: 在 AIRI 中配置阿里云百炼语音合成
 1. 打开 **设置 → 服务商 → 语音合成 → Alibaba Cloud Model Studio**。
 2. 将百炼 API Key 粘贴到基础设置；Base URL 使用界面默认值，除非你配置了兼容网关。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择 CosyVoice 模型与音色，再到 **设置 → 发声** 启用。
@@ -24,7 +24,7 @@ Azure 密钥可访问你的语音资源。不要提交、截图或分享它。
 1. 打开 **设置 → 服务商 → 语音合成 → Microsoft / Azure Speech**。
 2. 填写 API Key 和区域信息。Base URL 保持界面默认值，除非你使用兼容网关。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络、API Key 和区域是否填写正确。
 2. **选择模型和音色**：测试成功后，选择音色，并在 **设置 → 发声** 中启用。
@@ -23,7 +23,7 @@ description: 在 AIRI 网页版中使用浏览器本地语音合成
 1. 在网页版打开 **设置 → 服务商 → 语音合成 → Browser (Local)**。
 2. 等待模型准备完成，并选择模型和音色。

-### 3. 配置校验
+## 第三步：验证配置

 1. 在 **设置 → 发声** 选择该服务商、模型和音色。
 2. 输入短文本并试听；能正常播放即表示配置成功。
@@ -23,7 +23,7 @@ CometAPI 通过其兼容接口提供语音合成。
 1. 打开 **设置 → 服务商 → 语音合成 → CometAPI Speech**，填写 API Key。
 2. 保留默认 Base URL：`https://api.cometapi.com/v1/`；只有使用代理或兼容网关时才修改。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择可用模型与音色，再到 **设置 → 发声** 启用。
@@ -24,7 +24,7 @@ Deepgram 在 AIRI 中提供 Aura 系列语音合成模型。
 1. 打开 **设置 → 服务商 → 语音合成 → Deepgram**，将 API Key 粘贴到基础设置。
 2. 保留界面默认 Base URL；仅在自行部署兼容网关时修改。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择 Aura 模型与声音，再到 **设置 → 发声** 启用。
@@ -23,7 +23,7 @@ description: 在 AIRI 桌面版中使用本地语音合成
 1. 在 AIRI 桌面版打开 **设置 → 服务商 → 语音合成 → App (Local)**。
 2. 选择可用模型和音色；完成准备后，到 **设置 → 发声** 启用。

-### 3. 配置校验
+## 第三步：验证配置

 1. 输入一段短文本并试听。
 2. 能正常播放语音即表示配置成功。
@@ -25,7 +25,7 @@ ElevenLabs 可将 AIRI 的回复合成为语音。
 2. 将 API Key 粘贴到基础设置。
 3. 保留界面默认 Base URL；只有使用自己的兼容网关时才更改。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，在 **设置 → 发声** 选择模型与想使用的声音。
@@ -24,7 +24,7 @@ Google Gemini 音频语音合成会使用 Gemini 凭据和支持音频输出的
 1. 在 **设置 → 服务商 → 语音合成 → Google Gemini** 中填写 Gemini API Key。
 2. 保留界面默认 Base URL，除非你使用企业网关或兼容代理。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择界面列出的支持语音输出的模型，再到 **设置 → 发声** 启用。
@@ -24,7 +24,7 @@ Index-TTS 是通过本地 HTTP 服务接入 AIRI 的语音合成选项。
 1. 打开 **设置 → 服务商 → 语音合成 → Index-TTS by Bilibili**。
 2. 填写与本地服务一致的 Base URL。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试 AIRI 是否能连接该本地服务。
 2. **选择模型和音色**：测试成功后，选择 `IndexTTS-1.5` 和服务返回的音色；再到 **设置 → 发声** 启用。
@@ -23,7 +23,7 @@ Kokoro 在 AIRI 中以本地模型方式运行语音合成。
 1. 打开 **设置 → 服务商 → 语音合成 → Kokoro**。
 2. 选择 AIRI 提供的可用 Kokoro 模型。

-### 3. 配置校验
+## 第三步：验证配置

 1. **选择模型和音色**：模型准备完成后，选择音色，再到 **设置 → 发声** 启用。
 2. 输入短文本试听；能正常播放即表示模型已准备完成。
@@ -23,7 +23,7 @@ MiMo 支持预设音色、声音设计和声音克隆三种语音合成模式。
 1. 在 **设置 → 服务商 → 语音合成 → Xiaomi MiMo** 中填写 API Key。
 2. 保留默认 Base URL：`https://api.xiaomimimo.com/v1/`，除非服务商提供了其他地址。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择预设音色、声音设计或声音克隆模型，并在 **设置 → 发声** 启用。
@@ -24,7 +24,7 @@ MiniMax Speech 可在 AIRI 中提供语音合成模型和预设声音。
 1. 打开 **设置 → 服务商 → 语音合成 → MiniMax Speech**，粘贴 API Key。
 2. 保留默认服务地址 `https://api.minimax.io`，除非服务商明确提供了其他地址。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择如 `speech-2.8-hd` 或 `speech-2.8-turbo` 的可用模型与声音，再到 **设置 → 发声** 启用。
@@ -23,7 +23,7 @@ description: 在 AIRI 中使用官方提供的语音合成
 1. 打开 **设置 → 服务商 → 语音合成 → AIRI 官方语音合成**。
 2. 等待 AIRI 从服务端加载当前可用模型和音色。

-### 3. 配置校验
+## 第三步：验证配置

 1. 在 **设置 → 发声** 选择模型和音色，然后使用短文本试听。
 2. 能正常播放即表示配置成功。若服务端未提供流式语音，流式选项不会出现。
@@ -26,7 +26,7 @@ description: 在 AIRI 中配置 OpenAI 或兼容 OpenAI 的 API 作为语音合
 3. 使用 OpenAI 官方服务时，保留默认 Base URL：`https://api.openai.com/v1/`；使用兼容服务时，填写服务商文档提供的 API 根地址。
 4. 根据需要调整语速。

-### 3. 配置校验
+## 第三步：验证配置

 1. 在“发声”中选择已配置的服务商、模型和音色。
 2. 输入一段测试文本并点击测试。
@@ -25,7 +25,7 @@ OpenRouter 是一个聚合式 API 服务商。完成配置后，在“发声”
 2. 将 API Key 粘贴到基础设置。
 3. 保留默认 Base URL：`https://openrouter.ai/api/v1/`。

-### 3. 配置校验
+## 第三步：验证配置

 1. 在“发声”中选择已配置的服务商、模型和音色。
 2. 输入一段测试文本并点击测试。
@@ -23,7 +23,7 @@ Player2 Speech 是通过本地服务连接的语音合成选项。
 1. 打开 **设置 → 服务商 → 语音合成 → Player2 Speech**。
 2. 填写与服务地址一致的 Base URL。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试 AIRI 是否能连接该服务。
 2. **选择模型和音色**：测试成功后，选择 `player2-tts` 与服务返回的声音，再到 **设置 → 发声** 启用。
@@ -24,7 +24,7 @@ description: 在 AIRI 中配置火山引擎语音合成
 1. 打开 **设置 → 服务商 → 语音合成 → 火山引擎**。
 2. 填写 API Key 和 App ID；Base URL 使用界面默认值，除非你使用兼容网关。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络、API Key 和 App ID 是否填写正确。
 2. **选择模型和音色**：测试成功后，选择音色，再到 **设置 → 发声** 启用。
@@ -25,7 +25,7 @@ description: 在 AIRI 中配置阿里云智能语音交互服务（ASR）
 2. 填写 **AccessKey ID**、**AccessKey Secret** 和 **AppKey**。
 3. 选择距离你最近的区域，例如华东 `cn-shanghai`、华北 `cn-beijing` 或华南 `cn-shenzhen`。

-### 3. 配置校验
+## 第三步：验证配置

 1. 确认页面提示基础凭据验证通过。
 2. 在“听觉”中选择阿里云 NLS 和音频输入设备。
@@ -23,7 +23,7 @@ description: 在 AIRI 网页版中使用浏览器本地语音识别
 1. 在网页版打开 **设置 → 服务商 → 语音识别 → Browser (Local)**。
 2. 等待模型准备完成后选择模型，并在 **设置 → 听觉** 中启用。

-### 3. 配置校验
+## 第三步：验证配置

 1. 允许浏览器访问麦克风，进行一段短语音输入。
 2. 转写文字能显示即表示配置成功。
@@ -23,7 +23,7 @@ CometAPI 通过其兼容接口提供音频转写。
 1. 打开 **设置 → 服务商 → 语音识别 → CometAPI Transcription**，填写 API Key。
 2. 保留默认 Base URL：`https://api.cometapi.com/v1/`；只有使用代理或兼容网关时才修改。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型**：测试成功后，选择可用转写模型；再到 **设置 → 听觉** 启用。
@@ -23,7 +23,7 @@ description: 在 AIRI 桌面版中使用本地语音识别
 1. 在 AIRI 桌面版打开 **设置 → 服务商 → 语音识别 → App (Local)**。
 2. 选择可用模型；完成准备后，到 **设置 → 听觉** 启用。

-### 3. 配置校验
+## 第三步：验证配置

 1. 允许 AIRI 使用麦克风，并进行一段短语音输入。
 2. 识别结果能显示在 AIRI 中即表示配置成功。
@@ -23,7 +23,7 @@ MiMo 使用其原生音频理解模型完成语音转写。
 1. 在 **设置 → 服务商 → 语音识别 → Xiaomi MiMo** 中填写 API Key。
 2. 保留默认 Base URL：`https://api.xiaomimimo.com/v1/`，除非服务商提供了其他地址。

-### 3. 配置校验
+## 第三步：验证配置

 1. **Ping API**：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
 2. **选择模型**：测试成功后，选择 `mimo-v2-omni` 或界面列出的可用模型；随后到 **设置 → 听觉** 启用。
@@ -23,7 +23,7 @@ description: 在 AIRI 中使用官方提供的实时语音识别
 1. 打开 **设置 → 服务商 → 语音识别 → AIRI 官方语音识别**。
 2. 选择 `Auto` 或服务端提供的模型，再到 **设置 → 听觉** 启用。

-### 3. 配置校验
+## 第三步：验证配置

 1. 允许 AIRI 使用麦克风，并进行一段短语音输入。
 2. 转写文字能显示即表示配置成功。
@@ -25,7 +25,7 @@ description: 在 AIRI 中配置 OpenAI 或兼容 OpenAI 的 API 作为语音识
 2. 填写 API Key 和要使用的 ASR/STT 模型 ID。
 3. 使用 OpenAI 官方服务时，保留默认 Base URL：`https://api.openai.com/v1/`；使用兼容服务时，填写服务商文档提供的 API 根地址。

-### 3. 配置校验
+## 第三步：验证配置

 1. 在“听觉”中选择已配置的服务商和模型，并选择音频输入设备。
 2. 点击“开始监听”，然后对着麦克风说话或播放一段音频。
@@ -23,7 +23,7 @@ Web Speech API 仅适用于浏览器环境，AIRI 桌面版（Electron）不支
 1. 在网页版打开 **设置 → 服务商 → 语音识别 → Web Speech API**。
 2. 选择识别语言，以及需要时的连续识别和中间结果选项。

-### 3. 配置校验
+## 第三步：验证配置

 1. 前往 **设置 → 听觉** 选择 Web Speech API 和音频输入设备。
 2. 允许浏览器访问麦克风，开始一次短语音输入测试。
@@ -9,55 +9,21 @@ description: 为 AIRI 的视觉模块选择图像理解服务商和模型
 同一服务商通常同时提供聊天和图像理解模型。复用凭据可减少重复配置；你仍需选择一个明确支持图像输入的模型，纯文本模型无法完成视觉任务。
 :::

+::: warning 使用屏幕视觉前，需要启动 Vision Capture
+仅配置视觉服务商和模型时，无需开启此工具。
+
+如需让 AIRI 分析屏幕或窗口，请前往「系统 → 开发者 → Vision Capture」：授予屏幕录制权限，选择要捕获的窗口或显示器，然后点击「Start ticker」。如需将识别结果提供给 AIRI 对话，再开启「Publish to character」。
+
+Vision Capture 是当前的桌面端调试／开发工作流；离开该页面会停止捕获循环。完整说明见[桌面端开发者工具](../../contributing/desktop-developer-tools#vision-capture)。
+:::
+
 ## 第一步：选择视觉服务商

 1. 打开 **设置 → 服务商 → 视觉**。
 2. 选择一个你已经配置过或准备配置的聊天服务商。
 3. 按该服务商卡片填写凭据。字段与其聊天服务商版本一致，例如 API Key、Base URL、Azure 资源信息或 Amazon Bedrock Region。

-可用的视觉服务商来自当前聊天服务商注册表。下面每一项都会在 **设置 → 服务商 → 视觉** 中出现相同服务商的配置卡片；凭据与对应聊天页相同。
-
-## 服务商与对应聊天配置
-
-| 视觉服务商 | 对应聊天配置 |
-| --- | --- |
-| AIRI 官方提供商 | [AIRI 官方提供商](./providers/consciousness/official.md) |
-| 302.AI | [302.AI](./providers/consciousness/302ai.md) |
-| AIHubMix | [AIHubMix](./providers/consciousness/aihubmix.md) |
-| Amazon Bedrock | [Amazon Bedrock](./providers/consciousness/amazon-bedrock.md) |
-| Anthropic | [Anthropic](./providers/consciousness/anthropic.md) |
-| Azure AI Foundry | [Azure AI Foundry](./providers/consciousness/azure-ai-foundry.md) |
-| Azure OpenAI | [Azure OpenAI](./providers/consciousness/azure-openai.md) |
-| BytePlus | [BytePlus](./providers/consciousness/byteplus.md) |
-| BytePlus Coding Plan | [BytePlus Coding Plan](./providers/consciousness/byteplus-coding-plan.md) |
-| Cerebras | [Cerebras](./providers/consciousness/cerebras.md) |
-| Cloudflare Workers AI | [Cloudflare Workers AI](./providers/consciousness/cloudflare-workers-ai.md) |
-| CometAPI | [CometAPI](./providers/consciousness/comet-api.md) |
-| DeepSeek | [DeepSeek](./providers/consciousness/deepseek.md) |
-| Featherless.ai | [Featherless.ai](./providers/consciousness/featherless.md) |
-| Fireworks AI | [Fireworks AI](./providers/consciousness/fireworks.md) |
-| Google Gemini | [Google Gemini](./providers/consciousness/google-gemini.md) |
-| Groq | [Groq](./providers/consciousness/groq.md) |
-| LM Studio | [LM Studio](./providers/consciousness/lm-studio.md) |
-| MiniMax | [MiniMax](./providers/consciousness/minimax.md) |
-| MiniMax Global | [MiniMax Global](./providers/consciousness/minimax-global.md) |
-| Mistral | [Mistral](./providers/consciousness/mistral.md) |
-| ModelScope | [ModelScope](./providers/consciousness/modelscope.md) |
-| Moonshot | [月之暗面](./providers/consciousness/moonshot.md) |
-| 小米 MiMo | [小米 MiMo](./providers/consciousness/mimo.md) |
-| n1n | [n1n](./providers/consciousness/n1n.md) |
-| NVIDIA NIM | [NVIDIA NIM](./providers/consciousness/nvidia.md) |
-| Novita | [Novita](./providers/consciousness/novita.md) |
-| Ollama | [Ollama](./providers/consciousness/ollama.md) |
-| OpenAI 与兼容 API | [OpenAI 与兼容 API](./providers/consciousness/openai.md) |
-| OpenRouter | [OpenRouter](./providers/consciousness/openrouter.md) |
-| Perplexity | [Perplexity](./providers/consciousness/perplexity.md) |
-| Together.ai | [Together.ai](./providers/consciousness/together.md) |
-| xAI | [xAI](./providers/consciousness/xai.md) |
-| Z.ai | [Z.ai](./providers/consciousness/zhipu.md) |
-| 火山引擎 Coding Plan | [火山引擎 Coding Plan](./providers/consciousness/volcengine-coding-plan.md) |
-
-这表示 AIRI 有该服务商的视觉配置入口，并不表示该服务商的每一个模型都能读图。仍须在模型列表中选择明确支持图片输入的模型。
+视觉服务商与聊天服务商一一对应：先从侧栏“服务商 → 聊天服务商”完成对应服务商的配置，再在视觉页使用相同凭据。视觉入口可用不表示每个模型都能读图；仍须在模型列表中选择明确支持图像输入的模型。

 ::: warning 图像与凭据安全
 视觉分析会把画面发送给所选服务商。不要捕获包含 API Key、密码、个人信息或未经授权内容的画面；云端服务的凭据也不得提交到仓库、截图或发送给他人。
@@ -68,7 +34,7 @@ description: 为 AIRI 的视觉模块选择图像理解服务商和模型
 1. 打开 **设置 → 视觉**。
 2. 选择刚配置的服务商。
 3. 从模型列表选择支持图片或视觉输入的模型。
-4. 启用需要的视觉功能，并按页面提示选择画面来源或捕获方式。
+4. 启用需要的视觉功能，并按页面提示选择画面来源或捕获方式。如需要可以设置 Capture interval，即「捕获间隔」，用来调整捕获的时间间隔。

 ## 第三步：配置校验

@@ -0,0 +1,59 @@
+---
+title: 配置网络搜索
+description: 使用 Tavily 让 AIRI 在对话中搜索最新信息
+---
+
+网络搜索让 AIRI 在需要最新资料或不熟悉的信息时查询互联网。它使用你自己的 Tavily API Key；启用后，AIRI 会在合适的对话中自行调用搜索工具，并在回答中附上实际使用的来源链接。
+
+## 前提条件
+
+- 已安装并启动 AIRI。
+- 已拥有 Tavily 账号，并从 [Tavily](https://tavily.com/) 控制台创建 API Key。
+- 已配置可使用工具调用的聊天服务商和模型。若 AIRI 无法使用工具，请先更换为支持工具调用的模型。
+
+::: warning API Key 安全
+Tavily API Key 只应保存在当前设备。不要提交到仓库、发送给他人，或放入角色卡、日志和截图中。若怀疑密钥已泄露，请立即在 Tavily 控制台撤销它并创建新密钥。
+:::
+
+## 配置步骤
+
+1. 打开 **设置 → 机体模块 → 网络搜索**。
+2. 开启「启用网络搜索」。
+3. 在「Tavily API 密钥」中粘贴 API Key。
+4. 出现「网络搜索已就绪」后即可返回聊天；设置会自动保存，无需另点保存按钮。
+
+关闭开关或清空 API Key 后，AIRI 不会再向 Tavily 发送搜索请求。
+
+## AIRI 何时会搜索
+
+AIRI 优先使用已有知识；当你明确要求搜索，或问题涉及会快速变化的信息时，它才会使用网络搜索。比如新闻、价格、最近发布的版本、当前活动、实时榜单或最新文档。
+
+若希望它搜索得更准确，请直接说清楚目标与范围，例如：
+
+- “搜索 AIRI 最新稳定版的发行说明，并附上链接。”
+- “查找 Tavily 官方文档中有关 API Key 的说明。”
+- “只搜索 `github.com/moeru-ai/airi` 上最近一周的更新。”
+
+搜索结果会包含来源链接。AIRI 只能引用实际查询到的链接；如果回答没有找到足够的资料，应继续搜索或明确说明不确定之处。
+
+## 隐私、可靠性与安全
+
+每次搜索会将查询文字发送至 Tavily。因此不要在搜索词中包含 API Key、密码、访问令牌、私人地址或其他不应提供给第三方的信息。搜索结果也可能包含错误、过期或带有偏见的内容。
+
+::: warning 请核实重要信息
+搜索结果仅供 AIRI 参考，不会自动改变你原本的提问或操作目标。涉及账户、安全、医疗、法律或财务的内容，请打开来源链接自行核实，并优先参考官方或一手来源。
+:::
+
+## 常见问题
+
+### 显示已配置，但 AIRI 没有搜索
+
+先确认网络搜索开关仍处于开启状态，并确认当前聊天模型支持工具调用。接着直接在聊天中要求“搜索并附上来源链接”；如果仍未调用，请检查模型服务商是否允许工具调用请求。
+
+### 提示 API Key、权限或额度错误
+
+回到 Tavily 控制台确认密钥完整、仍有效，并检查账户的可用额度或访问权限。复制时不要带入前后的空格或换行；更换密钥后返回 AIRI 重新粘贴即可。
+
+### 搜索结果不准确或不够新
+
+在提问中说明时间范围、地点和希望使用的来源，例如“只查过去一周”或“仅使用官方文档”。对重要结论打开所附链接核对；网络搜索不能替代专业建议或独立判断。
--- a/Show More
+++ b/Show More