Phase 13: Tools & Protocols

اكتشاف المهارات والكشف التدريجي

تصبح المهارة مفيدة قبل أن يتم تحميل جسمها. اسمها وصفها يحصلون على مكان في الكتالوج؛ ملفاتها العميقة يحصلون على السياق فقط عندما تصل المهمة إليهم.

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 13 · 22 (Agent Skills: Portable Contract and Runtime Boundary)

Time: ~105 minutes

أهداف التعلم

بناء خط أنابيب اكتشاف نظام الملفات التي تفصل النطاق والتحقق من التحقق من التحقق من النطاق، وسياسة الصدام، ونشر الكتالوج.
شرح مستويات الكشف الثلاثة: البيانات المعدنية الكتالوجية، والإرشادات النشطة، والموارد المحددة للمهمة.
إشارات التصميم بحيث يمكن للوكيل الوصول إلى التفاصيل المطلوبة مباشرة دون تحميل الحزمة بأكملها.
مساحة الكتالوجية الميزانية مستقلة عن سياق المهارات الفعالة.
رفض عبور المسار و إفراج الروابط عندما تقرأ المهارة مواردها الخاصة.

المشكلة

عميلك لديه 200 مهارة مثبتةSKILL.md، ملف المرجح، النص، والعرض في بداية الجلسة سوف تدفن المهمة الحالية في إجراء غير مرتبط. لا تحميل شيء سوف تجبر المستخدم على تذكر مسارات نظام الملفات الدقيقة.

التسوية المعتادة هي الكتالوج: عرض نموذج هوية صغيرة وصف التوجيه لكل مهارة مؤهلة، ثم تحميل الجسم الكامل فقط بعد الاختيار. وهذا يخلق مشاكل هندسية جديدة.

أولاً، لا يعد الاكتشاف مجرد بحث ملفات متكررة. يمكن أن توجد مهارات في المشاريع أو المستخدم أو المدير أو المكونات التضخمة أو المجالات المدمجة. يمكن أن تتشارك حزمتان اسمًا. يمكن أن يشير الرابط التوافقي إلى خارج الجذر الموثوق به. يمكن أن تستغرق حزمة غير مصممة مساحة الكتالوج أو تصبح مستحيلة الاستدعاء.

ثانياً، يمكن أن تصبح الكشف التدريجيّة إرتباكًا متدريّداً.SKILL.mdيقول "اقرأ الدليل المعني" والحزمة تحتوي على اثني عشر دليل، يجب أن تخمن النموذج. إذا أشار كل دليل إلى ثلاثة ملفات أخرى، يصبح الحملة مسيرة رسمية غير محدودة.

وقت تشغيل جيد يجعل الاكتشافات محددة والكشف عن قصد.

المفهوم

اكتشاف هو خط أنابيب المجمعين

تعامل نظام الملفات كمدخول مصدر. لا تنشر المسارات الخام مباشرة إلى النموذج.

يجب أن تنتج كل مرحلة بيانات مهيكلة وفشل مهيكلي. يجب أن يرد سجل الكشف على:

ما هي الجذور التي تم البحث فيها؟
أي مرشحات وجدت؟
أي مرشحات رفضت ولماذا؟
أي حزمة فازت في اصطدام؟
ما هي المواد التي تم تقصيرها أو حذفها بسبب الميزانية؟

بدون هذه الدليل، "الموديل لم يستخدم مهارتي" هو تقريبا مستحيل للتشخيص.

نطاق سياسة وقت التشغيل

تُحدد المواصفات المحمولة مجموعة مهارات، وليس مسار تثبيت عالمي واحد أو ترتيب الأولوية. يقرر المضيف أين يبحث.

قد يستخدم وقت تشغيل عام هذه النطاقات:

Scope	Example root	Intended ownership
Workspace	`<repo>/.agents/skills/`	Project maintainers
User	`<user-data>/skills/`	One developer
Administrator	`<system>/skills/`	Machine or organization policy
Plugin	A signed plugin bundle	Plugin publisher and installer
Built-in	Runtime package	Runtime vendor

اعتبارا من أغسطس 2026، فإن كودكس يستند إلى مشروع اكتشاف من $CWD/.agents/skillsمن خلال أدلة أسلاف حتى جذور المخبز، بالإضافة إلى المستخدم، والمدير، والمواقع المدمجة. يدعم أدلة المهارات المتصلة. يمكن أن تظهر كلتا الأسماء المكررة بدلاً من الاندماج. هذه هي سلوكيات كودكس، وليس متطلبات من SKILL.md• التحقق من التيارCodex skill documentationعندما تكتب مُعدّلة.

لا تختلق أبداً الأولوية من أسماء المجلات، إعلنها كسياسة واختبارها. مختبر الدروس يستخدم رتبة كاملة صريحة لكلScopeلذا فإن مجموعة المرشحين نفسها دائماً تحل بنفس الطريقة.

التصادمات تحتاج إلى هوية خارج`name`

حزمين مسمّينrelease-readinessيمكن أن تكون مشروعة. يمكن أن تكون إحدى هذه الإدخالات إغلاق مساحة العمل والآخر إغلاق مستخدم. لذا فإن إدخال الكتالوج يحتاج على الأقل:

json{
  "name": "release-readiness",
  "description": "Inspect a release candidate for this repository.",
  "scope": "workspace",
  "source": "/repo/.agents/skills/release-readiness",
  "selected": true
}

تشمل سياسات التصدم المشتركة:

Policy	Benefit	Risk
Keep every candidate	Nothing is hidden	The model sees ambiguous names
Highest-precedence scope wins	Simple invocation	A local package can shadow a trusted one
Reject duplicates	No silent shadowing	Legitimate overrides stop working
Qualify names by source	Explicit identity	User-facing names become longer

اختر سياسة واحدة للمضيف. الحفاظ على المرشحين الرفضين أو المظلومين في التشخيص حتى عندما لا يكونون في الكتالوج النموذجي.

ثلاثة مستويات الكشف

تُصف المواصفات المُحددة لمهارات العميل الحمل المُرحَّل، والمركز هو أنّ لكل مستوى غرض مختلف.

#### المستوى 1: البيانات المعدنية الكتالوجية

يحتاج النموذج إلى معلومات كافية لتمييز المهارة من الجيران. وتقدر المواصفات حوالي 100 رمز لكل إدخال في الكتالوج، ولكن التسلسل والمعيار الحقيقي ينتمون إلى المضيف.

وصف مفيد يحتوي على فقرتين:

yamldescription: Validate a release candidate and produce a readiness report. Use when the user asks whether a version, tag, or package is ready to publish.

القاعدة الأولى تعلن القدرة، والقاعدة الثانية تعلن حدود الإطلاق، والدرس 25 يقيّم هذه الحدود مع طلبات إيجابية و شبه ضائعة.

#### المستوى 2: تعليمات نشطة

بعد تنشيطها، يجب أن يعمل الجسم كخريطة وإجراء.SKILL.mdتحت 500 سطر، هذا إشارة تصميم، وليس هدفًا لملءه.

يجب أن يحتوي الجسم على:

حدود المهمة
سير العمل الافتراضي
ظروف الفروع
الإشارات المباشرة إلى ملفات أعمق؛
عقود الأدوات والمنشورات
الفشل والإيقاف من السلوك
الناتج المتوقع والتحقق منه.

لا تنقل سير العمل المركزي إلى مرجع فقط لتقصير ملف الإدخال. يجب أن يمنح النموذج سياقًا كافٍ لبدء العمل بشكل صحيح.

#### المستوى الثالث: الموارد الداعمة

توفر المرجحات النص أو البيانات. توفر السكريبتات الحسابات التحديدية. يتم نسخ الأصول أو ملءها أو تحويلها إلى إمدادات بدلاً من التعامل معها كإرشادات.

Directory	Model reads it?	Model executes it?	Typical content
`references/`	Yes, when needed	No	schemas, policies, domain guides
`scripts/`	May inspect it	Through a permitted tool	validators, converters, collectors
`assets/`	Only if useful	No	templates, fixtures, images, starter files

هذه الأسماء هي اتفاقيات، وليس قدرات سحرية. لا يزال المضيف بحاجة إلى وصول الملفات و أداة تنفيذ.

الإشارات الخاصة بالفرع تفوق إشارات المواضيع

اكتب ملف الدخول كخريطة قرار:

markdown## Choose the path

- For a Python package, read `references/python-release.md`.
- For a container image, read `references/container-release.md`.
- For a documentation-only release, read `references/docs-release.md`.
- If the release combines artifact types, read only the guides for those artifacts.

هذا يعطي كل مرجع حالة تحميل قابل للملاحظة.references/لا يوجد

حافظ على الرسم البياني للمراجعة مشحونة.SKILL.mdوتجنب السلاسل العميقة. قفزة واحدة تجعل الوصول قابلة للتحقق وتقلل من فرصة أن القيود المطلوبة لا تدخل أبداً في السياق.

ميزانية الكتالوجية والسياق النشط هي ميزانيات مختلفة

دعوناc_iأن تكون التكلفة المسلسلة الكتالوجية للمهاراتi،B_cميزانية الكتالوج b_jتكلفة الجسم النشط، و r_kالموارد التي تحملها بالفعل.

textcatalog_cost = sum(c_i for every published skill)
active_cost = sum(b_j for every activated skill) + sum(r_k for every disclosed resource)

إن خفض ميزانية واحدة لا يقلل تلقائيًا من الأخرى. يمكن أن توفر التصفيات القصيرة مساحة الكتالوج في حين أن جسم 900 سطر نشط لا يزال يزداد الاحتلال على المهمة. يمكن تقسيم الجسم إلى مرجعيات تقليل التكلفة النشطة فقط عندما يتجنب الوقت والإرشادات تحميل فروع غير ذات صلة.

كودكس حاليا ميزانية قائمة المهارات الأولية في 2 في المئة من السياق

نافذة عندما يكون حجم النافذة السياقية معروفة. قيمة 8000 حرف هو

الاحتمالات التي تمتلكها في الموقع

قاعدة 2 في المئة عندما يتجاوز الكتالوج الميزانية المعمول بها

يمكن اختصار أو حذف وصف.

سياسة "كودكس"، ليست ملكية لمعايير مهارات العميل

مسارات الموارد هي حدود الثقة

يجب أن تقرأ المهارة فقط الملفات داخل حزمة. لا يكفي التحقق من السطر المسبق حرفيا:

textreferences/../../../../.ssh/config
references/external-link -> /private/company-secrets

حل جذور الحزمة والمرشح مع أساسية النظام الملفي، رفض المدخلات المطلقة، وتحقق من أن المرشح المحل يبقى تحت الجذر المحل. قرر ما إذا كان الروابط المماثلة مسموحة قبل اكتشاف. إذا تم السماح بذلك، تحقق من الهدف المحل في كل مرة.

لا يُؤكد احتواء المسار ثقة المحتوى. إشارة صالحة داخل الحزمة لا تزال قد تحتوي على تعليمات ضارة. يتعامل الدروس 26 مع هذا التهديد.

يجب أن تكون الحمل قابلًا للملاحظة

تسجيل الأحداث التي تكشف عنها دون تسجيل الأسرار:

json{
  "event": "skill.resource.loaded",
  "skill": "release-readiness",
  "resource": "references/python-release.md",
  "reason": "candidate contains pyproject.toml",
  "bytes": 2840
}

السبب يحول اختيار السياق إلى دليل قابلة للتعقيد. كما يساعد على تحديد التعليمات التي تسبب وكيل تحميل كل ملف "فقط في حالة".

بناءها

code/main.pyيُبني محرك اكتشاف وتفشي تحديد.

يحتوي سطح الاكتشاف على:

Scopeلمعلومات المصدر والسبقية
SkillCandidateلمرشح نظام الملفات غير المصرح به؛
discover_scope(scope)إعداد إرشادات المهارات الفورية؛
resolve_collisions(candidates, precedence)تطبيق سياسة واحدة مدعومة؛
CatalogEntryوbuild_catalog(...)نشر البيانات المعدنية المحدودة
CatalogBudgetلتحقيق إدخالات تسلسلية دون تظاهر بأحرف هي رموز عالمية.

يحتوي سطح الكشف على:

load_skill_body(entry, ...)لتنشيط المستوى 2
validate_reference(skill_dir, reference)لتحديد المسارات
load_reference(...)لقرأات المستوى 3 المحدودة

إدير المختبر

bashcd "$(git rev-parse --show-toplevel)"
cd phases/13-tools-and-protocols/24-skill-discovery-and-progressive-disclosure
python3 code/main.py
python3 -m unittest discover -s code/tests -v

هذا الحجر يتطلب نسخة محلية ويقوم بحل جذور مخزن من أي

المجلد العامل داخل ذلك النسخة.

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

لماذا الاكتشافات ضئيلة

discover_scopeيفتش إداريات الأطفال المباشرةSKILL.mdلا يعالج كل شخص يعشّرSKILL.mdكحزمة منفصلة. هذا يحافظ على حدود الحزمة ويتجنب نشر أمثلة أو أجهزة في داخل مهارة مثبتة.

لماذا لا يقوم المختبر بتحليل المواد الـ YAML التعسفي

يدعم المختبر المواد الاولية المتعددة اللازمة لمطالبته. يجب أن تستخدم وقت تشغيل الإنتاج محاكاة YAML آمنة مع مخطط صريح ومحدودية الحجم ، وتعطيل بناء الأشياء المخصصة. "Stdlib فقط" هو قيود تدريس ، وليس إذن لاختراع لهجة YAML جزئية بصمت.

استخدمها

تطبيق قائمة التحقق هذه على أي مُكيف اكتشاف:

قم بإدراج كل جذور مُعدّلة ومن يمكنه كتابةها.
إضافة إشارة ما إذا كان يسمح بتوصيل الحزم المرتبطة.
تأكييد اسم الحزمة، اسم المجلة، البيانات المعدنية المطلوبة، وحجم جسم الدخول.
الحفاظ على المصدر والطابع في الهوية الداخلية.
إعلان واختبار سلوك الاسم المكرر.
قياس الكتالوج المتسلسل المحدد الذي تم إرساله إلى النموذج.
سجل سبب تحميل الجسم أو الموارد
حافظ على قراءة الموارد داخل جذور الحزمة المحلولة.
الفشل بشكل واضح عندما يفتقر ملف مرجع
إعادة بناء الكتالوج عندما تتغير التثبيتات أو السياسات.

أرسله

هذا الدرس يخلقskill-catalog-builderمجموعة. يصفح الجذور المنظمة صراحة، ويرفض ملفات الدخول المتصلة والإطلاع على أسماء المجلات، ويحلّ صدامات عبر المجال، ويرفض النسخ المزدوجة ذات الأولوية المتساوية، ويقوم بتضمين البيانات الأساسية المختارة في الملفات الدخولية والمصفوفة، وميزانيات الشخصيات المتسلسلة.

يحتوي تقرير JSON على إدخالات مختارة، مرشحات ظل، وإدخالات مفقودة، أخطاء التحقق، والفضلية، واستخدام الميزانية. لا يزال تحميل الجسم والمرجعية عمليات منفصلة في الوقت التشغيل، لذلك لا يقوم بناء الكتالوج بتنفيذ النصوص أو إدخال الحزمة بأكملها في السياق.

التمارين

أضف نطاق التضمين ووضعها بين المستخدم والفضلية المدمجة. أثبت نتيجة الصدام باستخدام اختبار.
تغيير سياسة التصدم من أعلى الأولوية إلى أسماء مؤهلة. الحفاظ على كل من الإدخالات في الكتالوج.
إضافة حد حجم البايت إلى load_referenceاختبر الملف بالضبط عند الحد و بايت فوقه
إخلق وصفين يبدو متطابقين تقريباً أعد كتابتهما حتى لا تتداخل حدود الزناد
إضافة إشارة تحتوي على الهيش لكل مرجع وسجل. اكتشاف الموارد المعدلة قبل تحملها.
أستخدم الديمو لتقديم تقرير مستوى 1، المستوى 2، والستوى 3 حسابات البايت بشكل منفصل.

الشروط الرئيسية

Term	What people say	What it actually means
Skill discovery	"Find every SKILL.md"	Search configured scopes, validate packages, attach provenance, and apply policy
Skill catalog	"The list of installed skills"	Compact model-visible routing metadata for eligible packages
Collision policy	"Which duplicate wins"	A declared rule for same-name candidates from different sources
Progressive disclosure	"Lazy loading"	Staged context admission from catalog to body to branch-specific resources
Reference graph	"Files linked by the skill"	The reachable resource structure and its load conditions
Path containment	"Stay in the folder"	Verify resolved resource targets remain inside the resolved package root