dsh-sound-atelier 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 1.0.2 — 2026-11-15
+
+- Voice delivery for messaging plugins is now built in (previously the separate `dsh-speech-bridge` plugin, same maintainer): the `send_speech_reply` tool for OneBot, QQBot and dsh-im conversations, the "語音交付" settings page with channel capabilities and recent results, and the optional `external:dsh-voice` speech-to-text source. Nothing extra to install.
+- Two new settings, both on by default: `speechBridgeEnabled` and `speechBridgeExternalVoice`. The tool only appears in conversations that have a matching messaging tool.
+- If the old standalone bridge is still installed it keeps handling delivery and the built-in one stays out of its way.
+
+# 1.0.1 — 2026-11-15
+
+- Fix one-click update being unavailable: the updater now finds the DSH command-line entry in DSH Desktop and in `dsh web`, runs it the way the host was started, and reads the profile from where the plugin is installed instead of assuming `web`.
+
 # 1.0.0 — 2026-11-15
 
 - Prepare the renamed DSH-sound-atelier fork for source distribution; maintainer puffdog-git.

package/COMMUNICATION-COMPATIBILITY.md

@@ -1,5 +1,7 @@
 # 外部通訊插件相容性檢查
 
+> **1.0.2 更新**：下文提到的獨立 `dsh-speech-bridge` 已併入聲音工坊，不必另外安裝。用法與開關見 [SPEECH-INTEGRATION.md](SPEECH-INTEGRATION.md) 的「通訊語音交付」。以下保留併入前的檢查紀錄。
+
 ## 後續實作已加入
 
 使用者後續要求原生語音泡泡並以模擬驗收：已新增本機 `dsh-im-voice` 5.10.0-voice.1 分支，透過語音意圖協商接入 10 個通道的原生語音路徑，詳見該分支 NATIVE-VOICE.md。Slack／Email／iMessage 維持音訊附件。原版 dsh-im 備份保留，TTS 本身未納入通訊協定。以下「dsh-im 只附件」敘述適用原版與不支援的新通道，不再代表本機語音分支的完整能力。

package/README.en.md

@@ -32,6 +32,7 @@ Based on [dsh-tts](https://github.com/GooDAnDReaDY/dsh-tts) 0.4.42 by GooDAnDRea
 - 🇯🇵 **Chinese/Japanese dubbing.** Chinese on screen, Japanese out loud. Great for role-play.
 - 🧬 **Voice cloning.** Build a voice from a recording; RVC voice conversion is supported too.
 - 🛟 **Switches when one breaks.** If the first speech service fails, the next in your list takes over.
+- 💬 **Voice messages in chat apps.** With the QQ (OneBot, QQBot) or dsh-im messaging plugins, ask for a spoken reply and the AI sends it as a voice message.
 
 ## 💞 Made for Discord-cyberfriend
 
@@ -90,6 +91,7 @@ Does the user have a source folder instead of a market install? Follow "Installi
 - **Cloud speech services cost money.** Reading, previews and creating voices may all be billed, to your own account. Edge is free.
 - **Local models are yours to set up.** None are bundled, large ones need an NVIDIA GPU, and the one-click setup is tested on Windows only.
 - **Not every service was tested with a paid account.** Try a short phrase when switching to a new one.
+- **Voice messages in chat apps are simulation-tested only.** Real delivery on QQ and other platforms has not been verified by a person.
 - **Get consent before cloning someone's voice.** Models have their own licences too, and some forbid commercial use.
 - **Do not install the upstream `@goodandready/dsh-tts` alongside this.** The two conflict.
 

package/README.md

@@ -32,6 +32,7 @@
 - 🇯🇵 **中日配音**：畫面顯示中文，嘴巴講日文，角色扮演很對味。
 - 🧬 **複製聲音**：用一段錄音建立專屬音色；也支援 RVC 變聲。
 - 🛟 **壞了會自動換**：第一個語音服務失敗時，依你排好的順序換下一個。
+- 💬 **在聊天軟體送語音訊息**：搭配 QQ（OneBot、QQBot）或 dsh-im 通訊插件時，你說一聲，AI 就把回覆合成語音、當成語音訊息送出。
 
 ## 💞 和 Discord 賽博群友是天生一對
 
@@ -45,7 +46,7 @@
 
 ## 🚀 安裝
 
-在 DSH 的**插件市集**搜尋 `dsh-sound-atelier`，按安裝就好。
+在 DSH 的**插件市集**搜尋 `dsh-sound-atelier`，按安裝就好(正在提交審核)。
 
 喜歡用指令的話：
 
@@ -90,6 +91,7 @@ dsh plugin --profile web add dsh-sound-atelier
 - **雲端語音服務會收費。** 朗讀、試聽、建立音色都可能計費，帳單在你自己的帳號上。Edge 是免費的。
 - **本機模型要自己準備。** 插件不附模型，大型模型需要 NVIDIA 顯示卡；一鍵安裝只在 Windows 上測試過。
 - **不是每一家都實際付費測過。** 換新的語音服務時，先用一句短句試聽。
+- **聊天軟體的語音訊息只做過模擬測試。** QQ 和其他平台的實際送達還沒有真人驗證過。
 - **複製別人的聲音前請取得同意。** 模型本身也各有授權，有些不能商用。
 - **請不要同時安裝上游的 `@goodandready/dsh-tts`。** 兩個會打架。
 

package/SPEECH-INTEGRATION.md

@@ -4,12 +4,37 @@
 
 ## 設定頁
 
-目前主入口為「設定 → 語音」，分成「朗讀與聲音」和「語音交付」。交付頁需啟用獨立 dsh-speech-bridge；未啟用時會提示，不影響單獨朗讀。人格頁的「在聊天軟體中使用語音」提供一般使用者操作說明，下列保留給插件作者的接口契約。
+目前主入口為「設定 → 語音」，分成「朗讀與聲音」和「語音交付」。語音交付從 1.0.2 起內建（原本是獨立的 dsh-speech-bridge），不必另外安裝；交付頁有兩個開關，見下方「通訊語音交付」。人格頁的「在聊天軟體中使用語音」提供一般使用者操作說明，下列保留給插件作者的接口契約。
 
 全繁中介面分為「語音來源」「聲音管理」「人格與語言」「進階設定」。先選線上語音服務或本機部署，再選主要服務、模型、聲音與試聽。分類切換只更換主要服務列，備援列仍可混用線上與本機；設定需按儲存。服務的模型 ID、音色 ID、API 協議名稱、第三方回傳內容與診斷 JSON 保留原文。
 
 聲音管理保留錄音、八家雲端永久音色、本機推理服務、模型／索引／音色包、RVC、背景工作及診斷。安裝與載入需明確操作，開啟頁面不會下載模型或建立付費音色。
 
+## 通訊語音交付
+
+1.0.2 起內建，程式在 `lib/speech-bridge/`。不儲存通訊帳號憑證，也不修改其他插件。
+
+在 OneBot、QQBot 或 dsh-im 的正式對話裡，Agent 可以呼叫 `send_speech_reply({text, channel:"auto", instruction})`。這個工具只在目前對話有對應的通訊工具時才會出現，所以沒有安裝這些通訊插件的人不會看到它。它是「使用者要求語音回覆時」用的工具，不會把所有文字回覆自動變成語音。
+
+| 出口 | 使用的原插件工具 | 交付形式 |
+|---|---|---|
+| dsh-onebot-qq | `qq_send_voice` | 原生語音，受原插件的成員權限與路徑限制 |
+| @zaofan/dsh-qqbot | `send_media(kind=voice)` | 原生語音，收件人由目前對話決定 |
+| @xmanrui/dsh-im | `dsh_im_return_file` | 支援時要求原生語音泡泡，否則是音訊附件；登記成功只代表已排程，不代表平台已送達 |
+
+音訊由聲音工坊自己合成，沿用人格／工作區／對話的音色設定與語氣提示。MP3 上限 4 MiB、文字上限 10000 字；超過會拒絕，不會截斷。一個對話一次只跑一個交付工作，可以取消，不會自動重送。
+
+設定頁「語音交付」分頁的兩個開關：
+
+- **讓 AI 用語音訊息回覆**（`speechBridgeEnabled`，預設開）：關掉後工具立刻消失。
+- **提供 dsh-voice 作為語音辨識來源**（`speechBridgeExternalVoice`，預設開）：把外部 `@goodandready/dsh-voice` 的聽寫功能登記成來源 `external:dsh-voice`。需要另外安裝並設定該插件；不會自動切換目前使用的語音辨識；變更後要重新啟動 DSH。
+
+狀態端點 `GET /dsh-sound-atelier/speech-bridge/status`（只接受本機連線）回傳通道能力與本次啟動最近 30 筆交付狀態，不含文字、錄音、收件人或私人路徑。
+
+如果電腦上還裝著舊的獨立 `dsh-speech-bridge`，聲音工坊會讓它繼續負責、不重複註冊工具；兩者功能相同，可以把舊的移除。
+
+這部分只做過模擬測試（真的通訊插件工具、最後的網路傳輸用替身），沒有在真實的 QQ 或其他平台驗證送達。
+
 ## 人格與音色方案
 
 先在語音來源調整設定，再在「人格與語言」將目前服務鏈、音色、語氣、本機參考、RVC 及配音語言存成具名方案。方案只保存安全憑證槽名稱，不保存 API Key。選擇人格、工作區或會話後套用綁定，表格會列出使用的方案及主要聲音。方案與綁定立即儲存，與全域設定的儲存按鈕分開；刪除方案只解除本機綁定，不刪除雲端聲音、錄音或權重。

package/lib/client-src/33-speech-delivery.js

@@ -0,0 +1,122 @@
+// 「語音交付」頁：通道能力、格式限制與最近交付結果，以及兩個開關。
+//
+// 面板原本在獨立插件 dsh-speech-bridge 裡，1.0.2 起併入聲音工坊。
+// 電腦上還裝著舊的獨立橋接時，60-settings-page.js 會優先用它註冊的面板。
+
+// 語音交付的兩個開關：讀取與儲存都走聲音工坊自己的設定接口。
+function SpeechDeliverySettings({ status, onChanged }) {
+  const h = React.createElement
+  const [config, setConfig] = React.useState(null)
+  const [busy, setBusy] = React.useState(false)
+  const [error, setError] = React.useState('')
+  const alive = React.useRef(true)
+  const read = async () => {
+    const response = await clientFetch('/dsh-sound-atelier/config', { cache: 'no-store', timeoutMs: 8000 })
+    const data = await response.json()
+    if (!response.ok || !data.ok) throw Error('無法讀取設定')
+    return data
+  }
+  React.useEffect(() => {
+    alive.current = true
+    read()
+      .then((data) => alive.current && setConfig(data.config))
+      .catch((failure) => alive.current && setError(String(failure?.message || failure)))
+    return () => {
+      alive.current = false
+    }
+  }, [])
+  const toggle = async (key) => {
+    if (busy) return
+    setBusy(true)
+    setError('')
+    try {
+      const current = await read()
+      const response = await clientFetch('/dsh-sound-atelier/config', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...current.config, [key]: current.config[key] === false, revision: current.revision }),
+        timeoutMs: 10000,
+      })
+      const saved = await response.json().catch(() => ({}))
+      if (!response.ok || !saved.ok) throw Error(saved?.error?.message || '儲存失敗（HTTP ' + response.status + '）')
+      if (alive.current) setConfig(saved.config)
+      onChanged?.()
+    } catch (failure) {
+      if (alive.current) setError(String(failure?.message || failure))
+    } finally {
+      if (alive.current) setBusy(false)
+    }
+  }
+  const row = (key, title, help) =>
+    h(
+      'label',
+      { className: 'sv-switch', key },
+      h('input', {
+        type: 'checkbox',
+        'data-speech-bridge-setting': key,
+        checked: config ? config[key] !== false : true,
+        disabled: !config || busy,
+        onChange: () => toggle(key),
+      }),
+      h('span', null, h('strong', null, title), h('small', { className: 'sv-muted' }, help)),
+    )
+  const sttPending = config && status && (config.speechBridgeExternalVoice !== false) !== (status.externalVoiceEnabled !== false)
+  return h(
+    'div',
+    { className: 'sv-settings' },
+    row(
+      'speechBridgeEnabled',
+      '讓 AI 用語音訊息回覆',
+      '在 QQ（OneBot、QQBot）或 dsh-im 的對話裡，你要求語音回覆時，AI 會合成語音並用原本的通訊插件送出。沒有安裝這些通訊插件時不會有任何作用。',
+    ),
+    row(
+      'speechBridgeExternalVoice',
+      '提供 dsh-voice 作為語音辨識來源',
+      '需要另外安裝並設定 dsh-voice。開啟只是多一個可選的來源，不會自動切換目前使用的語音辨識。變更後要重新啟動 DSH 才生效。',
+    ),
+    sttPending ? h('p', { className: 'sv-muted', role: 'status' }, '語音辨識來源的變更已儲存，重新啟動 DSH 後生效。') : null,
+    status?.standalone
+      ? h(
+          'p',
+          { className: 'sv-muted', role: 'status' },
+          '偵測到另外安裝的 dsh-speech-bridge，目前由它提供語音交付。聲音工坊已內建相同功能，可以把它移除。',
+        )
+      : null,
+    error ? h('p', { className: 'sv-error', role: 'alert' }, error) : null,
+  )
+}
+
+const SpeechDeliveryPanel = (() => {
+  const h=React.createElement
+  const labels={generating:'合成中',queued:'已排程',sent:'已送出',attachment:'附件已送出',failed:'交付失敗',unknown:'結果不明',cancelled:'已取消'}
+  const css=`.sv-settings{display:grid;gap:10px;margin:0 0 18px;padding:14px 16px;border:1px solid var(--sv-line);border-radius:14px}.sv-switch{display:flex;gap:10px;align-items:flex-start;cursor:pointer}.sv-switch input{margin-top:5px;flex-shrink:0}.sv-switch span{display:flex;flex-direction:column;gap:2px;min-width:0}.sv-switch small{font-size:12px}.sv-panel{--sv-accent:var(--dsw-alias-brand-primary,#4d6bfe);--sv-line:var(--dsw-alias-border-l2,#8b9c9a35);color:var(--dsw-alias-label-primary,#203b37);max-width:1120px;padding:20px 4px 40px;font:14px/1.6 system-ui;overflow-wrap:anywhere}.sv-panel *{box-sizing:border-box}.sv-panel h2,.sv-panel h3,.sv-panel p{margin:0}.sv-panel button,.sv-panel input,.sv-panel select{font:inherit;color:inherit}.sv-panel button{cursor:pointer}.sv-top{display:flex;justify-content:space-between;align-items:start;gap:16px;margin-bottom:22px}.sv-top h2{font-size:25px;letter-spacing:.04em}.sv-muted{opacity:.7;font-size:13px}.sv-btn{background:transparent;border:1px solid var(--sv-line);border-radius:10px;padding:8px 15px;white-space:nowrap}.sv-btn:hover{background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 7%,transparent)}.sv-metrics{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;margin:18px 0}.sv-metric{border:1px solid var(--sv-line);border-radius:14px;padding:16px;background:linear-gradient(120deg,color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 5%,transparent),transparent)}.sv-metric strong{font-size:27px;display:block;line-height:1.3}.sv-note{border-left:3px solid var(--sv-accent);padding:12px 15px;background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 4%,transparent);border-radius:0 10px 10px 0;margin:16px 0}.sv-badge{display:inline-flex;font-size:12px;border-radius:20px;padding:3px 10px;background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 9%,transparent);color:var(--sv-accent);white-space:nowrap}.sv-badge.warn{color:#9c6419;background:#c18c2520}.sv-badge.bad{color:#b74e48;background:#b74e4818}.sv-tabs{display:flex;gap:8px;border-bottom:1px solid var(--sv-line);margin:24px 0 16px}.sv-tabs button{border:0;background:transparent;padding:10px 16px;border-bottom:3px solid transparent}.sv-tabs button[aria-current=page]{color:var(--sv-accent);border-bottom-color:var(--sv-accent);font-weight:700}.sv-filters{display:flex;gap:10px;flex-wrap:wrap;align-items:end;margin-bottom:16px}.sv-filters label{display:flex;flex-direction:column;gap:5px;font-size:12px}.sv-filters input,.sv-filters select{background:transparent;border:1px solid var(--sv-line);border-radius:9px;padding:8px 10px;max-width:100%;min-width:0}.sv-filters label:first-child{flex:1;min-width:170px}.sv-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(285px,100%),1fr));gap:12px}.sv-card{border:1px solid var(--sv-line);border-radius:14px;padding:17px;background:var(--dsw-alias-bg-layer-3,transparent)}.sv-card-head{display:flex;justify-content:space-between;gap:8px;align-items:start}.sv-card h3{font-size:16px}.sv-spec{display:grid;grid-template-columns:1fr 1fr;gap:10px;margin:16px 0 12px}.sv-spec span{display:block;font-size:11px;opacity:.65}.sv-spec strong{font-size:14px}.sv-card details{font-size:12px;margin:12px 0}.sv-card summary{cursor:pointer;color:var(--sv-accent)}.sv-card footer{border-top:1px solid var(--sv-line);padding-top:10px;font-size:12px;opacity:.7}.sv-results{display:grid;gap:10px}.sv-result{border:1px solid var(--sv-line);border-radius:12px;padding:16px}.sv-result p{margin-top:8px}.sv-empty{text-align:center;border:1px dashed var(--sv-line);border-radius:14px;padding:36px 18px}.sv-error{padding:14px;border:1px solid #b74e4870;border-radius:12px;color:#b74e48}.sv-panel :focus-visible{outline:3px solid var(--dsw-alias-brand-primary,#4d6bfe);outline-offset:3px}@media(max-width:500px){.sv-panel{padding:12px 0 24px}.sv-metrics{gap:7px}.sv-metric{padding:12px 9px}.sv-metric strong{font-size:23px}.sv-metric span{font-size:11px}.sv-top h2{font-size:22px}.sv-filters label{flex:1;min-width:100px}.sv-tabs button{padding:10px}.sv-card{padding:15px}}@media(prefers-color-scheme:dark){.sv-panel{--sv-accent:var(--dsw-alias-brand-primary,#4d6bfe);color:var(--dsw-alias-label-primary,#e2eee9)}.sv-panel option{background:#182923;color:#e2eee9}}`
+  function Panel({active=true}){
+   const [data,setData]=React.useState(null),[error,setError]=React.useState(''),[tab,setTab]=React.useState('channels'),[filter,setFilter]=React.useState('all'),[search,setSearch]=React.useState(''),[onlyFailures,setOnlyFailures]=React.useState(false),[updated,setUpdated]=React.useState('')
+   const current=React.useRef(null),alive=React.useRef(true)
+   const load=React.useCallback(async()=>{
+    if(current.current)return
+    const controller=new AbortController();current.current=controller;const timer=setTimeout(()=>controller.abort(),10000)
+    try{const r=await fetch('/dsh-sound-atelier/speech-bridge/status',{credentials:'same-origin',signal:controller.signal,cache:'no-store'});if(!r.ok)throw Error();const out=await r.json();if(!out.ok||!Array.isArray(out.catalog))throw Error();if(!alive.current)return;setData(out);setError('');setUpdated(new Date().toLocaleTimeString('zh-TW',{hour:'2-digit',minute:'2-digit',second:'2-digit'}))}catch{if(alive.current)setError(controller.signal.aborted?'讀取狀態逾時，請稍後按「更新」重試。':'無法讀取交付狀態，請稍後按「更新」重試。')}finally{clearTimeout(timer);if(current.current===controller)current.current=null}
+   },[])
+   React.useEffect(()=>{if(!active)return;alive.current=true;load();const timer=setInterval(()=>{if(!document.hidden)load()},5000);return()=>{alive.current=false;clearInterval(timer);current.current?.abort()}},[load,active])
+   const catalog=data?.catalog||[],recent=data?.recent||[],failed=recent.filter(r=>['failed','unknown'].includes(r.state)),shown=catalog.filter(c=>(filter==='all'||filter==='native'&&c.native||filter==='attachment'&&!c.native)&&`${c.name} ${c.source} ${c.format}`.toLowerCase().includes(search.toLowerCase())),results=onlyFailures?failed:recent
+   const nameFor=id=>catalog.find(c=>c.channel===id)?.name||({auto:'自動選擇',im:'dsh-im',onebot:'OneBot',qqbot:'QQBot'})[id]||'其他通道'
+   const badge=(text,kind)=>h('span',{className:'sv-badge '+(kind||'')},text)
+   return h('section',{className:'sv-panel','aria-label':'語音交付狀態'},h('style',null,css),
+    h('header',{className:'sv-top'},h('div',null,h('h2',null,'語音交付'),h('p',{className:'sv-muted'},'查看通道格式、限制與最近交付結果。')),h('button',{type:'button',className:'sv-btn',onClick:load},'更新')),
+    error?h('p',{className:'sv-error',role:'alert'},error):null,
+    h(SpeechDeliverySettings,{status:data,onChanged:load}),
+    !data&&!error?h('p',{role:'status'},'正在讀取通道能力…'):null,
+    data?h(React.Fragment,null,
+     h('div',{className:'sv-card-head'},badge(!data.deliveryEnabled?'語音交付已關閉':data.deliveryReady||data.standalone?'語音交付已就緒':'語音交付尚未就緒',data.deliveryEnabled&&(data.deliveryReady||data.standalone)?'':'warn'),h('span',{className:'sv-muted'},'最後更新 ',updated)),
+     h('div',{className:'sv-metrics'},[[catalog.filter(c=>c.native).length,'原生語音介面'],[catalog.filter(c=>!c.native).length,'附件交付通道'],[failed.length,'失敗或結果不明']].map(([n,label])=>h('div',{className:'sv-metric',key:label},h('strong',null,n),h('span',null,label)))),
+     h('div',{className:'sv-note'},'已排程 ≠ 已送達。原生語音只在支援的通道使用；超過上限會拒絕，不會截斷句尾。',h('p',{className:'sv-muted'},data.imLoaded?'dsh-im 語音擴充已載入；帳號連線由原通訊插件確認。':'dsh-im 語音擴充尚未載入；下列顯示已實作的能力，啟用原插件後才能交付。')),
+     h('nav',{className:'sv-tabs','aria-label':'語音交付頁籤'},[['channels','通道能力'],['recent','最近交付']].map(([id,title])=>h('button',{type:'button',key:id,'aria-current':tab===id?'page':undefined,onClick:()=>setTab(id)},title))),
+     tab==='channels'?h(React.Fragment,null,
+      h('div',{className:'sv-filters'},h('label',null,'搜尋通道',h('input',{type:'search',value:search,placeholder:'例如：微信、Discord','aria-label':'搜尋通道',onChange:e=>setSearch(e.target.value)})),h('label',null,'交付類型',h('select',{value:filter,'aria-label':'交付類型',onChange:e=>setFilter(e.target.value)},h('option',{value:'all'},'全部通道'),h('option',{value:'native'},'原生語音'),h('option',{value:'attachment'},'音訊附件')))),
+      h('div',{className:'sv-grid'},shown.length?shown.map(c=>h('article',{className:'sv-card',key:c.id},h('div',{className:'sv-card-head'},h('div',null,h('h3',null,c.name),h('p',{className:'sv-muted'},c.source)),badge(c.native?'原生語音':'音訊附件',c.native?'':'warn')),h('div',{className:'sv-spec'},h('div',null,h('span',null,'單則時長'),h('strong',null,c.maxSeconds?c.maxSeconds+' 秒':c.native?'依平台限制':'依附件限制')),h('div',null,h('span',null,'橋接輸入上限'),h('strong',null,'4 MiB'))),h('p',null,c.format),h('details',null,h('summary',null,'格式與限制說明'),h('p',null,c.limitNote),h('p',null,c.note)),h('footer',null,c.availability==='not-loaded'?'語音擴充未載入':c.availability==='loaded'?'擴充已載入 · 連線由原插件確認':'由目前通訊會話確認可用性'))):h('p',{className:'sv-empty'},'沒有符合條件的通道。'))
+     ):h(React.Fragment,null,h('div',{className:'sv-filters'},h('label',{style:{display:'flex',flexDirection:'row',alignItems:'center'}},h('input',{type:'checkbox',checked:onlyFailures,onChange:e=>setOnlyFailures(e.target.checked)}),'僅顯示失敗或結果不明')),h('p',{className:'sv-muted'},'只保留本次啟動最近 30 筆狀態，不保存文字、錄音、收件人或私人路徑。'),h('div',{className:'sv-results'},results.length?results.map(r=>h('article',{className:'sv-result',key:r.id},h('div',{className:'sv-card-head'},h('strong',null,nameFor(r.channel)),badge(labels[r.state]||'待確認',['failed','unknown'].includes(r.state)?'bad':r.state==='queued'?'warn':'')),h('small',{className:'sv-muted'},new Date(r.at).toLocaleString('zh-TW')),r.reason?h(React.Fragment,null,h('p',null,h('strong',null,r.reason.title)),h('p',null,r.reason.action)):r.state==='queued'?h('p',null,'音訊已交給本回合流程，等待通訊插件的送達結果。'):null)):h('div',{className:'sv-empty'},h('strong',null,onlyFailures?'目前沒有失敗紀錄':'還沒有語音交付紀錄'),h('p',{className:'sv-muted'},'使用通訊會話的語音回覆工具後，狀態會出現在這裡。'))))
+    ):null)
+  }
+  return Panel
+})()

package/lib/client-src/60-settings-page.js

@@ -98,13 +98,12 @@ function SpeechSettingsPage(props) {
         hidden: tab !== 'delivery',
       },
       React.createElement(ErrorBoundary, null, React.createElement(DiscordLinkCard, { active: tab === 'delivery' })),
-      Delivery
-        ? React.createElement(Delivery)
-        : React.createElement(
-            'p',
-            { className: 'dts-sub', role: 'status' },
-            '語音交付橋接未載入。啟用 dsh-speech-bridge 後，這裡會顯示通道能力與最近交付；朗讀設定仍可獨立使用。',
-          ),
+      // 語音交付已內建；電腦上另外裝了舊的獨立橋接時，沿用它註冊的面板（狀態在它那邊）。
+      React.createElement(
+        ErrorBoundary,
+        null,
+        Delivery ? React.createElement(Delivery) : React.createElement(SpeechDeliveryPanel, { active: tab === 'delivery' }),
+      ),
     ),
   )
 }

package/lib/client.js

@@ -6809,6 +6809,129 @@ function DiscordLinkCard({ active }) {
     body,
   )
 }
+// ---- 33-speech-delivery.js
+// 「語音交付」頁：通道能力、格式限制與最近交付結果，以及兩個開關。
+//
+// 面板原本在獨立插件 dsh-speech-bridge 裡，1.0.2 起併入聲音工坊。
+// 電腦上還裝著舊的獨立橋接時，60-settings-page.js 會優先用它註冊的面板。
+
+// 語音交付的兩個開關：讀取與儲存都走聲音工坊自己的設定接口。
+function SpeechDeliverySettings({ status, onChanged }) {
+  const h = React.createElement
+  const [config, setConfig] = React.useState(null)
+  const [busy, setBusy] = React.useState(false)
+  const [error, setError] = React.useState('')
+  const alive = React.useRef(true)
+  const read = async () => {
+    const response = await clientFetch('/dsh-sound-atelier/config', { cache: 'no-store', timeoutMs: 8000 })
+    const data = await response.json()
+    if (!response.ok || !data.ok) throw Error('無法讀取設定')
+    return data
+  }
+  React.useEffect(() => {
+    alive.current = true
+    read()
+      .then((data) => alive.current && setConfig(data.config))
+      .catch((failure) => alive.current && setError(String(failure?.message || failure)))
+    return () => {
+      alive.current = false
+    }
+  }, [])
+  const toggle = async (key) => {
+    if (busy) return
+    setBusy(true)
+    setError('')
+    try {
+      const current = await read()
+      const response = await clientFetch('/dsh-sound-atelier/config', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...current.config, [key]: current.config[key] === false, revision: current.revision }),
+        timeoutMs: 10000,
+      })
+      const saved = await response.json().catch(() => ({}))
+      if (!response.ok || !saved.ok) throw Error(saved?.error?.message || '儲存失敗（HTTP ' + response.status + '）')
+      if (alive.current) setConfig(saved.config)
+      onChanged?.()
+    } catch (failure) {
+      if (alive.current) setError(String(failure?.message || failure))
+    } finally {
+      if (alive.current) setBusy(false)
+    }
+  }
+  const row = (key, title, help) =>
+    h(
+      'label',
+      { className: 'sv-switch', key },
+      h('input', {
+        type: 'checkbox',
+        'data-speech-bridge-setting': key,
+        checked: config ? config[key] !== false : true,
+        disabled: !config || busy,
+        onChange: () => toggle(key),
+      }),
+      h('span', null, h('strong', null, title), h('small', { className: 'sv-muted' }, help)),
+    )
+  const sttPending = config && status && (config.speechBridgeExternalVoice !== false) !== (status.externalVoiceEnabled !== false)
+  return h(
+    'div',
+    { className: 'sv-settings' },
+    row(
+      'speechBridgeEnabled',
+      '讓 AI 用語音訊息回覆',
+      '在 QQ（OneBot、QQBot）或 dsh-im 的對話裡，你要求語音回覆時，AI 會合成語音並用原本的通訊插件送出。沒有安裝這些通訊插件時不會有任何作用。',
+    ),
+    row(
+      'speechBridgeExternalVoice',
+      '提供 dsh-voice 作為語音辨識來源',
+      '需要另外安裝並設定 dsh-voice。開啟只是多一個可選的來源，不會自動切換目前使用的語音辨識。變更後要重新啟動 DSH 才生效。',
+    ),
+    sttPending ? h('p', { className: 'sv-muted', role: 'status' }, '語音辨識來源的變更已儲存，重新啟動 DSH 後生效。') : null,
+    status?.standalone
+      ? h(
+          'p',
+          { className: 'sv-muted', role: 'status' },
+          '偵測到另外安裝的 dsh-speech-bridge，目前由它提供語音交付。聲音工坊已內建相同功能，可以把它移除。',
+        )
+      : null,
+    error ? h('p', { className: 'sv-error', role: 'alert' }, error) : null,
+  )
+}
+
+const SpeechDeliveryPanel = (() => {
+  const h=React.createElement
+  const labels={generating:'合成中',queued:'已排程',sent:'已送出',attachment:'附件已送出',failed:'交付失敗',unknown:'結果不明',cancelled:'已取消'}
+  const css=`.sv-settings{display:grid;gap:10px;margin:0 0 18px;padding:14px 16px;border:1px solid var(--sv-line);border-radius:14px}.sv-switch{display:flex;gap:10px;align-items:flex-start;cursor:pointer}.sv-switch input{margin-top:5px;flex-shrink:0}.sv-switch span{display:flex;flex-direction:column;gap:2px;min-width:0}.sv-switch small{font-size:12px}.sv-panel{--sv-accent:var(--dsw-alias-brand-primary,#4d6bfe);--sv-line:var(--dsw-alias-border-l2,#8b9c9a35);color:var(--dsw-alias-label-primary,#203b37);max-width:1120px;padding:20px 4px 40px;font:14px/1.6 system-ui;overflow-wrap:anywhere}.sv-panel *{box-sizing:border-box}.sv-panel h2,.sv-panel h3,.sv-panel p{margin:0}.sv-panel button,.sv-panel input,.sv-panel select{font:inherit;color:inherit}.sv-panel button{cursor:pointer}.sv-top{display:flex;justify-content:space-between;align-items:start;gap:16px;margin-bottom:22px}.sv-top h2{font-size:25px;letter-spacing:.04em}.sv-muted{opacity:.7;font-size:13px}.sv-btn{background:transparent;border:1px solid var(--sv-line);border-radius:10px;padding:8px 15px;white-space:nowrap}.sv-btn:hover{background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 7%,transparent)}.sv-metrics{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;margin:18px 0}.sv-metric{border:1px solid var(--sv-line);border-radius:14px;padding:16px;background:linear-gradient(120deg,color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 5%,transparent),transparent)}.sv-metric strong{font-size:27px;display:block;line-height:1.3}.sv-note{border-left:3px solid var(--sv-accent);padding:12px 15px;background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 4%,transparent);border-radius:0 10px 10px 0;margin:16px 0}.sv-badge{display:inline-flex;font-size:12px;border-radius:20px;padding:3px 10px;background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4d6bfe) 9%,transparent);color:var(--sv-accent);white-space:nowrap}.sv-badge.warn{color:#9c6419;background:#c18c2520}.sv-badge.bad{color:#b74e48;background:#b74e4818}.sv-tabs{display:flex;gap:8px;border-bottom:1px solid var(--sv-line);margin:24px 0 16px}.sv-tabs button{border:0;background:transparent;padding:10px 16px;border-bottom:3px solid transparent}.sv-tabs button[aria-current=page]{color:var(--sv-accent);border-bottom-color:var(--sv-accent);font-weight:700}.sv-filters{display:flex;gap:10px;flex-wrap:wrap;align-items:end;margin-bottom:16px}.sv-filters label{display:flex;flex-direction:column;gap:5px;font-size:12px}.sv-filters input,.sv-filters select{background:transparent;border:1px solid var(--sv-line);border-radius:9px;padding:8px 10px;max-width:100%;min-width:0}.sv-filters label:first-child{flex:1;min-width:170px}.sv-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(285px,100%),1fr));gap:12px}.sv-card{border:1px solid var(--sv-line);border-radius:14px;padding:17px;background:var(--dsw-alias-bg-layer-3,transparent)}.sv-card-head{display:flex;justify-content:space-between;gap:8px;align-items:start}.sv-card h3{font-size:16px}.sv-spec{display:grid;grid-template-columns:1fr 1fr;gap:10px;margin:16px 0 12px}.sv-spec span{display:block;font-size:11px;opacity:.65}.sv-spec strong{font-size:14px}.sv-card details{font-size:12px;margin:12px 0}.sv-card summary{cursor:pointer;color:var(--sv-accent)}.sv-card footer{border-top:1px solid var(--sv-line);padding-top:10px;font-size:12px;opacity:.7}.sv-results{display:grid;gap:10px}.sv-result{border:1px solid var(--sv-line);border-radius:12px;padding:16px}.sv-result p{margin-top:8px}.sv-empty{text-align:center;border:1px dashed var(--sv-line);border-radius:14px;padding:36px 18px}.sv-error{padding:14px;border:1px solid #b74e4870;border-radius:12px;color:#b74e48}.sv-panel :focus-visible{outline:3px solid var(--dsw-alias-brand-primary,#4d6bfe);outline-offset:3px}@media(max-width:500px){.sv-panel{padding:12px 0 24px}.sv-metrics{gap:7px}.sv-metric{padding:12px 9px}.sv-metric strong{font-size:23px}.sv-metric span{font-size:11px}.sv-top h2{font-size:22px}.sv-filters label{flex:1;min-width:100px}.sv-tabs button{padding:10px}.sv-card{padding:15px}}@media(prefers-color-scheme:dark){.sv-panel{--sv-accent:var(--dsw-alias-brand-primary,#4d6bfe);color:var(--dsw-alias-label-primary,#e2eee9)}.sv-panel option{background:#182923;color:#e2eee9}}`
+  function Panel({active=true}){
+   const [data,setData]=React.useState(null),[error,setError]=React.useState(''),[tab,setTab]=React.useState('channels'),[filter,setFilter]=React.useState('all'),[search,setSearch]=React.useState(''),[onlyFailures,setOnlyFailures]=React.useState(false),[updated,setUpdated]=React.useState('')
+   const current=React.useRef(null),alive=React.useRef(true)
+   const load=React.useCallback(async()=>{
+    if(current.current)return
+    const controller=new AbortController();current.current=controller;const timer=setTimeout(()=>controller.abort(),10000)
+    try{const r=await fetch('/dsh-sound-atelier/speech-bridge/status',{credentials:'same-origin',signal:controller.signal,cache:'no-store'});if(!r.ok)throw Error();const out=await r.json();if(!out.ok||!Array.isArray(out.catalog))throw Error();if(!alive.current)return;setData(out);setError('');setUpdated(new Date().toLocaleTimeString('zh-TW',{hour:'2-digit',minute:'2-digit',second:'2-digit'}))}catch{if(alive.current)setError(controller.signal.aborted?'讀取狀態逾時，請稍後按「更新」重試。':'無法讀取交付狀態，請稍後按「更新」重試。')}finally{clearTimeout(timer);if(current.current===controller)current.current=null}
+   },[])
+   React.useEffect(()=>{if(!active)return;alive.current=true;load();const timer=setInterval(()=>{if(!document.hidden)load()},5000);return()=>{alive.current=false;clearInterval(timer);current.current?.abort()}},[load,active])
+   const catalog=data?.catalog||[],recent=data?.recent||[],failed=recent.filter(r=>['failed','unknown'].includes(r.state)),shown=catalog.filter(c=>(filter==='all'||filter==='native'&&c.native||filter==='attachment'&&!c.native)&&`${c.name} ${c.source} ${c.format}`.toLowerCase().includes(search.toLowerCase())),results=onlyFailures?failed:recent
+   const nameFor=id=>catalog.find(c=>c.channel===id)?.name||({auto:'自動選擇',im:'dsh-im',onebot:'OneBot',qqbot:'QQBot'})[id]||'其他通道'
+   const badge=(text,kind)=>h('span',{className:'sv-badge '+(kind||'')},text)
+   return h('section',{className:'sv-panel','aria-label':'語音交付狀態'},h('style',null,css),
+    h('header',{className:'sv-top'},h('div',null,h('h2',null,'語音交付'),h('p',{className:'sv-muted'},'查看通道格式、限制與最近交付結果。')),h('button',{type:'button',className:'sv-btn',onClick:load},'更新')),
+    error?h('p',{className:'sv-error',role:'alert'},error):null,
+    h(SpeechDeliverySettings,{status:data,onChanged:load}),
+    !data&&!error?h('p',{role:'status'},'正在讀取通道能力…'):null,
+    data?h(React.Fragment,null,
+     h('div',{className:'sv-card-head'},badge(!data.deliveryEnabled?'語音交付已關閉':data.deliveryReady||data.standalone?'語音交付已就緒':'語音交付尚未就緒',data.deliveryEnabled&&(data.deliveryReady||data.standalone)?'':'warn'),h('span',{className:'sv-muted'},'最後更新 ',updated)),
+     h('div',{className:'sv-metrics'},[[catalog.filter(c=>c.native).length,'原生語音介面'],[catalog.filter(c=>!c.native).length,'附件交付通道'],[failed.length,'失敗或結果不明']].map(([n,label])=>h('div',{className:'sv-metric',key:label},h('strong',null,n),h('span',null,label)))),
+     h('div',{className:'sv-note'},'已排程 ≠ 已送達。原生語音只在支援的通道使用；超過上限會拒絕，不會截斷句尾。',h('p',{className:'sv-muted'},data.imLoaded?'dsh-im 語音擴充已載入；帳號連線由原通訊插件確認。':'dsh-im 語音擴充尚未載入；下列顯示已實作的能力，啟用原插件後才能交付。')),
+     h('nav',{className:'sv-tabs','aria-label':'語音交付頁籤'},[['channels','通道能力'],['recent','最近交付']].map(([id,title])=>h('button',{type:'button',key:id,'aria-current':tab===id?'page':undefined,onClick:()=>setTab(id)},title))),
+     tab==='channels'?h(React.Fragment,null,
+      h('div',{className:'sv-filters'},h('label',null,'搜尋通道',h('input',{type:'search',value:search,placeholder:'例如：微信、Discord','aria-label':'搜尋通道',onChange:e=>setSearch(e.target.value)})),h('label',null,'交付類型',h('select',{value:filter,'aria-label':'交付類型',onChange:e=>setFilter(e.target.value)},h('option',{value:'all'},'全部通道'),h('option',{value:'native'},'原生語音'),h('option',{value:'attachment'},'音訊附件')))),
+      h('div',{className:'sv-grid'},shown.length?shown.map(c=>h('article',{className:'sv-card',key:c.id},h('div',{className:'sv-card-head'},h('div',null,h('h3',null,c.name),h('p',{className:'sv-muted'},c.source)),badge(c.native?'原生語音':'音訊附件',c.native?'':'warn')),h('div',{className:'sv-spec'},h('div',null,h('span',null,'單則時長'),h('strong',null,c.maxSeconds?c.maxSeconds+' 秒':c.native?'依平台限制':'依附件限制')),h('div',null,h('span',null,'橋接輸入上限'),h('strong',null,'4 MiB'))),h('p',null,c.format),h('details',null,h('summary',null,'格式與限制說明'),h('p',null,c.limitNote),h('p',null,c.note)),h('footer',null,c.availability==='not-loaded'?'語音擴充未載入':c.availability==='loaded'?'擴充已載入 · 連線由原插件確認':'由目前通訊會話確認可用性'))):h('p',{className:'sv-empty'},'沒有符合條件的通道。'))
+     ):h(React.Fragment,null,h('div',{className:'sv-filters'},h('label',{style:{display:'flex',flexDirection:'row',alignItems:'center'}},h('input',{type:'checkbox',checked:onlyFailures,onChange:e=>setOnlyFailures(e.target.checked)}),'僅顯示失敗或結果不明')),h('p',{className:'sv-muted'},'只保留本次啟動最近 30 筆狀態，不保存文字、錄音、收件人或私人路徑。'),h('div',{className:'sv-results'},results.length?results.map(r=>h('article',{className:'sv-result',key:r.id},h('div',{className:'sv-card-head'},h('strong',null,nameFor(r.channel)),badge(labels[r.state]||'待確認',['failed','unknown'].includes(r.state)?'bad':r.state==='queued'?'warn':'')),h('small',{className:'sv-muted'},new Date(r.at).toLocaleString('zh-TW')),r.reason?h(React.Fragment,null,h('p',null,h('strong',null,r.reason.title)),h('p',null,r.reason.action)):r.state==='queued'?h('p',null,'音訊已交給本回合流程，等待通訊插件的送達結果。'):null)):h('div',{className:'sv-empty'},h('strong',null,onlyFailures?'目前沒有失敗紀錄':'還沒有語音交付紀錄'),h('p',{className:'sv-muted'},'使用通訊會話的語音回覆工具後，狀態會出現在這裡。'))))
+    ):null)
+  }
+  return Panel
+})()
 // ---- 40-tts-section.js
 // 模組層級的翻譯函式：內容不依賴元件狀態，放在元件外才不會每次重繪都換一個新函式
 //（子元件以它作為 effect 依賴，例如更新檢查）。
@@ -8948,13 +9071,12 @@ function SpeechSettingsPage(props) {
         hidden: tab !== 'delivery',
       },
       React.createElement(ErrorBoundary, null, React.createElement(DiscordLinkCard, { active: tab === 'delivery' })),
-      Delivery
-        ? React.createElement(Delivery)
-        : React.createElement(
-            'p',
-            { className: 'dts-sub', role: 'status' },
-            '語音交付橋接未載入。啟用 dsh-speech-bridge 後，這裡會顯示通道能力與最近交付；朗讀設定仍可獨立使用。',
-          ),
+      // 語音交付已內建；電腦上另外裝了舊的獨立橋接時，沿用它註冊的面板（狀態在它那邊）。
+      React.createElement(
+        ErrorBoundary,
+        null,
+        Delivery ? React.createElement(Delivery) : React.createElement(SpeechDeliveryPanel, { active: tab === 'delivery' }),
+      ),
     ),
   )
 }

package/lib/index.js

@@ -42,6 +42,7 @@ import { referenceFingerprint } from './providers/cosyvoice.js'
 import { fileFingerprint } from './providers/reference-audio.js'
 import { trimReplayWindow } from './replay-window.js'
 import { ensureFfmpeg } from './ffmpeg-ensure.js'
+import { applySpeechBridge } from './speech-bridge/index.js'
 import {
   CLOUD_PROVIDERS,
   assertCredentialRef,
@@ -342,6 +343,10 @@ export const Config = z.object({
   timeoutMs: z.number().step(1).min(1000).volatile().default(60000),
   maxQueue: z.number().step(1).min(0).volatile().default(8)
     .description('Synthesis queue budget (up to four parallel requests). Zero disables automatic speech. Completed audio has a separate replay window.'),
+  speechBridgeEnabled: z.boolean().volatile().default(true)
+    .description('讓 AI 在 OneBot／QQBot／dsh-im 的對話裡可以用語音訊息回覆（send_speech_reply 工具）。沒有安裝這些通訊插件時不會有任何作用。'),
+  speechBridgeExternalVoice: z.boolean().volatile().default(true)
+    .description('把外部 dsh-voice 的聽寫功能登記成一個語音辨識來源（external:dsh-voice）。不會自動切換目前使用的語音辨識；變更後重新啟動 DSH 才生效。'),
 })
 
 const LEGACY_NAMES = ['dsh-sound-atelier', 'goodandready/dsh-tts', 'dsh-tts', '@goodandready/dsh-tts']
@@ -1089,4 +1094,15 @@ export function apply(ctx, config) {
       },
     }),
   )
+
+  // 通訊語音交付（原 dsh-speech-bridge）：失敗時只影響語音交付，不影響朗讀。
+  try {
+    applySpeechBridge(ctx, {
+      tts: speechService,
+      enabled: () => live().speechBridgeEnabled !== false,
+      externalVoice: live().speechBridgeExternalVoice !== false,
+    })
+  } catch (error) {
+    console.warn('[dsh-sound-atelier] 語音交付橋接沒有啟動：' + String(error?.message || error))
+  }
 }

package/lib/speech-bridge/bridge.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {randomUUID} from 'node:crypto'
+import {failureReason} from './diagnostics.js'
+
+export const CHANNELS={onebot:'qq_send_voice',qqbot:'send_media',im:'dsh_im_return_file'}
+export function chooseChannel(tools,agent,requested='auto') {
+ let available=Object.entries(CHANNELS).filter(([,name])=>tools.executable(name,agent))
+ if(requested!=='auto'){
+  if(!available.some(([id])=>id===requested))throw Error('目前會話沒有此通訊插件的語音交付工具')
+  return requested
+ }
+ // dsh-im exposes its artifact tool globally; a scoped native channel wins.
+ if(available.some(([id])=>id!=='im'))available=available.filter(([id])=>id!=='im')
+ if(available.length!==1)throw Error(available.length?'目前會話有多個通訊出口，請指定 channel':'請在 OneBot、QQBot 或 dsh-im 的正式會話使用此工具')
+ return available[0][0]
+}
+export async function dispatch(tools,name,args,exec){
+ exec.signal.throwIfAborted()
+ const batch=await tools.execute({agent:exec.agent,signal:exec.signal,calls:[{type:'tool-call',id:randomUUID(),name,arguments:JSON.stringify(args)}]})
+ const result=batch.results?.[0]?.result
+ if(!result||result.isError)throw Object.assign(Error(result?.error?.message||'交付工具未完成；不會自動重送'),{code:result?.error?.code||result?.error?.info?.code})
+ const value=result.value
+ if(value?.ok===false||value?.sent===false)throw Error(value.msg||value.error||'通訊插件拒絕交付')
+ return value
+}
+export function createBridge({tools,tts,enabled=()=>true,onEvent=()=>{}}){
+ const pending=new Map(),controllers=new Set();let closed=false
+ const emit=event=>{try{onEvent(event)}catch{}}
+ async function run(args,exec,id){
+  if(closed||!enabled())throw Error('通訊語音橋接已停用')
+  if(!exec?.agent?.session||!exec.signal)throw Error('需要真實 Agent 會話')
+  const text=String(args.text||'').trim();if(!text||text.length>10000)throw Error('配音文字須為 1–10000 字')
+  if(args.instruction!==undefined&&(typeof args.instruction!=='string'||args.instruction.length>4000))throw Error('語氣提示上限 4000 字')
+  const channel=chooseChannel(tools,exec.agent,args.channel||'auto'),name=CHANNELS[channel]
+  const sid=exec.agent.session.id||exec.agent.session.header?.id
+  if(!sid)throw Error('會話缺少識別碼')
+  if(pending.has(sid))throw Error('此會話已有語音交付工作，請勿重複送出')
+  const controller=new AbortController(),signal=AbortSignal.any([exec.signal,controller.signal,AbortSignal.timeout(180000)])
+  pending.set(sid,controller);controllers.add(controller)
+  let artifact,dir
+  try{
+   signal.throwIfAborted()
+   emit({id,channel,state:'generating',stage:'synthesis'})
+   try{artifact=await tts.exportAudio({text,format:'mp3',sessionId:sid,signal,speechInstruction:args.instruction})}catch(error){error.safeStage='synthesis';throw error}
+   if(artifact.size>4*1024*1024)throw Error('音訊超過橋接 4 MiB 上限，請縮短文字')
+   let file=artifact.path
+   if(channel==='onebot'){
+    const cwd=exec.agent.session.header?.cwd
+    if(!cwd||!path.isAbsolute(cwd))throw Error('OneBot 會話沒有可用的工作區；不會改用其他目錄')
+    const root=await fs.realpath(cwd)
+    dir=await fs.mkdtemp(path.join(root,'.dsh-speech-'))
+    file=path.join(dir,'reply.mp3');await fs.copyFile(artifact.path,file)
+   }
+   signal.throwIfAborted()
+   if(closed||!enabled()||tools.executable(name,exec.agent)===undefined)throw Error('交付前插件或權限已變更')
+   const voiceCapable=channel==='im'&&!!tools.executable(name,exec.agent)?.parameters?.properties?.presentation
+   const payload=channel==='qqbot'?{kind:'voice',source:file}:{path:file,...(voiceCapable?{presentation:'voice'}:{})}
+   const receipt=await dispatch(tools,name,payload,{...exec,signal})
+   emit({id,artifactId:receipt?.artifactId,channel,state:channel==='im'?'queued':'sent',stage:'delivery'})
+   return {ok:true,channel,state:channel==='im'?'staged':'sent',nativeVoice:channel!=='im',deliveryMode:voiceCapable?'native-when-supported':channel==='im'?'audio-attachment':'native-voice',receipt:receipt??null}
+  }finally{
+   pending.delete(sid);controllers.delete(controller)
+   try{if(dir)await fs.rm(dir,{recursive:true,force:true})}finally{await artifact?.remove()}
+  }
+ }
+ async function send(args,exec){const id=randomUUID();try{return await run(args,exec,id)}catch(error){const reason=failureReason(error,error.safeStage||'delivery');emit({id,channel:args.channel||'auto',state:reason.code==='cancelled'?'cancelled':reason.code==='unknown'?'unknown':'failed',code:reason.code,stage:error.safeStage||'delivery'});throw error}}
+ return {send,close(){closed=true;for(const c of controllers)c.abort()}}
+}

package/lib/speech-bridge/catalog.js

@@ -0,0 +1,24 @@
+const rows=[
+ ['telegram','Telegram','Ogg Opus',120,'保留主題與引用回覆'],
+ ['whatsapp','WhatsApp','Ogg Opus',120,'以 PTT 語音便箋交付'],
+ ['discord','Discord','Ogg Opus',120,'包含時長與波形'],
+ ['matrix','Matrix','Ogg Opus',120,'語音外觀依客戶端擴充支援'],
+ ['feishu','飛書','Ogg Opus',120,'保留討論串回覆'],
+ ['qq','QQ','MP3',120,'由 QQ SDK 處理語音上傳'],
+ ['wecom','企微機器人','AMR-NB',60,'使用官方 SDK 的語音訊息'],
+ ['wecom-app','企微自建應用','AMR-NB',60,'使用應用語音訊息接口'],
+ ['dingtalk','釘釘','AMR-NB',60,'使用語音模板，時長以毫秒傳遞'],
+ ['weixin','微信 iLink','Tencent SILK',60,'依官方專案協定接線；尚無真平台驗收'],
+ ['slack','Slack','原音訊附件',null,'目前通道使用檔案上傳，非原生語音泡泡'],
+ ['email','Email','原音訊附件',null,'電子郵件附件不提供聊天語音泡泡'],
+ ['imessage','iMessage','原音訊附件',null,'目前通道未提供原生語音便箋接口'],
+]
+export function channelCatalog({imLoaded=false,reported=[]}={}){
+ return rows.map(([id,name,format,maxSeconds,note])=>{
+  const report=reported.find(r=>r.id===id),native=maxSeconds!==null
+  return {id:'im:'+id,channel:id,name,source:'dsh-im',native,format,maxSeconds:native?(report?.maxSeconds||maxSeconds):null,maxBytes:4*1024*1024,availability:imLoaded?'loaded':'not-loaded',note,limitNote:native?'本機交付上限，超限拒絕，不截斷':'受附件大小及平台限制；不套用原生語音時長上限'}
+ }).concat([
+  {id:'onebot',channel:'onebot',name:'OneBot',source:'獨立通訊插件',native:true,format:'MP3 → OneBot record',maxSeconds:null,maxBytes:4*1024*1024,availability:'session',note:'權限與可用性由目前會話的 OneBot 工具確認',limitNote:'時長依 NapCat 等後端限制'},
+  {id:'qqbot',channel:'qqbot',name:'QQBot',source:'獨立通訊插件',native:true,format:'MP3 → QQ voice',maxSeconds:null,maxBytes:4*1024*1024,availability:'session',note:'權限與可用性由目前會話的 QQBot 工具確認',limitNote:'時長及回覆時效依 QQ 平台限制'},
+ ])
+}

package/lib/speech-bridge/diagnostics.js

@@ -0,0 +1,48 @@
+const reasons={
+ permission:['服務權限不足','請檢查通訊插件的帳號權限、可發送範圍與媒體權限。'],
+ duration:['語音超過時長上限','請縮短回覆，或改用一般音訊附件；系統不會截斷內容。'],
+ size:['音訊超過大小上限','請縮短內容或降低音訊大小；橋接輸入上限為 4 MiB。'],
+ conversion:['音訊轉碼失敗','請確認音訊可讀取及轉碼引擎可用，再重新產生音訊。'],
+ unavailable:['目前會話沒有可用出口','請啟用對應通訊插件，並在它的正式會話使用語音交付。'],
+ context:['本回合沒有可用的交付範圍','請在原通訊會話重試；不要複製其他會話的目的地。'],
+ unknown:['平台送達結果不明','請先確認平台是否已收到；系統不會自動重送或補送附件。'],
+ rate:['服務暫時限制發送','請稍後再試，並檢查原通訊服務的發送頻率限制。'],
+ synthesis:['語音合成失敗','請到 TTS 設定檢查目前服務、金鑰權限與可用音色。'],
+ failed:['語音交付失敗','請檢查原通訊插件的狀態與紀錄；此處不顯示私人路徑或金鑰。'],
+ cancelled:['語音工作已取消','工作已停止；若平台已開始傳輸，請先確認是否收到，避免重送。'],
+}
+export function failureReason(error={},stage='delivery'){
+ const code=String(error.code||''),message=String(error.message||'')
+ let key=error.name==='AbortError'||/cancel|abort/i.test(code)?'cancelled'
+ :/uncertain|unknown/i.test(code)?'unknown'
+ :/permission|forbidden|401|403/i.test(code)||/權限|权限|permission|forbidden|HTTP\s*[(:]?\s*(401|403)/i.test(message)?'permission'
+ :/duration/i.test(code)||/時長|上限 \d+ 秒/.test(message)?'duration'
+ :/too-large|size-limit|^size$/i.test(code)||/MiB|大小上限|檔案過大/.test(message)?'size'
+ :/conversion|ffmpeg|codec/i.test(code)||/轉碼|格式轉換/.test(message)?'conversion'
+ :/context|consumer/i.test(code)||/active IM delivery consumer|live Harness Session|交付範圍/i.test(message)?'context'
+ :/unavailable|unknown-tool/i.test(code)||/沒有.*工具|正式會話|已停用|多個通訊出口|未啟用|未連線|通道未就緒|通道未就绪|not connected/i.test(message)?'unavailable'
+ :/rate|429/i.test(code)||/rate.limit|429|限流|頻率限制/i.test(message)?'rate'
+ :stage==='synthesis'?'synthesis':'failed'
+ return {code:key,title:reasons[key][0],action:key==='permission'&&stage==='synthesis'?'請到 TTS 供應商設定檢查 API Key 的語音合成權限與模型存取權。':reasons[key][1]}
+}
+const states=new Set(['generating','queued','sent','attachment','failed','unknown','cancelled'])
+const channels=new Set(['auto','onebot','qqbot','im','telegram','whatsapp','discord','matrix','feishu','qq','wecom','wecom-app','dingtalk','weixin','slack','email','imessage'])
+export function createDiagnostics({max=30,now=Date.now}={}){
+ let rows=[];const references=new Map()
+ return {
+  record(event){
+   let channel=channels.has(event.channel)?event.channel:'auto'
+   const id=references.get(event.artifactId)||event.id||event.artifactId
+   if(typeof id!=='string'||!/^[\w-]{1,80}$/.test(id))return
+   if(event.artifactId&&/^[\w-]{1,80}$/.test(event.artifactId))references.set(event.artifactId,id)
+   const old=rows.find(r=>r.id===id),state=states.has(event.state)?event.state:'failed'
+   if(channel==='auto'&&old)channel=old.channel
+   const reason=['failed','unknown','cancelled'].includes(state)?failureReason({code:event.code||state,name:state==='cancelled'?'AbortError':''},event.stage):null
+   const row={id,at:now(),channel,state,stage:event.stage==='synthesis'?'synthesis':'delivery',reason:reason||null}
+   if(old)rows=rows.map(r=>r===old?row:r);else rows.unshift(row)
+   rows=rows.slice(0,max)
+   if(references.size>max*2){const live=new Set(rows.map(r=>r.id));for(const[k,v]of references)if(!live.has(v))references.delete(k)}
+  },
+  snapshot:()=>rows.map(r=>({...r,reason:r.reason?{...r.reason}:null})),
+ }
+}