diagnostic-issue-resolver

诊断问题解决器

通过系统收集症状、自动诊断和针对性修复，诊断并解决常见的文本转语音问题。

此插件已不再提供 Telegram 机器人（于 2026-09-24 停用），因此“机器人无响应”不属于此技能处理的症状。

平台：macOS（Apple Silicon）

---

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移或需要采用变通方法，请立即修复此文件，不要延后。仅针对真实且可复现的问题进行更新。

何时使用此技能

• 朗读快捷键不起作用，或朗读的是上一次选中的内容
• 音频听起来不对、速度太慢或太快，或播放了两次
• Kokoro 引擎报错或超时
• 锁文件似乎卡住
• MLX Metal 加速无法正常工作

---

要求

• 能访问 /tmp/kokoro-tts.log 和 /tmp/tts_errors.log（脚本日志）
• 能访问 ~/.local/share/kokoro/（本地 Kokoro 引擎）
• 能通过 curl 访问 http://[::1]:8780 上的 claude-tts-companion

---

已知问题表

问题	可能原因	诊断	修复
快捷键无响应	绑定指向带版本号的路径，或快捷键工具缺少权限	按下后立即运行 tail -20 /tmp/kokoro-tts.log	绑定 ~/.local/bin/tts_read_clipboard_wrapper.sh；授予“辅助功能”权限
朗读的是上一次选中的内容	复制完成前就读取了剪贴板	日志显示旧文本	使用包装脚本（它会等待 NSPasteboard 的 changeCount），而不是 tts_kokoro.sh
没有音频输出	TTS 锁已过期	stat /tmp/kokoro-tts.lock /tmp/tts_kokoro.lock	tts_stop.sh
首个词播放缓慢	Companion 已停止，回退到 Supertonic	curl -s --max-time 2 "http://[::1]:8780/health"	启动 claude-tts-companion；或接受回退方案
调速快捷键不起作用	设置速率时无法访问 Companion	grep speed: /tmp/kokoro-tts.log | tail -3	Companion 启动后再按一次
Kokoro 超时（试听）	首次加载模型	检查 ~/.cache/huggingface/	等待下载完成，或重新运行 kokoro-install.sh --install
锁永远卡住	心跳进程已退出	stat /tmp/kokoro-tts.lock + pgrep -x afplay	仅当锁已过期超过 30 秒且没有音频进程时，运行 tts_stop.sh
MLX 加速缓慢	Python 版本不对或依赖项有误	python -c "from mlx_audio.tts.utils import load_model; print('MLX OK')"	通过 kokoro-install.sh --upgrade 重新安装
音频重复播放	两个引擎同时运行，或两次按键发生竞争	检查是否有多个 afplay 进程	运行 tts_stop.sh，然后只按一次

---

工作流阶段

阶段 1：收集症状

使用 AskUserQuestion 了解用户遇到的问题。关键问题：

• 发生了什么？（没有声音、文本错误、速度不对、音频重叠、错误通知）
• 什么时候开始的？（升级后、移动 checkout 后、突然发生、一直如此）
• 当时在做什么？（使用快捷键朗读、调整速度、试听语音、手动运行脚本）

阶段 2：自动诊断

根据症状，运行以下相关检查：

# Lock state (both locks)
for f in /tmp/kokoro-tts.lock /tmp/tts_kokoro.lock; do
  ls -la "$f" 2>/dev/null && stat -f "%Sm" "$f" || echo "No $f"
done

# Audio processes
pgrep -la afplay; pgrep -la say

# Which engine the last presses used, and any errors
tail -30 /tmp/kokoro-tts.log 2>/dev/null
tail -20 /tmp/tts_errors.log 2>/dev/null

# Primary engine
curl -s --max-time 2 "http://[::1]:8780/health" || echo "companion down"

# Local Kokoro health
~/.local/share/kokoro/.venv/bin/python -c "from mlx_audio.tts.utils import load_model; print('MLX-Audio OK')"

# Links the hotkeys call
ls -la ~/.local/bin/tts_*.sh

阶段 3：根因分析

将诊断输出对应到上方的已知问题表。常见情况：

• 锁文件存在 + 修改时间超过 30s + 没有 afplay = 陈旧锁
• 日志显示每次按键都出现 engine=supertonic = 伴侣程序已停止
• 按键后日志没有任何内容 = 快捷键未运行脚本（绑定或权限问题）
• from mlx_audio.tts.utils import load_model 运行失败 = MLX-Audio 损坏
• 存在多个 afplay PID = 竞争条件

阶段 4：应用修复

应用已知问题表中的针对性修复。始终先采用影响最小的修复；对于任何与播放相关的问题，tts_stop.sh 都是安全的重置方式。

阶段 5：验证

应用修复后，验证问题是否已解决：

# Same path a hotkey takes
echo "Diagnostic test complete" | pbcopy && ~/.local/bin/tts_read_clipboard_wrapper.sh; echo "exit=$?"

# Local engine
bash "$(cc-plugin-root tts-tg-sync)/scripts/kokoro-install.sh" --health

---

TodoWrite 任务模板

1. [Symptoms] Collect symptoms via AskUserQuestion
2. [Triage] Map symptoms to likely causes
3. [Lock] Check both TTS locks (mtime, PID, stale detection)
4. [Engine] Check the companion and the Supertonic fallback via /tmp/kokoro-tts.log
5. [Kokoro] Verify Kokoro venv and MLX-Audio availability
6. [Fix] Apply targeted fix for identified root cause
7. [Verify] Run the wrapper and the health check to confirm resolution

---

变更后检查清单

• 已确定并记录根因
• 已成功应用修复
• 健康检查通过
• 测试音频播放正常
• 没有遗留的陈旧锁或孤立进程

故障排除

此技能本身就是故障排除技能。如果标准诊断无法确定问题：

1. 使用调试日志重新运行 Supertonic 路径：DEBUG=1 TTS_ENGINE=supertonic ~/.local/bin/tts_read_clipboard_wrapper.sh，然后读取 /tmp/tts_debug.log（Kokoro 路径只将日志写入 /tmp/kokoro-tts.log）
2. 检查系统音频：afplay /System/Library/Sounds/Tink.aiff（如果失败，则是 macOS 音频问题，而不是 TTS 问题）
3. 依次强制使用每个引擎：TTS_ENGINE=kokoro … 和 TTS_ENGINE=supertonic …
4. 使用 tts_generate.py 手动生成 Kokoro 音频，以隔离本地引擎
5. 如果其他方法都无效，使用 clean-component-removal 完全卸载，然后通过 full-stack-bootstrap 重新安装

---

参考文档

• 常见问题 -- 各已知问题的扩展诊断流程
• 锁调试 -- 深入了解锁机制
• 演进日志 -- 此技能的变更历史

执行后复盘

此技能执行完毕后，在结束任务前进行复盘：

0. 确认文件位置。 — 编辑前，使用 Glob 查找此技能的名称，确定此 SKILL.md 的规范路径。所有修正都针对此文件及其同级的 references/ — 绝不修改其他文档。
1. 哪里失败了？ — 修复导致失败的指令。如果问题可能再次发生，将其列为反模式。
2. 哪些做法的效果超出预期？ — 将其纳入推荐实践，并记录原因。
3. 哪些内容已偏离实际情况？ — 任何与现状不符的脚本、参考资料或外部依赖，都要立即修正。
4. 记录下来。 — 每项变更都要在演进日志中添加条目，说明触发原因、修复内容和证据。

不要推迟。下次调用时，你留下的内容会被沿用。