文档：添加小爱音箱集成文档

Author: jingyi0605

docs/Documentation/.vitepress/config.mts

@@ -111,6 +111,12 @@ const zhThemeConfig = createThemeConfig({
           { text: '设置', link: '/使用指南/设置' },
           { text: '插件', link: '/使用指南/插件' }
         ]
+      },
+      {
+        text: '设备集成',
+        items: [
+          { text: '小米音箱对接', link: '/使用指南/小米音箱对接' }
+        ]
       }
     ],
     '/开发文档/': [

docs/Documentation/使用指南/小米音箱对接.md

@@ -0,0 +1,186 @@
+---
+title: 小米音箱对接
+docId: zh-3.7
+version: v0.1
+status: draft
+order: 370
+outline: deep
+---
+
+# 小米音箱对接
+
+如果你想把刷好 `open-xiaoai` Client 的小米音箱接进 FamilyClaw，别绕弯路，按这个顺序做就行：
+
+1. 先刷机
+2. 再让音箱客户端连到 FamilyClaw 机器的 `4399` 端口
+3. 最后在项目里创建设备集成、同步设备，并设置响应词
+
+## 使用前先确认
+
+- FamilyClaw 已经正常运行，而且小米音箱能通过局域网访问部署这套项目的机器。
+- 你部署 FamilyClaw 的机器已经对局域网开放 `4399` 端口。
+- 你能登录 FamilyClaw，并且当前账号有家庭管理权限。
+- 你的小米音箱已经刷入可运行 `open-xiaoai` Client 的系统。
+
+## 第一部分：小米音箱刷机
+
+刷机步骤不要在这里重写一遍，直接按 `open-xiaoai` 官方刷机文档操作：
+
+- 刷机文档：
+  [open-xiaoai 官方刷机文档](https://github.com/idootop/open-xiaoai/blob/main/docs/flash.md)
+
+先看清两个前提：
+
+- 这份刷机文档当前只适用于 `小爱音箱 Pro（LX06）` 和 `Xiaomi 智能音箱 Pro（OH2P）`。
+- 数据线必须能传数据，不能只是充电线。
+
+刷机完成后，官方文档里还给了 SSH 登录方式。你能正常 SSH 进音箱，再继续下一步；连 SSH 都进不去，后面的客户端启动都是空谈。
+
+## 第二部分：启动小米音箱客户端
+
+客户端部分参考 `open-xiaoai` 的 Rust Client 文档，但这里要把 `SERVER` 地址改成你这套项目所在机器的局域网 IP，并固定使用 `4399` 端口。
+
+- 客户端文档：
+  [open-xiaoai Client 文档](https://github.com/idootop/open-xiaoai/blob/main/packages/client-rust/README.md)
+
+### 1. SSH 登录到音箱
+
+```bash
+ssh -o HostKeyAlgorithms=+ssh-rsa root@你的小米音箱IP
+```
+
+### 2. 创建客户端目录
+
+```bash
+mkdir -p /data/open-xiaoai
+```
+
+### 3. 写入 FamilyClaw 的服务端地址
+
+把下面的 IP 替换成你部署 FamilyClaw 那台机器的实际局域网 IP：
+
+```bash
+echo 'ws://192.168.31.100:4399' > /data/open-xiaoai/server.txt
+```
+
+这里别写错。这个地址不是音箱自己的 IP，也不是浏览器访问网页时随手复制出来的地址，而是 FamilyClaw 所在机器对音箱可达的地址。
+
+如果你是 Docker、NAS 或其他容器化部署，还要额外确认：
+
+- 宿主机已经把 `4399` 端口映射出来。
+- 防火墙 / 路由器没有把局域网访问拦掉。
+
+### 4. 启动客户端
+
+最省事的方式是直接按官方文档拉起启动脚本：
+
+```bash
+curl -sSfL https://gitee.com/idootop/artifacts/releases/download/open-xiaoai-client/init.sh | sh
+```
+
+如果你需要手动运行二进制，也要让它连到同一个地址：
+
+```bash
+/data/open-xiaoai/client ws://192.168.31.100:4399
+```
+
+### 5. 需要开机自启动时
+
+官方文档里也给了开机启动脚本，按它的方式配置就行。做完后重启音箱，再回到 FamilyClaw 里看是否已经发现到网关。
+
+## 第三部分：在 FamilyClaw 中添加音箱并设置响应词
+
+### 第一步：先创建“小爱音箱网关”实例
+
+打开：
+
+`设置 -> 设备与集成`
+
+然后按这个顺序操作：
+
+1. 点击 `通过实例添加设备`
+2. 在插件列表里选择 `小爱音箱网关`
+3. 填写实例名称，比如 `客厅小爱网关`
+4. 选择系统已经发现到的网关
+5. 点击 `创建实例`
+
+这里有两个关键点：
+
+- 如果系统只发现了 `1` 个可用网关，界面通常会自动绑定它。
+- 如果“已发现网关”还是空的，说明音箱客户端还没真正连上 FamilyClaw，先回去检查 IP、`4399` 端口和局域网连通性。
+
+### 第二步：把发现到的音箱同步进家庭
+
+实例创建好以后，仍然在 `设置 -> 设备与集成` 页面操作：
+
+1. 选中刚创建的 `小爱音箱网关` 实例
+2. 点击 `同步全部设备`
+3. 或者点击 `仅同步选中的设备`，只导入你想要的那几台
+
+同步完成后，这台音箱才算正式进入当前家庭，不再是“发现到了但还没纳管”的半成品状态。
+
+### 第三步：到设备详情里设置响应词
+
+现在不要继续停留在“设备与集成”页。这个页面主要负责接入和同步，不负责设备级管理。
+
+请改去这里：
+
+`家庭 -> 设备`
+
+找到刚刚导入的小米音箱，打开设备详情，然后进入 `语音接管` 页签。
+
+这里有两个配置：
+
+- `接管全部语音指令`
+  开启后，这台音箱上的所有语音请求都会直接交给 FamilyClaw，前缀就不再参与判断。
+- `响应前缀`
+  关闭全量接管时，只有以这些前缀开头的话才会进入 FamilyClaw。
+
+`响应前缀` 就是这篇文档里说的“响应词”。现在系统里的正式字段名叫“响应前缀”，别被两个叫法绕晕。
+
+### 响应词怎么填
+
+你可以按自己的习惯填写，比如：
+
+```text
+请,帮我,小管家
+```
+
+填写规则很简单：
+
+- 用逗号分隔。
+- 至少保留一个前缀，别把自己配成谁说什么都进来。
+- 如果已经打开 `接管全部语音指令`，这些前缀就不会再生效。
+
+## 常见排查
+
+### 设备与集成里看不到已发现网关
+
+先查这几件事：
+
+- `server.txt` 里写的是不是 FamilyClaw 机器的局域网 IP: `4399`
+- 音箱和 FamilyClaw 是不是在同一个局域网
+- `4399` 端口是不是已经对局域网开放
+- 客户端是不是已经真正跑起来了
+
+### 已经创建实例，但同步不到设备
+
+通常是这两类问题：
+
+- 你绑定错了网关，实例接的不是当前这台音箱所在的网关
+- 音箱客户端虽然启动了，但没有持续连到 FamilyClaw
+
+### 响应词不生效
+
+先别怀疑玄学，先检查配置本身：
+
+- `接管全部语音指令` 是不是已经打开了。打开时，前缀规则天然失效。
+- `响应前缀` 有没有写成空行、重复值或只带空格。
+- 你实际说的话是不是确实以这些前缀开头。
+
+## 相关文档
+
+- [设置](../使用指南/设置.md)
+- [家庭](../使用指南/家庭.md)
+- [open-xiaoai 官方刷机文档](https://github.com/idootop/open-xiaoai/blob/main/docs/flash.md)
+- [open-xiaoai Client 文档](https://github.com/idootop/open-xiaoai/blob/main/packages/client-rust/README.md)

docs/Documentation/使用指南/设置.md

@@ -69,3 +69,4 @@ outline: deep
 
 - 想开始聊天，去 [对话](../使用指南/对话.md)。
 - 想安装更多扩展能力，去 [插件](../使用指南/插件.md)。
+- 想把小米音箱接进来，去 [小米音箱对接](../使用指南/小米音箱对接.md)。