Kiro

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

التثبيتCopy Anchor Link

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

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

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

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

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

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

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

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

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

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

ملفات العوامل المخصّصةCopy Anchor Link

يقرأ Kiro العاملَ المخصّص من ملف Markdown في <project>/.kiro/agents/، وفق وثائق العوامل المخصّصة في Kiro. ويكتب التثبيت ملفًا واحدًا لكل مساعِد من Apothem في ذلك المجلّد، الأربعة عشر جميعًا. وهو يستهدف Kiro IDE 1.0 وKiro CLI V3 (kiro-cli --v3)، وهما الإصداران اللذان يقرآن صيغة Markdown. ولا يكتب أي ملف تعريف JSON ولا أيًّا من مفاتيح CLI 2.x الأقدم، لأن V3 يتخطّى ملف تعريف JSON يحوي allowedTools دون كتلة permissions. وهو يثبّت للمشروع فقط: فلا يُكتَب مجلّد المستخدم ~/.kiro/agents/.

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

لدى Kiro قائمة واحدة للأدوات، لذا تصبح الأدوات المسموح بها للمساعِد والمحظورة عليه تلك القائمة. والفئات هي read، وwrite، وshell، وweb، وsubagent:

الأداة التي لا فئة لها (TodoWrite، وMonitor، وArtifact، وTaskCreate، وTaskUpdate، ومُدخَل MCP) تُستبعَد. وتُستبعَد الفئة حين تُحظَر على المساعِد أي أداة فيها، لذا لا يكتسب المساعِد أبدًا أداةً حُظِرت عليه: فالمساعِد الذي لا يستطيع تعديل الملفات لا يحصل على الفئة write. والمساعِد الذي تسقط كل أدواته المسموح بها يُكتَب مع tools: []، كي لا يُمنَح كل الأدوات. ويحمل مساعِدان (mcp-builder وrefactor-surgeon) الفئة write، وتسعة يحملون shell، وثلاثة يحملون web. ولا يكتب التثبيت أي مفتاح model، لذا يعمل المساعِد على النموذج الذي يختاره Kiro، ولا أيًّا من permissions، وexcludedTools، وresources، وmcpServers، وhooks.

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

• لا يُحمِّل Kiro ملفات العوامل المخصّصة لمساحة عمل حتى تمنح مساحة العمل الثقة. ويسأل Kiro CLI 2.33 وما بعده "Trust this workspace?" في المرة الأولى التي تبدأ فيها جلسة V3 تفاعلية في مجلّد. فإن لم يسرد Kiro أيًّا من المساعِدات، فامنح المجلّد الثقة وابدأ جلسة جديدة.
• لم يتحقّق Apothem مما إذا كان Kiro CLI 2.x يُحمِّل عامل Markdown بصيغة V3. استخدم بيئة التطوير المتكاملة، أو شغّل kiro-cli --v3.
• ملفات العوامل ملفات مشروع عادية. أودِعها مع المشروع أو أدرِج .kiro/agents/ في .gitignore؛ ولا يختار Apothem نيابةً عنك.
• الملف الخاص بك الذي يحمل اسم مساعِد من Apothem يُحفَظ تحت ~/.apothem/backups/ ثم يُستبدَل. ولا يُعيده إلغاء التثبيت. ولا تُمَسّ الملفات ذات الأسماء الأخرى أبدًا، بما فيها ملفات تعريف JSON.
• تختلف صفحات Kiro في ما إذا كان العامل المخصّص يرى المهارات في ~/.kiro/skills/ افتراضيًا: فصفحة المهارات تقول إن العامل يحتاج إلى مورد skill://، بينما يقول مرجع الإعداد إن العامل يرث المهارات الافتراضية. ولا يضيف التثبيت أي مفتاح resources، لذا لا ترى المساعِدات المهارات إلا إذا صحّت القراءة الثانية.
• تسرد صفحة الأدوات المدمجة في Kiro الأدوات التي تتضمّنها كل فئة عادةً. وتتضمّن الفئة read أداتَي البحث عن الملفات والبحث في النصوص (glob وgrep في CLI 2.x)، ولهذا يُربَط Glob وGrep بها. وتتضمّن أيضًا code (تحليل الشيفرة بشجرة الصياغة) وintrospect (تجيب عن أسئلة حول Kiro نفسه)، لذا يستطيع المساعِد الذي يحمل read استخدام كلتيهما. وتسرد الصفحة code تحت write أيضًا، ولا تقول ما إذا كانت الأداة تعدّل الملفات.
• لم يتحقّق Apothem مما يفعله Kiro بمفتاح tools محذوف، ولا من مفاتيح البيانات الأمامية التي يشترطها Kiro إلى جانب name.

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

يُشغِّل Kiro الخطّافات من ملفات JSON في <project>/.kiro/hooks/، وفق وثائق الخطّافات في Kiro. ويكتب التثبيت ملفًا واحدًا هناك، apothem.json (إصدار ملف الخطّافات v1)، فيه خطّاف واحد:

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

لا يسجّل Apothem أي خطّاف PreToolUse أو PostToolUse على Kiro. إذ يضيف Kiro مُخرَج الأمر إلى سياق النموذج للحدثين SessionStart وUserPromptSubmit فقط، ويتجاهله لأحداث الأدوات. والحارس المسجَّل على حدث أداة سيكلّف بدء عملية في كل استدعاء أداة ولا يوصل شيئًا، لذا تبقى حُرّاس الكتابة والتعديل والصدفة، وتنبيه حجم السياق، وبروتوكول نهاية الجلسة، على الأدوات التي توصلها. ولا يكتب التثبيت أي خطّاف للحدث UserPromptSubmit، ولا يكتب أي خطّاف في مجلّد المستخدم ~/.kiro/hooks/.

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

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

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

يجعل --contract kiro المُوزِّعَ يطبع السياق نصًّا عاديًا، وهو ما يضيفه Kiro إلى السياق للحدث SessionStart. ولا يوثّق Kiro أي صدفة لإجراءات الأوامر على Windows. والأمر مكتوب لـ sh وcmd.exe، مع مسار مُفسِّر بشرطات مائلة أمامية بين علامتَي اقتباس؛ فإن شغّله Kiro تحت PowerShell على جهازك، احتاج المسار المقتبس إلى مُعامِل استدعاء (&) أمامه، ويمكنك إضافته يدويًا.

امنح مساحة العمل الثقة. لا يُحمِّل Kiro CLI 2.33 وما بعده خطّافات مساحة العمل إلا بعد أن تمنح مساحة العمل الثقة: إذ يسأل "Trust this workspace?" في المرة الأولى التي تبدأ فيها جلسة V3 تفاعلية (kiro-cli --v3) في مجلّد. ولا تُشغِّل جلسات Kiro Web أي خطّافات. ويطبع التثبيت هذا بوصفه ملاحظة.

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

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

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

إيقاف الخطّاف. اضبط APOTHEM_HOOKS_DISABLE=1 في بيئة Kiro لإسكات خطّاف Apothem. ويُعيد التحديث كتابة مُدخَل Apothem، لذا لا يدوم أي تعديل عليه، مع استثناء واحد: اضبط عليه "enabled": false، الذي يوثّقه Kiro بوصفه تخطّيًا للخطّاف دون حذفه، ويُبقي التحديث على ذلك.

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

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

يبدأ الملف بالبيانات الأمامية inclusion: always الخاصة به، لأن Kiro يشترط أن يكون إعداد التضمين أول محتوى في الملف. وتليها الكتلة التي يديرها Apothem؛ ويُحتفَظ بالنص الذي تضيفه بعد الكتلة في كل مزامنة.

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

سطح التوجيه في Kiro على نطاق المشروع تحت .kiro/steering/. يكتب المحوّل ملف توجيه مخصّصًا apothem-rules.md يحمل البيانات الأمامية inclusion: always، ولا يطمس أبدًا ملفات الأساس في Kiro التي ألّفها المُشغِّل (product.md، وtech.md، وstructure.md). مواصفات Kiro (.kiro/specs/) يملكها المُشغِّل؛ ولا يكتبها Apothem. ويكتب ملف خطّافات واحدًا، .kiro/hooks/apothem.json، ولا يكتب أي ملف آخر في .kiro/hooks/.

يوثّق Kiro المجلّد ~/.kiro/skills/ للمهارات العامة ولا يذكر ~/.agents/skills/، لذا يكتب التثبيت مجلّد Kiro لا المجلّد المشترك بين الأدوات. وتتغلّب مهارة مساحة العمل التي تحمل الاسم نفسه على المهارة العامة. ولم يتحقّق Apothem من كيفية تعامل Kiro مع مفتاح ترويسة في SKILL.md لا يسرده.

التحقّقCopy Anchor Link

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

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

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

التحديثCopy Anchor Link

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

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

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

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

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

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

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