أفضل الممارسات

هذه المقالة هي ملخص لـ "الحفر التي تم الدوس عليها". إذا كنت قد كتبت أكثر من 10 سير عمل، فستتمكن من التعاطف معها؛ إذا لم تكن قد كتبتها، فاحفظها أولاً ثم ارجع إليها عندما تصادفها.

1. كيفية كتابة سير العمل الذي يمكن وضعه في الإنتاج

بداية من نموذج

حتى لو كانت حالة استخدامك فريدة من نوعها من بين 240+ النماذج هناك عادة واحدة يمكنك "النصف، تغيير النصف" بدءًا من النموذج يوفّر الكثير من الوقت اللازم لبناء الهيكل العظمي من الصفر.

Instantiate from template حيث يبدأ معظم المستخدمين.

قم بـ "الإصدار الغبي" أولاً، ثم "الإصدار الذكي"

الإصدار الأول من سير العمل الجديد:

• القيم الافتراضية المرمزة للمتغيرات
• لا تضيف شرطًا، فقط قم بتشغيلهم جميعًا.
• استخدم مفتاح LLM الموحد للمنصة، فلا داعي للقلق بشأن BYOK
• لا تعلق كرون، تشغيل يدويا

بعد الانتهاء من ذلك، سنقوم "بتحسين" واحدًا تلو الآخر: المتغيرات، والتفرع، وBYOK، وكرون، والموافقة. بهذه الطريقة، يمكن تحديد المشاكل بسهولة في كل خطوة.

قم بالتشغيل الجاف في كل مرة تقوم فيها بإجراء تغيير

تم تغيير شيء ما ← التشغيل الجاف لرؤية هيكل DAG والتدفق المتغير ← التشغيل مرة أخرى. تكاليف التشغيل الجاف صفر، لا تقفز.

2. اختيار نوع الخطوة

الأولوية هي من الأعلى إلى الأسفل. إذا واجهت صعوبة في الاختيار، فاختر ما هو أعلى مرتبة:

1. code — إذا كان بإمكانك استخدام المنطق الحتمي، فلا تستخدم LLM. سريع ورخيص وقابل للاختبار.
2. classifier — استخدمه عندما يكون LLM مطلوبًا ولكن الإخراج عبارة عن فئة؛ لا تستخدم أغنية فردية للسماح للوكيل باللعب بحرية.
3. single — معظم مهام "التلخيص/الاستخراج/إعادة الكتابة".
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — استخدمها عندما تحتاج المهمة إلى عدة منظورات لتهدئة الأمور؛ استخدام واحد عندما يمكن لوكيل واحد التعامل معها وحدها.
6. agent_based — تتمتع المهام بخصائص متفرعة قوية، ويتطلب كل فرع من LLM تحديد مكان إرسالها.
7. state_machine — هناك تحولات واضحة للحالة، مثل الجولات المتعددة لدورة حياة التفاعل/أمر العمل.
8. manual_approval — ويجب إضافتها قبل أي خطوات تؤثر على الإنترنت / إنفاق الأموال / الجهات الخارجية.

3. المتغيرات وتدفق البيانات

يتم استخراج الحقول الكبيرة أولاً ثم تمريرها

عندما ترجع الخطوة الأولية 100 كيلو بايت JSON، لا ترسلها مباشرة إلى المهمة النهائية. استخدم الاستخراج لتحديد الحقول التي تحتاجها حقًا:

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

استخدم | الافتراضي (...) لمعرفة ذلك

عند الإشارة إلى متغير قد يكون فارغًا (مخرجات الخطوة التي تم تخطيها بشرط)، أضف الإعداد الافتراضي:

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

condition فرع مقابل on_failure

لا تخلط:

• عناصر التحكم في الحالة "لا يمكن اتخاذ هذه الخطوة في ظل الظروف العادية" - تخطي = تخطي (لا يعتبر فشلًا)
• on_failure هو "إجراء تعويضي بعد الخطأ" - إرسال إشعار/الرجوع إلى مصدر بيانات بديل

استخدم on_failure كتجربة، ولكن ليس كفرع عادي. يستخدم منطق العمل العادي الشرط.

4. الوكيل والنموذج

tool_set كلما كان أصغر كلما كان ذلك أفضل

لا يتم استخدام الأدوات المتوفرة بواسطة الإعداد المسبق الافتراضي في معظم الخطوات. قطعها إلى 2-3 قطع - يزيد معدل النجاح وينخفض استهلاك الرمز المميز.

يتم اختيار النماذج وفقا للمهام

• الاستدلال / مراجعة الكود → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• ملخص قصير / الفئة → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• الكتابة الصينية → كلود سونيت / كيمي K2
• سياق طويل (32 ألف+) → كيمي K2 / كلود 200 ألف

درجة الحرارة اختر حسب المهمة

• 0.0 – 0.3 – الاستدلال/التصنيف/الاستخراج (ليكون مستقرًا)
• 0.4 – 0.7 – ملخص/إعادة كتابة (متوازن)
• 0.7 – 0.9 – الكتابة الإبداعية/العصف الذهني (كن مبدعاً)

5. الاستمرار العاجز والتلقائي

تضيف جميع خطوات خط أنابيب البيانات الخالصة قوة: صحيح - يمكن للخدمة الاستمرار في العمل بعد إعادة التشغيل. لا تقم بإضافة خطوات تحتوي على آثار جانبية (إرسال رسائل/تقديم طلبات).

انظر التفاصيل عطر السيارات.

6. التقسيم والنموذجية

1. يحتوي سير العمل على أكثر من 15 خطوة، ويجب تقسيمها.
2. يجب استخدام نفس المنطق المكون من 3-5 خطوات في سير عمل آخر - ويجب تحويله إلى وحدة نمطية (سير عمل فرعي).
3. بعد إصدار الوحدة، سيؤدي حذف الإدخال/تغيير النوع إلى كسر التوافق، ويجب ترقية الإصدار الرئيسي.

7. مراقبة التكاليف

• التشغيل الجاف أولاً — كما ذُكر، الإهدار الحقيقي يُكلّفُ الأكثر، لذا هذا يُوفّرُ الأكثر.
• التصنيف باستخدام نماذج رخيصة — المصنف 9 من أصل 10 لا يتطلب Opus/GPT-5.
• هناك حد أعلى للتزامن — لمعالجة الدفعات، استخدم sub_workflow + max_parallel للتحكم في التزامن، ولا تدع TPM ينفجر.
• مؤشر ذاكرة التخزين المؤقت RAG — من المكلف إعادة تضمين نفس المجموعة في كل مرة ونقل النتائج إلى المنتج.
• ربط إنذار الميزانية — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. الأمن والامتثال

• لا تكتب المفاتيح أبدًا في YAML - استخدم مركز الاعتماد.
• بيانات اعتماد خطوة التعليمات البرمجية: يجب أن تكون القائمة واضحة - لا تقدم بيانات اعتماد الخطوة التي لا تحتاج إليها.
• إضافة موافقة يدوية قبل الدفع / التواصل الخارجي / كتابة قاعدة بيانات العملاء.
• فكر في فتح مهام سير العمل التي تتضمن بيانات المستخدم موافققائمة المعتمدين لفريق الامتثال للدخول.
• (د) أن تُحوّل المفتاح المستخدم في موقع " ويهوك " (وسر التوقيع في طريقة التوافق) بانتظام.

9. عملية الاختبار والإطلاق

1. يتم تشغيل سير العمل الجديد أولاً على صفحة اختبار سير العمل.
2. قم بتشغيل البرنامج النصي لخطوة التعليمات البرمجية بشكل منفصل في العقدة/البايثون المحلية لرؤية الإخراج.
3. قم بتشغيل سلوك الوكيل باستخدام مصحح أخطاء نقطة التوقف + عينة صغيرة 10 مرات للتحقق من الاستقرار.
4. استخدم "التشغيل مرة واحدة على الفور" للتحقق من المنطقة الزمنية/المعلمة المحددة مسبقًا قبل بدء الجدولة عبر الإنترنت.

10. التعاون والإصدارات

• قبل إجراء أي تغييرات مهمة، "قم بتصدير YAML" وقم بعمل نسخة احتياطية محلية - حتى إذا كنت لا تعرف تاريخ الإصدار، تكون النسخة المحلية أكثر موثوقية.
• التحرير متعدد الأشخاص: يأخذ شخص واحد القفل، ويحفظ التغييرات، ويحرر القفل، ثم يأخذه الشخص التالي. يرجى تقسيم التغيير الموازي إلى مهام سير عمل فرعية.
• قم بالمزامنة مع الفريق قبل إجراء تغييرات رئيسية على الإصدار - ربما يعتمد الآخرون على وحدتك.

11. الرصد والإنذار

• يرتبط فشل تنفيذ سير العمل الرئيسي بإشعار Slack/Feishu - إذا فشل، ستعرف على الفور.
• تحقق من لوحة بيانات البيانات بانتظام - ما هو سير العمل الأكثر تكلفة/الأبطأ/الذي يفشل في أغلب الأحيان؟ التحسين يبدأ به.
• تحقق من سجل التدقيق مرة واحدة شهريًا - هل هناك أي استثناءات للأذونات/من استخدم بيانات الاعتماد.

12. لقد أكملت قائمة مراجعة سير العمل

1. مرت فترة التشغيل الجاف
2. تشغيل ناجح
3. يتم تأكيد استراتيجية Idempotent/إعادة المحاولة لكل خطوة
4. هناك موافقة يدوية أو ضوابط شرطية صريحة قبل الآثار الجانبية الخارجية.
5. يتم تحليل جميع بيانات الاعتماد من مركز الاعتماد، ولا يوجد مفتاح نص عادي في YAML
6. تم ربط cron / webhook وتأكيد "وقت التشغيل التالي"
7. قم بإعداد إشعارات الفشل (على الأقل دفع Execution.failed إلى Slack)
8. قم بتصدير نسخة من YAML إلى git للنسخ الاحتياطي خارج الموقع

يوصى بمزيد من القراءة

• YAML Syntax reference — لا يمكن التحقق من الحقول الغامضة بدقة
• نقطة الانطلاق — أداة لتحديد المشاكل في العمليات المعقدة
• الاضطرابات — مقارنة أعراض محددة