dsh-line-bot 0.9.7 → 0.10.0

package/AGENTS.md

@@ -31,6 +31,7 @@ curl -s http://127.0.0.1:8791/health
 | 主動訊息沒出現 | 面板「主動傳訊」 | 每位使用者的倒數還沒到、每日／每月上限、靜音時段、兩則間距冷卻、連續未回覆已被暫停、沒有 session 或不在白名單 | 看 `status.nudge`、使用者表的「下次主動／未回覆」與日誌 |
 | 餘額提醒沒出現 | `balance` | provider 不是 `deepseek-account`、餘額高於門檻、冷卻中、靜音 | 面板「DeepSeek 餘額」看 `applicable`、`lastAskAt` |
 | Windows 安裝失敗 | CLI | 找不到 DSH 內建 pnpm；舊版 spawn `.cmd` 失敗 | 用面板安裝，或升級 CLI；必要時 `npm i -g pnpm` |
+| 語音沒送出或一直回文字 | 面板「語音回覆」、日誌 | 尚未按一鍵配置環境、未確認聲音使用權、沒有 ffmpeg、MLX 載入失敗、reply token 過期 | 面板「語音回覆」按一鍵配置與測試；看日誌 `語音回覆`／`語音合成失敗`；必要時看 `status.voice` |
 | npm `ETARGET` | — | registry／CDN 還沒傳播 | 等 1–5 分鐘再試 |
 
 ## 2. 圖片沒送出的排查順序
@@ -50,6 +51,7 @@ curl -s http://127.0.0.1:8791/health
 - `lib/meme-source.mjs`：讀 dsh-meme。
 - `lib/chat-import.mjs`：LINE 匯出聊天解析。
 - `lib/diagnostics.mjs`：doctor 用的檢查工具。
+- `lib/tts.mjs`／`tools/mlx_synth.py`：CosyVoice3 語音合成（MLX／GGUF）。
 - `bin/cli.mjs`：安裝／`doctor`。
 - HTTP：`/api/line-bot/status|config|action|doctor`（webServer）、`http://127.0.0.1:<port>/doctor|health|media/<id>|webhook`（外掛自己的伺服器）。
 - 資料：`$DSH_HOME/line-bot/`（config.json 600、state.json、memories.json、logs、personas、cache、users）。

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.10.0
+
+- 新增語音回覆（CosyVoice3-0.5B）：角色可以在回覆最後加 `[[voice]]`，插件會把文字合成語音並用 LINE 語音訊息送出；合成失敗或 reply token 過期時自動改用文字／push。
+- macOS（Apple Silicon）用 MLX 在本機合成；Windows／沒有 MLX 時用 CosyVoice GGUF（CrispASR）。面板可一鍵偵測與配置環境、開關語音、上傳參考音、調整語氣指令與長度、試聽。
+- 參考音預設使用指定音檔的 12–16 秒片段（存在 `<DSH_HOME>/line-bot/tts/ref/default.wav`）；可上傳自己的音檔替換。
+- 使用前必須在面板確認「有使用此聲音的權利」；語音檔會存在本機媒體庫，透過 tunnel 的 `/media/<token>` 提供給 LINE。
+
 # Changelog
 
 ## 0.9.7

package/README.en.md

@@ -99,6 +99,7 @@ At the top of the panel is a **sticky save bar**: "Save changes / Refresh" stays
 | Jokes | Text joke library: built-in seeds, Tieba quotes, wanjiqi barrage memes; per-source toggles, per-turn injection count, add/delete entries |
 | Personal memory | Per-user long-term memory, expiry cleanup, daily self-review, manual delete |
 | Memes | Reply with images/stickers from the dsh-meme library, enable/disable, image limit, and sample previews |
+| Voice replies | CosyVoice3 speech synthesis, on/off, reference upload, instruct style, audio preview |
 | Sticker & image vision | Fetch incoming LINE stickers or images and show them to the model; when the model cannot read images, describe them with modlens or a vision model (can be disabled) |
 | DeepSeek balance | Current balance, per-turn context, low-balance proactive reminder, threshold and cooldown (deepseek-account only) |
 | Proactive messages | Toggle, per-user countdown, min/max interval, unanswered limit, daily/monthly caps, minimum gap, quiet hours, idle, target users, prompt, send a test now, statistics (next possible time and paused users) |
@@ -224,6 +225,14 @@ The persona can attach a sticker to a text reply, or reply with just an image. I
 - When a LINE sticker arrives, the bot fetches the image and shows it to the model; vision-capable models read it directly, otherwise the bot asks modlens, then tries another vision model, and only then falls back to the keywords LINE provides. Turn "Understand stickers" off in the LINE credentials card to use keywords only.
 - Regular images work the same way: the bot downloads them through LINE's content API and attaches them to the message; if the model cannot read images, the same modlens / vision-model description path is used. Turn "Understand images" off in the LINE credentials card to skip them.
 - Without dsh-meme installed, the feature stays off and replies are text only.
+## Voice replies (CosyVoice3)
+
+- The persona can put `[[voice]]` at the end of a reply; the plugin synthesizes the text with CosyVoice3-0.5B and sends a LINE audio message (m4a).
+- On Apple Silicon macOS it synthesizes locally with MLX; on Windows (or without MLX) it uses CosyVoice GGUF (CrispASR). Press "Set up environment" once in the panel (downloads roughly 1–2 GB).
+- The "Voice replies" card toggles the feature, requires confirming that you have the rights to the voice, lets you upload a reference clip (the default is a 12–16 s cut of the provided sample), choose instruct/zero-shot mode, and preview the audio.
+- Synthesis takes about 20–40 s; if the reply token expires it falls back to push. Audio is stored under `<DSH_HOME>/line-bot/media/` and served at `/media/<token>` through the tunnel.
+- Requires `ffmpeg`; MLX mode needs Python 3.10+.
+
 ## Diagnostics
 - Panel → Advanced → Run diagnostics checks the server, tunnel, public URL, webhook, dsh-meme library, image converters, model, and recent errors; Safe repair only reconnects the tunnel and re-applies the webhook.
 - CLI: `npx dsh-line-bot doctor`, `doctor --fix`, `doctor --json`.
@@ -258,4 +267,4 @@ The persona can attach a sticker to a text reply, or reply with just an image. I
 
 - Host logic: `lib/*.mjs` (`util` / `config` / `line-api` / `persona` / `agent-runner` / `webhook-server` / `cloudflare` / `tunnel` / `nudge` / `tieba-sync` / `host`).
 - Panel: `client.js` (registers `settings.section` via `window.__ModuleLoader__`).
-- Entry point: `index.js` (mounts `/api/line-bot`, dev reload, cleanup on unload).
+- Entry point: `index.js` (mounts `/api/line-bot`, dev reload, cleanup on unload).

package/README.ja.md

@@ -99,6 +99,7 @@ npx dsh-line-bot install --no-companions
 | ジョーク | テキストネタ集：内蔵シード、貼吧名台詞、wanjiqi 弾幕ネタ。ソース別の切り替え、ターンごとの注入数、追加／削除 |
 | 個人メモリ | ユーザーごとの長期記憶、期限切れの自動削除、毎日の自己整理、手動削除 |
 | 表情パック | dsh-meme の画像ライブラリで画像／スタンプを返信、オンオフ、1 回の上限、サンプル表示 |
+| 音声返信 | CosyVoice3 による音声合成、オンオフ、参照音声アップロード、instruct、試聴 |
 | スタンプ・画像理解 | LINE スタンプや通常の画像を受信したら取得してモデルに見せる。画像非対応モデルは modlens や別の視覚モデルで説明（オフ可） |
 | DeepSeek 残高 | 現在の残高、毎ターンの注入、残高が少ないときの主動リマインド、しきい値とクールダウン（deepseek-account のみ） |
 | 自発メッセージ | オン／オフ、ユーザーごとのカウントダウン、最短／最長間隔、連続未返信の上限、1 日／1 か月の上限、最低間隔、静かな時間帯、idle、対象ユーザー、プロンプト、今すぐ試送、統計（次回予定と一時停止中の人数） |
@@ -224,6 +225,14 @@ Bot がグループ（または複数人のルーム）に追加されたとき
 - LINE スタンプを受信すると、スタンプ画像を取得してモデルに見せます。画像対応モデルはそのまま読み、非対応ならまず modlens、次に別の視覚モデルで説明し、最後に LINE のキーワードを使います。「LINE 認証情報」カードの「スタンプを理解する」でオフにできます。
 - 通常の画像も同じです。LINE content API でダウンロードしてモデルに添付し、画像非対応なら同じ modlens／視覚モデルの説明経路を使います。「LINE 認証情報」カードの「画像を理解する」でオフにできます。
 - dsh-meme がインストールされていない場合、この機能は無効になりテキストのみ返します。
+## 音声返信（CosyVoice3）
+
+- ペルソナは返信の最後に `[[voice]]` を付けると、CosyVoice3-0.5B で音声合成し、LINE の音声メッセージ（m4a）として送信します。
+- Apple Silicon の macOS では MLX でローカル合成します。Windows や MLX がない環境では CosyVoice GGUF（CrispASR）を使います。初回はパネルの「環境を一括セットアップ」を押してください（モデルを約 1–2GB ダウンロードします）。
+- パネルの「音声返信」でオンオフ、音声使用権の確認、参照音声のアップロード（既定は指定音源の 12–16 秒）、instruct／zero-shot の選択、試聴ができます。
+- 合成には約 20–40 秒かかります。reply token の期限が切れた場合は push に切り替わります。音声は `<DSH_HOME>/line-bot/media/` に保存され、tunnel の `/media/<token>` で配信されます。
+- `ffmpeg` が必要です。MLX モードは Python 3.10+ が必要です。
+
 ## 診断
 - パネルの「詳細設定 → 診断を実行」でサーバー、Tunnel、公開 URL、webhook、dsh-meme 図庫、画像変換ツール、モデル、最近のエラーを確認できます。「安全な修復」は tunnel 再接続と webhook 再設定だけを行います。
 - CLI：`npx dsh-line-bot doctor`、`doctor --fix`、`doctor --json`。
@@ -258,4 +267,4 @@ Bot がグループ（または複数人のルーム）に追加されたとき
 
 - host ロジック：`lib/*.mjs`（`util`／`config`／`line-api`／`persona`／`agent-runner`／`webhook-server`／`cloudflare`／`tunnel`／`nudge`／`tieba-sync`／`host`）。
 - パネル：`client.js`（`window.__ModuleLoader__` で `settings.section` を登録）。
-- エントリーポイント：`index.js`（`/api/line-bot` のマウント、dev reload、アンロード時のクリーンアップ）。
+- エントリーポイント：`index.js`（`/api/line-bot` のマウント、dev reload、アンロード時のクリーンアップ）。

package/README.ko.md

@@ -99,6 +99,7 @@ npx dsh-line-bot install --no-companions
 | 말장난 | 텍스트 밈: 내장 시드, 貼吧 명언, wanjiqi 탄막 밈. 출처별 켜기/끄기, 턴당 주입 수, 추가/삭제 |
 | 개인 기억 | 사용자별 장기 기억, 만료 자동 삭제, 매일 자기 정리, 수동 삭제 |
 | 이모티콘 | dsh-meme 라이브러리로 이미지/스티커 답장, 켜기/끄기, 1회 최대 장수, 샘플 미리보기 |
+| 음성 답장 | CosyVoice3 음성 합성, 켜기/끄기, 참조 음성 업로드, instruct, 미리듣기 |
 | 스티커·이미지 이해 | LINE 스티커나 일반 이미지를 받으면 가져와 모델에 보여 줌. 이미지 미지원 모델은 modlens 또는 다른 비전 모델로 설명 (끌 수 있음) |
 | DeepSeek 잔액 | 현재 잔액, 매 턴 주입, 잔액이 적을 때 캐릭터가 먼저 알림, 기준 금액과 쿨다운(deepseek-account 전용) |
 | 능동 메시지 | 켜기/끄기, 사용자별 카운트다운, 최소/최대 간격, 연속 미응답 상한, 일일/월간 상한, 최소 간격, 조용한 시간대, idle, 대상 사용자, 프롬프트, 지금 시험 발송, 통계(다음 예정 시각과 일시 중지 인원) |
@@ -222,6 +223,14 @@ Bot이 그룹(또는 다인 룸)에 추가되면:
 - LINE 스티커를 받으면 스티커 이미지를 가져와 모델에 보여 줍니다. 이미지 지원 모델은 바로 읽고, 아니면 먼저 modlens, 다음으로 다른 비전 모델로 설명하고, 마지막에 LINE 키워드로 대체합니다. 「LINE 자격 증명」 카드에서 「스티커 이해」를 끌 수 있습니다.
 - 일반 이미지도 같습니다. LINE content API로 내려받아 모델에 첨부하고, 이미지 미지원이면 같은 modlens／비전 모델 설명 경로를 씁니다. 「LINE 자격 증명」 카드에서 「이미지 이해」를 끌 수 있습니다.
 - dsh-meme이 설치되어 있지 않으면 이 기능은 꺼지고 텍스트만 답장합니다.
+## 음성 답장(CosyVoice3)
+
+- 페르소나가 답장 끝에 `[[voice]]`를 붙이면 CosyVoice3-0.5B로 음성을 합성해 LINE 음성 메시지(m4a)로 보냅니다.
+- Apple Silicon macOS에서는 MLX로 로컬 합성합니다. Windows이거나 MLX가 없으면 CosyVoice GGUF(CrispASR)를 사용합니다. 처음에는 패널의 「환경 일괄 설정」을 한 번 누르세요(모델 약 1–2GB 다운로드).
+- 패널 「음성 답장」에서 켜기/끄기, 음성 사용 권리 확인, 참조 음성 업로드(기본값은 지정 음원의 12–16초), instruct/zero-shot 선택, 미리듣기를 할 수 있습니다.
+- 합성에는 약 20–40초가 걸립니다. reply token이 만료되면 push로 자동 전환됩니다. 음성은 `<DSH_HOME>/line-bot/media/`에 저장되고 tunnel의 `/media/<token>`으로 제공됩니다.
+- `ffmpeg`가 필요합니다. MLX 모드는 Python 3.10+가 필요합니다.
+
 ## 진단
 - 패널의 "고급 설정 → 진단 실행"에서 서버, Tunnel, 공개 URL, webhook, dsh-meme 라이브러리, 이미지 변환 도구, 모델, 최근 오류를 확인할 수 있습니다. "안전 복구"는 tunnel 재연결과 webhook 재설정만 수행합니다.
 - CLI: `npx dsh-line-bot doctor`, `doctor --fix`, `doctor --json`.
@@ -256,4 +265,4 @@ Bot이 그룹(또는 다인 룸)에 추가되면:
 
 - host 로직: `lib/*.mjs`(`util`／`config`／`line-api`／`persona`／`agent-runner`／`webhook-server`／`cloudflare`／`tunnel`／`nudge`／`tieba-sync`／`host`).
 - 패널: `client.js`(`window.__ModuleLoader__`로 `settings.section` 등록).
-- 진입점: `index.js`(`/api/line-bot` 마운트, dev reload, 언로드 정리).
+- 진입점: `index.js`(`/api/line-bot` 마운트, dev reload, 언로드 정리).

package/README.md

@@ -99,6 +99,7 @@ npx dsh-line-bot install --no-companions
 | 玩梗 | 文字梗庫：內建種子、貼吧金句、wanjiqi 彈幕梗；三個來源可個別開關、每輪注入幾則、新增／刪除梗 |
 | 個人記憶 | 每位使用者分開的長期記憶、到期自動刪、每日請角色整理、手動刪除 |
 | 表情包 | 使用 dsh-meme 圖庫回圖片／貼圖、開關、一次最多幾張、圖庫樣本 |
+| 語音回覆 | CosyVoice3 語音合成、開關、參考音上傳、語氣指令、試聽 |
 | 貼圖與圖片理解 | 收到 LINE 貼圖或一般圖片時抓圖給模型看；模型不吃圖時用 modlens 或另一個視覺模型描述（可關閉） |
 | DeepSeek 餘額 | 目前餘額、每輪注入、低於門檻時由角色主動提醒、提醒門檻與冷卻（僅 deepseek-account） |
 | 主動傳訊 | 開關、每位使用者的倒數、最短／最長間隔、連續未回覆上限、每日／每月上限、兩則間距、安靜時段、idle、指定對象、提示詞、立即試傳、統計（下次可能時間與暫停人數） |
@@ -224,6 +225,14 @@ Bot 被加進群組（或多人聊天室）後：
 - 收到 LINE 貼圖時，會抓貼圖圖片交給模型看；模型支援圖片就直接讀，否則先用 modlens 描述，再不支援就改用另一個視覺模型，最後才退回 LINE 提供的關鍵字。可在「LINE 憑證」卡關閉「看得懂貼圖」。
 - 一般圖片也一樣：透過 LINE content API 下載後直接附給模型；模型不吃圖時走同一套 modlens／視覺模型描述。可在「LINE 憑證」卡關閉「看得懂一般圖片」。
 - 沒安裝 dsh-meme 時這個功能會自動停用，只回文字。
+## 語音回覆（CosyVoice3）
+
+- 角色可以在回覆最後加 `[[voice]]`，插件會用 CosyVoice3-0.5B 把文字合成語音，並以 LINE 語音訊息送出（m4a）。
+- macOS（Apple Silicon）在本機用 MLX 合成；Windows／沒有 MLX 時用 CosyVoice GGUF（CrispASR）。第一次要先在面板按「一鍵配置環境」（會下載模型，約 1–2GB）。
+- 面板「語音回覆」可開關、確認聲音使用權、上傳參考音（預設用指定音檔的 12–16 秒片段）、選推理模式與語氣指令、試聽。
+- 合成需要約 20–40 秒；若 reply token 過期會自動改用 push。語音檔存在 `<DSH_HOME>/line-bot/media/`，透過 tunnel 的 `/media/<token>` 提供。
+- 需要 `ffmpeg`；MLX 模式需要 Python 3.10+。
+
 ## 診斷與修復
 - 面板「進階設定 → 執行診斷」會檢查伺服器、Tunnel、公開網址、webhook、表情包圖庫、轉圖工具、模型與最近錯誤；「自動修復（安全）」只會重連 tunnel、重設 webhook。
 - 終端機：`npx dsh-line-bot doctor`、`npx dsh-line-bot doctor --fix`、`doctor --json`。
@@ -258,4 +267,4 @@ Bot 被加進群組（或多人聊天室）後：
 
 - host 邏輯：`lib/*.mjs`（`util`／`config`／`line-api`／`persona`／`agent-runner`／`webhook-server`／`cloudflare`／`tunnel`／`nudge`／`tieba-sync`／`host`）。
 - 面板：`client.js`（`window.__ModuleLoader__` 註冊 `settings.section`）。
-- 進入點：`index.js`（掛 `/api/line-bot`、dev reload、卸載清理）。
+- 進入點：`index.js`（掛 `/api/line-bot`、dev reload、卸載清理）。

package/README.zh-CN.md

@@ -99,6 +99,7 @@ npx dsh-line-bot install --no-companions
 | 玩梗 | 文字梗库：内置种子、贴吧金句、wanjiqi 弹幕梗；三个来源可分别开关、每轮注入几条、新增／删除梗 |
 | 个人记忆 | 每位用户分开的长期记忆、到期自动删除、每日请角色整理、手动删除 |
 | 表情包 | 使用 dsh-meme 图库回图片/贴图、开关、每次最多几张、图库样本 |
+| 语音回复 | CosyVoice3 语音合成、开关、参考音频上传、语气指令、试听 |
 | 贴图与图片理解 | 收到 LINE 贴图或一般图片时抓图给模型看；模型不吃图时用 modlens 或另一个视觉模型描述（可关闭） |
 | DeepSeek 余额 | 当前余额、每轮注入、低于门槛时由角色主动提醒、提醒门槛与冷却（仅 deepseek-account） |
 | 主动传讯 | 开关、每位使用者的倒数、最短／最长间隔、连续未回复上限、每日／每月上限、两则间距、安静时段、idle、指定对象、提示词、立即试传、统计（下次可能时间与暂停人数） |
@@ -224,6 +225,14 @@ Bot 被加入群组（或多人聊天室）后：
 - 收到 LINE 贴图时，会抓贴图图片交给模型看；模型支持图片就直接读，否则先用 modlens 描述，再不支持就改用另一个视觉模型，最后才退回 LINE 提供的关键词。可在「LINE 凭证」卡关闭「看得懂贴图」。
 - 一般图片也一样：通过 LINE content API 下载后直接附给模型；模型不吃图时走同一套 modlens／视觉模型描述。可在「LINE 凭证」卡关闭「看得懂一般图片」。
 - 没安装 dsh-meme 时该功能会自动停用，只回文字。
+## 语音回复（CosyVoice3）
+
+- 角色可以在回复最后加 `[[voice]]`，插件会用 CosyVoice3-0.5B 把文字合成语音，并以 LINE 语音消息发送（m4a）。
+- macOS（Apple Silicon）在本机用 MLX 合成；Windows／没有 MLX 时用 CosyVoice GGUF（CrispASR）。第一次要先在面板按「一键配置环境」（会下载模型，约 1–2GB）。
+- 面板「语音回复」可开关、确认声音使用权、上传参考音频（默认用指定音频的 12–16 秒片段）、选择推理模式与语气指令、试听。
+- 合成需要约 20–40 秒；若 reply token 过期会自动改用 push。语音文件存在 `<DSH_HOME>/line-bot/media/`，通过 tunnel 的 `/media/<token>` 提供。
+- 需要 `ffmpeg`；MLX 模式需要 Python 3.10+。
+
 ## 诊断与修复
 - 面板「高级设置 → 执行诊断」会检查服务器、Tunnel、公开网址、webhook、表情包图库、转图工具、模型与最近错误；「自动修复（安全）」只会重连 tunnel、重设 webhook。
 - 终端：`npx dsh-line-bot doctor`、`npx dsh-line-bot doctor --fix`、`doctor --json`。
@@ -258,4 +267,4 @@ Bot 被加入群组（或多人聊天室）后：
 
 - host 逻辑：`lib/*.mjs`（`util`／`config`／`line-api`／`persona`／`agent-runner`／`webhook-server`／`cloudflare`／`tunnel`／`nudge`／`tieba-sync`／`host`）。
 - 面板：`client.js`（`window.__ModuleLoader__` 注册 `settings.section`）。
-- 进入点：`index.js`（挂 `/api/line-bot`、dev reload、卸载清理）。
+- 进入点：`index.js`（挂 `/api/line-bot`、dev reload、卸载清理）。

package/TROUBLESHOOTING.md

@@ -32,6 +32,12 @@ npx dsh-line-bot doctor --fix   # 安全修復：重連 tunnel、重設 webhook
 - 模型不支援時，插件會先用 modlens 描述，再改用另一個視覺模型，最後才退回貼圖關鍵字。
 - modlens 可在「進階 → 診斷」看 `vision` check；失敗通常是 provider 額度或 503。一般圖片可在面板「LINE 憑證」關閉「看得懂一般圖片」。
 
+### 語音沒送出或一直回文字
+- 面板「語音回覆」要開啟、確認聲音使用權，並按過「一鍵配置環境」（第一次會下載模型）。
+- macOS 需要 Apple Silicon + Python 3.10+；Windows 需要 `ffmpeg`。音檔上傳後可按「測試語音」試聽。
+- 合成約需 20–40 秒；reply token 過期時會自動改用 push。日誌看 `語音回覆`、`語音合成失敗`。
+- 模型只有在語言上下文有語音提示時才會加 `[[voice]]`；可先用「測試 Agent 回覆」確認。
+
 ### APNG 不會動
 - LINE 不播放 APNG，只顯示第一幀。保持 `stickers.apng=false` 即可。
 

package/client.js

@@ -23,6 +23,7 @@ window.__ModuleLoader__.load({
       { key: 'balance', label: 'DeepSeek 餘額' },
       { key: 'nudge', label: '主動傳訊' },
       { key: 'meme', label: '表情包' },
+      { key: 'voice', label: '語音回覆' },
       { key: 'users', label: '使用者' },
       { key: 'group', label: '群組' },
       { key: 'advanced', label: '進階／日誌' },
@@ -366,6 +367,8 @@ window.__ModuleLoader__.load({
       const [modelCatalog, setModelCatalog] = useState(null)
       const [importGroup, setImportGroup] = useState('')
       const [doctorResult, setDoctorResult] = useState(null)
+      const [voicePreview, setVoicePreview] = useState(null)
+      const voiceInputRef = useRef(null)
       const importInput = useRef(null)
       const [localEdit, setLocalEdit] = useState({ id: '', name: '', text: '' })
 
@@ -697,6 +700,91 @@ window.__ModuleLoader__.load({
         await act('tieba-bars-add', {})
       }
 
+      async function installVoice() {
+        setBusy('voice-install')
+        setToast(null)
+        try {
+          await jpost('/action', { action: 'voice-install' })
+          setToast({ kind: 'ok', text: '已開始配置語音環境；完成前可以留在這一頁看狀態。' })
+        } catch (err) {
+          setToast({ kind: 'error', text: '配置失敗：' + (err.message || err) })
+        } finally {
+          setBusy('')
+        }
+      }
+
+      async function detectVoice() {
+        setBusy('voice-detect')
+        setToast(null)
+        try {
+          const value = await jpost('/action', { action: 'voice-detect' })
+          const result = value?.result || {}
+          setToast({ kind: 'ok', text: '偵測完成：' + (result.ready ? '環境就緒' : '尚未就緒（可按一鍵配置）') })
+          await refresh()
+        } catch (err) {
+          setToast({ kind: 'error', text: '偵測失敗：' + (err.message || err) })
+        } finally {
+          setBusy('')
+        }
+      }
+
+      async function testVoice() {
+        if (dirty) await persist(false).catch(() => {})
+        setBusy('voice-preview')
+        setToast(null)
+        try {
+          const value = await jpost('/action', { action: 'voice-preview', payload: { text: '主人，這是語音測試，聽得到嗎？' } })
+          const result = value?.result || null
+          setVoicePreview(result)
+          setToast({ kind: 'ok', text: result?.url ? '合成完成，可以試聽。' : '合成完成，但沒有公開網址；請確認 tunnel。' })
+        } catch (err) {
+          setToast({ kind: 'error', text: '語音測試失敗：' + (err.message || err) })
+        } finally {
+          setBusy('')
+        }
+      }
+
+      async function uploadVoice(event) {
+        const file = event?.target?.files?.[0]
+        if (event?.target) event.target.value = ''
+        if (!file) return
+        if (file.size > 20 * 1024 * 1024) {
+          setToast({ kind: 'error', text: '音檔超過 20MB。' })
+          return
+        }
+        setBusy('voice-save-reference')
+        setToast(null)
+        try {
+          const dataUrl = await new Promise((resolve, reject) => {
+            const reader = new FileReader()
+            reader.onload = () => resolve(String(reader.result || ''))
+            reader.onerror = () => reject(new Error('讀取檔案失敗'))
+            reader.readAsDataURL(file)
+          })
+          await jpost('/action', { action: 'voice-save-reference', payload: { dataUrl, filename: file.name } })
+          await refresh()
+          setToast({ kind: 'ok', text: '參考音已更新。' })
+        } catch (err) {
+          setToast({ kind: 'error', text: '上傳失敗：' + (err.message || err) })
+        } finally {
+          setBusy('')
+        }
+      }
+
+      async function resetVoiceReference() {
+        setBusy('voice-reset-reference')
+        setToast(null)
+        try {
+          await jpost('/action', { action: 'voice-reset-reference' })
+          await refresh()
+          setToast({ kind: 'ok', text: '已改用內建預設參考音。' })
+        } catch (err) {
+          setToast({ kind: 'error', text: '重設失敗：' + (err.message || err) })
+        } finally {
+          setBusy('')
+        }
+      }
+
       async function refresh() {
         setToast(null)
         try {
@@ -757,6 +845,9 @@ window.__ModuleLoader__.load({
       const memoryStatus = status.memory || {}
       const agentStatus = status.agent || {}
       const modelProviders = Array.isArray(modelCatalog?.providers) ? modelCatalog.providers : []
+      const voiceCfg = cfg.voice || {}
+      const voiceStatus = status.voice || {}
+      const voiceSetup = voiceStatus.setup || {}
       const memoryUsers = memoryData?.users || []
       const syncStats = status.sync || {}
       const runtime = status
@@ -1317,10 +1408,48 @@ window.__ModuleLoader__.load({
               ),
         ),
 
+        // 5.5 語音回覆
+        h(
+          Card,
+          { id: sectionDomId('voice'), order: 12, title: '語音回覆（CosyVoice3）', desc: '用 CosyVoice3-0.5B 把回覆合成語音；角色可以自己決定要不要用語音，也可以只用文字。第一次使用要先按「一鍵配置環境」。' },
+          h('div', { style: S.row },
+            h(Badge, { ok: voiceStatus.ready === true }, voiceStatus.ready ? '語音環境就緒' : '尚未就緒'),
+            h(Badge, { ok: voiceCfg.consent === true }, voiceCfg.consent ? '已確認使用權' : '未確認使用權'),
+            h(Badge, { ok: true }, voiceStatus.mlx?.ok ? 'macOS MLX' : voiceStatus.gguf?.ok ? 'GGUF' : '未安裝引擎'),
+            h(Badge, { ok: !!voiceStatus.reference?.path }, voiceStatus.reference?.path ? ('參考音 ' + (voiceStatus.reference.seconds || 0) + ' 秒') : '沒有參考音'),
+          ),
+          h('div', { style: S.hint }, 'macOS 會用 MLX（較快）；Windows 或沒有 MLX 時用 CosyVoice GGUF。合成一次約需 20–40 秒，送出時若 reply token 過期會自動改用 push。'),
+          h(Toggle, { checked: voiceCfg.enabled === true, onChange: (value) => update({ voice: { enabled: value } }), label: '開啟語音回覆', hint: '開啟後角色可以自己決定用語音；關閉時完全不合成。' }),
+          h(Toggle, { checked: voiceCfg.consent === true, onChange: (value) => update({ voice: { consent: value } }), label: '我確認有使用此聲音的權利', hint: '使用他人聲音做克隆前請先取得同意；確認後才會合成。' }),
+          h('div', { style: S.row },
+            h(Btn, { onClick: installVoice, disabled: !!busy }, busy === 'voice-install' ? '安裝中…' : '一鍵配置環境'),
+            h(Btn, { onClick: detectVoice, disabled: !!busy }, busy === 'voice-detect' ? '偵測中…' : '重新偵測'),
+            h(Btn, { onClick: testVoice, disabled: !!busy }, busy === 'voice-preview' ? '合成中…' : '測試語音'),
+            h(Btn, { onClick: () => voiceInputRef.current && voiceInputRef.current.click(), disabled: !!busy }, '上傳參考音'),
+            h('input', { ref: voiceInputRef, type: 'file', accept: 'audio/*', style: { display: 'none' }, onChange: uploadVoice }),
+          ),
+          h('div', { style: S.hint }, '目前參考音：' + (voiceStatus.reference?.path || '（尚未設定，預設會用插件內建的 12–16 秒片段）')),
+          voiceStatus.reference?.path ? h('div', { style: S.row }, h(Btn, { onClick: resetVoiceReference, disabled: !!busy }, '改用內建預設參考音')) : null,
+          h('div', { style: S.grid },
+            h(Field, { label: '引擎', hint: 'auto 會依系統自動挑選' }, h('select', { value: voiceCfg.provider || 'auto', onChange: (event) => update({ voice: { provider: event.target.value } }), style: S.input }, ['auto', 'mlx', 'gguf'].map((item) => h('option', { key: item, value: item }, item)))),
+            h(Field, { label: '推理模式' }, h('select', { value: voiceCfg.cloneMode || 'instruct', onChange: (event) => update({ voice: { cloneMode: event.target.value } }), style: S.input }, [['instruct', '自然語言語氣控制'], ['zero-shot', '零樣本（需參考音文字）']].map(([value, label]) => h('option', { key: value, value }, label)))),
+            h(Field, { label: '一次最多幾個字', hint: '太長會截斷；語音訊息上限約 60 秒' }, h(Num, { value: voiceCfg.maxChars, min: 20, max: 300, step: 10, onChange: (value) => update({ voice: { maxChars: value } }) })),
+          ),
+          h(Field, { label: '語氣指令（instruct）', hint: '用自然語言描述想要的語氣' }, h(Area, { value: voiceCfg.instructText, rows: 2, onChange: (value) => update({ voice: { instructText: value } }) })),
+          voiceCfg.cloneMode === 'zero-shot' ? h(Field, { label: '參考音文字（zero-shot 用）' }, h(Area, { value: voiceCfg.refText, rows: 2, onChange: (value) => update({ voice: { refText: value } }) })) : null,
+          voiceSetup.phase && voiceSetup.phase !== 'idle'
+            ? h('div', { style: voiceSetup.phase === 'error' ? S.warnBox : S.note }, '環境狀態：' + (voiceSetup.message || voiceSetup.phase) + (voiceSetup.error ? '（' + voiceSetup.error + '）' : ''))
+            : null,
+          voiceStatus.lastError ? h('div', { style: S.warnBox }, '最近錯誤：' + voiceStatus.lastError) : null,
+          voicePreview
+            ? h('div', { style: S.panelBox }, h('div', { style: S.fieldTitle }, '試聽（' + (voicePreview.provider || '') + '，' + Math.round((voicePreview.durationMs || 0) / 1000) + ' 秒）'), h('audio', { controls: true, src: voicePreview.url || voicePreview.localUrl || '', style: { width: '100%' } }))
+            : null,
+        ),
+
         // 6. 使用者
         h(
           Card,
-          { id: sectionDomId('users'), order: 12, title: '使用者', desc: '與 bot 互動過的 LINE 使用者。每個人有自己的 DSH session 與工作資料夾（記憶、檔案不互通），人設也可以個別指定。' },
+          { id: sectionDomId('users'), order: 13, title: '使用者', desc: '與 bot 互動過的 LINE 使用者。每個人有自己的 DSH session 與工作資料夾（記憶、檔案不互通），人設也可以個別指定。' },
           (access.pending || []).length > 0
             ? h('div', { style: S.panelBox },
                 h('div', { style: S.fieldTitle }, `待審核（${access.pending.length}）`),
@@ -1370,7 +1499,7 @@ window.__ModuleLoader__.load({
         // 6.5 群組
         h(
           Card,
-          { id: sectionDomId('group'), order: 13, title: '群組', desc: '被加進群組時，只有被 @、被引用，或依機率擲骰才回覆；每個群組有自己的 session、工作資料夾、人設與記憶；比較晚加入時可以匯入 LINE 匯出的聊天記錄補記憶。' },
+          { id: sectionDomId('group'), order: 14, title: '群組', desc: '被加進群組時，只有被 @、被引用，或依機率擲骰才回覆；每個群組有自己的 session、工作資料夾、人設與記憶；比較晚加入時可以匯入 LINE 匯出的聊天記錄補記憶。' },
           h('input', { ref: importInput, type: 'file', accept: '.txt,text/plain', style: { display: 'none' }, onChange: importChatFile }),
           h('div', { style: S.grid },
             h(Field, { label: '沒被點名時的回覆機率（%）', hint: '每則群組訊息用這個機率決定要不要回；0 就只在被 @ 或引用時回' },

package/lib/config.mjs

@@ -35,6 +35,19 @@ export const DEFAULT_CONFIG = {
     errorReply: '（剛剛卡住了，再說一次好嗎？）',
     emptyReply: '（她沒有說話）',
   },
+  voice: {
+    enabled: false,
+    consent: false,
+    provider: 'auto', // auto | mlx | gguf
+    cloneMode: 'instruct', // instruct | zero-shot
+    instructText: '用可愛、輕快、帶點撒嬌的語氣說，語速稍慢。',
+    refText: '',
+    maxChars: 80,
+    model: '',
+    referencePath: '',
+    referenceSource: '',
+    skipDisclaimer: true,
+  },
   server: {
     host: '127.0.0.1',
     port: 8791,
@@ -245,6 +258,19 @@ export function sanitizePatch(current, patch) {
   next.agent.workspaceRoot = String(next.agent.workspaceRoot || '').trim()
   next.agent.tiebaContext = Boolean(next.agent.tiebaContext)
 
+  const voice = next.voice || (next.voice = {})
+  voice.enabled = Boolean(voice.enabled)
+  voice.consent = Boolean(voice.consent)
+  voice.provider = ['auto', 'mlx', 'gguf'].includes(String(voice.provider)) ? String(voice.provider) : 'auto'
+  voice.cloneMode = String(voice.cloneMode) === 'zero-shot' ? 'zero-shot' : 'instruct'
+  voice.instructText = String(voice.instructText || '').slice(0, 500)
+  voice.refText = String(voice.refText || '').slice(0, 500)
+  voice.maxChars = clampInt(voice.maxChars, 20, 300, 80)
+  voice.model = String(voice.model || '').slice(0, 200)
+  voice.referencePath = String(voice.referencePath || '').trim()
+  voice.referenceSource = String(voice.referenceSource || '').trim()
+  voice.skipDisclaimer = Boolean(voice.skipDisclaimer)
+
   const sync = next.sync
   sync.enabled = Boolean(sync.enabled)
   sync.targetPersonaId = String(sync.targetPersonaId || '').trim() || 'dafeiyu'

package/lib/host.mjs

@@ -29,6 +29,7 @@ const stickersMod = await import(withVersion('./stickers.mjs'))
 const memeSourceMod = await import(withVersion('./meme-source.mjs'))
 const stickerImageMod = await import(withVersion('./sticker-image.mjs'))
 const visionMod = await import(withVersion('./vision.mjs'))
+const ttsMod = await import(withVersion('./tts.mjs'))
 const utilMod = await import(withVersion('./util.mjs'))
 const { createConfigStore, publicConfig, dataDir, dshHome } = configMod
 const { createPersonaClient } = personaMod
@@ -47,9 +48,10 @@ const { createStickerStore } = stickersMod
 const { createMemeSource } = memeSourceMod
 const { createStickerImages } = stickerImageMod
 const { createVision } = visionMod
+const { createTts } = ttsMod
 const { chunkText, clip, inQuietWindow, jsonFail, jsonOk, maskSecret, readJsonBody, safeArray, sleep, readJsonSafe } = utilMod
 
-export const VERSION = '0.9.7'
+export const VERSION = '0.10.0'
 
 // 環境變數提供的 Cloudflare API Token（方便用 shell 注入、不用把 token 寫進設定檔）。
 // 設定檔裡的 token 優先；兩者都沒有時才用環境變數。
@@ -401,7 +403,77 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
     const jokeText = jokes.contextText(() => store.get())
     // 群組不注入貼吧作息，避免在群組裡突然講起刷貼吧的事。
     const tieba = kind === 'user' ? tiebaContextText() : ''
-    return [modelContextText(), jokeText, tieba, balanceContextText(), extra, memoryContextText(ownerKey), memeContextText() || stickerContextText()].filter(Boolean).join('\n\n')
+    return [modelContextText(), voiceContextText(), jokeText, tieba, balanceContextText(), extra, memoryContextText(ownerKey), memeContextText() || stickerContextText()].filter(Boolean).join('\n\n')
+  }
+
+  const VOICE_MARKER = /\[\[\s*(?:voice|語音|语音|audio)\s*(?:[:：]\s*([^\]\n]{0,200}))?\s*\]\]/gi
+  let voiceCache = { at: 0, value: null }
+
+  function voiceStatusCached() {
+    if (!voiceCache.value || Date.now() - voiceCache.at > 10000) {
+      try {
+        voiceCache = { at: Date.now(), value: tts.status() }
+      } catch (error) {
+        voiceCache = { at: Date.now(), value: { ready: false, lastError: errorText(error) } }
+      }
+    }
+    return voiceCache.value
+  }
+
+  function voiceReady(cfg = store.get()) {
+    if (cfg.voice?.enabled !== true || cfg.voice?.consent !== true) return false
+    const st = voiceStatusCached()
+    return st?.ready === true && Boolean(st?.reference?.path)
+  }
+
+  function voiceContextText() {
+    const cfg = store.get()
+    if (cfg.voice?.enabled !== true || cfg.voice?.consent !== true) return ''
+    if (!voiceReady(cfg)) return ''
+    const max = Math.max(20, Math.min(300, Number(cfg.voice?.maxChars) || 80))
+    return [
+      '【語音】你可以用語音回覆。',
+      `想用時把 [[voice]] 放在回覆最後；如果要指定語氣，寫成 [[voice:用溫柔、帶點撒嬌的語氣，語速慢一點]]。`,
+      `語氣、情緒、語速、停頓這些「怎麼說」的指示只能放在標記裡；正文只放要念出來的字，不要把語氣描述、括號動作或舞台指示寫進正文（最多約 ${max} 字）。`,
+      '一次最多一則語音；不適合用語音（例如內容太長、需要圖片）就不要加標記。',
+    ].join('\n')
+  }
+
+  function splitVoiceMarker(text) {
+    let requested = false
+    let instruct = ''
+    const cleaned = String(text || '')
+      .replace(VOICE_MARKER, (_match, tone) => {
+        requested = true
+        if (tone && String(tone).trim()) instruct = String(tone).trim().slice(0, 200)
+        return ''
+      })
+      .trim()
+    return { text: cleaned, requested, instruct }
+  }
+
+  async function synthesizeVoiceMessage(text, instruct = '') {
+    const base = publicBaseSync()
+    if (!base) throw new Error('目前沒有公開網址，語音訊息送不出去')
+    const result = await tts.synthesize(text, { instructText: instruct })
+    const token = registerFile(result.m4a, 'audio/mp4')
+    if (!token) throw new Error('無法把語音檔存進媒體庫')
+    return {
+      message: { type: 'audio', originalContentUrl: `${base}/media/${token}`, duration: Math.max(1000, Math.round(result.durationMs || 0)) },
+      token,
+      provider: result.provider,
+      durationMs: result.durationMs,
+    }
+  }
+
+  async function replyMessages(userId, replyToken, messages) {
+    if (!Array.isArray(messages) || messages.length === 0) return
+    try {
+      await withToken((token) => lineApi.replyMessage(token, replyToken, messages))
+    } catch (error) {
+      logger.warn(`reply 失敗，改用 push：${errorText(error)}`)
+      await withToken((token) => lineApi.pushMessage(token, userId, messages))
+    }
   }
 
   async function refreshBalance() {
@@ -1426,6 +1498,25 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
     return token
   }
 
+  function registerFile(filePath, mime, ext = '') {
+    if (!filePath || !fs.existsSync(filePath)) return ''
+    const token = `m${randomBytes(6).toString('hex')}`
+    const suffix = ext || path.extname(String(filePath || '')).toLowerCase() || '.bin'
+    const filename = `${token}${suffix}`
+    const target = path.join(mediaDir, filename)
+    try {
+      fs.copyFileSync(filePath, target)
+    } catch (error) {
+      logger.warn(`複製媒體失敗：${error?.message || error}`)
+      return ''
+    }
+    const item = { file: filename, mime: mime || 'application/octet-stream', at: Date.now(), bytes: fs.statSync(target).size }
+    mediaTokens.set(token, item)
+    mediaIndex[token] = item
+    saveMediaIndex()
+    return token
+  }
+
   function getMedia(id) {
     const key = String(id || '')
     if (!key) return null
@@ -1804,10 +1895,28 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
         cwd: ensureUserWorkspace(conversationKey) || cfg.agent.cwd || undefined,
       })
       let replyText = String(result?.text || '').trim()
+      const voiceDirective = splitVoiceMarker(replyText)
+      replyText = voiceDirective.text
       const parsedReply = splitStickerMarkers(replyText)
-      if (!parsedReply.text && parsedReply.names.length === 0) replyText = cfg.line.emptyReply || '（她沒有說話）'
-      await replyOrPush(chatId, event.replyToken, replyText)
-      runtime.lastReply = { chatId, kind: sourceKind, at: Date.now(), text: clip(parsedReply.text || (parsedReply.names.length ? `[表情包] ${parsedReply.names.join('、')}` : replyText), 300) }
+      let voiceSent = null
+      if (voiceDirective.requested && voiceReady(cfg)) {
+        const spoken = parsedReply.text || ''
+        if (spoken) {
+          try {
+            voiceSent = await synthesizeVoiceMessage(spoken, voiceDirective.instruct)
+            logger.info(`語音回覆：${spoken.length} 字，${Math.round((voiceSent.durationMs || 0) / 1000)} 秒（${voiceSent.provider}；語氣：${voiceDirective.instruct || '預設'}）`)
+          } catch (error) {
+            logger.warn(`語音合成失敗，改用文字：${errorText(error)}`)
+          }
+        }
+      }
+      if (voiceSent) {
+        await replyMessages(chatId, event.replyToken, [voiceSent.message])
+      } else {
+        if (!parsedReply.text && parsedReply.names.length === 0) replyText = cfg.line.emptyReply || '（她沒有說話）'
+        await replyOrPush(chatId, event.replyToken, replyText)
+      }
+      runtime.lastReply = { chatId, kind: sourceKind, at: Date.now(), text: clip(voiceSent ? `[語音] ${parsedReply.text || replyText}` : parsedReply.text || (parsedReply.names.length ? `[表情包] ${parsedReply.names.join('、')}` : replyText), 300) }
       store.updateState((state) => {
         const map = state[bucketName] || {}
         const target = map[conversationKey]
@@ -1834,6 +1943,7 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
   const memes = createMemeSource({ ctx, logger })
   const stickerImages = createStickerImages({ ctx, logger, dir })
   const vision = createVision({ logger, cacheDir: path.join(dir, 'cache') })
+  const tts = createTts({ dir, logger, getConfig: () => store.get() })
   const mediaTokens = new Map()
   let imageSupportCache = { at: 0, key: '', value: false }
 
@@ -1949,7 +2059,9 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
   })
 
   async function sendPush(userId, text) {
-    const { messages } = await buildOutgoingMessages(text)
+    const voiceDirective = splitVoiceMarker(text)
+    if (voiceDirective.requested) logger.info('主動訊息中的語音標記已忽略，改用文字')
+    const { messages } = await buildOutgoingMessages(voiceDirective.text)
     if (messages.length === 0) return { sent: false, reason: 'empty' }
     const imageCount = messages.filter((item) => typeof item !== 'string' && item.type === 'image').length
     if (imageCount > 0) logger.info(`主動訊息含 ${imageCount} 張圖片`)
@@ -2388,6 +2500,18 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
         imageVision: cfg.line?.imageVision !== false,
         stickerVision: cfg.line?.stickerVision !== false,
       },
+      voice: {
+        ...voiceStatusCached(),
+        enabled: cfg.voice?.enabled === true,
+        consent: cfg.voice?.consent === true,
+        provider: cfg.voice?.provider || 'auto',
+        cloneMode: cfg.voice?.cloneMode || 'instruct',
+        instructText: cfg.voice?.instructText || '',
+        maxChars: Number(cfg.voice?.maxChars) || 80,
+        referencePath: cfg.voice?.referencePath || '',
+        ready: voiceReady(cfg),
+        publicBase: publicBaseSync(),
+      },
       memory: {
         ...memory.stats(),
         enabled: cfg.memory?.enabled !== false,
@@ -2676,6 +2800,53 @@ export async function create({ ctx, config: pluginConfig, logger: upstream }) {
         const built = await buildOutgoingMessages(String(payload.text))
         return { messages: built.messages, parsed: built.parsed }
       }
+      case 'voice-detect':
+        return tts.detect()
+      case 'voice-install': {
+        if (tts.status().installing) return { started: false, already: true }
+        tts.install()
+          .then((result) => {
+            if (result?.provider) store.patch({ voice: { provider: result.provider } }, { silent: true })
+            logger.info(`語音環境安裝完成（${result?.provider || 'unknown'}）`)
+            voiceCache = { at: 0, value: null }
+          })
+          .catch((error) => logger.error(`語音環境安裝失敗：${errorText(error)}`))
+        return { started: true }
+      }
+      case 'voice-preview':
+      case 'voice-test': {
+        const text = String(payload.text || '主人，這是語音測試，聽得到嗎？').trim()
+        if (!text) throw new Error('缺少文字')
+        const result = await tts.synthesize(text)
+        const token = registerFile(result.m4a, 'audio/mp4')
+        const base = publicBaseSync()
+        voiceCache = { at: 0, value: null }
+        return {
+          provider: result.provider,
+          durationMs: result.durationMs,
+          bytes: result.bytes,
+          chars: result.chars,
+          processingMs: result.processingMs,
+          url: base ? `${base}/media/${token}` : '',
+          localUrl: `/api/line-bot/media/${token}`,
+          token,
+        }
+      }
+      case 'voice-save-reference': {
+        const dataUrl = String(payload.dataUrl || '')
+        const match = /^data:([^;]+);base64,([\s\S]+)$/.exec(dataUrl)
+        if (!match) throw new Error('缺少音檔資料')
+        const buffer = Buffer.from(match[2], 'base64')
+        if (buffer.length > 20 * 1024 * 1024) throw new Error('音檔超過 20MB')
+        const saved = await tts.saveReferenceBuffer(buffer, String(payload.filename || 'reference'), String(payload.ext || '.wav'))
+        store.patch({ voice: { referencePath: saved.path } }, { silent: true })
+        voiceCache = { at: 0, value: null }
+        return { path: saved.path, seconds: saved.seconds }
+      }
+      case 'voice-reset-reference':
+        store.patch({ voice: { referencePath: '' } }, { silent: true })
+        voiceCache = { at: 0, value: null }
+        return { path: tts.referencePath() }
       case 'meme-send': {
         const userId = String(payload.userId || '').trim()
         if (!userId) throw new Error('缺少 userId')

package/lib/tts.mjs

@@ -0,0 +1,540 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFile, execFileSync } from 'node:child_process'
+import { promisify } from 'node:util'
+import { randomUUID } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+
+const execFileAsync = promisify(execFile)
+
+export const MLX_MODEL = 'mlx-community/Fun-CosyVoice3-0.5B-2512-8bit'
+export const GGUF_BACKEND = 'cosyvoice3-tts'
+export const CRISPASR_VERSION = 'v0.8.49'
+export const DEFAULT_INSTRUCT = '用可愛、輕快、帶點撒嬌的語氣說，語速稍慢。'
+
+const CRISPASR_MAC_URL = `https://github.com/CrispStrobe/CrispASR/releases/download/${CRISPASR_VERSION}/crispasr-macos-arm64.tar.gz`
+const CRISPASR_WIN_URL = `https://github.com/CrispStrobe/CrispASR/releases/download/${CRISPASR_VERSION}/crispasr-windows-x86_64-cpu.zip`
+
+function isWin() {
+  return process.platform === 'win32'
+}
+
+function which(command) {
+  try {
+    const out = execFileSync(isWin() ? 'where' : 'which', [command], { encoding: 'utf8', timeout: 4000 })
+    return String(out).split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0] || ''
+  } catch {
+    return ''
+  }
+}
+
+function fileExists(file) {
+  try {
+    return fs.existsSync(file)
+  } catch {
+    return false
+  }
+}
+
+function dirExists(dir) {
+  try {
+    return fs.statSync(dir).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function pythonVersion(python) {
+  try {
+    const out = execFileSync(python, ['-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], {
+      encoding: 'utf8',
+      timeout: 6000,
+      env: process.env,
+    }).trim()
+    const [major, minor] = out.split('.').map((value) => Number(value))
+    return { text: out, major, minor }
+  } catch {
+    return { text: '', major: 0, minor: 0 }
+  }
+}
+
+function parseDurationSeconds(text) {
+  const match = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(String(text || ''))
+  if (!match) return 0
+  return Number(match[1]) * 3600 + Number(match[2]) * 60 + Number(match[3])
+}
+
+export function createTts({ dir, logger, getConfig }) {
+  const root = path.join(dir, 'tts')
+  const paths = {
+    root,
+    refDir: path.join(root, 'ref'),
+    outDir: path.join(root, 'out'),
+    jobsDir: path.join(root, 'jobs'),
+    hfHome: path.join(root, 'hf'),
+    mlxVenv: path.join(root, 'mlx312-venv'),
+    mlxPython: path.join(root, 'mlx312-venv', 'bin', 'python'),
+    mlxScript: path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'tools', 'mlx_synth.py'),
+    macCrisp: path.join(root, 'crispasr', 'crispasr-macos-arm64', 'crispasr'),
+    winCrisp: path.join(root, 'crispasr', 'windows', 'crispasr.exe'),
+    winDir: path.join(root, 'crispasr', 'windows'),
+    defaultRef: path.join(root, 'ref', 'default.wav'),
+  }
+  for (const item of [paths.root, paths.refDir, paths.outDir, paths.jobsDir, paths.hfHome]) {
+    try {
+      fs.mkdirSync(item, { recursive: true })
+    } catch {
+      /* 權限不足時留給 status 回報 */
+    }
+  }
+
+  const state = {
+    setup: { phase: 'idle', message: '', error: '', at: 0, startedAt: 0 },
+    last: null,
+    lastError: '',
+    installing: false,
+  }
+
+  function setSetup(phase, message, error = '') {
+    state.setup = {
+      phase,
+      message,
+      error: error ? String(error).slice(0, 800) : '',
+      at: Date.now(),
+      startedAt: state.setup.startedAt || Date.now(),
+    }
+    if (logger) {
+      if (error) logger.warn(`語音環境：${message}（${String(error).slice(0, 200)}）`)
+      else logger.info(`語音環境：${message}`)
+    }
+  }
+
+  function cfgVoice() {
+    const cfg = getConfig ? getConfig() : {}
+    return cfg.voice || {}
+  }
+
+  function referencePath() {
+    const cfg = cfgVoice()
+    const configured = String(cfg.referencePath || '').trim()
+    if (configured && fileExists(configured)) return configured
+    if (fileExists(paths.defaultRef)) return paths.defaultRef
+    return ''
+  }
+
+  function referenceInfo() {
+    const file = referencePath()
+    if (!file) return { path: '', exists: false, seconds: 0 }
+    let seconds = 0
+    try {
+      const out = execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', file], {
+        encoding: 'utf8',
+        timeout: 8000,
+      })
+      seconds = Number(out.trim()) || 0
+    } catch {
+      seconds = 0
+    }
+    return { path: file, exists: true, seconds: Math.round(seconds * 100) / 100 }
+  }
+
+  function mlxModelCached() {
+    const hub = path.join(paths.hfHome, 'hub')
+    try {
+      const dirs = fs.readdirSync(hub).filter((name) => name.startsWith('models--mlx-community--Fun-CosyVoice3'))
+      for (const name of dirs) {
+        const snapshots = path.join(hub, name, 'snapshots')
+        if (!dirExists(snapshots)) continue
+        for (const snap of fs.readdirSync(snapshots)) {
+          if (fileExists(path.join(snapshots, snap, 'model.safetensors'))) return true
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+    return false
+  }
+
+  let mlxError = ''
+  function mlxReady() {
+    if (!fileExists(paths.mlxPython)) {
+      mlxError = '找不到 MLX Python 環境'
+      return false
+    }
+    if (!fileExists(paths.mlxScript)) {
+      mlxError = `找不到 MLX 合成腳本：${paths.mlxScript}`
+      return false
+    }
+    try {
+      execFileSync(paths.mlxPython, ['-c', 'import mlx_audio, mlx_lm, librosa'], { stdio: 'ignore', timeout: 30000 })
+      mlxError = ''
+      return true
+    } catch (error) {
+      mlxError = String(error?.stderr || error?.message || error).slice(0, 300)
+      return false
+    }
+  }
+
+  function ggufBinary() {
+    const candidates = [isWin() ? paths.winCrisp : paths.macCrisp, which('crispasr')]
+    return candidates.find((item) => item && fileExists(item)) || ''
+  }
+
+  function ggufReady() {
+    const bin = ggufBinary()
+    if (!bin) return false
+    try {
+      execFileSync(bin, ['--version'], { stdio: 'ignore', timeout: 8000 })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  function detect() {
+    const platform = process.platform
+    const arch = process.arch
+    const preferred = platform === 'darwin' && arch === 'arm64' ? 'mlx' : 'gguf'
+    const ffmpeg = which('ffmpeg')
+    const ref = referenceInfo()
+    return {
+      platform,
+      arch,
+      preferred,
+      ffmpeg: { path: ffmpeg, ok: !!ffmpeg },
+      mlx: {
+        ok: mlxReady(),
+        python: fileExists(paths.mlxPython) ? paths.mlxPython : '',
+        model: MLX_MODEL,
+        modelCached: mlxModelCached(),
+        error: mlxError,
+        script: paths.mlxScript,
+      },
+      gguf: {
+        ok: ggufReady(),
+        binary: ggufBinary(),
+        backend: GGUF_BACKEND,
+      },
+      reference: ref,
+      setup: state.setup,
+      ready: (preferred === 'mlx' ? mlxReady() : ggufReady()) && !!ref.path,
+    }
+  }
+
+  function resolveProvider(cfg = cfgVoice()) {
+    const detected = detect()
+    const wanted = String(cfg.provider || 'auto')
+    if (wanted === 'mlx') {
+      if (!detected.mlx.ok) throw new Error('MLX 語音環境還沒安裝完成，請先按「一鍵配置環境」')
+      return 'mlx'
+    }
+    if (wanted === 'gguf') {
+      if (!detected.gguf.ok) throw new Error('CosyVoice GGUF 引擎還沒安裝完成，請先按「一鍵配置環境」')
+      return 'gguf'
+    }
+    if (detected.mlx.ok && (detected.platform === 'darwin' || detected.preferred === 'mlx')) return 'mlx'
+    if (detected.gguf.ok) return 'gguf'
+    if (detected.mlx.ok) return 'mlx'
+    throw new Error('還沒有可用的語音引擎，請先按「一鍵配置環境」')
+  }
+
+  async function run(command, args, { env = process.env, timeout = 180000, maxBuffer = 20 * 1024 * 1024 } = {}) {
+    return execFileAsync(command, args, { env, timeout, maxBuffer })
+  }
+
+  function findPython() {
+    const candidates = [
+      process.env.LINEBOT_MLX_PYTHON,
+      '/opt/homebrew/opt/python@3.12/bin/python3.12',
+      '/opt/homebrew/bin/python3.12',
+      '/usr/local/bin/python3.12',
+      '/opt/homebrew/bin/python3.11',
+      '/usr/local/bin/python3.11',
+    ].filter(Boolean)
+    for (const candidate of candidates) {
+      if (!fileExists(candidate)) continue
+      const version = pythonVersion(candidate)
+      if (version.major > 3 || (version.major === 3 && version.minor >= 10)) return candidate
+    }
+    const system = which('python3')
+    if (system && !system.includes('DeepSeek Harness.app')) {
+      const version = pythonVersion(system)
+      if (version.major > 3 || (version.major === 3 && version.minor >= 10)) return system
+    }
+    return ''
+  }
+
+  function uvCommand() {
+    const candidates = [path.join(os.homedir(), '.local', 'bin', 'uv'), '/opt/homebrew/bin/uv', which('uv')].filter(Boolean)
+    return candidates.find((item) => fileExists(item)) || ''
+  }
+
+  async function installMlx() {
+    setSetup('python', '檢查 Python（MLX 需要 3.10 以上）')
+    let python = findPython()
+    if (!python) {
+      const brew = which('brew')
+      if (!brew) throw new Error('找不到 Python 3.10 以上，也找不到 Homebrew。請先安裝 Python 3.12。')
+      setSetup('python', '用 Homebrew 安裝 Python 3.12（第一次會比較久）')
+      await run(brew, ['install', 'python@3.12'], { timeout: 1200000 })
+      python = findPython()
+    }
+    if (!python) throw new Error('找不到可用的 Python 3.10 以上')
+
+    if (!fileExists(paths.mlxPython)) {
+      setSetup('venv', '建立 MLX 專用 Python 環境')
+      await run(python, ['-m', 'venv', paths.mlxVenv], { timeout: 120000 })
+    } else {
+      setSetup('venv', 'MLX Python 環境已存在')
+    }
+
+    const uv = uvCommand()
+    const pipBase = uv ? [uv, 'pip', 'install', '--python', paths.mlxPython] : [paths.mlxPython, '-m', 'pip', 'install']
+    setSetup('pip', '安裝 MLX 語音套件（mlx-audio-plus）')
+    const packages = ['mlx-audio-plus==0.1.7', 'mlx-lm==0.29.1', 'librosa', 'pyloudnorm', 'soundfile']
+    await run(pipBase[0], [...pipBase.slice(1), ...packages], { timeout: 1800000, env: { ...process.env, HF_HOME: paths.hfHome } })
+
+    if (!mlxModelCached()) {
+      setSetup('model', '下載 CosyVoice3-0.5B 模型（約 1.4GB，第一次會比較久）')
+      const downloader = [
+        'from huggingface_hub import snapshot_download',
+        `snapshot_download(${JSON.stringify(MLX_MODEL)}, cache_dir=${JSON.stringify(path.join(paths.hfHome, 'hub'))})`,
+      ].join('\n')
+      await run(paths.mlxPython, ['-c', downloader], {
+        timeout: 3600000,
+        env: { ...process.env, HF_HOME: paths.hfHome },
+      })
+    } else {
+      setSetup('model', 'MLX 模型已下載')
+    }
+    if (!mlxReady()) throw new Error('MLX 套件安裝後仍無法載入，請查看日誌')
+    return 'mlx'
+  }
+
+  async function downloadFile(url, target) {
+    const res = await fetch(url, { redirect: 'follow' })
+    if (!res.ok) throw new Error(`下載失敗（HTTP ${res.status}）：${url}`)
+    const bytes = Buffer.from(await res.arrayBuffer())
+    fs.writeFileSync(target, bytes)
+  }
+
+  async function installMacGguf() {
+    setSetup('engine', '下載 CosyVoice GGUF 引擎（macOS 備援）')
+    const target = path.join(root, 'crispasr')
+    fs.mkdirSync(target, { recursive: true })
+    const tgz = path.join(root, 'crispasr-macos-arm64.tar.gz')
+    await downloadFile(CRISPASR_MAC_URL, tgz)
+    await run('tar', ['-xzf', tgz, '-C', target], { timeout: 180000 })
+    if (!fileExists(paths.macCrisp)) throw new Error('解壓縮後找不到 crispasr 執行檔')
+    fs.chmodSync(paths.macCrisp, 0o755)
+    return 'gguf'
+  }
+
+  async function installWinGguf() {
+    setSetup('engine', '下載 CosyVoice GGUF 引擎（Windows）')
+    fs.mkdirSync(paths.winDir, { recursive: true })
+    const zip = path.join(root, 'crispasr-windows.zip')
+    await downloadFile(CRISPASR_WIN_URL, zip)
+    await run('powershell', ['-NoProfile', '-Command', `Expand-Archive -LiteralPath ${JSON.stringify(zip)} -DestinationPath ${JSON.stringify(paths.winDir)} -Force`], { timeout: 300000 })
+    const found = []
+    for (const name of fs.readdirSync(paths.winDir)) {
+      const full = path.join(paths.winDir, name)
+      if (/crispasr(\.exe)?$/i.test(name)) found.push(full)
+      if (dirExists(full)) {
+        for (const sub of fs.readdirSync(full)) {
+          if (/^crispasr(\.exe)?$/i.test(sub)) found.push(path.join(full, sub))
+        }
+      }
+    }
+    if (!found[0]) throw new Error('解壓縮後找不到 crispasr.exe')
+    if (found[0] !== paths.winCrisp) fs.copyFileSync(found[0], paths.winCrisp)
+    return 'gguf'
+  }
+
+  async function ensureDefaultReference() {
+    setSetup('reference', '準備預設參考音')
+    if (fileExists(paths.defaultRef)) return paths.defaultRef
+    const cfg = cfgVoice()
+    let source = String(cfg.referenceSource || '').trim()
+    if (!source || !fileExists(source)) {
+      const downloads = path.join(os.homedir(), 'Downloads')
+      try {
+        const hit = fs.readdirSync(downloads).find((name) => name.includes('本间心铃'))
+        if (hit) source = path.join(downloads, hit)
+      } catch {
+        /* no Downloads */
+      }
+    }
+    if (!source || !fileExists(source)) {
+      if (fileExists(paths.defaultRef)) return paths.defaultRef
+      throw new Error('找不到預設參考音，請在面板上傳一段聲音檔')
+    }
+    const ffmpeg = which('ffmpeg')
+    if (!ffmpeg) throw new Error('需要 ffmpeg 才能處理參考音，請先安裝 ffmpeg')
+    await run(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-ss', '12', '-t', '4.2', '-i', source, '-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le', paths.defaultRef], { timeout: 120000 })
+    return paths.defaultRef
+  }
+
+  async function install() {
+    if (state.installing) return { started: false, already: true }
+    state.installing = true
+    state.setup.startedAt = Date.now()
+    setSetup('detect', '偵測系統環境')
+    try {
+      const detected = detect()
+      let provider = ''
+      if (detected.platform === 'darwin' && detected.arch === 'arm64') {
+        try {
+          provider = await installMlx()
+        } catch (error) {
+          setSetup('fallback', 'MLX 安裝失敗，改用 GGUF 備援', error)
+          provider = await installMacGguf()
+        }
+      } else if (detected.platform === 'win32') {
+        provider = await installWinGguf()
+      } else {
+        provider = await installMacGguf()
+      }
+      await ensureDefaultReference()
+      const env = { ...process.env, HF_HOME: paths.hfHome }
+      setSetup('test', '測試語音合成')
+      await synthesize('主人，語音功能測試成功。', { forceProvider: provider, env, skipConsent: true })
+      setSetup('done', `環境已就緒（${provider === 'mlx' ? 'macOS MLX' : 'CosyVoice GGUF'}）`)
+      return { started: true, provider }
+    } catch (error) {
+      setSetup('error', '環境安裝失敗', error)
+      throw error
+    } finally {
+      state.installing = false
+    }
+  }
+
+  function cleanText(text, maxChars) {
+    const value = String(text || '')
+      .replace(/\[\[\s*(?:voice|語音|语音)\s*\]\]/gi, '')
+      .replace(/[*_`#>]/g, '')
+      .replace(/\s+/g, ' ')
+      .trim()
+    return value.slice(0, Math.max(1, maxChars))
+  }
+
+  async function synthesize(text, { forceProvider = '', env = process.env, skipConsent = false, instructText: instructOverride = '' } = {}) {
+    const cfg = cfgVoice()
+    if (!skipConsent && cfg.consent !== true) throw new Error('尚未確認聲音使用權利（面板：語音回覆 → 我確認有使用權）')
+    if (!skipConsent && cfg.enabled === false) throw new Error('語音功能未開啟')
+    const provider = forceProvider || resolveProvider(cfg)
+    const ref = referencePath()
+    if (!ref) throw new Error('尚未設定參考音')
+    const maxChars = Math.max(20, Math.min(300, Number(cfg.maxChars) || 80))
+    const cleaned = cleanText(text, maxChars)
+    if (!cleaned) throw new Error('沒有可合成的文字')
+    const ffmpeg = which('ffmpeg')
+    if (!ffmpeg) throw new Error('找不到 ffmpeg')
+    const id = randomUUID().slice(0, 8)
+    const prefix = path.join(paths.outDir, `tts-${id}`)
+    const startedAt = Date.now()
+    const instructText = String(instructOverride || cfg.instructText || DEFAULT_INSTRUCT).trim()
+    const cloneMode = String(cfg.cloneMode || 'instruct')
+    let wav = ''
+    try {
+      if (provider === 'mlx') {
+        const jobFile = path.join(paths.jobsDir, `${id}.json`)
+        const payload = {
+          text: cleaned,
+          model: String(cfg.model || MLX_MODEL),
+          refAudio: ref,
+          prefix,
+          instructText: cloneMode === 'instruct' ? instructText : '',
+          refText: cloneMode === 'zero-shot' ? String(cfg.refText || '') : '',
+        }
+        fs.writeFileSync(jobFile, JSON.stringify(payload), { mode: 0o600 })
+        const { stdout } = await run(paths.mlxPython, [paths.mlxScript, jobFile], {
+          timeout: 600000,
+          env: { ...env, HF_HOME: paths.hfHome },
+        })
+        const line = String(stdout || '').split(/\r?\n/).reverse().find((item) => item.startsWith('RESULT:'))
+        if (!line) throw new Error(`MLX 沒有回傳結果：${String(stdout).slice(-300)}`)
+        const result = JSON.parse(line.slice('RESULT:'.length))
+        if (!result.ok || !result.file) throw new Error('MLX 沒有產生音檔')
+        wav = result.file
+      } else {
+        const bin = ggufBinary()
+        if (!bin) throw new Error('找不到 crispasr 執行檔')
+        wav = `${prefix}.wav`
+        const args = ['--backend', GGUF_BACKEND, '-m', String(cfg.model || 'auto'), '--voice', ref, '--tts', cleaned, '--tts-output', wav, '-tl', 'zh', '--i-have-rights']
+        if (cloneMode === 'instruct' && instructText) args.push('--instruct', instructText)
+        if (cloneMode === 'zero-shot' && cfg.refText) args.push('--ref-text', String(cfg.refText))
+        if (cfg.skipDisclaimer !== false) args.push('--no-spoken-disclaimer', '--accept-marking-responsibility')
+        const { stderr } = await run(bin, args, { timeout: 900000, env: { ...env, HF_HOME: paths.hfHome } })
+        if (!fileExists(wav)) throw new Error(`GGUF 沒有產生音檔：${String(stderr || '').slice(-300)}`)
+      }
+      const m4a = `${prefix}.m4a`
+      await run(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-i', wav, '-c:a', 'aac', '-b:a', '96k', '-ar', '44100', '-ac', '1', m4a], { timeout: 120000 })
+      const durationMs = await fileDurationMs(m4a)
+      const bytes = fs.statSync(m4a).size
+      state.last = { provider, at: Date.now(), durationMs, bytes, chars: cleaned.length, processingMs: Date.now() - startedAt }
+      state.lastError = ''
+      return { provider, wav, m4a, durationMs, bytes, chars: cleaned.length, processingMs: state.last.processingMs }
+    } catch (error) {
+      state.lastError = String(error?.message || error)
+      throw error
+    }
+  }
+
+  async function fileDurationMs(file) {
+    try {
+      const { stdout } = await run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', file], { timeout: 15000 })
+      return Math.max(0, Math.round(Number(String(stdout).trim()) * 1000))
+    } catch {
+      return 0
+    }
+  }
+
+  async function saveReferenceBuffer(buffer, filename, ext = '.wav') {
+    const safe = String(filename || 'upload').replace(/[^\w.\-()\u4e00-\u9fff ]+/g, '_').slice(0, 60) || 'upload'
+    const src = path.join(paths.refDir, `${Date.now()}-${safe}${safe.endsWith(ext) ? '' : ext}`)
+    fs.writeFileSync(src, buffer)
+    if (!fileExists(src)) throw new Error('寫入上傳檔案失敗')
+    const ffmpeg = which('ffmpeg')
+    if (!ffmpeg) throw new Error('需要 ffmpeg 才能轉換音檔')
+    const dest = path.join(paths.refDir, `upload-${Date.now()}.wav`)
+    await run(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-i', src, '-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le', dest], { timeout: 120000 })
+    const info = referenceInfoFor(dest)
+    return { path: dest, ...info }
+  }
+
+  function referenceInfoFor(file) {
+    let seconds = 0
+    try {
+      const out = execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', file], { encoding: 'utf8', timeout: 8000 })
+      seconds = Number(out.trim()) || 0
+    } catch {
+      seconds = 0
+    }
+    return { seconds: Math.round(seconds * 100) / 100 }
+  }
+
+  function status() {
+    const detected = detect()
+    return {
+      ...detected,
+      reference: detected.reference,
+      setup: state.setup,
+      installing: state.installing,
+      last: state.last,
+      lastError: state.lastError,
+      mlxScript: fileExists(paths.mlxScript),
+      lastSample: (() => {
+        try {
+          const files = fs.readdirSync(paths.outDir).filter((name) => name.endsWith('.m4a')).sort().reverse()
+          return files[0] ? path.join(paths.outDir, files[0]) : ''
+        } catch {
+          return ''
+        }
+      })(),
+    }
+  }
+
+  return { detect, install, synthesize, status, saveReferenceBuffer, referencePath, paths }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-line-bot",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "description": "把 LINE 官方帳號（Messaging API）接進 DeepSeek Harness 的插件：內建 Cloudflare Tunnel、人設選擇（大肥魚或插件自訂）、主動傳訊與完整設定面板。",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,7 @@
     "client.js",
     "cordis.patch.yml",
     "lib",
+    "tools",
     "locale",
     "icon.svg",
     "README.md",
@@ -65,7 +66,7 @@
     "url": "https://github.com/Hanson0901/dsh-line-bot/issues"
   },
   "bin": {
-    "dsh-line-bot": "./bin/cli.mjs"
+    "dsh-line-bot": "bin/cli.mjs"
   },
   "publishConfig": {
     "access": "public"

package/tools/mlx_synth.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""One-shot MLX CosyVoice3 synthesis helper for dsh-line-bot.
+
+Reads a JSON job file, synthesizes one WAV, and prints a single
+`RESULT:{...}` line on stdout so the Node side can parse it.
+"""
+import glob
+import json
+import os
+import sys
+import traceback
+
+
+def emit(payload):
+    sys.stdout.write("RESULT:" + json.dumps(payload, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def main():
+    if len(sys.argv) < 2:
+        emit({"ok": False, "error": "missing job file"})
+        return 2
+    with open(sys.argv[1], "r", encoding="utf-8") as handle:
+        job = json.load(handle)
+
+    prefix = job.get("prefix") or "tts"
+    os.makedirs(os.path.dirname(prefix) or ".", exist_ok=True)
+
+    try:
+        from mlx_audio.tts.generate import generate_audio
+
+        kwargs = {
+            "text": job["text"],
+            "model": job.get("model") or "mlx-community/Fun-CosyVoice3-0.5B-2512-8bit",
+            "ref_audio": job.get("refAudio"),
+            "file_prefix": prefix,
+            "audio_format": "wav",
+            "verbose": False,
+            "join_audio": True,
+        }
+        if job.get("instructText"):
+            kwargs["instruct_text"] = job["instructText"]
+        elif job.get("refText"):
+            kwargs["ref_text"] = job["refText"]
+        generate_audio(**kwargs)
+
+        candidates = sorted(glob.glob(prefix + "*.wav"), key=os.path.getmtime)
+        if not candidates:
+            emit({"ok": False, "error": "no output wav produced"})
+            return 1
+        emit({"ok": True, "file": candidates[-1]})
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        traceback.print_exc(file=sys.stderr)
+        emit({"ok": False, "error": str(exc)})
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())