wehub/diegosouzapw--omniroute
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
diegosouzapw--omniroute/docs/i18n/es/CLAUDE.md
T
wehub-resource-sync d8dcd5f6d1 chore: import upstream snapshot with attribution
2026-07-13 13:39:12 +08:00

28 KiB
Raw Permalink Blame History

CLAUDE.md (Español)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

Este archivo proporciona orientación a Claude Code (claude.ai/code) al trabajar con código en este repositorio.

Inicio Rápido

npm install                    # Instalar dependencias (genera automáticamente .env a partir de .env.example)
npm run dev                    # Servidor de desarrollo en http://localhost:20128
npm run build                  # Construcción de producción (Next.js 16 independiente)
npm run lint                   # ESLint (se esperan 0 errores; las advertencias son preexistentes)
npm run typecheck:core         # Verificación de TypeScript (debería estar limpio)
npm run typecheck:noimplicit:core  # Verificación estricta (sin any implícito)
npm run test:coverage          # Pruebas unitarias + puerta de cobertura (75/75/75/70 — declaraciones/líneas/funciones/ramas)
npm run check                  # lint + test combinados
npm run check:cycles           # Detectar dependencias circulares

Ejecución de Pruebas

# Archivo de prueba único (ejecutor de pruebas nativo de Node.js — la mayoría de las pruebas)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (servidor MCP, autoCombo, caché)
npm run test:vitest

# Todas las suites
npm run test:all

Para la matriz completa de pruebas, consulta CONTRIBUTING.md → "Ejecución de Pruebas". Para una arquitectura profunda, consulta AGENTS.md.

Proyecto a Simple Vista

OmniRoute — proxy/router de IA unificado. Un punto final, más de 160 proveedores de LLM, retroceso automático.

Capa Ubicación Propósito
Rutas API src/app/api/v1/ Enrutador de Aplicaciones Next.js — puntos de entrada
Manejadores open-sse/handlers/ Procesamiento de solicitudes (chat, embeddings, etc)
Ejecutores open-sse/executors/ Despacho HTTP específico del proveedor
Traductores open-sse/translator/ Conversión de formato (OpenAI↔Claude↔Gemini)
Transformador open-sse/transformer/ API de respuestas ↔ Completaciones de Chat
Servicios open-sse/services/ Enrutamiento combinado, límites de tasa, caché, etc
Base de Datos src/lib/db/ Módulos de dominio SQLite (más de 45 archivos, 55 migraciones)
Dominio/Política src/domain/ Motor de políticas, reglas de costo, lógica de retroceso
Servidor MCP open-sse/mcp-server/ 37 herramientas (30 base + 3 memoria + 4 habilidades), 3 transportes, ~13 ámbitos
Servidor A2A src/lib/a2a/ Protocolo de agente JSON-RPC 2.0
Habilidades src/lib/skills/ Marco de habilidades extensible
Memoria src/lib/memory/ Memoria conversacional persistente

Monorepo: src/ (aplicación Next.js 16), open-sse/ (espacio de trabajo del motor de streaming), electron/ (aplicación de escritorio), tests/, bin/ (punto de entrada CLI).

Pipeline de Solicitudes

Cliente → /v1/chat/completions (ruta de Next.js)
  → CORS → validación de Zod → ¿autenticación? → verificación de políticas → guardia de inyección de prompts
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → verificación de caché → límite de tasa → ¿enrutamiento combinado?
      → resolveComboTargets() → handleSingleModel() por objetivo
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → reintentar con retroceso
    → traducción de respuesta → flujo SSE o JSON
    → Si Responses API: responsesTransformer.ts TransformStream

Las rutas de la API siguen un patrón consistente: Ruta → preflight CORS → validación del cuerpo de Zod → Autenticación opcional (extractApiKey/isValidApiKey) → aplicación de políticas de clave API → Delegación de manejadores (open-sse). No hay middleware global de Next.js: la interceptación es específica de la ruta.

Enrutamiento combinado (open-sse/services/combo.ts): 14 estrategias (prioridad, ponderado, llenar primero, round-robin, P2C, aleatorio, menos utilizado, optimizado por costo, consciente del reinicio, aleatorio estricto, automático, lkgp, optimizado por contexto, retransmisión de contexto). Cada objetivo llama a handleSingleModel() que envuelve handleChatCore() con manejo de errores por objetivo y verificaciones de cortacircuito. Consulte docs/routing/AUTO-COMBO.md para la puntuación de Auto-Combo de 9 factores y docs/architecture/RESILIENCE_GUIDE.md para las 3 capas de resiliencia.

Estado de Ejecución de Resiliencia

OmniRoute tiene tres mecanismos de falla temporal relacionados pero distintos. Mantenga su alcance separado al depurar el comportamiento de enrutamiento. Consulte el diagrama de resiliencia de 3 capas (fuente: docs/diagrams/resilience-3layers.mmd) para un mapa de un vistazo.

Cortacircuito del Proveedor

Alcance: todo el proveedor, por ejemplo, glm, openai, anthropic.

Propósito: detener el envío de tráfico a un proveedor que está fallando repetidamente a nivel upstream/servicio, para que un proveedor no saludable no ralentice cada solicitud.

Implementación:

  • Clase principal: src/shared/utils/circuitBreaker.ts
  • Cableado de puerta de chat/ejecución: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
  • API de estado en tiempo de ejecución: src/app/api/monitoring/health/route.ts
  • Envolturas compartidas: open-sse/services/accountFallback.ts
  • Tabla de estado persistido: domain_circuit_breakers

Estados:

  • CLOSED: se permite tráfico normal.
  • OPEN: el proveedor está temporalmente bloqueado; los llamadores reciben una respuesta de circuito-abierto del proveedor o el enrutamiento combinado salta a otro objetivo.
  • HALF_OPEN: ha transcurrido el tiempo de espera de reinicio; se permite una solicitud de sondeo. El éxito cierra el cortacircuito, el fracaso lo abre nuevamente.

Valores predeterminados (open-sse/config/constants.ts):

  • Proveedores de OAuth: umbral 3, tiempo de espera de reinicio 60s.
  • Proveedores de clave API: umbral 5, tiempo de espera de reinicio 30s.
  • Proveedores locales: umbral 2, tiempo de espera de reinicio 15s.

Solo los estados de falla a nivel de proveedor deben activar el cortacircuito del proveedor:

(408, 500, 502, 503, 504);

No active el cortacircuito de todo el proveedor por errores normales de cuenta/clave/modelo como la mayoría de los casos 401, 403 o 429. Esos generalmente pertenecen a la espera de conexión o bloqueo de modelo. Un proveedor de clave API genérico 403 debería ser recuperable a menos que se clasifique como un error terminal de proveedor/cuenta.

El cortacircuito utiliza recuperación perezosa, no un temporizador en segundo plano. Cuando OPEN expira, lecturas como getStatus(), canExecute(), y getRetryAfterMs() actualizan el estado a HALF_OPEN, para que los paneles de control y los constructores de candidatos combinados no sigan excluyendo un proveedor expirado para siempre.

Enfriamiento de Conexión

Alcance: una conexión/cuenta/clave de proveedor.

Propósito: omitir temporalmente una clave/cuenta mala mientras permite que otras conexiones para el mismo proveedor continúen atendiendo solicitudes.

Implementación:

  • Ruta de escritura/actualización: src/sse/services/auth.ts::markAccountUnavailable()
  • Selección/filtrado de cuentas: src/sse/services/auth.ts::getProviderCredentials...
  • Cálculo de enfriamiento: open-sse/services/accountFallback.ts::checkFallbackError()
  • Configuraciones: src/lib/resilience/settings.ts

Campos importantes en conexiones de proveedor:

rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;

Durante la selección de cuentas, se omite una conexión mientras:

new Date(rateLimitedUntil).getTime() > Date.now();

Los enfriamientos también son perezosos: cuando rateLimitedUntil está en el pasado, la conexión se vuelve elegible nuevamente. Al usar con éxito, clearAccountError() borra testStatus, rateLimitedUntil, campos de error y backoffLevel.

Comportamiento predeterminado de enfriamiento de conexión:

  • Enfriamiento base de OAuth: 5s.
  • Enfriamiento base de clave API: 3s.
  • La clave API 429 debería preferir pistas de reintento upstream (Retry-After, encabezados de reinicio, o texto de reinicio parseable) cuando estén disponibles.
  • Fallos recuperables repetidos utilizan retroceso exponencial:
baseCooldownMs * 2 ** failureIndex;

El guardia anti-thundering-herd previene fallos concurrentes en la misma conexión de extender repetidamente el enfriamiento o incrementar doblemente backoffLevel.

Los estados terminales no son enfriamientos. banned, expired, y credits_exhausted están destinados a permanecer no disponibles hasta que cambien las credenciales/configuraciones o un operador los reinicie. No sobrescriba estados terminales con estados de enfriamiento transitorios.

Bloqueo de Modelo

Alcance: proveedor + conexión + modelo.

Propósito: evitar deshabilitar toda una conexión cuando solo un modelo no está disponible o tiene un límite de cuota para esa conexión.

Ejemplos:

  • Proveedores de cuota por modelo que devuelven 429.
  • Proveedores locales que devuelven 404 para un modelo faltante.
  • Fallos de permisos de modo/modelo específicos del proveedor, como modos Grok seleccionados.

El bloqueo de modelo vive en open-sse/services/accountFallback.ts y permite que la misma conexión continúe atendiendo otros modelos.

Orientación para Depuración

  • Si todas las claves para un proveedor son omitidas, inspeccione tanto el estado del cortacircuito del proveedor como cada rateLimitedUntil/testStatus de conexión.
  • Si un proveedor parece estar excluido permanentemente después de la ventana de reinicio, verifique si el código está leyendo el state en bruto en lugar de usar getStatus()/canExecute().
  • Si una clave de proveedor falla pero otras deberían funcionar, prefiera el enfriamiento de conexión sobre el cortacircuito del proveedor.
  • Si solo un modelo falla, prefiera el bloqueo de modelo sobre el enfriamiento de conexión.
  • Si un estado debería recuperarse por sí mismo, debería tener una marca de tiempo futura/tiempo de espera de reinicio y una ruta de lectura que actualice el estado expirado. Los estados permanentes requieren cambios manuales de credenciales o configuración.

Convenciones Clave

Estilo de Código

  • 2 espacios, punto y coma, comillas dobles, ancho de 100 caracteres, comas finales en es5 (aplicado por lint-staged a través de Prettier)
  • Importaciones: externo → interno (@/, @omniroute/open-sse) → relativo
  • Nomenclatura: archivos=camelCase/kebab, componentes=PascalCase, constantes=UPPER_SNAKE
  • ESLint: no-eval, no-implied-eval, no-new-func = error en todas partes; no-explicit-any = advertencia en open-sse/ y tests/
  • TypeScript: strict: false, objetivo ES2022, módulo esnext, resolución bundler. Preferir tipos explícitos.

Base de Datos

  • Siempre pasar por los módulos de dominio en src/lib/db/ — nunca escribir SQL en bruto en rutas o manejadores
  • Nunca agregar lógica a src/lib/localDb.ts (capa de re-exportación solamente)
  • Nunca importar en bloque desde localDb.ts — importar módulos específicos de db/ en su lugar
  • Singleton de DB: getDbInstance() desde src/lib/db/core.ts (registro WAL)
  • Migraciones: src/lib/db/migrations/ — archivos SQL versionados, idempotentes, ejecutados en transacciones

Manejo de Errores

  • try/catch con tipos de error específicos, registrar con contexto de pino
  • Nunca tragar errores en flujos SSE — usar señales de aborto para limpieza
  • Devolver códigos de estado HTTP apropiados (4xx/5xx)

Seguridad

  • Nunca usar eval(), new Function(), o eval implícito
  • Validar todas las entradas con esquemas Zod
  • Cifrar credenciales en reposo (AES-256-GCM)
  • Lista de negación de encabezados upstream: src/shared/constants/upstreamHeaders.ts — mantener saneados, esquemas Zod y pruebas unitarias alineadas al editar
  • Credenciales públicas upstream (client_id/secret de OAuth estilo Gemini/Antigravity/Windsurf + claves web de Firebase extraídas de CLIs públicas): DEBEN ser incrustadas a través de resolvePublicCred() desde open-sse/utils/publicCreds.ts — nunca como literales de cadena. Ver docs/security/PUBLIC_CREDS.md para el patrón obligatorio.
  • Respuestas de error (HTTP / SSE / ejecutor / manejador MCP): DEBEN pasar por buildErrorBody() o sanitizeErrorMessage() desde open-sse/utils/error.ts — nunca poner err.stack o err.message en bruto en el cuerpo de la respuesta. Ver docs/security/ERROR_SANITIZATION.md.
  • Comandos de shell construidos a partir de variables: al llamar a exec()/spawn() con un script que necesita valores en tiempo de ejecución, pásalos a través de la opción env (escapados automáticamente) — nunca interpolar cadenas de rutas no confiables/externas en el cuerpo del script. Referencia: src/mitm/cert/install.ts::updateNssDatabases.
  • Bibliotecas seguras por defecto (tldrsec/awesome-secure-defaults): preferir Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink sobre implementaciones personalizadas siempre que se agreguen nuevas superficies sensibles a la seguridad.

Escenarios Comunes de Modificación

Agregar un Nuevo Proveedor

  1. Registrar en src/shared/constants/providers.ts (validado por Zod al cargar)
  2. Agregar ejecutor en open-sse/executors/ si se necesita lógica personalizada (extender BaseExecutor)
  3. Agregar traductor en open-sse/translator/ si no es formato OpenAI
  4. Agregar configuración de OAuth en src/lib/oauth/constants/oauth.ts si es basado en OAuth — si el CLI upstream envía un client_id/secret público, incrustar a través de resolvePublicCred() (ver docs/security/PUBLIC_CREDS.md), nunca como un literal
  5. Registrar modelos en open-sse/config/providerRegistry.ts
  6. Escribir pruebas en tests/unit/ (incluir la afirmación de forma publicCreds si agregaste un nuevo predeterminado incrustado)

Agregar una Nueva Ruta API

  1. Crear directorio bajo src/app/api/v1/your-route/
  2. Crear route.ts con manejadores GET/POST
  3. Seguir el patrón: CORS → validación del cuerpo Zod → autenticación opcional → delegación de manejador
  4. El manejador va en open-sse/handlers/ (importar desde allí, no en línea)
  5. Las respuestas de error utilizan buildErrorBody() / errorResponse() desde open-sse/utils/error.ts (auto-saneadas — nunca poner err.stack o err.message en bruto en el cuerpo). Ver docs/security/ERROR_SANITIZATION.md.
  6. Agregar pruebas — incluyendo al menos una afirmación de que las respuestas de error no filtran trazas de pila (!body.error.message.includes("at /"))

Agregar un Nuevo Módulo DB

  1. Crear src/lib/db/yourModule.ts — importar getDbInstance desde ./core.ts
  2. Exportar funciones CRUD para tu(s) tabla(s) de dominio
  3. Agregar migración en src/lib/db/migrations/ si se necesitan nuevas tablas
  4. Re-exportar desde src/lib/localDb.ts (agregar a la lista de re-exportación solamente)
  5. Escribir pruebas

Agregar una Nueva Herramienta MCP

  1. Agregar definición de herramienta en open-sse/mcp-server/tools/ con esquema de entrada Zod + manejador asíncrono
  2. Registrar en el conjunto de herramientas (conectado por createMcpServer())
  3. Asignar a los ámbitos apropiados
  4. Escribir pruebas (invocación de herramienta registrada en la tabla mcp_audit)

Agregar una Nueva Habilidad A2A

  1. Crear habilidad en src/lib/a2a/skills/ (ya existen 5: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
  2. La habilidad recibe contexto de tarea (mensajes, metadatos) → devuelve resultado estructurado
  3. Registrar en A2A_SKILL_HANDLERS en src/lib/a2a/taskExecution.ts
  4. Exponer en src/app/.well-known/agent.json/route.ts (Tarjeta de Agente)
  5. Escribir pruebas en tests/unit/
  6. Documentar en la tabla de habilidades en docs/frameworks/A2A-SERVER.md

Agregar un Nuevo Agente en la Nube

  1. Crear clase de agente en src/lib/cloudAgent/agents/ extendiendo CloudAgentBase (ya existen 3: codex-cloud, devin, jules)
  2. Implementar createTask, getStatus, approvePlan, sendMessage, listSources
  3. Registrar en src/lib/cloudAgent/registry.ts
  4. Agregar manejo de OAuth/credenciales si es necesario (src/lib/oauth/providers/)
  5. Pruebas + documentar en docs/frameworks/CLOUD_AGENT.md

Agregar un Nuevo Guardrail / Eval / Skill / Evento Webhook

  • Guardrail: src/lib/guardrails/ → docs: docs/security/GUARDRAILS.md
  • Suite de Eval: src/lib/evals/ → docs: docs/frameworks/EVALS.md
  • Skill (sandbox): src/lib/skills/ → docs: docs/frameworks/SKILLS.md
  • Evento Webhook: src/lib/webhookDispatcher.ts → docs: docs/frameworks/WEBHOOKS.md

Documentación de Referencia

Para cualquier cambio no trivial, lee primero el análisis correspondiente:

Área Doc
Navegación del repositorio docs/architecture/REPOSITORY_MAP.md
Arquitectura docs/architecture/ARCHITECTURE.md
Referencia de ingeniería docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (puntuación de 9 factores, 14 estrategias) docs/routing/AUTO-COMBO.md
Resiliencia (3 mecanismos) docs/architecture/RESILIENCE_GUIDE.md
Repetición de razonamiento docs/routing/REASONING_REPLAY.md
Marco de habilidades docs/frameworks/SKILLS.md
Sistema de memoria (FTS5 + Qdrant) docs/frameworks/MEMORY.md
Agentes en la nube docs/frameworks/CLOUD_AGENT.md
Líneas de protección (PII / inyección / visión) docs/security/GUARDRAILS.md
Credenciales públicas upstream (Gemini/etc.) docs/security/PUBLIC_CREDS.md
Saneamiento de mensajes de error docs/security/ERROR_SANITIZATION.md
Evaluaciones docs/frameworks/EVALS.md
Cumplimiento / auditoría docs/security/COMPLIANCE.md
Webhooks docs/frameworks/WEBHOOKS.md
Pipeline de autorización docs/architecture/AUTHZ_GUIDE.md
Sigilo (TLS / huella digital) docs/security/STEALTH_GUIDE.md
Protocolos de agente (A2A / ACP / Nube) docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
Servidor MCP docs/frameworks/MCP-SERVER.md
Servidor A2A docs/frameworks/A2A-SERVER.md
Referencia de API + OpenAPI docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Catálogo de proveedores (generado automáticamente) docs/reference/PROVIDER_REFERENCE.md
Flujo de lanzamiento docs/ops/RELEASE_CHECKLIST.md

Pruebas

Qué Comando
Pruebas unitarias npm run test:unit
Archivo único node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo) npm run test:vitest
E2E (Playwright) npm run test:e2e
Protocolo E2E (MCP+A2A) npm run test:protocols:e2e
Ecosistema npm run test:ecosystem
Puerta de cobertura npm run test:coverage (75/75/75/70 — declaraciones/líneas/funciones/ramas)
Informe de cobertura npm run coverage:report

Regla de PR: Si cambias el código de producción en src/, open-sse/, electron/, o bin/, debes incluir o actualizar pruebas en el mismo PR.

Preferencia de capa de prueba: unidad primero → integración (multi-módulo o estado de DB) → e2e (solo UI/workflow). Codifica reproducciones de errores como pruebas automatizadas antes o junto con la solución.

Política de cobertura de Copilot: Cuando un PR cambia el código de producción y la cobertura está por debajo del 75% (declaraciones/líneas/funciones) o 70% (ramas), no solo informes — agrega o actualiza pruebas, vuelve a ejecutar la puerta de cobertura, luego pide confirmación. Incluye comandos ejecutados, archivos de prueba cambiados y el resultado final de la cobertura en el informe del PR.

Flujo de trabajo de Git

# Nunca comites directamente en main
git checkout -b feat/tu-característica
git commit -m "feat: describe tu cambio"
git push -u origin feat/tu-característica

Prefijos de rama: feat/, fix/, refactor/, docs/, test/, chore/

Formato de commit (Commits Convencionales): feat(db): agregar cortacircuito — ámbitos: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Ganchos de Husky:

  • pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
  • pre-push: npm run test:unit

Entorno

  • Tiempo de ejecución: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, Módulos ES
  • TypeScript: 5.9+, objetivo ES2022, módulo esnext, resolución bundler
  • Alias de ruta: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
  • Puerto predeterminado: 20128 (API + dashboard en el mismo puerto)
  • Directorio de datos: variable de entorno DATA_DIR, por defecto ~/.omniroute/
  • Variables de entorno clave: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
  • Configuración: cp .env.example .env luego genera JWT_SECRET (openssl rand -base64 48) y API_KEY_SECRET (openssl rand -hex 32)

Reglas estrictas

  1. Nunca comites secretos o credenciales
  2. Nunca agregues lógica a localDb.ts
  3. Nunca uses eval() / new Function() / eval implícito
  4. Nunca comites directamente en main
  5. Nunca escribas SQL en bruto en rutas — usa módulos de src/lib/db/
  6. Nunca tragues errores silenciosamente en flujos SSE
  7. Siempre valida entradas con esquemas Zod
  8. Siempre incluye pruebas al cambiar código de producción
  9. La cobertura debe mantenerse ≥75% (declaraciones, líneas, funciones) / ≥70% (ramas). Medido actualmente: ~82%.
  10. Nunca evadas ganchos de Husky (--no-verify, --no-gpg-sign) sin aprobación explícita del operador.
  11. Nunca incrustes client_id/secret de OAuth público o claves web de Firebase como literales de cadena — siempre pasa por resolvePublicCred() (open-sse/utils/publicCreds.ts). Ver docs/security/PUBLIC_CREDS.md.
  12. Nunca devuelvas err.stack / err.message en respuestas HTTP / SSE / ejecutores — siempre enruta a través de buildErrorBody() o sanitizeErrorMessage() (open-sse/utils/error.ts). Ver docs/security/ERROR_SANITIZATION.md.
  13. Nunca interpolas cadenas de rutas externas o valores de tiempo de ejecución en scripts de shell pasados a exec()/spawn() — pasa a través de la opción env en su lugar. Referencia: src/mitm/cert/install.ts::updateNssDatabases.
  14. Nunca desestimes una alerta de CodeQL / Escaneo de Secretos sin (a) primero verificar la documentación del patrón anterior para ver si el helper se aplica, y (b) registrar la justificación técnica en el comentario de desestimación. Precedente: js/stack-trace-exposure planteado en sitios de llamada que ya enrutan a través de sanitizeErrorMessage() es una limitación conocida de CodeQL (sanitizadores personalizados no reconocidos) — desestima como falso positivo haciendo referencia a docs/security/ERROR_SANITIZATION.md.
  15. Nunca expongas rutas que generan procesos secundarios (/api/mcp/, /api/cli-tools/runtime/) sin clasificación isLocalOnlyPath() en src/server/authz/routeGuard.ts. La aplicación de loopback ocurre incondicionalmente antes de cualquier verificación de autenticación — un JWT filtrado a través de un túnel no puede activar la generación de procesos. Ver docs/security/ROUTE_GUARD_TIERS.md.
  16. Nunca incluyas trailers Co-Authored-By que acrediten a un asistente de IA, LLM o cuenta automatizada (p. ej. nombres que contengan "Claude", "GPT", "Copilot", "Bot"; correos en anthropic.com / openai.com / direcciones noreply.github.com propiedad de bots). Tales trailers redirigen la atribución del commit a la cuenta del bot en GitHub, ocultando al autor real (diegosouzapw) en el historial del PR. Los colaboradores humanos — incluyendo autores de PRs upstream y reporteros de issues que se portan a OmniRoute — PUEDEN y DEBEN ser acreditados con trailers estándar Co-authored-by: Name <email>; los flujos de trabajo de port upstream (/port-upstream-features, /port-upstream-issues) dependen de esto.
Reference in New Issue View Git Blame Copy Permalink