@xdfnet/ispeak 1.6.7 → 1.6.9

package/README.md

@@ -1,6 +1,6 @@
 # iSpeak
 
-![Version](https://img.shields.io/badge/version-1.6.7-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)
@@ -14,12 +14,6 @@ iSpeak 让 AI 编程助手开口说话。你写代码，它播结果——眼睛
 ```
 # 默认音色：温柔女声
 ispeak "Pull request 已合并，3 个测试通过"
-
-# Claude 模式：专属音色
-ispeak-claude "Code review 完成，发现 2 处可优化"
-
-# Codex 模式：另一种音色
-ispeak-codex "构建完成，耗时 12 秒"
 ```
 
 ## 为什么选 iSpeak
@@ -29,7 +23,7 @@ ispeak-codex "构建完成，耗时 12 秒"
 | AI 生成多条回复，TTS 账单飞涨 | 新消息只保留最新待执行任务，避免无效合成 |
 | 回复快慢不一，音频播报乱序 | 单 transaction worker，FIFO 顺序稳定 |
 | 修改配置要重启服务 | 热更新：编辑 `config.json` 立即生效 |
-| 默认音色太无聊 | 来源专属音色，Claude 和 Codex 声音不同 |
+| 默认音色太无聊 | hook 按来源前缀选择音色 |
 
 ## 快速上手
 
@@ -113,12 +107,6 @@ ispeak restart   # 重启服务
 ispeak version   # 版本
 ```
 
-语音专属快捷命令（指向 ispeak 的软链接）：
-```bash
-ispeak-claude "消息"   # Claude 专属音色
-ispeak-codex "消息"    # Codex 专属音色
-```
-
 ## 配置说明
 
 `~/.config/iSpeak/config.json`：
@@ -148,49 +136,9 @@ ispeak-codex "消息"    # Codex 专属音色
 
 ## 集成说明
 
-### Claude Code
-
-在 `~/.claude/settings.json` 中添加 Stop Hook：
-
-```json
-{
-  "hooks": {
-    "Stop": [{
-      "hooks": [{
-        "type": "command",
-        "command": "bash $HOME/.config/iSpeak/hook-speak.sh claude",
-        "timeout": 30
-      }]
-    }]
-  }
-}
-```
-
-### Codex
-
-推荐在 `~/.codex/config.toml` 中添加回合结束通知：
-
-```toml
-notify = ["bash", "/Users/你的用户名/.config/iSpeak/hook-speak.sh", "codex"]
-```
-
-如果你启用了 Codex hooks，也可以在 `~/.codex/hooks.json` 中添加 Stop Hook：
-
-```json
-{
-  "hooks": {
-    "Stop": [{
-      "hooks": [{
-        "type": "command",
-        "command": "bash $HOME/.config/iSpeak/hook-speak.sh codex",
-        "timeout": 30
-      }]
-    }]
-  }
-}
-```
+Claude Code 和 Codex 的详细 hook 配置见 [docs/hook-text-extraction.md](/Users/admin/iCode/iSpeak/docs/hook-text-extraction.md)。
 
-`hook-speak.sh` 会按 `turn_id` 做一次去重，所以即使 `notify` 和 `Stop` 都启用，同一回合也只会播一次。
+`hook-speak.sh` 会按 `turn_id` 做一次去重，所以同一回合不会播两次。
 
 ## 开发命令
 
@@ -207,7 +155,7 @@ make help       # 显示帮助
 
 | 文件 | 用途 |
 |------|------|
-| `~/Library/LaunchAgents/com.iSpeak.plist` | macOS 自动启动服务 |
+| `~/Library/LaunchAgents/com.ispeak.plist` | macOS 自动启动服务 |
 | `~/.config/iSpeak/ispeak.sock` | Unix Socket |
 | `~/.config/iSpeak/ispeak.log` | 日志（轮转） |
 | `~/.config/iSpeak/config.json` | 你的 API Key 和音色配置 |

package/configs/{com.iSpeak.plist → com.ispeak.plist}

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
     <key>Label</key>
-    <string>com.iSpeak</string>
+    <string>com.ispeak</string>
     <key>ProgramArguments</key>
     <array>
         <string>BINARY_PATH_PLACEHOLDER</string>

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"

package/{Docs/ARCHITECTURE.md → docs/architecture.md}

@@ -180,7 +180,7 @@ pending -> running -> delete
 └── hook-speak.sh    # Claude/Codex Hook
 
 ~/Library/LaunchAgents/
-└── com.iSpeak.plist # launchd 服务配置
+└── com.ispeak.plist # launchd 服务配置
 ```
 
 ## 稳定性设计

package/{Docs/HOOK_TEXT_EXTRACTION.md → docs/hook-text-extraction.md}

@@ -6,9 +6,9 @@
 
 推荐优先级：
 
-1. **Codex `notify`**：从脚本第二个参数 `$2` 读取 JSON，取 `last-assistant-message`。
-2. **Claude / Codex Stop Hook**：从 stdin 读取 JSON，优先取 `last_assistant_message`。
-3. **明确 transcript**：如果没有直接字段，只读取 payload 里明确传入的 `transcript_path`。
+1. **Codex `notify`**：从脚本第二个参数 `$2` 读取 JSON，取 `last-assistant-message`（kebab-case）。
+2. **Codex Stop Hook**：从 stdin 读取 JSON，取 `last_assistant_message`（snake_case）。
+3. **Claude Code Stop Hook**：从 stdin 读取 JSON，只读 `transcript_path`（官方无 direct 字段）。
 
 不扫描 `~/.codex/sessions`。没有 direct 字段也没有 `transcript_path` 时，本次不播报。
 
@@ -61,7 +61,7 @@ input="${2:-}"
 payload["last-assistant-message"]
 ```
 
-源码依据：`codex-rs/hooks/src/legacy_notify.rs`。该文件把 `last_assistant_message` 序列化为 kebab-case 的 `last-assistant-message`，并在执行命令前 `command.arg(notify_payload)`。
+源码依据：`codex-rs/hooks/src/legacy_notify.rs`（https://github.com/openai/codex，2026-05-11）。该文件把 `last_assistant_message` 序列化为 kebab-case 的 `last-assistant-message`，并在执行命令前 `command.arg(notify_payload)`。
 
 ## Codex CLI：Stop Hook
 
@@ -95,7 +95,23 @@ $2 = empty
 stdin = '{"hook_event_name":"Stop",...,"last_assistant_message":"..."}'
 ```
 
-核心字段：
+核心字段（源码 `StopCommandInput` struct）：
+
+```rust
+struct StopCommandInput {
+    session_id: String,
+    turn_id: String,
+    transcript_path: NullableString,
+    cwd: String,
+    hook_event_name: String,
+    model: String,
+    permission_mode: String,
+    stop_hook_active: bool,
+    last_assistant_message: NullableString,  // ← Codex 有此字段
+}
+```
+
+对应 JSON：
 
 ```json
 {
@@ -113,9 +129,8 @@ stdin = '{"hook_event_name":"Stop",...,"last_assistant_message":"..."}'
 
 源码依据：
 
-- `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-rs/hooks/src/events/stop.rs`（https://github.com/openai/codex，2026-05-11）：构造 `StopCommandInput`，包含 `last_assistant_message` 和 `transcript_path`。
+- `codex-rs/hooks/src/engine/command_runner.rs`（同上）：Hook 命令通过 stdin 接收 `input_json`。
 
 ## Codex Transcript
 
@@ -153,30 +168,35 @@ event.payload.content[].text
 
 ## Claude Code：Stop Hook
 
-Claude Code 官方 Stop Hook 通过 stdin 传 JSON，核心字段是：
+> **来源**：[Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks.md)，更新时间：2026-05-11
+
+Claude Code 官方 Stop Hook **没有 `last_assistant_message` 字段**。
+
+根据官方文档，Stop Hook 的 Common Input Fields 为：
 
 ```json
 {
-  "session_id": "...",
-  "transcript_path": "...",
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
+  "cwd": "/home/user/my-project",
+  "permission_mode": "default",
   "hook_event_name": "Stop",
-  "stop_hook_active": false
+  "effort": {
+    "level": "medium"
+  }
 }
 ```
 
-有些版本或场景可能直接提供：
+子 agent 上下文中额外字段：
 
 ```json
 {
-  "last_assistant_message": "最后一条 assistant 回复"
+  "agent_id": "subagent_xyz",
+  "agent_type": "Explore"
 }
 ```
 
-所以 Claude 的读取顺序是：
-
-1. `last_assistant_message`
-2. `message`
-3. `transcript_path`
+**结论**：Claude Code Stop Hook 官方设计只提供 `transcript_path`，没有直接内嵌 `last_assistant_message`。旧版本脚本的 `last_assistant_message` / `message` fallback 实际上**从未被官方文档支持**。
 
 Claude transcript 常见 assistant 形态：
 
@@ -207,11 +227,11 @@ fi
 - Claude / Codex Stop Hook：读 stdin
 - 如果 Codex 的 `notify` 和 `Stop` 同时启用，脚本会按 `turn_id` 去重，避免同一回合播两次
 
-Codex 文本字段优先级：
+Codex 文本字段优先级（源码确认）：
 
 ```js
-payload["last-assistant-message"]
-payload.last_assistant_message
+payload["last-assistant-message"]  // notify: kebab-case
+payload.last_assistant_message      // Stop Hook: snake_case
 payload.lastAssistantMessage
 payload.message
 payload.lastMessage
@@ -220,15 +240,14 @@ payload.transcriptPath
 payload["transcript-path"]
 ```
 
-Claude 文本字段优先级：
+Claude Code 文本字段优先级（官方文档）：
 
 ```js
-payload.last_assistant_message
-payload.message
-payload.transcript_path
-payload.transcriptPath
+payload.transcript_path  // 官方支持的唯一方式
 ```
 
+> **注**：Claude Code Stop Hook 官方 payload 中**没有 `last_assistant_message` 字段**，这是与 Codex 的本质区别。
+
 ## 为什么不能只读 stdin
 
 因为 Codex `notify` 不走 stdin。只读 stdin 会导致：
@@ -239,3 +258,17 @@ SPOKE: SKIP
 ```
 
 正确做法是先读 `$2`，再读 stdin；不扫历史 session。
+
+## Claude Code TEXT_LEN: 0 的根因
+
+当 Claude Code Stop Hook 触发但 `TEXT_LEN: 0` 时：
+
+1. **官方字段不存在**：Claude Code Stop Hook 官方 payload 中**没有 `last_assistant_message` 字段**，只有 `transcript_path`
+2. **transcript 文件可能晚一点才写完**：Hook 触发时文件虽已存在，但最后一条 assistant 文本还没落盘
+3. **结果**：如果只读一次，`hook-speak.sh` 可能拿到空串，本次不播报
+
+当前脚本对 Claude transcript 做了很短的轮询，等最后一条 assistant 文本真正出现再播，避免这个时序窗。
+
+这是 **Claude Code 与 Codex 的设计差异**，非 bug。Codex CLI（无论 notify 还是 Stop Hook）都提供 `last_assistant_message`，而 Claude Code 官方只提供 `transcript_path`。
+
+解决方案：从 `transcript_path` 读取并解析为最终一条 assistant 回复，并在 Claude 路径上补一个短轮询。

package/npm/postinstall.js

@@ -10,7 +10,8 @@ const root = path.resolve(__dirname, "..");
 const home = os.homedir();
 const binDir = path.join(home, ".local", "bin");
 const configDir = path.join(home, ".config", "iSpeak");
-const plistPath = path.join(home, "Library", "LaunchAgents", "com.iSpeak.plist");
+const plistPath = path.join(home, "Library", "LaunchAgents", "com.ispeak.plist");
+const legacyPlistPath = path.join(home, "Library", "LaunchAgents", "com.iSpeak.plist");
 const socketPath = path.join(configDir, "ispeak.sock");
 const binaryPath = path.join(binDir, "ispeakd");
 const cliPath = path.join(binDir, "ispeak");
@@ -136,12 +137,16 @@ function main() {
   run("go", ["build", "-ldflags=-s -w", "-o", buildPath, "."]);
 
   console.log("停止旧服务...");
+  run("launchctl", ["unload", legacyPlistPath], { allowFailure: true, stdio: "ignore" });
   run("launchctl", ["unload", plistPath], { allowFailure: true, stdio: "ignore" });
+  try {
+    fs.rmSync(legacyPlistPath, { force: true });
+  } catch (_) {
+    // Ignore migration cleanup failures.
+  }
 
   copyExecutable(buildPath, binaryPath);
   copyExecutable(path.join(root, "scripts", "ispeak"), cliPath);
-  symlinkForce(cliPath, path.join(binDir, "ispeak-claude"));
-  symlinkForce(cliPath, path.join(binDir, "ispeak-codex"));
 
   const configPath = path.join(configDir, "config.json");
   copyIfMissing(path.join(root, "configs", "config.example.json"), configPath);
@@ -149,7 +154,7 @@ function main() {
   installHook(path.join(root, "configs", "hook-speak.sh"), path.join(configDir, "hook-speak.sh"));
 
   const plist = fs
-    .readFileSync(path.join(root, "configs", "com.iSpeak.plist"), "utf8")
+    .readFileSync(path.join(root, "configs", "com.ispeak.plist"), "utf8")
     .replaceAll("BINARY_PATH_PLACEHOLDER", binaryPath);
   fs.writeFileSync(plistPath, plist);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdfnet/ispeak",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "description": "Local macOS TTS daemon for AI coding assistants, powered by Volcengine streaming TTS.",
   "license": "MIT",
   "homepage": "https://github.com/xdfnet/iSpeak#readme",
@@ -19,9 +19,7 @@
     "x64"
   ],
   "bin": {
-    "ispeak": "scripts/ispeak",
-    "ispeak-claude": "scripts/ispeak",
-    "ispeak-codex": "scripts/ispeak"
+    "ispeak": "scripts/ispeak"
   },
   "scripts": {
     "build": "go build -ldflags=\"-s -w\" -o build/ispeakd .",
@@ -38,7 +36,7 @@
     "scripts/ispeak",
     "configs/",
     "npm/",
-    "Docs/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],

package/scripts/ispeak

@@ -2,16 +2,10 @@
 # ispeak — iSpeak 控制命令
 set -euo pipefail
 
-VERSION="1.6.7"
+VERSION="1.6.9"
 SOCK="$HOME/.config/iSpeak/ispeak.sock"
-PLIST="$HOME/Library/LaunchAgents/com.iSpeak.plist"
-CMD_NAME="$(basename "$0")"
-SOURCE_PREFIX=""
-
-case "$CMD_NAME" in
-  ispeak-claude) SOURCE_PREFIX="{source:claude}" ;;
-  ispeak-codex) SOURCE_PREFIX="{source:codex}" ;;
-esac
+PLIST="$HOME/Library/LaunchAgents/com.ispeak.plist"
+LEGACY_PLIST="$HOME/Library/LaunchAgents/com.iSpeak.plist"
 
 cmd_status() {
   echo "== iSpeak =="
@@ -28,6 +22,7 @@ cmd_status() {
 }
 
 cmd_restart() {
+  launchctl unload "$LEGACY_PLIST" 2>/dev/null || true
   launchctl unload "$PLIST" 2>/dev/null || true
   launchctl load "$PLIST"
   sleep 0.5
@@ -53,6 +48,6 @@ case "${1:-}" in
     echo "  ispeak version     版本"
     ;;
   *)
-    printf "%s%s" "$SOURCE_PREFIX" "$*" | nc -U -w5 "$SOCK" 2>/dev/null || echo "ispeak: socket 不可用" >&2
+    printf "%s" "$*" | nc -U -w5 "$SOCK" 2>/dev/null || echo "ispeak: socket 不可用" >&2
     ;;
 esac