> ## Documentation Index
> Fetch the complete documentation index at: https://lousho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# السجل

`lousho add` يثبّت أداة أو مهارة أو قناة أو جدولًا زمنيًا أو خانة ذاكرة في
[مجلد وكيل](/ar/agent-directories) من سجل. السجل مجرد JSON
ثابت: فهرس ومستند لكل عنصر يحمل محتويات ملفاته.
تُنسخ الملفات إلى مشروعك شيفرةً مصدرية تملكها وتستطيع تعديلها. لا يوجد
محمِّل إضافات في وقت التشغيل، ولا يُنفَّذ أو يُستورد أي شيء من السجل
أثناء الإضافة.

لا يوجد سجل مستضاف حتى الآن. وجّه `lousho add` إلى سجل عبر `--registry` أو
متغير البيئة `LOUSHO_REGISTRY`؛ ودون أي منهما يفشل بالخطأ
`LOUSHO_CONFIG_INVALID` ويبيّن كيف تمرّر سجلًا.

```bash theme={null}
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` موقع
مستند العنصر؛ والمسار النسبي يُحلّ نسبةً إلى موقع الفهرس نفسه.

كل مستند عنصر يكون بهذا الشكل:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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` حين تطلب أدواته [موافقة](/ar/approvals) قبل أن تعمل. |

البيان هو ما يقول المؤلف إن الشيفرة تفعله. الـ 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 ...` لتنفّذه أنت.
  الأمر لا يثبّت حزمًا أبدًا.

الأخطاء مسرودة في [الأخطاء](/ar/errors#السجل). وواجهة سطر الأوامر كلها في
[CLI](/ar/cli).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.