Best Practices

Dieser Artikel ist eine Zusammenfassung von „Gruben, auf die getreten wurde“. Wenn Sie mehr als 10 Arbeitsabläufe geschrieben haben, können Sie sich in diese hineinversetzen; Wenn Sie sie noch nicht geschrieben haben, speichern Sie sie zunächst und greifen Sie darauf zurück, wenn Sie darauf stoßen.

1. Wie schreibe ich einen Workflow, der in die Produktion übernommen werden kann?

Von einer Vorlage aus starten

Auch wenn Ihr Szenario sehr speziell wirkt, findet sich unter den 240+ Vorlagen fast immer eine, die sich „halb zerlegen, halb anpassen“ lässt. Der Start von einer Vorlage spart viel Zeit gegenüber dem Aufbau des Grundgerüsts von Grund auf.

Instanziieren Sie aus der Vorlage ist für die meisten Nutzer der erste Schritt.

Machen Sie zuerst die „dumme Version“, dann die „intelligente Version“

Erste Version des neuen Workflows:

• Hartcodierte Standardwerte für Variablen
• Fügen Sie keine Bedingung hinzu, sondern führen Sie sie einfach alle aus.
• Nutzen Sie den einheitlichen LLM-Schlüssel der Plattform, ohne sich um BYOK kümmern zu müssen
• Cron nicht hängen lassen, sondern manuell ausführen

Nach dem Durchlaufen werden wir eine nach der anderen „verfeinern“: Variableisierung, Verzweigung, BYOK, Cron und Genehmigung. Auf diese Weise können Probleme bei jedem Schritt leicht lokalisiert werden.

Machen Sie jedes Mal einen Probelauf, wenn Sie eine Änderung vornehmen

Etwas geändert → Probelauf durchführen, um die DAG-Struktur und den Variablenfluss zu sehen → erneut ausführen. Trockenlauf kostet null, springen Sie nicht.

2. Auswahl des Schritttyps

Die Priorität ist von oben nach unten. Wenn Sie bei der Auswahl auf Schwierigkeiten stoßen, wählen Sie diejenige mit dem höheren Rang aus:

1. code — Wenn Sie deterministische Logik verwenden können, verwenden Sie kein LLM. Schnell, günstig, testbar.
2. classifier — Verwenden Sie es, wenn LLM erforderlich ist, die Ausgabe jedoch eine Kategorie ist; Verwenden Sie Single nicht, um den Agenten frei spielen zu lassen.
3. single — Die meisten „Zusammenfassen/Extrahieren/Neuschreiben“-Aufgaben.
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — Verwenden Sie es, wenn eine Aufgabe die Diskussion mehrerer Perspektiven erfordert; was ein einzelner Agent eigenständig erledigen kann, nutzen Sie single.
6. agent_based — Aufgaben weisen starke Verzweigungsmerkmale auf, und für jede Verzweigung muss LLM bestimmen, wohin sie gesendet werden soll.
7. state_machine — Es gibt klare Zustandsübergänge, wie z. B. mehrere Interaktionsrunden/Lebenszyklus von Arbeitsaufträgen.
8. manual_approval — Es muss vor allen Schritten hinzugefügt werden, die sich auf Online-/Geldausgaben/externe Parteien auswirken.

3. Variablen und Datenfluss

Große Felder werden zunächst extrahiert und dann übergeben

Wenn der Upstream-Schritt 100 KB JSON zurückgibt, senden Sie es nicht direkt an die Downstream-Aufgabe. Wählen Sie mit Extract die Felder aus, die Sie wirklich benötigen:

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

Verwenden Sie | default(...) um es herauszufinden

Wenn Sie auf eine Variable verweisen, die möglicherweise leer ist (die Ausgabe eines durch eine Bedingung übersprungenen Schritts), fügen Sie default hinzu:

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

condition Branch vs. on_failure

Nicht vermischen:

• Bedingungskontrollen „Dieser Schritt kann unter normalen Umständen nicht ausgeführt werden“ – überspringen = ÜBERSPRINGT (wird nicht als Fehler betrachtet)
• on_failure ist „Ausgleichsmaßnahme nach Fehler“ – Benachrichtigung/Downgrade an alternative Datenquelle senden

Verwenden Sie on_failure als Try-Catch, aber nicht als normalen Zweig. Die normale Geschäftslogik verwendet eine Bedingung.

4. Agent und Model

tool_set Je kleiner, desto besser

Die in der Standardvoreinstellung bereitgestellten Werkzeuge werden in den meisten Schritten nicht verwendet. Auf 2-3 Stücke schneiden – die Erfolgsquote steigt und der Token-Verbrauch sinkt.

Die Modelle werden nach Aufgaben ausgewählt

• Argumentation / Codeüberprüfung → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• Kurze Zusammenfassung / Kategorie → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• Chinesische Schrift → Claude Sonnet / Kimi K2
• Langer Kontext (32K+) → Kimi K2 / Claude 200K

Temperatur Auswahl nach Aufgabe

• 0,0 – 0,3 – Argumentation/Klassifikation/Extraktion (um stabil zu sein)
• 0,4 – 0,7 – Zusammenfassung/Umschreibung (ausgewogen)
• 0,7 – 0,9 – Kreatives Schreiben/Brainstorming (kreativ sein)

5. Idempotente und automatische Fortsetzung

Alle Schritte der reinen Datenpipeline fügen idempotent: true hinzu – der Dienst kann nach dem Neustart weiter ausgeführt werden. Fügen Sie keine Schritte hinzu, die Nebenwirkungen enthalten (Nachrichten senden/Bestellungen aufgeben).

Siehe Details Automatische Fortsetzung.

6. Aufteilung und Modularisierung

1. Ein Workflow hat mehr als 15 Schritte – er sollte aufgeteilt werden.
2. Die gleiche 3–5-Schritte-Logik muss in einem anderen Workflow verwendet werden – sie sollte in ein Modul (sub_workflow) umgewandelt werden.
3. Nach der Veröffentlichung des Moduls wird durch das Löschen der Eingabe/Ändern des Typs die Kompatibilität unterbrochen und die MAJOR-Version muss aktualisiert werden.

7. Kostenkontrolle

• Zuerst einen Trockenlauf durchführen — Wie bereits gesagt: Ein umsonst durchlaufener echter Lauf verschwendet am meisten Geld, daher spart diese Maßnahme am meisten.
• Klassifizierung anhand günstiger Modelle — Für den Klassifikator 9 von 10 ist Opus/GPT-5 nicht erforderlich.
• Es gibt eine Obergrenze für die Parallelität — Verwenden Sie für die Stapelverarbeitung sub_workflow + max_parallel, um die Parallelität zu steuern, und lassen Sie das TPM nicht explodieren.
• RAG-Index zwischenspeichern — Es ist kostspielig, jedes Mal den gleichen Korpus neu einzubetten und die Ergebnisse für das Produkt beizubehalten.
• Budgetalarm binden — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. Sicherheit und Compliance

• Schreiben Sie niemals Schlüssel in YAML – verwenden Sie Credential Center.
• Die Liste der Anmeldeinformationen des Codeschritts sollte explizit sein – geben Sie nicht die Schrittanmeldeinformationen an, die nicht benötigt werden.
• Fügen Sie „manual_approval“ vor der Zahlung/externen Kommunikation/Schreiben der Kundendatenbank hinzu.
• Erwägen Sie die Eröffnung von Workflows mit Benutzerdaten GenehmigerListe der Genehmiger, die das Compliance-Team eingeben kann.
• Rotieren Sie den für Webhooks verwendeten API Key (sowie das signing secret im Kompatibilitätsmodus) regelmäßig.

9. Test- und Einführungsprozess

1. Der neue Workflow wird zunächst auf der Test-Workflow-Seite getestet.
2. Führen Sie das Codeschrittskript separat im lokalen Knoten/Python aus, um die Ausgabe anzuzeigen.
3. Führen Sie das Verhalten des Agenten mit dem Breakpoint-Debugger und einem kleinen Beispiel zehnmal aus, um die Stabilität zu überprüfen.
4. Verwenden Sie „Einmal sofort auslösen“, um die Zeitzone/Parametervoreinstellung zu überprüfen, bevor die Planung online geht.

10. Zusammenarbeit und Versionen

• Bevor Sie wichtige Änderungen vornehmen, „exportieren Sie YAML“ und erstellen Sie ein lokales Backup – auch wenn Sie den Versionsverlauf nicht kennen, ist eine lokale Kopie zuverlässiger.
• Bearbeitung durch mehrere Personen: Eine Person übernimmt die Sperre, speichert die Änderungen, hebt die Sperre auf und die nächste Person übernimmt sie. Bitte teilen Sie die parallele Änderung in Unterworkflows auf.
• Synchronisieren Sie sich vor größeren Versionsänderungen mit dem Team – andere verlassen sich möglicherweise auf Ihr Modul.

11. Überwachung und Alarmierung

• Der Schlüsselworkflow „execution.failed“ ist an die Slack/Feishu-Benachrichtigung gebunden – wenn er fehlschlägt, erfahren Sie es sofort.
• Überprüfen Sie regelmäßig das Daten-Dashboard – welcher Workflow ist der teuerste/langsamste/fehlschlägt am häufigsten? Die Optimierung beginnt damit.
• Überprüfen Sie das Audit-Protokoll einmal im Monat. Gibt es Ausnahmen bei den Berechtigungen bzw. wer hat die Anmeldeinformationen verwendet?

12. Ich habe eine Workflow-Checkliste ausgefüllt

1. Trockenlauf bestanden
2. Ein gelungener Lauf
3. Die idempotente/Wiederholungsstrategie für jeden Schritt wird bestätigt
4. Es gibt manuelle_Genehmigungs- oder bedingungsspezifische explizite Kontrollen vor externen Nebenwirkungen.
5. Alle Anmeldeinformationen werden vom Credential Center analysiert. In YAML gibt es keinen Klartextschlüssel
6. Cron/Webhook gebunden und „nächste Triggerzeit“ bestätigt
7. Fehlerbenachrichtigungen einrichten (zumindest „execution.failed“ an Slack senden)
8. Exportieren Sie eine Kopie von YAML nach Git für die externe Sicherung

Empfohlene weitere Lektüre

• Yaml-syntaxreferenz — Fuzzy-Felder können nicht genau überprüft werden
• Debuggen von Haltepunkten — Ein Werkzeug zur Lokalisierung von Problemen in komplexen Prozessen
• Fehlerbehebung — Spezifischer Symptomvergleich