Back to Details

component-version-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Component Version Upgrade

组件版本升级

Upgrade individual components of the TTS + Telegram bot stack without rebuilding the entire system.
Platform: macOS (Apple Silicon)
无需重建整个系统，即可升级TTS + Telegram机器人栈中的单个组件。
平台：macOS (Apple Silicon)

When to Use This Skill

何时使用此Skill

  • User wants to upgrade Kokoro TTS engine, Python dependencies, or the model
  • User wants to update bot dependencies (Bun packages)
  • User wants to refresh 
    tts_generate.py
    from the plugin bundle
  • User wants to bump the Bun runtime version
  • 用户希望升级Kokoro TTS引擎、Python依赖项或模型
  • 用户希望更新机器人依赖项（Bun包）
  • 用户希望从插件包刷新
    tts_generate.py
  • 用户希望升级Bun运行时版本

Requirements

要求

  • uv
    installed (
    brew install uv
    )
  • mise
    installed and configured
  • Internet connectivity for package downloads
  • Existing installation (run 
    full-stack-bootstrap
    first if not installed)
  • 已安装
    uv
    （
    brew install uv
    ）
  • 已安装并配置
    mise
  • 具备下载包所需的网络连接
  • 已完成初始安装（若未安装，先运行
    full-stack-bootstrap
    ）

Upgradeable Components

可升级组件

ComponentCommandWhat It Does
Kokoro TTS engine
kokoro-install.sh --upgrade
Upgrades Python deps, re-downloads model, updates version.json
Bot dependencies
cd ~/.claude/automation/claude-telegram-sync && bun update
Updates Bun packages per package.json
tts_generate.pyRe-copy from plugin 
scripts/
to 
~/.local/share/kokoro/
Updates the TTS generation script
Bun runtime
mise use bun@latest
Updates the Bun version in mise.toml
组件命令功能说明
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版本

Workflow Phases

工作流阶段

Phase 1: Component Selection

阶段1：组件选择

Ask the user which component to upgrade using AskUserQuestion. Present the four options above.
使用AskUserQuestion询问用户要升级哪个组件，提供上述四个选项。

Phase 2: Pre-Upgrade Health Check

阶段2：升级前健康检查

bash
undefined
bash
undefined

Run health check to establish baseline

运行健康检查以建立基准

~/.local/share/kokoro/../../eon/cc-skills/plugins/tts-telegram-sync/scripts/kokoro-install.sh --health
~/.local/share/kokoro/../../eon/cc-skills/plugins/tts-telegram-sync/scripts/kokoro-install.sh --health

Record current versions

记录当前版本

cat ~/.local/share/kokoro/version.json
undefined
cat ~/.local/share/kokoro/version.json
undefined

Phase 3: Execute Upgrade

阶段3：执行升级

Run the appropriate upgrade command for the selected component.
运行所选组件对应的升级命令。

Phase 4: Post-Upgrade Verification

阶段4：升级后验证

bash
undefined
bash
undefined

Health check again

再次运行健康检查

kokoro-install.sh --health
kokoro-install.sh --health

Generate test audio to verify TTS still works

生成测试音频以验证TTS功能正常

~/.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
undefined
~/.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
undefined

Phase 5: Bot Restart (if needed)

阶段5：重启机器人（若需要）

If bot dependencies or Bun runtime were upgraded, restart the bot:
bash
pkill -f 'bun.*src/main.ts' || true
cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts
如果升级了机器人依赖项或Bun运行时，重启机器人：
bash
pkill -f 'bun.*src/main.ts' || true
cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

TodoWrite Task Templates

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
1. [识别] 通过AskUserQuestion展示可升级组件
2. [预检] 对目标组件运行健康检查
3. [备份] 记录当前版本（version.json、package.json）
4. [升级] 执行升级命令
5. [验证] 运行升级后健康检查
6. [测试] 生成测试音频以验证TTS功能正常
7. [重启] 若需要则重启机器人
8. [报告] 展示升级前后版本

Post-Change Checklist

变更后检查清单

  • Health check passes (all 8 checks OK)
  • version.json updated with new versions
  • Test audio generates and plays correctly
  • Bot is running if it was restarted
  • 健康检查通过（所有8项检查正常）
  • version.json已更新为新版本
  • 测试音频可正常生成并播放
  • 若重启了机器人，机器人已正常运行

Troubleshooting

故障排除

ProblemLikely CauseFix
Upgrade failsNo internet or PyPI issueCheck connectivity, retry
Model download slowFirst-time ~400MB, subsequent cachedWait for download to complete
Version mismatchStale version.jsonRe-run 
kokoro-install.sh --health
to check, 
--upgrade
to fix
MPS unavailable after upgradetorch version incompatibility
kokoro-install.sh --upgrade
reinstalls torch
Bot won't start after upgradeDependency conflict
cd ~/.claude/automation/claude-telegram-sync && bun install
问题可能原因解决方法
升级失败无网络或PyPI问题检查网络连接，重试
模型下载缓慢首次下载约400MB，后续会缓存等待下载完成
版本不匹配version.json过期重新运行
kokoro-install.sh --health
检查，使用
--upgrade
修复
升级后MPS不可用torch版本不兼容
kokoro-install.sh --upgrade
会重新安装torch
升级后机器人无法启动依赖冲突
cd ~/.claude/automation/claude-telegram-sync && bun install

Reference Documentation

参考文档

  • Upgrade Procedures -- Step-by-step upgrade instructions with rollback for each component
  • Evolution Log -- Change history for this skill
  • 升级流程 -- 每个组件的分步升级说明及回滚方案
  • 演进日志 -- 此Skill的变更历史