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 询问用户要升级哪个组件。提供上方的四个选项。

阶段 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. 确认自身位置。 — 编辑前，查找此 SKILL.md 的规范路径（使用 Glob 搜索此技能的名称）。所有修正都应针对此文件及其同级的 references/ — 绝不修改其他文档。
1. 哪里出了问题？ — 修复导致问题的指令。如果问题可能再次发生，将其列为反模式。
2. 哪些做得比预期更好？ — 将其列为推荐做法，并说明原因。
3. 哪些内容发生了偏差？ — 任何与实际情况不符的脚本、参考资料或外部依赖，都要立即修正。
4. 记录下来。 — 每项更改都要在演进日志中记录触发原因、修复内容和证据。

切勿推迟。下一次调用会继承你留下的内容。

---

---