system-health-check

用途

System Health Check 用于对 TTS 引擎、Telegram 机器人及其支撑基础设施执行一次覆盖 10 个子系统的综合健康检查，并生成一张通过/失败报告表，附带可操作的修复建议。

适用场景包括：

• 诊断 TTS 或 Telegram 机器人为何无法工作
• 在引导（bootstrap）或配置变更后验证系统就绪状态
• 演示或展示前的例行健康检查
• 调查 TTS 流水线中的间歇性故障
• 检查过期锁、僵尸进程或孤立的临时文件

运行要求

• Bun 运行时（用于机器人进程）
• Python 3.13，Kokoro 虚拟环境位于 ~/.local/share/kokoro/.venv
• Telegram 机器人 token 位于 ~/.claude/.secrets/ccterrybot-telegram
• 在 ~/.claude/automation/claude-telegram-sync/ 中配置好 mise.toml
• 平台：macOS（Apple Silicon）

工作流程

阶段 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

未发现超过 5 分钟的残留 WAV 文件则通过；存在孤立 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：总结与建议

• 报告通过/失败总数（例如“9/10 checks passed”）
• 针对每项失败，推荐相应的修复方法或应调用的技能

TodoWrite 任务模板

1. [Setup] 在机器人源码目录中从 mise 加载环境变量
2. [Run] 执行全部 10 项健康检查并收集结果
3. [Report] 展示各子系统 [OK]/[FAIL] 状态的结果表
4. [Summary] 显示通过/失败计数（例如 9/10 passed）
5. [Recommend] 针对失败项建议修复方法，并引用相关技能

变更后检查清单

• 全部 10 项检查均已执行（未因提前退出而跳过）
• 结果表以一致格式展示
• 每项失败都有可操作的修复建议
• 输出中未暴露敏感值（token、密钥）

故障排查

问题	原因	解决方案
所有检查失败	环境未设置	先运行 full-stack-bootstrap 技能
仅 Kokoro 检查（3-4）失败	Kokoro 虚拟环境缺失或损坏	运行 kokoro-install.sh --health 获取详细报告
锁卡住（检查 6）	TTS 进程崩溃留下的过期锁	检查锁时长与 PID；参见 diagnostic-issue-resolver 技能
机器人进程缺失（检查 1）	机器人崩溃或从未启动	参见 bot-process-control 技能
Telegram API 失败（检查 2）	token 过期或网络问题	验证 ~/.claude/.secrets/ccterrybot-telegram 中的 token；检查网络
非 Apple Silicon（检查 5）	运行在 Intel Mac 或 Linux 上	MLX-Audio 需要 Apple Silicon（M1+）
发现残留 WAV（检查 9）	TTS 进程在生成中途崩溃	用 rm /tmp/kokoro-tts-*.wav 清理；调查崩溃原因
Shell 符号链接缺失（检查 10）	引导不完整	从 full-stack-bootstrap 技能重新运行符号链接设置

参考文档

• Health Checks —— 每项检查的详细说明、失败含义与补救措施
• Evolution Log —— 本技能的变更历史

限制

• 平台限定为 macOS（Apple Silicon），检查 5 明确要求 arm64 架构，MLX-Audio 需要 M1 及以上芯片。
• 依赖特定的目录、文件与工具链（Bun、Python 3.13、Kokoro venv、mise、Telegram token 文件），缺失时相关检查会失败。
• 检查 7 为信息性检查，不参与通过/失败判定。
• 关于收费、价格等信息，资料中暂未提供。