Telegram - Conversa por Áudio (PICOCLAW)

Processar conversas por áudio no Telegram nativo do Picoclaw, sem webhook. Use quando o usuário quiser receber mensagem de voz, transcrever áudio recebido, g...

Security Scan

The code matches the declared purpose (voice-to-voice handling for Picoclaw) but the package declares no required environment variables or install steps while the runtime instructions and scripts require a GROQ_API_KEY, external Python packages (groq, edge_tts), hardcoded /root paths, and a long‑running background watcher — these mismatches and deployment assumptions warrant caution.

Purpose & Capability

The skill's functionality (transcribe with GROQ Whisper and synthesize with Edge TTS) is consistent with its description, but the registry metadata declares no required env vars or dependencies while SKILL.md and the scripts require GROQ_API_KEY, optionally PICOLAW_CHAT_ID/TELEGRAM_CHAT_ID, and Python packages (groq, edge_tts). The scripts also assume state directories under /root/.picoclaw and /tmp/picoclaw_media — these deployment assumptions are not declared in the registry and may be surprising or privilege-sensitive.

Instruction Scope

SKILL.md gives concrete runtime instructions (start a nohup watcher, call finalize_reply) and explicitly forbids webhooks. The instructions and scripts operate on local media folders, write state/metadata files, and rely on environment variables (GROQ_API_KEY, PICOLAW_CHAT_ID). They do not contain obvious exfiltration endpoints, but they do instruct running a persistent background process with file read/write access in the agent's workspace.

Install Mechanism

There is no install specification even though the code imports third-party Python libraries (groq, edge_tts). Without an install step or dependency manifest the skill will fail at runtime or silently rely on preinstalled packages. The lack of an explicit, vetted install source increases risk and deployment friction.

Credentials

The registry lists no required env vars, but SKILL.md and the scripts require GROQ_API_KEY (mandatory for transcription) and optionally PICOLAW_CHAT_ID / TELEGRAM_CHAT_ID. Edge TTS usage implies outbound network access. The skill also copies the full environment into subprocesses (env=os.environ.copy()), which can expose unrelated env variables to child processes — this should be considered when running in environments with sensitive env vars.

Persistence & Privilege

The skill does not set always:true, but the user is instructed to run a persistent background watcher (nohup). The scripts create and manage files under /root/.picoclaw/workspace/state/telegram-native-audio and /tmp/picoclaw_media and implement automatic cleanup. This provides persistent on-disk state and long-running processes but no modification of other skills' configs; still, running persistent processes and writing under /root are privilege decisions the operator should review.

What to consider before installing

This skill's code implements voice-to-voice processing and appears to do what it claims, but there are deployment mismatches and operational risks to consider before installing: - Required secrets/deps: The SKILL.md and scripts require GROQ_API_KEY (transcription) and rely on Python packages (groq, edge_tts), but the registry metadata declares no env vars or install steps. Do not run it without supplying GROQ_API_KEY and installing those packages in a controlled environment. - Installation: Add a clear dependency/install step (pip install groq edge_tts ...) or run in a virtualenv/container. Avoid running arbitrary code without pinning package versions. - Privileges & paths: The scripts use hardcoded /root/.picoclaw paths and /tmp/picoclaw_media and instruct starting a persistent nohup process; consider adjusting paths to a less-privileged user and run the watcher under a managed service/sandbox (systemd unit, container) rather than as root. - Environment leakage: finalize_reply/other scripts pass os.environ.copy() to subprocesses — ensure no sensitive environment variables are present or sanitize env before running. - Cleanup policy: The cleanup script deletes .json files and audio older than 15 days in the skill state directories. Confirm this retention policy is acceptable and that important metadata won't be removed unintentionally. - Network & secrets: Transcription and TTS call external services; ensure you trust the services and the provided API key scope. Monitor outbound network usage. If you want to proceed safely: request an install manifest from the author (requirements.txt or pyproject), confirm required env vars in registry metadata (GROQ_API_KEY, optional PICOLAW_CHAT_ID), run the skill in a container or dedicated service account, and review logs during an initial test. If the author cannot supply a dependency list or explain the /root path choice, treat the package with extra caution.

Telegram Native Audio

Criador: Fabyano Titara

Use esta skill para operar somente no Telegram nativo do Picoclaw.

Regras obrigatórias

• Não usar webhook.
• Não usar cloudflared.
• Não criar bot paralelo.
• Preservar o canal Telegram nativo já ativo.

Objetivo

Permitir o fluxo de conversas por voz no Telegram nativo através de um modelo semiautomático:

1. O Picoclaw baixa o áudio recebido no Telegram.
2. O watcher detecta o arquivo e transcreve automaticamente para texto.
3. O assistente recebe a transcrição e decide a resposta.
4. O assistente gera e envia a resposta em áudio usando um script finalizador.

Requisitos

• Chave de API do GROQ: É obrigatório configurar a variável de ambiente GROQ_API_KEY para o funcionamento da transcrição (modelo whisper-large-v3-turbo).
• Edge TTS: Utilizado para a geração de áudio (voz pt-BR-FranciscaNeural).

Recursos incluídos (Scripts)

• scripts/transcribe_audio.py: transcreve áudio com GROQ Whisper.
• scripts/generate_audio.py: gera áudio com EDGE TTS.
• scripts/semi_auto_watcher.py: monitora a pasta de mídia do Picoclaw (/tmp/picoclaw_media), transcreve novos áudios automaticamente e cria uma pendência de resposta.
• scripts/finalize_reply.py: recebe a pendência e o texto final da resposta, gera o áudio e envia de volta ao usuário.
• scripts/cleanup_old_files.py: rotina de limpeza automática que remove arquivos de áudio (inbox, outbox, tmp) mais antigos que 15 dias.

Como usar

1. Iniciar o Watcher (Semiautomático)

O watcher roda em background para processar novos áudios:

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. Responder a uma pendência de áudio

Quando um áudio é recebido, ele será transcrito e notificado ao assistente. Para responder com voz, o assistente deve executar:

python3 /root/.picoclaw/workspace/skills/telegram-native-audio/scripts/finalize_reply.py \
  "ID_DA_PENDENCIA" \
  "Texto da resposta que será falada"

3. Limpeza Automática (Auto-Cleanup)

A limpeza de áudios antigos (mais de 15 dias) é gerenciada automaticamente pelo semi_auto_watcher.py, que executa o script cleanup_old_files.py uma vez por dia.

Observações

• Preferir .ogg ou .mp3 conforme o canal aceitar melhor.
• Ao trabalhar nesta skill, manter o foco em integração com o runtime atual do Picoclaw, não em automação externa do Telegram.