@xdfnet/ispeak 1.6.9 → 1.6.11

package/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## 项目概述
+
+iSpeak — 字节跳动 TTS 本地播报服务。守护进程 `ispeakd` 监听 Unix Socket，接收文本后调用火山引擎 TTS 流式 API，边合成边播放。
+
+## 常用命令
+
+```bash
+make build      # 编译 ispeakd
+make install    # 安装 + 启动 launchd 服务
+make deploy     # 同 install
+make uninstall  # 卸载（停止服务 + 删除文件）
+make clean      # 清理编译产物
+make help       # 显示帮助
+```
+
+## 命令行测试约定
+
+- 测试 Claude：`claude -p "你好"`
+- 测试 Codex：`codex exec "你好"`
+
+## 架构
+
+```
+ispeak (CLI, bash)
+  └─ nc -U ~/.config/iSpeak/ispeak.sock
+      └─ ispeakd (Go daemon)
+           ├─ Task Engine (任务仓库)
+           │    └─ pending FIFO
+           └─ transactionWorker (single)
+                └─ pending -> running -> delete
+                     └─ SSE PCM chunk -> AVAudioEngine
+```
+
+- **Socket**: `~/.config/iSpeak/ispeak.sock`
+- **日志**: `~/.config/iSpeak/ispeak.log` (lumberjack 轮转, 10MB/份, 保留3份)
+- **Temp**: 进程级 tempDir，退出时清理
+- **Launchd PLIST**: `~/Library/LaunchAgents/com.ispeak.plist`
+
+## 核心文件
+
+- `main.go` — 守护进程、任务引擎、TTS 流式请求、SSE 解析、流式播放
+- `avaudioengine_player_darwin.go` — macOS 原生 `AVAudioEngine` PCM 播放器
+- `clean_text.go` — TTS 播报文本清洗
+- `main_test.go` — 任务引擎关键行为测试
+- `scripts/ispeak` — CLI 入口，通过 nc 发送文本到 socket
+- `configs/hook-speak.sh` — Claude/Codex Hook，bash + Node 解析输入
+
+## 消息格式
+
+CLI 与 daemon 通过 socket 传输原始文本，支持音色前缀：
+
+```
+{source:claude}文本  → 使用 claude 来源音色
+{source:codex}文本   → 使用 codex 来源音色
+文本                 → 使用默认音色
+```
+
+## 任务策略（节省 TTS 费用）
+
+新消息到达时：
+1. 删除所有 `pending` 任务（未开始）
+2. 不打断当前 `running` 事务
+3. 创建新任务并进入 `pending`
+
+**任务状态流转：**
+```
+pending → running → delete
+```
+
+## 失败策略
+
+- 流式合成/播放失败：直接删除任务，不重试，避免重复播报
+
+## 配置
+
+`~/.config/iSpeak/config.json`:
+
+```json
+{
+  "apiKey": "...",
+  "endpoint": "https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse",
+  "defaultVoice": { "voice_type": "zh_female_mizai_uranus_bigtts", "resourceId": "seed-tts-2.0" },
+  "sourceVoices": {
+    "claude": { "voice_type": "zh_female_tianmeitaozi_uranus_bigtts", "resourceId": "seed-tts-2.0" },
+    "codex": { "voice_type": "zh_male_shaonianzixin_uranus_bigtts", "resourceId": "seed-tts-2.0" }
+  }
+}
+```
+
+## 稳定性设计
+
+- 单 transaction worker，合成与播放同链路，降低首播延迟
+- 关键 goroutine 有 `panic recover`
+- 配置热更新（mtime 缓存 + 自动重载）
+- TTS HTTP Client 复用，减少连接开销
+- 主链路使用 macOS 原生 `AVAudioEngine` 播放 PCM
+- 播放失败直接删除任务，不重试
+- 日志轮转，防止文件过大
+- 进程级 temp 目录，退出时自动清理

package/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+这个仓库的共享工程约定、命令、架构和配置，统一看 [AGENTS.md](/Users/admin/iCode/iSpeak/AGENTS.md)。
+
+这里仅补充 Claude Code 相关的最小约定：
+
+- `configs/hook-speak.sh` 是 Claude/Codex 共用 hook
+- `{source:claude}` 会走 Claude 音色
+- 其余行为与 [AGENTS.md](/Users/admin/iCode/iSpeak/AGENTS.md) 保持一致

package/Makefile

@@ -0,0 +1,120 @@
+.PHONY: build test pack release push install deploy uninstall clean help
+
+VERSION  := 1.6.9
+TAG      := v$(VERSION)
+NPM_PKG  := @xdfnet/ispeak
+BIN     := build/ispeakd
+BIN_DIR := $(HOME)/.local/bin
+DST     := $(BIN_DIR)/ispeakd
+PLIST   := $(HOME)/Library/LaunchAgents/com.ispeak.plist
+LEGACY_PLIST := $(HOME)/Library/LaunchAgents/com.iSpeak.plist
+CONFIG  := $(HOME)/.config/iSpeak
+LOG     := $(HOME)/.config/iSpeak/ispeak.log
+CLI_SRC := scripts/ispeak
+HOOK_SRC := configs/hook-speak.sh
+PLIST_SRC := configs/com.ispeak.plist
+CONFIG_SRC := configs/config.example.json
+
+help:
+	@echo "iSpeak $(VERSION)"
+	@echo ""
+	@echo "  make build      # 编译 ispeakd"
+	@echo "  make test       # 运行 Go 测试、race 测试、构建、npm 打包预检"
+	@echo "  make release    # 推送 GitHub tag 并发布 npm latest"
+	@echo "  make push       # 同 release"
+	@echo "  make install    # 安装并启动服务（首次运行会部署配置和 hook）"
+	@echo "  make deploy     # 同 install"
+	@echo "  make uninstall  # 卸载（停止服务 + 删除文件）"
+	@echo "  make clean      # 清理编译产物"
+
+build:
+	@mkdir -p build
+	@go build -ldflags="-s -w" -o $(BIN) .
+	@echo "编译完成: $(BIN)"
+
+test:
+	@go test -count=1 ./...
+	@go test -race -count=1 ./...
+	@go build ./...
+	@bash scripts/test-hook-speak.sh
+	@npm pack --dry-run
+
+pack:
+	@npm pack --dry-run
+
+release: test
+	@if [ -n "$$(git status --porcelain)" ]; then \
+		echo "工作区不干净，请先提交或暂存改动"; \
+		git status --short; \
+		exit 1; \
+	fi
+	@if npm view $(NPM_PKG)@$(VERSION) version >/dev/null 2>&1; then \
+		echo "npm 版本已存在: $(NPM_PKG)@$(VERSION)"; \
+		exit 1; \
+	fi
+	@if git rev-parse "$(TAG)" >/dev/null 2>&1; then \
+		echo "tag 已存在: $(TAG)"; \
+	else \
+		git tag "$(TAG)"; \
+	fi
+	@git push origin HEAD
+	@git push origin "$(TAG)"
+	@npm publish --access public
+	@echo "已发布: $(NPM_PKG)@$(VERSION) / $(TAG)"
+
+push: release
+
+install: build
+	@# 停止旧服务
+	@launchctl unload $(LEGACY_PLIST) 2>/dev/null || true
+	@launchctl unload $(PLIST) 2>/dev/null || true
+	@rm -f $(LEGACY_PLIST)
+	@# 安装二进制和 CLI
+	@mkdir -p $(BIN_DIR)
+	@install -m 0755 $(BIN) $(DST)
+	@install -m 0755 $(CURDIR)/$(CLI_SRC) $(BIN_DIR)/ispeak
+	@# 部署配置文件（首次不覆盖已有）
+	@mkdir -p $(CONFIG)
+	@if [ ! -f $(CONFIG)/config.json ]; then \
+		cp $(CONFIG_SRC) $(CONFIG)/config.json; \
+		echo "配置文件已创建: $(CONFIG)/config.json"; \
+	else \
+		echo "配置文件已存在: $(CONFIG)/config.json"; \
+	fi
+	@if grep -q '"endpoint"[[:space:]]*:[[:space:]]*"https://openspeech.bytedance.com/api/v3/tts/unidirectional"' $(CONFIG)/config.json; then \
+		cp $(CONFIG)/config.json $(CONFIG)/config.json.bak; \
+		perl -pi -e 's|"https://openspeech.bytedance.com/api/v3/tts/unidirectional"|"https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse"|g' $(CONFIG)/config.json; \
+		echo "配置 endpoint 已迁移到 SSE，旧配置备份: $(CONFIG)/config.json.bak"; \
+	fi
+	@# 部署 hook 脚本（覆盖安装；如有本地改动先备份）
+	@if [ -f $(CONFIG)/hook-speak.sh ] && ! cmp -s $(HOOK_SRC) $(CONFIG)/hook-speak.sh; then \
+		cp $(CONFIG)/hook-speak.sh $(CONFIG)/hook-speak.sh.bak; \
+		echo "旧 Hook 已备份: $(CONFIG)/hook-speak.sh.bak"; \
+	fi
+	@cp $(HOOK_SRC) $(CONFIG)/hook-speak.sh
+	@chmod +x $(CONFIG)/hook-speak.sh
+	@echo "Hook 脚本已安装: $(CONFIG)/hook-speak.sh"
+	@# 安装 launchd plist
+	@sed 's|BINARY_PATH_PLACEHOLDER|$(DST)|' $(PLIST_SRC) > $(PLIST)
+	@# 启动
+	@launchctl load $(PLIST)
+	@sleep 0.5
+	@# 自检
+	@$(BIN_DIR)/ispeak status && echo "" && echo "安装成功！" || { echo "安装失败，请检查日志: $(LOG)"; exit 1; }
+
+deploy: install
+
+uninstall:
+	@echo "停止服务..."
+	@launchctl unload $(LEGACY_PLIST) 2>/dev/null || true
+	@launchctl unload $(PLIST) 2>/dev/null || true
+	@rm -f $(LEGACY_PLIST)
+	@rm -f $(PLIST)
+	@echo "删除文件..."
+	@rm -f $(BIN_DIR)/ispeakd $(BIN_DIR)/ispeak
+	@echo "保留配置目录: $(CONFIG)"
+	@echo "卸载完成"
+
+clean:
+	@rm -rf build
+	@echo "清理完成"

package/avaudioengine_player_darwin.go

@@ -0,0 +1,315 @@
+//go:build darwin && cgo
+
+package main
+
+/*
+#cgo CFLAGS: -x objective-c -fblocks
+#cgo LDFLAGS: -framework AVFoundation -framework Foundation
+
+#include <AVFoundation/AVFoundation.h>
+#include <pthread.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+	AVAudioEngine *engine;
+	AVAudioPlayerNode *node;
+	AVAudioFormat *format;
+	pthread_mutex_t mu;
+	pthread_cond_t cond;
+	int pending;
+	int closing;
+	int started;
+} AVNativePlayer;
+
+static char *av_make_error(const char *prefix, NSError *error) {
+	const char *detail = "";
+	if (error != nil && [error localizedDescription] != nil) {
+		detail = [[error localizedDescription] UTF8String];
+	}
+	char buffer[512];
+	snprintf(buffer, sizeof(buffer), "%s: %s", prefix, detail);
+	return strdup(buffer);
+}
+
+static int av_player_create(double sampleRate, unsigned int channels, AVNativePlayer **out, char **err) {
+	if (out == NULL) {
+		if (err) *err = strdup("av_player_create: out is nil");
+		return -1;
+	}
+	*out = NULL;
+
+	@autoreleasepool {
+		AVNativePlayer *player = (AVNativePlayer *)calloc(1, sizeof(AVNativePlayer));
+		if (player == NULL) {
+			if (err) *err = strdup("av_player_create: calloc failed");
+			return -1;
+		}
+
+		if (pthread_mutex_init(&player->mu, NULL) != 0) {
+			if (err) *err = strdup("av_player_create: mutex init failed");
+			free(player);
+			return -1;
+		}
+		if (pthread_cond_init(&player->cond, NULL) != 0) {
+			if (err) *err = strdup("av_player_create: cond init failed");
+			pthread_mutex_destroy(&player->mu);
+			free(player);
+			return -1;
+		}
+
+		player->engine = [[AVAudioEngine alloc] init];
+		player->node = [[AVAudioPlayerNode alloc] init];
+		player->format = [[AVAudioFormat alloc] initWithCommonFormat:AVAudioPCMFormatFloat32 sampleRate:sampleRate channels:channels interleaved:NO];
+		if (player->engine == nil || player->node == nil || player->format == nil) {
+			if (err) *err = strdup("av_player_create: failed to allocate AVAudio objects");
+			[player->engine release];
+			[player->node release];
+			[player->format release];
+			pthread_cond_destroy(&player->cond);
+			pthread_mutex_destroy(&player->mu);
+			free(player);
+			return -1;
+		}
+
+		[player->engine attachNode:player->node];
+		[player->engine connect:player->node to:player->engine.mainMixerNode format:player->format];
+		[player->engine prepare];
+
+		NSError *error = nil;
+		if (![player->engine startAndReturnError:&error]) {
+			if (err) *err = av_make_error("AVAudioEngine start failed", error);
+			[player->node release];
+			[player->engine release];
+			[player->format release];
+			pthread_cond_destroy(&player->cond);
+			pthread_mutex_destroy(&player->mu);
+			free(player);
+			return -1;
+		}
+
+		[player->node play];
+		player->started = 1;
+		*out = player;
+		return 0;
+	}
+}
+
+static int av_player_write(AVNativePlayer *player, const void *data, size_t len, char **err) {
+	if (player == NULL || player->engine == nil || player->node == nil || player->format == nil) {
+		if (err) *err = strdup("av_player_write: player is closed");
+		return -1;
+	}
+	if (data == NULL || len == 0) {
+		return 0;
+	}
+
+	AVAudioFrameCount frames = (AVAudioFrameCount)(len / 2);
+	if (frames == 0) {
+		return 0;
+	}
+
+	AVAudioPCMBuffer *buffer = [[AVAudioPCMBuffer alloc] initWithPCMFormat:player->format frameCapacity:frames];
+	if (buffer == nil) {
+		if (err) *err = strdup("av_player_write: failed to allocate buffer");
+		return -1;
+	}
+	buffer.frameLength = frames;
+	float *dest = buffer.floatChannelData[0];
+	const int16_t *src = (const int16_t *)data;
+	for (AVAudioFrameCount i = 0; i < frames; i++) {
+		dest[i] = (float)src[i] / 32768.0f;
+	}
+
+	pthread_mutex_lock(&player->mu);
+	player->pending++;
+	pthread_mutex_unlock(&player->mu);
+
+	AVNativePlayer *captured = player;
+	[player->node scheduleBuffer:buffer completionHandler:^{
+		pthread_mutex_lock(&captured->mu);
+		if (captured->pending > 0) {
+			captured->pending--;
+		}
+		if (captured->closing && captured->pending == 0) {
+			pthread_cond_signal(&captured->cond);
+		}
+		pthread_mutex_unlock(&captured->mu);
+	}];
+
+	return 0;
+}
+
+static int av_player_close_and_dispose(AVNativePlayer *player, char **err) {
+	if (player == NULL) {
+		return 0;
+	}
+
+	pthread_mutex_lock(&player->mu);
+	player->closing = 1;
+	while (player->pending > 0) {
+		pthread_cond_wait(&player->cond, &player->mu);
+	}
+	pthread_mutex_unlock(&player->mu);
+
+	@autoreleasepool {
+		[player->node stop];
+		[player->engine stop];
+		[player->node release];
+		[player->engine release];
+		[player->format release];
+	}
+
+	pthread_cond_destroy(&player->cond);
+	pthread_mutex_destroy(&player->mu);
+	free(player);
+	return 0;
+}
+
+static int av_player_abort(AVNativePlayer *player, char **err) {
+	return av_player_close_and_dispose(player, err);
+}
+
+*/
+import "C"
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"sync"
+	"unsafe"
+)
+
+const (
+	audioEngineSampleRate = 48000
+	audioEngineChannels   = 1
+	audioEngineChunkSize   = 32 * 1024
+)
+
+type avAudioEngineStreamPlayer struct {
+	mu   sync.Mutex
+	ptr  *C.AVNativePlayer
+	tail []byte
+}
+
+func newDefaultStreamPlayer() (StreamPlayer, error) {
+	var ptr *C.AVNativePlayer
+	var cerr *C.char
+	if C.av_player_create(C.double(audioEngineSampleRate), C.uint(audioEngineChannels), &ptr, &cerr) != 0 {
+		return nil, cError(cerr)
+	}
+	log.Printf("播放器模式: AVAudioEngine PCM 流式 (%d Hz, %d channel)", audioEngineSampleRate, audioEngineChannels)
+	return &avAudioEngineStreamPlayer{ptr: ptr}, nil
+}
+
+func (p *avAudioEngineStreamPlayer) Write(audio []byte) error {
+	if len(audio) == 0 {
+		return nil
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.ptr == nil {
+		return errors.New("AVAudioEngine player 已关闭")
+	}
+
+	data := audio
+	if len(p.tail) > 0 {
+		data = append(append([]byte(nil), p.tail...), audio...)
+		p.tail = nil
+	}
+
+	if len(data)%2 == 1 {
+		p.tail = append(p.tail[:0], data[len(data)-1])
+		data = data[:len(data)-1]
+	}
+
+	for len(data) > 0 {
+		n := audioEngineChunkSize
+		if n > len(data) {
+			n = len(data)
+		}
+		if n%2 == 1 {
+			n--
+		}
+		if n <= 0 {
+			break
+		}
+		if err := p.writeChunk(data[:n]); err != nil {
+			return err
+		}
+		data = data[n:]
+	}
+
+	return nil
+}
+
+func (p *avAudioEngineStreamPlayer) CloseAndWait() error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.closeLocked()
+}
+
+func (p *avAudioEngineStreamPlayer) Abort() error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.closeLocked()
+}
+
+func (p *avAudioEngineStreamPlayer) writeChunk(data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+	if p.ptr == nil {
+		return errors.New("AVAudioEngine player 已关闭")
+	}
+
+	var cerr *C.char
+	if C.av_player_write(p.ptr, unsafe.Pointer(&data[0]), C.size_t(len(data)), &cerr) != 0 {
+		return cError(cerr)
+	}
+	return nil
+}
+
+func (p *avAudioEngineStreamPlayer) closeLocked() error {
+	if p.ptr == nil {
+		return nil
+	}
+
+	if len(p.tail) > 0 {
+		pad := append(append([]byte(nil), p.tail...), 0)
+		p.tail = nil
+		if err := p.writeChunk(pad); err != nil {
+			_ = p.disposeLocked()
+			return err
+		}
+	}
+
+	return p.disposeLocked()
+}
+
+func (p *avAudioEngineStreamPlayer) disposeLocked() error {
+	if p.ptr == nil {
+		return nil
+	}
+
+	var cerr *C.char
+	if C.av_player_close_and_dispose(p.ptr, &cerr) != 0 {
+		p.ptr = nil
+		return cError(cerr)
+	}
+	p.ptr = nil
+	return nil
+}
+
+func cError(cerr *C.char) error {
+	if cerr == nil {
+		return nil
+	}
+	defer C.free(unsafe.Pointer(cerr))
+	return fmt.Errorf("%s", C.GoString(cerr))
+}

package/main.go

@@ -96,12 +96,6 @@ func (e *TaskEngine) Start() {
 func (e *TaskEngine) Submit(text string, voice VoiceInfo, cfg Config) uint64 {
 	e.mu.Lock()
 
-	// 新任务进来先删所有未开始的任务。
-	for _, id := range e.pending {
-		delete(e.tasks, id)
-		log.Printf("删除待执行任务: id=%d", id)
-	}
-	e.pending = e.pending[:0]
 
 	e.nextID++
 	task := &Task{

package/main_test.go

@@ -0,0 +1,746 @@
+package main
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestSubmitKeepsAllPendingTasks(t *testing.T) {
+	e := NewTaskEngine()
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		return onAudio([]byte("ok"))
+	}
+	e.newStreamPlayerFn = newFakeStreamPlayerFactory()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+
+	e.Submit("a", voice, cfg)
+	e.Submit("b", voice, cfg)
+
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if len(e.pending) != 2 {
+		t.Fatalf("expected 2 pending, got %d", len(e.pending))
+	}
+	if e.latestID != 2 {
+		t.Fatalf("expected latestID 2, got %d", e.latestID)
+	}
+}
+
+func TestTransactionDeletesOnSynthesisFailureWithoutRetry(t *testing.T) {
+	e := NewTaskEngine()
+	var mu sync.Mutex
+	calls := 0
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		mu.Lock()
+		defer mu.Unlock()
+		calls++
+		return errors.New("fail")
+	}
+	e.newStreamPlayerFn = newFakeStreamPlayerFactory()
+	e.Start()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	id := e.Submit("x", voice, cfg)
+
+	waitFor(t, 2*time.Second, func() bool {
+		e.mu.Lock()
+		defer e.mu.Unlock()
+		_, ok := e.tasks[id]
+		return !ok
+	})
+
+	mu.Lock()
+	defer mu.Unlock()
+	if calls != 1 {
+		t.Fatalf("expected synth attempts=1, got %d", calls)
+	}
+}
+
+func TestTransactionDeletesOnPlayerWriteFailureWithoutRetry(t *testing.T) {
+	e := NewTaskEngine()
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		return onAudio([]byte("audio"))
+	}
+	var mu sync.Mutex
+	calls := 0
+	e.newStreamPlayerFn = func() (StreamPlayer, error) {
+		mu.Lock()
+		defer mu.Unlock()
+		calls++
+		return &fakeStreamPlayer{writeErr: calls == 1}, nil
+	}
+	e.Start()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	id := e.Submit("x", voice, cfg)
+
+	waitFor(t, 2*time.Second, func() bool {
+		e.mu.Lock()
+		defer e.mu.Unlock()
+		_, ok := e.tasks[id]
+		return !ok
+	})
+
+	mu.Lock()
+	defer mu.Unlock()
+	if calls != 1 {
+		t.Fatalf("expected player attempts=1, got %d", calls)
+	}
+}
+
+func TestSubmitDoesNotInterruptRunningTask(t *testing.T) {
+	e := NewTaskEngine()
+	start := make(chan struct{}, 1)
+	release := make(chan struct{})
+	var mu sync.Mutex
+	processed := make([]string, 0, 2)
+
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		if text == "a" {
+			start <- struct{}{}
+		}
+		if text == "a" {
+			<-release
+		}
+		mu.Lock()
+		processed = append(processed, text)
+		mu.Unlock()
+		return onAudio([]byte(text))
+	}
+	e.newStreamPlayerFn = newFakeStreamPlayerFactory()
+	e.Start()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	e.Submit("a", voice, cfg)
+	<-start // a 已进入 running
+	secondID := e.Submit("b", voice, cfg)
+
+	e.mu.Lock()
+	if len(e.pending) != 1 || e.pending[0] != secondID {
+		t.Fatalf("expected second task pending while first keeps running, got %#v", e.pending)
+	}
+	e.mu.Unlock()
+
+	close(release)
+
+	waitFor(t, 3*time.Second, func() bool {
+		e.mu.Lock()
+		defer e.mu.Unlock()
+		return len(e.tasks) == 0
+	})
+
+	mu.Lock()
+	defer mu.Unlock()
+	if strings.Join(processed, "") != "ab" {
+		t.Fatalf("expected processed [a b], got %#v", processed)
+	}
+}
+
+func TestClaimedStaleTaskIsSkippedBeforeTransaction(t *testing.T) {
+	e := NewTaskEngine()
+	calls := 0
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		calls++
+		return onAudio([]byte(text))
+	}
+	e.newStreamPlayerFn = newFakeStreamPlayerFactory()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	firstID := e.Submit("a", voice, cfg)
+	claimedID := e.claimPending()
+	if claimedID != firstID {
+		t.Fatalf("expected claimed first task %d, got %d", firstID, claimedID)
+	}
+	e.Submit("b", voice, cfg)
+
+	e.processTransaction(firstID)
+
+	if calls != 0 {
+		t.Fatalf("expected stale task skipped before transaction, got calls=%d", calls)
+	}
+	e.mu.Lock()
+	_, firstExists := e.tasks[firstID]
+	e.mu.Unlock()
+	if firstExists {
+		t.Fatalf("expected stale task deleted")
+	}
+}
+
+func TestSynthesisPanicDeletesTaskAndWorkerContinues(t *testing.T) {
+	e := NewTaskEngine()
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		if text == "panic" {
+			panic("boom")
+		}
+		return onAudio([]byte(text))
+	}
+	e.newStreamPlayerFn = newFakeStreamPlayerFactory()
+	e.Start()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	panicID := e.Submit("panic", voice, cfg)
+	waitForTaskDeleted(t, e, panicID)
+
+	okID := e.Submit("ok", voice, cfg)
+	waitForTaskDeleted(t, e, okID)
+}
+
+func TestPlaybackPanicDeletesTaskAndWorkerContinues(t *testing.T) {
+	e := NewTaskEngine()
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		return onAudio([]byte(text))
+	}
+	var mu sync.Mutex
+	calls := 0
+	e.newStreamPlayerFn = func() (StreamPlayer, error) {
+		mu.Lock()
+		defer mu.Unlock()
+		calls++
+		return &fakeStreamPlayer{panicOnWrite: calls == 1}, nil
+	}
+	e.Start()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	panicID := e.Submit("panic", voice, cfg)
+	waitForTaskDeleted(t, e, panicID)
+
+	okID := e.Submit("ok", voice, cfg)
+	waitForTaskDeleted(t, e, okID)
+}
+
+func TestParseSSEStreamWritesChunksInOrder(t *testing.T) {
+	stream := strings.NewReader(
+		"data: {\"audio\":\"YQ==\"}\n\n" +
+			"data: {\"data\":{\"audio\":\"Yg==\"}}\n\n" +
+			"data: [DONE]\n\n",
+	)
+
+	var got []string
+	err := parseSSEStream(stream, func(audio []byte) error {
+		got = append(got, string(audio))
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("parse stream: %v", err)
+	}
+	if strings.Join(got, "") != "ab" {
+		t.Fatalf("expected chunks ab, got %#v", got)
+	}
+}
+
+func TestParseSSEStreamHandlesLargeAudioLine(t *testing.T) {
+	payload := strings.Repeat("a", 300*1024)
+	encoded := base64.StdEncoding.EncodeToString([]byte(payload))
+	stream := strings.NewReader("data: {\"audio\":\"" + encoded + "\"}\n\n")
+
+	var got []byte
+	err := parseSSEStream(stream, func(audio []byte) error {
+		got = append(got, audio...)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("parse stream: %v", err)
+	}
+	if string(got) != payload {
+		t.Fatalf("expected large payload preserved, got len=%d", len(got))
+	}
+}
+
+func TestParseSSEStreamReturnsTTSFailureMessage(t *testing.T) {
+	stream := strings.NewReader("event: 153\ndata: {\"code\":55001307,\"message\":\"voice clone failed\",\"data\":null}\n\n")
+
+	err := parseSSEStream(stream, func(audio []byte) error {
+		t.Fatalf("unexpected audio callback")
+		return nil
+	})
+	if err == nil {
+		t.Fatalf("expected tts failure")
+	}
+	if !strings.Contains(err.Error(), "55001307") || !strings.Contains(err.Error(), "voice clone failed") {
+		t.Fatalf("expected code and message in error, got %v", err)
+	}
+}
+
+func TestCleanTextRemovesSpeechNoise(t *testing.T) {
+	input := strings.Join([]string{
+		"## 结果",
+		"- **验证通过**：[main.go](/Users/admin/iCode/iSpeak/main.go:123)",
+		"- commit: a97e57d Improve latest-only task handling",
+		"- 路径：/Users/admin/iCode/iSpeak/main.go",
+		"| 文件 | 状态 |",
+		"|------|------|",
+		"| model-00001.safetensors | ✅ 完整 |",
+		"```go",
+		"fmt.Println(\"不要播代码\")",
+		"```",
+		"https://example.com/path",
+		"飞哥，需要你重启服务。",
+	}, "\n")
+
+	got := cleanText(input)
+	for _, bad := range []string{
+		"**",
+		"`",
+		"/Users/admin",
+		"https://",
+		"fmt.Println",
+		"safetensors",
+		"文件",
+		"状态",
+		"完整",
+		"|------|",
+		"a97e57d",
+	} {
+		if strings.Contains(got, bad) {
+			t.Fatalf("expected cleaned text not to contain %q, got %q", bad, got)
+		}
+	}
+	for _, want := range []string{
+		"结果",
+		"验证通过",
+		"main.go",
+		"路径",
+		"飞哥，需要你重启服务。",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("expected cleaned text to contain %q, got %q", want, got)
+		}
+	}
+}
+
+func TestCleanTextOrderingPreservesLinkTitleBeforeRemovingURL(t *testing.T) {
+	got := cleanText("参考：[架构文档](https://example.com/docs)。")
+	if !strings.Contains(got, "架构文档") {
+		t.Fatalf("expected link title preserved, got %q", got)
+	}
+	if strings.Contains(got, "https://") || strings.Contains(got, "example.com") {
+		t.Fatalf("expected URL removed, got %q", got)
+	}
+}
+
+func TestCleanTextOrderingSkipsCodeBeforePathAndTableRules(t *testing.T) {
+	input := strings.Join([]string{
+		"结论保留。",
+		"```text",
+		"| 不该 | 播 |",
+		"/Users/admin/iCode/iSpeak/main.go",
+		"```",
+		"后续保留。",
+	}, "\n")
+
+	got := cleanText(input)
+	for _, bad := range []string{"不该", "/Users/admin", "main.go"} {
+		if strings.Contains(got, bad) {
+			t.Fatalf("expected code block removed before inline cleaning, got %q", got)
+		}
+	}
+	if !strings.Contains(got, "结论保留。") || !strings.Contains(got, "后续保留。") {
+		t.Fatalf("expected surrounding text preserved, got %q", got)
+	}
+}
+
+func TestCleanTextOrderingRemovesTableHeaderWhenSeparatorAppears(t *testing.T) {
+	input := strings.Join([]string{
+		"前言。",
+		"| 文件 | 状态 |",
+		"|---|---|",
+		"| main.go | 通过 |",
+		"结论。",
+	}, "\n")
+
+	got := cleanText(input)
+	for _, bad := range []string{"文件", "状态", "main.go"} {
+		if strings.Contains(got, bad) {
+			t.Fatalf("expected table header/content removed, got %q", got)
+		}
+	}
+	if !strings.Contains(got, "前言。") || !strings.Contains(got, "结论。") {
+		t.Fatalf("expected surrounding text preserved, got %q", got)
+	}
+}
+
+func TestCleanTextOrderingRemovesUUIDBeforeCommitHash(t *testing.T) {
+	got := cleanText("请求 ID：123e4567-e89b-12d3-a456-426614174000，状态成功。")
+	if strings.Contains(got, "123e4567") || strings.Contains(got, "426614174000") {
+		t.Fatalf("expected UUID removed as a whole, got %q", got)
+	}
+	if !strings.Contains(got, "状态成功。") {
+		t.Fatalf("expected conclusion preserved, got %q", got)
+	}
+}
+
+func TestCleanTextSkipsWholeMarkdownTable(t *testing.T) {
+	input := strings.Join([]string{
+		"表格如下：",
+		"| 文件 | 状态 |",
+		"|------|------|",
+		"| main.go | 通过 |",
+		"| main_test.go | 通过 |",
+		"结论：验证通过。",
+	}, "\n")
+
+	got := cleanText(input)
+	for _, bad := range []string{"文件", "状态", "main.go", "main_test.go"} {
+		if strings.Contains(got, bad) {
+			t.Fatalf("expected table content removed, got %q", got)
+		}
+	}
+	if !strings.Contains(got, "表格如下：") || !strings.Contains(got, "结论：验证通过。") {
+		t.Fatalf("expected surrounding text preserved, got %q", got)
+	}
+}
+
+func TestCleanTextSkipsArtifactAndHTML(t *testing.T) {
+	input := strings.Join([]string{
+		"这是前置结论。",
+		`<artifact identifier="demo" type="text/html">`,
+		"<!doctype html>",
+		"<html><body>不要播 HTML</body></html>",
+		"</artifact>",
+		"这是后置结论。",
+	}, "\n")
+
+	got := cleanText(input)
+	if strings.Contains(got, "HTML") || strings.Contains(got, "artifact") {
+		t.Fatalf("expected artifact/html removed, got %q", got)
+	}
+	if !strings.Contains(got, "这是前置结论。") || !strings.Contains(got, "这是后置结论。") {
+		t.Fatalf("expected surrounding conclusions preserved, got %q", got)
+	}
+}
+
+func TestCleanTextKeepsChinesePercentConclusion(t *testing.T) {
+	input := strings.Join([]string{
+		"下载 42% 12MB/s eta 1m",
+		"测试通过率 95%，可以发布。",
+	}, "\n")
+
+	got := cleanText(input)
+	if strings.Contains(got, "12MB/s") || strings.Contains(got, "eta") {
+		t.Fatalf("expected progress noise removed, got %q", got)
+	}
+	if !strings.Contains(got, "测试通过率 95%，可以发布。") {
+		t.Fatalf("expected Chinese percent conclusion preserved, got %q", got)
+	}
+}
+
+func TestCleanTextKeepsPlainPercentLine(t *testing.T) {
+	got := cleanText("覆盖率 95%")
+	if !strings.Contains(got, "覆盖率 95%") {
+		t.Fatalf("expected plain percent line preserved, got %q", got)
+	}
+}
+
+func TestCleanTextKeepsOrdinaryFileReferenceLine(t *testing.T) {
+	got := cleanText("已更新 main.go 和 README.md。")
+	if !strings.Contains(got, "main.go") || !strings.Contains(got, "README.md") {
+		t.Fatalf("expected ordinary file references preserved, got %q", got)
+	}
+}
+
+func TestCleanTextSingleLineArtifactDoesNotSwallowFollowingText(t *testing.T) {
+	input := strings.Join([]string{
+		`<artifact identifier="demo">不要播</artifact>`,
+		"后面的结论要保留。",
+	}, "\n")
+
+	got := cleanText(input)
+	if strings.Contains(got, "不要播") || strings.Contains(got, "artifact") {
+		t.Fatalf("expected single-line artifact removed, got %q", got)
+	}
+	if !strings.Contains(got, "后面的结论要保留。") {
+		t.Fatalf("expected following text preserved, got %q", got)
+	}
+}
+
+func TestHandleConnectionPreservesMultilineBeforeCleaning(t *testing.T) {
+	oldConfigDir := configDir
+	oldCacheValid := configCacheValid
+	oldCachePath := configCachePath
+	oldCacheModTime := configCacheModTime
+	oldCache := configCache
+	t.Cleanup(func() {
+		configDir = oldConfigDir
+		configCacheValid = oldCacheValid
+		configCachePath = oldCachePath
+		configCacheModTime = oldCacheModTime
+		configCache = oldCache
+	})
+
+	dir := t.TempDir()
+	configDir = dir
+	configCacheValid = false
+	cfg := `{
+		"apiKey": "key",
+		"endpoint": "https://example.com/tts",
+		"defaultVoice": {"voice_type": "voice", "resourceId": "resource"}
+	}`
+	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte(cfg), 0644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	server, client := net.Pipe()
+	e := NewTaskEngine()
+	done := make(chan struct{})
+	go func() {
+		handleConnection(server, e)
+		close(done)
+	}()
+
+	msg := strings.Join([]string{
+		"不是，飞哥。",
+		"",
+		"| 部分 | 是否常驻 |",
+		"|---|---|",
+		"| ispeakd | 是 |",
+		"",
+		"也就是说：daemon 常驻，播放器不是常驻。",
+	}, "\n")
+	if _, err := client.Write([]byte(msg)); err != nil {
+		t.Fatalf("write client: %v", err)
+	}
+	if err := client.Close(); err != nil {
+		t.Fatalf("close client: %v", err)
+	}
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatalf("handleConnection did not return")
+	}
+
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if len(e.pending) != 1 {
+		t.Fatalf("expected one pending task, got %d", len(e.pending))
+	}
+	task := e.tasks[e.pending[0]]
+	if !strings.Contains(task.Text, "不是，飞哥。") ||
+		!strings.Contains(task.Text, "也就是说：daemon 常驻，播放器不是常驻。") {
+		t.Fatalf("expected surrounding text preserved, got %q", task.Text)
+	}
+	if strings.Contains(task.Text, "是否常驻") || strings.Contains(task.Text, "ispeakd | 是") {
+		t.Fatalf("expected table removed, got %q", task.Text)
+	}
+}
+
+func TestInvalidSSEAudioDeletesTaskAndWorkerContinues(t *testing.T) {
+	e := NewTaskEngine()
+	e.synthesizeStreamFn = func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error {
+		if text == "bad" {
+			return parseSSEStream(strings.NewReader("data: {\"audio\":\"***\"}\n\n"), onAudio)
+		}
+		return onAudio([]byte(text))
+	}
+	e.newStreamPlayerFn = newFakeStreamPlayerFactory()
+	e.Start()
+
+	cfg := Config{}
+	voice := VoiceInfo{VoiceType: "v", ResourceID: "r"}
+	badID := e.Submit("bad", voice, cfg)
+	waitForTaskDeleted(t, e, badID)
+
+	okID := e.Submit("ok", voice, cfg)
+	waitForTaskDeleted(t, e, okID)
+}
+
+func TestValidateConfigRequiresDefaultVoiceResourceID(t *testing.T) {
+	cfg := Config{
+		APIKey:   "key",
+		Endpoint: "https://example.com/tts",
+		DefaultVoice: &VoiceInfo{
+			VoiceType: "voice",
+		},
+	}
+
+	err := validateConfig(cfg)
+	if err == nil || !strings.Contains(err.Error(), "defaultVoice.resourceId") {
+		t.Fatalf("expected defaultVoice.resourceId error, got %v", err)
+	}
+}
+
+func TestValidateConfigRequiresSourceVoiceResourceID(t *testing.T) {
+	cfg := Config{
+		APIKey:   "key",
+		Endpoint: "https://example.com/tts",
+		DefaultVoice: &VoiceInfo{
+			VoiceType:  "voice",
+			ResourceID: "resource",
+		},
+		SourceVoices: map[string]*VoiceInfo{
+			"codex": {
+				VoiceType: "codex-voice",
+			},
+		},
+	}
+
+	err := validateConfig(cfg)
+	if err == nil || !strings.Contains(err.Error(), "sourceVoices.codex.resourceId") {
+		t.Fatalf("expected sourceVoices.codex.resourceId error, got %v", err)
+	}
+}
+
+type fakeStreamPlayer struct {
+	writeErr     bool
+	closeErr     bool
+	panicOnWrite bool
+	chunks       [][]byte
+	aborted      bool
+	closed       bool
+	closeBlock   chan struct{}
+	closeStarted chan struct{}
+	closeOnce    sync.Once
+}
+
+func newFakeStreamPlayerFactory() func() (StreamPlayer, error) {
+	return func() (StreamPlayer, error) {
+		return &fakeStreamPlayer{}, nil
+	}
+}
+
+func (p *fakeStreamPlayer) Write(audio []byte) error {
+	if p.panicOnWrite {
+		panic("boom")
+	}
+	if p.writeErr {
+		return errors.New("write failed")
+	}
+	p.chunks = append(p.chunks, append([]byte(nil), audio...))
+	return nil
+}
+
+func (p *fakeStreamPlayer) CloseAndWait() error {
+	p.closed = true
+	if p.closeStarted != nil {
+		p.closeStarted <- struct{}{}
+	}
+	if p.closeBlock != nil {
+		<-p.closeBlock
+	}
+	if p.closeErr {
+		return errors.New("close failed")
+	}
+	return nil
+}
+
+func (p *fakeStreamPlayer) Abort() error {
+	p.aborted = true
+	if p.closeBlock != nil {
+		p.closeOnce.Do(func() {
+			close(p.closeBlock)
+		})
+	}
+	return nil
+}
+
+func TestListenUnixSocketRemovesStalePath(t *testing.T) {
+	socketPath := shortSocketPath(t)
+	if err := os.WriteFile(socketPath, []byte("stale"), 0644); err != nil {
+		t.Fatalf("write stale socket path: %v", err)
+	}
+
+	listener, err := listenUnixSocket(socketPath)
+	if err != nil {
+		t.Fatalf("listen with stale socket path: %v", err)
+	}
+	defer listener.Close()
+}
+
+func TestListenUnixSocketDetectsRunningInstance(t *testing.T) {
+	socketPath := shortSocketPath(t)
+	listener, err := listenUnixSocket(socketPath)
+	if err != nil {
+		t.Fatalf("first listen: %v", err)
+	}
+	defer listener.Close()
+
+	done := make(chan struct{})
+	go func() {
+		conn, err := listener.Accept()
+		if err == nil {
+			_ = conn.Close()
+		}
+		close(done)
+	}()
+
+	second, err := listenUnixSocket(socketPath)
+	if second != nil {
+		_ = second.Close()
+	}
+	if !errors.Is(err, errAlreadyRunning) {
+		t.Fatalf("expected errAlreadyRunning, got %v", err)
+	}
+
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatalf("test listener did not accept probe connection")
+	}
+}
+
+func TestListenUnixSocketRemovesClosedListenerSocket(t *testing.T) {
+	socketPath := shortSocketPath(t)
+	stale, err := net.Listen("unix", socketPath)
+	if err != nil {
+		t.Fatalf("create stale listener: %v", err)
+	}
+	if err := stale.Close(); err != nil {
+		t.Fatalf("close stale listener: %v", err)
+	}
+
+	listener, err := listenUnixSocket(socketPath)
+	if err != nil {
+		t.Fatalf("listen after stale listener close: %v", err)
+	}
+	defer listener.Close()
+}
+
+func shortSocketPath(t *testing.T) string {
+	t.Helper()
+
+	dir, err := os.MkdirTemp("/tmp", "ispeak-*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = os.RemoveAll(dir)
+	})
+	return filepath.Join(dir, "sock")
+}
+
+func waitForTaskDeleted(t *testing.T, e *TaskEngine, id uint64) {
+	t.Helper()
+	waitFor(t, 2*time.Second, func() bool {
+		e.mu.Lock()
+		defer e.mu.Unlock()
+		_, ok := e.tasks[id]
+		return !ok
+	})
+}
+
+func waitFor(t *testing.T, timeout time.Duration, fn func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if fn() {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("condition not met within %s", timeout)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdfnet/ispeak",
-  "version": "1.6.9",
+  "version": "1.6.11",
   "description": "Local macOS TTS daemon for AI coding assistants, powered by Volcengine streaming TTS.",
   "license": "MIT",
   "homepage": "https://github.com/xdfnet/iSpeak#readme",
@@ -31,6 +31,12 @@
   "files": [
     "main.go",
     "clean_text.go",
+    "avaudioengine_player_darwin.go",
+    "stream_player_unsupported.go",
+    "main_test.go",
+    "Makefile",
+    "CLAUDE.md",
+    "AGENTS.md",
     "go.mod",
     "go.sum",
     "scripts/ispeak",

package/stream_player_unsupported.go

@@ -0,0 +1,9 @@
+//go:build !darwin || !cgo
+
+package main
+
+import "errors"
+
+func newDefaultStreamPlayer() (StreamPlayer, error) {
+	return nil, errors.New("AVAudioEngine 播放器仅支持 macOS 且需要启用 cgo")
+}