@xdfnet/ispeak 1.6.8 → 1.6.10

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/README.md

@@ -1,6 +1,6 @@
 # iSpeak
 
-![Version](https://img.shields.io/badge/version-1.6.8-blue)
+![Version](https://img.shields.io/badge/version-1.6.9-blue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Go Version](https://img.shields.io/badge/Go-1.26-blue)](https://golang.org/dl/)
 ![Platform](https://img.shields.io/badge/platform-macOS-green)

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/configs/hook-speak.sh

@@ -52,7 +52,7 @@ function lastClaudeAssistant(payload) {
   if (direct) return { text: direct, turnId: extractTurnId(payload) };
 
   const transcript = firstString(payload.transcript_path, payload.transcriptPath);
-  return transcript ? lastAssistantFromTranscript(transcript, "claude") : { text: "", turnId: extractTurnId(payload) };
+  return transcript ? lastClaudeTranscript(transcript, payload) : { text: "", turnId: extractTurnId(payload) };
 }
 
 function lastCodexAssistant(payload) {
@@ -98,11 +98,29 @@ function firstString(...values) {
 
 function collectText(content) {
   if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .map(item => item && typeof item.text === "string" ? item.text : "")
-    .filter(Boolean)
-    .join(" ");
+  if (Array.isArray(content)) {
+    return content
+      .map(item => collectText(item))
+      .filter(Boolean)
+      .join(" ");
+  }
+  if (!content || typeof content !== "object") return "";
+  if (typeof content.text === "string") return content.text;
+  if (content.content) return collectText(content.content);
+  return "";
+}
+
+function lastClaudeTranscript(file, payload) {
+  const deadline = Date.now() + 1200;
+  let result = { text: "", turnId: extractTurnId(payload) };
+
+  while (Date.now() <= deadline) {
+    result = lastAssistantFromTranscript(file, "claude");
+    if (result.text) return result;
+    sleepMs(120);
+  }
+
+  return result;
 }
 
 function lastAssistantFromTranscript(file, source) {
@@ -179,6 +197,10 @@ function textHash(text) {
   return crypto.createHash("sha1").update(text, "utf8").digest("hex");
 }
 
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 NODE
 )
 
@@ -192,6 +214,23 @@ echo "SOURCE: $SOURCE" >> "$LOG"
 echo "TEXT_LEN: ${#result}" >> "$LOG"
 echo "PREVIEW: ${result:0:150}" >> "$LOG"
 
+# Claude Code Stop Hook 调试
+if [[ "$SOURCE" == "claude" && -n "$input" ]]; then
+  # 用 grep 提取 transcript_path
+  tp=$(echo "$input" | grep -o '"transcript_path":"[^"]*"' | head -1 | sed 's/"transcript_path":"//;s/"$//')
+  if [[ -n "$tp" ]]; then
+    echo "CLAUDE_TRANSCRIPT_PATH: $tp" >> "$LOG"
+    if [[ -f "$tp" ]]; then
+      echo "CLAUDE_TRANSCRIPT_EXISTS: yes" >> "$LOG"
+    else
+      echo "CLAUDE_TRANSCRIPT_EXISTS: no" >> "$LOG"
+    fi
+  else
+    echo "CLAUDE_TRANSCRIPT_PATH: none" >> "$LOG"
+    echo "CLAUDE_RAW: ${input:0:300}" >> "$LOG"
+  fi
+fi
+
 if [[ -n "$result" && -S "$SOCK" ]]; then
   printf "{source:%s}%s" "$SOURCE" "$result" | nc -U -w5 "$SOCK" 2>> "$LOG"
   echo "SPOKE: OK" >> "$LOG"