# 全栈引导 One-time bootstrap of the entire TTS + Telegram bot stack: Kokoro TTS engine (MLX-Audio on Apple Silicon), Telegram bot via BotFather, secrets management, environment configuration, and shell symlinks. > **Platform** : macOS (Apple Silicon) ## 何时使用此技能 * 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) ** ** ## 要求组件|必填 |安装 ---|---|--- 包子|是的 | `brew install oven-sh/bun/bun` 米塞|是的 | `brew 安装 mise` 紫外线|是的 | `brew 安装 uv` Python 3.13 |是的 | `uv python 安装 3.13` 自制|是的 | Already installed on macOS dev machines 苹果芯片 (M1+) |是的 | MLX Metal 加速所需 ** ** ## 工作流程阶段 ### Phase 0: Preflight Check Verify all prerequisites are installed and accessible: command -v bun # Bun runtime for TypeScript bot command -v mise # Environment manager 命令 -v uv # Python 包管理器 uv python 列表 | grep 3.13 # Python 3.13 available 如果缺少任何工具，请通过 Homebrew 安装（`brew install `）。 Python 3.13 is installed via `uv python install 3.13`. ### Phase 1: Kokoro TTS Engine Install Run the bundled installer script: bash 脚本/kokoro-install.sh --install 这执行： 1. 需要 Apple Silicon（在 Intel/Linux 上快速失败） 2. Creates venv at `~/.local/share/kokoro/.venv` with Python 3.13 via uv 3. 安装 PyPI deps（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` ### Phase 2: BotFather Token Setup 引导用户通过 Telegram BotFather 创建机器人令牌： 1. 打开 Telegram，搜索“@BotFather” 2.发送`/newbot`，按照提示操作（姓名+用户名） 3.复制HTTP API令牌 4. 验证令牌：`curl -s "https://api.telegram.org/bot/getMe" | jq.好的` 5. 通过向机器人发送消息来获取 chat_id，然后： `curl -s "https://api.telegram.org/bot/getUpdates" | jq '.result[0].message.chat.id'` 如果令牌已存在于“~/.claude/.secrets/ccterrybot-telegram”中，请验证其是否有效并跳过此阶段。 ### 第三阶段：秘密存储安全地存储机器人令牌： mkdir -p ~/.claude/.secrets chmod 700 ~/.claude/.secrets echo "BOT_TOKEN=<令牌>" > ~/.claude/.secrets/ccterrybot-telegram echo "CHAT_ID=" >> ~/.claude/.secrets/ccterrybot-telegram chmod 600 ~/.claude/.secrets/ccterrybot-电报在 bot 目录中创建 `.mise.local.toml` (gitignored) 以加载机密： # ~/.claude/automation/claude-telegram-sync/.mise.local.toml [环境] _.file =“{{env.HOME}}/.claude/.secrets/ccterrybot-telegram” ### 第四阶段：环境配置将 Kokoro 路径添加到 `mise.toml`： # 在 ~/.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" ### 第 5 阶段：Shell 符号链接在 `~/.local/bin/` 中创建指向插件 shell 脚本的符号链接： mkdir -p ~/.local/bin ln -sf <插件>/scripts/tts_kokoro.sh ~/.local/bin/tts_kokoro.sh ln -sf <插件>/scripts/tts_read_clipboard.sh ~/.local/bin/tts_read_clipboard.sh ln -sf <插件>/scripts/tts_read_clipboard_wrapper.sh ~/.local/bin/tts_read_clipboard_wrapper.sh ln -sf <插件>/scripts/tts_speed_up.sh ~/.local/bin/tts_speed_up.sh ln -sf <插件>/scripts/tts_speed_down.sh ~/.local/bin/tts_speed_down.sh ln -sf <插件>/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“您好，引导程序完成。” --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：卷曲-s“https://api.telegram.org/bot${BOT_TOKEN}/getMe”| jq.好的 ** ** ## TodoWrite 任务模板 ### 模板：全栈引导 1. [预检] 验证 Bun 已安装 2. [预检] 验证mise是否安装 3. [预检] 验证 uv 已安装 4. [预检] 通过 uv 验证 Python 3.13 是否可用 5. [Kokoro] 运行 kokoro-install.sh --install 6.【Kokoro】验证MLX-Audio加速 7. [BotFather] 指导 BotFather 代币创建（或验证现有） 8. [Secrets] 将令牌存储在 ~/.claude/.secrets/ccterrybot-telegram 中 9. [Secrets] 创建 .mise.local.toml，其中 _.file 引用 Secrets 10.【环境】在mise.toml中添加KOKORO_VENV和KOKORO_SCRIPT 11. [符号链接] 为所有 TTS shell 脚本创建 ~/.local/bin/ 符号链接 12.【验证】用Kokoro生成测试WAV并用afplay播放 13. [验证] 检查机器人通过 Telegram API 响应 /status ** ** ## 变更后清单修改该技能后： 1. 验证 `kokoro-install.sh --health` 通过所有 6 个检查 2. 确认 `.mise.local.toml` 被 gitignored 3.测试符号链接正确解析（`ls -la ~/.local/bin/tts_*.sh`） 4. 通过“getMe” API 调用验证机器人令牌是否有效 5. 运行完整的 TTS 往返：剪贴板文本到音频播放 6. 使用更改描述更新 `references/evolution-log.md` ** ** ## 故障排除问题 |原因 |解决方案 ---|---|--- 未找到紫外线 |未安装 | `brew 安装 uv` Python 3.13 不可用 |未通过 uv 安装 | `uv python 安装 3.13` 不是苹果芯片|英特尔 Mac 或 Linux |需要 M1 或更新版本的 Mac（MLX Metal）模型下载失败 |网络问题或 HuggingFace 中断 |检查互联网连接，重试 BotFather 令牌无效 |拼写错误或撤销令牌 |通过 `curl https://api.telegram.org/bot/getMe` 进行验证 kokoro-install.sh 权限被拒绝 |脚本不可执行 | `chmod +x 脚本/kokoro-install.sh` Venv 已经存在 |以前的部分安装 |运行 `kokoro-install.sh --uninstall` 然后运行 `--install` 找不到 tts_generate.py |捆绑包复制失败 |检查插件中是否存在“scripts/tts_generate.py” ** ** ## 参考文档 * [Kokoro Bootstrap]() \- 详细的 venv 设置、Python 3.13 via uv、MLX-Audio、模型下载 * [BotFather 指南]() \- 分步 Telegram 机器人创建和令牌管理 * [Upstream Fork]() \- MLX-Audio Kokoro 上游和捆绑脚本原理 * [进化日志]() \- 更改此技能的历史记录

全栈引导程序

包含技能