full-stack-bootstrap

全栈初始化

一次性初始化整个 TTS + Telegram 机器人技术栈：Kokoro TTS 引擎（Apple Silicon 上的 MLX-Audio）、通过 BotFather 创建 Telegram 机器人、密钥管理、环境配置和 Shell 符号链接。

平台：macOS（Apple Silicon）

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏差，或需要采用变通方案，请立即修复此文件，不要拖延。只针对真实且可复现的问题进行更新。

何时使用此技能

• 首次设置 tts-tg-sync 插件
• 全新安装操作系统或迁移硬件后重新安装
• 在新机器上设置完整的 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. 写入 version.json，记录 mlx_audio 版本、后端和模型 ID

阶段 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（已加入 gitignore），以加载密钥：

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

阶段 4：环境配置

将 Kokoro 路径添加到 mise.toml：

# 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：Shell 符号链接

在 ~/.local/bin/ 中创建指向插件 Shell 脚本的符号链接：

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 已加入 gitignore
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	Bundle 复制失败	检查插件中的 scripts/tts_generate.py 是否存在

---

参考文档

• Kokoro Bootstrap - 详细介绍虚拟环境设置、通过 uv 安装 Python 3.14、MLX-Audio 和模型下载
• BotFather Guide - 逐步介绍 Telegram 机器人创建和令牌管理
• Upstream Fork - MLX-Audio Kokoro 上游项目及捆绑脚本的原因
• Evolution Log - 此技能的变更历史

执行后复盘

此技能完成后，请在结束任务前进行复盘：

0. 确认位置。 — 通过 Glob 搜索此技能的名称，找到此 SKILL.md 的规范路径，然后再进行编辑。所有修正都应针对此文件及其同级的 references/ — 绝不能修改其他文档。
1. 哪里失败了？ — 修正导致失败的指令。如果问题可能再次发生，请将其列为反模式。
2. 哪些地方的效果超出预期？ — 将其提升为推荐做法，并记录原因。
3. 哪些内容已经偏离？ — 如果脚本、参考资料或外部依赖与实际情况不再一致，请立即修正。
4. 记录下来。 — 每项变更都要在 evolution-log 中添加条目，注明触发原因、修正内容和依据。

不要推迟。下一次调用会继承你留下的一切。

---

---