وكيلان وباكلوج واحد: تنسيق وكيل فرز ووكيل برمجة عبر حالة المهمة كوسيلة تسليم

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

الإجابة المغرية هي بناء طابور رسائل، أو جعل الوكيلين يستدعي أحدهما الآخر، أو الاحتفاظ بحالة مشتركة في قناة جانبية. لا تحتاج إلى أي من ذلك. أداة تتبع المهام تملك أصلًا وسيلة تسليم جاهزة أمام عينيك: حالة المهمة. حين يحرّك الوكيل "أ" مهمة من عمود إلى العمود التالي، فتلك الحركة هي الرسالة. الوكيل "ب" يراقب المهام في عموده ويلتقطها. لا شيء آخر يحتاج إلى تنسيقهما.

هذا نمط تركّبه بنفسك من ميزات يشحنها Taskfolk أصلًا، لا زر "اربط وكيلين". ويستحق العناء حين تكون لديك فعلًا وظيفتان متمايزتان تريد فصلهما. إن كان وكيل واحد يستطيع إنجاز كل شيء، فأبقه وكيلًا واحدًا. لكن حين يصبح الفرز والإصلاح همّين منفصلين حقًا، تكون أعمدة الحالة أنظف سلك بينهما.

لماذا تصلح الحالة وسيلة تسليم

تغيير الحالة يملك ثلاث خصائص تجعله ناقل رسائل جيدًا، ومعظم أنظمة التنسيق المرتجلة تفتقد واحدة منها على الأقل.

إنه دائم. الحالة تعيش في قاعدة البيانات لا في ذاكرة وكيل. إذا انهار وكيل البرمجة في منتصف عمله، تبقى المهمة جالسة في عمودها حين يعيد الوكيل التشغيل. لا شيء يضيع في قناة لم توجد إلا ما دامت عملية ما تعمل.

إنه قابل للملاحظة. يستطيع أي إنسان فتح اللوحة ورؤية موضع كل مهمة بالضبط. وهذا أهم مما يبدو. حين يمرر وكيلان العمل بينهما، فإن نمط الفشل الذي تخشاه هو الانحراف الصامت: شيء صُنّف خطأً قبل ثلاث خطوات ولم يلحظ أحد. مع اللوحة، يكون التكدس مرئيًا. إذا تراكمت أربعون مهمة في عمود واحد، تراها بلمحة وتذهب لتعرف السبب.

إنه مصدر الحقيقة أصلًا. في Taskfolk، الحقل issues.status هو العمود الفقري الدلالي الذي يحدد هل المهمة مفتوحة، ومتى حُلّت، وكيف تظهر في التقارير. أنت لا تخترع آلة حالات موازية يمكن أن تنحرف عن الحقيقية؛ التسليم والحقيقة هما الحقل نفسه.

صمّم الأعمدة بوصفها البروتوكول

أعمدة لوحة Taskfolk قابلة للتخصيص (STATUS-CUSTOM-01). كل مشروع يحصل على أعمدة مسمّاة وملوّنة ومرتّبة، وكل عمود يُربط بواحدة من سبع فئات حالة ثابتة (backlog, todo, in progress, in review, done, failed, cancelled). الفئة هي الوعاء الدلالي؛ والعمود هو الاسم المقروء الذي تمنحه إياه. هذا الفصل هو ما يتيح لك تشكيل الأعمدة حول سير عملك دون كسر التقارير.

لإعداد وكيلين، رتّب الأعمدة على شكل خط أنابيب وعامل كل عمود كصندوق بريد لمن يملك تلك المرحلة:

العمود	الفئة	صندوق بريد مَن
الوارد (Inbox)	backlog	وكيل الفرز. كل مهمة جديدة تهبط هنا.
مصنّفة (Classified)	todo	إنسان. ينقل وكيل الفرز المهمة إلى هنا بعد ضبط النوع والأولوية والمشروع والتسميات.
جاهزة للبرمجة (Ready to code)	todo	وكيل البرمجة. نقلها إنسان إلى هنا بعد نظرة.
قيد التنفيذ (In progress)	in progress	لا أحد. وكيل البرمجة يحجز المهمة بنقلها إلى هنا، فلا يخطفها عامل ثانٍ.
قيد المراجعة (In review)	in review	إنسان. نقلها وكيل البرمجة إلى هنا حين فتح طلب سحب.
منجزة / فاشلة (Done / Failed)	done / failed	نهائية.

اقرأ الجدول من أعلى إلى أسفل وستتضح الحركة كلها. لكل وكيل عمود واحد بالضبط يسحب منه وعمود واحد يدفع إليه. والإنسان يجلس في الفجوتين اللتين تحتاجان إلى حكم بشري. لا أحد مضطر إلى سؤال أحد؛ موضع البطاقة هو الحوار كله.

خط الأنابيب كاملًا، مع من يحرّك كل بطاقة:

flowchart TD
    I[Inbox] -->|"triage agent"| C[Classified]
    C -->|"a human, after a look"| RC["Ready to code"]
    RC -->|"coding agent claims it"| P["In progress"]
    P -->|"coding agent opens a PR"| R["In review"]
    R -->|"a human"| D[Done]
    R -->|"a human"| F[Failed]

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

اجعل الحركات الخاطئة مستحيلة

خطر خط الأنابيب أن يحرّك وكيل مهمة إلى حيث لا ينبغي. وكيل الفرز لا يجوز أن يشحن الأشياء مباشرة إلى "منجزة"، ووكيل البرمجة لا يجوز أن يعيد تصنيف مهمة ويردّها إلى الوارد.

يملك Taskfolk قواعد انتقال لهذا بالضبط (WORKFLOW-01). كل عمود يستطيع إعلان الأعمدة التي يُسمح للمهمة بالانتقال إليها تاليًا، محفوظة في allowed_transitions. اتركها فارغة فتُسمح كل حركة، وهذا هو الافتراضي. اضبطها، فيرفض سير العمل أي حركة ليست في القائمة. القاعدة تُفرض على كل مسار يكتب حالة، بما في ذلك API العام وخادم MCP، فلا يستطيع وكيل الالتفاف عليها باستدعاء نقطة نهاية مختلفة.

اضبط الانتقالات لتطابق خط الأنابيب أعلاه فتتوقف الأعمدة عن كونها اقتراحات وتصبح آلة حالات حقيقية:

• الوارد لا يذهب إلا إلى مصنّفة.
• مصنّفة لا تذهب إلا إلى جاهزة للبرمجة (وذلك بيد إنسان).
• جاهزة للبرمجة لا تذهب إلا إلى قيد التنفيذ.
• وهكذا نزولًا على الخط.

إذا حاول وكيل البرمجة دفع شيء عائدًا إلى الوارد، تُرفض الكتابة برسالة مقروءة، وتجد الخلل في منطق الوكيل بدل أن تجده بعد أسبوع في لوحة متشابكة.

هناك حارس ثانٍ يستحق الضبط: حد WIP لكل عمود. أعط "قيد التنفيذ" حدًا من ثلاث مثلًا، فلا يستطيع وكيل البرمجة سحب مهمة رابعة وثلاث منها في الطريق. هذا يمنع وكيلًا منفلتًا من حجز الباكلوج كله دفعة واحدة، ويطابق طريقة إدارتك لفريق حقيقي.

اربط الوكيلين

كل وكيل يحتاج إلى أمرين: إيجاد المهام في عموده، وتحريك ما ينهيه. وكلاهما يمر عبر الواجهة نفسها التي يستخدمها الإنسان، لكن برمجيًا. وجّه كل وكيل إلى REST API أو خادم MCP، أيهما يناسب طريقة بناء الوكيل.

أولًا، اجلب أعمدة المشروع مرة واحدة ليعرف كل وكيل قيمة status_id لصندوق بريده:

curl -s https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/statuses \
  -H "Authorization: Bearer $TASKFOLK_API_KEY"

للعثور على العمل، اعرض المهام مرشّحة بالفئة ثم طابق العمود على جهة العميل. كل مهمة في الاستجابة تحمل status_id وstatus_name، وهذا ما يميّز "مصنّفة" عن "جاهزة للبرمجة" حين تُربط كلتاهما بالفئة todo:

curl -s "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues?status=todo" \
  -H "Authorization: Bearer $TASKFOLK_API_KEY"

الحركة نفسها نداء PATCH. تمرير status_id يستهدف عمودًا محددًا؛ وتستنتج الأداة الفئة، وتفحص قواعد الانتقال، وتكتب سطر النشاط. هذا وكيل البرمجة يحجز WEB-12، بصيغة curl:

curl -s -X PATCH https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues/WEB-12 \
  -H "Authorization: Bearer $TASKFOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status_id": "<id of In progress>"}'

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues/WEB-12",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TASKFOLK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ status_id: inProgressId }),
  },
);
const issue = await res.json();

import os
import requests

res = requests.patch(
    "https://taskfolk.ai/api/v1/workspaces/taskfolk/projects/WEB/issues/WEB-12",
    headers={"Authorization": f"Bearer {os.environ['TASKFOLK_API_KEY']}"},
    json={"status_id": in_progress_id},
)
issue = res.json()

توجد أيضًا نقطة نهاية مخصصة للانتقال، POST /api/v1/workspaces/{slug}/projects/{key}/issues/{KEY-N}/transition، تأخذ فئة الحالة مع ترتيب اختياري لإعادة التموضع؛ وهي تحاكي سحب البطاقة على اللوحة. لهذا النمط، يبقى PATCH مع status_id الأداة الأدق لأنه يسمّي العمود بالضبط.

ولأن قواعد الانتقال وحدود WIP تعيش في أداة التتبع لا في الوكيل، يبقى كود الوكيل صغيرًا: اقرأ عمودي، نفّذ، قدّم للأمام. ولا يحتاج إلى معرفة أن بقية خط الأنابيب موجودة أصلًا.

امنح كل وكيل مفتاح API خاصًا محدود النطاق. وكيل الفرز يحتاج إلى قراءة المهام وتعديل حقولها؛ ولا يحتاج إلى إغلاق السبرنتات أو تغيير إعدادات المشروع. ووكيل البرمجة يحتاج إلى تحريك المهام والتعليق؛ ولا يحتاج إلى إعادة التصنيف. المفاتيح الضيقة تعني أن الوكيل الذي يسيء التصرف لا يسيء إلا داخل مساره، وتستطيع إلغاء أحدهما دون لمس الآخر. هذه النصيحة نفسها من مقالنا عن MCP مقابل REST API: اقرأ بسخاء، واكتب بضيق، ومفتاح لكل وكيل.

الحركة عبر الزمن، واللوحة السطح المشترك الوحيد:

sequenceDiagram
    participant T as Triage agent
    participant B as The board
    participant H as A human
    participant C as Coding agent
    Note over B: new issue lands in Inbox
    T->>B: read Inbox, classify, set fields
    T->>B: move to Classified
    H->>B: sanity check, move to Ready to code
    B->>C: automation pings the coding agent
    C->>B: claim it, move to In progress
    C->>B: open a PR, move to In review
    H->>B: approve to Done, or send to Failed

دع قواعد الأتمتة تتولى الحركات المملة

بعض هذه الحركة لا يحتاج إلى وكيل أصلًا. أتمتة سير العمل في Taskfolk تشغّل قاعدة "WHEN يحدث هذا، IF تحققت هذه الشروط، THEN افعل هذا" على أحداث المهام، فيمكن للتوجيه البديهي أن يجري وحده.

قاعدتان تناسبان إعداد الوكيلين. WHEN تُنشأ مهمة، IF جاءت عبر نموذج استقبال عام، THEN أسقطها في عمود وارد وكيل الفرز وأضف تسمية incoming. وWHEN تتغير حالة مهمة إلى قيد المراجعة، THEN انشر تعليقًا يشير إلى المُبلِّغ ليعرف إنسان أن عليه النظر. وكيل البرمجة لا يحتاج إلى تذكّر إخطار أحد؛ الأتمتة تنطلق من تغيير الحالة الذي أجراه الوكيل أصلًا.

الخط الذي أرسمه: دع الأتمتة تتولى الحركات الميكانيكية البحتة التي لا حكم فيها، واترك كل ما يتطلب قراءة المهمة لوكيل أو شخص. الأتمتة بارعة في "أضف هذه التسمية دائمًا" ورديئة في "قرر هل هذه مهمة مكررة".

الحدود الصريحة

هذا ليس دفعًا (push). الوكلاء يستطلعون أعمدتهم على فترات؛ لا وجود لحضور لحظي أو تدفق أحداث يوقظ الوكيل لحظة هبوط البطاقة. لحلقة فرز وإصلاح تعمل بإيقاع الدقائق، الاستطلاع كافٍ. أما إن احتجت إلى رد فعل دون الثانية، فليس هذا هو الحل.

وأنت أيضًا من يركّب هذا بنفسه. يمنحك Taskfolk الأجزاء (أعمدة مخصصة، قواعد انتقال، حدود WIP، قواعد أتمتة، وAPI وخادم MCP)، لكن لا يوجد قالب يطبع لك خط أنابيب لوكيلين. أنت تصمم الأعمدة، وتضبط الانتقالات، وتكتب حلقتي الوكيلين الصغيرتين. هذا إعداد أكثر من نقرة زر، وهذه هي الحالة الصادقة للميزة اليوم.

وأبقِ إنسانًا في الحلقة ريثما تبني الثقة. عمود المراجعة موجود ليلتقط شخص تصنيفًا سيئًا قبل أن يتحول إلى كود سيئ. وبعد أن تراقب الخط يعمل نظيفًا مدة كافية، قرر كم من المنتصف تريد أتمتته. ابدأ حذرًا.

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

إن أردت تجربتها، فالقطع موجودة في كل مشروع: أضف أعمدة خط الأنابيب من اللوحة، واضبط الانتقالات وحدود WIP في إعدادات المشروع، ووجّه وكلاءك إلى API. انظر وثائق المطوّرين للمفاتيح ونقاط النهاية.