component-version-upgrade

コンポーネントのバージョンアップグレード

システム全体を再構築せずに、TTS ＋ Telegram ボットスタックの各コンポーネントをアップグレードします。

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

---

自己進化するスキル：このスキルは使用するたびに改善されます。手順に誤りがある場合、パラメーターが変更された場合、または回避策が必要になった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。

このスキルを使う場面

• Kokoro TTS エンジン、Python の依存関係、またはモデルをアップグレードしたい場合
• ボットの依存関係（Bun パッケージ）を更新したい場合
• プラグインバンドルから tts_generate.py を更新したい場合
• Bun ランタイムのバージョンを上げたい場合

---

必要条件

• uv がインストール済みであること（brew install uv）
• mise がインストールされ、設定済みであること
• パッケージのダウンロードに必要なインターネット接続
• 既存のインストール環境があること（未インストールの場合は、先に full-stack-bootstrap を実行してください）

---

アップグレード可能なコンポーネント

コンポーネント	コマンド	処理内容
Kokoro TTS エンジン	kokoro-install.sh --upgrade	Python の依存関係をアップグレードし、モデルを再ダウンロードして、version.json を更新します
ボットの依存関係	cd ~/.claude/automation/claude-telegram-sync && bun update	package.json に従って Bun パッケージを更新します
tts_generate.py	プラグインの scripts/ から ~/.local/share/kokoro/ に再コピー	TTS 生成スクリプトを更新します
Bun ランタイム	mise use bun@latest	mise.toml の Bun バージョンを更新します

---

ワークフローのフェーズ

フェーズ 1：コンポーネントの選択

AskUserQuestion を使って、アップグレードするコンポーネントをユーザーに尋ねます。上記の 4 つの選択肢を提示してください。

フェーズ 2：アップグレード前のヘルスチェック

# Run health check to establish baseline
~/.local/share/kokoro/../../eon/cc-skills/plugins/tts-tg-sync/scripts/kokoro-install.sh --health

# Record current versions
cat ~/.local/share/kokoro/version.json

フェーズ 3：アップグレードの実行

選択したコンポーネントに対応するアップグレードコマンドを実行します。

フェーズ 4：アップグレード後の検証

# Health check again
kokoro-install.sh --health

# Generate test audio to verify TTS still works
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
  --text "Upgrade verification test" --voice af_heart --lang en-us --speed 1.0 \
  --output /tmp/kokoro-tts-upgrade-test.wav

フェーズ 5：ボットの再起動（必要な場合）

ボットの依存関係または Bun ランタイムをアップグレードした場合は、ボットを再起動します。

pkill -f 'bun.*src/main.ts' || true
cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

---

TodoWrite タスクテンプレート

1. [Identify] Present upgradeable components via AskUserQuestion
2. [Preflight] Run health check on target component
3. [Backup] Note current versions (version.json, package.json)
4. [Upgrade] Execute upgrade command
5. [Verify] Run post-upgrade health check
6. [Test] Generate test audio to verify TTS still works
7. [Restart] Restart bot if needed
8. [Report] Show before/after versions

---

変更後のチェックリスト

• ヘルスチェックに合格している（6 項目すべて OK）
• version.json が新しいバージョンで更新されている
• テスト用の音声が正しく生成され、再生される
• 再起動した場合、ボットが稼働している

トラブルシューティング

問題	考えられる原因	対処方法
アップグレードに失敗する	インターネット接続がない、または PyPI の問題	接続を確認して再試行してください
モデルのダウンロードが遅い	初回は約 400MB、以降はキャッシュを使用	ダウンロードが完了するまでお待ちください
バージョンが一致しない	version.json が古い	kokoro-install.sh --health を再実行して確認し、--upgrade で修正してください
MLX-Audio のインポートに失敗する	mlx-audio のバージョン非互換	kokoro-install.sh --upgrade で mlx-audio を再インストールしてください
アップグレード後にボットが起動しない	依存関係の競合	cd ~/.claude/automation/claude-telegram-sync && bun install

---

関連ドキュメント

• アップグレード手順 -- 各コンポーネントのロールバック手順を含む、ステップごとのアップグレード手順
• 進化ログ -- このスキルの変更履歴

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返ります。

0. 現在地を特定します。 — 編集前に、このスキルの正規パスを見つけます（このスキル名で Glob を実行します）。修正対象はこのファイルとその兄弟ファイルである references/ のみです。他のドキュメントには手を加えません。
1. 何が失敗しましたか？ — 原因となった指示を修正します。同じことが再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったことは何ですか？ — 推奨プラクティスにします。その理由も記録します。
3. 何が現状とずれていますか？ — 現状に合わなくなったスクリプト、参照情報、外部依存関係があれば、今すぐ修正します。
4. 記録します。 — すべての変更について、きっかけ、修正内容、根拠を記した進化ログのエントリを追加します。

先送りしないでください。次回の実行には、ここに残した内容が引き継がれます。

---

---