السجل

lousho add يثبّت أداة أو مهارة أو قناة أو جدولًا زمنيًا أو خانة ذاكرة في مجلد وكيل من سجل. السجل مجرد JSON ثابت: فهرس ومستند لكل عنصر يحمل محتويات ملفاته. تُنسخ الملفات إلى مشروعك شيفرةً مصدرية تملكها وتستطيع تعديلها. لا يوجد محمِّل إضافات في وقت التشغيل، ولا يُنفَّذ أو يُستورد أي شيء من السجل أثناء الإضافة. لا يوجد سجل مستضاف حتى الآن. وجّه lousho add إلى سجل عبر --registry أو متغير البيئة LOUSHO_REGISTRY؛ ودون أي منهما يفشل بالخطأ LOUSHO_CONFIG_INVALID ويبيّن كيف تمرّر سجلًا.

lousho add --list --registry ./registry/index.json
lousho add web-search --registry https://example.com/registry/index.json --dir ./my-agent
LOUSHO_REGISTRY=./registry/index.json lousho add web-search --dry-run

الخيار	المعنى
`--registry <url-or-path>`	الفهرس: عنوان `http(s)` أو مسار محلي (ويُستخدم `LOUSHO_REGISTRY` عند غيابه).
`--dir <agent-dir>`	مجلد الوكيل الذي يُكتب فيه (الافتراضي: المجلد الحالي؛ ويجب أن يكون موجودًا).
`--yes`، `-y`	لا تطلب تأكيدًا. مطلوب حين لا يكون stdin طرفية.
`--overwrite`	استبدل الملفات الموجودة (ودونه يكون الملف الموجود خطأ `LOUSHO_REGISTRY_FILE_EXISTS`).
`--dry-run`	اطبع بيان الصلاحيات والملفات، ولا تكتب شيئًا، واخرج بالرمز 0.
`--list`	اطبع عناصر السجل ثم اخرج.

قبل أن يكتب أي شيء، يطبع lousho add بيان الصلاحيات (manifest) والملفات التي سيكتبها، ثم يسأل [y/N].

الصيغة

الفهرس هو { items: [{ name, type, description, url | path }] }. وtype أحد القيم tool أو skill أو channel أو schedule أو memory. يحدّد url / path موقع مستند العنصر؛ والمسار النسبي يُحلّ نسبةً إلى موقع الفهرس نفسه. كل مستند عنصر يكون بهذا الشكل:

{
  "name": "web-search",
  "type": "tool",
  "description": "Search the web with the Example Search API",
  "files": [
    {
      "path": "tools/web-search.ts",
      "content": "import { defineTool } from '@lousho/build-ai-agent';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  inputSchema: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
    }
  ],
  "permissions": {
    "network": ["api.example.com"],
    "env": ["SEARCH_KEY"],
    "filesystem": "none",
    "exec": false,
    "needsApproval": true
  },
  "dependencies": ["zod"]
}

ومدخله في index.json:

{
  "items": [
    { "name": "web-search", "type": "tool", "description": "Search the web with the Example Search API", "path": "items/web-search.json" }
  ]
}

استضف الاثنين ملفات ثابتة في أي مكان (مجلد في مستودع، أو مخزن كائنات، أو خادم ويب). يجب أن يطابق name وtype في المستند مدخله في الفهرس، ويتكوّن الاسم من أحرف وأرقام و. و_ و-. المستند الذي لا يطابق الصيغة يُعطي الخطأ LOUSHO_REGISTRY_INVALID، مع ذكر الحقول المعنية.

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

permissions يصرّح بما يستطيع العنصر فعله، لتقرر قبل تثبيته. كله اختياري؛ وما يغيب يُعرض بالقيمة “none” / “no”.

الحقل	المعنى
`network`	الخوادم (hosts) التي يتصل بها.
`env`	متغيرات البيئة التي يقرؤها.
`filesystem`	`none` أو `read` أو `write`.
`exec`	`true` حين ينفّذ أوامر.
`needsApproval`	`true` حين تطلب أدواته موافقة قبل أن تعمل.

البيان هو ما يقول المؤلف إن الشيفرة تفعله. الـ SDK لا يفرضه، وهو ليس بيئة معزولة: اقرأ الملفات التي يسردها (يعرضها --dry-run) كما تقرأ أي اعتمادية قبل تشغيلها.

قواعد الأمان

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

الأخطاء مسرودة في الأخطاء. وواجهة سطر الأوامر كلها في CLI.

البداية

بناء وكيل

تركيب الوكلاء

تشغيل موثوق

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

الاختبار والمراقبة

النشر

الصيغة

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

قواعد الأمان

​الصيغة

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

​قواعد الأمان

الصيغة

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

قواعد الأمان