مفاتيح API للوكلاء: قراءة وكتابة ونشر، وسجل تدقيق ستراجعه فعلًا

امنح كل وكيل أضيق مفتاح في Shager يغطي مهمته: read للتقارير، وwrite للصياغة، وpublish فقط للخطوة التي تجدول المنشورات. احفظ المفاتيح في متغيرات البيئة أو في إعدادات عميل MCP، ولا تضعها أبدًا في التعليمات. ألغِ المفاتيح ودوّرها من لوحة الوكلاء، واقرأ سجل التدقيق فيها، الذي يسرد كل استدعاء يجريه الوكيل، مرة في الأسبوع على الأقل ما دام الوكيل جديدًا.

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

ماذا تتيح كل صلاحية؟

يحمل كل مفتاح في Shager صلاحية واحدة أو أكثر من ثلاث. وكل عملية في الـ API تعلن الصلاحية التي تحتاج إليها، ويمكنك رؤيتها في الحقل x-scope لكل عملية في مستند OpenAPI. أدوات MCP هي العمليات نفسها، فتنطبق القواعد نفسها عبر MCP.

الصلاحية	العمليات
read	whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics
write	create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post
publish	schedule_post

أمران في هذا الجدول يستحقان الانتباه.

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

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

المفتاح الذي يُستخدم من دون الصلاحية المطلوبة يتلقى خطأ بالشكل المعتاد، { "error": { "code", "message" } }، مع HTTP 403. على الوكلاء أن يبلغوا عن هذا الخطأ بدل البحث عن طريق للالتفاف عليه، ويجب أن تنص تعليماتك الدائمة على ذلك.

مرّر جانبيًا لرؤية المخطط كاملًا

من أين تأتي المفاتيح

هناك طريقان.

إنسان ينشئ المفتاح من app.shager.ai/dashboard/agents ويختار الصلاحيات. هذا هو الطريق المعتاد لوكالة تضيف وكيلًا إلى حساب قائم.

الوكيل يسجّل نفسه. الوكيل الذي لا يملك حسابًا يستدعي POST https://app.shager.ai/api/v1/agent/signup مع agent_name، ويُستحسن أن يضيف contact_email للإنسان المسؤول عنه. يتلقى api_key يظهر مرة واحدة فقط، وclaim_url. يعمل هذا المفتاح فورًا في بيئة اختبار تستطيع إنشاء حتى خمس مساحات عمل، ورفع الوسائط، وإنشاء المسودات، والقراءة. لكنه لا يستطيع الجدولة أو النشر، ولا إنشاء روابط الربط للعملاء، ولا إرسال طلبات الموافقة.

curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Northwind content agent (Claude Code)",
       "contact_email":"ops@northwind-agency.example",
       "purpose":"Draft weekly posts for 3 retail clients"}'

لا تُرفع هذه القيود إلا حين يفتح إنسان claim_url، ويسجّل الدخول، ويتولى ملكية المؤسسة. في تلك اللحظة يقرر الإنسان هل يحصل مفتاح الوكيل على publish أيضًا. وإن لم يتولَّ أحد الملكية، تنتهي صلاحية بيئة الاختبار بعد سبعة أيام. الوصفة الكاملة منشورة في /auth.md، والشرح خطوة بخطوة في التسجيل الذاتي للوكيل وتولّي الملكية.

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

كيف يحفظ الوكلاء المفاتيح ويرسلونها؟

مفاتيح Shager رموز حامل (bearer tokens) تُرسل بصيغة Authorization: Bearer shgr_live_.... والخاصية الجوهرية لرمز الحامل، كما يصوغها RFC 6750، أن أي طرف يملكه يستطيع استخدامه. لا شيء آخر يثبت الهوية. فالمهمة كلها هي ألا يتسرب.

عمليًا:

1. متغيرات البيئة، يُشار إليها من الإعدادات. يدعم Claude Code التوسيع ${VAR} في ترويسات .mcp.json، بحسب وثائق MCP الخاصة به. يمكن إيداع الملف في المستودع، ويبقى المفتاح في البيئة.
2. لا مفاتيح في التعليمات أبدًا. المفتاح الملصق في المحادثة ينتهي في السجلات والنصوص المحفوظة، وأحيانًا في محادثات مشتركة.
3. لا مفاتيح في مجلد العميل أبدًا. إن كنت تحتفظ بمجلدات سياق لكل عميل، فالمفاتيح لا مكان لها فيها. هذه المجلدات تُشارَك وتُضغط وتُرسل.
4. مفتاح لكل دور من أدوار الوكيل. مهمة التقارير ووكيل الصياغة وخطوة الجدولة لا ينبغي أن تتشارك مفتاحًا. وحين يتسرب أحدها، تلغي مفتاحًا واحدًا.

{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
    }
  }
}

يقبل خادم MCP الخاص بـ Shager ترويسة مفتاح API هذه. أما العملاء الذين يتصلون بتسجيل الدخول عبر OAuth بدلًا منها، مثل الموصل المخصص في Claude أو ChatGPT، فيحصلون على القدر نفسه من التحكم: يوافق شخص على الاتصال في شاشة الموافقة في Shager، والنشر خانة منفصلة متوقفة افتراضيًا، ويظهر الاتصال في سجل التدقيق نفسه. ويشرح مقال Shager وChatGPT خطوات الإعداد في ChatGPT.

تدوير المفاتيح من دون انقطاع

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

1. أنشئ مفتاحًا جديدًا بالصلاحيات نفسها من لوحة التحكم.
2. حدّث متغير البيئة حيث يعمل الوكيل.
3. شغّل whoami بالمفتاح الجديد للتأكد من أنه يعمل ويُظهر الصلاحيات المتوقعة.
4. ألغِ المفتاح القديم.

يسري الإلغاء على كل استدعاء يُجرى بذلك المفتاح، عبر MCP وREST على حد سواء.

مرّر جانبيًا لرؤية المخطط كاملًا

حدود المعدل جزء من الأمان

كل مفتاح محدود بـ 120 طلبًا في الدقيقة. الوكيل حسن التصرف لا يقترب من هذا الحد أبدًا: مسودة أسبوعية كاملة لعميل لا تتجاوز بضع عشرات من الاستدعاءات. وحين يصطدم وكيل بـ HTTP 429، فالأمر يعني عادةً حلقة مفرغة، وكيلًا يعيد الاستدعاء الفاشل نفسه مرة بعد مرة. يجب أن تتعامل تعليماتك مع 429 كإشارة توقف، لا كسبب لإعادة المحاولة بسرعة أكبر. تراجَع، وأبلِغ، ودع إنسانًا يلقي نظرة.

قراءة سجل التدقيق

تعرض لوحة الوكلاء سجل تدقيق بكل استدعاء يجريه الوكلاء. ولا فائدة منه إلا إذا قرأه أحد. ما الذي تبحث عنه في الأسابيع الأولى مع وكيل جديد:

1. استدعاءات لم تتوقعها. وكيل تقارير يستدعي create_post يعني أن تعليماته أو مفتاحه خطأ.
2. انحراف مساحة العمل. استدعاءات تمس عميلًا لا علاقة للمهمة به. هذا هو الإنذار المبكر للخطأ بين العملاء الذي نناقشه في وكيل واحد وعملاء كثيرون.
3. دفعات من الأخطاء. تكرار 403 يعني أن الوكيل يواصل محاولة شيء خارج صلاحيته. أصلِح التعليمات، لا الصلاحية.

بعد بضعة أسابيع خالية من المشكلات، تكفي نظرة سريعة أسبوعية.

الأسئلة الشائعة

هل ينبغي أن يملك الوكيل صلاحية النشر في أي وقت؟

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

ماذا يحدث لمفتاح الوكيل حين تُتولّى ملكية بيئة الاختبار؟

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

هل يمكن قصر مفتاح على مساحة عمل عميل واحد؟

الصلاحيات تحدد ما يستطيع المفتاح فعله، لا مساحة العمل التي يعمل فيها. افصل العملاء عبر مساحات العمل، وسياق خاص بكل عميل، وعادة تحديد مساحة العمل بالاسم قبل كل عملية كتابة، واستخدم مفاتيح منفصلة لكل دور كي يبقى الإلغاء دقيقًا.

إلى أين بعد ذلك

إن كنت تُعدّ وكيلك الأول، فإن نقطة دخول الوكلاء تعرض الطريقين للحصول على مفتاح. ابدأ بمفتاح write، ولا تضف publish إلا حين تستحق المسودات ذلك.