اكتشاف التكوين وحلّه

يصف هذا المستند كيف يحلّ وكيل البرمجة (coding-agent) التكوين حالياً: أي الجذور يتم فحصها، وكيف تعمل الأسبقية، وكيف يُستهلك التكوين المحلول من قِبَل الإعدادات والمهارات والخطّافات (hooks) والأدوات والإضافات.

النطاق

التنفيذ الأساسي:

src/config.ts
src/config/settings.ts
src/config/settings-schema.ts
src/discovery/builtin.ts
src/discovery/helpers.ts

نقاط التكامل الرئيسية:

src/capability/index.ts
src/discovery/index.ts
src/extensibility/skills.ts
src/extensibility/hooks/loader.ts
src/extensibility/custom-tools/loader.ts
src/extensibility/extensions/loader.ts

تدفق الحلّ (مرئي)

         Config roots (ordered)
┌───────────────────────────────────────┐
│ 1) ~/.xcsh/agent + <cwd>/.xcsh          │
│ 2) ~/.claude   + <cwd>/.claude        │
│ 3) ~/.codex    + <cwd>/.codex         │
│ 4) ~/.gemini   + <cwd>/.gemini        │
└───────────────────────────────────────┘
                    │
                    ▼
        config.ts helper resolution
  (getConfigDirs/findConfigFile/findNearest...)
                    │
                    ▼
       capability providers enumerate items
 (native, claude, codex, gemini, agents, etc.)
                    │
                    ▼
      priority sort + per-capability dedup
                    │
                    ▼
          subsystem-specific consumption
   (settings, skills, hooks, tools, extensions)

1) جذور التكوين وترتيب المصادر

الجذور القانونية

يُعرّف src/config.ts قائمة أسبقية مصادر ثابتة:

.xcsh (أصلي)
.claude
.codex
.gemini

القواعد على مستوى المستخدم:

~/.xcsh/agent
~/.claude
~/.codex
~/.gemini

القواعد على مستوى المشروع:

<cwd>/.xcsh
<cwd>/.claude
<cwd>/.codex
<cwd>/.gemini

CONFIG_DIR_NAME هو .xcsh (packages/utils/src/dirs.ts).

قيد مهم

المساعدات العامة في src/config.ts لا تتضمن .pi في ترتيب اكتشاف المصادر.

2) مساعدات الاكتشاف الأساسية (`src/config.ts`)

`getConfigDirs(subpath, options)`

تُرجع مُدخلات مرتبة:

المُدخلات على مستوى المستخدم أولاً (حسب أسبقية المصدر)
ثم المُدخلات على مستوى المشروع (حسب نفس أسبقية المصدر)

الخيارات:

user (الافتراضي true)
project (الافتراضي true)
cwd (الافتراضي getProjectDir())
existingOnly (الافتراضي false)

تُستخدم هذه الواجهة البرمجية لعمليات البحث عن التكوين المبنية على المجلدات (الأوامر، الخطّافات، الأدوات، الوكلاء، إلخ).

`findConfigFile(subpath, options)` / `findConfigFileWithMeta(...)`

تبحث عن أول ملف موجود عبر القواعد المرتبة، وتُرجع أول تطابق (المسار فقط أو المسار + البيانات الوصفية).

`findAllNearestProjectConfigDirs(subpath, cwd)`

تتنقل عبر المجلدات الأب صعوداً وتُرجع أقرب مجلد موجود لكل قاعدة مصدر (.xcsh، .claude، .codex، .gemini)، ثم تُرتّب النتائج حسب أسبقية المصدر.

استخدم هذه الدالة عندما يجب أن يُورَث تكوين المشروع من المجلدات الأب (سلوك المستودعات المتعددة/مساحات العمل المتداخلة).

3) غلاف ملف التكوين (`ConfigFile<T>` في `src/config.ts`)

ConfigFile<T> هو المُحمّل المُتحقق من المخطط لملفات التكوين المفردة.

الصيغ المدعومة:

.yml / .yaml
.json / .jsonc

السلوك:

يتحقق من البيانات المُحلّلة باستخدام AJV مقابل مخطط TypeBox المُقدّم.
يُخبّئ نتيجة التحميل حتى استدعاء invalidate().
يُرجع نتيجة ثلاثية الحالة عبر tryLoad():
- ok
- not-found
- error (ConfigError مع سياق المخطط/التحليل)

ترحيل النسخ القديمة لا يزال مدعوماً:

إذا كان المسار المستهدف .yml/.yaml، يتم ترحيل ملف .json مجاور تلقائياً مرة واحدة (migrateJsonToYml).

4) نموذج حلّ الإعدادات (`src/config/settings.ts`)

نموذج الإعدادات في وقت التشغيل مُطبّق بطبقات:

الإعدادات العامة: ~/.xcsh/agent/config.yml
إعدادات المشروع: مُكتشفة عبر قدرة الإعدادات (settings.json من المزوّدين)
التجاوزات في وقت التشغيل: في الذاكرة، غير مستمرة
القيم الافتراضية للمخطط: من SETTINGS_SCHEMA

مسار القراءة الفعّال:

defaults <- global <- project <- overrides

سلوك الكتابة:

settings.set(...) يكتب إلى الطبقة العامة (config.yml) ويُدرج عملية حفظ في الخلفية.
إعدادات المشروع هي للقراءة فقط من اكتشاف القدرات.

سلوك الترحيل لا يزال نشطاً

عند بدء التشغيل، إذا كان config.yml مفقوداً:

الترحيل من ~/.xcsh/agent/settings.json (يُعاد تسميته إلى .bak عند النجاح)
الدمج مع إعدادات قاعدة البيانات القديمة من agent.db
كتابة النتيجة المدمجة إلى config.yml

عمليات ترحيل على مستوى الحقول في #migrateRawSettings:

queueMode -> steeringMode
ask.timeout بالمللي ثانية -> بالثواني عندما تبدو القيمة القديمة كمللي ثانية (> 1000)
البنية القديمة المسطحة theme: "..." -> بنية theme.dark/theme.light

5) تكامل القدرات/الاكتشاف

معظم تدفقات تحميل التكوين غير الأساسية تمر عبر سجل القدرات (src/capability/index.ts + src/discovery/index.ts).

ترتيب المزوّدين

يتم ترتيب المزوّدين حسب الأولوية الرقمية (الأعلى أولاً). أمثلة على الأولويات:

OMP الأصلي (builtin.ts): 100
Claude: 80
Codex / agents / Claude marketplace: 70
Gemini: 60

Provider precedence (higher wins)

native (.xcsh)          priority 100
claude                 priority  80
codex / agents / ...   priority  70
gemini                 priority  60

دلالات إزالة التكرار

تُعرّف القدرات key(item):

نفس المفتاح => العنصر الأول يفوز (العنصر ذو الأولوية الأعلى/المُحمّل أولاً)
لا مفتاح (undefined) => لا إزالة تكرار، يتم الاحتفاظ بجميع العناصر

المفاتيح ذات الصلة:

المهارات: name
الأدوات: name
الخطّافات: ${type}:${tool}:${name}
وحدات الإضافات: name
الإضافات: name
الإعدادات: لا إزالة تكرار (يتم الاحتفاظ بجميع العناصر)

6) سلوك المزوّد الأصلي `.xcsh` (`src/discovery/builtin.ts`)

المزوّد الأصلي (id: native) يقرأ من:

المشروع: <cwd>/.xcsh/...
المستخدم: ~/.xcsh/agent/...

قاعدة قبول المجلد

builtin.ts يتضمن جذر التكوين فقط إذا كان المجلد موجوداً وغير فارغ (ifNonEmptyDir).

التحميل الخاص بالنطاق

المهارات: skills/*/SKILL.md
أوامر الشرطة المائلة: commands/*.md
القواعد: rules/*.{md,mdc}
المطالبات: prompts/*.md
التعليمات: instructions/*.md
الخطّافات: hooks/pre/*، hooks/post/*
الأدوات: tools/*.json|*.md و tools/<name>/index.ts
وحدات الإضافات: مُكتشفة تحت extensions/ (+ مصفوفة نصوص قديمة settings.json.extensions)
الإضافات: extensions/<name>/gemini-extension.json
قدرة الإعدادات: settings.json

فارق دقيق في البحث عن أقرب مشروع

بالنسبة لـ SYSTEM.md و XCSH.md، يستخدم المزوّد الأصلي بحث أقرب مجلد .xcsh أب في المشروع (تصاعدي) لكنه لا يزال يشترط أن يكون مجلد .xcsh غير فارغ.

7) كيف تستهلك الأنظمة الفرعية الرئيسية التكوين

نظام الإعدادات الفرعي

Settings.init() يُحمّل config.yml العام + عناصر قدرة settings.json المُكتشفة على مستوى المشروع.
يتم دمج عناصر القدرات التي تحمل level === "project" فقط في طبقة المشروع.

نظام المهارات الفرعي

extensibility/skills.ts يُحمّل عبر loadCapability(skillCapability.id, { cwd }).
يُطبّق مفاتيح تبديل المصادر والمرشحات (ignoredSkills، includeSkills، مجلدات مخصصة).
مفاتيح التبديل ذات الأسماء القديمة لا تزال موجودة (skills.enablePiUser، skills.enablePiProject) لكنها تتحكم في المزوّد الأصلي (provider === "native").

نظام الخطّافات الفرعي

discoverAndLoadHooks() يحلّ مسارات الخطّافات من قدرة الخطّافات + المسارات المُعدّة صراحةً.
ثم يُحمّل الوحدات عبر استيراد Bun.

نظام الأدوات الفرعي

discoverAndLoadCustomTools() يحلّ مسارات الأدوات من قدرة الأدوات + مسارات أدوات الإضافات + المسارات المُعدّة صراحةً.
ملفات الأدوات التصريحية .md/.json هي بيانات وصفية فقط؛ التحميل التنفيذي يتوقع وحدات شفرة.

نظام الإضافات الفرعي

discoverAndLoadExtensions() يحلّ وحدات الإضافات من قدرة وحدة الإضافات بالإضافة إلى المسارات الصريحة.
التنفيذ الحالي يحتفظ عمداً فقط بعناصر القدرات التي تحمل _source.provider === "native" قبل التحميل.

8) قواعد الأسبقية التي يمكن الاعتماد عليها

استخدم هذا النموذج الذهني:

ترتيب مجلد المصدر من config.ts يُحدد ترتيب المسارات المرشحة.
أولوية مزوّد القدرة تُحدد الأسبقية عبر المزوّدين.
إزالة تكرار مفتاح القدرة تُحدد سلوك التعارض (الأول يفوز للقدرات ذات المفاتيح).
منطق الدمج الخاص بالنظام الفرعي يمكن أن يُغيّر الأسبقية الفعّالة بشكل إضافي (خاصةً الإعدادات).

تحذير خاص بالإعدادات

عناصر قدرة الإعدادات لا يتم إزالة تكرارها؛ Settings.#loadProjectSettings() يُجري دمجاً عميقاً لعناصر المشروع بالترتيب المُرجَع. لأن الدمج يُطبّق قيم العنصر الأحدث فوق القيم الأقدم، فإن سلوك التجاوز الفعّال يعتمد على ترتيب إصدار المزوّد، وليس فقط على دلالات مفتاح القدرة.

9) سلوكيات التوافق/القديمة لا تزال موجودة

ترحيل JSON -> YAML في ConfigFile للملفات المستهدفة بصيغة YAML.
ترحيل الإعدادات من settings.json و agent.db إلى config.yml.
عمليات ترحيل مفاتيح الإعدادات (queueMode، ask.timeout، theme المسطح).
توافق بيان الإضافات: المُحمّل يقبل كلاً من أقسام بيان package.json.xcsh و package.json.pi.
أسماء الإعدادات القديمة skills.enablePiUser / skills.enablePiProject لا تزال بوابات نشطة لمصدر المهارات الأصلي.

إذا تمت إزالة مسارات التوافق هذه من الشفرة، حدّث هذا المستند فوراً؛ عدة سلوكيات في وقت التشغيل لا تزال تعتمد عليها اليوم.