xiaomusic/docs/issues/655.md

---
title: 在线搜索扩展说明文档
---
# 在线搜索扩展说明文档
> **⚠️ 重要升级提示**
> 本次更新涉及到配置文件结构更新，旧版配置可能不适用。请务必手动删除 **`/conf/plugins-config.json`** 后重启，重新在网页端进行配置。

---

## 1. 功能概述

在线搜索扩展是 `xiaomusic` 的扩展功能，旨在提供在线音乐搜索与播放功能。用户可通过网页端搜索来自多个音乐平台的资源，并灵活选择**推送至小爱音箱**或**网页端在线播放**。

系统底层支持两种独立的接口生态，用户可在后台**二选一**进行切换，以适应不同的使用习惯和资源需求。同时，提供了智能追加歌曲及 AI 提取用户口令等高级特性。

---

## 2. 接口生态选择（二选一）

用户需在后台配置页面选择其中一种模式作为当前生效的搜索源。**两者为并列关系，同一时间仅有一种生效。**

### 🅰️ 生态一：MusicFree 插件版

**核心机制**：基于插件化架构，通过加载不同的 JS 插件对接各类音乐源。

**主要特点**：
- **高度灵活**：支持订阅插件源自动更新，也可手动导入本地 `.js` 插件文件
- **精细管控**：可单独启用、禁用或卸载特定插件
- **聚合搜索**：支持在后台配置支持搜索的插件平台，根据插件排序聚合平台结果
- **权重策略**：搜索结果优先级遵循 `【歌曲名匹配度】>【歌手名匹配度】>【插件权重】`
    - *注：插件权重由启用列表中的排序决定，前 9 个插件有效，排名越靠前权重越高（最高 9 分）*

**适用场景**：MusicFree生态，有相关插件和资源

### 🅱️ 生态二：LX Server 接口版

**核心机制**：基于开源的 LX Sync Server 项目（<https://xcq0607.github.io/lxserver/>），通过配置服务器地址接入。

**主要特点**：
- **配置简便**：只需填写有效的接口地址（如 `http://127.0.0.1:9527/api`）
- **聚合搜索**：支持在后台配置支持搜索的音乐平台列表，聚合平台结果
- **稳定高效**：由服务端统一维护接口逻辑，无需管理单个插件

**适用场景**：洛雪生态，且已部署LX Sync Server相关服务

---

## 3. 主要功能特性

### 3.1 跨平台搜索与展示

- **精准搜索**：支持 `歌曲名 - 艺术家` 格式，提升匹配准确度
- **信息丰富**：结果展示标题、艺术家、专辑、时长、音质及来源平台标签
- **分页浏览**：采用服务端分页策略，每页默认 20 条，支持快速翻页及返回顶部

### 3.2 智能追加歌曲

- **自动追加（高级）**
    - **功能**：当播放到歌单末尾时，自动搜索并添加**同歌手**的其他歌曲，实现无限连播
    - **配置**：默认开启，可在高级设置中关闭，仅对「全部播放」模式生效

---

## 4. 语音交互与智能解析

### 4.1 新增语音口令

支持通过语音直接在线搜索 [歌曲、歌手]。

> **前置配置**：需在后台【允许唤醒的命令】选项中添加：`,singer_play,online_play,`

<img width="509" height="102" alt="Image" src="https://gproxy.hanxi.cc/proxy/user-attachments/assets/aff9a971-0f88-4ff4-8042-63cef51478b1" />

**在线播放指定歌曲**
- **指令格式**：`在线播放 + 关键词`
- **示例**：`在线播放 林俊杰 江南 `、` 在线播放 陈奕迅`
- **行为**：直接调用当前选定的接口生态（MusicFree 或 LX Server）进行搜索，匹配首个资源立即播放

**在线播放歌手歌单**
- **指令格式**：`播放歌手 + 歌手名`
- **示例**：`播放歌手 周杰伦`
- **行为**：搜索该歌手热门歌曲，创建临时歌单并顺序播放

### 4.2 AI 智能口令提取（高级设置）

- **功能**：利用 AI 大模型分析复杂的用户语音指令，精准提取"歌名"和"歌手名"
- **优势**：显著提高模糊指令（如"我想听那首关于秋天的歌"）的搜索命中率
- **配置**
    - 默认**未启用**
    - 需用户在高级设置中配置 AI 接口地址、API Key 及模型名称（留空地址默认使用阿里百炼）

---

## 5. 后台管理与配置指南

### 5.1 接口生态切换

- **操作位置**：后台配置页面的「接口生态」区域
- **切换逻辑**
    - 用户可点击切换 `MusicFree` 或 `LX Server`
    - 切换时系统会弹出确认提示，因为不同生态的配置项（插件列表 vs 平台列表）互不兼容
    - **生效规则**：保存后，搜索功能将立即使用新选定的生态逻辑

### 5.2 详细配置项

**若选择 MusicFree 插件版：**
- **插件源管理**：编辑订阅地址，点击「更新订阅」获取最新插件列表
- **插件操作**：查看已安装插件状态，支持启用、禁用、卸载及手动上传 `.js` 文件导入
- **官方频道**：提供直达 MusicFree 官方插件市场的链接

**若选择 LX Server 接口版：**
- **地址配置**：输入有效的 API 地址，系统自动校验格式
- **平台管理**：管理支持搜索的音乐平台，支持添加或删除平台配置，实现聚合搜索

### 5.3 高级设置

- **自动追加歌曲**：开关控制，决定是否在列表播完后自动补充同歌手歌曲
- **AI 大模型配置**
    - 输入框：接口地址、API Key、模型名称
    - 说明：非必须功能，追求极致搜索体验的用户建议配置

---

## 6. 常见问题与提示

- **设备绑定**：使用推送功能前，务必在系统首页完成小爱音箱的设备绑定
- **资源兼容性**：MusicFree 部分插件（如B站源）获取的音频流可能不被小爱音箱支持，此类资源建议使用**网页端播放**
- **优先级逻辑**
    - 选定 **LX Server** 时：只调用 LX Server 接口
    - 选定 **MusicFree** 时：调用已启用且排序靠前的 MusicFree 插件
- **语音命令配置**：自定义语音口令生效前，请检查【允许唤醒的命令】列表中是否包含 `singer_play` 和 `online_play`

## 评论

### 评论 1 - hanxi
入口：

<img width="325" height="326" alt="Image" src="https://gproxy.hanxi.cc/proxy/user-attachments/assets/7718a251-4419-4833-909e-3d2bf8fd7c8f" />

搜索和推送到当前播放音箱：

<img width="327" height="641" alt="Image" src="https://gproxy.hanxi.cc/proxy/user-attachments/assets/3722a302-42f4-4c16-9754-98697f1d0dfc" />
---

### 评论 2 - gdzjy
@boluofan  建议把https://github.com/lyswhut/lx-music-mobile 的音源也兼容了吧 ，毕竟lx-music-mobile项目比MusicFree更早，有很多免费的音源。
---

### 评论 3 - boluofan
> [@boluofan](https://github.com/boluofan) 建议把https://github.com/lyswhut/lx-music-mobile 的音源也兼容了吧 ，毕竟lx-music-mobile项目比MusicFree更早，有很多免费的音源。

lxmusic的插件沙箱环境不好做，暂不打算支持。
---

### 评论 4 - VectorZhao
用户口令智能提取没有生效，**/conf/plugins-config.json配置如下

```
{
  "account": "",
  "password": "",
  "openapi_info": {
    "search_url": "https://music-dl.sayqz.com/api/",
    "enabled": false
  },
  "enabled_plugins": [],
  "plugins_info": [],
  "auto_add_song": true,
  "aiapi_info": {
    "base_url": "https://api.xxxxxx",
    "api_key": "sk-98ALygBWge9nExxxxxxxxxxxxxxx",
    "model": "gemini-3-flash-preview",
    "enabled": true
  }
}
```
---

### 评论 5 - mail4zc
这个 自动追加歌曲功能 如何使用，我 用在线播放 口令播放了某首歌曲，播完后可以继续追加该歌手的歌曲吗？
那个【全部播放】模式是指的什么，是全部循环吗？
---

### 评论 6 - boluofan
> 用户口令智能提取没有生效，**/conf/plugins-config.json配置如下
> 
> ```
> {
>   "account": "",
>   "password": "",
>   "openapi_info": {
>     "search_url": "https://music-dl.sayqz.com/api/",
>     "enabled": false
>   },
>   "enabled_plugins": [],
>   "plugins_info": [],
>   "auto_add_song": true,
>   "aiapi_info": {
>     "base_url": "https://api.xxxxxx",
>     "api_key": "sk-98ALygBWge9nExxxxxxxxxxxxxxx",
>     "model": "gemini-3-flash-preview",
>     "enabled": true
>   }
> }
> ```

你这个LLM模型调用是否符合 【OpenAI API 规范】，暂时只支持这个规范。详见https://cloud.tencent.com/developer/article/2546689
---

### 评论 7 - boluofan
> 这个 自动追加歌曲功能 如何使用，我 用在线播放 口令播放了某首歌曲，播完后可以继续追加该歌手的歌曲吗？ 那个【全部播放】模式是指的什么，是全部循环吗？

暂时没将配置添加到前端，只能通过修改配置文件中的属性启用：
 // 启用自动添加歌曲功能
  "auto_add_song": true,

【全部播放】模式就是【全部循环】，默认在线点播创建的歌单就是该模式。
---

[Issue 链接](https://github.com/hanxi/xiaomusic/issues/655)