تقرير العميل الأسبوعي: يكتبه وكيل كل يوم اثنين قبل أن تستيقظ

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

الجزء الذي يحتاج إلى تفكير ليس الكود، بل تحديد ما يحتاج العميل إلى رؤيته فعلًا، والصدق بشأن ما تقيسه الأرقام.

ماذا يجب أن يتضمن تقرير التوزيع الأسبوعي؟

أربعة أقسام تكفي. وكل ما عداها مكانه المراجعة الشهرية.

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

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

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

استدعاءات البيانات

لكل مساحة عمل خاصة بعميل، يشغّل الوكيل هذا التسلسل. أسماء الأدوات هي أدوات MCP الحقيقية، ومقابلاتها في REST موجودة في مستند OpenAPI.

1. list_workspaces لتحديد مساحة عمل العميل بالاسم.
2. list_posts مع ضبط status على PUBLISHED، ثم مرة أخرى مع PARTIALLY_PUBLISHED وFAILED. يصل limit إلى 100.
3. get_post لكل منشور من الأسبوع، للحصول على الحالة في كل حساب والروابط المنشورة ورسائل الخطأ.
4. get_analytics مع from وto يغطيان الأسبوع.
5. list_channels، لربط معرّفات القنوات بأسماء حسابات مقروءة واكتشاف الحسابات التي تغيّرت حالة ربطها.

استدعاء التحليلات عبر REST:

curl -s "https://app.shager.ai/api/v1/workspaces/ws_example/analytics?from=2026-09-14T00:00:00%2B03:00&to=2026-09-20T23:59:59%2B03:00" \
  -H "Authorization: Bearer $SHAGER_READ_KEY"

في هذا الرابط تفصيلان يوقعان الناس في الخطأ. علامة + في فارق التوقيت يجب ترميزها بـ %2B في سلسلة الاستعلام، وإلا قرأها الخادم مسافة. وحدود الأسبوع يجب حسابها وفق المنطقة الزمنية للعميل، لا للخادم. وإن أُغفل from، فإن get_analytics يعتمد افتراضيًا آخر 30 يومًا، وهذا ليس ما يريده تقرير أسبوعي.

النقرات ليست عملاء محتملين، فاربط بينهما

يمنح Shager كل حساب رابطًا قصيرًا خاصًا به ووسوم UTM، حيث يميّز utm_content الحساب. وهذا ما يجعل الربط ممكنًا. يسجّل نظام CRM العملاء المحتملين مع قيم UTM الملتقطة من نموذج صفحة الهبوط، ويطابقها الوكيل مع أعداد النقرات لكل حساب في Shager عبر قيمة utm_content نفسها.

والجدول الناتج هو قلب التقرير:

الحساب	المنشورات	النقرات (Shager)	العملاء المحتملون (CRM)	ملاحظة
Aurora Downtown	4	...	...
Aurora Northside	4	...	...	تلزم إعادة الربط

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

وإن لم يكن لديك وصول إلى CRM، فالتقرير يعمل بالنقرات وحدها. اذكر ذلك في رأس التقرير. فالتقرير الذي يسمّي النقرات «نتائج» هو الطريق الذي تخسر به الوكالات الثقة بعد ربع سنة.

تشغيله دون إشراف عبر Claude Code

يمكن تشغيل Claude Code بشكل غير تفاعلي عبر claude -p، كما تشرح وثائق التشغيل دون واجهة. وهذا يحوّل التقرير الأسبوعي إلى مهمة cron.

أولًا، مجلد مشروع للتقارير فيه ملف .mcp.json يقرأ المفتاح من البيئة. تدعم وثائق MCP في Claude Code توسيع ${VAR} داخل الترويسات:

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

ثم التعليمات، محفوظة كمهارة كي يعيش المنطق في ملف واحد لا في سطر داخل crontab. يحمّل Claude Code مهارات المشروع من .claude/skills/<name>/SKILL.md، وفق وثائق المهارات:

---
name: weekly-report
description: Compile the weekly distribution report for one client workspace from Shager. Use when asked for a weekly client report.
---

The argument is the client workspace name: $ARGUMENTS

1. Resolve the workspace with list_workspaces. Read its timezone.
2. Compute last Monday 00:00 to Sunday 23:59:59 in that timezone, with offsets.
3. Collect posts with list_posts (PUBLISHED, PARTIALLY_PUBLISHED, FAILED) and
   keep those published in the window. Call get_post for each.
4. Call get_analytics for the window. Map channel ids to names with list_channels.
5. If crm/<workspace>.csv exists, join leads on utm_content.
6. Write reports/<workspace>/<YYYY-MM-DD>.md with four sections: Delivery,
   Clicks by account, Clicks by post, Actions. Use tables. No adjectives about
   performance; numbers and one plain sentence per section.
7. Never call any tool that creates, schedules or cancels anything.

ثم الأمر المجدول، الذي يوافق مسبقًا على أدوات القراءة وكتابة الملفات فقط:

cd ~/agency-reports && claude -p "/weekly-report Aurora" \
  --allowedTools "mcp__shager__list_*,mcp__shager__get_*,mcp__shager__whoami,Write" \
  --output-format json > logs/aurora-$(date +%F).json

صيغة قواعد السماح ذات البادئة mcp__<server>__ والنجمة في آخرها موثقة في مرجع الصلاحيات في Claude Code. وأي أداة ليست في هذه القائمة لن تُعتمد تلقائيًا في تشغيل دون إشراف.

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

لماذا يهم مفتاح القراءة فقط هنا

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

ويظهر كل استدعاء يجريه وكيل التقارير أيضًا في سجل التدقيق على اللوحة نفسها، وهي طريقة جيدة للتأكد في أيام الاثنين الأولى من أنه يستدعي ما تتوقعه ولا شيء غيره.

كتابة الجزء السردي

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

أسئلة شائعة

هل يستطيع الوكيل إرسال التقرير إلى العميل مباشرة؟

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

هل يتضمن get_analytics العملاء المحتملين؟

لا. فهو يعيد النقرات على روابط Shager المُتتبَّعة، لكل حساب ولكل منشور، ضمن نطاق زمني. أما العملاء المحتملون فيأتون من CRM العميل أو من أداة النماذج لديه، ويُطابَقون عبر utm_content. ويجب أن يُبقي التقرير المصدرين منفصلين بوضوح.

إلى أي مدى يمكن أن يعود التقرير إلى الوراء؟

يقبل get_analytics أي قيمتين from وto ترسلهما، مع افتراض آخر 30 يومًا حين يُغفل from. وللمقارنة من شهر إلى شهر، شغّل المهارة نفسها بنافذة مختلفة بدلًا من الاعتماد على التقارير السابقة المحفوظة مصدرًا للحقيقة.

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

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