Cursor

المورّد: Anysphere اسم التثبيت: cursor الحالة: إتاحة عامة الإعداد الأصلي: .cursor/rules/ في جذر المشروع

التثبيتCopy Anchor Link

apothem install --harness cursor --project /path/to/project

يُجسِّد المحوّل ملف قواعد .mdc واحدًا بنطاق المشروع من سطح القواعد والحوكمة المشترك في Apothem، ويكتب مساعِدات Apothem بوصفها عوامل فرعية لـ Cursor في المشروع (راجع العوامل الفرعية)، ويضيف خطّافًا واحدًا إلى hooks.json الخاص بالمشروع (راجع الخطّافات).

ويكتب أيضًا مهارات Apothem، والقواعد والقوالب التي تستشهد بها، في دليلك المنزلي، قبل أن يمسّ المشروع (راجع الملفات خارج المشروع).

الملفات المكتوبة:

• <project>/.cursor/rules/apothem-rules.mdc، ملف القواعد.
• <project>/.cursor/agents/<name>.md لكل مساعِد من مساعِدات Apothem، في المشروع.
• <project>/.cursor/hooks.json، مع إضافة مُدخلة sessionStart واحدة إليه. وتبقى مُدخلاتك ومفاتيحك الخاصة فيه.
• <project>/.apothem/support/cursor/hooks/، سكربتات الخطّافات، في المشروع.
• ~/.agents/skills/<name>/SKILL.md لكل مهارة وأمر من Apothem، في دليلك المنزلي.
• ~/.config/apothem/rules/ و~/.config/apothem/templates/، في دليلك المنزلي.

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

الملفات خارج المشروعCopy Anchor Link

يكتب التثبيت أيضًا مهارات Apothem في دليلك المنزلي، قبل أن يغيّر أي شيء في المشروع:

هذه المجلّدات مشتركة، وليست خاصة بالمشروع:

• كل مشروع تثبّت فيه cursor، وكل تثبيت آخر لـ Apothem يسمّي المجلّد، يستخدم النسخة نفسها ويكتب الملفات نفسها، لذا لا يهمّ الترتيب الذي تثبّت به. وتقرأ أدوات أخرى عديدة ~/.agents/skills/ أيضًا؛ ويسردها سجلّ أُطُر العمل.
• يختار --project ملف القواعد الذي يُكتَب والمشروعَ الذي ينتمي إليه التثبيت. ولا يغيّر المكان الذي تذهب إليه المهارات.
• لا يضيف التثبيت أي ملف مهارة أو قاعدة إلى مستودعك. ويحصل المشروع على ملف القواعد، وملفات العوامل الفرعية في .cursor/agents/، ومُدخلة الخطّاف في .cursor/hooks.json، إضافةً إلى المجلّد .apothem/ الذي يُنشئه كل تثبيت على مستوى المشروع، والذي يحوي أيضًا سكربتات الخطّافات.
• تُكتَب المجلّدات المنزلية أولًا. فإن فشل ذلك، مثلًا لأن مجلّدًا في المسار رابطٌ يخرج من دليلك المنزلي (أما الرابط الذي يبقى داخله فيُتَّبَع) أو لا يمكن الكتابة فيه، يتوقّف التثبيت مع الخطأ قبل أن يتغيّر أي شيء في المشروع.
• مجلّد المهارة الذي يحمل اسم مهارة من Apothem ولم يكتبه Apothem يُترَك كما هو، ويطبع التثبيت تحذيرًا يسمّيه. أعد تسميته أو انقله، ثم شغّل apothem update. ويفشل apothem verify ما دام ذلك الاسم محجوزًا.
• يبلغ مجموع الملفات بضعة ميغابايتات.

يطبع التثبيت ملاحظة تسمّي المجلّدات التي يكتبها خارج --project، ويسردها --dry-run.

العوامل الفرعيةCopy Anchor Link

يقرأ Cursor العامل الفرعي من ملف Markdown في <project>/.cursor/agents/، وفق وثائق العوامل الفرعية في Cursor. ويكتب التثبيت ملفًا واحدًا لكل مساعِد من مساعِدات Apothem في ذلك المجلّد. وهو يثبّت للمشروع فقط ولا يكتب أي مجلّد ~/.cursor/agents/.

يُبقي كل ملف تعليمات المساعِد دون تغيير ويحمل مفاتيح البيانات الأمامية التالية:

لا يملك Cursor مفتاحًا يسرد الأدوات أو يحظرها: فالعامل الفرعي يرث كل أدوات أصله. والقيد الوحيد الذي يستطيع فرضه هو readonly: true، الذي لا يسمح بأي تعديلات على الملفات ولا بأي أوامر صدفة تغيّر الحالة. لذا لا يُكتَب السطران tools وdisallowedTools الخاصان بالمساعِد، ولا يبقى القيد إلا في صورة تلك الراية:

• المساعِدات الخمسة أعلاه للقراءة فقط ولا تملك Bash، لذا تحصل على readonly: true وتُبقي صياغة القراءة فقط في أوصافها.
• سبعة مساعِدات للقراءة فقط لكنها تُشغِّل أوامر (codebase-explorer، وdependency-auditor، وdesign-critic، وprompt-evaluator، وquality-gate، وsecurity-scanner، وtest-runner). وكان readonly: true سيوقف أيضًا تشغيلات الاختبار والفحص الأسلوبي لديها، لذا لا تحصل على أي راية، وتُسقِط أوصافها تسمية القراءة فقط التي لن يفرضها Cursor. ولا يتغيّر إلا الوصف: إذ تُنسَخ التعليمات دون تغيير، فتظل تصف المساعِد بأنه للقراءة فقط وتذكر قيدًا على الأدوات لا يحمله ملف Cursor. ويتبع النموذج ذلك النص، لكن Cursor لا يفرضه، ويعمل المساعِد بكل أدوات الأصل.
• mcp-builder وrefactor-surgeon يكتبان الملفات ويبقيان دون تغيير.

لا يكتب التثبيت أي مفتاح model، لذا يعمل المساعِد على النموذج الذي يستخدمه الأصل، ولا يكتب is_background، ولا حدًّا للأدوار، ولا مفاتيح Apothem: version وupdated وportability.

أمور ينبغي معرفتها:

• ملفات العوامل الفرعية ملفات مشروع عادية. أودِعها مع المشروع أو أدرِج .cursor/agents/ في .gitignore؛ ولا يختار Apothem نيابةً عنك.
• يُحمِّل Cursor أيضًا مجلّدات المساعِدات المكتوبة لأدوات أخرى، ومنها .claude/agents/ في المشروع و~/.claude/agents/ في دليلك المنزلي (ويسرد سجلّ أُطُر العمل البقية). وعند تعارض الأسماء يتقدّم المشروع على المجلّد المنزلي ويتقدّم .cursor/ على الآخرين، لذا ففي مشروع فيه هذا التثبيت تحلّ الملفات الأصلية محلّ نسخ Claude Code التي كان Cursor سيستوردها من ~/.claude/agents/. ولا تقول وثائق Cursor ما إذا كان يُحمِّل النسختين كلتيهما أو يُسقِط الأدنى منهما، ولا ما إذا كان يطبّق السطرين tools وdisallowedTools في ملف Claude Code يستورده.
• الملف الخاص بك الذي يحمل اسم مساعِد من Apothem يُحفَظ تحت ~/.apothem/backups/ ثم يُستبدَل. ولا يُعيده إلغاء التثبيت. ولا تُمَسّ الملفات ذات الأسماء الأخرى أبدًا.
• لم يتحقّق Apothem مما إذا كان Cursor يقرأ ملفات TOML التي تكتبها أداة أخرى في المجلّدات التي يستوردها، ولا مما إذا كان الإعداد Third-Party Imports يوقف تلك المجلّدات المستوردة، ولا مما إذا كان يقرأ امتدادات غير .md أو مجلّدات متداخلة في .cursor/agents/.

الخطّافاتCopy Anchor Link

يُشغِّل Cursor الخطّافات من ملفات hooks.json، وفق وثائق الخطّافات في Cursor. ويضيف التثبيت مُدخلة واحدة إلى <project>/.cursor/hooks.json:

يضيف الخطّاف سياقًا للنموذج. ولا يحجب أي شيء، ولا ينتظر Cursor خطّاف sessionStart.

لا يسجّل هذا الإصدار الأول شيئًا آخر. تسرد وثائق Cursor الحقل additional_context للحدث postToolUse أيضًا، وسيسجّل Apothem عدّاد حجم السياق هناك حالما يُظهر اختبار استقصائي أن السياق يصل إلى النموذج. ولا يسجّل أي حارس preToolUse: إذ لا يوثّق Cursor الحقل agent_message، وهو الحقل الذي سيتحدّث عبره الحارس، إلا لإجراء يرفضه، وحُرّاس Apothem لا ترفض أبدًا. وتبقى حُرّاس الكتابة والتعديل والصدفة، وفحص AskUserQuestion، وبروتوكول نهاية الجلسة، على الأدوات التي توصلها.

أين تذهب الملفات

hooks.json ملفك أنت، ويوثّق Cursor خطّافات المشروع بوصفها مُودَعة في نظام التحكّم بالإصدارات. ويضيف التثبيت مُدخلة Apothem بعد مُدخلاتك ويترك مُدخلاتك ومفاتيحك الأخرى كما كانت؛ ولا يستبدل التحديث إلا المُدخلة التي يُشغِّل أمرها مُوزِّع Apothem (.apothem/support/cursor/hooks/dispatch.py مع --contract cursor، أيًّا كان مسار المشروع الذي كُتِبت تحته)، ولا يُزيل إلغاء التثبيت إلا تلك المُدخلة. والخطّاف الخاص بك الذي يشاركه الاسم فقط، مثل tools/hooks/dispatch.py في مشروعك، أو الذي يُشغِّل python -m apothem.conformity.gate، لا يُعَدّ أبدًا خطّافًا لـ Apothem. ويحذف إلغاء التثبيت الملف حين لا يتبقى فيه شيء آخر، بعد حفظ نسخة منه تحت ~/.apothem/backups/. والملف الذي يحوي تعليقات، أو فاصلة زائدة في النهاية، أو قيمة hooks بشكل خاطئ لا يمكن إعادة كتابته دون فقدان شيء، لذا يُبلِغ التثبيت عن خطأ config.unparseable لذلك الملف، ويتركه دون مساس ويتوقّف، مع إزالة الملفات الأخرى التي كان قد بدأ كتابتها مجدّدًا: أصلِح الملف، أو أضِف المُدخلة بنفسك.

الملف المُودَع يسمّي جهازك. يحوي أمر المُدخلة المُفسِّرَ الذي عثر عليه Apothem حين عمل والمسارَ المطلق للمشروع، لذا فإن الزميل الذي يسحب الملف يحصل على أمر يشير إلى جهازك. ويُبلِغ Cursor عن الأمر الذي لا يستطيع العثور عليه بأنه فاشل وتستمرّ الجلسة، فلا ينكسر شيء، لكن الخطّاف لا يفعل شيئًا هناك. فلا تُودِع الملف إلا إن كان فريقك يتشارك ذلك التخطيط. ولا يوثّق Cursor أي صيغة غير مُودَعة لملف خطّافات المشروع. والمجلّد .apothem/ هو مكان السكربتات، ومقتطف .gitignore الخاص بالمشروع يُبقيه خارج نظام التحكّم بالإصدارات.

يبدو الأمر هكذا، مع المُفسِّر ومسار المشروع لديك في موضع المسارين:

"/path/to/python" "/path/to/project/.apothem/support/cursor/hooks/dispatch.py" --contract cursor sessionStart

على مضيف Windows يبدأ الأمر بـ & ، مُعامِل الاستدعاء في PowerShell، لأن تطبيق سطح المكتب في Cursor يُشغِّل أوامر الخطّافات عبر PowerShell، حيث لا يُعَدّ السطر الذي يبدأ بمسار برنامج مقتبس استدعاءً. وتقرأ sh العلامة & في البداية بوصفها خطأً في الصياغة، لذا لا يحصل عليها أي مضيف آخر. وتسمّي الوثائق الصدفة لا طريقة الاقتباس، لذا فهذه قراءة Apothem لصياغة PowerShell.

يقرأ --contract cursor الحقلين conversation_id وworkspace_roots من Cursor ويُجيب بـ {"additional_context": ...} ولا شيء غيره.

مسارات قد تسيء الصدفة قراءتها. يُرفَض مسار المشروع أو المُفسِّر الذي يحوي $، أو علامة اقتباس مائلة (backtick)، أو علامة اقتباس مزدوجة، أو شرطة مائلة عكسية، قبل كتابة أي شيء: فداخل الأمر المقتبس سيُشغِّل ملفًا مختلفًا، أو يكسر JSON الذي يُكتَب فيه الأمر. ويسمّي الخطأ المسار؛ انقل المشروع أو أعد تسميته ثم شغّل التثبيت مجدّدًا. والمسافة أو الفاصلة العليا في المسار لا تضرّ.

يُشغِّل Cursor أيضًا الخطّافات التي كتبها Claude Code. يُحمِّل Cursor الخطّافات في ~/.claude/settings.json و.claude/settings.json و.claude/settings.local.json ما دام الإعداد «Include Third-Party Plugins, Skills, and Other Configs» مفعّلًا (في Cursor Settings، تحت Third-Party Imports)، وهو الوضع الافتراضي، ويُشغِّل كل خطّاف مطابق من كل مصدر. وإن كنت قد ثبّتّ Apothem لـ Claude Code أيضًا، فقد تعمل مجموعتا الخطّافات كلتاهما. ويتشارك أمر sessionStart هنا ونسخته في Claude Code علامةً واحدة لكل جلسة في مجلّد حالة الخطّافات الخاص بـ Apothem، لذا يصمت أيّهما يعمل ثانيًا ويصل التمهيد إلى النموذج مرة واحدة؛ ويتعرّف Apothem على Cursor من المتغيّرين CURSOR_PROJECT_DIR وCURSOR_VERSION اللذين يضبطهما Cursor لخطّافاته. وتغطّي العلامة عشر ثوانٍ، لذا فإن بدءًا لاحقًا للجلسة نفسها، مثل عملية ضغط ثانية، يظل يوصل التمهيد. ويعمل عدّاد حجم السياق في نسخة Claude Code إضافةً إلى ذلك، ولا يُزيل Apothem تكرار العدّادات. ولتشغيل الخطّاف الموجود هنا وحده، أوقف ذلك الإعداد؛ وهذا يوقف أيضًا استيراد Cursor للإضافات والمهارات والإعدادات الأخرى من أطراف ثالثة. ويطبع التثبيت هذا بوصفه ملاحظة.

أمور ينبغي معرفتها. يُعيد Cursor تحميل hooks.json حين يُحفَظ، لذا لا حاجة إلى إعادة التشغيل. وتعمل خطّافات المشروع في مساحات العمل الموثوقة. ويُشغِّل Cursor السحابي خطّافات المشروع في المستودع لكنه يؤجّل sessionStart، لذا لا تنطلق المُدخلة هناك. اضبط APOTHEM_HOOKS_DISABLE=1 في بيئة Cursor لإسكات خطّاف Apothem.

تعيين الملف التعريفي إلى الإعداد الأصليCopy Anchor Link

يقرأ المحوّل الملف التعريفي المشترك لـ Apothem ويُجسِّد ملف قواعد المشروع في كل تشغيل لـ apothem install أو apothem update. الملف التعريفي المشترك هو مصدر الحقيقة؛ وتُنسَخ التعديلات المحلية للمشروع على الملف المُولَّد احتياطيًا قبل أن تستبدل المزامنة التالية المحتوى الذي يديره Apothem.

يبدأ الملف ببياناته الأمامية بصيغة YAML (description، وglobs، وalwaysApply: true)، لأن Cursor لا يقرأ نوع القاعدة إلا من البيانات الأمامية في بداية الملف. وتليها الكتلة التي يديرها Apothem؛ ويُحتفَظ بالنص الذي تضيفه بعد الكتلة في كل مزامنة.

ملاحظات التوافقCopy Anchor Link

يدعم Cursor 0.45+ التعليمات على مستوى المشروع عبر .cursor/rules/. يكتب المحوّل افتراضيًا إلى دليل .cursor/rules/ بنطاق المشروع؛ ولا يملك Cursor مسارًا موثّقًا قائمًا على الملفات للقواعد العامّة على مستوى المستخدم كي يديره هذا المحوّل.

يُحمِّل Cursor المهارات من ~/.agents/skills/، لذا تظهر المهارات التي يكتبها التثبيت في Cursor دون إعداد إضافي. ويُحمِّل Cursor أيضًا ~/.claude/skills/، لذا فعلى جهاز فيه أيضًا تثبيت لـ Claude Code قد يسرد أسماء المهارات نفسها مرتين، ولا تقول وثائقه أيّ النسختين تتقدّم. ولم يتحقّق Apothem من كيفية تعامل Cursor مع مفتاح ترويسة في SKILL.md لا يسرده؛ وتحمل المهارات user-invocable، وdisable-model-invocation، وallowed-tools، وargument-hint، وخريطة metadata.

التحقّقCopy Anchor Link

apothem verify --harness cursor --project /path/to/project

يؤكّد أمر التحقّق ما يلي:

1. الإعداد الأصلي موجود في المسار المتوقَّع.
2. كل هدف مُدار موجود، بما في ذلك المجلّد .cursor/agents/ وملف الخطّافات .cursor/hooks.json؛ والملفات المُدارة غير فارغة، وتُحلَّل إعدادات JSON أو YAML. ويجب أن يحوي ملف الخطّافات مُدخلة تُشغِّل مُوزِّع Apothem (لا يُشغِّله الفحص)، لذا فإن الملف الذي أُعيد إلى حالته السابقة أو أُفرِغ لم يعد يجتاز التحقّق. أضِف --profile PATH لتتحقّق كذلك من أن الملفات المثبّتة تطابق ذلك الملف التعريفي. وبالنسبة إلى .cursor/agents/ يتحقّق الفحص من وجود المجلّد، لا من وجود كل ملف مساعِد فيه؛ ويسرد apothem diff --harness cursor --project /path/to/project ملفات المساعِدات المفقودة أو القديمة.
3. كل مجلّد مهارة من Apothem في مكانه ومعه SKILL.md، أيًّا كان التثبيت الذي كتبه، ولا يوجد مجلّد مهارة يحمل اسمًا من Apothem ويعود إلى شيء لم يكتبه Apothem. ويسمّي الفحص الفاشل المجلّدات المفقودة أو الدخيلة.
4. روتين التحقّق الخاص بالمحوّل يُبلِغ عن النجاح.

التحديثCopy Anchor Link

apothem update --harness cursor --project /path/to/project

يُعيد اشتقاق ملف قواعد المشروع من الحالة الراهنة للملف التعريفي المشترك.

ويُعيد التحديث أيضًا كتابة أي مجلّد مهارة تختلف ملفاته عن الملفات الحالية. وإن كنت قد ثبّتّ بإصدار سابق لم يكتب أي مهارات، فإن التحديث يضيفها. ويُعيد كتابة ملفات العوامل الفرعية التي تختلف عن الحالية، ويضيف أي ملفات مفقودة منها. ويُحدِّث كذلك سكربتات الخطّافات ومُدخلة Apothem في .cursor/hooks.json، تاركًا مُدخلاتك الخاصة دون مساس.

إلغاء التثبيتCopy Anchor Link

apothem uninstall --harness cursor --project /path/to/project

يُزيل كتلة Apothem، والبيانات الأمامية التي كتبها Apothem فوقها، من <project>/.cursor/rules/apothem-rules.mdc ويُبقي أي نص آخر فيه. ولا يُحذَف الملف إلا عندما لا يبقى فيه شيء آخر. قبل التغيير، تُحفَظ نسخة مختومة بالوقت من الملف تحت ~/.apothem/backups/؛ ولا يُترَك أي ملف نسخة احتياطية في المشروع. لا يتأثّر ملف YAML الخاص بالملف التعريفي المشترك ولا محرّك Apothem.

ويُزيل إلغاء التثبيت أيضًا ملفات العوامل الفرعية التي كتبها في <project>/.cursor/agents/ ويُبقي أي ملف آخر هناك؛ ويُزال المجلّد حين يبقى فارغًا. ويُزيل مُدخلة Apothem من <project>/.cursor/hooks.json، متعرّفًا عليها من مسار المُوزِّع في أمرها، ويُبقي مُدخلاتك ومفاتيحك الخاصة. ولا يُحذَف الملف إلا حين لا يتبقى فيه شيء آخر. وتُزال كذلك سكربتات الخطّافات في <project>/.apothem/support/cursor/hooks/. وإن كان في ملفٍ تعليقات لا يستطيع إلغاء التثبيت قراءتها، فإنه يترك ذلك الملف كما هو ويُبلِغ عن المُدخلة بأنها تُخطِّيت، مع السبب؛ أزِل مُدخلة Apothem يدويًا. ويُزيل مجلّدات المهارات التي كتبها في ~/.agents/skills/ والقواعد والقوالب في ~/.config/apothem/، ولكن فقط حين لا يعود أي تثبيت آخر لـ Apothem يستخدمها. فقد يستخدمها مشروع آخر، أو أداة أخرى تشارك المجلّد. وفي تلك الحالة يُبقي إلغاء التثبيت المجلّدات، ويطبع التثبيت الذي يستخدمها، ويُزيلها آخر إلغاء تثبيت. وتبقى الملفات التي أضفتها إلى تلك المجلّدات، ويُزال المجلّد الذي يبقى فارغًا. ويُنسَخ كل مجلّد احتياطيًا تحت ~/.apothem/backups/ قبل إزالته.

بوابة المطابقةCopy Anchor Link

python -m apothem.conformity.gate --all .

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

مفاتيح الضبطCopy Anchor Link

انظر أيضًاCopy Anchor Link

• كل أُطُر العمل — الفهرس الكامل للأدوات المدعومة
• دليل التثبيت — ثبّت Apothem في إطار العمل هذا
• مرجع apothem harnesses — اسرد المحوّلات وافحصها من واجهة سطر الأوامر