Back to Details

full-stack-bootstrap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Full Stack Bootstrap

全栈引导设置

One-time bootstrap of the entire TTS + Telegram bot stack: Kokoro TTS engine (Apple Silicon MPS), Telegram bot via BotFather, secrets management, environment configuration, and shell symlinks.
Platform: macOS (Apple Silicon)
TTS + Telegram机器人全栈的一次性引导设置：Kokoro TTS引擎（Apple Silicon MPS）、通过BotFather创建Telegram机器人、密钥管理、环境配置及Shell符号链接。
平台: macOS（Apple Silicon）

When to Use This Skill

何时使用此技能

  • First-time setup of the tts-telegram-sync plugin
  • Reinstalling after a clean OS install or hardware migration
  • Setting up a new machine with the full TTS + Telegram stack
  • Recovering from a broken installation (run 
    kokoro-install.sh --uninstall
    first)
  • 首次搭建tts-telegram-sync插件
  • 干净安装系统或硬件迁移后重新安装
  • 在新机器上搭建完整的TTS + Telegram栈
  • 从损坏的安装中恢复（先运行
    kokoro-install.sh --uninstall
    ）

Requirements

前置要求

ComponentRequiredInstallation
BunYes
brew install oven-sh/bun/bun
miseYes
brew install mise
uvYes
brew install uv
Python 3.13Yes
uv python install 3.13
HomebrewYesAlready installed on macOS dev machines
Apple Silicon (M1+)YesRequired for MPS acceleration
组件是否必需安装方式
Bun是
brew install oven-sh/bun/bun
mise是
brew install mise
uv是
brew install uv
Python 3.13是
uv python install 3.13
Homebrew是macOS开发机器通常已预装
Apple Silicon (M1+)是必需用于MPS加速

Workflow Phases

工作流阶段

Phase 0: Preflight Check

阶段0：预检检查

Verify all prerequisites are installed and accessible:
bash
command -v bun    # Bun runtime for TypeScript bot
command -v mise   # Environment manager
command -v uv     # Python package manager
uv python list | grep 3.13  # Python 3.13 available
If any tool is missing, install via Homebrew (
brew install <tool>
). Python 3.13 is installed via 
uv python install 3.13
.
验证所有前置工具已安装且可访问：
bash
command -v bun    # TypeScript机器人的Bun运行时
command -v mise   # 环境管理器
command -v uv     # Python包管理器
uv python list | grep 3.13  # 确认Python 3.13可用
如果缺少任何工具，通过Homebrew安装（
brew install <工具>
）。Python 3.13通过
uv python install 3.13
安装。

Phase 1: Kokoro TTS Engine Install

阶段1：Kokoro TTS引擎安装

Run the bundled installer script:
bash
bash scripts/kokoro-install.sh --install
<!-- SSoT-OK: kokoro-install.sh is the SSoT for versions and deps -->
This performs:
  1. Creates venv at 
    ~/.local/share/kokoro/.venv
    with Python 3.13 via uv
  2. Installs PyPI deps (kokoro, misaki, torch, soundfile, numpy, transformers, huggingface_hub, loguru) -- versions pinned in 
    scripts/kokoro-install.sh
  3. Copies 
    tts_generate.py
    from plugin bundle to 
    ~/.local/share/kokoro/
  4. Downloads Kokoro-82M model from HuggingFace (
    hexgrad/Kokoro-82M
    )
  5. Verifies Apple Silicon MPS is available via 
    torch.backends.mps.is_available()
  6. Writes 
    version.json
    with kokoro, torch, and Python versions
运行捆绑的安装脚本：
bash
bash scripts/kokoro-install.sh --install
<!-- SSoT-OK: kokoro-install.sh是版本和依赖的单一可信源 -->
此脚本将执行以下操作：
  1. 通过uv在
    ~/.local/share/kokoro/.venv
    创建基于Python 3.13的虚拟环境
  2. 安装PyPI依赖（kokoro、misaki、torch、soundfile、numpy、transformers、huggingface_hub、loguru）——版本在
    scripts/kokoro-install.sh
    中固定
  3. 将插件包中的
    tts_generate.py
    复制到
    ~/.local/share/kokoro/
  4. 从HuggingFace下载Kokoro-82M模型（
    hexgrad/Kokoro-82M
    ）
  5. 通过
    torch.backends.mps.is_available()
    验证Apple Silicon MPS是否可用
  6. 写入包含kokoro、torch及Python版本的
    version.json

Phase 2: BotFather Token Setup

阶段2：BotFather令牌设置

Guide the user through Telegram BotFather to create a bot token:
  1. Open Telegram, search for 
    @BotFather
  2. Send 
    /newbot
    , follow prompts (name + username)
  3. Copy the HTTP API token
  4. Verify token: 
    curl -s "https://api.telegram.org/bot<TOKEN>/getMe" | jq .ok
  5. Get chat_id by sending a message to the bot, then: 
    curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'
If a token already exists at 
~/.claude/.secrets/ccterrybot-telegram
, verify it works and skip this phase.
引导用户通过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
已存在令牌，验证其可用后可跳过此阶段。

Phase 3: Secrets Storage

阶段3：密钥存储

Store the bot token securely:
bash
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
Create 
.mise.local.toml
(gitignored) in the bot directory to load secrets:
toml
undefined
安全存储机器人令牌：
bash
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
在机器人目录中创建.git忽略的
.mise.local.toml
以加载密钥：
toml
undefined

~/.claude/automation/claude-telegram-sync/.mise.local.toml

~/.claude/automation/claude-telegram-sync/.mise.local.toml

[env] _.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"
undefined
[env] _.file = "{{env.HOME}}/.claude/.secrets/ccterrybot-telegram"
undefined

Phase 4: Environment Configuration

阶段4：环境配置

Add Kokoro paths to 
mise.toml
:
toml
undefined
将Kokoro路径添加到
mise.toml
：
toml
undefined

In ~/.claude/automation/claude-telegram-sync/mise.toml [env] section

在~/.claude/automation/claude-telegram-sync/mise.toml的[env]部分

KOKORO_VENV = "{{env.HOME}}/.local/share/kokoro/.venv" KOKORO_SCRIPT = "{{env.HOME}}/.local/share/kokoro/tts_generate.py"
undefined
KOKORO_VENV = "{{env.HOME}}/.local/share/kokoro/.venv" KOKORO_SCRIPT = "{{env.HOME}}/.local/share/kokoro/tts_generate.py"
undefined

Phase 5: Shell Symlinks

阶段5：Shell符号链接

Create symlinks in 
~/.local/bin/
pointing to plugin shell scripts:
bash
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
在
~/.local/bin/
中创建指向插件Shell脚本的符号链接：
bash
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

Phase 6: Verification

阶段6：验证

  1. Generate a test WAV and play it:
bash
~/.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. Verify bot responds to /status via Telegram API:
bash
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok
  1. 生成测试WAV文件并播放：
bash
~/.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命令：
bash
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getMe" | jq .ok

TodoWrite Task Templates

TodoWrite任务模板

Template: Full Stack Bootstrap

模板：全栈引导设置

1. [Preflight] Verify Bun installed
2. [Preflight] Verify mise installed
3. [Preflight] Verify uv installed
4. [Preflight] Verify Python 3.13 available via uv
5. [Kokoro] Run kokoro-install.sh --install
6. [Kokoro] Verify MPS 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. [预检] 验证Bun已安装
2. [预检] 验证mise已安装
3. [预检] 验证uv已安装
4. [预检] 验证uv可获取Python 3.13
5. [Kokoro] 运行kokoro-install.sh --install
6. [Kokoro] 验证MPS加速可用
7. [BotFather] 引导创建BotFather令牌（或验证现有令牌）
8. [密钥] 将令牌存储到~/.claude/.secrets/ccterrybot-telegram
9. [密钥] 创建指向密钥文件的.mise.local.toml
10. [环境] 将KOKORO_VENV和KOKORO_SCRIPT添加到mise.toml
11. [符号链接] 为所有TTS Shell脚本在~/.local/bin/创建符号链接
12. [验证] 使用Kokoro生成测试WAV并通过afplay播放
13. [验证] 通过Telegram API检查机器人响应/status命令

Post-Change Checklist

变更后检查清单

After modifying this skill:
  1. Verify 
    kokoro-install.sh --health
    passes all 8 checks
  2. Confirm 
    .mise.local.toml
    is gitignored
  3. Test symlinks resolve correctly (
    ls -la ~/.local/bin/tts_*.sh
    )
  4. Verify bot token works via 
    getMe
    API call
  5. Run a full TTS round-trip: clipboard text to audio playback
  6. Update 
    references/evolution-log.md
    with change description
修改此技能后：
  1. 验证
    kokoro-install.sh --health
    通过全部8项检查
  2. 确认
    .mise.local.toml
    已被Git忽略
  3. 测试符号链接解析正确（
    ls -la ~/.local/bin/tts_*.sh
    ）
  4. 通过
    getMe
    API调用验证机器人令牌可用
  5. 运行完整的TTS往返测试：剪贴板文本转音频播放
  6. 在
    references/evolution-log.md
    中更新变更说明

Troubleshooting

故障排除

IssueCauseSolution
uv not foundNot installed
brew install uv
Python 3.13 not availableNot installed via uv
uv python install 3.13
MPS not availableNot Apple SiliconRequires M1 or newer Mac
Model download failsNetwork issue or HuggingFace outageCheck internet connectivity, retry
BotFather token invalidTypo or revoked tokenVerify via 
curl https://api.telegram.org/bot<TOKEN>/getMe
kokoro-install.sh permission deniedScript not executable
chmod +x scripts/kokoro-install.sh
Venv already existsPrevious partial installRun 
kokoro-install.sh --uninstall
then 
--install
tts_generate.py not foundBundle copy failedCheck 
scripts/tts_generate.py
exists in plugin
问题原因解决方案
uv未找到未安装
brew install uv
Python 3.13不可用未通过uv安装
uv python install 3.13
MPS不可用非Apple Silicon设备需要M1或更新型号的Mac
模型下载失败网络问题或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

Reference Documentation

参考文档

  • Kokoro Bootstrap - Detailed venv setup, Python 3.13 via uv, torch + MPS, model download
  • BotFather Guide - Step-by-step Telegram bot creation and token management
  • Upstream Fork - hexgrad/kokoro fork provenance and tts_generate.py bundling rationale
  • Evolution Log - Change history for this skill
  • Kokoro引导设置 - 详细的虚拟环境设置、通过uv安装Python 3.13、torch + MPS、模型下载
  • BotFather指南 - 分步创建Telegram机器人及令牌管理
  • 上游分支 - hexgrad/kokoro分支来源及tts_generate.py捆绑理由
  • 变更日志 - 此技能的变更历史