Melhores Práticas

Este artigo é um resumo de "poços pisados".

1. Como escrever um workflow que possa ser colocado em produção

Iniciar a partir de um modelo

Mesmo que seu caso de uso pareça único, entre os modelos 240+, geralmente há um que você pode "manter metade, mudar metade". A partir de um modelo economiza muito do tempo que leva para construir o esqueleto do zero.

Instantia do modelo é onde a maioria dos usuários começam.

Faça primeiro a "versão estúpida" e depois a "versão inteligente"

Primeira versão do novo workflow:

• Valores padrão codificados para variáveis
• Não adicione condições, apenas execute todas elas.
• Use a chave LLM unificada da plataforma, não precisa se preocupar com BYOK
• Não trave o cron, execute manualmente

Após a execução, iremos "refinar" um por um: variávelização, ramificação, BYOK, cron e aprovação.

Faça um teste sempre que fizer uma alteração

Algo mudou → teste para ver a estrutura do DAG e o fluxo variável → execute novamente.

2. Seleção do tipo de etapa

A prioridade é de cima para baixo.

1. code — Se você pode usar lógica determinística, não use LLM.
2. classifier — Use-o quando o LLM for necessário, mas o resultado for uma categoria;
3. single — A maioria das tarefas de "resumir/extrair/reescrever".
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — Use-o quando uma tarefa precisa de várias perspectivas para hash coisas para fora; use único quando um Agente pode lidar com isso sozinho.
6. agent_based — As tarefas têm fortes características de ramificação e cada ramificação exige que o LLM determine para onde enviá-la.
7. state_machine — Existem transições de estado claras, como múltiplas rodadas de interação/ciclo de vida de ordem de serviço.
8. manual_approval — Deve ser adicionado antes de qualquer etapa que afete on-line/gastar dinheiro/partes externas.

3. Variáveis e fluxo de dados

Campos grandes são extraídos primeiro e depois passados

Quando a etapa upstream retornar JSON de 100 KB, não o envie diretamente para a tarefa downstream.

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

Usar |

Ao se referir a uma variável que pode estar vazia (a saída de uma etapa ignorada por condição), adicione padrão:

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

condition Filial vs on_failure

Não misture:

• controles de condição "não é possível realizar esta etapa em circunstâncias normais" - skip = SKIPPED (não considerado uma falha)
• on_failure é "ação compensatória após erro" - envia notificação/downgrade para fonte de dados alternativa

Use on_failure como try-catch, mas não como um branch normal.

4. Agente e modelo

tool_set Quanto menor, melhor

As ferramentas fornecidas pela predefinição padrão não são usadas na maioria das etapas.

Os Modelos são selecionados de acordo com as tarefas

• Raciocínio / Revisão de código → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• Breve resumo / Categoria → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• Escrita chinesa → Claude Sonnet / Kimi K2
• Contexto longo (32K+) → Kimi K2 / Claude 200K

Temperatura Selecionar por tarefa

• 0,0 – 0,3 – Raciocínio/Classificação/Extração (para ser estável)
• 0,4 – 0,7 – resumo/reescrita (equilibrado)
• 0,7 – 0,9 – Escrita criativa/brainstorming (seja criativo)

5. Continuação idempotente e automática

Todas as etapas do pipeline de dados puro adicionam idempotent: true - o serviço pode continuar em execução após a reinicialização.

Ver detalhes Continuar automaticamente.

6. Divisão e Modularização

1. Um workflow tem mais de 15 etapas e deve ser dividido.
2. A mesma lógica de 3 a 5 etapas precisa ser usada em outro workflow - deve ser transformada em um módulo (sub_workflow).
3. Após o lançamento do módulo, excluir a entrada/alterar o tipo quebrará a compatibilidade e a versão PRINCIPAL deverá ser atualizada.

7. Controle de custos

• teste primeiro — Como observado, uma execução real desperdiçada custa mais, de modo que esta economiza mais.
• Classificação usando modelos baratos — O classificador 9 de 10 não requer Opus/GPT-5.
• Existe um limite máximo de simultaneidade — Para processamento em lote, use sub_workflow + max_parallel para controlar a simultaneidade e não deixe o TPM explodir.
• Índice RAG de cache — É caro incorporar sempre o mesmo corpus e persistir os resultados no produto.
• Vincular alarme de orçamento — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. Segurança e Conformidade

• Nunca escreva chaves em YAML - use o Credential Center.
• As credenciais do passo de código: a lista deve ser explícita — não forneça credenciais que o passo não vai usar.
• Adicione manual_approval antes do pagamento/comunicação externa/escrita no banco de dados do cliente.
• Considere abrir workflows envolvendo dados do usuário aprovadorLista de aprovadores para a equipe de conformidade inserir.
• Rodar a chave API usada para o Webhook (e o segredo de assinatura no modo compatibilidade) regularmente.

9. Processo de teste e lançamento

1. O novo workflow é primeiro testado na página de workflow de teste.
2. Execute o script da etapa de código separadamente no nó/python local para ver a saída.
3. Execute o comportamento do agente usando o depurador de ponto de interrupção + pequena amostra 10 vezes para verificar a estabilidade.
4. Use "Acionar uma vez imediatamente" para verificar o fuso horário/parâmetro predefinido antes que o agendamento fique online.

10. Colaboração e versões

• Antes de fazer qualquer alteração importante, "exporte YAML" e faça um backup local - mesmo que você não conheça o histórico da versão, uma cópia local é mais confiável.
• Edição multipessoa: uma pessoa pega o bloqueio, salva as alterações, libera o bloqueio e então a próxima pessoa o faz.
• Sincronize com a equipe antes de alterações importantes na versão - outras pessoas podem estar dependendo do seu módulo.

11. Monitoramento e Alarme

• O workflow de execução.failed da chave está vinculado à notificação do Slack/Feishu - se falhar, você saberá imediatamente.
• Verifique o painel de dados regularmente - qual workflow é o mais caro/mais lento/falha com mais frequência?
• Verifique o log de auditoria uma vez por mês - há alguma exceção às permissões/quem usou as credenciais.

12. Concluí uma lista de verificação de workflow

1. teste aprovado
2. Uma corrida de sucesso
3. A estratégia idempotente/nova tentativa para cada etapa é confirmada
4. Existem controles manuais_approval ou condicionais explícitos antes dos efeitos colaterais externos.
5. Todas as credenciais são analisadas no Credential Center, não há chave de texto simples no YAML
6. cron/webhook vinculado e confirmado "próximo horário de disparo"
7. Configure notificações de falha (pelo menos push execução.failed para Slack)
8. Exporte uma cópia do YAML para git para backup externo

Leitura adicional recomendada

• Referência de sintaxe YAML — Os campos difusos não podem ser verificados com precisão
• Depuração de pontos de paragem — Uma ferramenta para localizar problemas em processos complexos
• Resolução de Problemas — Comparação de sintomas específicos