Saltar a contenido

AGENTE.md — Manual operativo para agentes IA en SignalDashPro#

Este documento define cómo debe trabajar un agente IA en este repositorio para mantener continuidad técnica, disciplina operativa y trazabilidad de cambios.

Addendum vNext (2026-04-09):

  • Priorizar documentación canónica actual:
  • docs/matvard/IMPLEMENTATION_PLAN_VNEXT_SAM.md
  • docs/matvard/MATVARD_RUNTIME_CONTRACT.md
  • docs/matvard/PLAYBOOK_SOLUSDC_REAL.md
  • docs/HANDOFF.md
  • docs/TODO.md
  • Tratar bloques históricos extensos de este archivo como referencia de contexto, no como fuente de estado vigente.

Addendum operativo (2026-04-10):

  • Estado runtime verificado en CT110:
  • estrategia operativa MATVARD en foco: autopilot:matvard_advanced_shadow
  • runtime_symbol de playbook SOL: SOLUSDT
  • smoke autenticado MATVARD integrado en deploy release (fase 5c)
  • Si se cambia lógica de estrategia, playbook o UX operativa, el agente debe actualizar en la misma sesión:
  • docs/CHANGELOG.md (Unreleased)
  • docs/HANDOFF.md (estado vigente)
  • docs/TODO.md (checklist + siguiente validación)
  • este archivo docs/AGENTE.md cuando cambie el protocolo de trabajo del agente
  • Frontend: mantener consistencia visual en páginas operativas (dashboard, control-tower, matvard) usando patrones globales (hero/chips/nav) ya definidos en frontend/src/app/globals.css.

0) Estado actual de sesión (2026-04-04)#

Estado operativo confirmado en CT110:

  • Release activa: 20260404T131854Z-4d4b45eb.
  • Frontend y backend activos en sdp.perlatec.net / api.sdp.perlatec.net.
  • Fixes recientes de Analitica desplegados en producción.

Estado técnico reciente:

  • En Analitica (/analytics), se corrigió el comportamiento del botón "Buscar simbolo activo" que generaba confusión UX (saltaba de símbolo sin feedback claro si solo encontraba decisions en vez de trades).
  • Se dividió en dos acciones explícitas:
  • Actividad en Símbolo Actual: ajusta filtros (days, all status) explícitamente para ver la actividad del símbolo seleccionado.
  • Ir al Símbolo Más Activo: busca el símbolo con más actividad real e informa explícitamente a qué símbolo cambió.
  • Se añadió modo explícito para overlays (lookback vs rango visible) para evitar falsos vacíos.

Archivos de código clave relacionados:

  • frontend/src/app/analytics/page.tsx
  • frontend/src/components/BackendCandlesChart.tsx
  • frontend/src/lib/api.ts
  • backend/routers/analytics.py

Commits relevantes:

  • b553c6d0 — overlay activity symbol resolution.
  • 0078245f — reset de rango visible al cambiar símbolo con assist.
  • 4d4b45eb — modo lookback/rango visible y forzado de lookback en Buscar simbolo activo.

Referencias documentales a revisar primero en próximas sesiones:

  1. docs/HANDOFF.md (handoff operativo, aunque contiene bloques históricos legacy).
  2. docs/CHANGELOG.md (trazabilidad de cambios recientes en Analítica).
  3. docs/TODO.md (histórico de evolución de overlays y replay en Analítica).
  4. docs/architecture/modules/frontend.md (módulo Analítica en frontend).
  5. docs/matvard/README.md y docs/matvard/IMPLEMENTATION_PLAN_VNEXT_SAM.md (estado MATVARD canónico vNext).

Checklist de continuidad para el siguiente agente IA:

  1. Validar UX en navegador con hard refresh (Cmd+Shift+R).
  2. Probar nuevas acciones: Actividad en Símbolo Actual e Ir al Símbolo Más Activo para confirmar la mejora UX en resolución de overlays.

1) Propósito del proyecto (north star)#

SignalDashPro es una plataforma Binance-first para trading y analítica, con backend FastAPI + frontend Next.js, orientada a operación autónoma auditable.

Objetivo operativo actual (MVP):

  • Operar en Binance Spot Demo.
  • Prioridad de activo: PAXGUSDT (ORO tokenizado).
  • Estrategia activa: paxg_mean_reversion en M15.
  • Estrategia alternativa disponible (experimental): paxg_matvard_hybrid.
  • Riesgo base: AUTOPILOT_ORDER_NOTIONAL_PCT=0.02.
  • Status operativo vigente (2026-03-17): OPERATIVO COMPLETO
  • ✅ Full trading cycle enabled: AUTOPILOT_ALLOW_SELL=true, TRADE_MANAGER_ENABLED=true
  • ✅ Parámetros optimizados: BB_PERIOD=25, RSI_OVERSOLD=30 (+1.53% y +3.51% esperado)
  • ✅ Filtros de riesgo activos: MAX_VOLATILITY_PCT=0.159%, MIN_VOL_RATIO=4.54x (+22.8pp WR, +3.70pp PnL validado)
  • ✅ Validación backtest completada: 90 días, -61% trades pero +58.3% win-rate (+1.67% PnL en lugar de -2.03%)

2) Orden de verdad (source of truth)#

Cuando haya contradicciones entre documentos, usar este orden:

  1. Runtime real (endpoints /status, /jobs/status, /settings/autopilot, /ops/p0/readiness, logs y timers en CT110).
  2. HANDOFF.md (estado operativo y runbooks).
  3. README.md (estado resumido y guía principal).
  4. TODO.md (backlog vivo; puede mezclar histórico).
  5. CHANGELOG.md (histórico de cambios relevantes).

Regla: si runtime != docs, runtime manda y se debe actualizar documentación.

3) Arquitectura y entorno operativo#

Stack#

  • Backend: FastAPI + SQLAlchemy + PostgreSQL.
  • Frontend: Next.js.
  • Docs: MkDocs Material.
  • Infra: Proxmox (CT110 app, CT107 DB, CT103 proxy).

Servicios clave en CT110#

  • deploy-backend-1 (API :8096)
  • deploy-frontend-1 (UI :3000)
  • deploy-docs-1 (Docs :8001)
  • current-db-1 (Postgres :5433)

URLs públicas#

  • Frontend: https://sdp.perlatec.net
  • API: https://api.sdp.perlatec.net
  • Docs: https://sdp.perlatec.net/docs/
  • Changelog docs: https://sdp.perlatec.net/docs/CHANGELOG/

4) Flujo estándar de trabajo del agente#

Para cualquier tarea de desarrollo/ops:

  1. Diagnóstico breve
  2. Identificar alcance real (código, docs, runtime, deploy).

  3. Buscar contexto en README.md, HANDOFF.md, TODO.md, CHANGELOG.md.

  4. Implementación mínima y segura

  5. Cambiar solo lo necesario.

  6. Evitar “overengineering”.

  7. Validación técnica

  8. Sintaxis (bash -n para scripts shell).

  9. Verificación funcional mínima (endpoint/log/timer/comando objetivo).

  10. Trazabilidad

  11. Actualizar docs relevantes.

  12. Añadir entrada a CHANGELOG.md en Unreleased cuando aplique.

  13. Publicación

  14. Commit claro por intención.
  15. Push a master.
  16. Si es cambio operativo, sincronizar/activar en CT110 y evidenciar resultado.

5) Política documental obligatoria#

Si cambias comportamiento real, el agente debe actualizar lo siguiente:

  • README.md: estado operativo resumido y comandos principales.
  • HANDOFF.md: runbook operativo y hallazgos relevantes.
  • TODO.md: backlog y acciones inmediatas.
  • CHANGELOG.md: cambios relevantes (Added/Changed/Fixed/Security).

Regla: no abrir documentos nuevos innecesarios para microcambios; priorizar consolidación.

6) Política de changelog y releases#

Changelog#

  • Archivo canónico: CHANGELOG.md.
  • Formato: Added, Changed, Fixed, Security.
  • Cada PR/cambio significativo debe dejar rastro en Unreleased.

Docs UI#

  • Página navegable: CHANGELOG.md (referencia al changelog canónico).
  • Menú de docs configurado en mkdocs.yml.

Release / deploy#

  • Script base: scripts/ct110_deploy_release.sh.
  • Retry wrapper: scripts/ct110_deploy_retry.sh.
  • Shortcut docs-only: scripts/ct110_deploy_docs.sh.
  • Verificación de changelog en deploy:
  • Flag: --verify-docs-changelog=true|false.
  • Ruta validada: /docs/CHANGELOG/ (fallback /docs/changelog/).

7) Monitoreo y timers (mínimos esperados)#

Timers críticos esperados activos:

  • signaldashpro-binance-demo-auth-smoke.timer
  • signaldashpro-web-auth-smoke.timer
  • signaldashpro-openai-runtime-smoke.timer
  • signaldashpro-alerts.timer
  • signaldashpro-m15-autopromote.timer
  • signaldashpro-docs-changelog-check.timer (semanal)

Logs operativos principales:

  • storage/logs/ops/binance-demo-auth-smoke-latest.log
  • storage/logs/ops/openai-runtime-smoke-latest.log
  • storage/logs/ops/web-auth-smoke-*.log
  • storage/logs/ops/docs-changelog-check-latest.log

Endpoint operativo adicional (timeframe recommendations):

  • GET /ops/reports/paxg-timeframe/latest

8) Implementación reciente: Filtros de volatilidad/volumen (2026-03-17)#

Contexto:

  • Backtest de 90 días mostró win-rate de 35.5% con -2.03% PnL (negativo).
  • Análisis root-cause: trades perdedores ocurrían en volatilidad HIGH (+70%) y volumen LOW (-47%).

Solución implementada:

  • Función _historical_volatility() agregada a backend/services/strategies/paxg_mean_reversion.py.
  • Filtros aplicados en lógica de generate_signal(): rechaza BUY/SELL si:
  • historical_volatility_pct > 0.159% (too turbulent), O
  • volume_ratio < 4.54x (insufficient liquidity).

Validación (90d backtest):

  • Sin filtros: 31 trades, 35.5% WR, -2.03% PnL
  • Con filtros: 12 trades, 58.3% WR, +1.67% PnL
  • Mejora: +22.8pp win-rate, +3.70pp PnL, +188% profit factor

Runtime deployment:

  • AUTOPILOT_PAXG_MAX_VOLATILITY_PCT = 0.159 (manual override)
  • AUTOPILOT_PAXG_MIN_VOL_RATIO = 4.54 (manual override)
  • Ambos parametrizables vía /settings/autopilot endpoint.

Comportamiento en señales:

  • Diagnostics incluyen volatility_pct y volume_ratio en cada candle.
  • Si signal es rechazada por filtro, detalles muestran volatility_ok: false o volume_ratio_ok: false.
  • Sirve para debugging de por qué se skipped un entry que parecía válido.

Archivos modificados:

  • backend/services/strategies/paxg_mean_reversion.py (+volatility calc, +filters logic)
  • backend/routers/settings.py (+new AUTOPILOT keys, +defaults)
  • HANDOFF.md (documented status)
  • TODO.md (marked complete with metrics)
  • CHANGELOG.md (entry to be added)

Próximos pasos opcionales:

  • Monitor live performance 24-48h antes de ajustes adicionales.
  • Si win-rate observada se acerca a 58.3%, considerar publicar como "optimized_variant v1".
  • Sino, revertir uno o ambos filtros vía /settings/autopilot y retest.

8) Checklist de auditoría rápida (hoy)#

BACKTEST ANUAL EVALUADO Y APLICADO (2026-04-04)#

Análisis de 1 año (365 días M15, $1000): filtro 4.54x vol_ratio original estaba en P99+ (inviable). Calibración realista aplicada en runtime (0.15% vol, 1.5x vol_ratio). Resultado histórico esperado: 257 trades, 26.8% WR, +$124.62 (+12.46%), PF=1.23, DD=7.43%. Reporte base: /storage/reports/paxg_1y_with_filters_final_2026_03_17.json Status: Runtime defaults actualizados a calibración (0.15%, 1.5x) para optimizar volumen de entrada.

Comandos recomendados:

# Salud base
curl -sS http://127.0.0.1:8096/status

# Login + jobs
TOKEN=$(curl -sS -X POST http://127.0.0.1:8096/auth/login -H 'Content-Type: application/json' -d '{"email":"admin@sdp.perlatec.net","password":"***"}' | python3 -c 'import sys,json;print(json.load(sys.stdin).get("access_token",""))')
curl -sS http://127.0.0.1:8096/jobs/status -H "Authorization: Bearer $TOKEN"

# Estrategia / readiness
curl -sS http://127.0.0.1:8096/settings/autopilot -H "Authorization: Bearer $TOKEN"
curl -sS http://127.0.0.1:8096/settings/trade-manager -H "Authorization: Bearer $TOKEN"
curl -sS http://127.0.0.1:8096/ops/p0/readiness -H "Authorization: Bearer $TOKEN"
curl -sS 'http://127.0.0.1:8096/ops/strategy/performance?days=7' -H "Authorization: Bearer $TOKEN"

# Cola reciente (verificar side/source/error)
curl -sS 'http://127.0.0.1:8096/signals/queue?limit=20' -H "Authorization: Bearer $TOKEN" \
   | jq -r '.[] | [.created_at,.symbol,.side,.source,.status,(.last_error//"")] | @tsv'

# Timers
systemctl list-timers --all --no-pager | grep signaldashpro

9) Guardrails de seguridad y cumplimiento#

  • Nunca versionar secretos (BINANCE_API_KEY, BINANCE_API_SECRET, passwords, tokens).
  • env/* con credenciales es gitignored; usar rutas compartidas en servidor.
  • No exponer credenciales en docs, commits o logs.
  • Evitar comandos destructivos sin necesidad (rm -rf, drop de tablas, etc.).
  • Confirmar siempre impacto en producción antes de reiniciar servicios.

10) Incidentes frecuentes y respuesta#

  1. Smoke Binance falla con Permission denied

  2. Revisar chmod +x scripts/check_binance_demo_auth.sh y wrapper ops.

  3. Deploy helper falla al validar changelog docs

  4. Asegurar ruta correcta: /docs/CHANGELOG/ (o fallback /docs/changelog/).

  5. Si falla endpoint público desde CT110, usar check interno por defecto (public opcional).

  6. current no es repositorio git

  7. Es release inmutable por symlink; no asumir git pull en current.

  8. Usar flujo de tarball/deploy helper o copia controlada.

  9. Inconsistencia docs vs runtime

  10. Auditoría rápida de endpoints + timers.
  11. Actualizar README/HANDOFF/TODO/CHANGELOG en la misma sesión.

11) Definition of Done (DoD) para un agente#

Una tarea se considera completada solo si:

  • [ ] Cambio implementado y validado técnicamente.
  • [ ] Evidencia de funcionamiento (salida de comando/log/endpoint).
  • [ ] Documentación relevante actualizada.
  • [ ] Changelog actualizado si cambia comportamiento.
  • [ ] Commit/push realizados (si aplica).
  • [ ] Si afecta operación, sincronizado y validado en CT110.

12) Formato recomendado de commits#

Usar prefijos semánticos:

  • feat(...) nueva capacidad
  • fix(...) corrección
  • ops(...) operación/deploy/timers
  • docs(...) documentación
  • refactor(...) estructura sin cambio funcional

Ejemplos:

  • ops(timers): add weekly docs changelog check with systemd timer
  • fix(deploy): verify docs changelog on /docs/changelog path
  • docs(audit): unify runtime state as of 2026-03-15

13) Cadencia sugerida para agentes IA#

  • Cada sesión debe cerrar con: 1) resumen técnico, 2) riesgos pendientes, 3) próximos pasos concretos.
  • Si hay cambios operativos, incluir ruta de log y comando de verificación.
  • Mantener mensajes claros, ejecutables y orientados a continuidad entre sesiones.

14) Nota final#

Este AGENTE.md es el contrato operativo para mantener continuidad de desarrollo y operación en SignalDashPro.

Si el estado de runtime cambia (estrategia, timers, endpoints, deploy), este documento debe actualizarse junto con README.md, HANDOFF.md, TODO.md y CHANGELOG.md.