Public Artifact Sharing (Public HTTPS Links)

If your workflow generates a report (.md /.html /xlsx /.pdf) and wants to send it to others, the most direct way is to let the Slack/mail module upload the file attachment. ولكن الملفات الكبيرة ستكون بطيئة، وعادة ما يكون لمنصات التراسل حدود على حجم ملف واحد وعدد الملحقات.

المشاركة الصناعية العامة وهو طريق آخر: نشر قطعة أثرية واحدة كوصلة قصيرة من طراز HTTPS، وإرسال الرابط فقط في رسالة، وفتحه مباشرة - ويبقى الملف نفسه على الخادم، الذي يحفظ عرض النطاق الترددي ويسمح للمصفوفين بفحصه مباشرة (يمكن إرساله إلى HTML على شبكة الإنترنت). لتقاسم العديد من الملفات في آن واحد، يمكنك أيضا نشر دليل الأثرية بأكمله كوصلة واحدة، انظر "وصلات عامة على مستوى المحرك" أدناه.

متى تستخدمه

• ويتعين إرسال التقارير/اللوحات إلى سلاك/فيشو/البريد الإلكتروني، ولا أريد من الجميع أن ينقذوا كل واحد من هذه التقارير.
• تحتاج أن يطّلع متعاون خارجي (بلا حساب على المنصة) على لقطة بيانات من app store
• تشارك خلاصة ‎.md مؤقتًا مع عميل ليقرأها كـ HTML مباشرة في متصفح الهاتف
• تريد للرابط وقت انتهاء أو حدًا للتنزيلات أو حماية بكلمة مرور

طريقة الاستخدام — من الواجهة

1. افتح execution منتهيًا وانتقل إلى تبويب المخرجات؛ ستجد زر 🔗 مشاركة بجانب كل مخرَج
2. انقر 🔗 مشاركة لفتح مربع حوار المشاركة
3. المصادرة حسب الحاجة:
   • نطاق الوصول: الجمهور (العجز)/كلمة السر/الفريق/أعضاء محددين؛ انظر: نطاق القبول وطلبات الدخول
   • مدة الحياة: لا تنتهي أبداً (العجز) ساعة واحدة/ 24 ساعة/ 7 أيام/ 30 يوماً؛ تذكر خيارك الأخير
   • حد التنزيلات: 0 = بلا حد، >0 = يتعطل الرابط تلقائيًا بعد الاستنفاد
   • كلمة المرور (أسلوب كلمة السر): يحفز المركب على كلمة سر عندما تُفتح الرابط
   • عرض HTML عبر الإنترنت (خاص بـ .md): عند التحديد يعرض الرابط HTML منسقًا بدل تنزيل ملف ‎.md المصدر
4. قم بـ "ربطة الجينات" واحصل على "يور إل" مثل "الـ "برايدرون

طريقة الاستخدام — النشر التلقائي داخل سير العمل (موصى به)

وبعد تنفيذ سير العمل، يُحوَّل المنتج تلقائياً إلى وصلة عامة، ثم يُدفع الرابط تلقائياً إلى سلاك - ولا يلزم أن تتقاسم العملية بكاملها أي نقرات يدوية.

تنسيق نموذجي من ثلاث خطوات

1. تُكتب خطوة إنتاج المخرَج كالمعتاد دون أي وسم خاص — مثلاً:

   - step: build_report
     agent: reporter
     input: |
       生成今天的业务报表,写入 /tmp/.../daily.md。
     # 这一步完成后,引擎自动注册一个产物(execution 的 artifacts 列表里会出现)

2. صِل وحدة artifact publish المدمجة ومرّر اسم الخطوة السابقة `from_step: build_report`. تستعلم الوحدة تلقائيًا عن قائمة مخرجات الـ execution وتجد ملف تلك الخطوة وتنشئ الرابط العام:

   - step: share_report
     sub_workflow:
       name: dingyue-module-artifact-publish
       inputs:
         from_step: "build_report"          # ← 唯一必需字段:引用上一步的步骤名
         ttl_minutes: "0"                   # 永不过期；如需限时可改成分钟数
         render_markdown_as_html: "true"    # .md 直接在线 HTML 预览
       # base_url / api_token 不用填 —— 引擎自动注入运行时访问令牌
       outputs:
         share_url: public_url              # 下游可以用 {{var:share_url}} 引用
     depends_on: [build_report]

3. ثم صِل وحدة تسليم Slack المدمجة ومرّر public_url ← يستقبل Slack رسالة نصية مع رابط فقط دون رفع ملف:

   - step: notify
     sub_workflow:
       name: dingyue-module-slack-deliver
       inputs:
         slack_webhook_url: "{{var:slack_webhook_url}}"
         message_text: "📊 今日报表已生成"
         public_url: "{{var:share_url}}"   # ← 复用 share_report 的输出
     depends_on: [share_report]

ماذا لو تعددت المخرجات

إذا أنتجت خطوة build_report عدة ملفات (مثل daily.md وmetrics.json معًا)، رشّح بـ artifact_name:

- step: share_report
  sub_workflow:
    name: dingyue-module-artifact-publish
    inputs:
      from_step: "build_report"
      artifact_name: "daily.md"            # ← 精确挑选
      ttl_minutes: "0"
    outputs:
      share_url: public_url

بدون artifact_name تأخذ الوحدة أول مخرَج مطابق وتذكر في السجل عدد غير المستخدمة.

وصلات عمومية على مستوى الدليل: URL لتقاسم دليل الأثر الأثري بأكمله

الوصلة الوحيدة يمكن أن تشارك فقط قطعة أثرية واحدة في وقت واحد. إذا أسفر تنفيذ واحد عن مجموعة من الملفات (تقرير + بيانات + صور، أو حتى موقع ثابت متعدد الصفحات كامل)، يمكنك نشر الدليل الأثري بأكمله كصلة واحدة:

• على حساب التنفيذ تفاصيل "القطع الأثرية" نقر "حلق جميع القطع الأثرية" لتوليد وصلة دليلية تغطي جميع القطع الأثرية لهذا تنفيذ؛ والخيارات (نطاق الوصول/العمر/حصة التنزيل/كلمة السر) هي نفسها بالنسبة لملف واحد
• ويمكن للمبادرة أيضاً أن تشارك القطع الأثرية لخطوة واحدة. لتقاسم كل شيء POST /api/executions/{id}/directory-public-link; to share a single step: POST /api/executions/{id}/steps/{stepName}/directory-public-link
• الرابط يبدو كما يلي: https://braidrun.com/p/d/hN2kQ9.../، والزوار لا يحتاجون إلى حساب (في النظام العام)

ما يراه الزوار

• عن طريق التقصير، صفحة قائمة الملفات: اسم الملف، الحجم، والنوع، بالإضافة إلى عمر الرابط وحصة تحميل
• عندما يكون هناك فهرس html في الجذر الدليلي، يفتح كموقع ثابت - تقرير متعدد الصفحات من HTML ينتج عن تدفق العمل يمكن تقاسمه في موقع كامل؛ إضافة؟
• وعندما يُمكّن من إصدار المعلومات على شبكة الإنترنت، تُعرض الملفات المدمجة في الدليل على أنها مُشكّلة بنظام HTML
• الملفات في الدليل تُرسل دائماً من خلال المنبر مع المحتوى الصحيح (لا عن طريق إعادة توجيه 302 إلى تخزين الجسم)، لذا يمكن للمتصفح أن يجعل HTML / CSS/ JS بشكل سليم
• مجموعة التحميل تتراكم عبر الدليل بأكمله والصلة تنتهي تلقائياً بمجرد أن تستخدم

نطاق الوصول وطلبات الوصول

وتتقاسم الروابط والوصلات الدليلية ذات نطاق الوصول:

في طريقة الفريق أو الأعضاء المحددة، تصبح الرابط "ربطة عميقة مطلوبة".

تدفق طلب الوصول (اختياري في شكل فريق أو نمط معين من الأعضاء):

1. عند إنشاء الرابط، تحققوا من "المستعملون الموقعون" لتقديم طلب عندما يفتقرون إلى الوصول"
2. الزائر الذي لا يستطيع الوصول يفتح الرابط، يملأ استمارة الطلب في صفحة "لا دخول"
3. المساهم أو مدير الرابط يوافق على/يرفض تحت "الحساب /التقاسم" قبل الموافقة، يؤكد الشخص الذي ينتمي بالفعل إلى الفريق المختار
4. وبعد الموافقة، يضاف الشخص إلى قائمة الدخول ويمكنه فتح الصلة الأصلية مباشرة

وصلات الدليل الإداري

• "الحساب management Share management" يُدير وصلات منفردة ودليلية معاً: تغيير نطاق الوصول، تغيير الحياة، الإلغاء،
• وفيما يلي بيان موجز الأداء الإداري المناظر - القائمة/التحديث/الإلغاء: GET /api/directory-public-links · PATCH /api/directory-public-links/{token} · DELETE /api/directory-public-links/{token}
• الصانع هو مدير الوصلة عن طريق التقصير، ويمكنه أن يسمي مديرين إضافيين ليتعاملوا معا مع طلبات الدخول والإلغاءات

أساليب التقاسم المدعومة

أما الجدول الوارد أعلاه فيتعلق بوصلات وحيدة الوجوه؛ فالوصلات الدليلية دائماً ما تكون مرتكزاً إلى مجرى الملفات، وبالتالي فهي تعمل في أي شكل من أشكال النشر.

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

• الرموز غير قابلة للتعداد —— SecureRandom بطول 24 بايت ← base62 ≈ 143 بت إنتروبيا؛ المسح بالقوة الغاشمة غير مجدٍ
• الحماية من فهرسة الزواحف —— ترويسات الاستجابة X-Robots-Tag: noindex, nofollow + Referrer-Policy: no-referrer؛ لن يفهرس Google/Bing الروابط
• تحديد المعدل —— طبقة البوابة: ١٠ مرات في الثانية لنفس الشريحة، ٢٠ انفجارا؛ طبقة الخدمة: الحد الصلب استنادا إلى حمولات الأكسيد القصوى
• حماية بكلمة مرور (اختياري) —— Argon2id hashing; the browser prompts on access, and script clients use the Authorization: Basic or X-Artifact-Password header. The password is not placed in the URL query string, to keep it out of access logs
• سجلات التدقيق —— كل إنشاء / وصول / إبطال يكتب سجل audit_log يتضمن IP العميل وUser-Agent والطابع الزمني
• متوافق مع GDPR —— عند حذف الحساب تُنظَّف كل الروابط تعاقبيًا؛ وعند تصدير البيانات يُضمَّن artifact_public_links.jsonl في ملف ZIP
• إبطال فوري —— النقر على «إبطال» في صفحة إدارة المشاركة يسري فورًا؛ الروابط المُبطلة تعيد 410 Gone (وليس 404، لتجنب الخلط مع «غير موجود»)

إدارة الروابط المشارَكة

من «الحساب ← إدارة المشاركة» (أو مباشرة GET /api/public-links) ترى كل الروابط التي أنشأتها وعدّاد الوصول وحالة الإبطال. النقر على زر الإبطال يعطّل الرابط فورًا.

FAQ

س: لماذا يعرض الرابط 410 Gone؟

• انتهت صلاحية الرابط (انقضت مدة السريان)
• أُبطل الرابط من قبل منشئه أو مسؤول
• وقد بلغ عدد عمليات التنزيل حده (تنتهي الصلة تلقائياً بمجرد استخدام الحصة)
• كلمة السر كانت خاطئة (قبل أن تدخلي واحدة، سترى كلمة المرور الخاصة بـ(بروسر) بسرعة بدلاً من 410)

س: هل يمكن جعل الرابط بلا انتهاء صلاحية؟

نعم، لكن الواجهة ستطلب تأكيدًا ثانيًا — الرابط الدائم يعني أن أي شخص لديه الرابط يمكنه الوصول للأبد ما لم تُبطله يدويًا، فتوخَّ الحذر. يمكن للمسؤولين تعطيل الروابط الدائمة عالميًا عبر BRAIDRUN_PUBLIC_LINK_REJECT_PERMANENT=true.

س: هل تُفهرس محركات البحث الروابط؟

لا. تفرض الترويسات noindex وnofollow، وتضيف طبقة nginx ترويسة أخرى. لكن إن لصقت الرابط في صفحة عامة فقد تكتشف الزواحف الخارجية العنوان — لذا لا تنشر هذه الروابط أبدًا في GitHub README أو مقالات المدونات.

س: ما حجم الملف المناسب؟

في نمط تخزين الجسم: غير محدود نظريا؛ في الواقع محدود من قبل مُستشفي المُستخدم (عادة عشرات من الـ (إم بي ليست مشكلة In local disk mode: limited by the platform file reading speed, it is not recommended to exceed 100MB.

س: إذا حذفت الـ execution الخاص بالمخرَج، هل يظل الرابط القديم صالحًا؟

لا. عند حذف execution يُبطل النظام تعاقبيًا كل الروابط المشيرة إليه؛ وتعيد الزيارات اللاحقة 410 Gone.

س: هل هذه الميزة مفعّلة افتراضيًا؟

يجب أن يفعّلها المسؤول صراحةً عبر متغير البيئة BRAIDRUN_PUBLIC_BASE_URL؛ وبدونها لا يظهر زر المشاركة في الواجهة. راجع PRODUCTION_GUIDE §2.4 في وثائق التشغيل.