CodeBuddy

المورّد: Tencent اسم التثبيت: codebuddy الحالة: إتاحة عامة الإعداد الأصلي: <project>/.codebuddy/rules/apothem-rules.md

التثبيتCopy Anchor Link

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

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

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

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

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

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

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

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

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

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

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

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

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

لا تُكتَب إلا أسماء الأدوات التي تُظهرها وثائق CodeBuddy. إذ تسرد صفحة الإعدادات فيها الأدوات، وتسمّي صفحة العوامل الفرعية أداة إضافية واحدة، تتضمّنها القائمة أدناه:

Read, Grep, Glob, Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch,
Agent, Task, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate,
AskUserQuestion, ExitPlanMode, LSP, Skill, SlashCommand

الأداة التي يسمّيها المصدر وليست في تلك القائمة (مثل PowerShell أو TodoWrite) تُستبعَد من الحقلين كليهما. والأداة ذات النمط، مثل Bash(rm *)، ليس لها شكل في قائمة مفصولة بفواصل: فبوصفها أداة مسموحًا بها تُستبعَد، وبوصفها أداة محظورة تحظر الأداة كلها. والمساعِد الذي لا يستطيع تعديل الملفات يُبقي ذلك القيد: فلا يسرد Write أو Edit بين أدواته ويحظرهما كليهما. ولا يكتب التثبيت أي مفتاح model، لذا يعمل المساعِد على النموذج الذي يختاره CodeBuddy، ولا يكتب مفتاح permissionMode ولا hooks.

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

• ملفات العوامل الفرعية ملفات مشروع عادية. أودِعها مع المشروع أو أدرِج .codebuddy/agents/ في .gitignore؛ ولا يختار Apothem نيابةً عنك.
• يُحمِّل CodeBuddy ملفات العوامل الفرعية المضافة يدويًا في بداية الجلسة التالية، لذا ابدأ جلسة جديدة بعد التثبيت.
• الملف الخاص بك الذي يحمل اسم مساعِد من Apothem يُحفَظ تحت ~/.apothem/backups/ ثم يُستبدَل. ولا يُعيده إلغاء التثبيت. ولا تُمَسّ الملفات ذات الأسماء الأخرى أبدًا.
• تُظهر صفحة Subagents الخاصة ببيئة التطوير (IDE) في CodeBuddy مفاتيح لا تسردها صفحة واجهة سطر الأوامر، ولم يتحقّق Apothem من أن بيئة التطوير تقبل disallowedTools أو maxTurns.

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

يُشغِّل CodeBuddy الخطّافات من المفتاح hooks في ملفات إعداداته، وفق وثائق الخطّافات في CodeBuddy، التي تصف الخطّافات بأنها تجريبية (Beta). ويسجّل التثبيت خطّافين:

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

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

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

يسمّي كل أمر مسجَّل المُفسِّر الذي عثر عليه Apothem حين عمل، والمسار المطلق للمشروع، لذا فهو خاص بالجهاز. ولهذا يكتب التثبيت الملف المحلّي ولا يكتب أبدًا الملف المُودَع <project>/.codebuddy/settings.json. ولا يعدّل التثبيت .gitignore: تأكّد من أن ملفك يسرد .codebuddy/settings.local.json و.apothem/، حتى لا تتلقّى النسخة المسحوبة لدى زميلك أوامر تشير إلى جهازك.

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

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

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

لا يغيّر --contract codebuddy شيئًا في المُخرَج: إذ يقرأ CodeBuddy المغلّف نفسه الذي يقرؤه Claude Code. ويُشغِّل CodeBuddy أوامر الخطّافات عبر الصدفة لديك، وعبر Git Bash على Windows (فهو لا يدعم cmd.exe ولا PowerShell)، لذا تستخدم الأوامر اقتباس bash ومسار مُفسِّر بشرطات مائلة أمامية. ثبّت Git for Windows إن طلبه CodeBuddy.

راجِع الخطّافات بعد أن يعمل التثبيت. يلتقط CodeBuddy لقطة من إعداداته عند بدء التشغيل، ولا يُحمِّل فوريًا ملف إعدادات كتبته أداة أخرى، ولا يطبّق الخطّافات المضافة من الخارج إلا بعد أن تراجعها في لوحة /hooks الخاصة به. وبعد apothem install (وبعد أي تحديث يغيّر الخطّافات)، أعد تشغيل CodeBuddy وأكّد مُدخلات Apothem في /hooks. ويطبع التثبيت هذا بوصفه ملاحظة. ولا تقول الوثائق ما إذا كانت المراجعة تتكرّر بعد كل تغيير، لذا افتح /hooks مجدّدًا بعد أي تحديث.

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

إيقاف الخطّافات. اضبط APOTHEM_HOOKS_DISABLE=1 في بيئة CodeBuddy لإسكات خطّافات Apothem، أو اضبط الإعداد disableAllHooks الخاص بـ CodeBuddy نفسه لتعطيل كل الخطّافات.

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

يقرأ المحوّل الملف التعريفي المشترك لـ Apothem ويُجسِّد ملف قواعد المشروع في كل تشغيل لـ apothem install أو apothem update. يقرأ CodeBuddy كل ملف *.md تحت .codebuddy/rules/ بوصفه Markdown مع بيانات أمامية YAML اختيارية (alwaysApply، وpaths، وenabled) وفق وثائق CodeBuddy Rules؛ ويحمل ملف Apothem القيمة alwaysApply: true بحيث يسري سطح الحوكمة في كل تفاعل. البيانات الأمامية هي أول محتوى في الملف، وتليها الكتلة التي يديرها Apothem؛ ويُحتفَظ بالنص الذي تضيفه بعد الكتلة في كل مزامنة. الملف التعريفي المشترك هو مصدر الحقيقة؛ وتُنسَخ التعديلات المحلية للمشروع على الملف المُولَّد احتياطيًا قبل أن تستبدل المزامنة التالية المحتوى الذي يديره Apothem.

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

سطح القواعد في CodeBuddy مقصور على نطاق المشروع تحت .codebuddy/rules/. يكتب المحوّل ملفًا مخصّصًا هو apothem-rules.md يتعايش مع أي ملفات قواعد يؤلّفها المُشغِّل في الدليل نفسه. ملف ذاكرة المشروع CODEBUDDY.md، والملف المُودَع .codebuddy/settings.json، و.mcp.json الخاص بالمشروع (خوادم MCP) ملك للمُشغِّل؛ ولا يكتبها Apothem. يوثّق CodeBuddy أيضًا أوامر الشرطة المائلة؛ ولا يكتب المحوّل أيًّا منها، بل يُشير إلى تلك الانضباطات داخل ملف القواعد بدلًا من ذلك. لكنه يكتب فعلًا عوامل فرعية وخطّافين في المشروع (راجع العوامل الفرعية والخطّافات)، ويكتب المهارات، وأوامر Apothem بوصفها مهارات، في مجلّد المستخدم لديك (راجع الملفات خارج المشروع). حين لا يحتوي مشروع على CODEBUDDY.md، يقرأ CodeBuddy Code الملف AGENTS.md بوصفه ذاكرة المشروع، لذا يصل إلى CodeBuddy أيضًا أي ملف AGENTS.md يكتبه محوّل آخر. اصطلاحات سطح المورّد التي يعتمد عليها المحوّل مُثبَّتة في src/apothem/harnesses/codebuddy/STANDARD-CONVENTION-PIN.md، ملتقَطة بوصفها لقطة مقابل وثائق CodeBuddy الحيّة.

يوثّق CodeBuddy المجلّد ~/.codebuddy/skills/ لمهارات المستخدم ولا يذكر ~/.agents/skills/، لذا يكتب التثبيت مجلّد CodeBuddy لا المجلّد المشترك بين الأدوات. ولا يقرأ ذلك المجلّدَ إلا CodeBuddy. وتسرد صفحة المهارات فيه disable-model-invocation، وuser-invocable، وallowed-tools، ولا تسرد أي مفتاح metadata أو argument-hint؛ ولم يتحقّق Apothem من أن CodeBuddy يقبلهما.

التحقّقCopy Anchor Link

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

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

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

التحديثCopy Anchor Link

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

يُعيد اشتقاق ملف قواعد المشروع من الحالة الراهنة للملف التعريفي المشترك. install وupdate عمليتان لا يتغيّر أثرهما بالتكرار — إذ تكتب إعادة التشغيل فوق الملف المُدار بأحدث محتوى مُجسَّد.

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

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

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

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

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