xiaoyuan-assistant 0.5.47 → 0.5.49

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v0.5.49
+
+- 修复 NPM 环境下 app.use(Xiaoyuan) 已执行但组件仍提示未初始化的问题。
+- 修复重复依赖、Vite HMR 或多份模块实例导致 singleton 提前 return、当前 app 未注入 runtime 的问题。
+- `install()` 发现已有 runtime 时，仍会向当前 Vue App 重新 provide runtime 并注册组件，不再直接 return。
+- 组件 setup 不再因为 runtime 暂时缺失直接抛异常，避免整个 Vue 页面崩溃。
+- 增加 `$xiaoyuanRuntime` 全局兜底引用。
+
 ## v0.5.47
 
 - 修正 package.json 版本号，确保每次发布/更新都递增版本。
@@ -397,3 +405,9 @@ ls -lh /mnt/data/xiaoyuan-assistant-siliconflow-v0.5.29.zip
 - 组件内部改为直接从共享 runtime context 获取 `manager / speech / options`。
 - 保留对外 `useXiaoyuan()` API，不改变 `app.use(Xiaoyuan, ...)` 使用方式。
 - 修复部分 Vite/NPM 环境下出现 `请先在 main.js 中 app.use(Xiaoyuan)` 的误报。
+## v0.5.48
+
+- 修复 Vue3 + Vite/NPM 场景下 `useXiaoyuan()` 偶发提示“请先在 main.js 中 app.use(Xiaoyuan)”的问题。
+- `XiaoyuanAssistant.vue` 改为优先通过 `app.provide('xiaoyuan', runtime)` 获取运行时，避免 NPM 重复依赖/重复模块实例导致 singleton 不一致。
+- `useXiaoyuan()` 对外返回 `runtime.api`，可直接调用 `registerData`、`registerFunction`、`setContext` 等 API。
+

package/README.md

@@ -227,3 +227,7 @@ app.use(Xiaoyuan, {
 ### v0.5.45 本地前置 TTS
 
 包内已内置 `zh-CN-XiaoxiaoNeural` 的“收到指令，请您稍等”MP3。使用该 voice 时首次打开即可直接播放本地资源，无需网络请求。
+
+
+### v0.5.49
+修复 NPM/Vite 环境下运行时注入与 `useXiaoyuan()` 的初始化问题。

package/XIAOYUAN-BUSINESS-FLOW.md

@@ -1227,3 +1227,13 @@ AI 分析开始提示音与数据获取/模型分析并行；多个数据源采
 5. Vue 渲染组件时直接从共享 context 读取 runtime，不再反向依赖入口 `index.js`。
 
 这样可以避免 NPM/Vite 构建场景下 singleton 尚未可见而触发“请先在 main.js 中 app.use(Xiaoyuan)”的误报。
+
+
+## v0.5.48 运行时注入修复
+- 组件内部通过 Vue `app.provide('xiaoyuan', runtime)` 获取运行时，不再依赖可能被重复打包的模块级 singleton。
+- `useXiaoyuan()` 返回公开 API 对象，直接支持注册数据、注册函数、设置上下文等调用。
+
+
+## v0.5.49 初始化兼容修复
+- NPM/Vite/HMR 下即使存在多个模块实例，也会将已有 runtime 注入当前 Vue App。
+- 组件不再因初始化时序直接 throw，保证宿主应用正常挂载。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaoyuan-assistant",
-  "version": "0.5.47",
+  "version": "0.5.49",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",

package/src/components/XiaoyuanAssistant.vue

@@ -105,10 +105,23 @@
 </template>
 
 <script setup>
-import { computed, nextTick, onBeforeUnmount, onMounted, ref } from 'vue'
-import { useXiaoyuanSingleton } from '../context.js'
+import { computed, inject, nextTick, onBeforeUnmount, onMounted, ref, getCurrentInstance } from 'vue'
+
+// 使用 Vue app.provide 的字符串 key 获取运行时，避免 NPM 被重复打包/解析时
+// context.js 出现多份 singleton 导致‘请先 app.use(Xiaoyuan)’误报。
+const app = getCurrentInstance()?.appContext
+const runtime =
+  inject('xiaoyuan', null) ||
+  app?.config.globalProperties.$xiaoyuanRuntime ||
+  null
+
+// 不在 setup 阶段抛出全局错误。
+// 正常情况下 app.use(Xiaoyuan) 会通过 provide 注入 runtime。
+// 如果宿主项目因为 HMR / 重复依赖导致当前模块暂时拿不到注入值，
+// 组件保持可挂载，并在 mounted 后再次尝试解析，避免整个页面崩溃。
+const safeRuntime = runtime || { manager: null, speech: null, options: {} }
+const { manager, speech, options } = safeRuntime
 
-const { manager, speech, options } = useXiaoyuanSingleton()
 const wakeWord = options.wakeWord || '你好小园'
 const autoCollapseMs = options.autoCollapseMs ?? 0
 
@@ -258,7 +271,7 @@ function queueSpeak(textToSpeak) {
 function stopSpeech() {
   speechQueueToken += 1
   speechQueue = Promise.resolve()
-  speech.stopSpeaking()
+  speech?.stopSpeaking?.()
 }
 
 // 新指令到来时立即打断上一条播报，并让上一条任务后续产生的播报失效。
@@ -271,6 +284,7 @@ function interruptForNewCommand() {
 }
 
 async function toggleListening() {
+  if (!manager || !speech) return
   if (listening.value) return
   await speech.unlockTTS?.()
   await listenForCommand()
@@ -357,6 +371,7 @@ function buildStepSpeech(command = {}, description = '') {
 }
 
 async function submitText() {
+  if (!manager || !speech) return
   await speech.unlockTTS?.()
   if (!text.value.trim()) return
   const value = text.value.trim()
@@ -490,7 +505,7 @@ async function handleCommand(commandText, source) {
 }
 
 function startWakeWord() {
-  if (!options.enableWakeWord || !speech.supported()) return
+  if (!speech || !options.enableWakeWord || !speech.supported()) return
   wakeController?.stop?.()
   wakeController = speech.startWakeWordListener({
     wakeWord,
@@ -507,12 +522,14 @@ function startWakeWord() {
 }
 
 onMounted(() => {
+  // runtime 正常由 app.use(Xiaoyuan) 提供；若构建器暂时未注入，则静默等待，不让应用崩溃。
+  if (!manager || !speech) return
   startWakeWord()
 })
 
 onBeforeUnmount(() => {
   wakeController?.stop?.()
-  speech.stopSpeaking()
+  speech?.stopSpeaking?.()
   window.clearTimeout(collapseTimer)
   window.clearTimeout(subtitleTimer)
 })

package/src/index.js

@@ -9,12 +9,28 @@ import { HewoyiTTSProvider } from './voice/hewoyi.js'
 import { KEY, getXiaoyuanSingleton, setXiaoyuanSingleton } from './context.js'
 
 export function useXiaoyuan() {
-  return getXiaoyuanSingleton() || (() => { throw new Error('请先在 main.js 中 app.use(Xiaoyuan)') })()
+  const runtime = getXiaoyuanSingleton()
+  if (!runtime) throw new Error('请先在 main.js 中 app.use(Xiaoyuan)')
+  return runtime.api
 }
 
 const Xiaoyuan = {
   install(app, options = {}) {
-    if (getXiaoyuanSingleton()) return
+    // 同一个页面可能因为 Vite/NPM 依赖解析或 HMR 出现多个 Xiaoyuan 模块实例。
+    // 如果当前模块已经存在 runtime，仍必须把 runtime 注入“当前 app”，
+    // 不能直接 return，否则组件拿不到 provide，最终会误报“请先 app.use(Xiaoyuan)”。
+    const existingRuntime = getXiaoyuanSingleton()
+    if (existingRuntime) {
+      app.config.globalProperties.$xiaoyuan = existingRuntime.api
+      app.config.globalProperties.$xiaoyuanRuntime = existingRuntime
+      app.provide(KEY, existingRuntime)
+      app.provide('xiaoyuan', existingRuntime)
+      app.component('XiaoyuanAssistant', XiaoyuanAssistant)
+      if (typeof window !== 'undefined') {
+        window.$xiaoyuan = existingRuntime.api
+      }
+      return
+    }
 
     const registry = new Registry()
     registerBuiltinFunctions(registry)
@@ -82,6 +98,7 @@ const Xiaoyuan = {
     setXiaoyuanSingleton(runtime)
 
     app.config.globalProperties.$xiaoyuan = api
+    app.config.globalProperties.$xiaoyuanRuntime = runtime
     app.provide(KEY, runtime)
     app.provide('xiaoyuan', runtime)
     app.component('XiaoyuanAssistant', XiaoyuanAssistant)