dsh-speak 1.4.0 → 1.7.0

package/client/client.js

@@ -0,0 +1,304 @@
+// client.js — dsh-speak browser half: per-message Speak/Stop/Replay button,
+// speech-state WebSocket, and the native dsh-speak settings page.
+// ==============================================================================
+// Merged bundle (1.7.0): victorwads' PR #2 UI (message action + Settings page,
+// styled with @deepseek-ai/dsh-client-ui-primitives) plus the dsh-speak-specific
+// options (master switch, optional event announcements, editable fixed prompt,
+// queue-all-messages mode). All UI copy is bilingual (zh/en) via the DSH locale
+// service; the settings page entry is "dsh-speak 设置 / dsh-speak settings".
+//
+// Host contract (adapters/dsh/speech-hook.js):
+//   * /dsh-speak/control  — POST { action: 'play'|'stop'|'status', ... }
+//   * /dsh-speak/ws       — WebSocket publishing { type: 'speech-state', ... }
+//   * settings namespace 'dsh-speak' (installSettingsSection)
+//
+// The bundle is deliberately hand-written (no build step) and only uses
+// platform seed modules + official primitives (bundle-purity gate).
+'use strict'
+
+window.__ModuleLoader__.load({
+  id: 'dsh-speak',
+  factory: require => {
+    const module = { exports: {} }
+    const React = require('react')
+    const { Button, DisclosureRow, IconPauseOutline16, Input } = require('@deepseek-ai/dsh-client-ui-primitives')
+    const CONTROL_PATH = '/dsh-speak/control'
+    const SOCKET_PATH = '/dsh-speak/ws'
+    const SETTINGS_NAMESPACE = 'dsh-speak'
+
+    // ---- locale copy (zh / en) -------------------------------------------
+    const NS = 'dsh-speak'
+    const zh = {
+      nav: 'dsh-speak 设置',
+      settingsAria: 'dsh-speak 设置',
+      settingsIntro: '自动播报与逐条重播的语音偏好。',
+      settingsTitle: 'dsh-speak',
+      actionSpeakTurn: '播报此回合',
+      actionStop: '停止播报',
+      toggleOn: '开',
+      toggleOff: '关',
+      masterSwitch: '总开关',
+      masterSwitchHint: '临时开启或关闭所有播报。',
+      automaticSpeech: '自动朗读',
+      automaticSpeechHint: '朗读最终回复。手动重播始终可用。',
+      replayFullRead: '重播完整朗读',
+      replayFullReadHint: '手动重播时跳过超长文本的标题截断，完整朗读。',
+      queueAllMessages: '入队所有消息',
+      queueAllMessagesHint: '每一条 assistant 消息到达即入队朗读（中间消息也读，FIFO），而不只读最终回复。',
+      cleanMarkdown: '清理 Markdown',
+      cleanMarkdownHint: '把 Markdown 转成自然的语音文本。',
+      markdownCleaning: 'Markdown 清理',
+      readInlineCode: '朗读行内代码',
+      readInlineCodeHint: '朗读行内代码（去掉反引号标记）。',
+      codeBlocks: '代码块',
+      codeBlocksHint: '围栏代码块如何朗读。',
+      codeBlocksAll: '全部朗读',
+      codeBlocksSmart: '智能',
+      codeBlocksReplace: '全部替换',
+      codeBlockMaxChars: '代码块最大字数',
+      codeBlockMaxCharsHint: '仅用于智能模式。',
+      codeBlockReplacementText: '代码块替换文本',
+      codeBlockReplacementTextHint: '代码块被替换时朗读的文本。',
+      maxChars: '最大朗读字数',
+      maxCharsHint: 'macOS 上 0 = 不限；Windows 保留安全默认值。',
+      longTextBehavior: '超长文本行为',
+      longTextBehaviorHint: '超过正数上限时如何处理。',
+      longTextMessageOption: '朗读替换提示语',
+      longTextHeadingOption: '朗读最大标题',
+      fixedPrompt: '固定提示语',
+      fixedPromptHint: '超长文本（message 模式）时朗读的提示语。',
+      announceApprovals: '播报审批',
+      announceApprovalsHint: '朗读审批请求。',
+      announceQuestions: '播报提问',
+      announceQuestionsHint: '朗读 ask_user_question 问题。',
+      questionGap: '问题间隔（毫秒）',
+      questionGapHint: '多个问题播报之间的停顿。',
+      optionalEvents: '可选事件播报',
+      turnEnd: '回合结束',
+      turnEndHint: '一轮对话结束时播报。',
+      commandDone: '命令完成',
+      commandDoneHint: '命令完成或失败时播报。',
+      goalChange: '目标变更',
+      goalChangeHint: '目标创建/更新/完成时播报。',
+      toolErrors: '工具出错',
+      toolErrorsHint: '工具调用失败时播报错误摘要。',
+      todoWrite: '待办更新',
+      todoWriteHint: 'agent 更新待办列表时播报。',
+    }
+    const en = {
+      nav: 'dsh-speak settings',
+      settingsAria: 'dsh-speak settings',
+      settingsIntro: 'Speech preferences for automatic announcements and per-message replay.',
+      settingsTitle: 'dsh-speak',
+      actionSpeakTurn: 'Speak turn',
+      actionStop: 'Stop speaking',
+      toggleOn: 'On',
+      toggleOff: 'Off',
+      masterSwitch: 'Master Switch',
+      masterSwitchHint: 'Temporarily enable or disable all announcements.',
+      automaticSpeech: 'Automatic Speech',
+      automaticSpeechHint: 'Speaks final assistant responses. Manual replay always remains available.',
+      replayFullRead: 'Full Read on Replay',
+      replayFullReadHint: 'When replaying, read the full text instead of the heading fallback.',
+      queueAllMessages: 'Queue All Messages',
+      queueAllMessagesHint: 'Also speaks intermediate assistant messages in a FIFO queue, not only the final reply.',
+      cleanMarkdown: 'Clean Markdown Formatting',
+      cleanMarkdownHint: 'Converts Markdown into natural speech text.',
+      markdownCleaning: 'Markdown cleaning',
+      readInlineCode: 'Read Inline Code',
+      readInlineCodeHint: 'Reads inline code without backtick markers.',
+      codeBlocks: 'Code Blocks',
+      codeBlocksHint: 'Choose how fenced code blocks are spoken.',
+      codeBlocksAll: 'Read all',
+      codeBlocksSmart: 'Smart',
+      codeBlocksReplace: 'Replace all',
+      codeBlockMaxChars: 'Code Block Max Characters',
+      codeBlockMaxCharsHint: 'Only used by Smart code blocks.',
+      codeBlockReplacementText: 'Code Block Replacement Text',
+      codeBlockReplacementTextHint: 'Used when a code block is replaced.',
+      maxChars: 'Max Speech Characters',
+      maxCharsHint: '0 is unlimited on macOS; Windows keeps its safe default.',
+      longTextBehavior: 'Long Text Behavior',
+      longTextBehaviorHint: 'When a positive maximum is exceeded.',
+      longTextMessageOption: 'Read replacement message',
+      longTextHeadingOption: 'Read largest heading',
+      fixedPrompt: 'Fixed Prompt',
+      fixedPromptHint: 'The prompt spoken when the text is too long (message mode).',
+      announceApprovals: 'Announce Approvals',
+      announceApprovalsHint: 'Announces approval requests.',
+      announceQuestions: 'Announce Questions',
+      announceQuestionsHint: 'Announces ask-user questions.',
+      questionGap: 'Question Gap (ms)',
+      questionGapHint: 'Pause between multiple question announcements.',
+      optionalEvents: 'Optional event announcements',
+      turnEnd: 'Turn End',
+      turnEndHint: 'Announces when a round of conversation ends.',
+      commandDone: 'Command Done',
+      commandDoneHint: 'Announces when a command finishes or fails.',
+      goalChange: 'Goal Change',
+      goalChangeHint: 'Announces goal created/updated/completed.',
+      toolErrors: 'Tool Errors',
+      toolErrorsHint: 'Announces an error summary when a tool call fails.',
+      todoWrite: 'Todo Write',
+      todoWriteHint: 'Announces when the agent updates its todos.',
+    }
+
+    module.exports.inject = ['slots', 'timer', 'settingsScope', 'locale']
+    module.exports.apply = function apply(ctx) {
+      ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-speak: dictionaries')
+      const t = ctx.locale.bind(NS)
+
+      let speechState = { speaking: false, sessionId: null, turn: null, messageId: null, source: null, queueLength: 0 }
+      const listeners = new Set()
+      const settings = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE })
+      const e = React.createElement
+      function IconVolume2({ size = 20, className }) {
+        return e('svg', { width: size, height: size, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round', className, 'aria-hidden': 'true' },
+          e('path', { d: 'M11 4.702a.705.705 0 0 0-1.203-.498L6.413 7.587A1.4 1.4 0 0 1 5.416 8H3a1 1 0 0 0-1 1v6a1 1 0 0 0 1 1h2.416a1.4 1.4 0 0 1 .997.413l3.383 3.384A.705.705 0 0 0 11 19.298z' }),
+          e('path', { d: 'M16 9a5 5 0 0 1 0 6' }), e('path', { d: 'M19.364 18.364a9 9 0 0 0 0-12.728' }),
+        )
+      }
+      function publish(next) {
+        speechState = next && typeof next === 'object' ? next : { speaking: false, sessionId: null, turn: null, messageId: null, source: null, queueLength: 0 }
+        for (const listener of listeners) listener()
+      }
+      async function control(payload) {
+        const response = await fetch(CONTROL_PATH, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) })
+        if (!response.ok) throw new Error(`dsh-speak control failed (${response.status})`)
+        const state = await response.json()
+        if (state && state.type === 'speech-state') publish(state)
+        return state
+      }
+      ctx.effect(() => {
+        let socket = null
+        let retry = null
+        let disposed = false
+        const connect = () => {
+          if (disposed) return
+          const scheme = location.protocol === 'https:' ? 'wss:' : 'ws:'
+          socket = new WebSocket(`${scheme}//${location.host}${SOCKET_PATH}`)
+          socket.onmessage = event => {
+            try {
+              const state = JSON.parse(event.data)
+              if (state && state.type === 'speech-state') publish(state)
+            } catch (e) { console.warn('[dsh-speak] ignored invalid speech websocket state') }
+          }
+          socket.onclose = () => {
+            if (!disposed) retry = ctx.timeout(connect, 1000)
+          }
+          socket.onerror = () => { try { socket.close() } catch (e) { /* closed */ } }
+        }
+        connect()
+        return () => {
+          disposed = true
+          if (retry) retry()
+          try { if (socket) socket.close() } catch (e) { /* closed */ }
+        }
+      }, 'dsh-speak speech state websocket')
+      function useSpeechState() {
+        const [snapshot, setSnapshot] = React.useState(speechState)
+        React.useEffect(() => { const update = () => setSnapshot(speechState); listeners.add(update); return () => listeners.delete(update) }, [])
+        return snapshot
+      }
+      function visibleText(node) {
+        return Array.isArray(node && node.blocks) ? node.blocks.filter(block => block && block.kind === 'text' && typeof block.text === 'string').map(block => block.text).join('') : ''
+      }
+      function SpeakAction(props) {
+        const messageId = props.messageId == null ? null : String(props.messageId)
+        const turnData = props.useSession(snapshot => {
+          // DSH 会话投影：snapshot.chat.nodes 是按 key 索引的 Map，value 为
+          // { key, kind, data, location }。最终 assistant 消息内容在节点的
+          // data.finalNode（assistant 节点）或 data.closing.finalNode
+          // （turn-tail 节点）里，含 messageId / turn / seq / blocks。
+          const nodes = snapshot && snapshot.chat && snapshot.chat.nodes
+          if (!nodes || typeof nodes.values !== 'function') return { turn: null, text: '' }
+          const all = [...nodes.values()]
+          const finalOf = node => {
+            const d = node && node.data
+            if (!d) return null
+            if (d.finalNode) return d.finalNode
+            if (d.closing && d.closing.finalNode) return d.closing.finalNode
+            return d.kind === 'assistant' ? d : null
+          }
+          const entries = all.map(node => ({ final: finalOf(node) }))
+          const addressed = entries.find(entry => entry.final && String(entry.final.messageId) === messageId)
+          if (!addressed || !Number.isFinite(addressed.final.turn)) return { turn: null, text: '' }
+          const turn = addressed.final.turn
+          // 只重播点击的那条消息（assistant-actions 只渲染在回合尾部 = 最终回复），
+          // 不合并整个回合的所有中间消息
+          const text = visibleText(addressed.final)
+          return { turn, text }
+        })
+        const active = useSpeechState()
+        const speaking = active.speaking && String(active.sessionId) === String(props.sessionId) && active.turn === turnData.turn
+        const [pending, setPending] = React.useState(false)
+        const label = speaking ? t('actionStop') : t('actionSpeakTurn')
+        return e('button', {
+          type: 'button', className: 'dsh-speak-message-action', 'aria-label': label, 'aria-pressed': speaking,
+          'data-speaking': speaking || undefined, title: label, disabled: pending || !turnData.text.trim(),
+          onClick: () => {
+            if (pending) return
+            setPending(true)
+            const action = speaking ? 'stop' : 'play'
+            const payload = speaking ? { action } : { action, sessionId: props.sessionId, turn: turnData.turn, messageId, text: turnData.text }
+            void control(payload).catch(console.error).finally(() => setPending(false))
+          },
+        }, speaking ? e(IconPauseOutline16) : e(IconVolume2))
+      }
+      function useSettings() {
+        const [snapshot, setSnapshot] = React.useState(settings.getSnapshot())
+        React.useEffect(() => settings.subscribe(() => setSnapshot(settings.getSnapshot())), [])
+        return snapshot
+      }
+      function Field({ label, hint, children, inline }) {
+        return e('div', { className: 'dsh-speak-field' }, inline ? e('div', { className: 'dsh-speak-inline-field' }, e('div', { className: 'dsh-speak-field-label' }, label), children) : e('div', { className: 'dsh-speak-field-label' }, label), inline ? null : children, e('p', { className: 'dsh-speak-field-hint' }, hint))
+      }
+      function Toggle({ label, value, disabled, onChange, hint }) { return e(Field, { label: `${label}:`, hint, inline: true }, e('div', { className: 'dsh-speak-option-row' }, e(Button, { variant: 'outline', size: 'sm', disabled, 'aria-pressed': value, onClick: () => onChange(!value) }, value ? t('toggleOn') : t('toggleOff')))) }
+      function SettingInput({ label, value, disabled, numeric, onChange, hint }) { const id = `dsh-speak-${label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`; return e(Field, { label: `${label}:`, hint }, e('div', { className: 'dsh-speak-input-row' }, e(Input, { id, value: String(value), disabled, inputMode: numeric ? 'numeric' : undefined, onChange: event => onChange(event.target.value) }))) }
+      function Options({ label, value, disabled, onChange, hint, options }) { return e(Field, { label, hint }, e('div', { className: 'dsh-speak-option-row' }, ...options.map(option => e(Button, { key: option.value, variant: value === option.value ? 'primary' : 'outline', size: 'sm', disabled, 'aria-pressed': value === option.value, onClick: () => onChange(option.value) }, option.label)))) }
+      function MarkdownCleaning({ value, clean, disabled, set }) {
+        const [open, setOpen] = React.useState(true); const controlsDisabled = disabled || !clean
+        return e(DisclosureRow, { icon: null, title: t('markdownCleaning'), open, expandable: true, onToggle: () => setOpen(!open), expandOnRowClick: true }, e('div', { style: { paddingLeft: '22px' } },
+          e(Toggle, { label: t('readInlineCode'), value: value.readInlineCode !== false, disabled: controlsDisabled, onChange: next => set('readInlineCode', next), hint: t('readInlineCodeHint') }),
+          e(Options, { label: t('codeBlocks'), value: value.codeBlocks || 'smart', disabled: controlsDisabled, onChange: next => set('codeBlocks', next), hint: t('codeBlocksHint'), options: [{ value: 'all', label: t('codeBlocksAll') }, { value: 'smart', label: t('codeBlocksSmart') }, { value: 'replace', label: t('codeBlocksReplace') }] }),
+          e(SettingInput, { label: t('codeBlockMaxChars'), value: value.codeBlockMaxChars == null ? 300 : value.codeBlockMaxChars, numeric: true, disabled: controlsDisabled || value.codeBlocks !== 'smart', onChange: next => { if (/^\d+$/.test(next)) set('codeBlockMaxChars', Number(next)) }, hint: t('codeBlockMaxCharsHint') }),
+          e(SettingInput, { label: t('codeBlockReplacementText'), value: value.codeBlockReplacementText || 'You can see the code in our history.', disabled: controlsDisabled || value.codeBlocks === 'all', onChange: next => set('codeBlockReplacementText', next), hint: t('codeBlockReplacementTextHint') }),
+        ))
+      }
+      function SettingsCard() {
+        // hooks must run unconditionally (before the ready-guard return)
+        const [eventsOpen, setEventsOpen] = React.useState(false)
+        const snapshot = useSettings(); if (snapshot.status !== 'ready' || !snapshot.value) return null
+        const value = snapshot.value; const disabled = !snapshot.writable; const clean = value.cleanMarkdownFormatting !== false; const set = (field, next) => { void settings.set(field, next).catch(console.error) }
+        return e('section', { 'aria-label': t('settingsAria') }, e('h3', null, t('settingsTitle')), e('p', null, t('settingsIntro')),
+          e(Toggle, { label: t('masterSwitch'), value: value.enabled !== false, disabled, onChange: next => set('enabled', next), hint: t('masterSwitchHint') }),
+          e(Toggle, { label: t('automaticSpeech'), value: value.automaticSpeech !== false, disabled, onChange: next => set('automaticSpeech', next), hint: t('automaticSpeechHint') }),
+          e(Toggle, { label: t('replayFullRead'), value: value.replayFullRead === true, disabled, onChange: next => set('replayFullRead', next), hint: t('replayFullReadHint') }),
+          e(Toggle, { label: t('queueAllMessages'), value: value.queueAllMessages === true, disabled: disabled || value.automaticSpeech === false, onChange: next => set('queueAllMessages', next), hint: t('queueAllMessagesHint') }),
+          e(Toggle, { label: t('cleanMarkdown'), value: clean, disabled, onChange: next => set('cleanMarkdownFormatting', next), hint: t('cleanMarkdownHint') }), e(MarkdownCleaning, { value, clean, disabled, set }),
+          e(SettingInput, { label: t('maxChars'), value: value.maxChars == null ? 0 : value.maxChars, numeric: true, disabled, onChange: next => { if (/^\d+$/.test(next)) set('maxChars', Number(next)) }, hint: t('maxCharsHint') }),
+          e(Options, { label: t('longTextBehavior'), value: value.longTextMode || 'message', disabled, onChange: next => set('longTextMode', next), hint: t('longTextBehaviorHint'), options: [{ value: 'message', label: t('longTextMessageOption') }, { value: 'heading', label: t('longTextHeadingOption') }] }),
+          e(SettingInput, { label: t('fixedPrompt'), value: value.longTextMessage || '本次播报内容较长，请自行阅读。', disabled: disabled || value.longTextMode !== 'message', onChange: next => set('longTextMessage', next), hint: t('fixedPromptHint') }),
+          e(Toggle, { label: t('announceApprovals'), value: value.announceApprovals !== false, disabled, onChange: next => set('announceApprovals', next), hint: t('announceApprovalsHint') }),
+          e(Toggle, { label: t('announceQuestions'), value: value.announceQuestions !== false, disabled, onChange: next => set('announceQuestions', next), hint: t('announceQuestionsHint') }),
+          e(SettingInput, { label: t('questionGap'), value: value.questionGapMs == null ? 2000 : value.questionGapMs, numeric: true, disabled: disabled || value.announceQuestions === false, onChange: next => { if (/^\d+$/.test(next)) set('questionGapMs', Number(next)) }, hint: t('questionGapHint') }),
+          e(DisclosureRow, { icon: null, title: t('optionalEvents'), open: eventsOpen, expandable: true, onToggle: () => setEventsOpen(!eventsOpen), expandOnRowClick: true }, e('div', { style: { paddingLeft: '22px' } },
+            e(Toggle, { label: t('turnEnd'), value: value.announceTurnEnd === true, disabled, onChange: next => set('announceTurnEnd', next), hint: t('turnEndHint') }),
+            e(Toggle, { label: t('commandDone'), value: value.announceCommandDone === true, disabled, onChange: next => set('announceCommandDone', next), hint: t('commandDoneHint') }),
+            e(Toggle, { label: t('goalChange'), value: value.announceGoalChange === true, disabled, onChange: next => set('announceGoalChange', next), hint: t('goalChangeHint') }),
+            e(Toggle, { label: t('toolErrors'), value: value.announceToolErrors === true, disabled, onChange: next => set('announceToolErrors', next), hint: t('toolErrorsHint') }),
+            e(Toggle, { label: t('todoWrite'), value: value.announceTodoWrite === true, disabled, onChange: next => set('announceTodoWrite', next), hint: t('todoWriteHint') }),
+          )),
+        )
+      }
+      ctx.effect(() => {
+        const style = document.createElement('style'); style.dataset.plugin = 'dsh-speak'
+        style.textContent = '.dsh-speak-message-action{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;padding:5px;border:0;border-radius:28px;background:transparent;color:var(--dsw-alias-label-tertiary);cursor:pointer;font:inherit;font-size:14px;line-height:1}.dsh-speak-message-action:hover{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-secondary)}.dsh-speak-message-action[data-speaking]{color:var(--dsw-alias-label-primary)}.dsh-speak-message-action:disabled{cursor:default;opacity:.4}.dsh-speak-field{display:flex;flex-direction:column;gap:8px;margin:0 0 20px}.dsh-speak-field-label{font-weight:600;color:var(--dsw-alias-label-primary)}.dsh-speak-inline-field{display:flex;align-items:center;gap:8px;flex-wrap:wrap}.dsh-speak-inline-field>.dsh-speak-field-label{flex:none}.dsh-speak-field-hint{margin:0;color:var(--dsw-alias-label-tertiary)}.dsh-speak-field+.dsh-speak-field{margin-top:20px}.dsh-speak-option-row{display:inline-flex;align-items:center;gap:8px;width:max-content;max-width:100%}.dsh-speak-input-row{display:flex;max-width:100%}.dsh-speak-input-row>span{max-width:100%}'
+        document.head.appendChild(style); return () => style.remove()
+      }, 'dsh-speak message action styles')
+      ctx.slots.inject('conversation.chat.assistant-actions', () => ctx.slots.register({ name: 'conversation.chat.assistant-actions', id: 'speak', order: 5, label: 'Speak', locale: NS }, SpeakAction))
+      ctx.slots.inject('settings.section', () => ctx.slots.register({ name: 'settings.section', id: 'speak', order: 25, label: () => t('nav'), locale: NS }, SettingsCard))
+    }
+    return module.exports
+  },
+})

package/docs/DESIGN.md

@@ -2,9 +2,8 @@
 
 English · [中文](DESIGN.zh-CN.md)
 
-Status: **draft** — this document describes the current (proven) local implementation
-and the target generic structure of this repository. It is the reference for the
-README.
+Status: **maintained** — this document describes the current implementation and
+repository structure. It is the reference for the README.
 
 ---
 
@@ -36,12 +35,12 @@ Goals:
 
 Non-goals (for now):
 
-- Both engines — Windows `speak.ps1` and macOS `speak.sh` (built-in `say`) — are
-  **officially supported** (macOS ships in the npm package since 1.2.0).
-  Linux/headless TTS is not supported.
+- Linux/headless TTS is not supported (Windows uses `speak.ps1` + SAPI5; macOS
+  uses `speak.sh` + the built-in `say`, shipped in the npm package since 1.2.0).
 - In-repo packaging of NaturalVoiceSAPIAdapter (Windows 10 only) or voice data —
   they are prerequisites, not bundled.
-- Streaming/queued playback, per-voice audio files, non-Chinese voice curation.
+- Per-voice audio files, non-Chinese voice curation (the speech **playback
+  queue** is already implemented in 1.7.0 — see §3.2's host FIFO queue).
 
 ## 3. Architecture
 
@@ -115,15 +114,38 @@ no "reply finished" hook, so the plugin observes the session event stream:
 - listens to `session/event`;
 - filters `assistant/message` events with `surfaceOp == 'append'`;
 - extracts only `text` content blocks (reasoning / tool_use blocks are skipped);
-- buffers the text and starts a throttle timer (default 1500 ms) to merge
-  multi-step messages of one reply;
-- a `tool/call` event **cancels** the pending announcement — that round's assistant
-  text is process narration, not the final reply;
-- on fire: writes the text to a temp file and `spawn`s
-  `powershell.exe -File <engine> -File <tmp>` with `windowsHide` + `stdio: 'ignore'`
-  so the harness is never blocked; the temp file is deleted on exit.
-
-Registration snippet (also automated by `install.ps1`):
+- default mode: buffers the text and starts a throttle timer (default 1500 ms) to
+  merge multi-step messages of one reply; a `tool/call` event **cancels** the
+  pending announcement (that round's assistant text is process narration), but
+  **`turn/end` fallback-announces the final reply** (tool-calling replies are
+  still heard);
+- **host speech queue** (1.7.0, from PR #2): every announcement (final reply,
+  approvals, questions, optional events, manual replay) goes through a FIFO
+  queue — only one native speech process runs at a time, queued items continue
+  automatically. A `/dsh-speak/control` POST route (play/stop/status) and a
+  `/dsh-speak/ws` WebSocket broadcast the authoritative speech state (which
+  message is speaking, queue length).
+- **Final-reply replay** (1.7.0): the 🔊 button in the turn-tail (final reply)
+  action bar calls the control route to replay **that final message**; speech
+  execution stays fully owned by the host (keeps speaking even with the browser
+  closed).
+- **`queueAllMessages` switch** (1.7.0, default off): off = throttled final
+  reply + optional events (as before); on = every assistant message is enqueued
+  immediately (intermediate messages spoken too).
+- **Optional event announcements** (1.6.0, all off by default): `turn/end`,
+  `command/done`, `goal/change`, `tool/result` (on error), and `todo/write` each
+  have an independent toggle and announce a fixed phrase on fire (see §5).
+- **Settings namespace registration** (1.6.0): one timer tick after apply the
+  plugin calls `installSettingsSection(ctx, 'dsh-speak', schema, patchConfig,
+  hooks)`, resolving config as schema default → patch `config` → UI user layer.
+  `onChange` re-derives `cfg` from a saved `settingsSource()` thunk (note:
+  `installSettingsSection` only calls `setSource` on attach/detach, so changes
+  must be re-read in `onChange`). On hosts without a settings service (dsh <
+  0.1.0-rc.7 or no provider mounted) the registration is skipped silently and
+  the plugin works purely from the patch config — backward compatible.
+
+Registration snippet (also automated by `install.ps1`; npm installs use the bare
+package name `'dsh-speak'` — this is the file-install path):
 
 ```yaml
 # ~/.dsh/profiles/web/cordis.patch.yml
@@ -136,6 +158,32 @@ Registration snippet (also automated by `install.ps1`):
 > Node's ESM loader does not accept Windows absolute paths as plugin names — the
 > `file:///C:/...` URL form is required.
 
+### 3.4 DSH browser half — `client/client.js`
+
+A DSH client bundle (`window.__ModuleLoader__.load({ id: 'dsh-speak', factory })`)
+that registers two pieces of UI:
+
+- **Turn-tail Speak button** (1.7.0, from PR #2): registered into the
+  `conversation.chat.assistant-actions` slot (the turn's final-reply action bar).
+  Clicking 🔊 POSTs to `/dsh-speak/control` to replay that final message; clicking
+  again stops; clicking another switches. The button's speaking/paused state is
+  derived from the authoritative host state over the `/dsh-speak/ws` WebSocket
+  (matched by session + turn identity).
+- **Settings → dsh-speak settings page** (1.7.0): registered into the
+  `settings.section` slot, drawn with `@deepseek-ai/dsh-client-ui-primitives`
+  (Button / DisclosureRow / Input; Toggle / Options / SettingInput helpers). Every
+  option (master switch, automatic speech, queueAllMessages, Markdown cleaning,
+  code blocks, maxChars, longTextMode, fixed prompt, approvals/questions, the five
+  optional events) is read/written through `settingsScope.bind({ namespace:
+  'dsh-speak' })`.
+
+- The package declares its browser half via `package.json`
+  `dsh.client: { platform: 'web' }` + `exports['./client']`; DSH's client-modules
+  scanner picks it up and loads it automatically.
+- **Deliberately handwritten, zero build**: it only uses platform seed modules
+  and official primitives (the bundle-purity gate allows primitives but forbids
+  importing official package internals), matching the built bundles' contract.
+
 ### 3.3 Claude Code adapter — `adapters/claude-code/stop-hook.ps1`
 
 Claude Code *does* have a Stop hook. The hook JSON (with `transcript_path`) arrives
@@ -150,11 +198,18 @@ returns immediately. (Async spawning is safe here — the nested-spawn restricti
 | assistant round / event          | announced? |
 | -------------------------------- | ----------- |
 | final text reply, no tool call   | ✅ after throttle |
-| text + tool/call(s)              | ❌ (cancelled — narration) |
-| text + `ask_user_question` call  | ✅ the question text is kept and announced |
+| text + tool/call(s)              | 🟡 throttle cancelled (intermediate); **fallback-announced at turn end** |
+| text + `ask_user_question` call  | ✅ each question announced separately: "问题N" prefix (when several) + "选项N" numbering, `questionGapMs` pause between questions |
 | `approval/asked`                 | ✅ immediately (reason, else a fixed prompt) |
 | reasoning only, no text          | ❌ (no text block) |
 | streaming chunks                 | ❌ (filtered) |
+| `turn/end`                       | 🟡 off by default; announces "第 N 轮对话完成/中断/异常结束" |
+| `command/done`                   | 🟡 off by default; announces "命令执行完成/失败" |
+| `goal/change`                    | 🟡 off by default; announces "已创建目标/目标已完成…" (head) |
+| `tool/result`                    | 🟡 off by default; announces "工具调用出错" only when `error` or an `isError` content block is present (English details / technical codes are dropped, Chinese details kept) |
+| `todo/write`                     | 🟡 off by default; announces "待办已更新：n/m 完成" |
+| `assistant/message` (queueAllMessages on) | ✅ every message enqueued immediately (intermediate spoken too) |
+| manual replay (per-message 🔊)   | ✅ clear queue → stop current → speak that turn |
 
 ## 5. Configuration reference
 
@@ -166,15 +221,53 @@ returns immediately. (Async spawning is safe here — the nested-spawn restricti
 | `-File`           | `''`                        | UTF-8 file to read                       |
 | `-Volume`         | `50`                        | 0–100                                    |
 | `-Rate`           | `1`                         | speech rate (SAPI scale)                 |
-| `-MaxChars`       | `300`                       | beyond this, replaced by `LongTextMessage` |
+| `-MaxChars`       | platform                    | beyond this, replaced by `LongTextMessage` (macOS default 0 = unlimited) |
 | `-LongTextMessage`| `本次播报内容较长，请自行阅读。` | spoken instead of over-long text         |
+| `-LongTextMode`   | `message`                    | `message` (fixed prompt) \| `heading` (speak the largest markdown heading) |
+| `-CleanMarkdownFormatting` | `true`               | convert Markdown to natural speech (link labels kept, URLs stripped) |
+| `-ReadInlineCode` | `true`                       | read inline code without backtick markers |
+| `-CodeBlocks`     | `smart`                      | `all` \| `smart` \| `replace` (fenced code blocks) |
+| `-CodeBlockMaxChars` | `300`                    | smart-mode code block character limit |
+| `-CodeBlockReplacementText` | `You can see the code in our history.` | spoken in replace mode |
+
+### DSH plugin (profile `config`; since 1.7.0 also editable in the Settings → dsh-speak settings page)
+
+```yaml
+config:
+  enabled: true                # master switch
+  automaticSpeech: true        # auto-speak final replies
+  queueAllMessages: false      # true = enqueue every assistant message
+  replayFullRead: false        # true = manual replay skips the long-text truncation
+  cleanMarkdownFormatting: true
+  readInlineCode: true
+  codeBlocks: smart            # all | smart | replace
+  codeBlockMaxChars: 300
+  codeBlockReplacementText: 'You can see the code in our history.'
+  throttleMs: 1500
+  engine: ''                   # '' = auto-resolve
+  announceApprovals: true
+  announceQuestions: true
+  stripApprovalPrefix: true
+  questionGapMs: 2000          # pause between multiple question announcements (ms)
+  longTextMode: message        # message | heading
+  longTextMessage: '本次播报内容较长，请自行阅读。'
+  maxChars: 300                # macOS default 0 = unlimited
+  volume: 50                   # Windows only
+  rate: 0                      # 0 = engine default
+  # —— optional event announcements (off by default) ——
+  announceTurnEnd: false     # turn/end
+  announceCommandDone: false # command/done
+  announceGoalChange: false  # goal/change
+  announceToolErrors: false  # tool/result with error or isError block
+  announceTodoWrite: false   # todo/write
+```
 
-### DSH plugin (environment variables)
+Resolution order: schema default → patch `config` (base) → UI user layer. The
+browser dsh-speak settings page (`client/client.js`) and the patch YAML read/write
+the same settings document. Platform note: `maxChars` defaults to 0 on macOS
+(`say` has no ceiling) and 300 on Windows (SAPI safe limit).
 
-| var                  | default                                  | meaning                        |
-| -------------------- | ---------------------------------------- | ------------------------------ |
-| `DSH_SPEAK_ENGINE`   | empty (auto-resolved)                    | engine path override; otherwise resolved as `<package>/engine/<platform script>` → `~/.dsh/hooks/<platform script>` (Windows: `speak.ps1`, macOS: `speak.sh`) |
-| `DSH_SPEAK_THROTTLE_MS` | `1500`                                | merge delay before announcing  |
+Full configuration guide: the README's Configuration section.
 
 ## 6. Pitfalls (hard-won; do not "fix" casually)
 
@@ -203,11 +296,10 @@ by the agent) are the three reference patterns.
 
 ## 8. Scope
 
-This project is intentionally **not** a living product. It documents one proven way
-to give a harness a voice: a small engine + the two adapter patterns (event-stream
-and stop-hook) that worked. If you need more (voice management UI, more backends,
-cross-platform), treat the engine as the seam and build on top — this repository
-stays as a minimal, self-contained reference implementation.
+This repository stays **small and self-contained**: a small engine plus the two
+adapter patterns (event-stream and stop-hook), and it is **actively maintained**.
+If you need more (voice management UI, more backends, cross-platform), treat the
+engine as the seam and build on top.
 
 ## 9. Publishing as an npm plugin (appendix)
 
@@ -227,7 +319,7 @@ dependencies in the profile). This repository is prepared for that path:
 
 `speech-hook.js` locates `engine/speak.ps1` in this order:
 
-1. `DSH_SPEAK_ENGINE` environment override;
+1. `config.engine` override;
 2. `<package>/engine/speak.ps1` resolved relative to the plugin file — covers
    both a repo checkout and `node_modules/dsh-speak/` after `npm install`;
 3. legacy `%USERPROFILE%\.dsh\hooks\speak.ps1` (the file-install location).