system-health-check

系统健康检查

对 TTS 引擎、Telegram 机器人及支持基础设施执行涵盖 10 个子系统的全面健康检查。生成包含通过/失败结果表格以及可执行修复建议的报告。

平台：macOS（Apple Silicon）

何时使用此技能

• 诊断 TTS 或 Telegram 机器人无法正常工作的原因
• 在引导配置或更改配置后验证系统是否就绪
• 在演示或展示前执行例行健康检查
• 调查 TTS 流水线中的间歇性故障
• 检查是否存在过期锁、僵尸进程或遗留临时文件

要求

• Bun 运行时（用于机器人进程）
• Python 3.13，且 Kokoro 虚拟环境位于 ~/.local/share/kokoro/.venv
• Telegram 机器人令牌位于 ~/.claude/.secrets/ccterrybot-telegram
• ~/.claude/automation/claude-telegram-sync/ 中已配置 mise.toml

工作流阶段

阶段 1：设置

从 mise 加载环境变量，确保 BOT_TOKEN 和其他密钥可用：

cd ~/.claude/automation/claude-telegram-sync && eval "$(mise env)"

阶段 2：运行全部 10 项健康检查

执行每项检查并收集结果。每项检查都会返回 [OK] 或 [FAIL]，并附带简短的诊断消息。

检查 1：机器人进程

pgrep -la 'bun.*src/main.ts'

恰好找到一个进程则通过。找到零个或多个进程则失败。

检查 2：Telegram API

BOT_TOKEN=$(cat ~/.claude/.secrets/ccterrybot-telegram)
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok

响应为 true 则通过。响应为 false、null 或发生连接错误则失败。

检查 3：Kokoro 虚拟环境

[[ -d ~/.local/share/kokoro/.venv ]]

目录存在则通过。

检查 4：MLX-Audio 导入

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

导入成功且退出代码为 0 则通过。

检查 5：Apple Silicon

[[ "$(uname -m)" == "arm64" ]]

架构为 arm64 则通过。MLX-Audio 需要 Apple Silicon（M1 或更新型号）。

检查 6：锁状态

LOCK_FILE="/tmp/kokoro-tts.lock"
if [[ -f "$LOCK_FILE" ]]; then
  LOCK_PID=$(cat "$LOCK_FILE")
  LOCK_AGE=$(( $(date +%s) - $(stat -f %m "$LOCK_FILE") ))
  if kill -0 "$LOCK_PID" 2>/dev/null; then
    if [[ $LOCK_AGE -gt 30 ]]; then
      echo "STALE (PID $LOCK_PID alive but lock age ${LOCK_AGE}s > 30s threshold)"
    else
      echo "ACTIVE (PID $LOCK_PID, age ${LOCK_AGE}s)"
    fi
  else
    echo "ORPHANED (PID $LOCK_PID not running, age ${LOCK_AGE}s)"
  fi
else
  echo "NO LOCK (idle)"
fi

没有锁，或存在且年龄小于 30 秒的活动锁，则通过。存在过期锁或孤立锁则失败。

检查 7：音频进程

pgrep -x afplay
pgrep -x say

信息性检查。报告正在运行的音频进程数量。不判断通过或失败，仅报告状态。

检查 8：密钥文件

[[ -f ~/.claude/.secrets/ccterrybot-telegram ]]

文件存在且非空则通过。

检查 9：过期 WAV 文件

find /tmp -maxdepth 1 -name "kokoro-tts-*.wav" -mmin +5 2>/dev/null

未找到过期 WAV 文件（早于 5 分钟）则通过。存在孤立 WAV 文件则失败。

检查 10：Shell 符号链接

[[ -L ~/.local/bin/tts_kokoro.sh ]] && readlink ~/.local/bin/tts_kokoro.sh

符号链接存在且指向插件内的有效目标则通过。

阶段 3：报告

以表格形式显示结果：

| # | Subsystem        | Status | Detail                          |
|---|------------------|--------|---------------------------------|
| 1 | Bot Process      | [OK]   | PID 12345                       |
| 2 | Telegram API     | [OK]   | Bot @ccterrybot responding      |
| 3 | Kokoro venv      | [OK]   | ~/.local/share/kokoro/.venv     |
| 4 | MLX-Audio Import | [OK]   | mlx_audio module loaded         |
| 5 | Apple Silicon    | [OK]   | arm64 (MLX Metal)               |
| 6 | Lock State       | [OK]   | No lock (idle)                  |
| 7 | Audio Processes  | [OK]   | 0 afplay, 0 say                |
| 8 | Secrets File     | [OK]   | ccterrybot-telegram present     |
| 9 | Stale WAVs       | [OK]   | No orphaned files               |
|10 | Shell Symlinks   | [OK]   | tts_kokoro.sh -> plugin script  |

阶段 4：摘要和建议

• 报告通过/失败总数（例如，“10 项检查中通过 9 项”）
• 针对每项失败，建议相应的修复方法或应调用的技能

TodoWrite 任务模板

1. [Setup] Load environment variables from mise in bot source directory
2. [Run] Execute all 10 health checks and collect results
3. [Report] Display results table with [OK]/[FAIL] status for each subsystem
4. [Summary] Show pass/fail counts (e.g., 9/10 passed)
5. [Recommend] Suggest fixes for any failures, referencing relevant skills

更改后检查清单

• 已执行全部 10 项检查（未因提前退出而跳过任何检查）
• 已按统一格式显示结果表格
• 已为每项失败提供可执行的建议
• 输出中未泄露敏感值（令牌、密钥）

故障排除

问题	原因	解决方案
所有检查均失败	环境未设置	先运行 full-stack-bootstrap skill
只有 Kokoro 检查失败（3-4）	Kokoro 虚拟环境缺失或损坏	运行 kokoro-install.sh --health 查看详细报告
锁定卡住（检查 6）	TTS 进程崩溃后遗留的锁	检查锁的存在时间和 PID；参见 diagnostic-issue-resolver skill
Bot 进程缺失（检查 1）	Bot 崩溃或从未启动	参见 bot-process-control skill
Telegram API 失败（检查 2）	令牌已过期或网络问题	检查 ~/.claude/.secrets/ccterrybot-telegram 中的令牌；检查网络
不是 Apple Silicon（检查 5）	正在 Intel Mac 或 Linux 上运行	MLX-Audio 需要 Apple Silicon（M1+）
发现过期的 WAV 文件（检查 9）	TTS 进程在生成过程中崩溃	使用 rm /tmp/kokoro-tts-*.wav 清理；调查崩溃原因
缺少 Shell 符号链接（检查 10）	Bootstrap 未完成	从 full-stack-bootstrap skill 重新运行符号链接设置

参考文档

• 健康检查 - 详细说明每项检查、失败含义和修复方法
• 演进日志 - 此 skill 的变更历史