الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
lousho add يثبّت tool أو skill أو channel أو schedule أو خانة memory أو kit داخل agent directory من registry. عنصر الـkit هو agent directory كامل: تثبيته يوزّع agent.* وinstructions.md وtools وskills وسub-agents، فيصبح الهدف (أو يتوسع ليصبح) agent directory بذاته. الـregistry مجرد JSON ثابت: index إضافة إلى مستند لكل عنصر يحمل محتوى ملفاته. تُنسخ الملفات إلى مشروعك كودًا مصدريًا تملكه وتستطيع تعديله. لا يوجد plugin loader في الـruntime، ولا شيء من الـregistry يُنفَّذ أو يُستورد أثناء الإضافة. lousho add يعمل دون أي إعداد: بدون --registry أو LOUSHO_REGISTRY يقرأ الـregistry الافتراضي على https://registry.lousho.com/index.json، وهو مجلد registry/dist/ في مستودع الـSDK مُقدَّم كـJSON ثابت. إذا تعذّر الوصول لهذا الـhost، يقرأ lousho add بدلًا منه من GitHub: من وسم الإصدار (release tag) الخاص بنسخة الـSDK المثبّتة (https://raw.githubusercontent.com/LinuxDevil/lousho/<version>/registry/dist/index.json)، ثم من الوسم نفسه مع البادئة v (للإصدارات الأقدم)، ثم من main. وإذا تعذّر الوصول إلى GitHub أيضًا (بدون اتصال، أو عطل، أو نسخة لم يُرفع وسمها أبدًا)، يقرأ lousho add نسخة registry/dist/ المرفقة داخل الحزمة المثبّتة، ويطبع تنبيهًا من سطر واحد بأن هذا الـregistry المرفق قد يكون أقدم من النسخة المتاحة على الإنترنت. الـregistry الافتراضي وحده يرجع إلى هذا البديل، أما الـregistry الذي تسمّيه بنفسك فلا. --registry وLOUSHO_REGISTRY توجّهانه إلى registry آخر، والقيمة none (في أي منهما) تعطّل الـregistry بالكامل — وحينها يفشل lousho add بـLOUSHO_CONFIG_INVALID، وهذا يناسب الاستخدام offline أو البيئات المغلقة. الـregistry الافتراضي فيه حاليًا تسعة عناصر: الـcoding kits (coding-kit وcoding-pi) تستخدم الـagent directory نفسه كمساحة عمل المشروع. لذلك ترفض أدوات الملفات فيها تعديل ملفات الـagent نفسه: agent.* وapprove.* وhooks.* وinstructions* وlousho-registry.json، وأي شيء تحت .lousho/ وtools/ وskills/ وsubagents/ و.git/ وnode_modules/. والـshell فيها يشغّل فقط node --test (مسارات ملفات اختبار، بلا flags) وgit status. ومع ذلك تظل الـkits تشغّل الاختبارات التي يكتب الـagent الكود لها، أي أن كود الـagent يعمل بصلاحيات مستخدمك. استخدم shell داخل sandbox للعمل غير الموثوق (راجع أدوات مساحة العمل). والـsub-agent الخاص بالبرمجة من Pi في kit الـcoding-pi له أدواته الخاصة، وهذه القواعد لا تغطيها.
قبل أن يكتب أي شيء، يطبع lousho add الـmanifest والملفات التي سيكتبها، ويفحص كود العنصر مقابل الـmanifest، ثم يسأل [y/N]. بعد الكتابة يسجّل العنصر في lousho-registry.json.

الصيغة

الـindex هو { items: [{ name, type, description, url | path }] }. قيمة type واحدة من tool أو skill أو channel أو schedule أو memory أو kit. وurl / path يحددان مكان مستند العنصر؛ المسار النسبي يُحلّ بالنسبة لموقع الـindex نفسه. كل مستند عنصر بهذا الشكل:
ومدخله في index.json:
استضف الاثنين كملفات ثابتة في أي مكان: مجلد في repo، أو object store، أو web server. يجب أن يطابق name وtype في المستند مدخلهما في الـindex. يبدأ الاسم بحرف أو رقم، ثم أحرف وأرقام و. و_ و-. المستند الذي لا يطابق الصيغة يُرجع LOUSHO_REGISTRY_INVALID مع ذكر الحقول. لتساهم بعنصر في الـregistry الافتراضي، أضف مجلد registry/<name>/ في مستودع الـSDK: ملف item.json (فيه name وtype وdescription وpermissions وdependencies) وملفات العنصر مرتبة كما يجب أن تصل في الـagent directory (tools/x.ts وskills/<name>/SKILL.md وchannels/x.ts؛ وملفات الـkit تكوّن agent directory كامل، مثل agent.json وinstructions.md وhooks.ts وtools/ وsubagents/<name>/). الأمر npm run registry:build يتحقق من كل عنصر بالقواعد نفسها التي يفرضها lousho add (الـschema والمسارات وفحص الكود مقابل الـmanifest) ويعيد بناء registry/dist/؛ أجرِ commit للنتيجة. الـCI يشغّل npm run registry:check ويفشل إذا كانت registry/dist/ قديمة.

بيان الصلاحيات

permissions يصرّح بما يستطيع العنصر فعله، فتقرر قبل أن تثبّته. كله اختياري؛ وما يغيب يظهر كـ”none” / “no”. ما يفرضه lousho add قبل أن يكتب أي شيء:
  • الكود يطابق الـmanifest. كل ملف JavaScript وTypeScript في العنصر يُفحص، بعد حذف التعليقات، عما يصل إليه بشكل ظاهر:
    • exec: true عند import لـchild_process (بـnode: أو بدونها) أو execa أو shelljs، أو عند استخدام createShellTool أو runShellCommand أو SubprocessSandbox من الـSDK؛
    • filesystem: "read" (أو "write") عند import لـfs (بما فيها fs/promises وصيغ node:) أو fs-extra أو graceful-fs، أو createFsTools من الـSDK، و"write" عند استدعاء writeFile أو appendFile أو createWriteStream أو mkdir أو mkdtemp أو rm أو rmdir أو unlink أو rename أو copyFile أو cp (وصيغها الـSync)؛
    • network غير فارغ عند fetch( أو استخدام createHttpTool من الـSDK أو import لـhttp أو https أو http2 أو net أو tls أو dgram أو undici أو axios أو node-fetch أو ws، وكل host بصيغة http(s):// أو ws(s):// داخل string يجب أن يطابق أحد مدخلات network (الـhost الذي يُبنى وقت التشغيل، مثل `https://${host}/`، يحتاج network غير فارغ ويُطبع كملاحظة، لأنه لا يمكن فحصه)؛
    • كل process.env.NAME وprocess.env['NAME'] يجب أن يكون مدرجًا في env.
    تُرفض دائمًا eval( وnew Function( وprocess.env[name] المحسوب وprocess.env مستخدمة كاملة، وأي import() أو require() لغير string literal، وrequire مستخدمة كقيمة (const r = require). عدم المطابقة يُرجع LOUSHO_REGISTRY_MANIFEST_MISMATCH مع كل ملاحظة بالشكل <file>:<line>: <what> (<fix>)؛ و--dry-run يبلّغ عنها أيضًا. ملفات Markdown وغيرها مما ليس كود (مثل SKILL.md في الـskill) لا تُفحص. يجب أن تكون مدخلات network أسماء host أو wildcards تبدأ بـ*. (api.example.com و*.example.com — الـwildcard يطابق الـsubdomains فقط، لا الـhost المجرّد)، ومدخلات env أسماء متغيرات (SEARCH_KEY)؛ أي شيء آخر يُرجع LOUSHO_REGISTRY_INVALID.
  • الموافقة تغطي الصلاحيات المرتفعة. exec: true وfilesystem: "write" وnetwork غير الفارغ وenv غير الفارغ تُوسم [elevated: ...] في الـmanifest المطبوع. السؤال التفاعلي يسردها قبل [y/N]. ومع --yes يجب أن تسمّي كل واحدة في --allow (--allow network,env للمثال أعلاه)، لأن --yes هو الطريقة التي تشغّل بها السكربتات والـagents الأمر lousho add، ولا ينبغي أن يمنح تنفيذ أوامر بصمت.
  • إيصال بما ثُبِّت. بعد الكتابة، lousho add يحدّث lousho-registry.json في جذر الـagent directory (بجانب instructions.md). مدخل كل عنصر فيه type وregistry الذي جاء منه وinstalledAt وpermissions وpath وsha256 لكل ملف، فتستطيع لاحقًا معرفة ما إذا عُدّل ملف. --overwrite يستبدل المدخل؛ --dry-run لا يكتب شيئًا. الإيصال غير الصالح كـJSON يوقف التثبيت قبل كتابة أي ملف. والإيصال هو ما يفرضه loadAgentDir عند التحميل ووقت التشغيل (أدناه).
وما يفرضه loadAgentDir، انطلاقًا من الإيصال، عندما يُحمَّل الـagent وتعمل أدوات العنصر:
  • السلامة. كل ملف يسرده الإيصال يُعاد حساب هاشه. الملف الذي عُدّل أو حُذف منذ ذلك الحين يجعل عنصره unattested (غير مُصدَّق): تحذير يذكر العنصر والملفات المتغيرة، وresolveAgentDir() يبلّغ عن الشيء نفسه في manifest.registry (status: 'attested' | 'unattested'، إضافة إلى مسارات modified وmissing). التحميل لا يُرفض — الملفات ملكك تعدّلها — والإيصال الذي يتعذّر قراءته تحذير، لا خطأ.
  • الـapproval. أدوات العنصر المصرِّح فيه بـexec: true أو needsApproval: true — وأدوات أي عنصر unattested لم يعد إيصاله القديم يشهد للكود المعدَّل — تنتظر approval دائمًا؛ وdeny من needsApproval الخاصة بالأداة نفسها يظل رافضًا. ولا شيء داخل الـagent directory يستطيع تجاوزها: قاعدة صلاحيات من نوع allow ووضع صلاحيات (acceptEdits) لا يشغّلان الاستدعاء (قاعدة deny أو plan أو dontAsk تظل ترفضه)، وملف approve الخاص بالمجلد نفسه يؤجّله. الذي يقرر فقط هو شخص يحلّ التوقف (agent.approvals.resolve()) أو callback approve يمرّره كودك إلى loadAgentDir(dir, { approve }).
  • الـsub-agents. مجلد الـsub-agent داخل العنصر المثبَّت (subagents/<name>/ في الـkit) يخضع للإيصال نفسه: أدواته مقيّدة مثل باقي أدوات العنصر، وملف approve الخاص به يؤجّل استدعاءاتها المفروضة أيضًا. توقف الـsub-agent ليس له مقبض approvals.resolve()، فالذي يقرر فيها هو callback approve الذي يمرّره كودك إلى loadAgentDir()؛ وبدونه لا يعمل الاستدعاء المفوَّض، ويُبلَّغ الوكيل الرئيسي أن الـsub-agent توقف بانتظار approval.
  • الشبكة. أثناء عمل أداة لعنصر له إيصال، fetch يقتصر على الـhosts التي يصرّح بها network: الـhost غير المدرج في الـmanifest يُرفض، والعنصر الذي لا يصرّح بأي network لا يستطيع إجراء fetch أصلًا.
  • البيئة. وأثناء عملها، process.env يعرض للأداة فقط الأسماء التي يصرّح بها env.
  • أدوات الـsandbox. الأداة التي تعلن requiresSandbox تحصل على adapter مضيَّق: run() يُرفض بدون exec، وwriteFile() بدون filesystem: "write"، وبيئة الأمر هي الأساس المعتاد غير السري زائد المتغيرات المصرَّح بها فقط.
التقييد يظل بضيق الـmanifest الذي قُبل عند التثبيت على الأقل، سواء كان العنصر مُصدَّقًا أم لا: تعديل ملف مثبَّت يوسمه ويطلب approval على استدعاءاته ولا يوسّع شيئًا، إلى أن يثبّت lousho add <name> --overwrite الملفات الحالية ويصدّقها من جديد. ما لا يفعله: فحص وقت التثبيت يقرأ الكود كما هو مكتوب، وتقييد وقت التشغيل يغطي فقط ما يستطيع الـSDK اعتراضه — استدعاءات fetch وقراءات process.env أثناء عمل الأداة، والـadapter المسلَّم لأداة sandbox. الطلبات عبر http/net/axios، والوصول للملفات، ومرجع محفوظ في module scope (const f = fetch)، والعمل المنفَّذ عند استيراد الملف، وسياسة الشبكة الخاصة بالحاوية نفسها ({ allow } في SubprocessSandbox خاصية للـsandbox لا للعنصر) — كل هذا خارجه. وكذلك الكود الذي يخفي ما يفعله (string escapes وaliasing وحمولات مشفَّرة وdependency تؤدي العمل) عن الفحص الساكن. اقرأ الملفات التي يسردها (يعرضها --dry-run) كما تقرأ أي dependency قبل تشغيلها.

قواعد الأمان

  • يجب أن يكون كل files[].path نسبيًا وnormalized وبشرطات أمامية: لا ..، لا مسار مطلق، لا حرف قرص (C:)، لا backslashes، لا مقاطع فارغة أو .. وبعد حل الـsymlinks يجب أن يظل داخل الـagent directory، ولا يُكتب أبدًا عبر symlink إلى هدفه.
  • يجب أن يكون الملف داخل المجلد الذي يسمح به نوع عنصره: tool في tools/، وskill في skills/<name>/، وchannel في channels/، وschedule في schedules/، وmemory في memory/. الـkit هو الاستثناء الوحيد: لأنه agent directory كامل، يمكن أن تقع ملفاته في أي مسار نسبي (تظل normalized وداخل الهدف حسب القاعدة أعلاه).
  • الملفات الموجودة لا تُستبدل بدون --overwrite. كل الملفات تُفحص قبل كتابة أي منها، فالعنصر المعيب لا يكتب شيئًا. كل إخفاق من هذه هو LOUSHO_REGISTRY_UNSAFE_PATH أو LOUSHO_REGISTRY_FILE_EXISTS.
  • الحد الأقصى للملف 256 KiB وللعنصر 1 MiB؛ ومستند الـregistry مليونا حرف كحد أقصى.
  • تُقرأ فقط روابط http(s) والمسارات المحلية، بمهلة 15 ثانية لكل fetch (وإلا LOUSHO_REGISTRY_UNREACHABLE).
  • dependencies تُطبع كسطر npm install ... لتشغّله أنت. الأمر لا يثبّت حزمًا أبدًا.
الأخطاء مسردة في الأخطاء. والـCLI كامل في CLI.