xiaoyuan-assistant 0.5.48 → 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 版本号，确保每次发布/更新都递增版本。

package/README.md

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

package/XIAOYUAN-BUSINESS-FLOW.md

@@ -1232,3 +1232,8 @@ AI 分析开始提示音与数据获取/模型分析并行；多个数据源采
 ## 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.48",
+  "version": "0.5.49",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",

package/src/components/XiaoyuanAssistant.vue

@@ -109,13 +109,19 @@ import { computed, inject, nextTick, onBeforeUnmount, onMounted, ref, getCurrent
 
 // 使用 Vue app.provide 的字符串 key 获取运行时，避免 NPM 被重复打包/解析时
 // context.js 出现多份 singleton 导致‘请先 app.use(Xiaoyuan)’误报。
-const runtime = inject('xiaoyuan', null) || getCurrentInstance()?.appContext.config.globalProperties.$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
 
-if (!runtime) {
-  throw new Error('请先在 main.js 中 app.use(Xiaoyuan)')
-}
-
-const { manager, speech, options } = runtime
 const wakeWord = options.wakeWord || '你好小园'
 const autoCollapseMs = options.autoCollapseMs ?? 0
 
@@ -265,7 +271,7 @@ function queueSpeak(textToSpeak) {
 function stopSpeech() {
   speechQueueToken += 1
   speechQueue = Promise.resolve()
-  speech.stopSpeaking()
+  speech?.stopSpeaking?.()
 }
 
 // 新指令到来时立即打断上一条播报，并让上一条任务后续产生的播报失效。
@@ -278,6 +284,7 @@ function interruptForNewCommand() {
 }
 
 async function toggleListening() {
+  if (!manager || !speech) return
   if (listening.value) return
   await speech.unlockTTS?.()
   await listenForCommand()
@@ -364,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()
@@ -497,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,
@@ -514,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

@@ -16,7 +16,21 @@ export function useXiaoyuan() {
 
 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)
@@ -84,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)