Mejores practicas

Este artículo es un resumen de los "pozos pisados". Si has escrito más de 10 flujos de trabajo, podrás empatizar con ellos; Si no los ha escrito, guárdelos primero y vuelva a consultarlos cuando los encuentre.

1. Cómo escribir un flujo de trabajo que se pueda poner en producción.

Empezar a partir de una plantilla

Aunque su caso parezca muy singular, entre las más de 240 plantillas casi siempre hay una que sirve «tomando la mitad y modificando la otra mitad». Empezar a partir de una plantilla ahorra mucho tiempo de montar el esqueleto desde cero.

Crear una instancia desde la plantilla es el primer paso para la mayoría de los usuarios.

Haz primero la "versión estúpida" y luego la "versión inteligente".

Primera versión del nuevo flujo de trabajo:

• Valores predeterminados codificados para variables
• No agregue condiciones, simplemente ejecútelas todas.
• Utilice la clave LLM unificada de la plataforma, no necesita preocuparse por BYOK
• No cuelgues cron, ejecútalo manualmente

Después de ejecutarlo, "refinaremos" uno por uno: variableización, bifurcación, BYOK, cron y aprobación. De esta manera, los problemas se pueden localizar fácilmente en cada paso.

Realice un funcionamiento en seco cada vez que realice un cambio.

Se cambió algo → ejecución en seco para ver la estructura DAG y el flujo variable → ejecutar nuevamente. El ensayo no cuesta nada, no se salte.

2. Selección del tipo de paso

La prioridad es de arriba hacia abajo. Si tiene dificultades para elegir, elija el que tenga una clasificación más alta:

1. code — Si puede utilizar la lógica determinista, no utilice LLM. Rápido, barato y comprobable.
2. classifier — Use it when LLM is required but the output is a category; no utilice single para permitir que el Agente juegue libremente.
3. single — La mayoría de las tareas de "resumir/extraer/reescribir".
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — Úselo cuando la tarea requiera que varios puntos de vista debatan entre sí; cuando un solo Agent pueda completarla por sí solo, use single.
6. agent_based — Las tareas tienen fuertes características de ramificación y cada sucursal requiere LLM para determinar dónde enviarlas.
7. state_machine — Hay transiciones de estado claras, como múltiples rondas de interacción/ciclo de vida de la orden de trabajo.
8. manual_approval — Debe agregarse antes de cualquier paso que afecte a Internet/gastar dinero/partes externas.

3. Variables y flujo de datos

Los campos grandes se extraen primero y luego se pasan.

Cuando el paso ascendente devuelva JSON de 100 KB, no lo envíe directamente a la tarea descendente. Utilice extraer para seleccionar los campos que realmente necesita:

- id: fetch_data
  type: code
  code: |
    // 返回一个很大的 JSON
    return await heavyFetch();
  extract:
    user_count: $.data.stats.total_users
    top_3: $.data.items[:3].name

Uso | predeterminado(...) para averiguarlo

Cuando haga referencia a una variable que puede estar vacía (la salida de un paso omitido por condición), agregue default:

- id: summarize
  type: single
  agent: writer
  condition: "length({{steps.classify.categories}} | default([])) > 0"
  task: "{{steps.classify.output | default('无内容可摘要')}}"

condition Rama vs on_failure

No mezclar:

• controles de condición "no se puede realizar este paso en circunstancias normales" - skip = SKIPPED (no se considera una falla)
• on_failure es "acción compensatoria después del error": enviar notificación/bajar de categoría a una fuente de datos alternativa

Utilice on_failure como try-catch, pero no como una rama normal. La lógica empresarial normal utiliza la condición.

4. Agente y modelo

tool_set Cuanto más pequeño, mejor

Las herramientas proporcionadas por el ajuste preestablecido predeterminado no se utilizan en la mayoría de los pasos. Cut to 2-3 pieces - the success rate increases and the token consumption decreases.

Los modelos se seleccionan según las tareas.

• Razonamiento / Revisión de código → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• Breve resumen / Categoría → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• Escritura china → Claude Sonnet / Kimi K2
• Contexto largo (32K+) → Kimi K2 / Claude 200K

Temperatura Seleccionar por tarea

• 0.0 – 0.3 – Razonamiento/Clasificación/Extracción (para ser estable)
• 0,4 – 0,7 – resumen/reescritura (equilibrado)
• 0,7 – 0,9 – Escritura creativa/lluvia de ideas (sea creativo)

5. continuación idempotente y automática

Todos los pasos de la canalización de datos puros agregan idempotente: verdadero: el servicio puede continuar ejecutándose después de reiniciar. No agregue pasos que contengan efectos secundarios (enviar mensajes/realizar pedidos).

Ver detalles Reanudación automática.

6. División y modularización

1. Un flujo de trabajo tiene más de 15 pasos y debe dividirse.
2. Se debe utilizar la misma lógica de 3 a 5 pasos en otro flujo de trabajo; se debe convertir en un módulo (sub_workflow).
3. Después de lanzar el módulo, eliminar la entrada/cambiar el tipo romperá la compatibilidad y se deberá actualizar la versión PRINCIPAL.

7. Control de costos

• ejecución en seco primero — Como ya se ha dicho, un ensayo en falso que gasta una ejecución real es lo que más dinero desperdicia, así que esto es lo que más ahorra.
• Clasificación utilizando modelos baratos. — El clasificador 9 de 10 no requiere Opus/GPT-5.
• Hay un límite superior de concurrencia — Para el procesamiento por lotes, utilice sub_workflow + max_parallel para controlar la simultaneidad y no permita que el TPM explote.
• Índice RAG de caché — Es costoso volver a incorporar el mismo corpus cada vez y conservar los resultados en el producto.
• Vincular alarma de presupuesto — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. Seguridad y cumplimiento

• Nunca escriba claves en YAML; utilice el Centro de credenciales.
• Las credenciales del paso del código: la lista debe ser explícita; no proporcione las credenciales del paso que no necesita.
• Agregue manual_approval antes del pago / comunicación externa / escritura de la base de datos de clientes.
• Considere abrir flujos de trabajo que involucren datos de usuario aprobadorLista de aprobadores para que ingrese el equipo de cumplimiento.
• Rote periódicamente la API Key del Webhook (y el signing secret del modo de compatibilidad).

9. Proceso de prueba y lanzamiento.

1. El nuevo flujo de trabajo se ejecuta primero en seco en la página del flujo de trabajo de prueba.
2. Ejecute el script del paso del código por separado en el nodo local/python para ver el resultado.
3. Ejecute el comportamiento del agente usando el depurador de puntos de interrupción + una pequeña muestra 10 veces para verificar la estabilidad.
4. Use "Trigger once immediately" to verify the time zone/parameter preset before scheduling goes online.

10. Colaboración y Versiones

• Antes de realizar cambios importantes, "exporte YAML" y haga una copia de seguridad local; incluso si no conoce el historial de versiones, una copia local es más confiable.
• Edición de varias personas: una persona toma el candado, guarda los cambios, libera el candado y luego la siguiente persona lo toma. Divida el cambio paralelo en subflujos de trabajo.
• Sincronice con el equipo antes de cambios importantes en la versión; es posible que otros confíen en su módulo.

11. Monitoreo y alarmas

• La ejecución fallida del flujo de trabajo clave está vinculada a la notificación de Slack/Feishu; si falla, lo sabrás de inmediato.
• Consulte el panel de datos con regularidad: ¿qué flujo de trabajo es el más caro, el más lento o el que falla con mayor frecuencia? La optimización comienza con eso.
• Verifique el registro de auditoría una vez al mes: ¿hay excepciones a los permisos/quién ha utilizado las credenciales?

12. Completé una lista de verificación del flujo de trabajo

1. ensayo pasado
2. Una carrera exitosa
3. Se confirma la estrategia idempotente/reintento para cada paso
4. Hay controles explícitos de aprobación manual o condición antes de los efectos secundarios externos.
5. Todas las credenciales se analizan desde el Centro de credenciales, no hay ninguna clave de texto sin formato en YAML
6. cron/webhook vinculado y confirmado "próxima hora de activación"
7. Configure notificaciones de fallas (al menos envíe la ejecución. Falló en Slack)
8. Exporte una copia de YAML a git para realizar una copia de seguridad externa

Lectura adicional recomendada

• Referencia de sintaxis YAML — Los campos borrosos no se pueden comprobar con precisión
• Depuración de puntos de interrupción — Una herramienta para localizar problemas en procesos complejos
• Solución de problemas — Comparación de síntomas específicos