dsh-speak 1.0.0 → 1.2.0

package/engine/speak.ps1

@@ -1,76 +1,76 @@
-# speak.ps1 — Harness-agnostic speech engine (Windows SAPI5 + NaturalVoiceSAPIAdapter)
-# ====================================================================================
-# Reads text (inline or from a UTF-8 file), cleans it for speech synthesis, and reads
-# it aloud through Windows SAPI5, preferring natural voices registered by
-# NaturalVoiceSAPIAdapter (https://github.com/gexgd0419/NaturalVoiceSAPIAdapter).
-#
-# This script knows NOTHING about any harness (DSH, Claude Code, ...). Any process
-# can call it:
-#
-#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speak.ps1 -Text "hello"
-#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speak.ps1 -File C:\tmp\msg.txt
-#
-# It is best-effort by design: it never throws, never blocks the caller for longer
-# than the utterance itself, and exits 0 even if something failed.
-#
-# Design notes (see docs/DESIGN.md for full rationale):
-#   * Markdown symbols, URLs and emoji are stripped before speaking — SAPI5 Speak()
-#     silently fails (produces no audio, no error) when it hits emoji/surrogates.
-#   * NaturalVoiceSAPIAdapter has a per-Speak character ceiling (~375-470 chars);
-#     beyond that it silently speaks nothing. Text longer than $MaxChars is replaced
-#     with $LongTextMessage instead.
-#   * Adapter-registered voices often have plain names ("Microsoft Xiaoxiao") that do
-#     not contain the word "Natural", so matching checks Name + Description.
-# ====================================================================================
-
-param(
-    [string]$Text = '',
-    [string]$File = '',
-    [int]$Volume = 50,
-    [int]$Rate = 1,
-    [int]$MaxChars = 300,
-    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。'
-)
-
-# ---------- input: pick text source ----------
-if ($File) {
-    if (-not (Test-Path $File)) { exit 0 }
-    $text = [System.IO.File]::ReadAllText($File, [System.Text.Encoding]::UTF8)
-} else {
-    $text = [string]$Text
-}
-if (-not $text -or -not $text.Trim()) { exit 0 }
-
-# ---------- clean: markdown -> plain speech text ----------
-# code blocks, inline code, markdown links, bare URLs, emphasis/marker chars
-$text = $text -replace '```[\s\S]*?```', ' '
-$text = $text -replace '`[^`]*`', ' '
-$text = $text -replace '\[([^\]]*)\]\([^\)]*\)', '$1'
-$text = $text -replace 'https?://\S+', ' '
-$text = $text -replace '[-#*_~|>+]+', ' '
-# emoji / special symbols (Speak() fails silently on them): keep CJK, CJK punct,
-# full-width ranges, ASCII printable
-$text = [regex]::Replace($text, '[^一-龥　-〿＀-￯ - -~]', '')
-$text = $text -replace '\s+', ' '
-$text = $text.Trim()
-
-# ---------- length guard: adapter per-Speak ceiling ----------
-if ($text.Length -gt $MaxChars) { $text = $LongTextMessage }
-
-# ---------- speak ----------
-Add-Type -AssemblyName System.Speech
-$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
-$synth.Volume = $Volume
-
-# prefer a zh natural voice (NaturalVoiceSAPIAdapter-registered), fall back to any zh
-$voices = $synth.GetInstalledVoices()
-$voice = $voices | Where-Object {
-    $_.VoiceInfo.Culture.Name -like 'zh*' -and
-    ($_.VoiceInfo.Name + ' ' + $_.VoiceInfo.Description) -match 'Natural|Online'
-} | Select-Object -First 1
-if (-not $voice) { $voice = $voices | Where-Object { $_.VoiceInfo.Culture.Name -like 'zh*' } | Select-Object -First 1 }
-if ($voice) { $synth.SelectVoice($voice.VoiceInfo.Name) }
-
-$synth.Rate = $Rate
-$synth.Speak($text)
-exit 0
+# speak.ps1 — Harness-agnostic speech engine (Windows SAPI5 + NaturalVoiceSAPIAdapter)
+# ====================================================================================
+# Reads text (inline or from a UTF-8 file), cleans it for speech synthesis, and reads
+# it aloud through Windows SAPI5, preferring natural voices registered by
+# NaturalVoiceSAPIAdapter (https://github.com/gexgd0419/NaturalVoiceSAPIAdapter).
+#
+# This script knows NOTHING about any harness (DSH, Claude Code, ...). Any process
+# can call it:
+#
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speak.ps1 -Text "hello"
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speak.ps1 -File C:\tmp\msg.txt
+#
+# It is best-effort by design: it never throws, never blocks the caller for longer
+# than the utterance itself, and exits 0 even if something failed.
+#
+# Design notes (see docs/DESIGN.md for full rationale):
+#   * Markdown symbols, URLs and emoji are stripped before speaking — SAPI5 Speak()
+#     silently fails (produces no audio, no error) when it hits emoji/surrogates.
+#   * NaturalVoiceSAPIAdapter has a per-Speak character ceiling (~375-470 chars);
+#     beyond that it silently speaks nothing. Text longer than $MaxChars is replaced
+#     with $LongTextMessage instead.
+#   * Adapter-registered voices often have plain names ("Microsoft Xiaoxiao") that do
+#     not contain the word "Natural", so matching checks Name + Description.
+# ====================================================================================
+
+param(
+    [string]$Text = '',
+    [string]$File = '',
+    [int]$Volume = 50,
+    [int]$Rate = 1,
+    [int]$MaxChars = 300,
+    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。'
+)
+
+# ---------- input: pick text source ----------
+if ($File) {
+    if (-not (Test-Path $File)) { exit 0 }
+    $text = [System.IO.File]::ReadAllText($File, [System.Text.Encoding]::UTF8)
+} else {
+    $text = [string]$Text
+}
+if (-not $text -or -not $text.Trim()) { exit 0 }
+
+# ---------- clean: markdown -> plain speech text ----------
+# code blocks, inline code, markdown links, bare URLs, emphasis/marker chars
+$text = $text -replace '```[\s\S]*?```', ' '
+$text = $text -replace '`[^`]*`', ' '
+$text = $text -replace '\[([^\]]*)\]\([^\)]*\)', '$1'
+$text = $text -replace 'https?://\S+', ' '
+$text = $text -replace '[-#*_~|>+]+', ' '
+# emoji / special symbols (Speak() fails silently on them): keep CJK, CJK punct,
+# full-width ranges, ASCII printable
+$text = [regex]::Replace($text, '[^一-龥　-〿＀-￯ - -~]', '')
+$text = $text -replace '\s+', ' '
+$text = $text.Trim()
+
+# ---------- length guard: adapter per-Speak ceiling ----------
+if ($text.Length -gt $MaxChars) { $text = $LongTextMessage }
+
+# ---------- speak ----------
+Add-Type -AssemblyName System.Speech
+$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
+$synth.Volume = $Volume
+
+# prefer a zh natural voice (NaturalVoiceSAPIAdapter-registered), fall back to any zh
+$voices = $synth.GetInstalledVoices()
+$voice = $voices | Where-Object {
+    $_.VoiceInfo.Culture.Name -like 'zh*' -and
+    ($_.VoiceInfo.Name + ' ' + $_.VoiceInfo.Description) -match 'Natural|Online'
+} | Select-Object -First 1
+if (-not $voice) { $voice = $voices | Where-Object { $_.VoiceInfo.Culture.Name -like 'zh*' } | Select-Object -First 1 }
+if ($voice) { $synth.SelectVoice($voice.VoiceInfo.Name) }
+
+$synth.Rate = $Rate
+$synth.Speak($text)
+exit 0

package/engine/speak.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# speak.sh — macOS speech engine (uses the built-in `say` command)
+# ==============================================================================
+# The macOS counterpart of engine/speak.ps1. Reads text (inline or UTF-8 file),
+# cleans it for speech synthesis, and reads it aloud via the system `say`
+# command. Any process can call it:
+#
+#   ./speak.sh -t "你好，构建完成"
+#   ./speak.sh -f /tmp/msg.txt -v Eddy -r 200
+#
+# Best-effort by design: never throws, exits 0 even if something failed.
+#
+# Voice selection:
+#   * no -v (default): follow the system voice — on recent macOS this is the
+#     Siri voice chosen in Settings > Siri > Voice (e.g. "声音 1"), on older
+#     versions the Spoken Content voice. This is the least surprising default.
+#   * -v <name>: force a voice by name (e.g. Eddy, Flo, Tingting — see
+#     `say -v '?'`).
+#   * NOTE: the Siri voices ("声音 1-4") are NOT exposed to `say` — they do not
+#     appear in `say -v '?'` and cannot be selected by name; they only work as
+#     the system default.
+#
+# Notes:
+#   * LC_ALL is pinned to a UTF-8 locale so the perl cleaning pipeline and bash
+#     character counting behave identically regardless of the caller's locale
+#     (a C/POSIX locale would silently strip all CJK text).
+#   * The cleaning pipeline mirrors speak.ps1 (markdown/URL/emoji stripped).
+#   * `say` has no volume flag — volume is controlled by the system output.
+#   * Length guard: text over $MAX_CHARS is replaced with $LONG_MSG.
+# ==============================================================================
+
+export LC_ALL="${LC_ALL:-en_US.UTF-8}"
+
+TEXT=""
+FILE=""
+VOICE=""
+RATE=175          # words per minute (say default)
+MAX_CHARS=300
+LONG_MSG="本次播报内容较长，请自行阅读。"
+
+usage() {
+  echo "usage: speak.sh [-t text | -f file] [-v voice] [-r wpm] [-m maxchars] [-l longmsg]" >&2
+  exit 1
+}
+
+while getopts "t:f:v:r:m:l:h" opt; do
+  case "$opt" in
+    t) TEXT="$OPTARG" ;;
+    f) FILE="$OPTARG" ;;
+    v) VOICE="$OPTARG" ;;
+    r) RATE="$OPTARG" ;;
+    m) MAX_CHARS="$OPTARG" ;;
+    l) LONG_MSG="$OPTARG" ;;
+    h) usage ;;
+    *) usage ;;
+  esac
+done
+
+# ---------- input ----------
+if [ -n "$FILE" ]; then
+  [ -f "$FILE" ] || exit 0
+  TEXT=$(/usr/bin/perl -CSD -e 'print <>' "$FILE")
+fi
+if [ -z "$TEXT" ]; then exit 0; fi
+
+# ---------- clean (mirrors speak.ps1) ----------
+TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -pe '
+  s/```[\s\S]*?```/ /g;          # code blocks
+  s/`[^`]*`/ /g;                  # inline code
+  s/\[([^\]]*)\]\([^\)]*\)/$1/g;  # markdown links
+  s|https?://\S+| |g;             # bare URLs
+  s/[-#*_~|>+]+/ /g;              # emphasis / marker chars
+  s/[^\p{Han}\x{3000}-\x{303F}\x{FF00}-\x{FFEF}\x{2000}-\x{206F}\x{20}-\x{7E}]//g;  # emoji / specials
+  s/\s+/ /g;                      # collapse whitespace
+')
+TEXT=$(printf '%s' "$TEXT" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+
+# ---------- length guard ----------
+if [ "${#TEXT}" -gt "$MAX_CHARS" ]; then
+  TEXT="$LONG_MSG"
+fi
+
+# ---------- speak (no -v => system default voice) ----------
+if [ -n "$VOICE" ]; then
+  say -v "$VOICE" -r "$RATE" "$TEXT"
+else
+  say -r "$RATE" "$TEXT"
+fi
+exit 0

package/engine/speech-prompt.ps1

@@ -1,22 +1,22 @@
-# speech-prompt.ps1 — Short prompt announcement (synchronous, blocking)
-# Use when a harness/agent needs the user's attention (a question, an approval
-# request). Reads the text through engine/speak.ps1 and waits until it finishes,
-# so the caller knows the announcement was actually spoken.
-#
-#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-prompt.ps1 -Text "请做出选择"
-
-param([string]$Text = '请做出选择')
-
-if (-not $Text) { exit 0 }
-
-$speak = Join-Path $PSScriptRoot 'speak.ps1'
-if (-not (Test-Path $speak)) { exit 0 }
-
-$tmp = Join-Path $env:TEMP ('speech-prompt-' + [guid]::NewGuid().ToString('N') + '.txt')
-try {
-    [System.IO.File]::WriteAllText($tmp, $Text, [System.Text.UTF8Encoding]::new($false))
-    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $speak -File $tmp
-    exit $LASTEXITCODE
-} finally {
-    if (Test-Path $tmp) { Remove-Item $tmp -Force -ErrorAction SilentlyContinue }
-}
+# speech-prompt.ps1 — Short prompt announcement (synchronous, blocking)
+# Use when a harness/agent needs the user's attention (a question, an approval
+# request). Reads the text through engine/speak.ps1 and waits until it finishes,
+# so the caller knows the announcement was actually spoken.
+#
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-prompt.ps1 -Text "请做出选择"
+
+param([string]$Text = '请做出选择')
+
+if (-not $Text) { exit 0 }
+
+$speak = Join-Path $PSScriptRoot 'speak.ps1'
+if (-not (Test-Path $speak)) { exit 0 }
+
+$tmp = Join-Path $env:TEMP ('speech-prompt-' + [guid]::NewGuid().ToString('N') + '.txt')
+try {
+    [System.IO.File]::WriteAllText($tmp, $Text, [System.Text.UTF8Encoding]::new($false))
+    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $speak -File $tmp
+    exit $LASTEXITCODE
+} finally {
+    if (Test-Path $tmp) { Remove-Item $tmp -Force -ErrorAction SilentlyContinue }
+}

package/engine/speech-summary.ps1

@@ -1,27 +1,27 @@
-# speech-summary.ps1 — Reply summary announcement (synchronous, blocking)
-# For harnesses with no "reply finished" event (e.g. DSH has no Stop hook): the
-# agent calls this at the end of its final reply.
-#
-#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-summary.ps1 -Text "总结文本"
-#
-# NOTE: keep this SYNCHRONOUS. An earlier version spawned the inner powershell
-# asynchronously with Start-Process; DSH's sandbox blocks nested sub-process
-# spawning, so it silently produced no audio. The synchronous call chain
-# (summary -> speak.ps1) is the reliable path (cost: caller waits for the
-# utterance to finish).
-
-param([string]$Text = '')
-
-if (-not $Text) { exit 0 }
-
-$speak = Join-Path $PSScriptRoot 'speak.ps1'
-if (-not (Test-Path $speak)) { exit 0 }
-
-$tmp = Join-Path $env:TEMP ('speech-summary-' + [guid]::NewGuid().ToString('N') + '.txt')
-try {
-    [System.IO.File]::WriteAllText($tmp, $Text, [System.Text.UTF8Encoding]::new($false))
-    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $speak -File $tmp
-    exit $LASTEXITCODE
-} finally {
-    if (Test-Path $tmp) { Remove-Item $tmp -Force -ErrorAction SilentlyContinue }
-}
+# speech-summary.ps1 — Reply summary announcement (synchronous, blocking)
+# For harnesses with no "reply finished" event (e.g. DSH has no Stop hook): the
+# agent calls this at the end of its final reply.
+#
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-summary.ps1 -Text "总结文本"
+#
+# NOTE: keep this SYNCHRONOUS. An earlier version spawned the inner powershell
+# asynchronously with Start-Process; DSH's sandbox blocks nested sub-process
+# spawning, so it silently produced no audio. The synchronous call chain
+# (summary -> speak.ps1) is the reliable path (cost: caller waits for the
+# utterance to finish).
+
+param([string]$Text = '')
+
+if (-not $Text) { exit 0 }
+
+$speak = Join-Path $PSScriptRoot 'speak.ps1'
+if (-not (Test-Path $speak)) { exit 0 }
+
+$tmp = Join-Path $env:TEMP ('speech-summary-' + [guid]::NewGuid().ToString('N') + '.txt')
+try {
+    [System.IO.File]::WriteAllText($tmp, $Text, [System.Text.UTF8Encoding]::new($false))
+    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $speak -File $tmp
+    exit $LASTEXITCODE
+} finally {
+    if (Test-Path $tmp) { Remove-Item $tmp -Force -ErrorAction SilentlyContinue }
+}

package/package.json

@@ -1,43 +1,46 @@
-{
-  "name": "dsh-speak",
-  "version": "1.0.0",
-  "description": "Make your AI harness speak — verified voice announcements for DSH and other AI coding harnesses (Windows SAPI5 + natural voices)",
-  "main": "adapters/dsh/speech-hook.js",
-  "files": [
-    "adapters/dsh/speech-hook.js",
-    "adapters/dsh/install.ps1",
-    "engine/",
-    "docs/",
-    "README.md",
-    "README.zh-CN.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "tts",
-    "text-to-speech",
-    "voice",
-    "speech",
-    "voice-announcement",
-    "sapi5",
-    "windows",
-    "powershell"
-  ],
-  "scripts": {
-    "prepublishOnly": "node --check adapters/dsh/speech-hook.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Alan2Z/dsh-speak.git"
-  },
-  "author": "Alan2Z",
-  "license": "MIT",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org"
-  }
-}
+{
+  "name": "dsh-speak",
+  "version": "1.2.0",
+  "description": "Make your AI harness speak — verified voice announcements for DSH and other AI coding harnesses (Windows SAPI5 + macOS system voices)",
+  "main": "adapters/dsh/speech-hook.js",
+  "files": [
+    "adapters/dsh/speech-hook.js",
+    "adapters/dsh/install.ps1",
+    "engine/",
+    "docs/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "tts",
+    "text-to-speech",
+    "voice",
+    "speech",
+    "voice-announcement",
+    "sapi5",
+    "windows",
+    "powershell",
+    "macos",
+    "darwin",
+    "say"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --check adapters/dsh/speech-hook.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alan2Z/dsh-speak.git"
+  },
+  "author": "Alan2Z",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}