¿Qué hace signalradar?
Canales de Entrega
SignalRadar admite tres adaptadores de entrega para enviar alertas:
webhook(recomendado, portátil) — HTTP POST a cualquier endpoint (webhook de Slack, API de Telegram Bot, Discord, etc.). Funciona en cualquier plataforma. Cuando se combina con programacióncrontab, entrega notificaciones con cero costo de LLM y cero dependencia de plataforma.file— Añade alertas a un archivo JSONL local. Bueno para registro local o consumo personalizado.openclaw(solo OpenClaw) — Mensajería de la plataforma OpenClaw. Solo disponible cuando se instala a través de ClawHub. No es portátil a otras plataformas.
El canal de entrega predeterminado es webhook. Configure su URL de webhook con:
python3 scripts/signalradar.py config delivery webhook https://su-url-de-webhook
Ruta de entrega (detalle técnico):
crontab → signalradar.py run --yes --output json → HIT detectado → deliver_hit() → HTTP POST a URL de webhook → mensaje entregado. Cero dependencia de plataforma, cero costo de LLM.
Mapeo de Intenciones
Después de recibir un mensaje del usuario, elija un comando de esta tabla. Cuando ninguna intención coincida, NO ejecute ningún comando — simplemente charle normalmente.
| Intención del usuario (expresiones comunes en chino) | Intención en inglés | Comando |
|---|---|---|
| "看看我监控了啥" / "我的列表" / "在追踪哪些" | "list my monitors" / "what am I tracking" | list |
| "有啥变化吗" / "检查一下" / "跑一下" | "any changes?" / "run a check" | run |
| "帮我加一下 [URL]" / "监控这个链接" | "add this market" / "monitor this" | add <url> |
| "帮我加几个市场" / "想监控但没链接" | "add markets" (no URL) | add (sin argumento) → lista de seguimiento vacía devuelve ONBOARD_NEEDED, el agente inicia el flujo onboard |
| "删掉第 N 个" / "不监控这个了" | "remove #N" / "stop monitoring" | remove <N> |
| "阈值改成 X" / "灵敏度调高" | "change threshold" / "more sensitive" | config threshold.abs_pp <X> |
| "多久检查一次" / "改成 30 分钟" | "check frequency" / "every 30 min" | schedule / schedule 30 |
| "自动监控还在跑吗" / "cron 状态" | "is auto-monitoring running?" | schedule (ver estado) |
| "现在设置是什么" / "阈值多少" | "what are current settings?" | config (debe verificar el valor real) |
| "健康检查" / "能用吗" | "health check" / "is it working?" | doctor --output json |
| "周报" / "本周总结" / "生成 digest" | "weekly digest" / "summary report" | digest |
| "设置推送" / "配置通知渠道" | "set up notifications" / "configure delivery" | Guiar al usuario para que proporcione la URL del webhook, luego config delivery webhook <url> |
| "通知改中文" / "语言改中文" | "switch to Chinese notifications" | config profile.language zh |
| "好的" / "没事" / "OK" / "知道了" | casual chat | NO ejecutar ningún comando |
| "那个 GPT 概率多少了" | "what's the probability of X?" | `show <number |
Reglas Críticas
CR-01 Eventos con múltiples mercados deben informar el conteo primero
Si el evento tiene múltiples mercados (>3), la CLI fuerza la impresión del conteo, resumen de tipos y lista de mercados antes de esperar confirmación; --yes no puede omitir esto. El agente aún debe explicar el conteo y los tipos antes de ejecutar add.
CR-02 Nunca agregar mercados automáticamente El usuario debe proporcionar explícitamente una URL de Polymarket o elegir entre las predefinidas. No agregar automáticamente.
CR-03 El agente no debe editar directamente archivos de datos
El agente no debe editar ~/.signalradar/cache/, ~/.signalradar/config/watchlist.json ni archivos de línea base usando herramientas de Escritura/Edición. Use solo comandos CLI. Las ejecuciones normales escriben estos archivos automáticamente — ese es el comportamiento esperado. (Nota: el usuario humano puede editar manualmente watchlist.json — el sistema lo tolera. Esta regla solo restringe al Agente.)
CR-04 No usar --yes en conversaciones humanas
Al interactuar con un usuario humano, el Agente NO debe usar la bandera --yes. La bandera --yes es solo para pipelines automatizados/CI (pruebas de humo, trabajos cron, pasos previos a publicación). Deje que la confirmación incorporada maneje la interacción con el usuario.
CR-05 Siempre verificar los valores de configuración reales
Cuando el usuario pregunte sobre la configuración actual, SIEMPRE ejecute signalradar.py config primero. No adivine ni recuerde de memoria. Si falta un valor, informe el valor predeterminado y diga "este es el valor predeterminado".
CR-06 Habilitar monitoreo automático después de la primera adición (crontab primero, con puerta de ruta)
Después del primer add o onboard finalize, el monitoreo en segundo plano intenta habilitarse automáticamente (intervalo de 10 minutos). Prefiere crontab del sistema; recurre a openclaw cron solo cuando crontab no está disponible. Puerta de ruta: cuando delivery.primary.channel == openclaw + controlador crontab + sin ruta de respuesta capturada, la CLI habilita el monitoreo pero devuelve una advertencia route_missing porque las comprobaciones pueden ejecutarse mientras la entrega de chat en segundo plano no está lista. El Agente NO debe preguntar "¿debo configurar cron?" y NO debe crear trabajos manualmente. Verifique delivery_status en schedule --output json e informe honestamente si el monitoreo y la entrega están activos. Combinación recomendada: programación crontab + entrega webhook = cero costo de LLM + cero dependencia de plataforma.
CR-07 Use CLI para administrar la configuración y la programación
Use signalradar.py config [key] [value] para la configuración (umbral, canal de entrega, etc.). Use signalradar.py schedule [N|disable] [--driver auto|openclaw|crontab] para la frecuencia de monitoreo. No edite manualmente archivos JSON de configuración.
CR-08 Lista de seguimiento vacía activa la incorporación
Cuando la lista de seguimiento está vacía y el Agente ejecuta add/run --output json, la respuesta será ONBOARD_NEEDED. El Agente debe iniciar el flujo de onboard de 3 pasos, no sugerir proporcionar una URL.
CR-09 La incorporación es un flujo de 3 pasos + guía de webhook (principio de puente estrecho)
En modo Bot/Agente, la incorporación de nuevos usuarios pasa por el subcomando onboard en tres pasos:
onboard --step preview --output json→ mostrar lista de eventos predefinidos + educación sobre terminología (evento/mercado) → preguntar al usuario "¿cuáles eliminar?"onboard --step confirm --keep <selección-del-usuario> --output json→ mostrar detalles de submódulos + terminología (categoría/línea base) → preguntar "¿confirmar agregar?"onboard --step finalize --output json→ escribir lista de seguimiento + habilitar monitoreo automático → mostrar finalización + próximos pasos Cada paso debe esperar la respuesta del usuario antes de continuar. No comprima los 3 pasos en 1.
Guía de webhook (después de finalizar): El JSON ONBOARD_COMPLETE contiene el campo webhook_setup. Cuando webhook_setup.needed == true, el Agente debe guiar proactivamente al usuario para configurar una URL de webhook para la entrega push en segundo plano. Proporcione ejemplos de URL de Telegram Bot API / Slack / Discord. Después de que el usuario proporcione la URL, ejecute config delivery webhook <URL>.
CR-10 El push en segundo plano requiere una ruta de respuesta capturada
El --push en segundo plano en la ruta crontab requiere una ruta de respuesta almacenada (~/.signalradar/cache/openclaw_reply_route.json). Si falta, NO afirme que la entrega en segundo plano está funcionando. Para la entrega openclaw, verifique schedule --output json para delivery_status y route_ready.
CR-11 Verificar el estado real antes de afirmar que el push está listo (consciente del canal)
Antes de decirle al usuario que el push en segundo plano está funcionando, verifique schedule --output json → campo delivery_status:
"ready"→ el push está funcionando para el canal de entrega actual"webhook_url_missing"→ guíe al usuario para que ejecuteconfig delivery webhook <URL>"route_missing"→ solo relevante para el canal openclaw; si el usuario está en webhook, este campo no aparecerá"file_target_missing"→ guíe al usuario para que establezca el destino del archivo
No mezcle diagnósticos entre canales. Si el canal de entrega es webhook, no verifique ni informe route_ready — es irrelevante. El campo delivery_status ya tiene en cuenta el canal activo.
Errores Conocidos de la IA (NO repetir)
Estos errores ocurrieron realmente en producción. El Agente debe evitarlos.
Error 1: Agregar 28 mercados sin informar el conteo primero
- INCORRECTO: El usuario envía URL de Bitcoin → El Agente ejecuta
addy agrega 28 mercados silenciosamente - CORRECTO: Informar "Este evento tiene 28 submódulos (14 alcistas + 14 bajistas). ¿Agregar todos o elegir?" → esperar respuesta
Error 2: El usuario dice "好的" → El Agente activa run y devuelve NO_REPLY
- INCORRECTO: Usuario dice "好的" → El Agente ejecuta
signalradar.py run→ responde "NO_REPLY" - CORRECTO: "好的" es un reconocimiento casual. Responda normalmente sin ejecutar ningún comando.
Error 3: Usar --yes en conversaciones humanas
- INCORRECTO:
signalradar.py add <url> --yes(omite confirmación en chat humano) - CORRECTO:
signalradar.py add <url>(deje que la confirmación incorporada lo maneje; la CLI previsualiza forzosamente lotes grandes)
Error 4: Editar watchlist.json con herramientas de Escritura/Edición
- INCORRECTO: Editar
~/.signalradar/config/watchlist.jsoncon herramientas de Escritura/Edición - CORRECTO: Use comandos CLI
signalradar.py add,remove,config
Error 5: Adivinar valores de configuración de memoria
- INCORRECTO: "El umbral predeterminado es 5pp" (sin verificar)
- CORRECTO: Ejecute
signalradar.py config threshold.abs_ppprimero, luego responda con el valor real
Error 6: Escribir scripts compensatorios fuera de la habilidad
- INCORRECTO: Escribir scripts auxiliares fuera de la habilidad, como
send_alerts_to_telegram.py, para compensar el comportamiento faltante - CORRECTO: Mantener el monitoreo, la programación y la entrega dentro del contrato de la habilidad/tiempo de ejecución. Si hay una brecha real, arregle la habilidad en lugar de inventar scripts secundarios
Error 7: Tratar una actualización de clawhub como una instalación nueva sin verificar datos
- INCORRECTO: Después de
clawhub update, asumir que el usuario perdió todos los datos y tratar la instalación como nueva sin verificar el directorio de datos de tiempo de ejecución - CORRECTO: Leer primero el directorio de datos de usuario real (
~/.signalradar/oSIGNALRADAR_DATA_DIR) y solo entonces decidir si se necesita migración o recuperación
Error 8: Afirmar que el push está listo sin verificar la URL del webhook
- INCORRECTO: "¡El monitoreo en segundo plano está activo y las alertas se entregarán!" (cuando la URL del webhook está vacía)
- CORRECTO: Verificar
doctor --output json→ siwebhook_url_configured: false, guiar al usuario para configurar la URL del webhook
Error 9: Comprimir la incorporación de 3 pasos en una sola ejecución
- INCORRECTO: Ejecutar los 3 pasos de onboard en secuencia sin mostrar al usuario ningún resultado
- CORRECTO: Mostrar la salida de cada paso al usuario y esperar su respuesta antes de continuar
Error 10: Afirmar que el push está listo sin verificar la ruta
- INCORRECTO: "¡El push en segundo plano está listo!" (sin verificar route_ready)
- CORRECTO: Verificar
schedule --output json→ siroute_ready: false, decirle al usuario que la entrega aún no está armada
Error 11: Afirmar que el push está listo sin verificar la URL del webhook
- INCORRECTO: "¡El monitoreo en segundo plano está activo y las alertas se entregarán!" (cuando la URL del webhook está vacía)
- CORRECTO: Verificar
doctor --output json→ siwebhook_url_configured: false, guiar al usuario para configurar la URL del webhook
Inicio Rápido
# Instalar (usuarios de OpenClaw)
clawhub install signalradar
# O clonar directamente
git clone https://github.com/vahnxu/signalradar.git && cd signalradar
# 1. Verificación de salud
python3 scripts/signalradar.py doctor --output json
# 2. Agregar mercados (configuración guiada o por URL)
python3 scripts/signalradar.py add
python3 scripts/signalradar.py add https://polymarket.com/event/your-market-here
# 3. El monitoreo se inicia automáticamente después de la primera adición (cada 10 min)
# 4. Verificar estado de la programación
python3 scripts/signalradar.py schedule
# 5. Verificación manual (simulación)
python3 scripts/signalradar.py run --dry-run --output json
Tareas Comunes
Agregar un mercado
python3 scripts/signalradar.py add # Configuración guiada
python3 scripts/signalradar.py add <polymarket-event-url> [--category <name>]
Flujo: analizar URL → consultar API de Polymarket → mostrar pregunta del mercado + probabilidad actual → usuario confirma → registrar línea base.
- Si el evento tiene múltiples mercados (por ejemplo, diferentes rangos de fecha), la CLI muestra todos los mercados con sus probabilidades actuales antes de agregar. Para eventos grandes (>3 mercados), también muestra un resumen de tipos y fuerza la confirmación interactiva incluso si se pasó
--yes. - Si algunos mercados del evento ya están monitoreados, solo se agregan los nuevos.
- Si el mercado está liquidado/expirado, se muestra una advertencia pero el usuario aún puede agregarlo.
- La categoría predeterminada es
defaultsi no se especifica. No se solicita al usuario una categoría. - En la primera adición (lista de seguimiento vacía), se muestra una breve explicación del concepto de línea base.
Listar monitores
python3 scripts/signalradar.py list [--category <name>] [--archived]
Muestra todas las entradas agrupadas por categoría con numeración secuencial global. Cada entrada muestra: número, pregunta, última probabilidad conocida (de la caché de línea base local), fecha de finalización.
--archived muestra entradas eliminadas anteriormente (conservadas para exportación).
Mostrar un mercado monitoreado
python3 scripts/signalradar.py show <number-or-keyword> [--output json]
Busca uno o más mercados monitoreados por número de lista o palabra clave, obtiene la probabilidad actual y devuelve una instantánea de solo lectura sin actualizar las líneas base.
Eliminar un monitor
python3 scripts/signalradar.py remove <number>
Muestra el nombre de la entrada y solicita confirmación antes de eliminar. Las entradas eliminadas se archivan (se mueven a la matriz archived en ~/.signalradar/config/watchlist.json) con el historial completo conservado.
Ejecutar una verificación
python3 scripts/signalradar.py run [--dry-run] [--output json]
Verifica todas las entradas activas contra la API de Polymarket. Si el cambio de probabilidad supera el umbral, envía una alerta a través del canal de entrega configurado.
- Las entradas liquidadas/expiradas se omiten durante la ejecución, con un resumen al final: "N entidades liquidadas, considere eliminarlas."
- Cuando varios mercados se activan en la misma ejecución, se enumeran en la misma notificación agrupados por evento.
- Después de que se envía un HIT, la línea base se actualiza al nuevo valor de probabilidad. El texto de la notificación incluye "línea base actualizada a XX%."
--dry-runobtiene y evalúa pero no escribe ningún estado.--output openclawestá reservado para ejecuciones en segundo plano de la plataforma. EmiteHEARTBEAT_OKen verificaciones silenciosas, texto HIT listo para el usuario en alertas en tiempo real y texto de resumen cuando un resumen programado vence y el canal de entrega principal esopenclaw.
Administrar la programación
python3 scripts/signalradar.py schedule # Mostrar estado actual
python3 scripts/signalradar.py schedule 10 # Controlador automático (crontab primero)
python3 scripts/signalradar.py schedule 10 --driver openclaw # Forzar cron de openclaw
python3 scripts/signalradar.py schedule disable # Detener monitoreo automático
Recibir alertas
La configuración del webhook permite que las alertas se entreguen a cualquier servicio que acepte HTTP POST:
# Telegram - usar API de Telegram Bot
python3 scripts/signalradar.py config delivery webhook https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>
# Slack
python3 scripts/signalradar.py config delivery webhook https://hooks.slack.com/services/TXXXXX/BXXXXX/XXXXXXXXXX
# Discord
python3 scripts/signalradar.py config delivery webhook https://discord.com/api/webhooks/<ID>/<TOKEN>
Para guardar alertas localmente:
python3 scripts/signalradar.py config delivery channel file
python3 scripts/signalradar.py config delivery file.target ~/signalradar-alerts.jsonl
Verificar estado de entrega
python3 scripts/signalradar.py doctor --output json
Obtener resumen semanal
python3 scripts/signalradar.py digest
Genera un resumen de todos los cambios de probabilidad en los últimos 7 días, agrupados por evento, con métricas: opening, high, low, close, count of HITs. La salida es en inglés o chino según profile.language.
Desarrollo
Estilo de código
- Python 3.11+
- Sin dependencias externas (núcleo de solo stdlib)
- Sin herramientas de compilación — ejecución directa con
python3 - Pruebas con
pytest - Sin scripts de contenedorización — el código se ejecuta directamente
Pruebas
pip install pytest pytest-mock # una vez
pytest tests/ -v
Linting
pip install ruff
ruff check .
Configuración del proyecto
Se prefiere el lanzador de Python estándar — no se necesita Docker, ni Makefile avanzado:
python3 scripts/signalradar.py doctor --output json
Variables de entorno
SIGNALRADAR_DATA_DIR: directorio de datos de tiempo de ejecución anulado (predeterminado:~/.signalradar/)- Si no se proporcionan argumentos CLI, el script lee desde la variable de entorno o desde el valor predeterminado.
- Ninguna otra variable de entorno está obligatoriamente involucrada.
Estructura del proyecto
signalradar/
├── scripts/
│ ├── signalradar.py # Punto de entrada principal
│ └── cli.py # CLI de comando (opcional)
├── signalradar_lib/
│ ├── __init__.py
│ ├── core.py # Lógica principal: consultar Polymarket, almacenar línea base
│ ├── delivery.py # Lógica de entrega (webhook, archivo, openclaw)
│ ├── schedule.py # Programación crontab y de plataforma
│ └── config.py # Gestión de configuración (JSON local)
├── tests/
├── SKILL.md
├── README.md
├── LICENSE
└── pyproject.toml
El directorio signalradar_lib/ contiene la mayor parte de la lógica de la aplicación. scripts/ proporciona un punto de entrada simple de archivo único para la facilidad de uso del agente.