الاختلافات والتعبيرات

تستخدم جميع القيم الديناميكية في Braidrun "مراجع متغيرة". بناء الجملة له شكل واحد فقط: الأقواس المتعرجة المزدوجة.

{{var:name}}                     # workflow 级变量
{{steps.fetch.data.user.name}}   # 上游步骤的 JSON 输出
{{classifier.category}}          # 分类器路由结果
{{credentials.openai_api_key}}   # 凭据库里的密钥

أربعة مصادر للمتغيرات

1. var: — معلمات سير العمل

قسم المتغيرات / المعلمات في الجزء العلوي من سير العمل، أو إدخال الجدول الزمني / خطاف الويب المسبق.

variables:
  target_date:
    type: string
    default: "yesterday"
  top_n:
    type: number
    default: 10

steps:
  - id: fetch
    type: code
    code: |
      return { date: "{{var:target_date}}", top: {{var:top_n}} };

2. steps.id.* — الإخراج من خطوة المنبع

يوجد مخرجات منظمة بعد تشغيل كل خطوة. الحقول الفرعية الأكثر استخدامًا:

• steps.id.output — نص عادي أو قيمة إرجاع خام.
• steps.id.data — JSON منظم بعد الاستخراج.
• steps.id.artifacts[0].url — رابط ملف المنتج .
• steps.id.tokens / cost / duration_ms — إحصائيات التنفيذ.

steps:
  - id: fetch
    type: code
    extract:
      articles: $.items
      total: $.meta.total

  - id: summarize
    type: single
    agent: writer
    task: |
      我有 {{steps.fetch.data.total}} 条新闻，这是第一条：
      {{steps.fetch.data.articles[0].title}}

3. classifier.* — نتائج توجيه المصنف

يتم استخدام نتيجة خطوة المصنف السابقة كمرجع من المستوى الأول للحالة/التفرع.

steps:
  - id: triage
    type: classifier
    agent: planner
    task: "{{var:user_message}}"
    categories: [billing, technical, other]

  - id: respond
    type: single
    condition: "{{classifier.category}} == 'billing'"
    agent: writer
    task: "客户关于账单的问题是：{{var:user_message}}"

أي ما يعادل الخطوات.<classifier_step_id>.category - أقصر وأكثر دلالة.

4. credentials.* — مرجع الاعتماد

رابط الحل: مساحة اسم المستخدم → مساحة اسم الفريق → مساحة اسم النظام؛ انظر التفاصيل بيانات الاعتماد.

تعبير JSONPath

يمكن كتابة بناء جملة المسار البسيط بين قوسين متعرجين - متوافق بشكل أساسي مع مجموعة فرعية من JSONPath:

• {{steps.fetch.data.articles[0].title}} — مؤشر المصفوفة
• {{steps.fetch.data.articles[*].title}} — جميع عناصر المصفوفة (مصفوفة الإرجاع)
• {{steps.fetch.data.articles[?(@.score>5)]}} — التصفية المشروطة
• {{steps.fetch.data | length}} — الفلتر: الطول / العلوي / السفلي / الافتراضي / القطع

استخراج: هيكلة إخراج الخطوة

غالبًا ما تحتاج البيانات التي يتم إرجاعها بواسطة LLM أو التعليمات البرمجية إلى "اختيار بعض الحقول" لاستخدامها في المراحل النهائية. استخدام استخراج:

- id: fetch_user
  type: code
  code: |
    const res = await fetch('https://api.example.com/me');
    return await res.json();
  extract:
    name: $.profile.fullName
    company: $.profile.org.name
    is_admin: $.permissions[?(@=='admin')] | length > 0

بعد ذلك، ستكون Steps.fetch_user.data.name / .company متاحة مباشرة.

الشرط: التنفيذ المشروط

يمكن أن يكون لأي خطوة شرط - عندما يكون التعبير خطأ، يتم تخطي هذه الخطوة (يتم وضع علامة تخطي على حالة التنفيذ).

- id: summarize
  type: single
  agent: writer
  condition: "{{classifier.category}} == 'ai' && length({{steps.fetch.data.articles}}) > 0"
  task: "..."

المشغلين المدعومين:

• يقارن:== != < > <= >=
• منطق:&& || !
• خيط:contains(x, y) startsWith(x, y) endsWith(x, y) matches(x, /re/)
• صفيف:length(x) any(list, cond) all(list, cond)
• حكم قصيرة:isEmpty(x) isNotEmpty(x)

إعادة المحاولة: استراتيجية إعادة المحاولة

- id: fetch
  type: code
  code: "..."
  retry:
    max_attempts: 3
    backoff: exponential     # fixed | linear | exponential
    initial_delay_ms: 1000
    max_delay_ms: 30000
    retry_on: [network, rate_limit, http_5xx]

أعد المحاولة فقط في حالة وجود أخطاء عابرة (الشبكة/حد السرعة/5xx). لن تتم إعادة محاولة استثناءات الأعمال (فشل الحالة، رفض LLM).

التجميع: دمج مدخلات متعددة

استخدم التجميع عندما تقوم خطوة بجمع البيانات من مصادر أولية متعددة. على سبيل المثال، قم بتلخيص التعليقات بعد group_chat:

- id: combine
  type: code
  aggregate:
    comments: concat_lines({{steps.group_chat_1.messages}})
    total_tokens: sum({{steps.*.tokens}})
  code: "return { comments, total_tokens };"

الوظائف المجمعة المتاحة: concat/concat_lines/json_array/join(sep)/first/last/max/min/avg.

تعيين تسمية DTO

استخدم Snake_case (group_chat, agent_based) لـ YAML وcamelCase (groupChat, agentBased) لـ JSON API/DTO. تتحول المنصة تلقائيًا في كلا الاتجاهين، فلا داعي للقلق.

المزالق الشائعة

• إشارة إلى الخطوة التي لم يتم تشغيلها — إذا تخطى الشرط الخطوة الأولية، فستصبح المراجع النهائية إليه فارغة/غير محددة. استخدم | الافتراضي (...) لمعرفة ذلك.
• يتم توصيل الحقول الكبيرة مباشرة بالمهام — task: "{{steps.x.output}}" إذا كان الإخراج الأولي هو 100 كيلو بايت، فسوف تقوم LLM بتفجير الرمز المميز. قم أولاً بالاستخراج والضغط قبل الإرسال.
• YAML علامات الاقتباس في الداخل — يجب وضع التعبيرات التي تحتوي على نقطتين أو أحرف خاصة بين علامتي اقتباس مزدوجتين: condition: "{{x}} == 1"