loadAgentDir() تقرأه وتستدعي createAgent() بالخيارات التي تصفها الملفات، فتُرجع بالضبط ما تُرجعه createAgent(). يبقى الـ typed code API هو المرجع الأساسي: المجلد طريقة أخرى لكتابة الخيارات نفسها، ويمكنك الانتقال إلى الكود في أي وقت دون إعادة كتابة.
أمان: تحميل مجلد agent يشغّل الكود الذي فيه (agent.tsوكل شيء فيtools/). لا تحمّل إلا مجلدات تثق فيها. لا يوجد أي sandbox ضمني؛ الملفات تعمل بكامل صلاحيات العملية.
بنية المجلد
tools/ وعناصر skills/ وsubagents/ تُقرأ مرتّبة، فيكون التحميل deterministic ويعطي نفس النتيجة كل مرة.
ملف الـ config
أي مفتاح غير معروف يعتبر خطأ مع اقتراح (
'modle' (did you mean 'model'?)).
قاعدة permissions هي { "tool", "when"?, "action", "reason"?, "ttlMs"? }. tool اسم، أو قائمة أسماء ('*' تغطي كل الـ tools)، أو RegExp في config برمجي. action قيمتها 'allow' أو 'ask' أو 'deny'. ttlMs مسموح فقط في قواعد 'ask' — المدة التي تنتظرها الوقفة للحصول على قرار قبل أن تنتهي (‘approval expired’)، وهو يغلب على approvalTtlMs الخاصة بالـ agent. في JSON/YAML يكون when سجلًا من أسماء المعاملات إلى matchers، وكلها يجب أن تتحقق. السلسلة المجرّدة regular expression تُختبر على String(args[name])؛ والكائن يختار عمليات: eq/ne تقارن المعامل بالقيمة بـ ===/!==، وlt/lte/gt/gte تقارن Number(args[name]) بالقيمة (المعامل غير الرقمي لا يطابق أبدًا)، وmatches هي regular expression. عدة عمليات على معامل واحد يجب أن تتحقق كلها، فـ { "replicas": { "gte": 1, "lte": 10 } } تطابق من 1 إلى 10. وفي config برمجي يمكن تمرير الـ predicate نفسه. أول قاعدة تطابق هي التي تحسم.
hooks / approve نسبيًا ويبقى داخل المجلد. lousho build يحزّم ملفات hooks.* وapprove.* الجذرية بجانب الـ config ويحلّ ملف .js المصرَّف المجاور، فتظل مسارات .ts تعمل بعد البناء.
instructions/<family>.md تُلحَق بـ instructions.md إذا كان معرّف الـ model المحسوب يحتوي <family>: فـ instructions/openai.md تنطبق على openai/gpt-4o-mini وعلى openrouter/openai/gpt-4o-mini. أول تطابق بالترتيب الأبجدي يفوز؛ ومعرّف model لا علاقة له يحصل على الـ prompt الأساسي فقط.
Tools
كل ملف فيtools/ يصدّر افتراضيًا tool مبني بـ defineTool()، ويمكنه أيضًا تصدير tools أخرى بالاسم (أو مصفوفة tools). باقي التصديرات تُتجاهَل، لكن ملفًا لا يصدّر أي tool إطلاقًا يعتبر خطأ، وكذلك وجود tool اثنين بنفس الاسم (يُذكَر الملفان كلاهما في الرسالة).
Skills
skills/ يقبل ما تقبله loadSkills(): skills/<name>/SKILL.md وskills/<name>.md، ولكل منها description في الـ frontmatter. راجع Skills.
Sub-agents
كل مجلد داخلsubagents/ هو نفسه مجلد agent (ويمكن أن يكون له subagents/ خاص به). ويجب أن يحتوي الـ config الخاص به على description. كل واحد منها sub-agent أصلي للأب: يدخل في خريطة subagents الخاصة بالأب، فيفوّض إليه الـ model الخاص بالأب عبر tool الـ task (راجع Sub-agents). ويحصل الأب أيضًا على tool باسم delegate_to_<name>، باقية كاسم بديل متوافق مع الإصدارات السابقة: تأخذ نص المهمة وترجع الإجابة النهائية للـ sub-agent، وتعمل عبر نفس الـ runtime الذي يعمل به task. الـ sub-agent يستخدم model الخاص به إن حدّده، وإلا ورث model الأب؛ أما provider override الممرَّر إلى loadAgentDir() فيصل إلى الجميع.
في الحالتين يعمل الـ sub-agent داخل run الأب، مثل أي sub-agent في createAgent():
- قواعد
permissionsالخاصة بالأب تأتي أولًا في الـ sub-agent، فـdeny('write_file')على الأب يسري على الشجرة كلها؛ - استدعاء من الـ sub-agent يحتاج approval يوقف run الأب مؤقتًا (
finishReason: 'awaiting-approval'، وsubagentPathفي الـ approval المعلّقة يسمّي الـ sub-agent)، وagent.approvals.resolve()يكمله. الـapproveالخاص بمجلد الـ sub-agent نفسه يحسم استدعاءاته أولًا؛ وإن لم يوجد، يحسمهاapproveالممرَّر إلىloadAgentDir()في الكود، وإلا ينتظر الاستدعاء إنسانًا. ملفapproveالخاص بمجلد الأب لا يحسم استدعاءات الـ sub-agents التابعة له؛ - استهلاكه من الـ tokens يُضاف إلى استهلاك الأب (
result.usage.delegated)، وأحداثه تصل إلى listeners الأب موسومة بـevent.subagent، والـ spans الخاصة به تتداخل تحت trace الأب.
subagents/ المتداخلة ترفع maxSubagentDepth الخاص بالأب إلى عمق الشجرة (إلا إذا مرّرت قيمة بنفسك)، فيستطيع كل مستوى أن يفوّض.
مجلد sub-agent يضبط "engine": "pi" في الـ config يصبح بدلًا من ذلك sub-agent من نوع Pi coding-agent: يدخل في خريطة subagents الخاصة بالأب (tool الـ task) بدون الاسم البديل delegate_to_<name>، والـ sessions (الجلسات) فيه تعمل داخل مجلد الأب — مساحة العمل التي تتشاركها file tools الخاصة بالأب وجلسة Pi. model يأخذ المعرّف المعتاد pi/<provider>/<model>، وقواعد permissions تتحكم في tool calls الخاصة بجلسة Pi (read وbash وedit وwrite وغيرها). باقي مفاتيح الـ config تُتجاهَل: Pi يحمل system prompt الخاص فيه وcoding tools الخاصة به. تشغيل sub-agent من نوع pi يحتاج الـ peer dependency الاختيارية @earendil-works/pi-coding-agent والـ Node runtime — هدف Cloudflare Worker يرفضه.
loadAgentDir(dir, { piAgent: { ... } }) تحقن خيارات piAgent() في كل sub-agent من نوع engine: 'pi' (مثل modelRuntime وهمي في الاختبارات، أو sessionDir لإبقاء الـ approvals بعد إعادة التشغيل)؛ والمجلد دائمًا يفوز في cwd وname وdescription.
Channels
كل ملف فيchannels/ يصدّر افتراضيًا channel مبني بـ defineChannel() أو بأحد المصانع المدمجة (webhookChannel() وhttpChannel() وslackChannel() وdiscordChannel() وtelegramChannel() وgithubChannel() وteamsChannel()). اسم الـ channel هو الاسم الذي تحدّده هي، وإلا فاسم الملف. ملف لا يصدّر channel يفشل بخطأ LOUSHO_CHANNEL_INVALID مع ذكر الملف. resolveAgentDir() ترجعها في channels (وأسماءها في manifest.channels)؛ أما loadAgentDir() فلا تركّبها. خادم node الذي يولّده lousho build --target=node-server يركّبها تحت /channels بجانب مسارات الدردشة (createDeployedServer(agent, { channels })، وهو helper داخلي في الحزمة المولَّدة)؛ ومع خادمك الخاص استخدم mountChannels():
lousho dev يركّبها أيضًا، وlousho build ينشرها (انظر أدناه).
Memory
كل ملف فيmemory/ يصدّر افتراضيًا memory slot: ناتج defineMemory({ ... })، أو نفس الخيارات بدون name وحينها يكون اسم الملف هو اسم الـ slot. بخلاف الـ schedules والـ channels، الـ slots جزء من الـ agent: loadAgentDir() تمرّرها إلى createAgent({ memory })، فتعمل الـ tools remember_<name> / recall_<name> والاسترجاع داخل الـ prompt بدون أي كود إضافي، وmanifest.memory يسرد أسماءها. كل slot يستخدم provider الخاص فيه. ملف لا يصدّر slot يفشل بخطأ LOUSHO_MEMORY_INVALID مع ذكر الملف. وأي override لـ memory يُمرَّر إلى loadAgentDir(dir, { overrides }) يُدمَج مع slots المجلد بالاسم: عند التعارض يفوز الـ override.
dir النسبي في ملف memory/*.ts يُحَلّ نسبةً إلى مجلد العمل للعملية، لا إلى مجلد الـ agent (بخلاف store.dir في agent.ts، فهو نسبي إلى مجلد الـ agent). لذلك ./.lousho/memory المجرّد يضع الذاكرة في شجرة غير شجرة الـ sessions، ويتغيّر مكانها عندما تشغّل الـ agent من مجلد آخر أو من build. اربطه بالـ module بدلًا من ذلك، فيقع دائمًا بجانب باقي حالة الـ agent:
كيف يقابل createAgent()
resolveAgentDir() ترجع الخيارات المجمَّعة وmanifest، وهذا مفيد للاختبارات والأدوات:
lousho-registry.json (Registry)، يخبرك manifest.registry ما إذا كانت ملفات كل عنصر مثبَّت ما زالت تطابقه، وتعمل tools أي عنصر من الإيصال داخل الـ permission manifest الذي ثُبِّتت معه.
Overrides
الوسيط الثاني يأخذ نفس خياراتcreateAgent() ويغلب على الملفات. كل خيار يُمرَّر إلى الـ agent، بما فيها الخيارات التي لا يعلنها أي ملف (guardrails وonEvent وretry وreasoning وredactContent وoutput وغيرها). استخدمه لتبديل الـ model في الاختبارات:
tools وskills تستبدل المكتشَفة من المجلد (لا تُدمَج معها). وسلسلة provider/model الواردة في ملف تُسقَط عندما تعمل override لـ provider، فيُستخدَم الكائن الممرَّر كما هو. approve: null / hooks: null يزيلان ربط المجلد (الملف الذي يسمّيه الـ config لا يُستورَد أصلًا)؛ أما undefined فيُبقيه.
الانتقال من الملفات إلى الكود
استدعِresolveAgentDir() واطبع config والصق ما تحتاجه في استدعاء createAgent()؛ أو حمّل المجلد واعمل override فقط للأجزاء التي تريد تملّكها في الكود. الـ tools قيم defineTool() عادية، فيمكن استيراد ملف tool من الكود بدون أي تغيير.
تحميل TypeScript
ملفات.ts تُحمَّل بـ import() ديناميكي، فيجب أن تكون العملية تعمل أصلًا تحت TypeScript loader: npx tsx your-script.ts (أو ts-node أو bun أو deno أو type stripping المدمج في Node). بدون ذلك يفشل التحميل بخطأ يوضّح ذلك. صرّف المجلد أولًا، أو استخدم tools بصيغة .js/.mjs مع config بصيغة agent.json / agent.yaml فهي تعمل في كل مكان. وtool بامتداد .js يستخدم صيغة import يحتاج "type": "module" في أقرب package.json (أو امتداد .mjs).
شغّله بـ lousho dev
POST /chat للمجلد، ويعيد تحميله عندما يتغيّر instructions.md أو ملف الـ config أو tools/ أو skills/ أو subagents/ (راجع lousho dev للتفاصيل). ملف الـ tool يُستورَد من جديد في كل reload، فيسري أي تعديل على tools/*.ts من الرسالة التالية. وإعادة التحميل الفاشلة (خطأ syntax أو instructions.md فارغ) تُسجَّل وتُعرَض في صفحة الدردشة، والـ agent السابق يواصل الإجابة.
channels/ الخاصة بالمجلد تُركَّب تحت /channels وschedules/ تُشغَّل، والـ reload يبدّل الاثنين: الـ schedules القديمة تتوقّف قبل أن تبدأ الجديدة، فلا يعيش مؤقّت ولا مسار بعد زوال ملفه. مرّر --no-schedules لتركيب الـ channels بدون إطلاق الـ crons (راجع Schedules في dev).
انشره بـ lousho build
resolveAgentDir() عند الإقلاع، ويشغّل schedules/ ويركّب channels/ تحت /channels، ويحمي مسارات الدردشة بـ auth.ts إن وُجدت (مصادقة المسارات والهويات)، ويطبع ما وجده منها. الدالة التي يصدّرها auth.ts باسم authorizeSession أو authorizeApproval تحدّد من يستطيع استخدام session ومن يستطيع حسم approval، مثل مدير يوافق على طلب معلّق لمستخدم (من يستطيع حسم الموافقة)؛ وبدونهما يُبقي الخادم الإعدادات الافتراضية (الـ session والـ approvals الخاصة بها ملك للمستدعي الذي بدأها). ملفات الكود (الـ config، وauth.ts، وملف hooks.* / approve.* الجذري، وtools/، وschedules/، وchannels/، وmemory/، ومثلها في كل sub-agent) تُحزَّم إلى dist/agent/**.js، ولا يُنسَخ بجانبها إلا instructions.md (مع instructions/<family>.md) وskills/ وملف config بصيغة JSON/YAML (ومثلها في كل sub-agent)، فالخادم لا يحتاج TypeScript loader ولا مصادر ولا node_modules. لا يُنسَخ أي شيء آخر: ملفات .env، ومخزن الـ sessions في .lousho/ (أو store.dir في الـ config)، وأي ملف آخر تبقى خارج الـ build وصورة Docker الخاصة به. راجع النشر. هدف Cloudflare Worker يبني مجلدًا أيضًا مع تضمين كل مجلد فرعي: subagents/ تصبح delegate_to_ tools، وschedules/ تصبح cron triggers، وchannels/ تُركَّب تحت /channels، وmemory/ slots تعمل على kvMemory() (Cloudflare Workers).
التقديم عبر MCP
lousho mcp يأخذ مجلد agent كما يأخذ ملف spec (الإعداد): lousho mcp ./my-agent يقدّمه كخادم MCP (MCP).