GiaSip/giasip-skills

✦ Una habilidad GiaSip · parte del toolkit giasip · github.com/GiaSip

/dispatch — Despachador Multimodelo

Envía una tarea o instrucción a otro modelo de IA para su ejecución y recupera el resultado. Esta habilidad solo proporciona la capacidad de despacho — qué modelo elegir, si distribuir a varios modelos, lo decides tú (o el Claude actual) según la tarea en cuestión. Sin preferencia de modelo incorporada.

Directorio de Scripts

Importante: Todos los scripts residen en el subdirectorio scripts/ de esta carpeta de habilidad.

Configuración del agente — haz esto UNA VEZ antes de ejecutar cualquier comando a continuación: determina la ruta absoluta del directorio que contiene este SKILL.md y expórtala como BASE_DIR:

# Instalación global (la más común); usa la ruta de caché del plugin si está instalado como plugin
export BASE_DIR="$HOME/.claude/skills/giasip-dispatch"

Cada comando a continuación referencia los scripts como $BASE_DIR/scripts/<nombre-script>. BASE_DIR es una variable de shell que tú configuras en la sesión — no hay una variable de entorno CLAUDE_SKILL_DIR inyectada por el runtime, así que configura BASE_DIR primero o las rutas de los scripts no resolverán a nada.

Canales de Despacho

Canal	Modelos	Requisito Previo
API Agregador ★ ruta fácil — una clave	Extranjero: OpenRouter (DeepSeek/Qwen/GLM/Kimi/MiniMax + Claude/GPT/Gemini). China: SiliconFlow 硅基流动 (DeepSeek/Qwen/GLM/Kimi/MiniMax)	Un archivo de clave — openrouter.env o siliconflow.env en ~/.config/ai-keys/; configura DISPATCH_PROVIDER una vez
Llamada API directa (curl, por proveedor)	DeepSeek / Qwen / GLM / Doubao / MiniMax	Un .env separado por proveedor en ~/.config/ai-keys/ (avanzado)
Invocación CLI (agente)	Codex / Gemini / Kimi	Instalación local + inicio de sesión por CLI — necesario para capacidad de agente (escritura de código, visión nativa)
SubAgente Interno	Claude Haiku / Sonnet	Integrado en Claude Code, sin dependencia externa

Ruta fácil (recomendada para la mayoría de usuarios): obtén una clave de agregador y todos los alias que tu proveedor elegido soporte funcionarán — sin registro por proveedor. Extranjero → OpenRouter; China → SiliconFlow. Consulta el README "giasip-dispatch — Dependencias" para la configuración.

Cuando aún necesitas las rutas por proveedor / CLI: claves directas por proveedor (si ya las tienes, o para evitar la tarifa de ~5,5% de recarga de crédito de OpenRouter); canales CLI para trabajo agente que la API de chat no puede hacer — modo escritura de Codex (edita archivos), visión nativa PDF/imagen de Gemini. Los agregadores cubren todos los usos de análisis puro + multidifusión.

Para tareas de pensamiento/análisis puro (sin E/S de archivos, sin ejecución de comandos, sin cambios de código), prefiere la llamada directa API / Agregador — aproximadamente 10 veces más rápido que CLI. Usa CLI solo cuando la tarea necesite capacidades de agente (acceso al sistema de archivos, ejecución de comandos, cambios de código, visión nativa).

---

Disciplina General (lectura obligatoria para todas las llamadas CLI)

1. Usa heredoc para las instrucciones — evita problemas de comillas / caracteres especiales.
2. Añade </dev/null a todas las llamadas CLI — el entorno Bash de Claude Code tiene una tubería de stdin que nunca se cierra; sin esto, los CLIs se cuelgan esperando entrada.
3. Al construir instrucciones: mantenlas concisas y claras; no inyectes conceptos específicos de Claude Code (habilidades / hooks / SubAgente); usa instrucciones en chino para tareas en chino, inglés para inglés; incluye el contexto del proyecto necesario cuando sea relevante.

---

Enrutamiento por Complejidad

Selecciona automáticamente la estrategia de despacho según la naturaleza de la tarea:

¿Tarea visual? (catálogo PDF / documento escaneado / captura de pantalla / análisis de imagen)
├── Sí → [Gemini CLI] — análisis visual nativo de PDF + imagen
│   Disparador: el usuario proporciona ruta de imagen/PDF + la tarea implica "leer" contenido;
│   o la salida de markitdown está vacía/anormalmente pequeña
│   → NO intentes markitdown primero — enruta directamente a Gemini
│
├── Pensamiento/análisis puro (análisis de negocio, estrategia, comprensión de texto, traducción)
│   → [Llamada API directa] — no se necesita capacidad de agente, usa curl directamente a la API
│   10x más rápido; soporta modelos sin CLI (DeepSeek/Qwen/GLM etc.)
│
├── Simple + reversible (instalar paquetes, formatear, buscar, generar plantillas)
│   → [Despacho único] — prefiere SubAgente de Claude (Haiku) para velocidad
│   Usa CLI externo solo cuando la tarea necesite capacidades nativas chinas o específicas de IA
│
├── Ejecución de código (corregir errores, escribir pruebas, pequeña refactorización, generar archivos de código)
│   → [Modo escritura Codex] — sandbox=full, Codex modifica código directamente
│   Condición: tarea clara, en un proyecto gestionado con git, radio de explosión controlable
│   Siempre recuerda al usuario que haga `git diff` después
│
├── Complejidad media (desarrollo de funcionalidades, análisis de documentos, análisis de código)
│   → [Despacho único] — envía a la IA más adecuada
│
├── Complejo + irreversible (diseño de arquitectura, selección de tecnología, refactorización importante)
│   → [Multidifusión] — escalado automático, envía a 2-3 IAs, compara salidas
│
└── El usuario especifica IA ("ejecuta esto con Kimi")
    → [Asignación directa] — envía a la IA especificada, omite la coincidencia

Disparadores de multidifusión (cualquiera provoca escalado automático):

• El usuario dice "importante", "decisión crítica", "no puede estar equivocado"
• La tarea implica operaciones irreversibles (migración de base de datos, despliegue en producción)
• La tarea es selección de tecnología o diseño de arquitectura
• Radio de explosión estimado > 10 archivos o 3 módulos
• Tareas de análisis estratégico/de negocio en chino (por defecto: paralelo triple)

→ Consulta references/model-roster.md para recomendaciones de alineación de multidifusión por tipo de tarea.

---

Métodos de Despacho

API Agregador — ★ ruta fácil (una clave, recomendada)

El mismo api-dispatch.sh enruta a través de un agregador cuando configuras un proveedor. Una clave desbloquea todos los modelos a continuación — sin registro por proveedor.

# Configurar una vez por sesión (extranjero → openrouter, China → siliconflow), luego todos los alias compatibles funcionan
export DISPATCH_PROVIDER=openrouter        # o: siliconflow

$BASE_DIR/scripts/api-dispatch.sh --model deepseek "$(cat <<'EOF'
contenido de la instrucción
EOF
)"

# Anulación por llamada sin tocar la variable de entorno
$BASE_DIR/scripts/api-dispatch.sh --via siliconflow --model kimi "instrucción"

# Vía de escape — pasa cualquier ID de modelo del agregador textualmente (la tabla de alias no puede cubrir todo)
$BASE_DIR/scripts/api-dispatch.sh --via openrouter --model-id anthropic/claude-3.7-sonnet "instrucción"

Orden de resolución del proveedor: bandera --via > variable env $DISPATCH_PROVIDER > direct (predeterminado).

Proveedor	Archivo de Clave (~/.config/ai-keys/)	Alias	Nota
openrouter	openrouter.env (OPENROUTER_API_KEY)	deepseek / qwen / glm / kimi / minimax / claude / gpt / gemini	Extranjero; necesita VPN en China continental
siliconflow	siliconflow.env (SILICONFLOW_API_KEY)	deepseek / qwen / glm / kimi / minimax	China directo; solo código abierto/nacional (sin Claude/GPT/Gemini). Usuarios internacionales: export SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1

Los IDs de modelo del agregador son la parte volátil — los mapas alias → ID de modelo viven en references/model-roster.md; si una llamada da 404 en el modelo, verifica en la página de modelos del proveedor o pasa el ID correcto mediante --model-id.

Llamada API Directa — por proveedor (avanzado, sin agregador)

Si ya tienes claves por proveedor (o quieres evitar la tarifa de recarga de crédito del agregador), llama a cada proveedor directamente. Requiere un .env separado por proveedor:

$BASE_DIR/scripts/api-dispatch.sh --model <modelo> "$(cat <<'EOF'
contenido de la instrucción
EOF
)"

Texto largo mediante stdin:

echo "contenido de texto largo" | $BASE_DIR/scripts/api-dispatch.sh --model <modelo> --stdin

Modelos compatibles — consulta references/model-roster.md para la lista completa con fortalezas por modelo y recomendaciones de alineación de multidifusión.

Parámetro	Modelo	Archivo de Clave	Contexto
deepseek	DeepSeek V4-Pro (modo pensamiento activado)	deepseek.env	1M
qwen	Qwen3.6 Plus (Tongyi)	dashscope.env	1M
glm	GLM-5.2 (Zhipu insignia)	zai.env	200K
doubao	Doubao Seed-2.0 Pro (ByteDance)	volcengine.env	256K
minimax	MiniMax M3	minimax.env	—

Los nombres de los modelos evolucionan con las actualizaciones del proveedor — consulta la documentación del proveedor antes de llamar.

Codex CLI (OpenAI) — Protocolo App Server, sin arranque en frío

Modo solo lectura (análisis / revisión / investigación):

node $BASE_DIR/scripts/codex-appserver.mjs --effort xhigh "$(cat <<'EOF'
contenido de la instrucción
EOF
)" </dev/null

Modo escritura (cambios de código / correcciones de errores / generación de pruebas / creación de archivos):

node $BASE_DIR/scripts/codex-appserver.mjs --effort xhigh --sandbox full "$(cat <<'EOF'
contenido de la instrucción
EOF
)" </dev/null

Reglas de seguridad del modo escritura:

• Solo usar en directorios de proyecto gestionados con git (--cwd /ruta/al/proyecto)
• Después de la ejecución, recuerda siempre al usuario que haga git diff para revisar los cambios; git checkout . para revertir si no está satisfecho
• Para código de producción / bases de datos / scripts de despliegue, degradar a modo solo lectura + generar recomendaciones

Notas:

• --sandbox predeterminado es read-only; el modo escritura usa full (el script también soporta workspace-write / danger-full-access para uso avanzado)
• El script tiene una solución automática incorporada para rutas no ASCII (auto-symlink --cwd con caracteres CJK crea automáticamente un symlink temporal en /tmp, limpiado al salir)
• No añadas 2>/dev/null — el script genera información estructurada de progreso y errores en stderr
• El texto largo puede usar stdin: echo "texto largo" | node $BASE_DIR/scripts/codex-appserver.mjs --stdin --effort xhigh

Gemini CLI (Google) — se recomienda script supervisor

El supervisor tiene reintento inteligente / cadena de respaldo / interruptor de circuito / tiempo de espera / registro incorporados:

$BASE_DIR/scripts/gemini-supervisor.sh --cwd "/ruta/al/dir/de/trabajo" "$(cat <<'PROMPT_END'
contenido de la instrucción
PROMPT_END
)"

Comportamiento predeterminado del supervisor:

• Cadena de respaldo: modelo insignia → GA estable → flash (se salta automáticamente si no está disponible)
• Clasificación de errores: congestión a corto plazo 429 → retroceso + reintento con jitter; agotamiento de cuota diaria → saltar al siguiente modelo; 503 → misma ruta de retroceso
• Presupuesto global de intentos: 6; tiempo de espera máximo por modelo: 600s (configurable mediante GEMINI_MODEL_TIMEOUT)
• Interruptor de circuito: 3 fallos consecutivos por modelo → enfriamiento de 30 minutos
• Registros: ~/.cache/dispatch/gemini.log (JSONL) + estado: ~/.cache/dispatch/gemini-state.json

Especificar un solo modelo (saltar respaldo): $BASE_DIR/scripts/gemini-supervisor.sh --model <id-modelo> "instrucción" Modo stdin (recomendado para instrucciones largas): cat instruccion.txt | $BASE_DIR/scripts/gemini-supervisor.sh --stdin --cwd "/dir/trabajo"

Visión Gemini / análisis PDF (Gemini soporta de forma nativa PDF + análisis visual de imagen — la ruta estándar para PDFs escaneados / capturas de pantalla):

$BASE_DIR/scripts/gemini-supervisor.sh \
  --cwd "/ruta/al/dir/de/archivos" \
  "$(cat <<'PROMPT_END'
Por favor, analiza completamente todas las páginas de xxx.pdf y genera en formato markdown:
- Conserva todas las tablas de datos (usa sintaxis de tabla markdown)
- Conserva todas las especificaciones, parámetros técnicos, números de modelo
- Anota los números de página (## Página 1 / ## Página 2 ...)
- No omitas ningún detalle técnico
PROMPT_END
)" > salida.md

Casos de uso: catálogos PDF (sin capa de texto), escaneos, fichas técnicas de productos, análisis de capturas de pantalla, OCR de imágenes, extracción de datos de gráficos. Redirige a archivo (... > salida.md) para salidas grandes y evitar truncamiento de stdout.

Kimi CLI (Moonshot) — se recomienda script envoltorio, enrutamiento automático de endpoint

Disciplina del modelo de pensamiento: Kimi K2.6 es un modelo de pensamiento — el razonamiento puede llevar minutos para instrucciones complejas. El tiempo de espera de Bash debe ser ≥600000 (10 min) para tareas complejas. El script tiene streaming SSE incorporado + guardia inactiva (umbral de 120s sin bytes) + límite máximo de 900s. NO mates a mitad de ejecución ni lo sustituyas con curl escrito a mano. Para modo rápido: prefijo KIMI_NO_THINK=1 (inyecta {"thinking":{"type":"disabled"}}, respuesta ~4s, pero la calidad baja — solo para tareas que no requieren razonamiento).

# Predeterminado: endpoint general Moonshot (api.moonshot.cn/v1, MOONSHOT_API_KEY)
$BASE_DIR/scripts/kimi-dispatch.sh "$(cat <<'EOF'
contenido de la instrucción
EOF
)"

# Endpoint de codificación opt-in (Kimi CLI + api.kimi.com/coding/v1, KIMI_API_KEY)
KIMI_FOR_CODING=1 $BASE_DIR/scripts/kimi-dispatch.sh "instrucción"

# Modo rápido (desactivar pensamiento, respuesta ~4s)
KIMI_NO_THINK=1 $BASE_DIR/scripts/kimi-dispatch.sh "tarea simple"

Endpoint	Características	Mejor para
Moonshot general predeterminado	Razonamiento visible, conserva tendencia de seguimiento	Análisis general, preguntas y respuestas
KIMI_FOR_CODING=1	Mayor volumen de salida, arnés de agente incorporado, razonamiento oculto	Informes largos, escritura de archivos impulsada por agente, código de varios pasos

SubAgente Interno de Claude Code (sin CLI externo)

Para tareas simples usa Haiku, para tareas estándar usa Sonnet — genera un SubAgente a través de la herramienta Agent (especifica model: haiku o model: sonnet). Más rápido y barato que CLI sin cabeza, sin dependencias externas.

---

Verificación de Entorno

Comprobación rápida de disponibilidad antes de despachar:

# Herramientas CLI
command -v codex; command -v gemini; command -v kimi

# Claves API (para llamadas API directas)
ls ~/.config/ai-keys/*.env 2>/dev/null

Solo despacha a modelos disponibles. Si un CLI no está disponible, recurre a llamada API directa o cambia de modelo; un archivo de clave API existente significa que ese modelo se puede invocar.

---

Paralelización Multimodelo (validación cruzada / múltiples perspectivas)

Cuando necesitas que múltiples modelos den perspectivas independientes sobre la misma pregunta, dispara múltiples llamadas Bash en paralelo y deja que Claude sintetice los resultados. Escenarios típicos: decisiones importantes, selección de tecnología, verificación previa antes de acciones irreversibles, baja confianza en la salida de un solo modelo.

# Ejemplo de paralelización triple (misma instrucción a tres modelos)
$BASE_DIR/scripts/kimi-dispatch.sh "tarea de análisis" &
$BASE_DIR/scripts/api-dispatch.sh --model deepseek "tarea de análisis" &
$BASE_DIR/scripts/api-dispatch.sh --model doubao "tarea de análisis" &
wait

Principio de selección: diversidad cognitiva > cantidad — elige modelos con diferentes datos de entrenamiento / arquitectura para obtener perspectivas genuinamente diferentes; usa siempre el nivel más alto de cada modelo; controla el costo limitando el número de modelos en paralelo. Usa wait para esperar a que todos los trabajos en segundo plano terminen; si un modelo falla, las otras salidas aún proporcionan información valiosa.