دع وكلاء الذكاء الاصطناعي يديرون لوحتك عبر REST API: المصادقة والنطاقات والكتابة الآمنة

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

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

نموذج المصادقة، بوضوح

يصادق Taskfolk طلبات الـ API برمز حامل (bearer token). تنشئ مفتاح API، ويحمل كل طلب هذا المفتاح في الترويسة Authorization: Bearer <key>. لا رقصة OAuth لوكيل يعمل من خادم إلى خادم، ولا كوكي جلسة، ولا كلمة مرور.

curl https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues \
  -H "Authorization: Bearer tfk_live_XxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx"

المفتاح سلسلة نصية، ومن يحملها يتصرف باسمها. هذا هو النموذج بأكمله، ومعناه أن القرارات المهمة تدور حول ما يُسمح للمفتاح بفعله، لا حول طريقة تقديمه.

هناك أمران عن المفتاح يستحقان الترسيخ قبل أن تسلّمه لوكيل.

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

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

تُنشئ المفاتيح من إعدادات المطورين في مساحة العمل، والواجهة كاملة موثقة في /developer. يظهر المفتاح مرة واحدة عند الإنشاء؛ خزّنه في مدير الأسرار، لا في المستودع.

النطاقات: اقرأ بسخاء، واكتب بتقتير

تأتي نطاقات Taskfolk على شكلين. هناك نطاقات أب عريضة (read وwrite وadmin) ونطاقات دقيقة لكل مورد (issues:read وissues:write وcomments:write وlabels:write وغيرها). نطاق الكتابة الدقيق يتضمن نطاق القراءة المقابل، فـ issues:write يحمل معه issues:read تلقائيًا. أما write العريض فيتفرع إلى نطاقات الكتابة بمستوى العضو عبر الموارد.

وهنا القرار التصميمي الذي يهم الوكلاء: نطاق write العريض لا يشمل عمدًا عمليات الكتابة الإدارية. تعديل إعدادات مساحة العمل، إدارة الأعضاء، إدارة النماذج وقواعد الأتمتة، تدوير مفاتيح API، ربط الـ Webhooks: لا شيء من هذا يركب مع write. كلها لا تُطال إلا عبر النطاق الدقيق الصريح (workspaces:write وmembers:write وأشباهها) أو عبر نطاق admin العريض.

flowchart TD
    W[write scope] --> I[issues:write]
    W --> C[comments:write]
    W --> L[labels:write]
    AD[admin scope] --> T[admin tier writes]
    T --> WS[workspaces:write]
    T --> M[members:write]
    W -. never reaches .-> T

هذا مقصود. مفتاح يستطيع تسجيل الأخطاء يجب ألا يكون على بعد حقنة تعليمات واحدة من تعديل فوترتك أو سك مفاتيح جديدة.

فكّر إذًا في وظيفة الوكيل وقيّده عليها بالضبط:

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

قاوم غريزة منح admin «حتى يشتغل». المفتاح الموسّع أكثر من اللازم هو أشيع طريقة يتحول بها دمج وكيل إلى حادثة أمنية. إذا عاد استدعاء بخطأ forbidden فهذا نظام النطاقات يؤدي عمله؛ وسّع النطاق الواحد الذي تسميه نقطة النهاية، لا المنحة كلها.

نقل بطاقة وتسجيل مهمة

سطح الكتابة يتبع شكل المنتج: مساحات العمل تحتوي مشاريع، والمشاريع تحتوي مهام. لإنشاء مهمة ترسل POST إلى مجموعة مهام المشروع مع نطاق issues:write:

curl -X POST https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues \
  -H "Authorization: Bearer $TASKFOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "bug",
    "title": "Checkout button unresponsive on Safari",
    "priority": "high",
    "labels": ["triage"]
  }'

لنقل بطاقة، ترسل PATCH إلى المهمة وتغيّر حالتها. طلب الـ PATCH دمج جزئي (sparse merge)، فترسل الحقول التي تريد تغييرها فقط وتترك الباقي كما هو. نقل WEB-42 من قيد التنفيذ إلى قيد المراجعة هو PATCH صغير واحد يضبط الحالة، ولا شيء آخر في المهمة يُمس.

curl -X PATCH https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues/WEB-42 \
  -H "Authorization: Bearer $TASKFOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status": "in_review"}'

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues/WEB-42",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TASKFOLK_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ status: "in_review" }),
  }
);
const issue = await res.json();

import os, uuid, requests

res = requests.patch(
    "https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues/WEB-42",
    headers={
        "Authorization": f"Bearer {os.environ['TASKFOLK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"status": "in_review"},
)
issue = res.json()

سلوك الدمج الجزئي هذا ميزة أمان صامتة. وكيل ينوي تغيير حقل واحد لا يستطيع بالخطأ مسح وصف أو إعادة إسناد مالك لمجرد أنه نسي تضمين تلك الحقول في جسم الطلب. يرسل الفرق، ويحفظ الخادم الباقي.

دورة كاملة من القراءة فالتنفيذ فالتحقق على السلك:

sequenceDiagram
    participant A as Agent
    participant U as Taskfolk REST API
    A->>U: GET .../issues?status=... (issues:read)
    U-->>A: the column, as JSON
    A->>U: PATCH .../issues/WEB-42 with the status delta + Idempotency-Key
    U-->>A: the updated record, validated on write
    A->>U: retry after a timeout, same Idempotency-Key
    U-->>A: same result, no duplicate card

المجموعة الكاملة من العمليات (نحو 150 عملية عبر المهام والتعليقات والوسوم والحقول المخصصة والعروض المحفوظة والمستندات والنماذج وقواعد الأتمتة وغيرها) مسرودة في مرجع الـ API. وإن كنت لا تزال تفاضل بين استدعاء REST مباشرة وتشغيل الوكيل عبر خادم MCP، فقد كتبنا مقالة مستقلة عن الاختيار بين MCP وREST API؛ هذا الدليل يفترض أنك تستدعي REST.

كتابة آمنة: عدم التكرار ليس خيارًا مع الوكلاء

البشر يضغطون الزر مرة واحدة. الوكلاء يعيدون المحاولة. انقطاع شبكة عابر، مهلة انتهت، إطار عمل يعيد تشغيل خطوة فاشلة: أي من هذه يمكن أن يرسل استدعاء «أنشئ مهمة» نفسه مرتين، وبلا حماية تحصل على بطاقتين متطابقتين. يعالج Taskfolk هذا بمفتاح idempotency.

أرفق ترويسة Idempotency-Key بأي طلب يعدّل البيانات. هي سلسلة تختارها أنت (UUID لكل عملية منطقية يفي بالغرض). أول طلب بمفتاح معيّن ينفّذ المعالج ويخزّن الاستجابة مؤقتًا. وإعادة المحاولة بالمفتاح نفسه والجسم نفسه تعيد الاستجابة المخزنة بدل التنفيذ من جديد، فيقع الإنشاء مرة واحدة مهما كرره الوكيل. نافذة الإعادة 24 ساعة.

هناك حالتان حديّتان تستحقان المعرفة لأنهما تظهران في حلقات الوكلاء الفعلية:

ترسل	تستلم	المعنى
المفتاح نفسه، الجسم نفسه	الاستجابة المخزنة، معادة	إعادة محاولة آمنة؛ الكتابة نُفذت مرة واحدة
المفتاح نفسه، جسم مختلف	409 idempotency_violation	توليد مفاتيحك معطوب؛ عمليتان تشاركتا مفتاحًا واحدًا
المفتاح نفسه والطلب الأول ما زال جاريًا	409 conflict	الطلب الأصلي ما زال يعمل؛ انتظر ثم أعد المحاولة

كلا الخطأين 409 ميزة. فهما يحوّلان صنفًا من أخطاء التكرار الصامتة إلى أخطاء صاخبة يمكن التقاطها.

القاعدة العملية: ولّد مفتاح idempotency واحدًا لكل فعل مقصود، وضعه على كل كتابة، وتعامل مع 409 بوصفه إشارة إلى منطق إعادة المحاولة عندك، لا خطأً عابرًا تضرب عليه حتى يمر.

حدود المعدل والإبطال

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

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

حد صريح أو اثنان

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

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

جاهز للتجربة؟ افتح إعدادات المطورين لإنشاء مفتاح مقيّد بنطاقات، وأبقِ مرجع الـ API بجوار محررك وأنت تركّب الوصلة.