AgentSkillsCN

telegram-gateway-debug-loop

通过Peekaboo CLI，对macOS界面进行调试与压力测试，模拟Telegram对话的两端角色：先以调试日志运行lemon-gateway，再使用Telethon并输入用户凭证，在专用话题中发送或回复消息，同时实时监控gateway日志与运行时状态。适用于处理卡顿、投递失败、调度器/锁争用、异步委托缺陷，以及上下文溢出等问题。

SKILL.md
--- frontmatter
name: telegram-gateway-debug-loop
description: "Debug and stress-test lemon gateway behavior by acting as both sides of Telegram conversations: run lemon-gateway with debug logs, then use Telethon with user credentials to send/reply messages in a dedicated topic while watching gateway logs and runtime state. Use for stuck runs, delivery failures, scheduler/lock contention, async delegation bugs, and context overflows."
disable-model-invocation: true
argument-hint: "[description of issue to debug]"
allowed-tools: Read, Grep, Bash, Glob, Write

Telegram Gateway Debug Loop

Use this skill to run end-to-end repros with real Telegram traffic.

Setup

  1. •

    Load Telegram credentials from ~/.zeebot/api_keys/telegram.txt.

    • •Read the file to get api_id, api_hash, and phone number.
    • •NEVER print, echo, or commit these values. Hold them in memory only.
  2. •

    Start gateway with debug logging:

    bash
    cd /Users/z80/dev/lemon
LOG_LEVEL=debug ./bin/lemon-gateway --debug --sname lemon_gateway_debug

    Run this in the background and monitor its output.

  3. •

    Optionally attach a remote shell for live introspection:

    bash
    iex --sname lemon_attach --cookie lemon_gateway_dev_cookie --remsh lemon_gateway_debug@$(hostname -s)

Sending Messages via Telethon

  1. •

    Use Telethon through uv (no global install needed):

    bash
    uv run --with telethon python <script.py>

    Write a temporary Python script that:

    • •Connects with the user's Telegram credentials
    • •Sends messages into a dedicated debug topic/thread
    • •Keeps all probes in that thread
  2. •

    Stress async behavior with prompts that trigger delegation/tool runs:

    • •agent_id=coder delegation
    • •Async poll loops
    • •Multi-step tool workflows

Inspecting Runtime State

  1. •While traffic is active, inspect runtime state via the remote shell:
    • •:sys.get_state(LemonGateway.Scheduler) — scheduler state
    • •:sys.get_state(LemonGateway.EngineLock) — lock state
    • •DynamicSupervisor.which_children(LemonGateway.ThreadWorkerSupervisor) — active workers

Watching for Failures

  1. •Watch gateway logs for high-value failure signatures:
    • •:unknown_channel — message routed to unknown channel
    • •Scheduler stalls or lock starvation
    • •Context overflow/trim failures
    • •Delivery retries/timeouts

Capturing Repros

  1. •For each repro, capture:
    • •The exact prompt(s) sent
    • •Thread ID
    • •Timestamps
    • •State snapshots from the remote shell
    • •Relevant log lines

If $ARGUMENTS is provided, focus the debug session on reproducing that specific issue.

Secrets + Safety

  • •NEVER print or commit API keys, session strings, OTPs, or phone numbers.
  • •Keep credentials in local secret files only.
  • •If session auth is invalid, re-auth locally and update only local secret files.
  • •Do not include credentials in any script files that get written to disk — pass them via environment variables or read them at runtime.