“أين المستندات؟” إنه سؤال لا يستمتع أحد في فريق المنتج بالإجابة عليه. عادة ما يكون الرد الصادق نوعًا من “الخلف”. يحدق الكاتب في طلب سحب مغلق، محاولًا إجراء هندسة عكسية لما تغير. لقد انتقل مؤلف طلب السحب بالفعل. بحلول الوقت الذي يتم فيه نشر المستند فعليًا، يتم شحن الميزة، وأحيانًا أكثر من مرة.
لقد كنا في فريق Aspire (نحن فريق صغير مكون من 10 أدوات تطوير للتطبيقات الموزعة). قبل بضعة أشهر، كنا نحاول معرفة كيفية إدخال الذكاء الاصطناعي بأمان في عمليات التشغيل الآلي التي نثق بها بالفعل. وذلك عندما اكتشفنا سير عمل GitHub Agentic. لقد بدأت في دمج النماذج الأولية microsoft/aspire.
هذا ما حصلنا عليه، بالأرقام المأخوذة مباشرة من GitHub: بالنسبة لـ Aspire 13.3 و13.4، تم دمج 82 طلبًا لسحب المستندات المميزة بمتوسط 44.8 ساعة بعد طلب سحب المنتج، كل واحد منهم تمت مراجعته من قبل المهندس الذي قام بشحن الميزة. لا يوجد عدد جديد من الموظفين. لا توجد عملية إعادة التدريب. مجرد طريقة مختلفة لطرح السؤال “من يكتب هذا؟”
🔒 القيد: أتمتة عمليات الريبو المتقاطعة هي الجزء الصعب
منتجنا يعيش في microsoft/aspire ويعيش موقع المستندات الخاص بنا microsoft/aspire.dev– عمليات الريبو المختلفة ونشر الهدف وسلسلة المراجعة. تكتشف معظم الفرق أتمتة عمليات الريبو نفسها بسرعة كبيرة؛ أتمتة عمليات الريبو المتقاطعة هي المكان الذي تصبح فيه الأمور حادة. تنتمي الرموز المميزة واسعة النطاق إلى المتحف، وأي موقف أمني مسؤول (بما في ذلك موقفنا) يقيدها وفقًا لذلك. هذا شيء جيد. إنه أيضًا عنق الزجاجة الحقيقي إذا كان المكان الذي تكتب فيه المستندات ليس هو المكان الذي تكتب فيه الكود.
كان سير العمل الافتراضي لسنوات هو:
- يقوم المهندس بشحن ميزة في
microsoft/aspire. - يلاحظ كاتب المستندات بعد أسابيع.
- يفتح كاتب المستندات طلب السحب، ويقرأ الفرق، ويجري اختبار اتصال للمهندس لتوضيح ما تغير.
- المهندس موجود في الميزة التالية، يتذكر بشكل غامض، ويجيب بنصف الصورة.
- يتم شحن مشروع المستندات، أحيانًا ضد إصدار تم إصداره بالفعل.
هذه هي ضريبة الهندسة العكسية. كنا بحاجة إلى التشغيل الآلي الذي يتجاوز اتفاقيات إعادة الشراء دون تسليم الوكيل رمزًا مميزًا للكتابة في كل مكان. تبين أن سير عمل وكيل GitHub هو الحل.
🤖 لماذا سير عمل وكيل GitHub
يعد GitHub Agentic Workflows مشروعًا من فريق GitHub Next والذي أستمر في وصفه للناس باسم “إجراءات GitHub، ولكن مع نموذج كمعالج عنصر العمل وقضبان الحماية التي تستوفي المراجعة الأمنية.” وهذا اختزال، لكنه قريب.
شكلها:
- يمكنك تأليف سير عمل كـ ملف تخفيض السعر واحد (
.github/workflows/my-thing.md). واجهة أمامية على طراز YAML في الأعلى، وموجه باللغة الإنجليزية في الأسفل. - يمكنك تشغيل ترجمة GitHub Agentic Workflows، ويقوم بإنشاء شقيق
.lock.yml(سير عمل إجراءات GitHub العادي) الذي تلتزم به جنبًا إلى جنب. - في وقت التشغيل، يقوم سير العمل بتشغيل وكيل مقابل الموجه الخاص بك باستخدام مجموعة أدوات مقيدة.
- بشكل حاسم، الوكيل لا يكتب إلى GitHub مباشرة. إنها تبعث النية (كائن JSON blob الذي يصف طلبات السحب والمشكلات والتعليقات التي يريد إنشاءها)، ومهمة منفصلة ذات نطاق ضيق (الوظيفة معالج المخرجات الآمنة) يجسد هذه النية ضد تطبيق GitHub لكل سير عمل.
تلك الرصاصة الأخيرة هي الفتح. يحصل الوكيل على حق الوصول للقراءة ومطالبة. تمر عمليات الكتابة عبر خط أنابيب صغير يمكن التحقق منه مع قوائم السماح الواضحة. إيماءات المراجعة الأمنية. نحن نشحن.
💚 جانبا صغيرا: مداخن المشابهة
أحب أن يتم إنشاء الأدوات التي تستخدمها في البناء بنفس الأدوات التي تستخدمها في البناء. تم إنشاء مستندات سير عمل GitHub Agentic باستخدام Astro وStarlight. وكذلك aspire.dev—Astro مع Starlight، المجهز بالنظام البيئي الأوسع لمكونات Starlight (astro-mermaid، وstarlight-llms-txt، وstarlight-sidebar-topics، وstarlight-image-zoom، والموضوع الرائع @catppuccin/starlight، والمزيد. تحية لكريس سويثينبانك ومشرفي Starlight، يبدو أن النظام البيئي بأكمله مصمم من قبل أشخاص يهتمون حقًا).
هناك قرابة حقيقية هناك. الأداة التي نستخدمها لأتمتة المستندات وموقع المستندات الذي نقوم بأتمتة المستندات يشتركان في نفس الأساس. ملائم، لأن مخطط تسلسل حورية البحر في القسم التالي يعرض نفس الطريقة تمامًا في كلا العالمين.
خط الأنابيب من النهاية إلى النهاية
هذا هو التدفق الذي هبطنا عليه. بطل الرواية هو سير العمل يسمى pr-docs-check.md الذين يعيشون في microsoft/aspire.
يبدأ الجري يوم pull_request: closed ضد main أو release/*، ببوابة merged == true. من هناك، يقوم سير العمل أولاً بتشغيل محلل فرعي مستهدف محدد في نظام bash البسيط قبل أن يستيقظ الوكيل:
- سحب العنوان الرئيسي لطلب (على سبيل المثال 13.4 → الإصدار/13.4 on
aspire.dev). - عنوان الحدث الرئيسي للإصدار المرتبط (تحليل الإصلاحات/الإغلاق/الحل #N من النص، وجلب كل إصدار، واتخاذ أول حدث رئيسي غير فارغ).
- سحب المرجع الأساسي للطلب، إذا كان يطابق الإصدار/XY[.Z].
- العودة إلى الرئيسي.
هذا هو المحور. يتم تعيين المعالم الرئيسية في مستودع المنتج بشكل واضح لتحرير الفروع في المستندات الريبو. عندما يتم تشغيل الوكيل أخيرًا، فإنه يعرف بالضبط المكان الذي يجب أن تصل إليه المستندات دون أي كتابة إبداعية حول الفروع المستهدفة أو التخمين.
يقرأ الوكيل الاختلافات، ويفحص المشكلات المرتبطة، ويقرر: هل يحتاج هذا إلى مستندات؟ إذا كانت الإجابة بنعم، فإنه يقوم بصياغة المحتوى الفعلي في السحب microsoft/aspire.dev مساحة العمل، باتباع مهاراتنا الحالية في كتابة المستندات (الصوت، واتفاقيات MDX، ومكونات Starlight). ثم تنبعث أ create_pull_request الإخراج الآمن وارفعوا أيديكم.
يتولى معالج المخرجات الآمنة ما يلي:
- بادئة العنوان: [docs]
- التسمية: مستندات من الكود
- مسودة: صحيح (لا نقوم بالدمج التلقائي مطلقًا)
- الفرع الأساسي: مقدم من الوكيل، مقيد بـ
mainأوrelease/* - الريبو المستهدف:
microsoft/aspire.dev - المراجع : الشركات الصغيرة والمتوسطة التي تم تحديدها من طلب سحب المصدرمراجعات – على سبيل المثال، أي شخص يثق به فريق المنتج للموافقة على الميزة، يُطلب منه الآن الموافقة على المستند الخاص بهذه الميزة.
تقوم المهمة المصاحبة بنشر تعليق علامة مرة أخرى على طلب السحب المصدر باستخدام رابط طلب سحب المستندات وتقليل أي تعليق أقدم pr-docs-check تعليقات على إعادة التشغيل. المهندس الذي ضرب للتو دمج يتلقى إشعارًا في غضون بضع دقائق: “هذه هي مسودة المستندات. هل تبحث عنها؟”
🔐 عقد المخرجات الآمنة
القصة الأمنية بأكملها تعود إلى جزء صغير وممل من الموضوع الرئيسي:
tools:
github:
toolsets: [repos, issues, pull_requests]
min-integrity: approved # only run pinned, integrity-checked actions
allowed-repos:
- microsoft/*
github-app:
app-id: ${{ secrets.ASPIRE_BOT_APP_ID }}
private-key: ${{ secrets.ASPIRE_BOT_PRIVATE_KEY }}
owner: "microsoft"
repositories: ["aspire.dev", "aspire"]
safe-outputs:
create-pull-request:
title-prefix: "[docs] "
labels: [docs-from-code]
draft: true # human-in-the-loop, always
base-branch: main
allowed-base-branches: [main, release/*]
target-repo: "microsoft/aspire.dev"
protected-files: blocked # AGENTS.md, manifests, security config: hands off
fallback-as-issue: true هذه هي الصفقة في نص عادي. يحصل الوكيل على رمز تطبيق GitHub الذي تم تحديد نطاق تثبيته بالضبط اثنين من المستودعات– مستودع المنتج ومستودع المستندات – ولا يمكن الوصول إلى أي شيء آخر في المؤسسة. يمكنه فقط قبول طلبات السحب ضدها main أو release/*. AGENTS.md وبيانات التبعية محظورة بموجب السياسة. إذا فشل إنشاء طلب السحب (مشكلة في الشبكة، أو تعارض، أو أي شيء)، فسيعود إطار العمل إلى تقديم مشكلة، لذلك لا يتم إسقاط أي شيء بصمت.
هذا هو الجزء الذي أحببته المراجعة الأمنية بالفعل. منطق الوكيل غامض. سطح العمل ليس كذلك.
📊 بالأرقام
فيما يلي الإحصائيات من نافذة متجددة مدتها 30 يومًا (3 مايو – 2 يونيو 2026) يمتد إلى النهاية الخلفية لإصدار Aspire 13.3 والفترة التي تسبق الإصدار 13.4:
| متري | قيمة |
|---|---|
| تم دمج طلبات سحب المنتج في Microsoft/Aspire | 396 (338 إصدارًا رئيسيًا / 50 إصدارًا / 13.3 / 8 إصدارًا / 13.2) |
| يتم تشغيل سير العمل pr-docs-check | 396 |
| طلبات سحب مسودة المستندات التي تم إنشاؤها على microsoft/aspire.dev | 82 |
| – مدمج | 82 (100%) |
| – مغلق بدون دمج | 0 |
| – لا تزال مفتوحة | 0 |
| طلبات سحب المستندات تستهدف الفروع | 52 → الإصدار/13.3، 27 → الإصدار/13.4، 3 → رئيسي |
| متوسط الوقت اللازم للدمج (مستندات) | 44.8 ساعة |
| تم الدمج خلال 24 ساعة / 7 أيام | 38% / 96% |
ملحوظة: الأرقام التي تم التقاطها في وقت كتابة هذا التقرير؛ يستمر سير العمل في العمل، وبالتالي فإن الإجماليات ترتفع فقط.
بعض هذه الأرقام تستحق نظرة ثانية:
- 396 أشواط → 82 طلب سحب ليس عيبًا. يتم تشغيل سير العمل على كل طلب سحب مدمج؛ معظمها عبارة عن عمليات إعادة بناء داخلية أو إصلاحات اختبارية أو مطبات تبعية بدون سطح يواجه المستخدم. يعد الوكيل الذي يقول “لا حاجة إلى مستندات” أكثر من 300 مرة ميزة.
- معدل الدمج 100% يقول أن اختيارات مستندات الوكيل صحيحة. إن المطالبة الأكثر صرامة التي قمنا بشحنها بعد المرحلة الإيجابية الكاذبة v1 تؤتي ثمارها.
✅ ما نجح، ❌ ماذا فعل‘ر
ما نجح
- ✅ منعطف → رسم خرائط فرع الإصدار. كان هذا هو الخيار الوحيد ذو الرافعة المالية الأعلى الذي اتخذناه. لقد حدد المهندسون بالفعل معالم رئيسية فيما يتعلق بطلبات السحب والمشكلات؛ لقد حصلنا على توجيه دقيق للفرع المستهدف مجانًا.
- ✅ للمسودة فقط، للشركات الصغيرة والمتوسطة كمراجع. الوكيل لا يدمج أبدًا. المهندس الذي قام بشحن الميزة هو الذي يؤكد صحة المستندات. لقد أوقفنا ميزات الهندسة العكسية في طبقة المستند. يخبر المهندس مسودة المستندات فقط بما يجب قوله، في المكان الذي توجد فيه بالفعل.
- ✅ نطاق تطبيق GitHub لكل سير عمل. يحصل كل سير عمل على رمز التطبيق الخاص به مع نطاقات الريبو والأذونات الصريحة. تمت الموافقة على المراجعة الأمنية. لقد وافقنا أيضًا؛ في المرة الأولى التي احتجنا فيها إلى تدوير المفاتيح.
- ✅ الملفات المحمية: محظورة. لا يمكن للوكيل اللمس
AGENTS.mdأو بيانات الحزمة أو تكوين أمان الريبو. فترة.
ما لم (في البداية)
- ❌ سؤال الوكيل “هل هذه المستندات تستحق؟” كانت البوابة سخية جدًا في الإصدار الأول. لقد صاغ طلبات سحب للتغييرات التي كانت داخلية حقًا، مثل تعديل CI أو إعادة عامل التسجيل. النتيجة: 9 عمليات إغلاق لـ 69 طلب سحب (≈13%)، لذلك قمنا بتشديد تعريف التغيير الذي يواجه المستخدم وأضفنا أمثلة سلبية صريحة (CI، والمساعدون الداخليون، والاختبارات فقط). الآن، المعدل يتجه نحو الانخفاض.
- ❌ يلزم إنشاء طلب سحب عبر الريبو أ نمط الخروج معكوسة لم يكن ذلك واضحًا من المستندات. يعمل الوكيل في ريبو واحد؛ تحتاج المخرجات الآمنة إلى العثور على الريبو المستهدف لدفع الفرع. لقد حللناها عن طريق التحقق
microsoft/aspire.devمرتين — مرة واحدة كمساحة العمل الحالية، مرة واحدةunder _repos/aspire.dev– حتى يتمكن معالج المخرجات الآمنة من إعادة اكتشافها بشكل حتمي. - ❌ الفروقات الكبيرة تضرب الميزانيات السريعة. نحن نقوم باستخراج البيانات الوصفية لطلبات السحب مسبقًا (المشكلات المرتبطة، والمعالم الرئيسية، والمرجع الأساسي) في خطوات ما قبل الوكيل، بحيث يحصل الوكيل على ملخص صغير ومنظم بدلاً من حمولة ضخمة. هذا هو النمط المصمم لـ GitHub Agentic Workflow، وهو يعمل.
التفاف
التغييرات التي أجريناها غيرت تفكيرنا. لم يتم اعتبار الميزة منجزة حتى تم الانتهاء من المستندات. لم تعد المستندات تتبع خلفها مثل علبة من الصفيح على خيط. مراجعة المهندس هي البوابة؛ يقوم الروبوت بالكتابة.
بشكل حاسم، هذا لا يحل محل مؤلفي المستندات; فهو يخفف عنهم الأعباء. اعتاد كتابنا على قضاء معظم وقتهم في ميزات الهندسة العكسية. والآن يقضون وقتهم في الأشياء التي لا يستطيع القيام بها إلا الإنسان بشكل جيد: الصفحات السردية، ونماذج البرامج، والإرشادات المفاهيمية، وأجزاء المستندات التي لا تقع خارج نطاق الاختلاف. يتعامل الروبوت مع العمل الميكانيكي “تمت إضافة هذا الخيار الجديد؛ إليك تحديث الصفحة المرجعية” الذي لم يكن ممتعًا لأي شخص على الإطلاق.
شكرًا جزيلًا لفريق GitHub Next على سير عمل GitHub Agentic (ولجعل المخرجات الآمنة بدائية جزءًا من الدرجة الأولى من التصميم)، ولكريس سويثينبانك ومشرفي Starlight لمنصة المستندات التي نقوم بالأتمتة فيها. شكرًا جزيلًا أيضًا لرجال الأمن الذين أجبرتنا حواجز الحماية على تصميم هذا بالطريقة الصحيحة في المرة الأولى. السر الممل للأتمتة الجيدة هو أن القيود الأمنية القوية تجعل النظام أكثر جدارة بالثقة وأكثر صحة.
إذا قمت بإنشاء منتج في أحد مستودعات الريبو وأرسلت المستندات في مكان آخر – وخاصة إذا كان عليك القيام بذلك داخل أي حدود أمنية غير تافهة – فإن سير عمل GitHub Agentic Workflows يستحق نظرة جادة. ابدأ بسير عمل واحد، مثل pr-docs-check، وشاهد ما يحدث لمتوسط الوقت اللازم للمستندات.
🔗 سير العمل الأخرى
pr-docs-check هو الذي كتبت عنه هذا المنشور، لكنه لا يعمل بمفرده. إذا كنت مهتمًا بمعرفة الباقي، فالمصدر عام:
milestone-changelog.md: يتم تشغيله كل ساعتين، ويلتقط طلبات السحب المدمجة حديثًا في الحدث الرئيسي النشط، ويحتفظ بصفحة wiki 13.x-Change-log (ميزات جديدة، وتحسينات، وإصلاحات أخطاء ملحوظة) مع مشكلة تعليقات تحريرية مصاحبة. 346 أشواط.release-update-support-mdx.md: في إصدار ثابت من Aspire، المسودات أ [support] سحب الطلب علىaspire.devيقوم بتحديث صفحة سياسة الدعم (الترويج للإصدار الجديد، وخفض رتبة الإصدار السابق، وتحديث شارة “آخر تحديث”).update-integration-data.md: يعيش في مستندات الريبو؛ تشغيل تحديث pnpm: كل يوم، وتحديث البيانات التعريفية لـ NuGet + إحصائيات GitHub + نموذج البيانات، وفتح مهمة روتينية: تحديث بيانات التكامل (PR) باستخدام منطق الاستبدال والإغلاق لعمليات التشغيل التي لا معنى لها. 27 عملية تشغيل وثمانية طلبات سحب مدمجة.repo-pulse.md: لوحة تحكم ريبو متجددة لمدة ثلاثة أيام مثبتة على مشكلة واحدة ويتم تحديثها في مكانها: عمليات الدمج الأخيرة، وطلبات السحب في انتظار المراجعة، والقضايا الجديدة، ونشاط المناقشة. قضية واحدة، طازجة دائمًا.
أتمتة سعيدة يا أصدقاء! 🤖🚀
كتب بواسطة
