Pronunciation Assessment

---
name: pronunciation-assessment
display_name: 英语发音精评
display_name_en: English Pronunciation Assessment
description: 当用户有英文朗读录音及对应原文，想了解发音、流利度、朗读完整度以及需重点练习的单词和音素时，使用 score_pronunciation 工具取得真实评分，并给出精简可执行的复练建议。
description_zh: 对照英文原文评测朗读录音，定位值得重练的单词和音素，并提供具体建议。
description_en: Assess recorded English reading against a reference text and guide focused pronunciation practice using real scores.
allowed-tools: score_pronunciation
user-invocable: false
version: 0.2.2
author: 流利说
---

# 英语发音精评｜连接器使用说明

本文件是 WorkBuddy 连接器自带的 AI 调用规范，**不在本地模拟评分**。让真实评分结果变成用户能理解、能马上复练的反馈。连接器可服务于独立跟读，也可为听读练习、表达诊断等上层学习场景提供发音评测；不要宣称本连接器本身提供 ASR、TTS、录音界面或表达能力测评。

## 何时调用

当用户希望评测一段**有对应英文参考文本的真实朗读音频**，例如会议开场白、英文发言稿、单句/段落跟读，且能取得可传给 MCP 的真实音频内容时，调用 MCP Tool `score_pronunciation`。

不要只凭英文文本或用户描述生成所谓“AI 发音分”。如果用户只有音频、没有**独立于该录音的原稿**，先询问对应原文。由同一录音事后 ASR 得到的转写并非独立标准文本，不能直接拿它当正式参考原文去得出完整度/综合评测结论。用户后续确认的转写至多用于注明局限的练习线索，不可冒充事前稿件。

## 执行步骤

1. **收集输入**：参考英文原文 `ref_text`、完整 MP3/WAV 音频。若用户已经提供，不重复索取。原文应与用户本次读的内容相匹配；明显不匹配时先核实。
2. **读取真实音频**：只有在 WorkBuddy 运行环境可以合法、可靠地访问音频文件的二进制字节时，才能编码为 Base64；不得凭文件名、上传截图、文本转写或假数据编造 `audio_base64`。不要让用户把庞大的 Base64 直接贴进聊天。
3. **验证格式**：从可靠文件信息中读取 MP3/WAV 实际类型、声道数和采样率。不能判断时，先尝试使用环境内可用的文件信息读取能力；仍不可得就明确说明受限，不能猜测 1 声道 / 16000 Hz。若源音频不是 MP3/WAV，仅在环境具备可靠转换能力且用户允许的前提下先转换。
4. **调用评分**：使用 `score_pronunciation` MCP Tool 和下列参数；该 Tool 是连接器的 MCP 封装，**不是**让 AI 直接对 `/api/v1/speech/score` 发起 multipart 请求。
5. **解释结果**：以真实工具返回为唯一评分依据，按“结论 → 关键单词 → 下一步练习”给用户反馈。调用失败则说明实际失败原因，不生成模拟成绩。

### `score_pronunciation` MCP 参数

| 参数 | 要求 |
| --- | --- |
| `ref_text` | 必填；与朗读内容对应的真实英文参考文本；非空 |
| `audio_base64` | 必填；完整 MP3/WAV 文件字节的标准 Base64；**不含** `data:audio/...;base64,` 前缀 |
| `audio_format.type` | 必填；`MP3` 或 `WAV`（用真实文件类型） |
| `audio_format.audio_channel` | 必填；整数 `1` 或 `2`（根据真实文件信息） |
| `audio_format.sample_rate` | 必填；音频真实采样率，单位 Hz，如 `16000`、`44100`、`48000`（不可猜） |

以上字段沿用原连接器的 MCP Tool 约定；服务器实际返回的工具 schema 若不同，以运行时 tools/list 暴露的**真实**字段为准，不得自行捏造额外参数。与底层 HTTP REST 端点的字段 `audio_type`/`audio` 不能混淆。底层服务文档默认音频上限 8 MiB；音频过大时应提示用户缩短或压缩并保留清晰度，而非直接把不完整音频评分伪装成全段结果。

## 如何解读评分

评分端可能返回 `request_id` 与 `report`。`report` 中常见：

- `score.overall`：综合得分；`score.pronunciation`：发音准确度；`score.fluency`：流利度；`score.integrity`：朗读完整度（相对参考文本，不是表达内容是否完善）。
- `words[]`：`content`、`score.pronunciation`、`phones[]`。音素项可能包含 `ipa`、`score.pronunciation`。这些是定位训练重点的证据。
- `position`：可能包含音频/文字范围。未实测确认时间单位、可回放能力前，不输出精确到秒的回听定位，不承诺自动跳转音频片段。

仅展示**本次真实响应存在的字段**；不要硬补齐缺失维度、将部分得分平均为总分，或把数值映射为雅思、CEFR、母语者水平。维度不可用时写“本次未返回”。

选择需重练的 1–3 个单词时，优先参考返回的**实际词/音素得分**及其对当前发言的影响，不设置未经校准的绝对及格线；在词分几乎没有差异或没有逐词数据时，明确说明无法可靠选出“最差的三个词”。音素 `ipa` 与对应分数可用于建议针对性对照练习，但只有音素得分不代表引擎识别出了用户实际说成哪个音，也不能据此断言“舌位错误”“把 A 读成 B”。这些技巧可以标为通用练法，不应伪装为音频检测事实。

## 默认给用户的结果结构（Chat 输出，不生成 HTML）

**这次朗读表现**：一句话概括真实结果；如果有综合分，显示真实综合分及发音 / 流利度 / 完整度分项（按实际可得字段）；不夸大分数含义。

**最值得重练的单词**：1–3 项，建议形如“**word**（原始得分）— 低分音素 / IPA（仅在返回时）— 具体练法”。只选真实出现且有数据支持的词，原稿拼写和音素不自行猜测。

**下一轮怎么练**：给一项用户立刻能做的动作，例如“先慢速读 3 遍目标词 → 放回原句读 2 遍 → 再录一遍同一句”。如果用户提供第二次**同原文**录音，可再次调用工具比较同一参考文本下的两次实际分数；不能把改写后的另一句话与原句做直接同维度进步结论。

开头不要用长篇介绍或自夸技术；解释少而具体，让用户优先看到本次结论和下一次练习目标。用户追问时再解释音素、评分口径等细节。

## 无法评分 / 异常处理

- 没有独立原稿：先请求用户提供实际读的英文原文；若原文只能靠 ASR 生成，解释该方式不适用于正式参考文本评分。
- 没有音频，或当前 WorkBuddy 无法获取上传附件字节：说明缺少真实可处理音频，不要模拟评分；可请用户通过 WorkBuddy 支持的文件路径重新提供，或等待接入方完成文件读取适配。
- `audio_format` 不明、格式不支持、文件过大：提示需要满足的格式，并帮助用户从现有文件信息判断；不要捏造声道/采样率。
- 401/未授权/授权失效：按连接器实际提供的授权流程完成绑定或重新连接。**不得**索取用户在聊天中粘贴密钥。
- 400/413/429/5xx：按工具实际返回解释缺字段、超限、请求频繁、服务不可用；只在合适时重试，不做无上限循环。
- 部分返回、无有效分数：可以解释已取得的数据，但不要编造完整报告。
- 所有情形都不得把完整音频 Base64、Token、个人音频原文复制进调试日志或反馈正文；仅在确需复现错误时使用安全的请求标识。

## 边界与组合

本连接器提供的是**有参考文本的英语朗读发音评测底层能力**，不是完整的自由表达诊断产品：

- 听读与跟读类体验（示范、跟读、同句复练）由上层场景自行实现；本连接器只在已有参考原文和真实录音时提供评分。
- 表达内容、语境与修订建议属于表达诊断类能力。仅当存在可信参考原稿且评分已接通时，才调用本连接器补充发音证据。
- 本连接器不自动完成音频转写/纠正语法，不承诺录音、上传、用户登录或播放 UI，这些依赖宿主及其他服务能力。