إعداد Grok Bot في Cursor

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

ما هو Grok Bot؟

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

المكونات الأساسية لإعداد Grok Bot هي:

• الروتينات: تسلسلات من الإجراءات ينفذها البوت عند تشغيله
• المشغلات: أحداث تبدأ روتيناً، مثل رسالة Slack أو استدعاء Webhook
• عناوين URL لـ Webhook: عناوين نقاط النهاية التي ترسل إليها الخدمات الخارجية البيانات
• الإجراءات: خطوات فردية داخل روتين، مثل تعديلات الملفات أو أوامر الطرفية أو استدعاءات API

تلميح

قبل إعداد Grok Bot، تأكد من أن تثبيت Cursor محدث. تتلقى ميزات روتين Webhook تحسينات متكررة، وقد لا تدعم الإصدارات الأقدم جميع أنواع المشغلات الموضحة في هذا الدليل.

التكوين الأولي

تمكين Grok Bot

لتمكين Grok Bot في Cursor، انتقل إلى إعدادات الأتمتة:

1. افتح إعدادات Cursor (Ctrl+, أو Cmd+,)
2. انتقل إلى قسم Automations في الشريط الجانبي الأيسر
3. بدّل Enable Grok Bot لتنشيط الميزة
4. انقر على Generate Webhook Secret لإنشاء مفتاح سري لمصادقة الطلبات الواردة

// مثال على التكوين المولد المخزن في settings.json
{
  "cursor.grokBot.enabled": true,
  "cursor.grokBot.webhookSecret": "whsec_abc123def456ghi789",
  "cursor.grokBot.defaultModel": "cursor-agent-pro",
  "cursor.grokBot.maxConcurrentRoutines": 3
}

warning

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

إنشاء روتينك الأول

الروتين هو مجموعة من التعليمات يتبعها البوت عند تشغيله. أنشئ واحداً من لوحة Automations:

1. افتح لوحة Automations (Ctrl+Shift+A)
2. انقر على New Routine
3. أعطِ الروتين اسماً وصفياً، مثل "Slack Code Review Request"
4. اختر نوع مشغل (Webhook أو Slack أو Manual أو Schedule)
5. عرّف الإجراءات التي يجب أن ينفذها الروتين
6. احفظ ونشّط الروتين

# مثال على تكوين الروتين
name: "Slack Code Review Request"
description: "When a Slack message mentions @code-review, analyze the referenced file"
trigger:
  type: slack
  condition: "message.contains('@code-review')"
actions:
  - type: parse_message
    extract:
      file_path: "regex:review\\s+(.+)"
      question: "regex:asking\\s+(.+)"
  - type: read_file
    path: "{{file_path}}"
  - type: analyze
    prompt: "Review this code for potential issues, security vulnerabilities, and improvement suggestions."
  - type: slack_reply
    message: "{{analysis_result}}"

روتينات Webhook

تتيح روتينات Webhook للخدمات الخارجية تشغيل إجراءات في Cursor عن طريق إرسال طلبات HTTP POST إلى عنوان URL محدد.

فهم عنوان URL لـ Webhook

عندما تنشئ روتيناً مشغلاً بـ Webhook، يولد Cursor عنوان URL فريداً لـ Webhook. هذا العنوان هو المكان الذي ترسل إليه الخدمات الخارجية حمولاتها.

# مثال على تنسيق عنوان URL لـ Webhook
http://localhost:7541/webhooks/routines/rtn_abc123def456

warning

مشكلة شائعة أبلغ عنها المستخدمون هي أن تكوين روتين Webhook لا يعرض أي عنوان POST URL. يحدث هذا عادةً عندما لا يتم حفظ الروتين بالكامل أو لم يتم تعيين نوع المشغل إلى "Webhook" قبل الحفظ. إذا كنت لا ترى عنوان POST URL، فاتبع هذه الخطوات:

1. أعد فتح محرر الروتين
2. أكد أن نوع المشغل معين إلى "Webhook"
3. انقر على Save صراحةً (لا تغلق اللوحة فقط)
4. أعد فتح الروتين للتحقق من ظهور عنوان URL الآن

إذا لم يظهر عنوان URL بعد، فأعد تشغيل Cursor وحاول مرة أخرى. هذه مشكلة معروفة تم الإبلاغ عنها ويتم تتبع إصلاحها.

تسجيل روتين Webhook

إليك كيفية إنشاء روتين مشغل بـ Webhook خطوة بخطوة:

1. افتح لوحة Automations
2. انقر على New Routine
3. عيّن الاسم إلى "GitHub PR Notification"
4. عيّن نوع المشغل إلى Webhook
5. احفظ الروتين لتوليد عنوان URL لـ Webhook
6. انسخ عنوان POST URL المعروض
7. كوّن خدمتك الخارجية لإرسال الطلبات إلى ذلك العنوان

# مثال: إرسال Webhook من GitHub Action
import json
import urllib.request

webhook_url = "http://localhost:7541/webhooks/routines/rtn_abc123def456"
webhook_secret = "whsec_abc123def456ghi789"

payload = {
    "event": "pull_request.opened",
    "repository": "my-org/my-repo",
    "pr_number": 42,
    "pr_title": "Add payment gateway integration",
    "author": "jane-dev",
    "changed_files": ["src/payment/stripe.ts", "src/api/routes.ts"],
}

req = urllib.request.Request(
    webhook_url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "X-Webhook-Secret": webhook_secret,
    },
    method="POST",
)

try:
    with urllib.request.urlopen(req) as response:
        print(f"Status: {response.status}")
        print(f"Response: {response.read().decode()}")
except urllib.error.URLError as e:
    print(f"Webhook delivery failed: {e}")

التحقق من طلبات Webhook

تحقق دائماً من طلبات Webhook الواردة للتأكد من أنها تأتي من مصدر موثوق. يجب تضمين سر Webhook الذي أنشأته أثناء الإعداد في رأس X-Webhook-Secret.

// مثال على منطق التحقق (Node.js)
const crypto = require("crypto");

function validateWebhook(req, res, next) {
  const secret = req.headers["x-webhook-secret"];
  const expectedSecret = process.env.CURSOR_WEBHOOK_SECRET;

  if (!secret || secret !== expectedSecret) {
    return res.status(401).json({ error: "Invalid webhook secret" });
  }

  // اختياري: التحقق من طابع زمني للطلب لمنع هجمات إعادة التشغيل
  const timestamp = req.headers["x-webhook-timestamp"];
  const now = Date.now();
  const maxAge = 5 * 60 * 1000; // 5 دقائق

  if (timestamp && now - parseInt(timestamp) > maxAge) {
    return res.status(401).json({ error: "Webhook timestamp expired" });
  }

  next();
}

تلميح

لإعدادات الإنتاج، استخدم أداة مثل ngrok أو Cloudflare Tunnel لعرض نقطة نهاية Webhook المحلية على الإنترنت. يتيح ذلك للخدمات الخارجية مثل GitHub أو Slack أو Jira الوصول إلى مثيل Cursor المحلي الخاص بك.

تكامل Slack

Slack هو أحد أكثر مصادر المشغلات شيوعاً لروتينات Grok Bot. يمكنك تكوين Slack لإرسال رسائل إلى Cursor عندما تحدث أحداث معينة.

إعداد مشغل Slack

1. انتقل إلى صفحة تطبيقات Slack API
2. انقر على Create New App واختر From scratch
3. سَمِّ التطبيق "Cursor Grok Bot" واختر مساحة عملك
4. تحت Event Subscriptions، فعّل الأحداث
5. أدخل عنوان URL لـ Webhook الخاص بـ Cursor كعنوان Request URL
6. اشترك في أحداث البوت message.channels و reaction_added
7. تحت OAuth & Permissions، أضف نطاقي chat:write و channels:read
8. ثبّت التطبيق في مساحة عملك وانسخ Bot User OAuth Token

// مثال: معالج مشغل Slack في روتين Grok Bot
const slackTrigger = {
  type: "slack",
  events: ["message.channels"],
  conditions: {
    // التشغيل فقط عندما تذكر الرسالة @cursor-bot
    mentions_bot: true,
    // التشغيل فقط في قنوات محددة
    channels: ["#code-review", "#bug-reports", "#deployments"],
    // تجاهل رسائل البوت نفسه
    ignore_bots: true,
  },
};

إرسال ردود إلى Slack

عند اكتمال روتين، يمكنك إرسال النتيجة مرة أخرى إلى قناة Slack الأصلية:

const { WebClient } = require("@slack/web-api");

const slack = new WebClient(process.env.SLACK_BOT_TOKEN);

async function replyToSlack(channel, text) {
  await slack.chat.postMessage({
    channel: channel,
    text: text,
    // اختياري: التنسيق كرسالة Slack Block Kit
    blocks: [
      {
        type: "section",
        text: {
          type: "mrkdwn",
          text: text,
        },
      },
      {
        type: "divider",
      },
      {
        type: "context",
        elements: [
          {
            type: "mrkdwn",
            text: ":robot_face: Generated by Cursor Grok Bot",
          },
        ],
      },
    ],
  });
}

warning

إذا لم يتم تشغيل مشغل Slack الخاص بك، فتحقق من الأسباب الشائعة التالية:

1. تطبيق Slack غير مشترك في أنواع الأحداث الصحيحة
2. مستخدم البوت لا يملك إذن قراءة القناة المستهدفة
3. عنوان URL لـ Webhook غير صحيح أو غير قابل للوصول من الإنترنت
4. رأس X-Webhook-Secret لا يطابق القيمة المتوقعة
5. مرشح الشرط في الروتين الخاص بك لا يطابق الرسالة الواردة

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

تكوين المشغلات

يدعم Grok Bot عدة أنواع مشغلات بالإضافة إلى Webhooks وSlack. يساعدك فهم كل نوع مشغل في اختيار المناسب لحالة استخدامك.

أنواع المشغلات المتاحة

نوع المشغل	الوصف	حالة الاستخدام
Webhook	طلب HTTP POST من أي خدمة خارجية	أحداث GitHub، تحديثات Jira، خطوط أنابيب CI/CD
Slack	رسائل أو تفاعلات Slack	إشعارات الفريق، طلبات مراجعة الكود
Schedule	مشغل زمني (تعبير cron)	فحوصات دورية، ملخصات ليلية
File Watch	يتم تشغيله عند تغير ملف على القرص	تنسيق تلقائي، اختبار تلقائي عند الحفظ
Manual	يتم تشغيله باختصار لوحة مفاتيح أو أمر	تحليل كود عند الطلب

مثال على مشغل الجدولة

name: "Nightly Dependency Audit"
description: "Check for outdated dependencies every night at 2 AM"
trigger:
  type: schedule
  cron: "0 2 * * *"
actions:
  - type: terminal_command
    command: "npm audit --json"
  - type: analyze
    prompt: "Analyze these npm audit results and summarize the critical vulnerabilities."
  - type: slack_reply
    channel: "#security-alerts"
    message: "{{analysis_result}}"

مثال على مشغل مراقبة الملفات

name: "Auto-Format on Save"
description: "Run formatter whenever a TypeScript file is saved"
trigger:
  type: file_watch
  patterns:
    - "**/*.ts"
    - "**/*.tsx"
  events: ["save"]
actions:
  - type: terminal_command
    command: "npx prettier --write {{file_path}}"
  - type: terminal_command
    command: "npx eslint --fix {{file_path}}"

تلميح

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

تحرير الروتينات

تُخزَّن الروتينات كملفات تكوين YAML ويمكن تحريرها مباشرة أو عبر المحرر المرئي في Cursor.

استخدام المحرر المرئي

يوفر المحرر المرئي في لوحة Automations واجهة سحب وإفلات لبناء الروتينات:

1. اسحب كتل الإجراءات من اللوحة على اليسار
2. رتبها بالترتيب المطلوب
3. انقر على كل كتلة لتكوين معلماتها
4. استخدم زر Test لتشغيل الروتين بإدخال نموذجي
5. احفظ الروتين لتنشيطه

تحرير YAML مباشرة

لمزيد من التحكم، يمكنك تحرير ملف YAML للروتين مباشرة. تُخزَّن ملفات الروتين في دليل .cursor/automations/:

# قائمة بجميع الروتينات
ls -la .cursor/automations/

# تحرير روتين محدد
code .cursor/automations/nightly-audit.yaml

# .cursor/automations/code-review-bot.yaml
name: "Smart Code Review Bot"
description: "Analyzes changed files and posts a review comment"
trigger:
  type: webhook
  filter:
    event: "pull_request.opened"
actions:
  - type: parse_payload
    extract:
      pr_number: "$.pull_request.number"
      changed_files: "$.pull_request.changed_files"
      repo: "$.repository.full_name"

  - type: loop
    over: "{{changed_files}}"
    actions:
      - type: read_file
        path: "{{item}}"
      - type: analyze
        prompt: |
          Review this file for:
          1. Security vulnerabilities
          2. Performance issues
          3. Code style violations
          4. Missing error handling

  - type: format_output
    template: |
      ## Automated Code Review

      {{#each results}}
      ### {{this.file}}
      {{this.review}}
      {{/each}}

  - type: webhook_response
    status: 200
    body: "{{formatted_output}}"

warning

عند تحرير ملفات YAML للروتين مباشرة، تحقق دائماً من الصياغة قبل الحفظ. ملف YAML تالف سيتسبب في فشل الروتين بصمت. استخدم cursor.automations.validate في لوحة الأوامر للتحقق من جميع الروتينات.

خطوط عمل الأتمتة

يجمع الجمع بين روتينات متعددة خطوط عمل أتمتة قوية تربط خط أنابيب التطوير بأكمله.

مثال على سير العمل: أتمتة دورة حياة PR

يؤتمت سير العمل هذا دورة حياة طلب السحب بالكامل:

# الروتين 1: PR مفتوح - تحليل أولي
name: "PR Initial Analysis"
trigger:
  type: webhook
  filter:
    event: "pull_request.opened"
actions:
  - type: analyze
    prompt: "Summarize this PR and identify the main changes."
  - type: slack_reply
    channel: "#pr-updates"
    message: "New PR: {{pr_title}}\nSummary: {{analysis_result}}"

---

# الروتين 2: طلب مراجعة PR - تحليل عميق
name: "PR Deep Analysis"
trigger:
  type: slack
  conditions:
    mentions_bot: true
    contains_keyword: "deep-review"
actions:
  - type: analyze
    prompt: "Perform a comprehensive code review including security, performance, and architecture."
  - type: slack_reply
    channel: "{{trigger_channel}}"
    message: "{{analysis_result}}"

---

# الروتين 3: PR مدمج - تحديث التوثيق
name: "PR Merged - Update Docs"
trigger:
  type: webhook
  filter:
    event: "pull_request.closed"
    merged: true
actions:
  - type: analyze
    prompt: "Update the README and CHANGELOG based on the merged changes."
  - type: terminal_command
    command: "git add README.md CHANGELOG.md && git commit -m 'docs: update for PR #{{pr_number}}'"

مثال على سير العمل: الاستجابة للحوادث

name: "Incident Response Bot"
description: "When an error alert is posted to Slack, analyze and suggest fixes"
trigger:
  type: slack
  channels: ["#alerts", "#incidents"]
  conditions:
    contains_keyword: "ERROR"
actions:
  - type: parse_message
    extract:
      error_text: "regex:ERROR:\\s*(.+)"
      stack_trace: "regex:at\\s+(.+)"

  - type: search_codebase
    query: "{{error_text}}"

  - type: analyze
    prompt: |
      An error has occurred. Here is the error message and the relevant code.
      Suggest a fix and explain the root cause.
      Error: {{error_text}}
      Stack trace: {{stack_trace}}
      Relevant file: {{search_result}}

  - type: slack_reply
    channel: "{{trigger_channel}}"
    message: |
      :rotating_light: *Automated Analysis*
      *Likely cause:* {{analysis_result.cause}}
      *Suggested fix:* {{analysis_result.fix}}
      *File to check:* {{search_result}}

تلميح

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

استكشاف الأخطاء وإصلاحها

عدم ظهور عنوان URL لـ Webhook

هذه هي المشكلة الأكثر شيوعاً. عند إنشاء روتين مشغل بـ Webhook، قد يظهر حقل POST URL فارغاً.

السبب الجذري: تم حفظ الروتين قبل تعيين نوع المشغل، أو تم حفظ الروتين جزئياً فقط.

الحل:

1. احذف الروتين وأنشئ واحداً جديداً
2. عيّن نوع المشغل إلى "Webhook" قبل إدخال أي تفاصيل أخرى
3. انقر على Save وانتظر توليد عنوان URL
4. إذا لم يظهر عنوان URL بعد، فتحقق من لوحة إخراج Cursor عن أخطاء (View > Output > Cursor Automations)
5. كحل بديل، يمكنك بناء عنوان URL يدوياً باستخدام معرف الروتين من ملف YAML:

http://localhost:7541/webhooks/routines/{ROUTINE_ID}

عدم تشغيل مشغلات Slack

إذا كانت مشغلات Slack لا تستجيب للرسائل:

1. تحقق من تثبيت تطبيق Slack في مساحة عملك
2. تأكد من إمكانية الوصول إلى عنوان URL لاشتراك الأحداث (استخدم ميزة التحقق من Slack API)
3. أكد دعوة مستخدم البوت إلى القناة المستهدفة (/invite @cursor-grok-bot)
4. تحقق من أن شروط الروتين ليست مقيدة جداً
5. راجع سجل Cursor Automations للأحداث الواردة:

# عرض سجل الأتمتة
cat .cursor/automations/logs/automation.log | tail -100

# تصفية أحداث Slack
grep "slack" .cursor/automations/logs/automation.log

warning

لدى Slack مهلة 3 ثوانٍ للتحقق من عنوان URL لاشتراك الأحداث. إذا استغرق Cursor أكثر من 3 ثوانٍ للاستجابة لطلب التحقق الأولي، فسيقبل Slack عنوان URL. تأكد من تشغيل Cursor واستجابته عند تكوين اشتراك الأحداث في لوحة معلومات Slack API.

مشاكل تحرير الروتين

إذا لم تتمكن من حفظ أو تحرير روتين:

1. تحقق من صحة ملف YAML باستخدام لوحة الأوامر
2. تأكد من عدم قيام عملية أخرى بتأمين ملف الروتين
3. تحقق من أذونات الكتابة في دليل .cursor/automations/
4. حاول حذف دليل .cursor/automations/cache/ لفرض التحديث
5. أعد تشغيل Cursor إذا توقف المحرر المرئي عن الاستجابة

تصحيح تنفيذ الروتين

فعّل تسجيل التصحيح لرؤية معلومات مفصلة عن تنفيذ الروتين:

// في settings.json
{
  "cursor.grokBot.debug": true,
  "cursor.grokBot.logLevel": "verbose"
}

# عرض سجلات التصحيح في الوقت الفعلي
tail -f .cursor/automations/logs/automation.log

# تصفية روتين محدد
grep "routine_id: rtn_abc123" .cursor/automations/logs/automation.log

أفضل الممارسات

• ابدأ ببساطة: ابدأ بروتين إشعارات أساسي قبل بناء خطوط عمل معقدة
• اختبر بإدخال نموذجي: استخدم زر Test في المحرر المرئي قبل تنشيط روتين
• استخدم الشروط بحكمة: أضف مرشحات شرط لمنع تشغيل الروتينات على كل رسالة أو حدث
• راقب وقت التنفيذ: الروتينات طويلة الأمد قد تحظر تنفيذ روتينات أخرى. اضبط مهلة.
• تحكم في إصدار روتيناتك: خزّن ملفات YAML للروتين في مستودع git للتعاون الجماعي
• وثّق خطوط عملك: أضف أوصافاً واضحة لكل روتين لكي يفهم الزملاء غرضه
• بدّل أسرار Webhook: أعد توليد سر Webhook دورياً للأمان
• استخدم متغيرات البيئة: اشر إلى القيم الحساسة عبر متغيرات البيئة بدلاً من تضمينها في YAML

تلميح

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

الخاتمة

يوفر Grok Bot في Cursor طبقة أتمتة مرنة تربط محررك بالخدمات الخارجية من خلال روتينات Webhook ومشغلات Slack. باتباع خطوات الإعداد في هذا الدليل ومعالجة سيناريوهات استكشاف الأخطاء الشائعة، يمكنك بناء خطوط عمل أتمتة قوية توفر الوقت وتقلل الجهد اليدوي.

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