面向 uni-app（Vue 3） 或需在微信小程序中使用官方「同声传译」插件的场景。下文与具体业务仓库解耦，仅说明官方能力、配置方式与常见封装用法。
1. 官方能力是什么
微信提供 同声传译插件 ，小程序通过 requirePlugin 加载后，使用 getRecordRecognitionManager() 获得录音识别管理器：
- 调用
start({ lang })开始录音并识别； - 调用
stop()结束，在onStop回调中取最终文本； - 可选监听
onRecognize获取中间结果。
限制 ：仅 微信小程序 环境有效；需在小程序管理后台添加该插件，并在小程序配置里声明插件版本。
官方文档：同声传译插件
2. 小程序后台与配置
2.1 微信公众平台
- 登录 微信公众平台 → 小程序；
- 设置 → 第三方设置 → 插件管理 中添加「同声传译」插件（AppID：
wx069ba97219f66d99）； - 按后台展示的 可用版本号 记录，用于填写工程里的
version。
2.2 uni-app：manifest 声明（必须）
在 manifest.json 的 mp-weixin 中增加 plugins（路径以实际工程为准，常见为项目根或 src/manifest.json）：
json
{
"mp-weixin": {
"plugins": {
"WechatSI": {
"version": "0.3.5",
"provider": "wx069ba97219f66d99"
}
}
}
}| 字段 | 说明 |
|---|---|
WechatSI |
插件在代码里 requirePlugin('WechatSI') 时使用的 自定义别名，需与代码一致。 |
provider |
同声传译插件固定为 wx069ba97219f66d99。 |
version |
须与后台为该小程序申请的插件版本 一致或兼容；升级插件后务必同步修改并重新编译。 |
未正确声明时，运行时常见现象：requirePlugin 失败、管理器为空、或业务侧提示「插件不可用」。
2.3 原生小程序（非 uni-app）
在 app.json 中声明 plugins，字段含义与上表相同；业务代码中同样使用 requirePlugin('WechatSI')（别名与 json 中 key 一致即可）。
3. 使用 npm 封装：wechat-si-recognition
社区包 wechat-si-recognition 将插件加载、RecordRecognitionManager 事件绑定、录音权限 （scope.record）封装为 Vue 3 可用的 useWechatSIRecognition，适合 uni-app。
3.1 安装
bash
npm install wechat-si-recognition
# 或 pnpm add wechat-si-recognition
# 或 yarn add wechat-si-recognition依赖要求：vue ^3.0.0（peer）。
3.2 引入
javascript
import { useWechatSIRecognition } from 'wechat-si-recognition';也可在项目内做一层再导出（例如统一从 @/hooks/useWechatSIRecognition 引用），便于替换实现或集中改权限文案。
3.3 API 说明
useWechatSIRecognition(options)
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
lang |
string | 'zh_CN' |
识别语言：zh_CN、en_US、zh_HK、sichuanhua（以官方文档为准） |
onRecognize |
(result: string) => void |
无 | 中间识别结果 |
onStop |
(payload) => void |
无 | 结束回调，见下表 |
onError |
(payload) => void |
无 | 错误：{ retcode, msg } |
permissionModal |
object | 内置文案 | 无录音权限时弹窗：title、content、confirmText、cancelText |
onStop(payload) 常用字段
| 字段 | 说明 |
|---|---|
result |
最终识别文本 |
tempFilePath |
录音临时文件路径 |
duration |
时长（ms） |
fileSize |
文件大小 |
返回值
| 属性 | 说明 |
|---|---|
start() |
Promise<boolean>：内部先处理权限，成功开始录音则为 true |
stop() |
结束录音，触发 onStop / onError |
isAvailable |
当前编译与运行环境是否可用（仅微信小程序且插件加载成功时为 true） |
包内对非 MP-WEIXIN 条件编译分支会 安全降级 ：isAvailable === false，start() 解析为 false。
3.4 权限行为（封装内）
start() 大致顺序：
uni.getSetting检查scope.record；- 未授权则
uni.authorize； - 用户拒绝则
uni.showModal引导uni.openSetting； - 有权限后调用
manager.start({ lang })。
若你的产品规范要求「普通提示只用 Toast」，注意此处仍可能使用 uni.showModal，属于授权引导场景，与业务 Toast 规范可并存。
4. 推荐交互：按住说话（通用范式）
插件本身不管 UI，常见做法是 长按开始、松手结束 ，并加 短按防抖 避免误触：
touchstart：记录触点坐标；setTimeout（如 300ms ）后再调用start()；成功后再展示「录音中」蒙层、可选uni.vibrateShort。touchmove：根据纵向位移判断是否「上滑取消」；用标志位在onStop里决定是否丢弃result。touchend/touchcancel：若定时器未触发，清除定时器（视为轻点）；若已在录音，调用stop()。- 页面卸载或路由离开 ：务必
stop()，避免残留录音状态。
识别结果的去向由业务决定：写入输入框、直接提交接口、或展示确认框等，与插件无关。
说明 ：同声传译管理器 不提供 与实时 ASR 相同的 PCM 音量流；若要做「音量条动画」，需自研模拟或改用其他录音 API（与插件识别流程分开评估）。
5. 直接调用插件（不依赖 npm）
若不用 wechat-si-recognition，在小程序侧可自行：
javascript
const plugin = requirePlugin('WechatSI');
const manager = plugin.getRecordRecognitionManager();
manager.onStart = () => {};
manager.onRecognize = (res) => { /* res.result */ };
manager.onStop = (res) => { /* res.result 等 */ };
manager.onError = (res) => { /* res.retcode, res.msg */ };
// 仍需自行处理 scope.record 与 start/stop 生命周期
manager.start({ lang: 'zh_CN' });
// manager.stop();插件别名须与 manifest / app.json 中 plugins 的 key 一致（上例为 WechatSI）。
6. 排障清单
| 现象 | 可能原因 |
|---|---|
插件不可用 / requirePlugin 报错 |
未在后台添加插件，或 manifest 未声明 / version 错误 |
isAvailable 为 false（uni-app） |
非微信端编译产物，或插件加载失败 |
| 一直无识别结果 | 未授权麦克风、网络异常、说话过短，或插件侧错误（看 onError） |
| 开发者工具正常、真机不行 | 真机基础库版本、后台插件审核/生效状态、权限设置 |
Hook 层常见错误码（wechat-si-recognition）
| retcode | 含义 |
|---|---|
| -1 | 插件不可用或 start 异常 |
| -2 | 用户未授权录音 |
| 其他 | 以微信插件返回为准 |
7. 参考链接
安装依赖后，包内 README.md 与 index.js 注释可与本文对照阅读。