system-health-check

システムヘルスチェック

TTS エンジン、Telegram ボット、およびサポートインフラストラクチャ全体を対象に、10 項目の包括的なヘルスチェックを実行します。実行可能な修正案を含む合否レポートの表を出力します。

プラットフォーム：macOS（Apple Silicon）

このスキルを使うタイミング

• TTS または Telegram ボットが動作しない原因を診断するとき
• ブートストラップまたは設定変更後に、システムの準備状況を確認するとき
• デモやプレゼンテーションの前に定期的なヘルスチェックを行うとき
• TTS パイプラインで断続的に発生する障害を調査するとき
• 古いロック、ゾンビプロセス、または孤立した一時ファイルを確認するとき

要件

• Bun ランタイム（ボットプロセス用）
• ~/.local/share/kokoro/.venv に Kokoro venv を設定した Python 3.13
• ~/.claude/.secrets/ccterrybot-telegram に 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'

プロセスがちょうど 1 つ見つかった場合は合格です。0 個または 2 個以上の場合は不合格です。

チェック 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 venv

[[ -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：シェルのシンボリックリンク

[[ -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 スキルを実行します
Kokoro のチェック（3〜4）のみ失敗する	Kokoro の venv がないか、破損している	詳細なレポートを確認するには kokoro-install.sh --health を実行します
ロックが解除されない（チェック 6）	TTS プロセスがクラッシュして古いロックが残っている	ロックの経過時間と PID を確認します。diagnostic-issue-resolver スキルを参照してください
ボットプロセスが見つからない（チェック 1）	ボットがクラッシュしたか、起動されていない	bot-process-control スキルを参照してください
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 で削除し、クラッシュの原因を調査します
シェルのシンボリックリンクがない（チェック 10）	ブートストラップが未完了	full-stack-bootstrap スキルでシンボリックリンクのセットアップを再実行します

リファレンスドキュメント

• ヘルスチェック - 各チェックの詳細、失敗が示す内容、対処方法
• 進化のログ - このスキルの変更履歴