# 语音识别插件自定义基座制作指南

## ❌ **问题原因**

UTS 插件 `xwq-speech-to-text` 依赖第三方 Android 库 `vosk-android`，标准基座中不包含此依赖，因此需要制作**自定义基座**。

---

## 🔍 **错误信息**

```
error: Unresolved reference: vosk
import Model from "org.vosk.Model"
```

**原因：** 
- Vosk 语音识别库未编译到基座中
- 需要制作包含 vosk-android 依赖的自定义基座

---

## ✅ **解决方案1：制作自定义调试基座（推荐）**

### **步骤1：检查环境**

#### **1.1 检查 HBuilderX 版本**
- 要求：HBuilderX 4.63 或更高版本
- 检查：`帮助` → `关于`

#### **1.2 检查 Android SDK**
- 菜单：`工具` → `设置` → `插件配置` → `Android SDK`
- 如果未安装，点击"下载Android SDK"

---

### **步骤2：制作自定义基座**

#### **2.1 打开项目**
1. 在 HBuilderX 中打开项目：`fronted_uniapp`
2. 确保项目已保存

#### **2.2 制作基座**
1. **右键点击项目根目录**
2. **选择：`发行` → `原生 App-制作自定义调试基座`**
3. **配置选项：**
   - ✅ 选择平台：`Android`
   - ✅ 证书：使用 DCloud 公共证书（测试用）
   - ❌ 不勾选"仅打正式包"

4. **点击"打包"**

#### **2.3 等待打包**
- 打包时间：约 5-15 分钟
- 控制台会显示打包进度
- 打包完成后会提示"打包成功"

#### **2.4 下载基座**
打包完成后，基座文件会自动下载到：
```
fronted_uniapp/unpackage/debug/android_debug.apk
```

---

### **步骤3：安装自定义基座**

#### **3.1 手机连接**
1. 手机开启 USB 调试
2. 用数据线连接电脑
3. 确认手机弹出的授权提示

#### **3.2 安装基座**
**方法1：自动安装**
- HBuilderX 会自动检测并提示安装
- 点击"安装"即可

**方法2：手动安装**
```bash
# 使用 adb 安装
adb install -r fronted_uniapp/unpackage/debug/android_debug.apk
```

**方法3：直接安装**
- 将 `android_debug.apk` 复制到手机
- 在手机上点击安装

---

### **步骤4：使用自定义基座运行**

#### **4.1 运行项目**
1. 在 HBuilderX 中
2. 点击工具栏 "运行" → "运行到手机或模拟器" → "运行到 Android App 基座"
3. **重要：** 选择"自定义基座"（不是"标准基座"）

#### **4.2 验证**
- App 启动后，进入语音测评页面
- 如果能看到"准备就绪"，说明插件加载成功
- 如果还是报错，查看控制台日志

---

## ✅ **解决方案2：云端打包（正式发布用）**

如果是正式发布，使用云端打包：

### **步骤1：配置应用信息**

1. **打开 manifest.json**
2. **配置基础信息：**
   - 应用名称
   - 应用版本号
   - 应用图标
   - 包名（com.xxx.xxx）

### **步骤2：配置证书**

#### **2.1 生成证书（如果没有）**
```bash
# 使用 Android Studio 或命令行生成
keytool -genkey -v -keystore release.keystore -alias mykey -keyalg RSA -keysize 2048 -validity 10000
```

#### **2.2 在 HBuilderX 中配置证书**
1. `manifest.json` → `App 打包配置`
2. 选择证书文件
3. 输入证书密码和别名密码

---

### **步骤3：云端打包**

1. **右键项目根目录**
2. **选择：`发行` → `原生 App-云打包`**
3. **配置选项：**
   - ✅ 选择平台：`Android`
   - ✅ 使用自有证书
   - ✅ 勾选"打正式包"

4. **点击"打包"**

5. **等待打包完成**
   - 时间：约 10-20 分钟
   - 完成后会提示下载地址

6. **下载并安装**
   - 下载 APK 文件
   - 安装到手机测试

---

## ✅ **解决方案3：暂时禁用语音功能**

如果暂时不需要语音识别，可以：

### **方法1：隐藏语音入口**

修改首页，隐藏语音测评入口：

```vue
<!-- pages/index/index.vue -->
<!-- 注释掉或删除语音测评入口 -->
<!--
<view class="action-item" @click="goToSpeech">
    <view class="action-icon-wrapper voice">
        <text class="action-icon">🎤</text>
    </view>
    <text class="action-text">语音测评</text>
</view>
-->
```

### **方法2：显示提示信息**

已修改 `speech.vue`，现在会显示友好提示：
```
需要制作自定义基座才能使用语音识别功能。

步骤：
1. HBuilderX菜单：发行 → 原生App-制作自定义调试基座
2. 选择Android平台
3. 等待打包完成
4. 安装自定义基座到手机
```

---

## 🔧 **常见问题**

### **问题1：打包失败 - SDK 未配置**

**错误：** `Android SDK path not configured`

**解决：**
1. `工具` → `设置` → `插件配置` → `Android SDK`
2. 点击"下载 Android SDK"
3. 等待下载完成
4. 重新打包

---

### **问题2：打包失败 - 网络问题**

**错误：** `Failed to download dependency`

**解决：**
1. 检查网络连接
2. 使用国内镜像（config.json 已配置阿里云镜像）
3. 重试打包

---

### **问题3：基座安装失败**

**错误：** `App not installed`

**解决：**
1. 卸载旧的基座
2. 清除手机缓存
3. 重新安装

---

### **问题4：运行时仍然报错**

**检查：**
1. 是否选择了"自定义基座"运行（不是标准基座）
2. 自定义基座版本是否最新
3. 是否需要重新制作基座

**重新制作基座：**
- 删除旧的 `android_debug.apk`
- 重新执行制作流程
- 重新安装到手机

---

### **问题5：插件仍然无法使用**

**检查 config.json：**
```json
{
  "dependencies": [
    "com.alphacephei:vosk-android:0.3.47"
  ]
}
```

**验证依赖：**
1. 检查插件配置文件是否正确
2. 清除缓存重新打包
3. 查看打包日志是否有错误

---

## 📋 **制作自定义基座完整流程**

```mermaid
graph TD
    A[开始] --> B[检查 HBuilderX 版本]
    B --> C[配置 Android SDK]
    C --> D[右键项目 → 发行 → 制作自定义调试基座]
    D --> E[选择 Android 平台]
    E --> F[点击打包]
    F --> G[等待 5-15 分钟]
    G --> H[下载基座 APK]
    H --> I[安装到手机]
    I --> J[运行项目 - 选择自定义基座]
    J --> K{语音功能正常?}
    K -->|是| L[完成]
    K -->|否| M[查看日志排查]
    M --> N[重新制作基座]
    N --> G
```

---

## 🎯 **验证成功的标志**

### **1. 控制台日志**
```
[Speech] ========== 开始初始化语音模型 ==========
[Speech] 已保存的模型路径: /storage/...
[Speech] 模型加载成功
```

### **2. 页面显示**
- 状态：准备就绪，可以开始说话
- 调试信息：模型已加载

### **3. 功能测试**
- 点击"开始说话"按钮
- 说话后能看到识别文本
- 没有报错提示

---

## 📱 **自定义基座 vs 标准基座**

| 项目 | 标准基座 | 自定义基座 |
|------|----------|------------|
| **UTS 插件** | ❌ 不支持第三方依赖 | ✅ 支持 |
| **打包时间** | 快（秒级） | 慢（5-15分钟） |
| **更新频率** | 每次运行 | 需要重新制作 |
| **适用场景** | 普通功能开发 | 使用第三方依赖的插件 |
| **调试** | 实时同步代码 | 实时同步代码 |

---

## 💡 **最佳实践**

### **开发阶段**
1. ✅ 制作一次自定义基座
2. ✅ 安装到测试手机
3. ✅ 后续开发使用自定义基座运行
4. ⚠️ 插件更新后需要重新制作基座

### **测试阶段**
1. ✅ 使用自定义基座测试完整功能
2. ✅ 在不同机型上测试
3. ✅ 测试语音识别准确性

### **发布阶段**
1. ✅ 使用云端打包
2. ✅ 使用自有证书
3. ✅ 打正式包发布

---

## 📝 **注意事项**

1. **自定义基座只用于调试**
   - 不要发布自定义基座给用户
   - 正式发布使用云端打包

2. **基座需要定期更新**
   - 插件更新后重新制作
   - HBuilderX 更新后重新制作

3. **证书管理**
   - 测试用 DCloud 公共证书
   - 正式发布用自有证书
   - 妥善保管证书文件

4. **版本匹配**
   - 自定义基座版本要与 HBuilderX 版本匹配
   - 插件版本要兼容

---

## 🆘 **获取帮助**

### **官方文档**
- UTS 插件开发：https://uniapp.dcloud.net.cn/tutorial/run/uts-development-android.html
- 自定义基座：https://uniapp.dcloud.net.cn/tutorial/run/run-app.html#customplayground

### **社区支持**
- DCloud 社区：https://ask.dcloud.net.cn/
- uni-app 官方 QQ 群

### **插件作者**
- 查看插件详情页的联系方式

---

## ✅ **总结**

### **推荐方案**
1. **开发调试：** 制作自定义调试基座
2. **正式发布：** 云端打包

### **核心步骤**
1. 配置 Android SDK
2. 制作自定义基座
3. 安装到手机
4. 选择自定义基座运行

### **关键点**
- ⚠️ 必须使用自定义基座
- ⚠️ 不能用标准基座
- ⚠️ 插件更新后需重新制作

**现在请按照步骤制作自定义基座，完成后语音识别功能即可正常使用！** 🚀