xiaoyuan-assistant

小园智能助手 — Vue 3 语音交互组件，支持自然语言指令解析、页面操作、数据分析、TTS 语音播报和语音唤醒。

安装

npm install xiaoyuan-assistant

快速接入

// main.js
import { createApp } from 'vue'
import Xiaoyuan from 'xiaoyuan-assistant'
import 'xiaoyuan-assistant/style.css'
import App from './App.vue'

const app = createApp(App)

app.use(Xiaoyuan, {
  model: 'THUDM/GLM-Z1-9B-0414',
  aiUrl: 'https://api.siliconflow.cn/v1/chat/completions',
  apiKey: 'sk-your-api-key',
})

app.mount('#app')

组件会自动挂载到页面，右上角显示小园悬浮按钮。

配置参数

app.use(Xiaoyuan, {
  // === AI 模型 ===
  model: 'THUDM/GLM-Z1-9B-0414',           // 模型名称
  aiUrl: 'https://api.siliconflow.cn/v1/chat/completions', // AI 接口地址
  apiKey: 'sk-your-api-key',               // API Key

  // === 语音唤醒 ===
  wakeWord: '你好小园',                     // 唤醒词
  enableWakeWord: true,                    // 是否启用语音唤醒

  // === TTS 语音合成 ===
  enableTTS: true,                         // 是否启用 TTS
  tts: {
    provider: 'tts',                       // 任意非空值即可启用
    apiKey: 'chenyu',                      // TTS 接口 Bearer Token
    apiUrl: 'http://111.33.64.98:9000/v1/audio/speech', // TTS 接口地址（不填使用默认）
    voice: 'zh-CN-XiaoyiNeural',           // 语音角色
    model: 'tts-1',                        // 模型名称（不填使用默认 tts-1）
    format: 'mp3',                         // 音频输出格式
    speed: 1.0,                            // 语速调节 0.5-2.0（可选）
    pitch: 1.0,                            // 音调调节 0.5-2.0（可选）
    style: 'cheerful',                     // 情绪风格（可选：angry/chat/cheerful/sad）
  },

  // === 其他 ===
  autoCollapseMs: 0,                       // 自动收起延迟（毫秒），0 = 不自动收起
})

页面 DOM 约定

在需要语音控制的元素上添加 data-ai-* 属性：

<template>
  <!-- 菜单按钮 -->
  <button
    data-ai-function="handleMenuClick"
    :data-ai-param="menuName"
    data-ai-description="切换到指定菜单"
    @click="handleMenuClick(menuName)"
  >
    {{ menuName }}
  </button>

  <!-- 年份选择 -->
  <div
    data-ai-function="changeYear"
    :data-ai-param="year"
    data-ai-description="切换当前大屏时间年份"
    @click="changeYear(year)"
  >
    {{ year }}
  </div>
</template>

| 属性 | 说明 | |------|------| | data-ai-function | 能力名称，对应 JS 函数 | | data-ai-param | 参数值，如菜单名、年份等 | | data-ai-description | 描述，帮助 AI 理解何时调用 |

SDK 通过 data-ai-function + data-ai-param 精确定位 DOM 元素并触发点击，不依赖页面文字识别。页面切换后目标 DOM 未出现时，SDK 会自动等待。

数据源注册

注册数据源后，用户说"分析土壤数据"时，SDK 会自动获取数据并交给 AI 分析：

import { useXiaoyuan } from 'xiaoyuan-assistant'

const xiaoyuan = useXiaoyuan()

xiaoyuan.registerData({
  name: 'soilData',
  description: '当前页面墒情监测数据，包含土壤水分、温度和养分',
  schema: {
    depth: { type: 'number', description: '土壤深度，cm' },
    humidity: { type: 'number', description: '土壤湿度，%' },
    temperature: { type: 'number', description: '土壤温度，℃' },
    nitrogen: { type: 'number', description: '氮含量，mg/kg' },
    phosphorus: { type: 'number', description: '磷含量，mg/kg' },
    potassium: { type: 'number', description: '钾含量，mg/kg' },
  },
  get: () => tableData.value  // 返回当前数据
})

多指令支持

SDK 支持一句话中包含多个指令，自动按顺序分割执行：

"先切换集成监管，然后切换到2025年，最后分析一下土壤数据"

会被分割为 3 个步骤：

| 步骤 | 类型 | 执行方式 | |------|------|---------| | 切换集成监管 | action | 点击对应 DOM 元素 | | 切换到2025年 | action | 年份切换 | | 分析土壤数据 | analysis | 获取数据 + AI 分析 |

支持的分割连接词：然后、接着、随后、之后、再、并且、最后、下一步、接下来、继续、还有、再去、再来、首先、第一步/第二步/第三步... 等。

识别为对话的指令（如"讲个笑话"、"Vue3是什么"）会直接交给 AI 聊天回复，不影响其他指令的执行顺序。

内置通用方法

以下能力无需注册，SDK 内置支持：

| 方法 | 说明 | 示例语音指令 | |------|------|-------------| | refreshPage | 刷新当前页面 | "刷新一下页面" | | goBack | 返回上一页 | "返回刚才那个页面" | | goForward | 前进一页 | "前进" | | openDataCenter | 打开数据中台 | "进入数据中台" | | closeDataCenter | 关闭数据中台 | "退出数据中台" | | scrollPageTop | 滚动到顶部 | "返回顶部" | | scrollPageBottom | 滚动到底部 | "滚动到底部" |

TTS 语音角色

| 语音代码 | 描述 | |---------|------| | zh-CN-XiaoxiaoNeural | 晓晓 - 温暖活泼（女声） | | zh-CN-XiaoyiNeural | 晓伊 - 温暖亲切（女声） | | zh-CN-YunxiNeural | 云希 - 稳重大气（男声） | | zh-CN-YunyangNeural | 云扬 - 专业权威（男声） | | zh-CN-XiaohanNeural | 晓涵 - 清新活泼（女声） | | zh-CN-XiaomengNeural | 晓梦 - 甜美活力（女声） |

更多语音角色请参考微软官方文档。

指令处理流程

用户语音/文字输入
       ↓
本地 JS 解析（多指令分割 + 能力匹配）
       ↓
┌─────────────────────────────────────┐
│ action  → 直接点击 DOM 元素          │
│ analysis → 获取数据 + AI 深度分析     │
│ chat    → AI 聊天回复（讲笑话/问答等）│
└─────────────────────────────────────┘
       ↓
TTS 语音播报每步结果

版本

当前版本：v0.5.64

详细更新日志请查看 CHANGELOG.md。