الخطّافات

تنطلق الخطّافات عند أحداث الأدوات وتُحمِّل سياقات رسائل يعاملها المساعد بوصفها مُوجِّهات نظام إضافية. ويعيش التوصيل في كتلة الخطّافات في settings.json الخاص بـ Claude Code (تثبيت المحرّك) أو في hooks.json الخاص بالإضافة (تثبيت الإضافة)، وفي ملف الخطّافات hooks.json الخاص بـ Codex، وفي خريطة الخطّافات في settings.json الخاص بـ Qwen Code، وفي مفتاح الخطّافات في .codebuddy/settings.local.json الخاص بـ CodeBuddy (SessionStart وPostToolUse فقط)، وفي ملف خطّافات Kiro .kiro/hooks/apothem.json (SessionStart فقط)، وفي ملف خطّافات GitHub Copilot .github/hooks/apothem.json (sessionStart وpostToolUse فقط)، وفي مفتاح الخطّافات في .devin/config.local.json الخاص بـ Windsurf (Devin Local) (SessionStart وPostToolUse فقط)، وفي ملف خطّافات المشروع الخاص بـ Cursor .cursor/hooks.json (sessionStart فقط).

المُوزِّعCopy Anchor Link

تستدعي مُدخَلات الخطّافات التي يثبّتها المحرّك المُوزِّعَ عبر المسار المطلق للبرنامج النصّي، مع مُفسِّر يُحَلّ وقت التثبيت. وتحمل القوالب الرمزين ${PYTHON_BIN} و${HARNESS_ROOT}، اللذين يُصيِّرهما المُثبِّت وقت التثبيت. يُجسِّد Claude Code وQwen Code المُوزِّع تحت <harness-root>/.apothem/support/hooks/؛ وCodex تحت <harness-root>/hooks/. تستخدم مُدخَلات Claude Code صيغة التنفيذ المباشر (command مع args)، فلا تحتاج إلى صدفة. وتُشغِّل إضافة Claude Code كل خطّاف بالصيغة bash "${CLAUDE_PLUGIN_ROOT}/lib/apothem/hooks/lib/bootstrap.sh" <event> [<message-file> ...]، في صدفة الخطّافات الافتراضية لـ Claude Code (sh على macOS وLinux، وGit Bash على Windows)؛ ويعثر برنامج التمهيد على مُفسِّر Python 3.10+ ويُشغِّل المُوزِّع المُحزَّم. ويُخزِّن المُفسِّرَ الذي عثر عليه مؤقتًا في interpreter-path (interpreter-path-ps1 لـ bootstrap.ps1) تحت دليل حالة الخطّافات (أدناه) ويُعيد استخدامه ما دام المُفسِّر لا يزال موجودًا، فيجري فحص PATH مرة واحدة بدلًا من أن يجري قبل كل استدعاء أداة؛ احذف ملف التخزين المؤقت لفرض فحص جديد. ولا يُعتَدّ إلا بدليل حالة مطلق وبمسار مُخزَّن مطلق.

يُسجِّل كل سطح مُدخَل مُوزِّع واحدًا لكل حدث ومُطابِق، يسرد كل رسالة يُقيِّمها ذلك المُطابِق: عملية واحدة تقرأ الحمولة مرة واحدة، وتُشغِّل كل حارس، وتُجيب بغلاف واحد، فتبدأ عملية Write مُوزِّعًا واحدًا بدلًا من واحد لكل حارس. ويُشغِّل تثبيت المحرّك لـ Claude Code أيضًا بوابة المطابقة (gate.py --hook) على Write وEdit بوصفها مُدخَلًا مستقلًا. وعلى Windows من دون Git for Windows، استخدم تثبيت المحرّك (apothem install --harness claude-code)، الذي لا تحتاج خطّافاته ذات صيغة التنفيذ المباشر إلى صدفة. المُوزِّع برنامج نصّي مستقل يعتمد على المكتبة القياسية وحدها: فهو يُمهِّد sys.path الخاص به، فلا حاجة إلى حزمة apothem قابلة للاستيراد على المضيف. ومن نسخة مسحوبة من المصدر، تُشغِّل صيغة الوحدة python -m apothem.hooks.dispatch <event> (مع PYTHONPATH=src) الشيفرة نفسها لأغراض التطوير. ويُحمِّل المُوزِّع hooks/lib/resolve_root.py لحلّ جذر المنظومة، ويُفوِّض إلى hooks/emit_hook_context.py وhooks/session_start_bootstrap.py.

عقود المورّدينCopy Anchor Link

يُشغِّل إطار العمل الذي ليس Claude Code المُوزِّعَ نفسه مع --contract <id> بعد البرنامج النصّي، مثلًا "<python>" "<project>/.apothem/support/hooks/dispatch.py" --contract codebuddy SessionStart. ويُترجِم العقد (hooks/lib/vendor_contract.py) تهجئات المورّد للأحداث وأسماء الأدوات ومفاتيح الحمولة إلى شكل Claude الذي تقرؤه المُعالِجات، ويُعيد كتابة الغلاف إلى الشكل الذي يقرؤه المورّد، ويُسقِط الحدث الذي لا يُسلِّمه المورّد إلى النموذج. ومن دون الراية لا يُترجَم شيء ويكون الخرج غلاف Claude، بايتًا ببايت. والراية جزء من سطر الأوامر المُوثَّق للمُوزِّع: dispatch.py [--contract <id>] <Event> [<message> ...].

يُثبِّت مُحوّلٌ من Apothem اليوم العقودَ codebuddy وcopilot وcursor وdevin وkiro (devin يُثبِّته محوّل Windsurf)؛ ويُثبِت العقد claude أن سطر الأوامر الافتراضي لم يتغيّر. ويبقى المُوزِّع استشاريًا في ظل كل عقد: لا يحمل أي شكل إذنًا، ولا قرارًا، ولا حظرًا، ولا دخل أداة مُعادًا كتابته.

يُحمِّل Cursor وDevin Local الخطّافات التي تحملها ملفات إعدادات Claude Code إلى جانب خطّافاتهما، لذا قد تعمل مجموعتان عند وجود تثبيت Apothem لـ Claude Code على الجهاز نفسه. ويُسلَّم تمهيد SessionStart مرة واحدة: يتشارك أمر المورّد الخاص (--contract cursor أو --contract devin) ونسخة Claude Code، وهي سطر الأوامر الافتراضي، علامةً واحدة لكل جلسة ومصدر في دليل حالة الخطّافات، وأيّهما يعمل ثانيًا يبقى صامتًا. ولا يشارك سطر الأوامر الافتراضي إلا عندما تُسمّي بيئة العملية المضيف (CURSOR_PROJECT_DIR أو CURSOR_VERSION أو DEVIN_PROJECT_DIR)؛ وفي ظل Claude Code وCodex وQwen Code لا يقرأ العلامة أبدًا. وتسري العلامة عشر ثوانٍ، فيظل بدء لاحق للجلسة نفسها، مثل ضغط ثانٍ، يُسلِّم سياق استعادته. ولا يُزال تكرار أي عدّاد لـ PostToolUse، لذا يعمل عدّاد حجم السياق في الموضعين ويبلغ عتباته مبكرًا. ويطبع التثبيت ملاحظة تُسمّي مفتاح المورّد لإيقاف الاستيراد (في Cursor: "Include Third-Party Plugins, Skills, and Other Configs"؛ وفي Devin: read_config_from.claude).

لا يُسجَّل أمر إلا حيث يُسلِّم المورّد خرجه إلى النموذج. يُضيف Kiro الخرج القياسي للخطّاف إلى السياق لـ SessionStart وUserPromptSubmit فقط، لذا يُسجِّل ملف Kiro الحدث SessionStart وحده. ويقرأ Copilot القيمة additionalContext من sessionStart وpostToolUse ولا يقرأ من preToolUse إلا حقول الأذونات، لذا يُسجِّل ملف Copilot هذين الحدثين، بأسمائهما بصيغة camelCase، ولا يُسجِّل أي حارس. ويحمل كل مُدخَل في Copilot أمرًا لـ bash وأمرًا لـ powershell. وكلا الملفين مملوك لـ Apothem ويُسمّي المُفسِّر ومسار المشروع على الجهاز الذي أجرى التثبيت؛ وتشرح صفحات أُطر العمل ما يعنيه ذلك لملف يُودِعه مستودع.

يقرأ Devin Local القيمة additionalContext من SessionStart وUserPromptSubmit وPostToolUse ولا يُوثِّق شيئًا لـ PreToolUse، لذا يحمل تسجيل Windsurf الحدثين SessionStart وPostToolUse، من دون مُطابِق (مُطابِق Devin تعبير نمطي، والمُطابِق المحذوف يُطابِق كل أداة). ويُوضَع في ملف التجاوز المحلي .devin/config.local.json، الذي يُوثِّقه Devin بوصفه مُتجاهَلًا في git ويستثنيه من git بنفسه عبر .git/info/exclude. يُضيف خطّاف sessionStart في Cursor القيمة additional_context إلى السياق الأولي للمحادثة؛ وتُسجِّل النسخة الأولى ذلك الحدث وحده. والملف .cursor/hooks.json في Cursor هو ملف خطّافات المشروع الوحيد، لذا فهو ملك المُشغِّل: يدمج التثبيت فيه مُدخَلًا واحدًا، ويحتفظ بمُدخَلات المُشغِّل ومفاتيحه، ويرفض ملفًا لا يستطيع إعادة كتابته من دون فقد، ويُميِّز مُدخَله الخاص بمسار المُوزِّع في الأمر. ويُشغِّل تطبيق سطح المكتب لـ Cursor أوامر الخطّافات عبر PowerShell على Windows، لذا يبدأ الأمر على مضيف Windows بـ & .

عبر الملفات الخمسة كلها، يكون المُدخَل لـ Apothem عندما يُشغِّل أمره .apothem/support/[<harness>/]hooks/dispatch.py مع --contract <id>، أيًّا كان مسار المشروع الذي كُتب تحته. لذا يحتفظ المشروع المُعاد تسميته أو المنقول أو المُستنسَخ بمجموعة واحدة من المُدخَلات، ولا يُستبدَل خطّاف من خطّافاتك أو يُزال أبدًا، مثل hooks/dispatch.py في شجرتك الخاصة أو python -m apothem.conformity.gate. ويُبلِغ apothem verify عن غياب التسجيل حالما لا يبقى في الملف أي مُدخَل من مُدخَلات Apothem، ويُبلِغ إلغاء التثبيت الذي لا يستطيع قراءة الملف عنه بوصفه مُتخطًّى. ويُرفَض عند التثبيت مسار المشروع أو المُفسِّر الذي يحتوي على $ أو علامة اقتباس خلفية أو علامة اقتباس مزدوجة أو شرطة مائلة عكسية، مع تسمية المسار، لأن الأمر المُقتبَس سيُشغِّل ملفًا مختلفًا.

سياقات الرسائلCopy Anchor Link

تعيش سياقات Markdown لكل حدث تحت src/apothem/hooks/messages/:

• دورة حياة الجلسة: sessionstart.md، وskill-index.md، وprecompact.md، وpostcompact.md، وstop.md، وposttooluse-proactive-compaction.md
• استدعاءات الصدفة: pretooluse-bash.md، وpretooluse-bash-plan-guard.md
• كتابة الملفات: pretooluse-write.md، وpretooluse-edit.md، وpretooluse-notebookedit.md، وpretooluse-write-plan-guard.md، وpretooluse-write-header-guard.md، وpretooluse-edit-header-guard.md، وpretooluse-conformity.md
• حرّاس على المحتوى: pretooluse-dependency-guard.md، وpretooluse-eval-guard.md
• الأسئلة: pretooluse-askuserquestion-recommended.md

على Claude Code، يُسلِّم خطّافُ SessionStart الملفَّ postcompact.md عندما تُستأنَف الجلسة بعد الضغط، لأن Claude Code لا يُمرِّر مُخرَجات خطّاف PreCompact أو PostCompact إلى المساعد.

الملف skill-index.md مُولَّد، لا مكتوب: يُصيِّره scripts/dev/generate_skill_index.py من فهرس المهارات والأوامر، سطرًا واحدًا لكل مجموعة مهام، مع عرض المهارات اليدوية بالصيغة /apothem:<name>. وعلى Claude Code يُضيفه خطّاف SessionStart إلى سياق الجلسة عندما يكون الملف موجودًا. وهو موجود لأن Claude Code يُسقِط أوصاف المهارات من قائمته حالما تتجاوز القائمة ميزانيتها من الأحرف، ويُبقي الفهرس كل مهارة قابلة للعثور عليها بحسب المهمة. ويعرض تثبيت الإضافة المهارات اليدوية بالصيغة /apothem:<name>؛ ويُسقِط تثبيت المحرّك البادئة. ويبقى النص دون 1,600 حرف، ويُخفِق generate_skill_index.py --check عندما لا يعود الملف المُودَع مطابقًا للفهرس.

عندما يعمل Apothem بوصفه إضافة لـ Claude Code وحدها، لا يُحمَّل أي ملف قواعد عند الإطلاق. فيُضيف خطّاف SessionStart حينئذٍ مؤشّرًا قصيرًا إلى الدليل المُحزَّم rules/. وإذا كان ذلك الدليل يحتوي على apothem-rule-index.md، فإن المؤشّر يُخبر الجلسة أيضًا بأن تقرأ القواعد الأساسية الأربع أولًا، لأن لا شيء يُحمِّلها في هذا الوضع (agnostic-posture، وauthority-inquiry، وsession-closure، وcontext-management)، ويُسمّي الفهرس، الذي يقول أي قاعدة تُقرأ لأي مهمة. ولا يُدرَج نص الفهرس مضمّنًا.

عندما يحتوي المشروع على قاعدة معرفة صنعتها مهارة knowledge-wiki، يُقارن خطّاف SessionStart بصمتها بالبصمة المُسجَّلة عند آخر خطّ أساس، وإذا اختلفتا، يُضيف سطرًا واحدًا يقترح وضع الانجراف في المهارة (--mode drift --kb <path>). والبصمة هي عدد الصفحات مع أحدث مُدخَل في السجل؛ والنسخة المُسجَّلة هي أحدث سطر baseline في log.md الخاص بالقاعدة، الذي لا يكتبه إلا وضع الانجراف. ويفحص الخطّاف أربعة مسارات تحت جذر المشروع، بالترتيب: knowledge-base/، وwiki/، وdocs/knowledge-base/، وdocs/wiki/، ولا يعتدّ إلا بدليل يحتوي على index.md وlog.md كليهما. والمشروع الذي لا يحتوي على قاعدة يدفع أقل من جزء من الألف من الثانية. ومع وجودها، يقرأ الخطّاف على الأكثر آخر 256 KiB من log.md ويسرد ثلاثة أدلّة مسطّحة؛ ولا يجتاز الشجرة أبدًا ولا يكتب أبدًا. ويحمل السطر مسارًا ثابتًا، وتاريخًا، وعددَي صفحات، ولا يحمل أبدًا نصًّا من القاعدة. ويبقى صامتًا عندما لا توجد قاعدة، أو لا يوجد خطّ أساس، أو لا يوجد تغيير، أو يوجد ملف لا يستطيع قراءته، ويتكرّر في كل جلسة إلى أن يُسجِّل وضع الانجراف خطّ أساس جديدًا. والقاعدة الموجودة في أي مسار آخر تعمل في كل أوضاع المهارة لكنها لا تحصل على سطر عند بدء الجلسة.

يُحمِّل المُوزِّع كل ملف سياق عندما ينطلق حدثه وتكون وسيطة سياقه مُسجَّلة في ملف الإعدادات. ويُزال سطر تعليق الترخيص وقسم ## Bindings الختامي قبل أن يصل النص إلى المساعد؛ فكلاهما موجود للمشرفين ولبوابة المطابقة.

الحارس الذي لا يجد شيئًا لا يحقن شيئًا. والحارس الذي ينطلق لا يحقن إلا قسم ## Advisory من رسالته، مملوءًا بما وجده (المسار، والمُعرِّف، والبدائية)، متبوعًا بـ Full procedure: <message-file>. وبقية الملف هي الإجراء الكامل، الذي لا يقرؤه المساعد إلا عندما يحتاج إلى التفاصيل. وتحكم الحرّاس على "داخل المشروع" قياسًا إلى جذر git فوق دليل العمل لاستدعاء الأداة، ولا تحكم أبدًا قياسًا إلى الشجرة التي ثُبِّت فيها الخطّاف.

عقد وقت التشغيلCopy Anchor Link

يفي كل أمر خطّاف مُسجَّل بالعقد نفسه، الذي يفحصه tests/hooks/test_hook_contract.py على الإضافة، وعلى تثبيت المحرّك لـ Claude Code، وعلى Codex، وعلى Qwen Code، وعلى تثبيت CodeBuddy (تُفحَص ملفات Kiro وCopilot وCursor وWindsurf قياسًا إلى عقودها بواسطة tests/hooks/test_native_hook_registrations.py، وتُشغَّل كما يُشغِّلها المورّدون بواسطة tests/integration/test_native_hook_files_roundtrip.py، وtest_cursor_hooks_roundtrip.py، وtest_windsurf_hooks_roundtrip.py):

• يعمل من نسخة مسحوبة عادية. يخرج بالرمز 0، ويكون الخرج القياسي فارغًا أو كائن JSON واحدًا. ولا يعتمد أي خطّاف على بِتّ التنفيذ لملف.
• مُسجَّل مرة واحدة. لكل حدث ومُطابِق مُدخَل مُوزِّع واحد لكل سطح، يسرد كل رسالة يُقيِّمها، فلا يعمل حارس أبدًا مرتين على استدعاء أداة واحد.
• محدود. لا يتجاوز أي نص مُصدَر 10,000 حرف. ولا يتكلّم حارس الاعتماديات إلا عندما تستهدف الكتابة بيان اعتماديات أو ملف قفل، ولا يتكلّم حارس التقييم الديناميكي إلا عندما يحتوي المحتوى أو الأمر على بدائية تقييم أو إلغاء تسلسل غير آمن. وينطلق تنبيه الضغط مرتين على الأكثر لكل دورة ضغط.
• يستخدم القنوات التي يُسلِّمها إطار العمل. تنتقل توجيهات PreToolUse في hookSpecificOutput؛ ويُعيد حارس AskUserQuestion القيمة additionalContext، أو permissionDecision: deny في ظل الاشتراك الاختياري الصارم. يُهمِل Claude Code مُخرَجات PreCompact وPostCompact، لذا يصل سياق الاستعادة بعد الضغط على Claude Code مع حدث SessionStart الذي يكون مصدره compact.
• لا يُشغِّل شيفرة المشروع أبدًا. يَحُلّ برنامج التمهيد شجرته المُثبَّتة الخاصة به ولا يأخذ أبدًا برنامجًا نصّيًا من المشروع المفتوح. وتُقرأ توجيهات بدء الجلسة من الشجرة المُثبَّتة؛ ولا يُقرأ دليل المشروع إلا لملخّصات الخطط والذاكرة ولفحص انجراف قاعدة المعرفة.
• يُخفِق بصورة مفتوحة. ملف الرسالة المفقود، أو المُفسِّر المفقود، أو الحالة التالفة يُنتِج الخروج بالرمز 0 وغلافًا صالحًا.

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

تعيش حالة الخطّافات لكل جلسة في دليل خاص بكل مستخدم يُنشأ بالوضع 0700: APOTHEM_HOOK_STATE_DIR عند ضبطه، وإلا ${CLAUDE_PLUGIN_DATA}/state لإضافة Claude Code، وإلا $XDG_STATE_HOME/apothem، وإلا ~/.local/state/apothem (%LOCALAPPDATA%\apothem\state على Windows).

جرد رسائل الخطّافات المُولَّدCopy Anchor Link