Back to Details

settings-and-tuning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Settings and Tuning

设置与调优

Configure all adjustable parameters for the TTS engine, Telegram bot, and supporting infrastructure. All settings are centralized in the mise.toml SSoT.
Platform: macOS (Apple Silicon)
配置TTS引擎、Telegram机器人及配套基础设施的所有可调参数。所有设置都集中存放在作为唯一真实数据源（SSoT）的mise.toml文件中。
平台: macOS (Apple Silicon)

When to Use This Skill

何时使用该技能

  • Changing TTS voice (English, Chinese, or macOS 
    say
    voices)
  • Adjusting speech speed
  • Tuning TTS timeouts or queue depth
  • Configuring notification rate limiting or circuit breakers
  • Adjusting prompt executor throttling
  • Modifying session picker limits
  • Changing audit log retention
  • 更换TTS语音（英文、中文，或是macOS 
    say
    命令自带语音）
  • 调整语音播放速度
  • 调优TTS超时时间或队列深度
  • 配置通知限流或熔断机制
  • 调整提示词执行器节流规则
  • 修改会话选择器限制
  • 更改审计日志保留时长

Requirements

前置要求

ComponentRequiredInstallation
miseYes
brew install mise
(for env loading)
Bot runningRecommendedChanges to TTS/queue settings require bot restart
组件要求安装说明
mise必须
brew install mise
（用于环境加载）
运行机器人推荐修改TTS/队列设置后需要重启机器人

Workflow Phases

工作流阶段

Phase 0: Read Current Configuration

阶段0：读取当前配置

Read the current mise.toml to see all active settings:
bash
cat ~/.claude/automation/claude-telegram-sync/mise.toml
All configurable values live in the 
[env]
section. The file is the single source of truth for the entire stack.
读取当前的mise.toml文件查看所有生效设置：
bash
cat ~/.claude/automation/claude-telegram-sync/mise.toml
所有可配置值都位于 
[env]
区块下，该文件是整个技术栈的唯一真实数据源。

Phase 1: Identify What to Change

阶段1：确认要修改的配置项

Present the config groups to the user via AskUserQuestion. Config groups:
GroupSettingsDescription
TTS Voice
TTS_VOICE_EN
, 
TTS_VOICE_ZH
, 
TTS_VOICE_SAY_EN
, 
TTS_VOICE_SAY_ZH
Voice selection per language
TTS Speed
TTS_SPEED
Speech rate multiplier
TTS Timeouts
TTS_GENERATE_TIMEOUT_MS
, 
TTS_SAY_TIMEOUT_MS
Generation and playback timeouts
TTS Queue
TTS_MAX_QUEUE_DEPTH
, 
TTS_STALE_TTL_MS
, 
TTS_MAX_TEXT_LEN
Queue limits and staleness
TTS Signal
TTS_SIGNAL_SOUND
Signal sound path (empty to disable)
Rate Limiting
NOTIFICATION_MIN_INTERVAL_MS
, 
SUMMARIZER_*
Notification and summarizer throttling
Prompt Executor
PROMPT_*
Prompt execution throttling and circuit breaker
Session Picker
SESSION_*
Session scanning and display limits
Audit
AUDIT_RETENTION_DAYS
Log retention period
Model
HAIKU_MODEL
Claude model for Agent SDK calls
通过AskUserQuestion向用户展示配置分组，配置分组如下：
分组设置项说明
TTS语音
TTS_VOICE_EN
, 
TTS_VOICE_ZH
, 
TTS_VOICE_SAY_EN
, 
TTS_VOICE_SAY_ZH
各语言的语音选择
TTS语速
TTS_SPEED
语速倍数
TTS超时
TTS_GENERATE_TIMEOUT_MS
, 
TTS_SAY_TIMEOUT_MS
生成与播放超时
TTS队列
TTS_MAX_QUEUE_DEPTH
, 
TTS_STALE_TTL_MS
, 
TTS_MAX_TEXT_LEN
队列限制与过期时长
TTS提示音
TTS_SIGNAL_SOUND
提示音文件路径（为空则禁用）
限流
NOTIFICATION_MIN_INTERVAL_MS
, 
SUMMARIZER_*
通知和摘要生成器节流
提示词执行器
PROMPT_*
提示词执行节流与熔断
会话选择器
SESSION_*
会话扫描与展示限制
审计
AUDIT_RETENTION_DAYS
日志保留周期
模型
HAIKU_MODEL
Agent SDK调用使用的Claude模型

Phase 2: Edit Configuration

阶段2：编辑配置

Edit the appropriate line(s) in 
~/.claude/automation/claude-telegram-sync/mise.toml
. Use the Edit tool to make precise changes to specific values.
编辑 
~/.claude/automation/claude-telegram-sync/mise.toml
文件中的对应行，使用编辑工具对特定值进行精确修改。

Phase 3: Validate and Apply

阶段3：验证并生效

  1. Verify the edited value is within the valid range (see Config Reference)
  2. If TTS, queue, or rate limiting settings changed, restart the bot:
bash
undefined
  1. 确认编辑后的值处于合法范围内（参考配置参考）
  2. 如果修改了TTS、队列或限流设置，重启机器人：
bash
undefined

Option A: If using mise tasks

选项A：使用mise任务

cd ~/.claude/automation/claude-telegram-sync && mise run bot:restart
cd ~/.claude/automation/claude-telegram-sync && mise run bot:restart

Option B: Manual restart

选项B：手动重启

pkill -f "bun.*main.ts" && cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

1. Confirm new settings are active by checking bot logs or testing the affected feature

---
pkill -f "bun.*main.ts" && cd ~/.claude/automation/claude-telegram-sync && bun --watch run src/main.ts

3. 通过查看机器人日志或测试受影响功能，确认新设置已生效

---

TodoWrite Task Templates

待编写任务模板

Template: Settings Adjustment

模板：设置调整

1. [Read] Read current mise.toml configuration
2. [Identify] Present config groups to user via AskUserQuestion
3. [Select] User selects setting category to modify
4. [Edit] Update mise.toml with new values
5. [Validate] Verify values are in valid range
6. [Apply] Restart bot to apply changes (if TTS or queue settings changed)
7. [Verify] Confirm new settings are active
1. [Read] Read current mise.toml configuration
2. [Identify] Present config groups to user via AskUserQuestion
3. [Select] User selects setting category to modify
4. [Edit] Update mise.toml with new values
5. [Validate] Verify values are in valid range
6. [Apply] Restart bot to apply changes (if TTS or queue settings changed)
7. [Verify] Confirm new settings are active

Post-Change Checklist

修改后检查清单

After modifying this skill:
  1. Verify all config groups in SKILL.md match current mise.toml
  2. Update config-reference.md if new env vars were added
  3. Test that changed settings take effect after bot restart
  4. Update 
    references/evolution-log.md
    with change description
修改该技能后：
  1. 确认SKILL.md中的所有配置分组与当前mise.toml一致
  2. 如果新增了环境变量，更新config-reference.md
  3. 测试修改后的设置在机器人重启后能正常生效
  4. 在 
    references/evolution-log.md
    中更新修改说明

Troubleshooting

故障排查

IssueCauseSolution
Settings not taking effectBot not restartedRestart bot after changing mise.toml
mise.toml parse errorInvalid TOML syntaxCheck for missing quotes or unescaped chars
Voice not foundInvalid voice nameCheck voice catalog (Kokoro voices are case-sensitive)
Speed too fast/slowValue out of rangeUse 0.5 to 2.0 range for TTS_SPEED
Circuit breaker stuck openToo many failuresWait for breaker timeout or restart bot
Timeout too shortTTS generation slow on first runModel warmup takes longer; increase timeout
问题原因解决方案
设置不生效机器人未重启修改mise.toml后重启机器人
mise.toml解析错误TOML语法无效检查是否缺少引号或存在未转义字符
找不到语音语音名称无效检查语音目录（Kokoro语音区分大小写）
语速过快/过慢值超出范围TTS_SPEED取值范围为0.5到2.0
熔断器处于打开状态失败次数过多等待熔断器超时或重启机器人
超时时间过短首次运行时TTS生成速度慢模型预热需要更长时间，调高超时时间

Reference Documentation

参考文档

  • Config Reference - Full reference table with all env vars, defaults, valid ranges, and component ownership
  • mise.toml Reference - Hub/spoke mise architecture, secret loading, and task file structure
  • Evolution Log - Change history for this skill
  • 配置参考 - 包含所有环境变量、默认值、合法范围和所属组件的完整参考表
  • mise.toml参考 - 中心/分支mise架构、密钥加载和任务文件结构说明
  • 迭代日志 - 该技能的修改历史