full-stack-bootstrap

フルスタックのブートストラップ

TTS と Telegram ボットのスタック全体を一度にブートストラップします。Kokoro TTS エンジン（Apple Silicon 上の MLX-Audio）、BotFather を使った Telegram ボットの設定、シークレット管理、環境設定、シェルのシンボリックリンクを扱います。

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

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

このスキルを使用するタイミング

• tts-tg-sync プラグインを初めてセットアップするとき
• OS のクリーンインストール後やハードウェア移行後に再インストールするとき
• TTS と Telegram のスタック全体を新しいマシンにセットアップするとき
• インストールが壊れた状態から復旧するとき（最初に kokoro-install.sh --uninstall を実行してください）

---

要件

コンポーネント	必須	インストール方法
Bun	はい	brew install oven-sh/bun/bun
mise	はい	brew install mise
uv	はい	brew install uv
Python 3.14	はい	uv python install 3.14
Homebrew	はい	macOS の開発マシンにはインストール済み
Apple Silicon（M1 以降）	はい	MLX Metal アクセラレーションに必要

---

ワークフローのフェーズ

フェーズ 0：事前チェック

すべての前提条件がインストールされ、利用可能であることを確認します。

command -v bun    # Bun runtime for TypeScript bot
command -v mise   # Environment manager
command -v uv     # Python package manager
uv python list | grep 3.14  # Python 3.14 available

ツールが不足している場合は、Homebrew 経由でインストールしてください（brew install <tool>）。Python 3.14 は uv python install 3.14 でインストールします。

フェーズ 1：Kokoro TTS エンジンのインストール

同梱のインストーラースクリプトを実行します。

bash scripts/kokoro-install.sh --install

以下の処理が実行されます。

1. Apple Silicon が必要です（Intel／Linux では直ちに失敗します）
2. uv 経由で Python 3.14 を使い、~/.local/share/kokoro/.venv に仮想環境を作成します
3. PyPI の依存関係（mlx-audio、soundfile、numpy）をインストールします
4. プラグインのバンドルから kokoro_common.py と tts_generate.py を ~/.local/share/kokoro/ にコピーします
5. HuggingFace から Kokoro-82M-bf16 MLX モデル（mlx-community/Kokoro-82M-bf16）をダウンロードします
6. mlx_audio のバージョン、バックエンド、モデル ID を含む version.json を書き込みます

フェーズ 2：BotFather トークンのセットアップ

Telegram BotFather を使ってボットトークンを作成する手順を案内します。

1. Telegram を開き、@BotFather を検索します
2. /newbot を送信し、プロンプトに従って名前とユーザー名を設定します
3. HTTP API トークンをコピーします
4. トークンを確認します：curl -s "https://api.telegram.org/bot<TOKEN>/getMe" | jq .ok
5. ボットにメッセージを送信して chat_id を取得し、次を実行します：curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'

トークンがすでに ~/.claude/.secrets/ccterrybot-telegram にある場合は、動作を確認してこのフェーズをスキップしてください。

フェーズ 3：シークレットの保存

ボットトークンを安全に保存します。

mkdir -p ~/.claude/.secrets
chmod 700 ~/.claude/.secrets
echo "BOT_TOKEN=<token>" > ~/.claude/.secrets/ccterrybot-telegram
echo "CHAT_ID=<chat_id>" >> ~/.claude/.secrets/ccterrybot-telegram
chmod 600 ~/.claude/.secrets/ccterrybot-telegram

ボットのディレクトリに .mise.local.toml（Git で無視されます）を作成し、シークレットを読み込みます。

# ~/.claude/automation/claude-telegram-sync/.mise.local.toml
[env]
_.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"

フェーズ 4：環境設定

mise.toml に Kokoro のパスを追加します。

# In ~/.claude/automation/claude-telegram-sync/mise.toml [env] section
KOKORO_VENV = "{{env.HOME}}/.local/share/kokoro/.venv"
KOKORO_SCRIPT = "{{env.HOME}}/.local/share/kokoro/tts_generate.py"

フェーズ 5：シェルのシンボリックリンク

プラグインのシェルスクリプトを参照するシンボリックリンクを ~/.local/bin/ に作成します。

mkdir -p ~/.local/bin
ln -sf <plugin>/scripts/tts_kokoro.sh ~/.local/bin/tts_kokoro.sh
ln -sf <plugin>/scripts/tts_read_clipboard.sh ~/.local/bin/tts_read_clipboard.sh
ln -sf <plugin>/scripts/tts_read_clipboard_wrapper.sh ~/.local/bin/tts_read_clipboard_wrapper.sh
ln -sf <plugin>/scripts/tts_speed_up.sh ~/.local/bin/tts_speed_up.sh
ln -sf <plugin>/scripts/tts_speed_down.sh ~/.local/bin/tts_speed_down.sh
ln -sf <plugin>/scripts/tts_speed_reset.sh ~/.local/bin/tts_speed_reset.sh

フェーズ 6：検証

1. テスト用 WAV を生成して再生します。

~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_generate.py \
    --text "Hello, bootstrap complete." --voice af_heart --lang en-us --speed 1.0 --output /tmp/test-bootstrap.wav
afplay /tmp/test-bootstrap.wav
rm -f /tmp/test-bootstrap.wav

1. Telegram API 経由で、ボットが /status に応答することを確認します。

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok

---

TodoWrite タスクテンプレート

テンプレート：フルスタックのブートストラップ

1. [Preflight] Verify Bun installed
2. [Preflight] Verify mise installed
3. [Preflight] Verify uv installed
4. [Preflight] Verify Python 3.14 available via uv
5. [Kokoro] Run kokoro-install.sh --install
6. [Kokoro] Verify MLX-Audio acceleration
7. [BotFather] Guide BotFather token creation (or verify existing)
8. [Secrets] Store token in ~/.claude/.secrets/ccterrybot-telegram
9. [Secrets] Create .mise.local.toml with _.file reference to secrets
10. [Environment] Add KOKORO_VENV and KOKORO_SCRIPT to mise.toml
11. [Symlinks] Create ~/.local/bin/ symlinks for all TTS shell scripts
12. [Verify] Generate test WAV with Kokoro and play with afplay
13. [Verify] Check bot responds to /status via Telegram API

---

変更後のチェックリスト

このスキルを変更した後は、以下を確認してください。

1. kokoro-install.sh --health ですべての 6 項目のチェックに合格することを確認します
2. .mise.local.toml が Git で無視されることを確認します
3. シンボリックリンクが正しく解決されることを確認します（ls -la ~/.local/bin/tts_*.sh）
4. getMe API 呼び出しでボットトークンが機能することを確認します
5. TTS の一連の往復処理を実行します：クリップボードのテキストから音声を再生します
6. 変更内容を references/evolution-log.md に記録します

トラブルシューティング

問題	原因	解決策
uv が見つからない	インストールされていない	brew install uv
Python 3.14 が利用できない	uv 経由でインストールされていない	uv python install 3.14
Apple Silicon ではない	Intel Mac または Linux	M1 以降の Mac が必要です（MLX Metal）
モデルのダウンロードに失敗する	ネットワークの問題または HuggingFace の障害	インターネット接続を確認して、再試行してください
BotFather のトークンが無効	入力ミスまたはトークンが取り消されている	curl https://api.telegram.org/bot<TOKEN>/getMe で確認してください
kokoro-install.sh の権限が拒否される	スクリプトに実行権限がない	chmod +x scripts/kokoro-install.sh
仮想環境がすでに存在する	前回のインストールが途中で失敗した	kokoro-install.sh --uninstall を実行してから --install を実行してください
tts_generate.py が見つからない	バンドルのコピーに失敗した	プラグイン内に scripts/tts_generate.py が存在することを確認してください

---

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

• Kokoro のブートストラップ - 仮想環境の詳細なセットアップ、uv 経由の Python 3.14、MLX-Audio、モデルのダウンロード
• BotFather ガイド - Telegram ボットの作成とトークン管理の手順
• 上流フォーク - MLX-Audio Kokoro の上流プロジェクトとスクリプトをバンドルする理由
• 進化ログ - このスキルの変更履歴

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返ってください：

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

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

---

---