@xdfnet/ispeak 1.6.3 → 1.6.4

package/Docs/ARCHITECTURE.md

@@ -4,8 +4,8 @@
 
 iSpeak 是一个运行在 macOS 上的本地 TTS 播报守护进程，通过 Unix Socket 接收文本，调用火山引擎 TTS 流式 API，边合成边播放。
 
-当前版本采用“任务仓库 + 单 speak worker”流式链路：
-- speak worker：领取待合成任务，SSE 每到一段音频就写入播放器 stdin
+当前版本采用“任务仓库 + 单 transaction worker”流式链路：
+- transaction worker：领取待执行任务，SSE 每到一段音频就写入播放器 stdin
 - 播放器优先使用 `ffplay -i pipe:0`，没有 `ffplay` 时回退到完整音频 `afplay`
 
 ## 系统架构
@@ -28,15 +28,15 @@ iSpeak 是一个运行在 macOS 上的本地 TTS 播报守护进程，通过 Uni
 │  ┌───────────────────────────────────────────────────────┐  │
 │  │  Task Repository (in-memory)                         │  │
 │  │  - tasks: map[uint64]*Task                           │  │
-│  │  - pendingSynth: []uint64 (FIFO)                     │  │
+│  │  - pending: []uint64 (FIFO)                          │  │
 │  └───────────────────────────────────────────────────────┘  │
 │             │                                               │
 │             ▼                                               │
-│  Speak Worker (single)                                      │
-│  - pending_synth -> speaking                                │
+│  Transaction Worker (single)                               │
+│  - pending -> running                                      │
 │  - 调用 TTS 流式接口（失败直接删除，不重试）                  │
 │  - SSE audio chunk -> StreamPlayer.Write                    │
-│  - 播放完成后删除任务；连续失败删除任务                       │
+│  - 播放完成后删除任务；失败直接删除任务                       │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -48,7 +48,7 @@ iSpeak 是一个运行在 macOS 上的本地 TTS 播报守护进程，通过 Uni
 ```go
 type Task struct {
     ID     uint64     // 任务 ID（递增）
-    Text   string     // 过滤后的待合成文本
+    Text   string     // 过滤后的待执行文本
     Status TaskStatus // 当前状态
     Voice  VoiceInfo  // 任务音色快照
     Cfg    Config     // 任务配置快照（提交时）
@@ -59,8 +59,8 @@ type Task struct {
 
 ```go
 const (
-    TaskStatusPendingSynth TaskStatus = iota // 待合成
-    TaskStatusSpeaking                       // 流式合成播放中
+    TaskStatusPending TaskStatus = iota // 待执行
+    TaskStatusRunning                   // 合成播放事务执行中
 )
 ```
 
@@ -76,9 +76,9 @@ type TaskEngine struct {
 
     nextID       uint64
     tasks        map[uint64]*Task
-    pendingSynth []uint64
-
-    synthWake chan struct{}
+    latestID     uint64
+    pending      []uint64
+    wake chan struct{}
 
     synthesizeStreamFn func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error
     newStreamPlayerFn  func() (StreamPlayer, error)
@@ -100,30 +100,30 @@ type StreamPlayer interface {
 ### 状态流转
 
 ```
-pending_synth -> speaking -> delete
+pending -> running -> delete
 ```
 
 ### 任务提交（核心规则）
 
 `Submit(cleanedText, voice, cfg)` 原子执行：
-1. 删除所有 `pending_synth` 任务
-2. 打断当前 `speaking` 任务（取消合成/停止播放）
-3. 创建新任务（`pending_synth`）
-4. 唤醒 speak worker
+1. 删除所有 `pending` 任务
+2. 不打断当前 `running` 事务
+3. 创建新任务（`pending`）
+4. 唤醒 transaction worker
 
 策略说明：
-- 未开始合成的旧任务直接删除
-- 已领取但过期的旧任务在合成前跳过
-- 正在合成/播放的旧任务会被新消息取消
+- 未开始的旧任务直接删除
+- 已领取但过期的旧任务在事务执行前跳过
+- 正在合成/播放的任务自然结束
 
-### Speak worker 规则
+### Transaction worker 规则
 
-1. FIFO 领取 `pending_synth` 任务并置 `speaking`
+1. FIFO 领取 `pending` 任务并置 `running`
 2. 启动 `StreamPlayer`
 3. 调用 TTS 流式接口，SSE 每解析出一个音频 chunk 就写入播放器
 4. TTS 结束后关闭播放器 stdin 并等待播放结束
 5. 成功：删除任务
-6. 连续失败：删除任务
+6. 失败：删除任务，不重试
 
 ## 消息流程
 
@@ -150,7 +150,7 @@ pending_synth -> speaking -> delete
 
 ### 2. 流式合成播放阶段
 
-- speak worker 领取任务
+- transaction worker 领取任务
 - HTTP POST 火山引擎 TTS 接口
 - 解析 SSE 流并 base64 解码音频 chunk
 - 优先将 chunk 写入 `ffplay` stdin 实时播放
@@ -160,13 +160,13 @@ pending_synth -> speaking -> delete
 ## 并发与一致性
 
 - 单引擎锁 `mu` 保护任务仓库与 FIFO 队列
-- 单 speak worker，保证播报顺序稳定
-- `synthWake` 为缓冲 1 的唤醒信号，防止重复唤醒堆积
+- 单 transaction worker，保证播报顺序稳定
+- `wake` 为缓冲 1 的唤醒信号，防止重复唤醒堆积
 - FIFO 保证未开始任务公平顺序
 
 ## 失败与成本策略
 
-- 新任务到达时清理 `pending_synth` 并打断当前任务，避免无效合成/播放
+- 新任务到达时只清理 `pending`，不打断当前任务
 - 流式合成/播放失败：直接删除任务，不重试，避免重复播报
 - 只保留最新消息优先播报，降低 TTS 成本
 

package/README.md

@@ -26,8 +26,8 @@ ispeak-codex "构建完成，耗时 12 秒"
 
 | 问题 | 方案 |
 |------|------|
-| AI 生成多条回复，TTS 账单飞涨 | 新消息只保留最新待合成任务，避免无效合成 |
-| 回复快慢不一，音频播报乱序 | 单 speak worker，FIFO 顺序稳定 |
+| AI 生成多条回复，TTS 账单飞涨 | 新消息只保留最新待执行任务，避免无效合成 |
+| 回复快慢不一，音频播报乱序 | 单 transaction worker，FIFO 顺序稳定 |
 | 修改配置要重启服务 | 热更新：编辑 `config.json` 立即生效 |
 | 默认音色太无聊 | 来源专属音色，Claude 和 Codex 声音不同 |
 
@@ -72,7 +72,7 @@ ispeak "iSpeak 准备好了"
 │         │                                            │
 │         ▼                                           │
 │   任务引擎                                           │
-│   （pending_synth → speaking → delete）              │
+│   （pending → running → delete）              │
 │         │                                            │
 │         ▼                                           │
 │   单 Worker 流式链路                                 │
@@ -86,10 +86,10 @@ ispeak "iSpeak 准备好了"
 
 **任务状态流转：**
 ```
-pending_synth → speaking → delete
+pending → running → delete
 ```
 
-新消息到达时会清理未开始任务，并打断当前合成/播放，只保留最新消息优先播报。
+新消息到达时只清理未开始任务，不打断当前合成/播放；当前事务结束后再播最新消息。
 
 ## 语音清洗规则
 

package/main.go

@@ -200,12 +200,12 @@ func (p *bufferedStreamPlayer) Abort() error {
 }
 
 // 任务状态
-// 生命周期：pending_synth -> speaking -> delete
+// 生命周期：pending -> running -> delete
 type TaskStatus int
 
 const (
-	TaskStatusPendingSynth TaskStatus = iota
-	TaskStatusSpeaking
+	TaskStatusPending TaskStatus = iota
+	TaskStatusRunning
 )
 
 // 单个 TTS 任务
@@ -217,18 +217,16 @@ type Task struct {
 	Cfg    Config
 }
 
-// 任务引擎：任务仓库 + 单流式合成播放 worker
+// 任务引擎：任务仓库 + 单事务 worker
 type TaskEngine struct {
 	mu sync.Mutex
 
-	nextID       uint64
-	latestID     uint64
-	tasks        map[uint64]*Task
-	pendingSynth []uint64
-	activeID     uint64
-	activeCancel context.CancelFunc
+	nextID   uint64
+	latestID uint64
+	tasks    map[uint64]*Task
+	pending  []uint64
 
-	synthWake chan struct{}
+	wake chan struct{}
 
 	synthesizeStreamFn func(ctx context.Context, cfg Config, text string, voice *VoiceInfo, onAudio func([]byte) error) error
 	newStreamPlayerFn  func() (StreamPlayer, error)
@@ -237,67 +235,58 @@ type TaskEngine struct {
 func NewTaskEngine() *TaskEngine {
 	return &TaskEngine{
 		tasks:              make(map[uint64]*Task),
-		synthWake:          make(chan struct{}, 1),
+		wake:               make(chan struct{}, 1),
 		synthesizeStreamFn: synthesizeStream,
 		newStreamPlayerFn:  newDefaultStreamPlayer,
 	}
 }
 
 func (e *TaskEngine) Start() {
-	go e.speakWorker()
+	go e.transactionWorker()
 }
 
 func (e *TaskEngine) Submit(text string, voice VoiceInfo, cfg Config) uint64 {
 	e.mu.Lock()
 
-	// 新任务进来先删所有未开始合成任务
-	for _, id := range e.pendingSynth {
+	// 新任务进来先删所有未开始的任务。
+	for _, id := range e.pending {
 		delete(e.tasks, id)
-		log.Printf("删除待合成任务: id=%d", id)
-	}
-	e.pendingSynth = e.pendingSynth[:0]
-
-	cancelActive := e.activeCancel
-	activeID := e.activeID
-	if activeID != 0 {
-		log.Printf("打断当前播报任务: id=%d", activeID)
+		log.Printf("删除待执行任务: id=%d", id)
 	}
+	e.pending = e.pending[:0]
 
 	e.nextID++
 	task := &Task{
 		ID:     e.nextID,
 		Text:   text,
-		Status: TaskStatusPendingSynth,
+		Status: TaskStatusPending,
 		Voice:  voice,
 		Cfg:    cfg,
 	}
 	e.tasks[task.ID] = task
 	e.latestID = task.ID
-	e.pendingSynth = append(e.pendingSynth, task.ID)
+	e.pending = append(e.pending, task.ID)
 	log.Printf("任务创建: id=%d text=%s", task.ID, text)
 
-	notify(e.synthWake)
+	notify(e.wake)
 	e.mu.Unlock()
 
-	if cancelActive != nil {
-		cancelActive()
-	}
 	return task.ID
 }
 
-func (e *TaskEngine) speakWorker() {
+func (e *TaskEngine) transactionWorker() {
 	for {
-		id := e.claimPendingSynth()
+		id := e.claimPending()
 		if id == 0 {
-			<-e.synthWake
+			<-e.wake
 			continue
 		}
 
-		e.processSpeakTask(id)
+		e.processTransaction(id)
 	}
 }
 
-func (e *TaskEngine) processSpeakTask(id uint64) {
+func (e *TaskEngine) processTransaction(id uint64) {
 	defer func() {
 		if r := recover(); r != nil {
 			log.Printf("播报任务崩溃并删除: id=%d err=%v", id, r)
@@ -305,27 +294,18 @@ func (e *TaskEngine) processSpeakTask(id uint64) {
 		}
 	}()
 
-	ctx, cancel := context.WithCancel(context.Background())
-	e.setActiveTask(id, cancel)
-	defer e.clearActiveTask(id)
-
 	task, ok := e.getTask(id)
 	if !ok {
 		return
 	}
 	if !e.isLatestTask(id) {
-		cancel()
 		log.Printf("跳过过期播报任务: id=%d", id)
 		e.deleteTask(id)
 		return
 	}
 
-	if err := e.speakOnce(ctx, task); err != nil {
-		if errors.Is(err, context.Canceled) {
-			log.Printf("播报已打断并删除任务: id=%d", id)
-		} else {
-			log.Printf("播报失败并删除任务: id=%d err=%v", id, err)
-		}
+	if err := e.runTransaction(task); err != nil {
+		log.Printf("播报失败并删除任务: id=%d err=%v", id, err)
 		e.deleteTask(id)
 		return
 	}
@@ -334,7 +314,7 @@ func (e *TaskEngine) processSpeakTask(id uint64) {
 	e.deleteTask(id)
 }
 
-func (e *TaskEngine) speakOnce(ctx context.Context, task *Task) error {
+func (e *TaskEngine) runTransaction(task *Task) error {
 	startedAt := time.Now()
 	player, err := e.newStreamPlayerFn()
 	if err != nil {
@@ -350,45 +330,34 @@ func (e *TaskEngine) speakOnce(ctx context.Context, task *Task) error {
 		return player.Write(audio)
 	}
 
-	if err := e.synthesizeStreamFn(ctx, task.Cfg, task.Text, &task.Voice, onAudio); err != nil {
+	if err := e.synthesizeStreamFn(context.Background(), task.Cfg, task.Text, &task.Voice, onAudio); err != nil {
 		_ = player.Abort()
 		return err
 	}
 	log.Printf("TTS 流结束: id=%d elapsed=%s", task.ID, time.Since(startedAt).Round(time.Millisecond))
 
-	done := make(chan error, 1)
-	go func() {
-		done <- player.CloseAndWait()
-	}()
-	select {
-	case err := <-done:
-		if err != nil {
-			_ = player.Abort()
-			return err
-		}
-	case <-ctx.Done():
+	if err := player.CloseAndWait(); err != nil {
 		_ = player.Abort()
-		<-done
-		return ctx.Err()
+		return err
 	}
 	return nil
 }
 
-func (e *TaskEngine) claimPendingSynth() uint64 {
+func (e *TaskEngine) claimPending() uint64 {
 	e.mu.Lock()
 	defer e.mu.Unlock()
 
-	for len(e.pendingSynth) > 0 {
-		id := e.pendingSynth[0]
-		e.pendingSynth = e.pendingSynth[1:]
+	for len(e.pending) > 0 {
+		id := e.pending[0]
+		e.pending = e.pending[1:]
 		task, ok := e.tasks[id]
 		if !ok {
 			continue
 		}
-		if task.Status != TaskStatusPendingSynth {
+		if task.Status != TaskStatusPending {
 			continue
 		}
-		task.Status = TaskStatusSpeaking
+		task.Status = TaskStatusRunning
 		return id
 	}
 	return 0
@@ -412,22 +381,6 @@ func (e *TaskEngine) deleteTask(id uint64) {
 	delete(e.tasks, id)
 }
 
-func (e *TaskEngine) setActiveTask(id uint64, cancel context.CancelFunc) {
-	e.mu.Lock()
-	defer e.mu.Unlock()
-	e.activeID = id
-	e.activeCancel = cancel
-}
-
-func (e *TaskEngine) clearActiveTask(id uint64) {
-	e.mu.Lock()
-	defer e.mu.Unlock()
-	if e.activeID == id {
-		e.activeID = 0
-		e.activeCancel = nil
-	}
-}
-
 func (e *TaskEngine) isLatestTask(id uint64) bool {
 	e.mu.Lock()
 	defer e.mu.Unlock()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdfnet/ispeak",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "description": "Local macOS TTS daemon for AI coding assistants, powered by Volcengine streaming TTS.",
   "license": "MIT",
   "homepage": "https://github.com/xdfnet/iSpeak#readme",