الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
يمكنك تعريف الـ agent كمجلد. loadAgentDir() تقرأه وتستدعي createAgent() بالخيارات التي تصفها الملفات، فتُرجع بالضبط ما تُرجعه createAgent(). يبقى الـ typed code API هو المرجع الأساسي: المجلد طريقة أخرى لكتابة الخيارات نفسها، ويمكنك الانتقال إلى الكود في أي وقت دون إعادة كتابة.
أمان: تحميل مجلد agent يشغّل الكود الذي فيه (agent.ts وكل شيء في tools/). لا تحمّل إلا مجلدات تثق فيها. لا يوجد أي sandbox ضمني؛ الملفات تعمل بكامل صلاحيات العملية.

بنية المجلد

مسموح بملف config واحد فقط. الملفات داخل 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:
المسار يتبع الـ module: الـ build المنسوخ أو المحزَّم يُبقي ذاكرته بجانبه، فوجّهه إلى مسار مطلق ثابت (أو provider قاعدة بيانات) إذا كان يجب أن تبقى الذاكرة بعد إعادة النشر.

كيف يقابل createAgent()

resolveAgentDir() ترجع الخيارات المجمَّعة وmanifest، وهذا مفيد للاختبارات والأدوات:
عندما يحتوي المجلد إيصال تثبيت lousho-registry.json (Registry)، يخبرك manifest.registry ما إذا كانت ملفات كل عنصر مثبَّت ما زالت تطابقه، وتعمل tools أي عنصر من الإيصال داخل الـ permission manifest الذي ثُبِّتت معه.

Overrides

الوسيط الثاني يأخذ نفس خيارات createAgent() ويغلب على الملفات. كل خيار يُمرَّر إلى الـ agent، بما فيها الخيارات التي لا يعلنها أي ملف (guardrails وonEvent وretry وreasoning وredactContent وoutput وغيرها). استخدمه لتبديل الـ model في الاختبارات:
overrides الخاصة بـ 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

مجلد الـ agent هو وحدة النشر: الخادم المبني يحمّله بـ 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).