يصف مستودع AI Software Factory مسارًا يبدأ بغرض المنتج ومهمة وينتهي بطلب دمج ينشئه Archon. التثبيت وفحوص سير العمل مجرد بداية. يذكر المشرف في دليل الساعة الأولى أن التحقق الفعلي من العملية كاملة ما زال مطلوبًا. يتبع هذا الدليل تعديل المصنع 9e2d85298b45497031009597a6ae0811b66fe6d6 وإصدار Archon المثبت fad09169ea1b43512bc7ee88470d47f960a3e0f8 . وهو قراءة للوثائق والشيفرة، وليس تقريرًا عن تثبيت أو تشغيل أجرته BIG CHANGE.

المسار لفريق يتحكم بمستودع تطبيق أو PRD، وصلاحيات GitHub وحساب مزود النماذج. يوثق القائم على المشروع صراحة استنساخ المصنع وتثبيته في مستودعك الخاص. لا تتضمن شجرة المصنع المحددة ملف ترخيص أو إشعار؛ ولا يثبت هذا الدليل حقوقاً أوسع لإعادة الاستخدام أو التوزيع. ينطبق ترخيص Archon من نوع MIT على مصدر Archon المنفصل. لا تضع أسرار المزود في نصوص المهام أو التعليمات أو السجلات أو محاضر المراجعة.

التغيير الكبير

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

1. فحص المستودع والصلاحيات والمصدر المحدد

تتطلب تعليمات إعداد المشرف Git وPython 3.10 أو أحدث، و gh موثقًا بنطاق workflow ، ومستودع GitHub بعيدًا، ووكيل برمجة، وBun وuv. يجب أن يستطيع Git كذلك دفع ملفات سير العمل ( gh auth setup-git ). قبل تشغيل الوكيل، افحص أوامر الاختبار والبدء وCI الموجودة، وحماية الفروع، والوصول إلى GitHub، وتوثيق المزود وفوترة النماذج. امنح فقط صلاحيات المستودع وسير العمل اللازمة.

استنسخ المصنع خارج مستودع التطبيق وانتقل إلى التعديل المحدد. يُشغّل أمر التثبيت الموثق من جذر التطبيق:

Terminal
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init

استخدم python3 عند الحاجة. ينسخ المثبّت قوالب المصنع والمشروع ويثبت مصدر Archon المذكور في pack.json. يحدد كل من README والحزمة في هذا التعديل الإصدار fad09169ea1b43512bc7ee88470d47f960a3e0f8 . لا يوثق المثبّت مزودًا، ولا يختار مستويات النماذج، ولا يبدأ جدولًا. افحص تغييرات الملفات قبل قبولها في مستودعك.

اضبط المزود المختار ومعرّفات النماذج المدعومة بحسب إرشادات Archon المثبتة. ضع أوامر التحليل الساكن واختبارات الوحدات الفعلية في harness/harness.config.json . عندما يتعذر على GitHub إرجاع حماية الفروع، حدد وظائف CI المطلوبة للدمج في required_checks . راجع protected_paths كي تتطلب تغييرات الغرض وإطار التحقق وسياسة المصنع تدخل إنسان. يترك القالب أوامر الفحص العادية و required_checks فارغة؛ نسخه وحده لا ينشئ بوابة قبول صالحة.

2. كتابة الغرض والفحوص للمنتج الموجود

اكتب في MISSION.md غرض المنتج وحدوده الصارمة وطلبات معقولة خارج النطاق. صف في harness/END-TO-END.md من رحلتين إلى خمس رحلات مستخدم يكملها التطبيق الحالي فعلًا، مع الفائدة التي يراها المستخدم. رحلة تعتمد على ميزة لم تُبنَ ستعطل التسليم الأول. اكتب في .factory/holdout/HOLDOUT.md حالات منفصلة تجمع سلوكيات أو تختبر الحدود. اسم المجلد لا يخفيها عن مطور له وصول إلى نسخة العمل نفسها؛ ضع الحالات الخاصة فعلًا خارج النسخة ولا تعطها إلا لمرحلة التحقق.

للمستودع الذي يحتوي PRD فقط، يطلب README اشتقاق الغرض والرحلات المقصودة وأوامر التحقق من الوثيقة. يجب أن تجعل المهمة الأولى المقترحة المنتج قابلًا للتشغيل وتذكر أمر البدء ومسارات الصحة وهوية البناء والاختبارات وCI. راجع الاقتراح قبل السماح بنشر المهام.

حوّل الرحلات إلى مدخلات السيناريو التي تتوقعها مسارات تشغيل Archon. اتبع الملف المثبت factory/RUNTIME_HOST.md لإعداد لقطة للتطبيق من التعديل المسلّم، وحالة جديدة، وفحوص الصحة وهوية البناء، وأوامر بدء Python أو Node المسموحة. المضيف الموثق لا يدير قواعد بيانات بعيدة أو حاويات أو موارد سحابية بوصفها موارد تشغيل يملك إدارتها. التطبيق الذي يستخدمها يحتاج ترتيب تحقق مبررًا على نحو منفصل؛ نجاح فحص المضيف المحلي لا يثبت عزلها.

قبل الاعتماد على المقيّم، أنشئ خط أساس ناجحًا يختبر قيمة حقيقية للمستخدم، وأظهر أن عيبًا متعمدًا مناسبًا يفشل، وتأكد أن هوية مرشح خاطئة تعيد حكمًا غير حاسم. يعطي دليل المضيف مدخلات مجموعة الاختبارات والحقول الدقيقة المتوقعة، ومنها expectations_passed: true و baseline_verified: true . احتفظ بالاستجابة الأصلية الفعلية وهوية المرشح كدليل. لا يكفي اختبار تحميل الصفحة فقط أو اختبار يجهز الحالة النهائية مباشرة.

3. فحص التثبيت ثم اختيار مهمة واحدة

شغّل من جذر التطبيق:

Terminal
python factory/consumer.py doctor
python factory/consumer.py list

doctor يفحص المصدر المحدد وقدرات الأوامر ومسارات العمل المتاحة. ويعرض list المسارات المكتشفة. لا يثبت أي منهما قدرة المزود على إنهاء المهمة، أو نجاح CI، أو تشغيل التطبيق. أصلح الإخفاقات المبلغ عنها قبل التسليم، واترك الجدولة معطلة.

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

Terminal
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json

استبدل الرابط بمهمة تتحكم بها. يمنع discovery_publication=preview الصريح نشر الاكتشافات المرتبطة بالمراجعة كمهام؛ وإلا يستخدم المسار المحدد archon-ship القيمة الافتراضية auto . استخدم archon-lifecycle فقط بعد تجهيز سيناريو التشغيل ومدخلات الاختبارات المحجوزة. مرر المهمة كـ target والمسارات كـ scenario و holdout ، مع merge_mode=approve و discovery_publication=preview . قدم كذلك merge_method معتمدًا للمشروع: merge أو squash أو rebase . مثلًا لا تستخدم merge_method=squash إلا إذا سمح المستودع. يتضمن المسار التحقق أثناء التشغيل والاختبارات المحجوزة، والإصلاح وبوابة الدمج. يحتفظ وضع الموافقة بقرار إنسان قبل الدمج؛ علامة جاهزية المسار ليست ذلك القرار. خيار مضيف المصنع الموثق --runtime-host يعمل في المقدمة فقط ولا يجتمع مع --detach أو --resume .

لـPRD، أمر قائمة الأعمال الموثق هو:

Terminal
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve

استبدل docs/PRD.md الموضوع بين علامات اقتباس بمسار PRD الفعلي نسبة إلى نسخة عمل التطبيق. راجع المهام المقترحة وترتيبها قبل النشر. اضبط مضيف التشغيل بحسب طريقة بدء التطبيق وعقد الهوية المعلنين في المهمة الأولى، ثم نفذها عبر archon-lifecycle بالرحلات والاختبارات المحجوزة الجاهزة. افحص المهمة الأولى بعناية تساوي عناية المهام التالية.

4. تقييم الفروق والنتيجة العاملة قبل الموافقة

احتفظ بمعرّف التشغيل المعاد. يوفر برنامج التحكم get <run-id> --json --events و status --all --json لمتابعة التقدم والأدلة. قارن المهمة والخطة بـ MISSION.md ؛ اقرأ الفروق الفعلية لطلب الدمج والمراجعة المستقلة لأحدث نسخة؛ افحص نتائج CI اللازمة وتقرير المسارات المحمية. شغّل رحلات المنتج على النسخة المسلمة وافحص النتائج الأصلية للتشغيل والاختبارات المحجوزة، بما فيها هوية المرشح. قارن نتيجة المستخدم المرصودة بمعايير القبول. ينبغي للمراجع إعادة الطلب الناقص للإصلاح؛ يصف README الأمر archon-deliver --adopt <run id> لتسليم محتجز في طابور الدمج.

لا يوافق على الدمج بعد نجاح الفحوص إلا إنسان مخوّل في المستودع. يحتاج النشر التشغيلي أوامر خاصة بالمشروع للنشر والصحة والهوية، ثم قراءة تؤكد النسخة بعد النشر؛ دمج الطلب وحده لا يثبت نشره. أبقِ الجدولة معطلة طوال المهمة الأولى وقرر بصورة منفصلة إن كنت ستفعّل تشغيلًا متكررًا.

لا تحدد إرشادات التكلفة للمشرف سعرًا ثابتًا للتشغيل. تنصح بقياس الرموز منذ اليوم الأول ومراقبة استدعاءات النموذج في مهمة صغيرة قبل تفعيل حلقة. الرسوم تعتمد على المزود والنماذج وشروط الحساب. لم تقس BIG CHANGE إنفاق هذا المصنع.

يحتاج التشغيل النشط قرار إيقاف صريحًا أيضًا. في شيفرة التحكم، يمنع halt الإطلاقات الجديدة والاستكمالات، فيما يستهدف cancel <run-id> العمل النشط. يوقف pause إطلاقات المؤقت لكنه يسمح بإيقاظ العمل الجاري. لا يغني أي أمر عن فحص حالة التشغيل الحالية وتغييرات المستودع البعيد.

المصادر والقراءة الإضافية