مخطط البيانات الأمامية
دليل مرجعي لبنية كتلة البيانات الأمامية بصيغة YAML، والمفاتيح المطلوبة لكل صنف، وقواعد الإنفاذ لدى المدقّقات عبر أصناف المُنتَجات.
مرجع معتمد للبيانات الأمامية بصيغة YAML في كل صنف من أصناف المُنتَجات. الملخّص في قسم الاصطلاحات من
CLAUDE.mdهو الإعلان المُضمَّن؛ أما مخططات JSON Schema لكل صنف فيsrc/apothem/schemas/(إذ يرفضadditionalProperties: falseفي مخططَي المهارات والأوامر المفاتيحَ غير المعروفة، بينما تُعلِن مخططات العوامل ونمط الإخراج والخطةadditionalProperties: true)، فهي العقد المقروء آليًا، وتكون لها الغلبة عند أي خلاف. هذه الصفحة هي فهرس المفاتيح المطلوبة، ويحملartifact-schema.mdxالقوالب والأمثلة المحلولة لكل صنف — وكلتاهما إسقاطان مقروءان للبشر لتلك المخططات.
1. شكل كتلة البيانات الأمامية
يحمل كل مُنتَج بيانات أمامية بصيغة YAML في رأسه، محدودة بسطرَي ---. وفي ملفات عائلة Markdown تكون البيانات الأمامية أول محتوى في الملف، ويلي سطرُ ترويسة SPDX المرجعي وفق site/content/docs/reference/authorship-header.mdx الفاصلَ --- الختامي.
تستخدم مفاتيح الأوامر صيغة kebab-case. وتستخدم مفاتيح المهارات صيغة kebab-case ما عدا userInvocable، وهي كتابة camelCase التي يستخدمها متن المصدر، ويُعيد تثبيت Claude Code تسميتها إلى user-invocable. وينقل تثبيت Claude Code وإضافته أيضًا المفاتيح الخاصة بـApothem وحده (version، وupdated، وarchetype، وportability) في المهارة أو الأمر إلى خريطة metadata: لاحقة من سلاسل نصية بين علامتَي اقتباس، بهذا الترتيب الثابت، لأن Claude Code يتجاهل المفاتيح العلوية غير المعروفة، ولأن معيار Agent Skills يحفظ المفاتيح الإضافية في metadata؛ أما ملفات المصدر وكل إطار عمل آخر فتُبقيها في المستوى العلوي، ما عدا مجلّدات المهارات المشتركة على مستوى المستخدم (~/.agents/skills/ والمجلّدات ~/.codebuddy/skills/، و~/.kiro/skills/، و~/.trae/skills/)، التي تطويها بالطريقة نفسها. أما مفاتيح القواعد والعمّال المُفوَّضين فهي بصيغة camelCase، كما يسرد جدول المفاتيح المطلوبة في القسم 2. والقيم المفردة إما مجرّدة وإما بين علامتَي اقتباس مزدوجتين؛ وتوضع بين علامتَي اقتباس القيم النصية التي تحتوي على نقطتين رأسيتين، أو علامات #، أو غيرها من المحارف ذات الدلالة في YAML.
2. الحقول المطلوبة لكل صنف
تختلف مجموعة المفاتيح المطلوبة باختلاف صنف المُنتَج. ويفرض الشكلَ المعتمد scripts/dev/validate_ecosystem.py ومخططاتُ JSON Schema لكل صنف تحت الدليل src/apothem/schemas/. لكلٍّ من أصناف المساعِدين والمهارات والأوامر وأنماط الإخراج والخطط ملف مخطط واحد، مدرَج أدناه؛ أما صنفا CLAUDE.md والقواعد فلا مخطط لهما، ويفحص validate_ecosystem.py مفاتيحهما. ملفات الخطط ليست في الجدول أدناه؛ وتُسرَد مفاتيحها في انضباط الخطط.
src/apothem/schemas/agent.schema.json
src/apothem/schemas/skill.schema.json
src/apothem/schemas/command.schema.json
src/apothem/schemas/output-style.schema.json
src/apothem/schemas/plan.schema.json| الصنف | المفاتيح المطلوبة |
|---|---|
CLAUDE.md (إعداد الجذر) | name، version، updated، description، scope، portability |
القواعد (src/apothem/rules/*.md) | name، description، pathFilter، alwaysApply |
الأوامر (src/apothem/commands/*.md) | name، version، updated، description، argument-hint، disable-model-invocation، portability، allowed-tools |
المساعِدون، ويُسمَّون أيضًا العمّال المُفوَّضين (src/apothem/agents/*.md) | name، version، updated، description، tools (اختياري: المساعِد الذي يحذفه يرث كل أداة؛ ولإعطاء مساعِدٍ يسرد tools خادمَ MCP، سمِّ الخادم في المفتاح agent_mcp_servers من الملف التعريفي)، disallowedTools، maxTurns، effort |
المهارات (src/apothem/skills/*/SKILL.md) | name، version، updated، description، archetype، userInvocable، disable-model-invocation، allowed-tools؛ ويُعيد تثبيت Claude Code وإضافته، ومجلّدات المهارات المشتركة على مستوى المستخدم، تسمية userInvocable إلى user-invocable، ويشترط المخطط أن تحمل كل مهارة تهجئة واحدة بالضبط من التهجئتين، لا الاثنتين معًا؛ ويكتب تثبيت Qwen Code الحقل allowed-tools في صورة قائمة allowedTools، وهو المفتاح والشكل اللذان يقرؤهما Qwen Code |
أنماط الإخراج (src/apothem/output-styles/*.md) | name، description؛ ويضبط كل نمط مشحون أيضًا keep-coding-instructions: true كي يحتفظ Claude Code بتعليماته الخاصة بهندسة البرمجيات |
تحمل المخططات لكل صنف في src/apothem/schemas/ مجموعة القيود الكاملة، بما فيها قيود النوع، والصيغة، والتعداد، والنمط، وحدود الطول: فحقل description في المهارة أو الأمر لا يتجاوز 1,024 محرفًا، وهو حدّ Agent Skills.
3. المدقّقات
يجتاز scripts/dev/validate_ecosystem.py شجرة المُنتَجات، ويطبّق مجموعات المفاتيح المطلوبة أعلاه، ويُبلِغ عن [FAIL] لأي مُنتَج ينقصه حقل مطلوب. ويفرض frontmatter-grep العامل عند كل كتابة في src/apothem/conformity/frontmatter_grep.py الشكل نفسه عند حدود خطّاف PreToolUse Write/Edit.
اصطلاحات التسمية
تحدّد أسماء الملفات بصيغة kebab-case، وتنسيق مفاتيح frontmatter، وتسمية الفروع بادئات النوع، ودلالات البادئات الرقمية لتسلسلات المُخرَجات المُرتَّبة.
اصطلاحات Markdown
توحيد نكهة Markdown، وبنية العناوين، وإعلانات لغة كتل الشيفرة المُسوَّرة، وصيغ الروابط الداخلية، وترويسات التأليف، والإنفاذ عبر المدقّقات.