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:
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()) أو callbackapproveيمرّره كودك إلىloadAgentDir(dir, { approve }). - الـsub-agents. مجلد الـsub-agent داخل العنصر المثبَّت (
subagents/<name>/في الـkit) يخضع للإيصال نفسه: أدواته مقيّدة مثل باقي أدوات العنصر، وملفapproveالخاص به يؤجّل استدعاءاتها المفروضة أيضًا. توقف الـsub-agent ليس له مقبضapprovals.resolve()، فالذي يقرر فيها هو callbackapproveالذي يمرّره كودك إلىloadAgentDir()؛ وبدونه لا يعمل الاستدعاء المفوَّض، ويُبلَّغ الوكيل الرئيسي أن الـsub-agent توقف بانتظار approval. - الشبكة. أثناء عمل أداة لعنصر له إيصال،
fetchيقتصر على الـhosts التي يصرّح بهاnetwork: الـhost غير المدرج في الـmanifest يُرفض، والعنصر الذي لا يصرّح بأيnetworkلا يستطيع إجراء fetch أصلًا. - البيئة. وأثناء عملها،
process.envيعرض للأداة فقط الأسماء التي يصرّح بهاenv. - أدوات الـsandbox. الأداة التي تعلن
requiresSandboxتحصل على adapter مضيَّق:run()يُرفض بدونexec، وwriteFile()بدونfilesystem: "write"، وبيئة الأمر هي الأساس المعتاد غير السري زائد المتغيرات المصرَّح بها فقط.
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 ...لتشغّله أنت. الأمر لا يثبّت حزمًا أبدًا.