Telegram 原生音频

作者： Fabyano Titara

使用此技能仅操作 Picoclaw 的 原生 Telegram 客户端。

强制规则

• 不得使用 webhook。
• 不得使用 cloudflared。
• 不得创建并行 bot。
• 须保留当前已启用的 Telegram 原生通信通道。

目标

通过一个 半自动模型，实现 Telegram 原生客户端中的语音对话流程：

1. Picoclaw 下载 Telegram 中接收到的音频文件。
2. Watcher 检测到新音频文件后，自动将其转录为文本。
3. 助手接收该文本转录结果，并决定如何响应。
4. 助手调用终结脚本，生成并发送语音形式的响应。

依赖要求

• GROQ API 密钥：必须配置环境变量 GROQ_API_KEY，以支持语音转文字功能（使用模型 whisper-large-v3-turbo）。
• Edge TTS：用于语音合成（选用音色 pt-BR-FranciscaNeural）。

包含的功能组件（脚本）

• scripts/transcribe_audio.py：使用 GROQ Whisper 进行音频转文字。
• scripts/generate_audio.py：使用 EDGE TTS 生成语音音频。
• scripts/semi_auto_watcher.py：监控 Picoclaw 的媒体目录（/tmp/picoclaw_media），自动转录新音频，并创建待处理的响应任务（pendency）。
• scripts/finalize_reply.py：接收待处理任务 ID 和最终响应文本，生成语音并回传给用户。
• scripts/cleanup_old_files.py：自动清理脚本，删除超过 15 天 的音频文件（包括 inbox、outbox 和 tmp 目录下的文件）。

使用方法

1. 启动 Watcher（半自动模式）

Watcher 以后台方式持续运行，用于处理新收到的音频：

nohup python3 /root/.picoclaw/workspace/skills/telegram-native-audio/scripts/semi_auto_watcher.py > /root/.picoclaw/workspace/skills/telegram-native-audio/scripts/semi_auto_watcher.log 2>&1 &

2. 回复一条音频待办任务

当接收到一段音频时，它将被自动转录，并通知助手。若需以语音形式回复，请助手执行以下命令：

python3 /root/.picoclaw/workspace/skills/telegram-native-audio/scripts/finalize_reply.py 
  "ID_DA_PENDENCIA" 
  "将被朗读的响应文本"

3. 自动清理（Auto-Cleanup）

对超过 15 天的旧音频文件的清理工作由 semi_auto_watcher.py 自动管理，该脚本每日定时执行一次 cleanup_old_files.py。

注意事项

• 请根据 Telegram 原生通道对格式的支持情况，优先选用 .ogg 或 .mp3 格式。
• 开发或维护此技能时，请聚焦于与 Picoclaw 当前 runtime 的集成，而非外部 Telegram 自动化。