الوحدة 10 — مشروع: فريق تحرير وثائقيّ

نجمع في هذه الوحدة كلّ ما تعلّمناه في مشروع كامل: تسليم وثيقة منتَج من عشر صفحات، جاهزة للمراجعة البشريّة والنشر. سنقيس الجودة، ونقارن ثلاثة حلول (فريقنا، وكيل واحد، كاتب بشريّ)، ونستخلص متى تستحقّ المقاربة التوظيف الفعليّ.

المدخلات والمخرَج المطلوب

المدخلات: ملفّ Markdown من 40 صفحة يصف مواصفات منتَج SaaS جديد (نظام إدارة مشاريع). يحوي: قائمة وظائف، فئات مستخدمين، متطلّبات وظيفيّة، قيود تقنيّة.

المخرَج: وثيقة عرض للمنتَج من ~10 صفحات (~5 000 كلمة)، بأسلوب رسميّ، تُقدَّم للعملاء المحتملين. تشمل: وصف موجز، الوظائف الرئيسيّة، حالات استخدام، مقارنة مع منافسَين، أسعار، أسئلة متكرّرة.

البنية الكاملة للفريق

from crewai import Agent, Task, Crew, Process
from crewai_tools import FileReadTool, SerperDevTool
from langchain_openai import ChatOpenAI

llm_lourd = ChatOpenAI(model="gpt-4o", temperature=0.2)
llm_ecrit = ChatOpenAI(model="gpt-4o", temperature=0.4)
llm_leger = ChatOpenAI(model="gpt-4o-mini", temperature=0)

analyste = Agent(
    role="محلّل مواصفات منتَج",
    goal="استخراج الوظائف والفئات وحالات الاستخدام من المواصفات",
    backstory="مهندس منتَج بخبرة عشر سنوات في تحليل SaaS",
    llm=llm_lourd,
    tools=[FileReadTool(file_path="./specs.md")],
    max_iter=6,
    allow_delegation=False,
    verbose=True,
)

redacteur = Agent(
    role="محرّر عرض منتَج",
    goal="كتابة وثيقة عشر صفحات بأسلوب رسميّ للعملاء",
    backstory="محرّر توثيقات لواجهات برمجيّة عامّة منذ 2015",
    llm=llm_ecrit,
    tools=[SerperDevTool()],
    max_iter=8,
    allow_delegation=False,
)

relecteur = Agent(
    role="مراجِع تقنيّ ولغويّ",
    goal="التحقّق من الاتّساق والدقّة، وإصدار قائمة تصحيحات مُرقَّمة",
    backstory="مراجِع لغويّ لفرق توثيق منذ سبع سنوات",
    llm=llm_lourd,
    tools=[FileReadTool(file_path="./guide-style.md")],
    max_iter=5,
    allow_delegation=False,
)

responsable = Agent(
    role="مسؤول التحرير",
    goal="إصدار قرار نهائيّ ونشر الوثيقة إن كانت جاهزة",
    backstory="مدير توثيق يوازن آراء الفريق ويقرّر التسليم",
    llm=llm_leger,
    max_iter=6,
    allow_delegation=True,
)

المهامّ الأربع

t1 = Task(
    description="اقرأ specs.md واستخرج قائمة الوظائف والفئات وحالات الاستخدام.",
    expected_output="ملفّ Markdown مُهيكَل، 10 إلى 15 وظيفة، حالة استخدام لكلّ منها.",
    agent=analyste,
    output_file="./out/analyse.md",
)

t2 = Task(
    description="اكتب وثيقة العرض من التحليل. غطِّ الأقسام الستّة المطلوبة.",
    expected_output="ملفّ Markdown ~5000 كلمة، عناوين مستوى ثانٍ لكلّ قسم.",
    agent=redacteur,
    context=[t1],
    output_file="./out/vue-produit-brouillon.md",
)

t3 = Task(
    description=(
        "راجع الوثيقة المكتوبة. تحقّق من الاتّساق مع التحليل، "
        "من الدقّة اللغويّة، ومن احترام دليل الأسلوب."
    ),
    expected_output="قائمة تصحيحات مُرقَّمة؛ إن كانت الوثيقة سليمة، اذكر ذلك صراحةً.",
    agent=relecteur,
    context=[t1, t2],
    output_file="./out/relecture.md",
)

t4 = Task(
    description=(
        "اقرأ التصحيحات، طبّق الجوهريّة منها، وأصدِر النسخة النهائيّة. "
        "إن كانت التصحيحات كثيرة، فوّض جولة إعادة كتابة للمحرِّر."
    ),
    expected_output="النسخة النهائيّة الجاهزة للتسليم، Markdown ~5000 كلمة.",
    agent=responsable,
    context=[t1, t2, t3],
    output_file="./out/vue-produit-final.md",
    human_input=True,  # نقطة تحقّق بشريّة أخيرة
)

equipe = Crew(
    agents=[analyste, redacteur, relecteur, responsable],
    tasks=[t1, t2, t3, t4],
    process=Process.sequential,
    memory=True,
    embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},
    verbose=False,
)

resultat = equipe.kickoff()

تقييم الجودة

قيّمنا الوثيقة الناتجة عبر ثلاثة مراجعين بشريّين مستقلّين، على شبكة من ستّة أبعاد (كلّ منها من 10):

البعد	فريق CrewAI	وكيل واحد	كاتب بشريّ (يوم عمل)
اكتمال المحتوى	8.7	6.9	9.4
الدقّة التقنيّة	8.1	7.5	9.1
الأسلوب والنبرة	7.9	7.2	9.2
البنية والتنظيم	9.0	6.5	8.6
الأخطاء اللغويّة	8.8	7.8	9.7
إجمالي (متوسّط)	8.4	7.2	9.2

قراءة:

• الفريق يتفوّق على الوكيل الوحيد في كلّ الأبعاد، بأثر أكبر في «البنية والتنظيم» و«اكتمال المحتوى» (المراجِع يفرض هيكلًا).
• الكاتب البشريّ يبقى الأفضل في «الأسلوب والنبرة» و«الأخطاء اللغويّة» — كما هو متوقّع.
• الفارق بين الفريق والبشر ~0.8 نقطة، مقابل فارق ساعات مقابل يوم عمل. المقايضة مغرية على الوثائق المتكرّرة.

الكلفة النهائيّة

المؤشّر	فريق CrewAI	وكيل واحد	كاتب بشريّ
الزمن	~90 ثانية	~35 ثانية	6 إلى 8 ساعات
الكلفة النقديّة	0.55 د.أ	0.22 د.أ	~350 د.أ
مراجعة بشريّة	30 دقيقة	60 دقيقة	15 دقيقة
الكلفة الفعليّة (مراجعة×50 د.أ/س)	~25 د.أ	~50 د.أ	~360 د.أ

الاستنتاج: على وثيقة تُنتَج مرّة كلّ أسبوعَين، فريق CrewAI يوفّر ~90٪ مقابل كاتب بشريّ، بجودة مقبولة بعد مراجعة قصيرة.

قرارات الإنتاج

• متى نُشغّل الفريق: عند وصول مواصفات جديدة من فريق المنتَج، تلقائيًّا عبر خطّاف Git.
• نقطة التحقّق البشريّة: human_input=True على المهمّة الأخيرة، مراجَعة من مدير التوثيق.
• إعادة التنفيذ: إن رفض المدير، تُعاد الجولة الأخيرة فقط عبر إعادة تنفيذ t4 بتصحيحات جديدة في inputs.
• مراقبة الفاتورة: تنبيه إن تجاوز التنفيذ 1.0 د.أ (يعني أنّ شيئًا انحرف).
• المحرِّر البشريّ: يبقى مسؤولًا عن التسليم النهائيّ ولا يُستبدَل. الفريق يُختصر أسبوعًا من العمل، لا يُلغي المراجعة.

توسيعات محتملة

• تعدّد اللغات: إضافة وكيل «مترجم» يُخرج النسختَين الفرنسيّة والإنجليزيّة بعد الاعتماد.
• وكيل «مصمّم بصريّ»: يقترح مواقع الصور والرسومات في الوثيقة (بلا توليدها).
• دمج مع أدوات النشر: أداة تُنشر الوثيقة تلقائيًّا على Notion أو Confluence بعد الموافقة.
• جولة اختبار A/B: تشغيل نسختَين بلمسات أسلوب مختلفة، وقياس أيّهما يُقنع العملاء أكثر.

حدود المشروع

هذا فريق تحرير للوثائق، لا لـ«كلّ شيء». حاول تشغيله على مهمّة بعيدة عن التوثيق (كتابة عقد قانونيّ، تحليل ماليّ) وستفشل: أدوار غير مناسبة، ومخرَج متوقّع غير محدّد. كلّ فريق CrewAI يُبنى لحالة استخدام محدّدة.

الخلاصة

• فريق تتابعيّ من أربعة وكلاء يُنتج وثيقة ~5000 كلمة في ~90 ثانية بكلفة ~0.55 د.أ.
• الجودة المُقاسة (8.4/10) أعلى بوضوح من وكيل وحيد (7.2/10) وأقلّ بلمسة من بشر (9.2/10).
• التسليم الفعليّ يبقى تحت مراجعة بشريّة قصيرة عبر human_input=True؛ لا نشر تلقائيّ.
• الفريق مُصمَّم لحالة استخدام محدّدة (توثيق منتَج)؛ إعادة توظيفه على مهمّة مختلفة تتطلّب إعادة تصميم شاملة.