docs(tts): Edge TTS 完整语言/音色清单 + 自动生成脚本

参考 https://github.com/caojunfei/audio_codebuddy/issues 运维需求，
把 Edge TTS 支持的 316 个音色 / 74 种语言写进 docs/tts-edge-languages.md，
方便后续选择音色 / 添加方言支持时直接查表。

包含：
- 中文方言速查表(普通话/粤语/国语/川/东北/陕西方言)
- 14 个中文音色完整列表
- 74 种语言按 Locale 聚合的索引
- 切换音色的三种方式(CLI / models.json / API)
- 前端 voice_01~voice_10 → Edge 实际音色的映射
- 已知限制(语速等价于播放器、限频、没商用授权等)
- 重新生成步骤:scripts/gen-edge-tts-doc.js

deploy-package/edge-voices-snapshot.txt

@@ -0,0 +1,324 @@
+Name                               Gender    ContentCategories      VoicePersonalities
+---------------------------------  --------  ---------------------  --------------------------------------
+af-ZA-AdriNeural                   Female    General                Friendly, Positive
+af-ZA-WillemNeural                 Male      General                Friendly, Positive
+am-ET-AmehaNeural                  Male      General                Friendly, Positive
+am-ET-MekdesNeural                 Female    General                Friendly, Positive
+ar-AE-FatimaNeural                 Female    General                Friendly, Positive
+ar-AE-HamdanNeural                 Male      General                Friendly, Positive
+ar-BH-AliNeural                    Male      General                Friendly, Positive
+ar-BH-LailaNeural                  Female    General                Friendly, Positive
+ar-DZ-AminaNeural                  Female    General                Friendly, Positive
+ar-DZ-IsmaelNeural                 Male      General                Friendly, Positive
+ar-EG-SalmaNeural                  Female    General                Friendly, Positive
+ar-EG-ShakirNeural                 Male      General                Friendly, Positive
+ar-IQ-BasselNeural                 Male      General                Friendly, Positive
+ar-IQ-RanaNeural                   Female    General                Friendly, Positive
+ar-JO-SanaNeural                   Female    General                Friendly, Positive
+ar-JO-TaimNeural                   Male      General                Friendly, Positive
+ar-KW-FahedNeural                  Male      General                Friendly, Positive
+ar-KW-NouraNeural                  Female    General                Friendly, Positive
+ar-LB-LaylaNeural                  Female    General                Friendly, Positive
+ar-LB-RamiNeural                   Male      General                Friendly, Positive
+ar-LY-ImanNeural                   Female    General                Friendly, Positive
+ar-LY-OmarNeural                   Male      General                Friendly, Positive
+ar-MA-JamalNeural                  Male      General                Friendly, Positive
+ar-MA-MounaNeural                  Female    General                Friendly, Positive
+ar-OM-AbdullahNeural               Male      General                Friendly, Positive
+ar-OM-AyshaNeural                  Female    General                Friendly, Positive
+ar-QA-AmalNeural                   Female    General                Friendly, Positive
+ar-QA-MoazNeural                   Male      General                Friendly, Positive
+ar-SA-HamedNeural                  Male      General                Friendly, Positive
+ar-SA-ZariyahNeural                Female    General                Friendly, Positive
+ar-SY-AmanyNeural                  Female    General                Friendly, Positive
+ar-SY-LaithNeural                  Male      General                Friendly, Positive
+ar-TN-HediNeural                   Male      General                Friendly, Positive
+ar-TN-ReemNeural                   Female    General                Friendly, Positive
+ar-YE-MaryamNeural                 Female    General                Friendly, Positive
+ar-YE-SalehNeural                  Male      General                Friendly, Positive
+az-AZ-BabekNeural                  Male      General                Friendly, Positive
+az-AZ-BanuNeural                   Female    General                Friendly, Positive
+bg-BG-BorislavNeural               Male      General                Friendly, Positive
+bg-BG-KalinaNeural                 Female    General                Friendly, Positive
+bn-BD-NabanitaNeural               Female    General                Friendly, Positive
+bn-BD-PradeepNeural                Male      General                Friendly, Positive
+bn-IN-BashkarNeural                Male      General                Friendly, Positive
+bn-IN-TanishaaNeural               Female    General                Friendly, Positive
+bs-BA-GoranNeural                  Male      General                Friendly, Positive
+bs-BA-VesnaNeural                  Female    General                Friendly, Positive
+ca-ES-EnricNeural                  Male      General                Friendly, Positive
+ca-ES-JoanaNeural                  Female    General                Friendly, Positive
+cs-CZ-AntoninNeural                Male      General                Friendly, Positive
+cs-CZ-VlastaNeural                 Female    General                Friendly, Positive
+cy-GB-AledNeural                   Male      General                Friendly, Positive
+cy-GB-NiaNeural                    Female    General                Friendly, Positive
+da-DK-ChristelNeural               Female    General                Friendly, Positive
+da-DK-JeppeNeural                  Male      General                Friendly, Positive
+de-AT-IngridNeural                 Female    General                Friendly, Positive
+de-AT-JonasNeural                  Male      General                Friendly, Positive
+de-CH-JanNeural                    Male      General                Friendly, Positive
+de-CH-LeniNeural                   Female    General                Friendly, Positive
+de-DE-AmalaNeural                  Female    General                Friendly, Positive
+de-DE-ConradNeural                 Male      General                Friendly, Positive
+de-DE-FlorianMultilingualNeural    Male      General                Friendly, Positive
+de-DE-KatjaNeural                  Female    General                Friendly, Positive
+de-DE-KillianNeural                Male      General                Friendly, Positive
+de-DE-SeraphinaMultilingualNeural  Female    General                Friendly, Positive
+el-GR-AthinaNeural                 Female    General                Friendly, Positive
+el-GR-NestorasNeural               Male      General                Friendly, Positive
+en-AU-NatashaNeural                Female    General                Friendly, Positive
+en-AU-WilliamMultilingualNeural    Male      General                Friendly, Positive
+en-CA-ClaraNeural                  Female    General                Friendly, Positive
+en-CA-LiamNeural                   Male      General                Friendly, Positive
+en-GB-LibbyNeural                  Female    General                Friendly, Positive
+en-GB-MaisieNeural                 Female    General                Friendly, Positive
+en-GB-RyanNeural                   Male      General                Friendly, Positive
+en-GB-SoniaNeural                  Female    General                Friendly, Positive
+en-GB-ThomasNeural                 Male      General                Friendly, Positive
+en-HK-SamNeural                    Male      General                Friendly, Positive
+en-HK-YanNeural                    Female    General                Friendly, Positive
+en-IE-ConnorNeural                 Male      General                Friendly, Positive
+en-IE-EmilyNeural                  Female    General                Friendly, Positive
+en-IN-NeerjaExpressiveNeural       Female    General                Friendly, Positive
+en-IN-NeerjaNeural                 Female    General                Friendly, Positive
+en-IN-PrabhatNeural                Male      General                Friendly, Positive
+en-KE-AsiliaNeural                 Female    General                Friendly, Positive
+en-KE-ChilembaNeural               Male      General                Friendly, Positive
+en-NG-AbeoNeural                   Male      General                Friendly, Positive
+en-NG-EzinneNeural                 Female    General                Friendly, Positive
+en-NZ-MitchellNeural               Male      General                Friendly, Positive
+en-NZ-MollyNeural                  Female    General                Friendly, Positive
+en-PH-JamesNeural                  Male      General                Friendly, Positive
+en-PH-RosaNeural                   Female    General                Friendly, Positive
+en-SG-LunaNeural                   Female    General                Friendly, Positive
+en-SG-WayneNeural                  Male      General                Friendly, Positive
+en-TZ-ElimuNeural                  Male      General                Friendly, Positive
+en-TZ-ImaniNeural                  Female    General                Friendly, Positive
+en-US-AnaNeural                    Female    Cartoon, Conversation  Cute
+en-US-AndrewMultilingualNeural     Male      Conversation, Copilot  Warm, Confident, Authentic, Honest
+en-US-AndrewNeural                 Male      Conversation, Copilot  Warm, Confident, Authentic, Honest
+en-US-AriaNeural                   Female    News, Novel            Positive, Confident
+en-US-AvaMultilingualNeural        Female    Conversation, Copilot  Expressive, Caring, Pleasant, Friendly
+en-US-AvaNeural                    Female    Conversation, Copilot  Expressive, Caring, Pleasant, Friendly
+en-US-BrianMultilingualNeural      Male      Conversation, Copilot  Approachable, Casual, Sincere
+en-US-BrianNeural                  Male      Conversation, Copilot  Approachable, Casual, Sincere
+en-US-ChristopherNeural            Male      News, Novel            Reliable, Authority
+en-US-EmmaMultilingualNeural       Female    Conversation, Copilot  Cheerful, Clear, Conversational
+en-US-EmmaNeural                   Female    Conversation, Copilot  Cheerful, Clear, Conversational
+en-US-EricNeural                   Male      News, Novel            Rational
+en-US-GuyNeural                    Male      News, Novel            Passion
+en-US-JennyNeural                  Female    General                Friendly, Considerate, Comfort
+en-US-MichelleNeural               Female    News, Novel            Friendly, Pleasant
+en-US-RogerNeural                  Male      News, Novel            Lively
+en-US-SteffanNeural                Male      News, Novel            Rational
+en-ZA-LeahNeural                   Female    General                Friendly, Positive
+en-ZA-LukeNeural                   Male      General                Friendly, Positive
+es-AR-ElenaNeural                  Female    General                Friendly, Positive
+es-AR-TomasNeural                  Male      General                Friendly, Positive
+es-BO-MarceloNeural                Male      General                Friendly, Positive
+es-BO-SofiaNeural                  Female    General                Friendly, Positive
+es-CL-CatalinaNeural               Female    General                Friendly, Positive
+es-CL-LorenzoNeural                Male      General                Friendly, Positive
+es-CO-GonzaloNeural                Male      General                Friendly, Positive
+es-CO-SalomeNeural                 Female    General                Friendly, Positive
+es-CR-JuanNeural                   Male      General                Friendly, Positive
+es-CR-MariaNeural                  Female    General                Friendly, Positive
+es-CU-BelkysNeural                 Female    General                Friendly, Positive
+es-CU-ManuelNeural                 Male      General                Friendly, Positive
+es-DO-EmilioNeural                 Male      General                Friendly, Positive
+es-DO-RamonaNeural                 Female    General                Friendly, Positive
+es-EC-AndreaNeural                 Female    General                Friendly, Positive
+es-EC-LuisNeural                   Male      General                Friendly, Positive
+es-ES-AlvaroNeural                 Male      General                Friendly, Positive
+es-ES-ElviraNeural                 Female    General                Friendly, Positive
+es-ES-XimenaNeural                 Female    General                Friendly, Positive
+es-GQ-JavierNeural                 Male      General                Friendly, Positive
+es-GQ-TeresaNeural                 Female    General                Friendly, Positive
+es-GT-AndresNeural                 Male      General                Friendly, Positive
+es-GT-MartaNeural                  Female    General                Friendly, Positive
+es-HN-CarlosNeural                 Male      General                Friendly, Positive
+es-HN-KarlaNeural                  Female    General                Friendly, Positive
+es-MX-DaliaNeural                  Female    General                Friendly, Positive
+es-MX-JorgeNeural                  Male      General                Friendly, Positive
+es-NI-FedericoNeural               Male      General                Friendly, Positive
+es-NI-YolandaNeural                Female    General                Friendly, Positive
+es-PA-MargaritaNeural              Female    General                Friendly, Positive
+es-PA-RobertoNeural                Male      General                Friendly, Positive
+es-PE-AlexNeural                   Male      General                Friendly, Positive
+es-PE-CamilaNeural                 Female    General                Friendly, Positive
+es-PR-KarinaNeural                 Female    General                Friendly, Positive
+es-PR-VictorNeural                 Male      General                Friendly, Positive
+es-PY-MarioNeural                  Male      General                Friendly, Positive
+es-PY-TaniaNeural                  Female    General                Friendly, Positive
+es-SV-LorenaNeural                 Female    General                Friendly, Positive
+es-SV-RodrigoNeural                Male      General                Friendly, Positive
+es-US-AlonsoNeural                 Male      General                Friendly, Positive
+es-US-PalomaNeural                 Female    General                Friendly, Positive
+es-UY-MateoNeural                  Male      General                Friendly, Positive
+es-UY-ValentinaNeural              Female    General                Friendly, Positive
+es-VE-PaolaNeural                  Female    General                Friendly, Positive
+es-VE-SebastianNeural              Male      General                Friendly, Positive
+et-EE-AnuNeural                    Female    General                Friendly, Positive
+et-EE-KertNeural                   Male      General                Friendly, Positive
+fa-IR-DilaraNeural                 Female    General                Friendly, Positive
+fa-IR-FaridNeural                  Male      General                Friendly, Positive
+fi-FI-HarriNeural                  Male      General                Friendly, Positive
+fi-FI-NooraNeural                  Female    General                Friendly, Positive
+fil-PH-AngeloNeural                Male      General                Friendly, Positive
+fil-PH-BlessicaNeural              Female    General                Friendly, Positive
+fr-BE-CharlineNeural               Female    General                Friendly, Positive
+fr-BE-GerardNeural                 Male      General                Friendly, Positive
+fr-CA-AntoineNeural                Male      General                Friendly, Positive
+fr-CA-JeanNeural                   Male      General                Friendly, Positive
+fr-CA-SylvieNeural                 Female    General                Friendly, Positive
+fr-CA-ThierryNeural                Male      General                Friendly, Positive
+fr-CH-ArianeNeural                 Female    General                Friendly, Positive
+fr-CH-FabriceNeural                Male      General                Friendly, Positive
+fr-FR-DeniseNeural                 Female    General                Friendly, Positive
+fr-FR-EloiseNeural                 Female    General                Friendly, Positive
+fr-FR-HenriNeural                  Male      General                Friendly, Positive
+fr-FR-RemyMultilingualNeural       Male      General                Friendly, Positive
+fr-FR-VivienneMultilingualNeural   Female    General                Friendly, Positive
+ga-IE-ColmNeural                   Male      General                Friendly, Positive
+ga-IE-OrlaNeural                   Female    General                Friendly, Positive
+gl-ES-RoiNeural                    Male      General                Friendly, Positive
+gl-ES-SabelaNeural                 Female    General                Friendly, Positive
+gu-IN-DhwaniNeural                 Female    General                Friendly, Positive
+gu-IN-NiranjanNeural               Male      General                Friendly, Positive
+he-IL-AvriNeural                   Male      General                Friendly, Positive
+he-IL-HilaNeural                   Female    General                Friendly, Positive
+hi-IN-MadhurNeural                 Male      General                Friendly, Positive
+hi-IN-SwaraNeural                  Female    General                Friendly, Positive
+hr-HR-GabrijelaNeural              Female    General                Friendly, Positive
+hr-HR-SreckoNeural                 Male      General                Friendly, Positive
+hu-HU-NoemiNeural                  Female    General                Friendly, Positive
+hu-HU-TamasNeural                  Male      General                Friendly, Positive
+id-ID-ArdiNeural                   Male      General                Friendly, Positive
+id-ID-GadisNeural                  Female    General                Friendly, Positive
+is-IS-GudrunNeural                 Female    General                Friendly, Positive
+is-IS-GunnarNeural                 Male      General                Friendly, Positive
+it-IT-DiegoNeural                  Male      General                Friendly, Positive
+it-IT-ElsaNeural                   Female    General                Friendly, Positive
+it-IT-GiuseppeMultilingualNeural   Male      General                Friendly, Positive
+it-IT-IsabellaNeural               Female    General                Friendly, Positive
+iu-Cans-CA-SiqiniqNeural           Female    General                Friendly, Positive
+iu-Cans-CA-TaqqiqNeural            Male      General                Friendly, Positive
+iu-Latn-CA-SiqiniqNeural           Female    General                Friendly, Positive
+iu-Latn-CA-TaqqiqNeural            Male      General                Friendly, Positive
+ja-JP-KeitaNeural                  Male      General                Friendly, Positive
+ja-JP-NanamiNeural                 Female    General                Friendly, Positive
+jv-ID-DimasNeural                  Male      General                Friendly, Positive
+jv-ID-SitiNeural                   Female    General                Friendly, Positive
+ka-GE-EkaNeural                    Female    General                Friendly, Positive
+ka-GE-GiorgiNeural                 Male      General                Friendly, Positive
+kk-KZ-AigulNeural                  Female    General                Friendly, Positive
+kk-KZ-DauletNeural                 Male      General                Friendly, Positive
+km-KH-PisethNeural                 Male      General                Friendly, Positive
+km-KH-SreymomNeural                Female    General                Friendly, Positive
+kn-IN-GaganNeural                  Male      General                Friendly, Positive
+kn-IN-SapnaNeural                  Female    General                Friendly, Positive
+ko-KR-HyunsuMultilingualNeural     Male      General                Friendly, Positive
+ko-KR-InJoonNeural                 Male      General                Friendly, Positive
+ko-KR-SunHiNeural                  Female    General                Friendly, Positive
+lo-LA-ChanthavongNeural            Male      General                Friendly, Positive
+lo-LA-KeomanyNeural                Female    General                Friendly, Positive
+lt-LT-LeonasNeural                 Male      General                Friendly, Positive
+lt-LT-OnaNeural                    Female    General                Friendly, Positive
+lv-LV-EveritaNeural                Female    General                Friendly, Positive
+lv-LV-NilsNeural                   Male      General                Friendly, Positive
+mk-MK-AleksandarNeural             Male      General                Friendly, Positive
+mk-MK-MarijaNeural                 Female    General                Friendly, Positive
+ml-IN-MidhunNeural                 Male      General                Friendly, Positive
+ml-IN-SobhanaNeural                Female    General                Friendly, Positive
+mn-MN-BataaNeural                  Male      General                Friendly, Positive
+mn-MN-YesuiNeural                  Female    General                Friendly, Positive
+mr-IN-AarohiNeural                 Female    General                Friendly, Positive
+mr-IN-ManoharNeural                Male      General                Friendly, Positive
+ms-MY-OsmanNeural                  Male      General                Friendly, Positive
+ms-MY-YasminNeural                 Female    General                Friendly, Positive
+mt-MT-GraceNeural                  Female    General                Friendly, Positive
+mt-MT-JosephNeural                 Male      General                Friendly, Positive
+my-MM-NilarNeural                  Female    General                Friendly, Positive
+my-MM-ThihaNeural                  Male      General                Friendly, Positive
+nb-NO-FinnNeural                   Male      General                Friendly, Positive
+nb-NO-PernilleNeural               Female    General                Friendly, Positive
+ne-NP-HemkalaNeural                Female    General                Friendly, Positive
+ne-NP-SagarNeural                  Male      General                Friendly, Positive
+nl-BE-ArnaudNeural                 Male      General                Friendly, Positive
+nl-BE-DenaNeural                   Female    General                Friendly, Positive
+nl-NL-ColetteNeural                Female    General                Friendly, Positive
+nl-NL-FennaNeural                  Female    General                Friendly, Positive
+nl-NL-MaartenNeural                Male      General                Friendly, Positive
+pl-PL-MarekNeural                  Male      General                Friendly, Positive
+pl-PL-ZofiaNeural                  Female    General                Friendly, Positive
+ps-AF-GulNawazNeural               Male      General                Friendly, Positive
+ps-AF-LatifaNeural                 Female    General                Friendly, Positive
+pt-BR-AntonioNeural                Male      General                Friendly, Positive
+pt-BR-FranciscaNeural              Female    General                Friendly, Positive
+pt-BR-ThalitaMultilingualNeural    Female    General                Friendly, Positive
+pt-PT-DuarteNeural                 Male      General                Friendly, Positive
+pt-PT-RaquelNeural                 Female    General                Friendly, Positive
+ro-RO-AlinaNeural                  Female    General                Friendly, Positive
+ro-RO-EmilNeural                   Male      General                Friendly, Positive
+ru-RU-DmitryNeural                 Male      General                Friendly, Positive
+ru-RU-SvetlanaNeural               Female    General                Friendly, Positive
+si-LK-SameeraNeural                Male      General                Friendly, Positive
+si-LK-ThiliniNeural                Female    General                Friendly, Positive
+sk-SK-LukasNeural                  Male      General                Friendly, Positive
+sk-SK-ViktoriaNeural               Female    General                Friendly, Positive
+sl-SI-PetraNeural                  Female    General                Friendly, Positive
+sl-SI-RokNeural                    Male      General                Friendly, Positive
+so-SO-MuuseNeural                  Male      General                Friendly, Positive
+so-SO-UbaxNeural                   Female    General                Friendly, Positive
+sq-AL-AnilaNeural                  Female    General                Friendly, Positive
+sq-AL-IlirNeural                   Male      General                Friendly, Positive
+sr-RS-NicholasNeural               Male      General                Friendly, Positive
+sr-RS-SophieNeural                 Female    General                Friendly, Positive
+su-ID-JajangNeural                 Male      General                Friendly, Positive
+su-ID-TutiNeural                   Female    General                Friendly, Positive
+sv-SE-MattiasNeural                Male      General                Friendly, Positive
+sv-SE-SofieNeural                  Female    General                Friendly, Positive
+sw-KE-RafikiNeural                 Male      General                Friendly, Positive
+sw-KE-ZuriNeural                   Female    General                Friendly, Positive
+sw-TZ-DaudiNeural                  Male      General                Friendly, Positive
+sw-TZ-RehemaNeural                 Female    General                Friendly, Positive
+ta-IN-PallaviNeural                Female    General                Friendly, Positive
+ta-IN-ValluvarNeural               Male      General                Friendly, Positive
+ta-LK-KumarNeural                  Male      General                Friendly, Positive
+ta-LK-SaranyaNeural                Female    General                Friendly, Positive
+ta-MY-KaniNeural                   Female    General                Friendly, Positive
+ta-MY-SuryaNeural                  Male      General                Friendly, Positive
+ta-SG-AnbuNeural                   Male      General                Friendly, Positive
+ta-SG-VenbaNeural                  Female    General                Friendly, Positive
+te-IN-MohanNeural                  Male      General                Friendly, Positive
+te-IN-ShrutiNeural                 Female    General                Friendly, Positive
+th-TH-NiwatNeural                  Male      General                Friendly, Positive
+th-TH-PremwadeeNeural              Female    General                Friendly, Positive
+tr-TR-AhmetNeural                  Male      General                Friendly, Positive
+tr-TR-EmelNeural                   Female    General                Friendly, Positive
+uk-UA-OstapNeural                  Male      General                Friendly, Positive
+uk-UA-PolinaNeural                 Female    General                Friendly, Positive
+ur-IN-GulNeural                    Female    General                Friendly, Positive
+ur-IN-SalmanNeural                 Male      General                Friendly, Positive
+ur-PK-AsadNeural                   Male      General                Friendly, Positive
+ur-PK-UzmaNeural                   Female    General                Friendly, Positive
+uz-UZ-MadinaNeural                 Female    General                Friendly, Positive
+uz-UZ-SardorNeural                 Male      General                Friendly, Positive
+vi-VN-HoaiMyNeural                 Female    General                Friendly, Positive
+vi-VN-NamMinhNeural                Male      General                Friendly, Positive
+zh-CN-XiaoxiaoNeural               Female    News, Novel            Warm
+zh-CN-XiaoyiNeural                 Female    Cartoon, Novel         Lively
+zh-CN-YunjianNeural                Male      Sports,  Novel         Passion
+zh-CN-YunxiNeural                  Male      Novel                  Lively, Sunshine
+zh-CN-YunxiaNeural                 Male      Cartoon, Novel         Cute
+zh-CN-YunyangNeural                Male      News                   Professional, Reliable
+zh-CN-liaoning-XiaobeiNeural       Female    Dialect                Humorous
+zh-CN-shaanxi-XiaoniNeural         Female    Dialect                Bright
+zh-HK-HiuGaaiNeural                Female    General                Friendly, Positive
+zh-HK-HiuMaanNeural                Female    General                Friendly, Positive
+zh-HK-WanLungNeural                Male      General                Friendly, Positive
+zh-TW-HsiaoChenNeural              Female    General                Friendly, Positive
+zh-TW-HsiaoYuNeural                Female    General                Friendly, Positive
+zh-TW-YunJheNeural                 Male      General                Friendly, Positive
+zu-ZA-ThandoNeural                 Female    General                Friendly, Positive
+zu-ZA-ThembaNeural                 Male      General                Friendly, Positive

deploy-package/scripts/gen-edge-tts-doc.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * gen-edge-tts-doc.js — 从 `edge-tts --list-voices` 输出生成完整 TTS 语言/音色文档
+ *
+ * Usage:
+ *   edge-tts --list-voices > /tmp/voices.txt
+ *   node gen-edge-tts-doc.js /tmp/voices.txt > docs/tts-edge-languages.md
+ *
+ * 输出:Markdown 表格 + 中文方言分类 + 完整 75 语言列表
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const inputFile = process.argv[2];
+if (!inputFile) {
+  console.error('Usage: node gen-edge-tts-doc.js <voices.txt>');
+  process.exit(1);
+}
+
+const raw = fs.readFileSync(inputFile, 'utf8');
+const lines = raw.split('\n').filter(Boolean);
+// 头两行是表头 + 分隔线,数据从第 3 行开始
+const dataLines = lines.slice(2);
+
+// 解析每行:ShortName \t Gender \t ContentCategories \t VoicePersonalities
+const voices = [];
+for (const line of dataLines) {
+  const cols = line.trim().split(/\s{2,}/);
+  if (cols.length < 2) continue;
+  const shortName = cols[0];
+  // ShortName 形如 zh-CN-XiaoxiaoNeural → locale=zh-CN, name=XiaoxiaoNeural, lang=zh
+  const m = shortName.match(/^([a-z]{2,3})(?:[-]([A-Z]{2}))?[-]([A-Za-z]+)$/);
+  if (!m) continue;
+  const [, lang, region, name] = m;
+  const locale = region ? `${lang}-${region}` : lang;
+  voices.push({
+    shortName,
+    lang,
+    region: region || '',
+    locale,
+    name,
+    gender: cols[1] || '',
+    contentCategories: cols[2] || '',
+    personalities: cols[3] || '',
+  });
+}
+
+// 按 locale 分组
+const byLocale = new Map();
+for (const v of voices) {
+  if (!byLocale.has(v.locale)) byLocale.set(v.locale, []);
+  byLocale.get(v.locale).push(v);
+}
+
+// 按语言聚合统计
+const langNames = {
+  af: '南非荷兰语 Afrikaans', ar: '阿拉伯语 Arabic', am: '阿姆哈拉语 Amharic',
+  az: '阿塞拜疆语 Azerbaijani', bg: '保加利亚语 Bulgarian', bn: '孟加拉语 Bengali',
+  bs: '波斯尼亚语 Bosnian', ca: '加泰罗尼亚语 Catalan', cs: '捷克语 Czech',
+  cy: '威尔士语 Welsh', da: '丹麦语 Danish', de: '德语 German',
+  el: '希腊语 Greek', en: '英语 English', es: '西班牙语 Spanish',
+  et: '爱沙尼亚语 Estonian', fa: '波斯语 Persian', fi: '芬兰语 Finnish',
+  fil: '菲律宾语 Filipino', fr: '法语 French', ga: '爱尔兰语 Irish',
+  gl: '加利西亚语 Galician', gu: '古吉拉特语 Gujarati', he: '希伯来语 Hebrew',
+  hi: '印地语 Hindi', hr: '克罗地亚语 Croatian', hu: '匈牙利语 Hungarian',
+  id: '印度尼西亚语 Indonesian', is: '冰岛语 Icelandic', it: '意大利语 Italian',
+  iu: '因纽特语 Inuktitut', ja: '日语 Japanese', jv: '爪哇语 Javanese',
+  ka: '格鲁吉亚语 Georgian', kk: '哈萨克语 Kazakh', km: '高棉语 Khmer',
+  kn: '卡纳达语 Kannada', ko: '韩语 Korean', lo: '老挝语 Lao',
+  lt: '立陶宛语 Lithuanian', lv: '拉脱维亚语 Latvian', mk: '马其顿语 Macedonian',
+  ml: '马拉雅拉姆语 Malayalam', mn: '蒙古语 Mongolian', mr: '马拉地语 Marathi',
+  ms: '马来语 Malay', mt: '马耳他语 Maltese', my: '缅甸语 Burmese',
+  nb: '挪威语(书面) Norwegian Bokmål', ne: '尼泊尔语 Nepali', nl: '荷兰语 Dutch',
+  pl: '波兰语 Polish', ps: '普什图语 Pashto', pt: '葡萄牙语 Portuguese',
+  ro: '罗马尼亚语 Romanian', ru: '俄语 Russian', si: '僧伽罗语 Sinhala',
+  sk: '斯洛伐克语 Slovak', sl: '斯洛文尼亚语 Slovenian', so: '索马里语 Somali',
+  sq: '阿尔巴尼亚语 Albanian', sr: '塞尔维亚语 Serbian', su: '巽他语 Sundanese',
+  sv: '瑞典语 Swedish', sw: '斯瓦希里语 Swahili', ta: '泰米尔语 Tamil',
+  te: '泰卢固语 Telugu', th: '泰语 Thai', tr: '土耳其语 Turkish',
+  uk: '乌克兰语 Ukrainian', ur: '乌尔都语 Urdu', uz: '乌兹别克语 Uzbek',
+  vi: '越南语 Vietnamese', zh: '中文 Chinese', zu: '祖鲁语 Zulu',
+};
+
+const localesByLang = new Map();
+for (const [locale, arr] of byLocale.entries()) {
+  const lang = arr[0].lang;
+  if (!localesByLang.has(lang)) localesByLang.set(lang, []);
+  localesByLang.get(lang).push(locale);
+}
+for (const [, arr] of localesByLang) arr.sort();
+
+// 中文方言单独分类
+const zhDialects = {
+  'zh-CN': '普通话(中国大陆)',
+  'zh-HK': '粤语(香港)',
+  'zh-TW': '国语(台湾)',
+  'zh-CN-sichuan': '四川话',
+  'zh-CN-liaoning': '东北话',
+  'zh-CN-shaanxi': '陕西方言',
+};
+
+const md = [];
+md.push('# Edge TTS 支持的语言 / 音色清单');
+md.push('');
+md.push(`> 自动生成自 edge-tts 7.2.8 (--list-voices)。共 **${voices.length} 个音色**,覆盖 **${localesByLang.size} 种语言**。`);
+md.push('');
+md.push('**项目当前使用:** `zh-CN-XiaoxiaoNeural`(中文温柔女声,在 `server/src/config/models.json` 的 `tts.defaultVoice` 配置)。');
+md.push('');
+md.push('**特性:** Edge TTS 是 Microsoft Edge 浏览器的"大声朗读"引擎,基于 Azure 神经网络,**完全免费**、**免 API Key**、单次最长 ~3000 字符、中文安全 1000 字。');
+md.push('');
+
+// ========== 中文方言(单独高亮) ==========
+md.push('## 中文方言(项目最常用)');
+md.push('');
+md.push('| Locale | 方言 | 音色数 | 常用音色 |');
+md.push('|--------|------|--------|---------|');
+for (const [locale, name] of Object.entries(zhDialects)) {
+  const arr = byLocale.get(locale) || [];
+  const sampleNames = arr.map(v => v.name).slice(0, 4).join(', ');
+  md.push(`| ${locale} | ${name} | ${arr.length} | ${sampleNames}${arr.length > 4 ? '...' : ''} |`);
+}
+md.push('');
+
+// ========== 完整中文音色列表 ==========
+md.push('### 全部中文音色(14 个)');
+md.push('');
+md.push('| ShortName | 性别 | 风格 |');
+md.push('|-----------|------|------|');
+const zhVoices = voices.filter(v => v.lang === 'zh').sort((a, b) => a.shortName.localeCompare(b.shortName));
+for (const v of zhVoices) {
+  md.push(`| \`${v.shortName}\` | ${v.gender} | ${v.personalities || v.contentCategories} |`);
+}
+md.push('');
+
+// ========== 75 种语言汇总 ==========
+md.push(`## 全部 ${localesByLang.size} 种语言汇总`);
+md.push('');
+md.push('按字母排序,展示每个 Locale 的音色数:');
+md.push('');
+md.push('| Locale | 语言 | 音色数 | 主要音色 |');
+md.push('|--------|------|--------|---------|');
+const sortedLangs = [...localesByLang.keys()].sort();
+for (const lang of sortedLangs) {
+  const locales = localesByLang.get(lang);
+  const langName = langNames[lang] || lang;
+  for (const locale of locales) {
+    const arr = byLocale.get(locale);
+    const sampleNames = arr.map(v => v.name).slice(0, 3).join(', ');
+    md.push(`| ${locale} | ${langName} | ${arr.length} | ${sampleNames}${arr.length > 3 ? '...' : ''} |`);
+  }
+}
+md.push('');
+
+// ========== 使用示例 ==========
+md.push('## 切换音色 / 语言');
+md.push('');
+md.push('### 命令行测试');
+md.push('');
+md.push('```bash');
+md.push('# 中文女声(默认)');
+md.push('edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media out.mp3');
+md.push('');
+md.push('# 粤语女声');
+md.push('edge-tts --voice zh-HK-HiuMaanNeural --text "你好,這是粵語測試" --write-media cantonese.mp3');
+md.push('');
+md.push('# 四川话');
+md.push('edge-tts --voice zh-CN-sichuan-YunxiNeural --text "今天天气好巴适" --write-media sc.mp3');
+md.push('');
+md.push('# 英语男声');
+md.push('edge-tts --voice en-US-GuyNeural --text "Hello, world." --write-media en.mp3');
+md.push('');
+md.push('# 日语女声');
+md.push('edge-tts --voice ja-JP-NanamiNeural --text "こんにちは" --write-media ja.mp3');
+md.push('');
+md.push('# 一次性列出全部语音');
+md.push('edge-tts --list-voices > voices.txt');
+md.push('```');
+md.push('');
+md.push('### 项目内修改默认音色');
+md.push('');
+md.push('编辑 `server/src/config/models.json`:');
+md.push('');
+md.push('```json');
+md.push('{');
+md.push('  "tts": {');
+md.push('    "defaultVendor": "edge",');
+md.push('    "defaultModel": "edge-tts",');
+md.push('    "defaultVoice": "zh-CN-XiaoxiaoNeural"   // ← 改这里');
+md.push('  }');
+md.push('}');
+md.push('```');
+md.push('');
+md.push('或者环境变量覆盖(在 `server/.env`):');
+md.push('');
+md.push('```bash');
+md.push('EDGE_TTS_VOICE=zh-HK-HiuMaanNeural');
+md.push('```');
+md.push('');
+md.push('### API 调用时按音色生成');
+md.push('');
+md.push('前端 → 后端 `/api/tts/generate` 接口传 `voiceId` 字段:');
+md.push('');
+md.push('```json');
+md.push('{');
+md.push('  "text": "你好世界",');
+md.push('  "voiceId": "zh-CN-YunxiNeural"');
+md.push('}');
+md.push('```');
+md.push('');
+
+// ========== 前端统一音色 ID 映射 ==========
+md.push('## 前端统一音色 ID → 实际 Edge TTS 音色映射');
+md.push('');
+md.push('前端用 10 个统一 ID(`voice_01`~`voice_10`)展示,后端 `edge-tts.provider.ts:51-62` 的 `EDGE_VOICE_MAP` 把它们映射到实际 Edge 音色:');
+md.push('');
+md.push('| 前端 ID | 实际 Edge 音色 | 描述 |');
+md.push('|---------|----------------|------|');
+const map = [
+  ['voice_01', 'zh-CN-XiaoxiaoNeural', '温柔女声'],
+  ['voice_02', 'zh-CN-YunxiNeural', '磁性男声'],
+  ['voice_03', 'zh-CN-XiaoyiNeural', '活泼女声'],
+  ['voice_04', 'zh-CN-YunyangNeural', '知性女声(新闻)'],
+  ['voice_05', 'zh-CN-YunjianNeural', '阳光男声'],
+  ['voice_06', 'zh-CN-YunyangNeural', '沧桑男声'],
+  ['voice_07', 'zh-CN-XiaoxiaoNeural', '甜美女声'],
+  ['voice_08', 'zh-CN-YunxiNeural', '清朗男声'],
+  ['voice_09', 'zh-CN-XiaoyiNeural', '亲切女声'],
+  ['voice_10', 'zh-CN-XiaoshuangNeural', '稚嫩童声'],
+];
+for (const [id, voice, desc] of map) {
+  md.push(`| ${id} | \`${voice}\` | ${desc} |`);
+}
+md.push('');
+md.push('> 当前 10 个统一 ID 实际只用到 6 种 Edge 音色,语音方案日后续可补充粤语、英语等跨语言音色(增加 voiceId 11~20 等)。');
+md.push('');
+
+// ========== 已知限制 ==========
+md.push('## 已知限制');
+md.push('');
+md.push('- **文本长度:** 单次 ~3000 字符(中文约 1000 字),超出会被服务端拒绝。代码已自动按 1000 字分段拼接(`tts.service.ts` 的 `splitText`)。');
+md.push('- **语速控制:** `--rate` 参数是**后处理时间拉伸**,听感等同于播放器 `audio.playbackRate`(见 `docs/tts-speed-note.md` 或代码 commit dd1fea03)。');
+md.push('- **稳定性:** 依赖微软服务器,偶尔会限频(502/timeout),代码已加 retry + 多个 vendor fallback(`provider.registry.ts`)。');
+md.push('- **没商用授权:** 内部使用 OK,正式商用建议切阿里云 CosyVoice/Qwen-TTS。');
+md.push('');
+
+// ========== 维护 ==========
+md.push('## 如何更新本文档');
+md.push('');
+md.push('Edge TTS 升级可能新增/删除音色,重新生成:');
+md.push('');
+md.push('```bash');
+md.push('# 1. 服务器上导出最新列表');
+md.push('ssh root@8.159.134.106 "edge-tts --list-voices" > /tmp/voices.txt');
+md.push('');
+md.push('# 2. 本地跑脚本生成');
+md.push('node deploy-package/scripts/gen-edge-tts-doc.js /tmp/voices.txt > docs/tts-edge-languages.md');
+md.push('');
+md.push('# 3. 提交');
+md.push('git add docs/tts-edge-languages.md deploy-package/edge-voices-snapshot.txt');
+md.push('git commit -m "docs(tts): 更新 Edge TTS 音色清单"');
+md.push('```');
+md.push('');
+
+process.stdout.write(md.join('\n'));

docs/tts-edge-languages.md

@@ -0,0 +1,277 @@
+# Edge TTS 支持的语言 / 音色清单
+
+> 自动生成自 edge-tts 7.2.8 (--list-voices)。共 **316 个音色**,覆盖 **74 种语言**。
+
+**项目当前使用:** `zh-CN-XiaoxiaoNeural`(中文温柔女声,在 `server/src/config/models.json` 的 `tts.defaultVoice` 配置)。
+
+**特性:** Edge TTS 是 Microsoft Edge 浏览器的"大声朗读"引擎,基于 Azure 神经网络,**完全免费**、**免 API Key**、单次最长 ~3000 字符、中文安全 1000 字。
+
+## 中文方言(项目最常用)
+
+| Locale | 方言 | 音色数 | 常用音色 |
+|--------|------|--------|---------|
+| zh-CN | 普通话(中国大陆) | 6 | XiaoxiaoNeural, XiaoyiNeural, YunjianNeural, YunxiNeural... |
+| zh-HK | 粤语(香港) | 3 | HiuGaaiNeural, HiuMaanNeural, WanLungNeural |
+| zh-TW | 国语(台湾) | 3 | HsiaoChenNeural, HsiaoYuNeural, YunJheNeural |
+| zh-CN-sichuan | 四川话 | 0 |  |
+| zh-CN-liaoning | 东北话 | 0 |  |
+| zh-CN-shaanxi | 陕西方言 | 0 |  |
+
+### 全部中文音色(14 个)
+
+| ShortName | 性别 | 风格 |
+|-----------|------|------|
+| `zh-CN-XiaoxiaoNeural` | Female | Warm |
+| `zh-CN-XiaoyiNeural` | Female | Lively |
+| `zh-CN-YunjianNeural` | Male | Novel |
+| `zh-CN-YunxiaNeural` | Male | Cute |
+| `zh-CN-YunxiNeural` | Male | Lively, Sunshine |
+| `zh-CN-YunyangNeural` | Male | Professional, Reliable |
+| `zh-HK-HiuGaaiNeural` | Female | Friendly, Positive |
+| `zh-HK-HiuMaanNeural` | Female | Friendly, Positive |
+| `zh-HK-WanLungNeural` | Male | Friendly, Positive |
+| `zh-TW-HsiaoChenNeural` | Female | Friendly, Positive |
+| `zh-TW-HsiaoYuNeural` | Female | Friendly, Positive |
+| `zh-TW-YunJheNeural` | Male | Friendly, Positive |
+
+## 全部 74 种语言汇总
+
+按字母排序,展示每个 Locale 的音色数:
+
+| Locale | 语言 | 音色数 | 主要音色 |
+|--------|------|--------|---------|
+| af-ZA | 南非荷兰语 Afrikaans | 2 | AdriNeural, WillemNeural |
+| am-ET | 阿姆哈拉语 Amharic | 2 | AmehaNeural, MekdesNeural |
+| ar-AE | 阿拉伯语 Arabic | 2 | FatimaNeural, HamdanNeural |
+| ar-BH | 阿拉伯语 Arabic | 2 | AliNeural, LailaNeural |
+| ar-DZ | 阿拉伯语 Arabic | 2 | AminaNeural, IsmaelNeural |
+| ar-EG | 阿拉伯语 Arabic | 2 | SalmaNeural, ShakirNeural |
+| ar-IQ | 阿拉伯语 Arabic | 2 | BasselNeural, RanaNeural |
+| ar-JO | 阿拉伯语 Arabic | 2 | SanaNeural, TaimNeural |
+| ar-KW | 阿拉伯语 Arabic | 2 | FahedNeural, NouraNeural |
+| ar-LB | 阿拉伯语 Arabic | 2 | LaylaNeural, RamiNeural |
+| ar-LY | 阿拉伯语 Arabic | 2 | ImanNeural, OmarNeural |
+| ar-MA | 阿拉伯语 Arabic | 2 | JamalNeural, MounaNeural |
+| ar-OM | 阿拉伯语 Arabic | 2 | AbdullahNeural, AyshaNeural |
+| ar-QA | 阿拉伯语 Arabic | 2 | AmalNeural, MoazNeural |
+| ar-SA | 阿拉伯语 Arabic | 2 | HamedNeural, ZariyahNeural |
+| ar-SY | 阿拉伯语 Arabic | 2 | AmanyNeural, LaithNeural |
+| ar-TN | 阿拉伯语 Arabic | 2 | HediNeural, ReemNeural |
+| ar-YE | 阿拉伯语 Arabic | 2 | MaryamNeural, SalehNeural |
+| az-AZ | 阿塞拜疆语 Azerbaijani | 2 | BabekNeural, BanuNeural |
+| bg-BG | 保加利亚语 Bulgarian | 2 | BorislavNeural, KalinaNeural |
+| bn-BD | 孟加拉语 Bengali | 2 | NabanitaNeural, PradeepNeural |
+| bn-IN | 孟加拉语 Bengali | 2 | BashkarNeural, TanishaaNeural |
+| bs-BA | 波斯尼亚语 Bosnian | 2 | GoranNeural, VesnaNeural |
+| ca-ES | 加泰罗尼亚语 Catalan | 2 | EnricNeural, JoanaNeural |
+| cs-CZ | 捷克语 Czech | 2 | AntoninNeural, VlastaNeural |
+| cy-GB | 威尔士语 Welsh | 2 | AledNeural, NiaNeural |
+| da-DK | 丹麦语 Danish | 2 | ChristelNeural, JeppeNeural |
+| de-AT | 德语 German | 2 | IngridNeural, JonasNeural |
+| de-CH | 德语 German | 2 | JanNeural, LeniNeural |
+| de-DE | 德语 German | 6 | AmalaNeural, ConradNeural, FlorianMultilingualNeural... |
+| el-GR | 希腊语 Greek | 2 | AthinaNeural, NestorasNeural |
+| en-AU | 英语 English | 2 | NatashaNeural, WilliamMultilingualNeural |
+| en-CA | 英语 English | 2 | ClaraNeural, LiamNeural |
+| en-GB | 英语 English | 5 | LibbyNeural, MaisieNeural, RyanNeural... |
+| en-HK | 英语 English | 2 | SamNeural, YanNeural |
+| en-IE | 英语 English | 2 | ConnorNeural, EmilyNeural |
+| en-IN | 英语 English | 3 | NeerjaExpressiveNeural, NeerjaNeural, PrabhatNeural |
+| en-KE | 英语 English | 2 | AsiliaNeural, ChilembaNeural |
+| en-NG | 英语 English | 2 | AbeoNeural, EzinneNeural |
+| en-NZ | 英语 English | 2 | MitchellNeural, MollyNeural |
+| en-PH | 英语 English | 2 | JamesNeural, RosaNeural |
+| en-SG | 英语 English | 2 | LunaNeural, WayneNeural |
+| en-TZ | 英语 English | 2 | ElimuNeural, ImaniNeural |
+| en-US | 英语 English | 17 | AnaNeural, AndrewMultilingualNeural, AndrewNeural... |
+| en-ZA | 英语 English | 2 | LeahNeural, LukeNeural |
+| es-AR | 西班牙语 Spanish | 2 | ElenaNeural, TomasNeural |
+| es-BO | 西班牙语 Spanish | 2 | MarceloNeural, SofiaNeural |
+| es-CL | 西班牙语 Spanish | 2 | CatalinaNeural, LorenzoNeural |
+| es-CO | 西班牙语 Spanish | 2 | GonzaloNeural, SalomeNeural |
+| es-CR | 西班牙语 Spanish | 2 | JuanNeural, MariaNeural |
+| es-CU | 西班牙语 Spanish | 2 | BelkysNeural, ManuelNeural |
+| es-DO | 西班牙语 Spanish | 2 | EmilioNeural, RamonaNeural |
+| es-EC | 西班牙语 Spanish | 2 | AndreaNeural, LuisNeural |
+| es-ES | 西班牙语 Spanish | 3 | AlvaroNeural, ElviraNeural, XimenaNeural |
+| es-GQ | 西班牙语 Spanish | 2 | JavierNeural, TeresaNeural |
+| es-GT | 西班牙语 Spanish | 2 | AndresNeural, MartaNeural |
+| es-HN | 西班牙语 Spanish | 2 | CarlosNeural, KarlaNeural |
+| es-MX | 西班牙语 Spanish | 2 | DaliaNeural, JorgeNeural |
+| es-NI | 西班牙语 Spanish | 2 | FedericoNeural, YolandaNeural |
+| es-PA | 西班牙语 Spanish | 2 | MargaritaNeural, RobertoNeural |
+| es-PE | 西班牙语 Spanish | 2 | AlexNeural, CamilaNeural |
+| es-PR | 西班牙语 Spanish | 2 | KarinaNeural, VictorNeural |
+| es-PY | 西班牙语 Spanish | 2 | MarioNeural, TaniaNeural |
+| es-SV | 西班牙语 Spanish | 2 | LorenaNeural, RodrigoNeural |
+| es-US | 西班牙语 Spanish | 2 | AlonsoNeural, PalomaNeural |
+| es-UY | 西班牙语 Spanish | 2 | MateoNeural, ValentinaNeural |
+| es-VE | 西班牙语 Spanish | 2 | PaolaNeural, SebastianNeural |
+| et-EE | 爱沙尼亚语 Estonian | 2 | AnuNeural, KertNeural |
+| fa-IR | 波斯语 Persian | 2 | DilaraNeural, FaridNeural |
+| fi-FI | 芬兰语 Finnish | 2 | HarriNeural, NooraNeural |
+| fil-PH | 菲律宾语 Filipino | 2 | AngeloNeural, BlessicaNeural |
+| fr-BE | 法语 French | 2 | CharlineNeural, GerardNeural |
+| fr-CA | 法语 French | 4 | AntoineNeural, JeanNeural, SylvieNeural... |
+| fr-CH | 法语 French | 2 | ArianeNeural, FabriceNeural |
+| fr-FR | 法语 French | 5 | DeniseNeural, EloiseNeural, HenriNeural... |
+| ga-IE | 爱尔兰语 Irish | 2 | ColmNeural, OrlaNeural |
+| gl-ES | 加利西亚语 Galician | 2 | RoiNeural, SabelaNeural |
+| gu-IN | 古吉拉特语 Gujarati | 2 | DhwaniNeural, NiranjanNeural |
+| he-IL | 希伯来语 Hebrew | 2 | AvriNeural, HilaNeural |
+| hi-IN | 印地语 Hindi | 2 | MadhurNeural, SwaraNeural |
+| hr-HR | 克罗地亚语 Croatian | 2 | GabrijelaNeural, SreckoNeural |
+| hu-HU | 匈牙利语 Hungarian | 2 | NoemiNeural, TamasNeural |
+| id-ID | 印度尼西亚语 Indonesian | 2 | ArdiNeural, GadisNeural |
+| is-IS | 冰岛语 Icelandic | 2 | GudrunNeural, GunnarNeural |
+| it-IT | 意大利语 Italian | 4 | DiegoNeural, ElsaNeural, GiuseppeMultilingualNeural... |
+| ja-JP | 日语 Japanese | 2 | KeitaNeural, NanamiNeural |
+| jv-ID | 爪哇语 Javanese | 2 | DimasNeural, SitiNeural |
+| ka-GE | 格鲁吉亚语 Georgian | 2 | EkaNeural, GiorgiNeural |
+| kk-KZ | 哈萨克语 Kazakh | 2 | AigulNeural, DauletNeural |
+| km-KH | 高棉语 Khmer | 2 | PisethNeural, SreymomNeural |
+| kn-IN | 卡纳达语 Kannada | 2 | GaganNeural, SapnaNeural |
+| ko-KR | 韩语 Korean | 3 | HyunsuMultilingualNeural, InJoonNeural, SunHiNeural |
+| lo-LA | 老挝语 Lao | 2 | ChanthavongNeural, KeomanyNeural |
+| lt-LT | 立陶宛语 Lithuanian | 2 | LeonasNeural, OnaNeural |
+| lv-LV | 拉脱维亚语 Latvian | 2 | EveritaNeural, NilsNeural |
+| mk-MK | 马其顿语 Macedonian | 2 | AleksandarNeural, MarijaNeural |
+| ml-IN | 马拉雅拉姆语 Malayalam | 2 | MidhunNeural, SobhanaNeural |
+| mn-MN | 蒙古语 Mongolian | 2 | BataaNeural, YesuiNeural |
+| mr-IN | 马拉地语 Marathi | 2 | AarohiNeural, ManoharNeural |
+| ms-MY | 马来语 Malay | 2 | OsmanNeural, YasminNeural |
+| mt-MT | 马耳他语 Maltese | 2 | GraceNeural, JosephNeural |
+| my-MM | 缅甸语 Burmese | 2 | NilarNeural, ThihaNeural |
+| nb-NO | 挪威语(书面) Norwegian Bokmål | 2 | FinnNeural, PernilleNeural |
+| ne-NP | 尼泊尔语 Nepali | 2 | HemkalaNeural, SagarNeural |
+| nl-BE | 荷兰语 Dutch | 2 | ArnaudNeural, DenaNeural |
+| nl-NL | 荷兰语 Dutch | 3 | ColetteNeural, FennaNeural, MaartenNeural |
+| pl-PL | 波兰语 Polish | 2 | MarekNeural, ZofiaNeural |
+| ps-AF | 普什图语 Pashto | 2 | GulNawazNeural, LatifaNeural |
+| pt-BR | 葡萄牙语 Portuguese | 3 | AntonioNeural, FranciscaNeural, ThalitaMultilingualNeural |
+| pt-PT | 葡萄牙语 Portuguese | 2 | DuarteNeural, RaquelNeural |
+| ro-RO | 罗马尼亚语 Romanian | 2 | AlinaNeural, EmilNeural |
+| ru-RU | 俄语 Russian | 2 | DmitryNeural, SvetlanaNeural |
+| si-LK | 僧伽罗语 Sinhala | 2 | SameeraNeural, ThiliniNeural |
+| sk-SK | 斯洛伐克语 Slovak | 2 | LukasNeural, ViktoriaNeural |
+| sl-SI | 斯洛文尼亚语 Slovenian | 2 | PetraNeural, RokNeural |
+| so-SO | 索马里语 Somali | 2 | MuuseNeural, UbaxNeural |
+| sq-AL | 阿尔巴尼亚语 Albanian | 2 | AnilaNeural, IlirNeural |
+| sr-RS | 塞尔维亚语 Serbian | 2 | NicholasNeural, SophieNeural |
+| su-ID | 巽他语 Sundanese | 2 | JajangNeural, TutiNeural |
+| sv-SE | 瑞典语 Swedish | 2 | MattiasNeural, SofieNeural |
+| sw-KE | 斯瓦希里语 Swahili | 2 | RafikiNeural, ZuriNeural |
+| sw-TZ | 斯瓦希里语 Swahili | 2 | DaudiNeural, RehemaNeural |
+| ta-IN | 泰米尔语 Tamil | 2 | PallaviNeural, ValluvarNeural |
+| ta-LK | 泰米尔语 Tamil | 2 | KumarNeural, SaranyaNeural |
+| ta-MY | 泰米尔语 Tamil | 2 | KaniNeural, SuryaNeural |
+| ta-SG | 泰米尔语 Tamil | 2 | AnbuNeural, VenbaNeural |
+| te-IN | 泰卢固语 Telugu | 2 | MohanNeural, ShrutiNeural |
+| th-TH | 泰语 Thai | 2 | NiwatNeural, PremwadeeNeural |
+| tr-TR | 土耳其语 Turkish | 2 | AhmetNeural, EmelNeural |
+| uk-UA | 乌克兰语 Ukrainian | 2 | OstapNeural, PolinaNeural |
+| ur-IN | 乌尔都语 Urdu | 2 | GulNeural, SalmanNeural |
+| ur-PK | 乌尔都语 Urdu | 2 | AsadNeural, UzmaNeural |
+| uz-UZ | 乌兹别克语 Uzbek | 2 | MadinaNeural, SardorNeural |
+| vi-VN | 越南语 Vietnamese | 2 | HoaiMyNeural, NamMinhNeural |
+| zh-CN | 中文 Chinese | 6 | XiaoxiaoNeural, XiaoyiNeural, YunjianNeural... |
+| zh-HK | 中文 Chinese | 3 | HiuGaaiNeural, HiuMaanNeural, WanLungNeural |
+| zh-TW | 中文 Chinese | 3 | HsiaoChenNeural, HsiaoYuNeural, YunJheNeural |
+| zu-ZA | 祖鲁语 Zulu | 2 | ThandoNeural, ThembaNeural |
+
+## 切换音色 / 语言
+
+### 命令行测试
+
+```bash
+# 中文女声(默认)
+edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media out.mp3
+
+# 粤语女声
+edge-tts --voice zh-HK-HiuMaanNeural --text "你好,這是粵語測試" --write-media cantonese.mp3
+
+# 四川话
+edge-tts --voice zh-CN-sichuan-YunxiNeural --text "今天天气好巴适" --write-media sc.mp3
+
+# 英语男声
+edge-tts --voice en-US-GuyNeural --text "Hello, world." --write-media en.mp3
+
+# 日语女声
+edge-tts --voice ja-JP-NanamiNeural --text "こんにちは" --write-media ja.mp3
+
+# 一次性列出全部语音
+edge-tts --list-voices > voices.txt
+```
+
+### 项目内修改默认音色
+
+编辑 `server/src/config/models.json`:
+
+```json
+{
+  "tts": {
+    "defaultVendor": "edge",
+    "defaultModel": "edge-tts",
+    "defaultVoice": "zh-CN-XiaoxiaoNeural"   // ← 改这里
+  }
+}
+```
+
+或者环境变量覆盖(在 `server/.env`):
+
+```bash
+EDGE_TTS_VOICE=zh-HK-HiuMaanNeural
+```
+
+### API 调用时按音色生成
+
+前端 → 后端 `/api/tts/generate` 接口传 `voiceId` 字段:
+
+```json
+{
+  "text": "你好世界",
+  "voiceId": "zh-CN-YunxiNeural"
+}
+```
+
+## 前端统一音色 ID → 实际 Edge TTS 音色映射
+
+前端用 10 个统一 ID(`voice_01`~`voice_10`)展示,后端 `edge-tts.provider.ts:51-62` 的 `EDGE_VOICE_MAP` 把它们映射到实际 Edge 音色:
+
+| 前端 ID | 实际 Edge 音色 | 描述 |
+|---------|----------------|------|
+| voice_01 | `zh-CN-XiaoxiaoNeural` | 温柔女声 |
+| voice_02 | `zh-CN-YunxiNeural` | 磁性男声 |
+| voice_03 | `zh-CN-XiaoyiNeural` | 活泼女声 |
+| voice_04 | `zh-CN-YunyangNeural` | 知性女声(新闻) |
+| voice_05 | `zh-CN-YunjianNeural` | 阳光男声 |
+| voice_06 | `zh-CN-YunyangNeural` | 沧桑男声 |
+| voice_07 | `zh-CN-XiaoxiaoNeural` | 甜美女声 |
+| voice_08 | `zh-CN-YunxiNeural` | 清朗男声 |
+| voice_09 | `zh-CN-XiaoyiNeural` | 亲切女声 |
+| voice_10 | `zh-CN-XiaoshuangNeural` | 稚嫩童声 |
+
+> 当前 10 个统一 ID 实际只用到 6 种 Edge 音色,语音方案日后续可补充粤语、英语等跨语言音色(增加 voiceId 11~20 等)。
+
+## 已知限制
+
+- **文本长度:** 单次 ~3000 字符(中文约 1000 字),超出会被服务端拒绝。代码已自动按 1000 字分段拼接(`tts.service.ts` 的 `splitText`)。
+- **语速控制:** `--rate` 参数是**后处理时间拉伸**,听感等同于播放器 `audio.playbackRate`(见 `docs/tts-speed-note.md` 或代码 commit dd1fea03)。
+- **稳定性:** 依赖微软服务器,偶尔会限频(502/timeout),代码已加 retry + 多个 vendor fallback(`provider.registry.ts`)。
+- **没商用授权:** 内部使用 OK,正式商用建议切阿里云 CosyVoice/Qwen-TTS。
+
+## 如何更新本文档
+
+Edge TTS 升级可能新增/删除音色,重新生成:
+
+```bash
+# 1. 服务器上导出最新列表
+ssh root@8.159.134.106 "edge-tts --list-voices" > /tmp/voices.txt
+
+# 2. 本地跑脚本生成
+node deploy-package/scripts/gen-edge-tts-doc.js /tmp/voices.txt > docs/tts-edge-languages.md
+
+# 3. 提交
+git add docs/tts-edge-languages.md deploy-package/edge-voices-snapshot.txt
+git commit -m "docs(tts): 更新 Edge TTS 音色清单"
+```