@xdfnet/ispeak 1.6.5 → 1.6.7

package/Docs/ARCHITECTURE.md

@@ -177,7 +177,7 @@ pending -> running -> delete
 ├── config.json      # API Key、音色配置
 ├── ispeak.sock      # Unix Socket
 ├── ispeak.log       # 日志（lumberjack 轮转）
-└── hook-speak.sh    # Claude/Codex Stop Hook
+└── hook-speak.sh    # Claude/Codex Hook
 
 ~/Library/LaunchAgents/
 └── com.iSpeak.plist # launchd 服务配置

package/Docs/HOOK_TEXT_EXTRACTION.md

@@ -0,0 +1,241 @@
+# Hook 文本提取链路
+
+本文记录 Claude Code / Codex CLI 在 Hook 中拿到“最后一条 assistant 回复”的实际方式。`hook-speak.sh` 的目标只做两件事：取最后一条 assistant 回复，发给 iSpeak socket。
+
+## 结论
+
+推荐优先级：
+
+1. **Codex `notify`**：从脚本第二个参数 `$2` 读取 JSON，取 `last-assistant-message`。
+2. **Claude / Codex Stop Hook**：从 stdin 读取 JSON，优先取 `last_assistant_message`。
+3. **明确 transcript**：如果没有直接字段，只读取 payload 里明确传入的 `transcript_path`。
+
+不扫描 `~/.codex/sessions`。没有 direct 字段也没有 `transcript_path` 时，本次不播报。
+
+## Codex CLI：notify
+
+当前本机版本：
+
+```text
+codex-cli 0.130.0
+```
+
+Codex CLI 的 `notify = [...]` 是 legacy notify 机制。官方源码里会把通知 JSON 追加成命令的最后一个 argv 参数，不写 stdin。
+
+配置示例：
+
+```toml
+notify = ["/Users/你的用户名/.config/iSpeak/hook-speak.sh", "codex"]
+```
+
+脚本实际收到：
+
+```bash
+$1 = "codex"
+$2 = '{"type":"agent-turn-complete",...,"last-assistant-message":"..."}'
+stdin = empty
+```
+
+核心字段：
+
+```json
+{
+  "type": "agent-turn-complete",
+  "thread-id": "...",
+  "turn-id": "...",
+  "cwd": "...",
+  "input-messages": ["..."],
+  "last-assistant-message": "最后一条 assistant 回复"
+}
+```
+
+所以 Codex `notify` 的正确读取方式是：
+
+```bash
+input="${2:-}"
+```
+
+然后解析：
+
+```js
+payload["last-assistant-message"]
+```
+
+源码依据：`codex-rs/hooks/src/legacy_notify.rs`。该文件把 `last_assistant_message` 序列化为 kebab-case 的 `last-assistant-message`，并在执行命令前 `command.arg(notify_payload)`。
+
+## Codex CLI：Stop Hook
+
+Codex 也支持 Claude 风格 Hook。Stop Hook 的输入 JSON 写入 stdin。
+
+配置示例：
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $HOME/.config/iSpeak/hook-speak.sh codex",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+脚本实际收到：
+
+```bash
+$1 = "codex"
+$2 = empty
+stdin = '{"hook_event_name":"Stop",...,"last_assistant_message":"..."}'
+```
+
+核心字段：
+
+```json
+{
+  "session_id": "...",
+  "turn_id": "...",
+  "transcript_path": "...",
+  "cwd": "...",
+  "hook_event_name": "Stop",
+  "model": "...",
+  "permission_mode": "bypassPermissions",
+  "stop_hook_active": false,
+  "last_assistant_message": "最后一条 assistant 回复"
+}
+```
+
+源码依据：
+
+- `codex-rs/hooks/src/events/stop.rs`：构造 `StopCommandInput`，包含 `last_assistant_message` 和 `transcript_path`。
+- `codex-rs/hooks/schema/generated/stop.command.input.schema.json`：Stop stdin schema。
+- `codex-rs/hooks/src/engine/command_runner.rs`：Hook 命令通过 stdin 接收 `input_json`。
+
+## Codex Transcript
+
+Codex 的 transcript/session 文件是 JSONL。实际 assistant 回复形态：
+
+```json
+{
+  "type": "response_item",
+  "payload": {
+    "type": "message",
+    "role": "assistant",
+    "content": [
+      {
+        "type": "output_text",
+        "text": "最后一条 assistant 回复"
+      }
+    ]
+  }
+}
+```
+
+提取规则：
+
+```js
+event.type === "response_item" &&
+event.payload?.type === "message" &&
+event.payload?.role === "assistant"
+```
+
+然后拼接：
+
+```js
+event.payload.content[].text
+```
+
+## Claude Code：Stop Hook
+
+Claude Code 官方 Stop Hook 通过 stdin 传 JSON，核心字段是：
+
+```json
+{
+  "session_id": "...",
+  "transcript_path": "...",
+  "hook_event_name": "Stop",
+  "stop_hook_active": false
+}
+```
+
+有些版本或场景可能直接提供：
+
+```json
+{
+  "last_assistant_message": "最后一条 assistant 回复"
+}
+```
+
+所以 Claude 的读取顺序是：
+
+1. `last_assistant_message`
+2. `message`
+3. `transcript_path`
+
+Claude transcript 常见 assistant 形态：
+
+```json
+{"role":"assistant","content":[{"type":"text","text":"..."}]}
+```
+
+或：
+
+```json
+{"message":{"role":"assistant","content":[{"type":"text","text":"..."}]}}
+```
+
+## 当前脚本策略
+
+`configs/hook-speak.sh` 当前入口：
+
+```bash
+input="${2:-}"
+if [[ -z "$input" ]]; then
+  input=$(cat)
+fi
+```
+
+含义：
+
+- Codex `notify`：读 `$2`
+- Claude / Codex Stop Hook：读 stdin
+- 如果 Codex 的 `notify` 和 `Stop` 同时启用，脚本会按 `turn_id` 去重，避免同一回合播两次
+
+Codex 文本字段优先级：
+
+```js
+payload["last-assistant-message"]
+payload.last_assistant_message
+payload.lastAssistantMessage
+payload.message
+payload.lastMessage
+payload.transcript_path
+payload.transcriptPath
+payload["transcript-path"]
+```
+
+Claude 文本字段优先级：
+
+```js
+payload.last_assistant_message
+payload.message
+payload.transcript_path
+payload.transcriptPath
+```
+
+## 为什么不能只读 stdin
+
+因为 Codex `notify` 不走 stdin。只读 stdin 会导致：
+
+```text
+TEXT_LEN: 0
+SPOKE: SKIP
+```
+
+正确做法是先读 `$2`，再读 stdin；不扫历史 session。

package/README.md

@@ -1,13 +1,13 @@
 # iSpeak
 
-![Version](https://img.shields.io/badge/version-1.6.3-blue)
+![Version](https://img.shields.io/badge/version-1.6.7-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)
 
 iSpeak 让 AI 编程助手开口说话。你写代码，它播结果——眼睛休息，耳朵来听。
 
-适合 Claude Code 或 Codex 常驻后台的开发者。AI 完成任务后自动播报；你发新消息时，旧播报立即中断，不花冤枉钱。
+适合 Claude Code 或 Codex 常驻后台的开发者。AI 完成任务后自动播报；你发新消息时，未开始的旧播报会被丢弃，不花冤枉钱。
 
 ## 效果示例
 
@@ -39,11 +39,7 @@ ispeak-codex "构建完成，耗时 12 秒"
 npm i -g @xdfnet/ispeak
 ```
 
-当前 npm 安装会在本机编译 `ispeakd`，需要已安装 Go。没有 `ffplay` 时会自动回退 `afplay`；推荐安装 `ffmpeg` 获得流式播放：
-
-```bash
-brew install ffmpeg
-```
+当前 npm 安装会在本机编译 `ispeakd`，需要已安装 Go。主播放链路使用 macOS 原生 `AVAudioEngine`，不依赖 `ffmpeg`。失败时直接记录日志并删除任务。
 
 **源码安装：**
 
@@ -76,11 +72,11 @@ ispeak "iSpeak 准备好了"
 │         │                                            │
 │         ▼                                           │
 │   单 Worker 流式链路                                 │
-│   （SSE audio chunk → 播放器 stdin）                  │
+│   （SSE PCM chunk → AVAudioEngine）                 │
 │         │                                            │
 │         ▼                                           │
-│   流式播放器                                         │
-│   （优先 ffplay stdin，无 ffplay 回退 afplay）         │
+│   错误处理                                          │
+│   （失败时记录日志并删除任务）                        │
 └─────────────────────────────────────────────────────┘
 ```
 
@@ -104,8 +100,7 @@ pending → running → delete
 - Markdown 链接：只保留链接标题，不播 URL
 - 绝对路径：简化为“路径”
 - 长 commit hash、UUID、长 ID：不播
-- 明显文件列表：如模型分片、代码文件列表、下载文件清单
-- 下载进度和终端噪声：百分比、速度、进度条、ANSI 控制符
+- 下载进度噪声：速度、ETA、预计剩余时间、ANSI 控制符
 
 保留优先级：结论、成功/失败状态、需要用户操作的下一步、关键错误原因。
 
@@ -131,7 +126,7 @@ ispeak-codex "消息"    # Codex 专属音色
 ```json
 {
   "apiKey": "你的火山引擎 API Key",
-  "endpoint": "https://openspeech.bytedance.com/api/v3/tts/unidirectional",
+  "endpoint": "https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse",
   "defaultVoice": {
     "voice_type": "zh_female_mizai_uranus_bigtts",
     "resourceId": "seed-tts-2.0"
@@ -173,7 +168,13 @@ ispeak-codex "消息"    # Codex 专属音色
 
 ### Codex
 
-在 `~/.codex/hooks.json` 中添加 Stop Hook：
+推荐在 `~/.codex/config.toml` 中添加回合结束通知：
+
+```toml
+notify = ["bash", "/Users/你的用户名/.config/iSpeak/hook-speak.sh", "codex"]
+```
+
+如果你启用了 Codex hooks，也可以在 `~/.codex/hooks.json` 中添加 Stop Hook：
 
 ```json
 {
@@ -189,6 +190,8 @@ ispeak-codex "消息"    # Codex 专属音色
 }
 ```
 
+`hook-speak.sh` 会按 `turn_id` 做一次去重，所以即使 `notify` 和 `Stop` 都启用，同一回合也只会播一次。
+
 ## 开发命令
 
 ```bash

package/clean_text.go

@@ -0,0 +1,153 @@
+package main
+
+import (
+	"regexp"
+	"strings"
+)
+
+var (
+	markdownLinkRe     = regexp.MustCompile(`\[[^\]]+\]\(([^)]*)\)`)
+	absolutePathRe     = regexp.MustCompile(`/(?:Users|private|tmp|var|opt|usr|bin|sbin|etc|Library|Applications)/\S+`)
+	commitHashRe       = regexp.MustCompile(`\b[0-9a-f]{7,40}\b`)
+	uuidRe             = regexp.MustCompile(`\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b`)
+	urlRe              = regexp.MustCompile(`https?://\S+`)
+	ansiEscapeRe       = regexp.MustCompile(`\x1b\[[0-9;]*[A-Za-z]`)
+	multiSpaceRe       = regexp.MustCompile(`\s+`)
+	markdownListRe     = regexp.MustCompile(`^\s*(?:[-*+]\s+|\d+[.)]\s+)`)
+	htmlTagRe          = regexp.MustCompile(`<[^>]+>`)
+	codeFenceStartRe   = regexp.MustCompile("^```")
+	artifactStartRe    = regexp.MustCompile(`(?i)^<artifact\b`)
+	htmlDocumentLineRe = regexp.MustCompile(`(?i)^<!doctype html|^<html\b|^<head\b|^<body\b|^<style\b|^</`)
+	speedNoiseRe       = regexp.MustCompile(`(?i)\d+(?:\.\d+)?\s*(?:kb|mb|gb)/s`)
+	etaNoiseRe         = regexp.MustCompile(`(?i)\bETA\b|预计剩余|剩余时间`)
+)
+
+// 过滤格式符号，保留自然朗读文本。
+// 顺序很重要：先跳过跨行块结构，再跳过整行噪声，最后清理行内符号。
+func cleanText(text string) string {
+	var lines []string
+	rawLines := strings.Split(text, "\n")
+	inCodeBlock := false
+	inArtifact := false
+	inMarkdownTable := false
+	for i := 0; i < len(rawLines); i++ {
+		line := rawLines[i]
+		line = strings.TrimSpace(line)
+		if line == "" {
+			inMarkdownTable = false
+			continue
+		}
+		if codeFenceStartRe.MatchString(line) {
+			inCodeBlock = !inCodeBlock
+			continue
+		}
+		if inCodeBlock {
+			continue
+		}
+		if artifactStartRe.MatchString(line) {
+			inArtifact = !strings.Contains(strings.ToLower(line), "</artifact>")
+			continue
+		}
+		if inArtifact {
+			if strings.Contains(strings.ToLower(line), "</artifact>") {
+				inArtifact = false
+			}
+			continue
+		}
+		if isMarkdownTableSeparator(line) {
+			if len(lines) > 0 && isMarkdownTableRow(strings.TrimSpace(rawLines[i-1])) {
+				lines = lines[:len(lines)-1]
+			}
+			inMarkdownTable = true
+			continue
+		}
+		if inMarkdownTable {
+			if isMarkdownTableRow(line) {
+				continue
+			}
+			inMarkdownTable = false
+		}
+		if shouldSkipSpeechLine(line) {
+			continue
+		}
+
+		cleaned := cleanSpeechLine(line)
+		if cleaned != "" {
+			lines = append(lines, cleaned)
+		}
+	}
+	return strings.Join(lines, "，")
+}
+
+func shouldSkipSpeechLine(line string) bool {
+	if isMarkdownTableSeparator(line) {
+		return true
+	}
+	if strings.HasPrefix(line, "---") && strings.Count(line, "-") > 3 {
+		return true
+	}
+	if htmlDocumentLineRe.MatchString(line) {
+		return true
+	}
+	if isProgressNoiseLine(line) {
+		return true
+	}
+	if isMostlyTableRow(line) {
+		return true
+	}
+	return false
+}
+
+func isMarkdownTableSeparator(line string) bool {
+	line = strings.TrimSpace(line)
+	return strings.Contains(line, "|") && strings.Trim(line, "|-: ") == ""
+}
+
+func isMarkdownTableRow(line string) bool {
+	line = strings.TrimSpace(line)
+	return strings.Count(line, "|") >= 2
+}
+
+func cleanSpeechLine(line string) string {
+	// Markdown 链接必须在 URL 删除前处理，否则会丢掉链接标题。
+	line = ansiEscapeRe.ReplaceAllString(line, "")
+	line = markdownListRe.ReplaceAllString(line, "")
+	line = markdownLinkRe.ReplaceAllStringFunc(line, func(match string) string {
+		if end := strings.Index(match, "]"); end > 1 {
+			return match[1:end]
+		}
+		return ""
+	})
+	line = urlRe.ReplaceAllString(line, "")
+	line = absolutePathRe.ReplaceAllString(line, " 路径 ")
+	// UUID 必须在短 hash 前处理，避免先删短片段后破坏 UUID 识别。
+	line = uuidRe.ReplaceAllString(line, "")
+	line = commitHashRe.ReplaceAllString(line, "")
+	line = htmlTagRe.ReplaceAllString(line, "")
+	line = strings.NewReplacer(
+		"**", "",
+		"*", "",
+		"`", "",
+		"#", "",
+		">", "",
+		"✅", "",
+		"❌", "",
+		"✓", "",
+		"✗", "",
+		"→", "到",
+	).Replace(line)
+	line = strings.Trim(line, " \t-:|")
+	line = multiSpaceRe.ReplaceAllString(line, " ")
+	return strings.TrimSpace(line)
+}
+
+func isMostlyTableRow(line string) bool {
+	if !strings.Contains(line, "|") {
+		return false
+	}
+	return strings.Count(line, "|") >= 2 && len([]rune(line)) > 40
+}
+
+func isProgressNoiseLine(line string) bool {
+	return speedNoiseRe.MatchString(line) || etaNoiseRe.MatchString(line)
+}

package/configs/config.example.json

@@ -1,6 +1,6 @@
 {
   "apiKey": "your-api-key",
-  "endpoint": "https://openspeech.bytedance.com/api/v3/tts/unidirectional",
+  "endpoint": "https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse",
   "defaultVoice": {
     "voice_type": "zh_female_mizai_uranus_bigtts",
     "resourceId": "seed-tts-2.0"