Tts Error Reporting
Developmenttts-error-reportingTts Error Reporting is an Agent Skill for development published in the Project-N-E-K-O/N.E.K.O repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Convention for reporting errors from multiprocessing TTS workers to the main process frontend. Use this skill when modifying, adding, or debugging TTS workers in tts_client.py to ensure connection errors, quotas, and API limits correctly display Toast notifications to the user rather than failing silently.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Project-N-E-K-O/N.E.K.O/blob/HEAD/.agent/skills/tts-error-reporting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tts-error-reporting, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
TTS Error Reporting Protocol
To ensure users are properly notified when a TTS service encounters an error (such as quota exhaustion, API issues, or connection failures), TTS workers running in separate processes must propagate errors back to the main process (core.py).
Core Rule: Use response_queue.put(("__error__", error_msg))
When a TTS worker (e.g. step_realtime_tts_worker, qwen_realtime_tts_worker, etc.) catches an error, it MUST NOT only log the error using logger.error(). It MUST ALSO send the error message back to the main process through its response_queue using the explicit tuple format ("__error__", error_msg).
This ensures that core.py's tts_response_handler can intercept the error and translate it into a frontend WebSocket message (type: 'status'), triggering a user-friendly Toast notification (e.g., "💥 免费TTS限额已耗尽").
Example Implementation
# Bad Pattern (Fails silently for user)
except Exception as e:
logger.error(f"TTS Worker Error: {e}")
# Worker dies or hangs, user stuck on "Preparing..."
# Good Pattern (Structured JSON error for i18n frontend toasts)
import json
except Exception as e:
logger.error(f"TTS Worker Error: {e}")
# Map to specific error codes known to i18n
error_payload = json.dumps({"code": "API_QUOTA_TIME", "details": str(e)})
response_queue.put(("__error__", error_payload))
# Acceptable Fallback (Fallback 1008 error if code unknown)
except Exception as e:
logger.error(f"TTS Worker Error: {e}")
error_payload = json.dumps({"code": "API_1008_FALLBACK", "msg": str(e)})
response_queue.put(("__error__", error_payload))
WebSocket Stream Callbacks Example
import json
def on_error(self, message: str):
logger.error(f"TTS Error: {message}")
error_payload = json.dumps({"code": "API_1008_FALLBACK", "msg": message})
self.response_queue.put(("__error__", error_payload))
Checklist for Adding a New TTS Worker
Whenever you add a new TTS API worker in tts_client.py:
- Ensure the worker signature accepts a
response_queue. - Locate all network initialization blocks,
try/exceptloops, andon_errorWebSocket callbacks. - In every local exception block where the worker might fail or drop the connection, add
response_queue.put(("__error__", error_message_string)). - Ensure string encoding handles JSON cleanly if propagating raw API errors.