Windsurf

المورّد: Devin Desktop (سابقًا Codeium Windsurf) اسم التثبيت: windsurf الحالة: إصدار عام الإعداد الأصلي: <project>/.devin/rules/apothem-rules.md

أصبح Windsurf الآن Devin Desktop، و.devin/rules/ هو الموقع المُفضَّل لقواعد مساحة العمل (وتكون له الأسبقية على .windsurf/rules/).

التثبيتCopy Anchor Link

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

يكتب المحوّل ملف قواعد واحدًا لـ Windsurf على نطاق المشروع انطلاقًا من القواعد المشتركة لـ Apothem وسطح الحوكمة، ويكتب أحد عشر من مساعِدات Apothem بوصفها عوامل فرعية لـ Devin Local في المشروع (راجع العوامل الفرعية)، ويسجّل خطّافين لـ Devin Local (راجع الخطّافات).

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

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

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

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

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

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

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

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

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

يقرأ Devin Local، الذي تبدأ عليه علامات التبويب الجديدة في Devin Desktop، العاملَ الفرعي من ملف Markdown في <project>/.devin/agents/، وفق وثائق العوامل الفرعية في Devin. أما Cascade، الوضع الأقدم، فليس فيه عوامل فرعية. ويكتب التثبيت أحد عشر من مساعِدات Apothem الأربعة عشر في ذلك المجلّد. وهو يثبّت للمشروع فقط ولا يكتب أي مجلّد عوامل فرعية على مستوى المستخدم (~/.config/devin/agents/ على Linux وmacOS، و%APPDATA%\devin\agents\ على Windows).

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

لا يملك Devin مفتاحًا يحظر أداة، لذا تصبح الأدوات المسموح بها للمساعِد، مطروحًا منها أدواته المحظورة، قائمةَ allowed-tools الوحيدة. وأداة Bash الخاصة بالمساعِد هي exec في Devin، والأداة التي لا يسرد لها Devin اسمًا تُستبعَد. وتحصل المساعِدات للقراءة فقط على read وglob وgrep، إضافةً إلى exec لتلك التي تُشغِّل أوامر، ولا تحصل أبدًا على write أو edit.

ثلاثة مساعِدات لا تُثبَّت: citation-auditor، وfact-checker، وresearch-scout. فهي تحتاج إلى البحث على الويب وجلب صفحات الويب، ولا يوثّق Devin اسمًا في allowed-tools لأيٍّ منهما، لذا يحجبها التثبيت بدلًا من كتابة نسخة لا تستطيع البحث أو نسخة تملك كل الأدوات. والملف الخاص بك في .devin/agents/ الذي يحمل أحد تلك الأسماء لا يُمَسّ أبدًا.

لا يكتب التثبيت أي مفتاح model. ويُشغِّل Devin العامل الفرعي على نموذجه الافتراضي الخاص بالعوامل الفرعية، وهو ليس نموذج الجلسة التي بدأته. ولا يكتب كذلك max-nesting ولا أيًّا من مفاتيح Apothem: maxTurns وversion وupdated وportability.

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

• العوامل الفرعية المخصّصة تجريبية. إذ يصف Devin الصيغة والخيارات بأنها عرضة للتغيير، ويحوي Devin Desktop مفتاح Subagents (Preview) في Devin Settings (والإعداد subagents_enabled في Devin CLI مفعّل افتراضيًا).
• ملفات العوامل الفرعية ملفات مشروع عادية. أودِعها مع المشروع أو أدرِج .devin/agents/ في .gitignore؛ ولا يختار Apothem نيابةً عنك.
• الملف الخاص بك الذي يحمل اسم مساعِد من Apothem يُحفَظ تحت ~/.apothem/backups/ ثم يُستبدَل. ولا يُعيده إلغاء التثبيت. ولا تُمَسّ الملفات ذات الأسماء الأخرى أبدًا.
• يقرأ Devin أيضًا المجلّد المشترك .agents/agents/، الذي لا يكتبه Apothem أبدًا، وتوثّق Devin CLI استيراد العوامل الفرعية من مجلّد .claude/ دون تسمية المسار. ويعثر Devin Local على ملفاته بالطريقة نفسها التي تتبعها Devin CLI، لذا ينطبق ذلك الاستيراد هناك أيضًا.
• لم يتحقّق Apothem من أسماء allowed-tools لأدوات الويب، ولا من القيم التي يقبلها model، ولا من كيفية قراءة قائمة allowed-tools فارغة.

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

يُشغِّل Devin Local الخطّافات من المفتاح hooks في ملفات إعداده، وفق وثائق الخطّافات في Devin. ويسجّل التثبيت خطّافين:

كلاهما يضيف سياقًا للنموذج. ولا يحجب أيٌّ منهما استدعاء أداة أو جلسة.

لا يسجّل Apothem أي حارس PreToolUse على Devin. إذ تسرد وثائق Devin الحقل additionalContext (الحقل الذي تتحدّث عبره حُرّاس Apothem) للأحداث UserPromptSubmit وSessionStart وPostToolUse، ولا تسرد للحدث PreToolUse إلا قرارًا وإعادة كتابة للمُدخَل. والحارس المسجَّل هناك سيكلّف بدء عملية في كل استدعاء أداة وقد لا يوصل شيئًا، لذا تبقى حُرّاس الكتابة والتعديل والصدفة، وفحص AskUserQuestion، وبروتوكول نهاية الجلسة، على الأدوات التي توصلها. وسيسجّل Apothem حارسًا على حدث في Devin حالما تُظهر الوثائق، أو اختبار استقصائي، أنه يصل إلى النموذج.

هذه خطّافات Devin Local. أما الوضع الأقدم Cascade فيقرأ صيغة خطّافات مختلفة (.devin/hooks.json)، لا يكتبها التثبيت.

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

يسمّي كل أمر مسجَّل المُفسِّر الذي عثر عليه Apothem حين عمل، والمسار المطلق للمشروع، لذا فهو خاص بالجهاز. ولهذا يكتب التثبيت الملف المحلّي ولا يكتب أبدًا الملف المشترك <project>/.devin/config.json، ولا الملف المستقل .devin/hooks.v1.json، ولا إعدادات .claude/. ولا يعدّل التثبيت .gitignore. إذ يستبعد Devin ملفات إعداده المحلّية من git بنفسه (عبر .git/info/exclude)، لذا لا تتلقّى النسخة المسحوبة لدى زميلك أوامر تشير إلى جهازك؛ وتأكّد من أن .gitignore لديك يسرد .apothem/.

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

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

"/path/to/python" "/path/to/project/.apothem/support/windsurf/hooks/dispatch.py" --contract devin SessionStart

يربط --contract devin أسماء أدوات Devin المكتوبة بأحرف صغيرة (exec، وwrite، وedit، وread، وgrep، وglob) بالأسماء التي تختبرها معالِجات Apothem، ويُبقي المُخرَج بالمغلّف نفسه الذي يقرؤه Claude Code. ولا يُكتَب أي مُطابِق: فمُطابِق Devin تعبير نمطي، والمُطابِق المحذوف يطابق كل أداة، وSessionStart ليس فيه أداة تُطابَق.

أمور ينبغي فحصها بعد التثبيت

• لا يُشغِّل Devin أي خطّاف ما دامت مساحة العمل في Restricted Mode. امنح مساحة العمل الثقة أولًا.
• لمعرفة ما إذا كانت الخطّافات قد حُمِّلت، افتح علامة التبويب Hooks في Customizations الخاصة بـ Devin Local، أو شغّل /hooks في Devin CLI. وكلاهما يسرد كل خطّاف مع ملفه المصدر.
• لا تسمّي وثائق Devin أي صدفة لأوامر الخطّافات على Windows. وتستخدم الأوامر اقتباس sh، الذي لن تحلّله PowerShell دون مُعامِل استدعاء. ولم يتحقّق Apothem مما يُشغِّله Devin Local على Windows؛ فإن لم تُحمَّل الخطّافات هناك، فأبلِغ عن ذلك في تذكرة (issue).

يُشغِّل Devin أيضًا الخطّافات التي كتبها Claude Code. يُحمِّل Devin الخطّافات في ~/.claude/settings.json و.claude/settings.json و.claude/settings.local.json ما دام read_config_from.claude مفعّلًا، وهو مفعّل افتراضيًا، إذ يعثر Devin Local على ملفاته بالطريقة نفسها التي تتبعها Devin CLI. وإن كنت قد ثبّتّ Apothem لـ Claude Code أيضًا، فقد تعمل مجموعتا الخطّافات كلتاهما. ويتشارك أمر SessionStart هنا ونسخته في Claude Code علامةً واحدة لكل جلسة في مجلّد حالة الخطّافات الخاص بـ Apothem، لذا يصمت أيّهما يعمل ثانيًا ويصل التمهيد إلى النموذج مرة واحدة؛ ويتعرّف Apothem على Devin من المتغيّر DEVIN_PROJECT_DIR الذي يضبطه Devin لخطّافاته. وتغطّي العلامة عشر ثوانٍ، لذا فإن بدءًا لاحقًا للجلسة نفسها يظل يوصل التمهيد. ويعمل عدّاد حجم السياق في كلا الموضعين، فتُبلَغ عتباته مبكرًا، ولا يُزيل Apothem تكرار العدّادات. ولتحميل هذه الخطّافات وحدها، اضبط "claude": false تحت "read_config_from" في إعداد المستخدم لديك (~/.config/devin/config.json، أو %APPDATA%\devin\config.json على Windows) أو في ملف .devin/config.json الخاص بالمشروع؛ وهذا يوقف أيضًا استيراد Devin لقواعد Claude Code ومهاراته وأوامره وخوادم MCP الخاصة به. ويطبع التثبيت هذا بوصفه ملاحظة.

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

إيقاف الخطّافات. اضبط APOTHEM_HOOKS_DISABLE=1 في بيئة Devin لإسكات خطّافات Apothem.

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

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

يبدأ الملف ببياناته الأمامية trigger: always_on، التي تضبط وضع تفعيل القاعدة. وتليها الكتلة التي يديرها Apothem؛ ويُحتفَظ بالنص الذي تضيفه بعد الكتلة في كل مزامنة.

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

سطح القواعد الحالي في Windsurf على نطاق المشروع تحت .devin/rules/ (الموقع المُفضَّل، الذي تكون له الأسبقية على الموقع الاحتياطي .windsurf/rules/ المُبقى للتوافق مع الإصدارات السابقة). سير العمل والذكريات المحلّية للجهاز يملكها المُشغِّل؛ ولا يكتبها Apothem، ولا يكتب ملف خطّافات Cascade ولا إعداد Devin المشترك. ولا تُكتَب صيغة الملف الواحد .windsurfrules عن قصد.

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

التحقّقCopy Anchor Link

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

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

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

التحديثCopy Anchor Link

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

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

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

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

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

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

ويُزيل إلغاء التثبيت أيضًا ملفات العوامل الفرعية التي كتبها في <project>/.devin/agents/ ويُبقي أي ملف آخر هناك؛ ويُزال المجلّد حين يبقى فارغًا. ويُزيل معالِجات خطّافات Apothem من <project>/.devin/config.local.json، متعرّفًا عليها من مسار المُوزِّع في أمرها، ويُبقي خطّافاتك ومفاتيحك الخاصة. ولا يُحذَف الملف إلا حين يكون Apothem قد أنشأه ولا يتبقى فيه شيء آخر. وتُزال كذلك سكربتات الخطّافات في <project>/.apothem/support/windsurf/hooks/. ويُزيل مجلّدات المهارات التي كتبها في ~/.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 — اسرد المحوّلات وافحصها من واجهة سطر الأوامر