المهارات الأصلية

المهارات الأصلية هي أدوات Python داخل العملية تأتي مع كاظمه وتُسجَّل تلقائيًا على LocalToolRegistry عند الإقلاع (لا عملية فرعية، ولا جولة شبكة — بخلاف خوادم MCP). تعيش في kazma-skills/kazma_skills/native/ ويكتشفها NativeSkillLoader.

المهارات تُحمَّل دائمًا حتى عند غياب تبعية اختيارية — استدعاء أداة خلفيتها غير مثبَّتة يعيد سلسلة تلميح تثبيت ودّية بدلًا من الفشل. ثبِّت الإضافة (extra) لتفعيل تلك الخلفية: pip install -e ".[document,database,web]".

لقائمة كل أداة الكاملة (الأسماء، والوسائط، وتصنيف الخطورة)، انظر كتالوج الأدوات.

أتمتة المتصفح (`browser_automation`)

تحكم بمتصفح بلا واجهة عبر Playwright للصفحات المعروضة بـJS والتي لا يستطيع جلب HTTP العادي قراءتها. تتطلب الإضافة [web] + تثبيت متصفح لمرة واحدة:

pip install -e ".[web]"
playwright install chromium

الأداة	ما تفعله
`browser_navigate`	فتح عنوان URL، وإرجاع العنوان + نص المتن المرئي
`browser_click`	النقر على عنصر عبر محدد CSS
`browser_extract_text`	استخراج النص من العناصر (أو المتن كاملًا)
`browser_screenshot`	لقطة شاشة للصفحة كاملة → `kazma-data/images/`
`browser_fill_form`	ملء المدخلات من تعيين `{selector: value}`
`browser_eval_js`	تقييم JavaScript في جانب الصفحة — مقيَّد بـHITL كخطر

سياق Chromium بلا واجهة مشترك يستمر عبر الاستدعاءات من أجل الكفاءة.

التقويم (`calendar`)

قراءة الأحداث وإدارتها. ثلاث خلفيات، تُختار عبر بيانات اعتماد مدعومة بالخزنة (نفس المخزن الذي يستخدمه Gmail). متغيرات البيئة تجاوز فقط، وليست مصدر الحقيقة.

Google Calendar — الإعدادات → البريد الإلكتروني → الاتصال بـGoogle (نطاق التقويم مضمَّن) أو الاتصال بـGoogle Calendar على بطاقة التقويم. تعيش الرموز في الخزنة كـcalendar.google.*. فعِّل Google Calendar API في مشروع Cloud. لا يُرسل رمز Gmail-فقط إلى التقويم أبدًا.
Microsoft Outlook (MS Graph) — الإعدادات → البريد الإلكتروني → الاتصال بـMicrosoft (يطلب Calendars.ReadWrite مع البريد)، أو الاتصال بتقويم Outlook على بطاقة التقويم للتقويم وحده.
زر قطع الاتصال لكل تقويم على البطاقة يعطّله حتى يُعاد الاتصال به هناك من جديد، حتى مع بقاء بريده مسجَّلًا للدخول.
البيئة الرملية (sandbox) — تقويم محلي في الذاكرة عندما لا يكون أي حساب متصلًا (provider=auto). الصريح provider="google" / "outlook" يفشل مغلقًا مع تلميح اتصال — لا يتظاهر بأنه تقويم حقيقي فارغ.

# Optional override only — prefer Settings → Email → the calendar card
export GOOGLE_CALENDAR_TOKEN=ya29...

الأداة	ما تفعله
`list_events`	سرد الأحداث في نطاق زمني (ISO 8601؛ الافتراضي الأيام السبعة القادمة)
`create_event`	إنشاء حدث (الملخص، البداية، النهاية، الموقع، الوصف)
`update_event`	تحديث حدث بالمعرف
`delete_event`	حذف حدث بالمعرف
`find_free_slots`	إيجاد الفترات الحرة بمدة معينة في تاريخ ما

استخدم provider="auto" (الافتراضي) لاختيار أول خلفية لديها بيانات اعتماد، أو provider="google" / "outlook" لتثبيت واحدة.

منصة المستندات (`document_platform`) — المفضَّلة

ذكاء مستندات دائم ومحدود بالمستأجرين عبر DocumentIngestionService المشترك. معرفات معتمة، ومهام آمنة ضد إعادة التشغيل، وقراءات مُسيَّجة. انظر ذكاء المستندات.

الأداة	الغرض
`document_import`	ملف آمن لمساحة العمل → استيعاب + تحليل دائمان؛ ينتظر حتى 30 ثانية بلوغ حالة نهائية، ويُبلغ بالحالة التي بلغها
`document_status`	حالة `job_id`، أو أحدث مهمة لـ `document_id`؛ بلا معرفات → نظرة عامة على منصة المستأجر
`document_read`	محتوى مُسيَّج صفحةً صفحة عبر معرف معتم (`page`، و`offset`، و`max_chars`، والافتراضي 20,000)
`document_index`	النشر في مكتبة معرفية (`library_id`)
`document_search`	البحث في المكتبة (`library_id`، و`query`، و`top_k`؛ نتائج مُسيَّجة)
`document_cancel`	إلغاء مهمة بالمعرف (خطر: تطلب الموافقة)
`document_convert`	تحويل التنسيق → ملف محفوظ (مساره، لـ `send_file`) ومعرف قطعته (artifact)
`document_redact`	حجب PDF فيزيائي → قطعة جديدة وملف محفوظ (خطر: تطلب الموافقة)

تعمل الأدوات بصفتها مشغّل التثبيت، مثل أمر الدردشة /documents وصفحة المستندات في واجهة الويب، فتقرأ ما رُفع هناك، وتسرد الصفحة ما تستورده (منذ 2026-10-13). ومع مستخدمي المنصات (وضع تعدد المستخدمين) ترفض. والمهمة أو المستند الذي لا تستطيع قراءته يُجاب عنه كأنه غير معروف.

يعمل منسِّق المهام (coordinator) على التثبيت الأساسي (pypdf وpdfplumber وpython-docx وopenpyxl وpython-pptx تبعيات أساسية). وتضيف الإضافة [document-platform] كلًّا من PyMuPDF (أول محلِّل لملفات PDF، والحجب)، وpypdfium2، وOCR ‏(pytesseract وpdf2image وPillow)، وWeasyPrint ‏(HTML/Markdown → PDF)؛ أما Tesseract وLibreOffice وClamAV فحزم نظام. وما هو جاهز يُعرض حيًّا: /documents health أو GET /api/documents/health (وفي ملف تعريف العامل في الحاوية، يكون التقرير هو تقرير صورة العامل نفسها).

توليد المستندات (`document_generator`) — المسار البسيط / القديم

إنشاء مستندات بسيطة من محتوى منظم دون المنصة الدائمة. تهبط الملفات تحت kazma-data/documents/. فضِّل document_platform عندما تحتاج معرفات معتمة، أو ACL، أو مهامًا، أو إعادة استيعاب. ومع ذلك يجري التوليد في عامل العرض المعزول (DocumentService.generate)، ويجتاز ملف PDF المولَّد فحص المحتوى النشط نفسه الذي يجتازه الملف المرفوع قبل أن يغادر العامل.

المكتبات reportlab وpython-docx وopenpyxl تبعيات أساسية، فلا يحتاج PDF/DOCX/XLSX إلى أي إضافة؛ ولا تبقى [document] إلا اسمًا مستعارًا للتوافق.

الأداة	المخرجات	المكتبة
`generate_pdf`	`.pdf` في `kazma-data/documents/`	reportlab
`generate_docx`	`.docx`	python-docx
`generate_xlsx`	`.xlsx` (متعدد الأوراق)	openpyxl
`generate_markdown_doc`	`.md`	(بلا تبعية)

كل أداة تأخذ عنوانًا + أقسامًا ([{heading, body}])، أو أوراقًا لـXLSX.

خطوط PDF العربية: يستخدم generate_pdf زوج IBM Plex Sans Arabic نفسه المستخدم في واجهة الويب ووثائق Docusaurus (مضمَّن تحت kazma_core/documents/assets/fonts/). يُتحقق من التغطية مقابل أشكال العرض العربية قبل قبول الوجه؛ ويبقى Amiri خطًّا احتياطيًا من نوع النسخ (naskh) عند غياب Plex. تجاوز الدليل عبر KAZMA_DOCUMENT_FONT_DIR. الاتجاه لكل فقرة، لا لكل مستند: تُحاذى الفقرة العربية إلى اليمين والفقرة الإنجليزية إلى اليسار في الملف نفسه. ويُعرض ملف PDF الذي يحوي العربية عبر محرّك DOCX وLibreOffice ‏(soffice) حين يكون مثبَّتًا، من أجل تشكيل واتجاه ثنائي (bidi) حقيقيين؛ ودون LibreOffice يرتد إلى ReportLab ويقول ذلك في تحذير.

توليد الصور

أداة نواة مدمجة (generate_image في kazma_core/tools/image_gen.py)، وليست مهارة أصلية — متعددة الخلفيات عبر image_backends/router.py:

الخلفية	مفتاح المزوّد	يحتاج
Pollinations	`pollinations`	لا شيء (بلا مفتاح، الافتراضي)
DALL-E (OpenAI)	`dall-e`	`OPENAI_API_KEY`
Stability (SDXL)	`stability`	`STABILITY_API_KEY`
Flux (FAL.ai)	`flux`	`FAL_KEY`

يختار provider="auto" أول خلفية لديها بيانات اعتماد. تجاوز عبر KAZMA_IMAGE_PROVIDER. المخرجات → kazma-data/images/.

عميل قواعد البيانات (`database_client`)

الاستعلام عن قواعد البيانات للقراءة فقط. SQLite مدمج؛ وPostgres/MySQL/Mongo تحتاج الإضافة [database]:

pip install -e ".[database]"   # psycopg, pymysql, pymongo

الأداة	ما تفعله
`inspect_db_schema`	الجداول، والأعمدة، والأنواع، والمفاتيح الأساسية، والفهارس
`execute_db_query`	SELECT محلي في SQLite، أو قدرة قراءة بعيدة مسمّاة
`sqlite_query`	اسم مستعار ملائم لـSQLite المحلي

تبقى مسارات SQLite محصورة بمساحة العمل، وتُرفض مخازن كاظمه نفسها. تستخدم القراءات البعيدة db_uri="connection:warehouse". تُرفض عناوين URI البعيدة الخام، بما فيها عناوين localhost. يعرّف المشغّل الاتصال في security.database_client.connections، وهو إعداد محمي لا يستطيع الوكيل كتابته. يحتاج كل مدخل enabled: true وdsn محفوظًا في الخزنة وrole الدخول المتوقع، وقائمة tenants صريحة وtables بأسماء مؤهلة schema.table (أسماء المجموعات في MongoDB). تُرفض الأنماط البديلة العامة.

مثلًا، يمكن للمشغّل تسجيل قارئ PostgreSQL من بيئة Python الخاصة بالتثبيت. شغّل هذا بعد تحميل إعدادات التثبيت المعتادة وضبط خزنة مشفرة؛ ولا تضع كلمة المرور في موجّه أو Git:

import os
from kazma_core.config_store import get_config_store
from kazma_core.security.vault import get_vault

vault = get_vault()
assert vault is not None, "Configure the encrypted vault first"
vault.store_install_scoped("warehouse_read_dsn", os.environ["WAREHOUSE_READ_DSN"], category="database")
get_config_store().set("security.database_client.connections", {
    "warehouse": {
        "enabled": True,
        "dsn": "vault://warehouse_read_dsn",
        "role": "kazma_reader",
        "tenants": ["default"],
        "tables": ["reporting.items"],
    }
})

تستخدم SQL البعيدة قواعد SELECT محلّلة، مع الإسقاطات المعتادة والمقارنات والوصلات وCTE غير المتكررة ومجموعة صغيرة من دوال التجميع والنصوص المدمجة. تُرفض الدوال المجهولة والتحويلات والعوامل المخصصة والأقفال وINTO والعبارات المتعددة والجداول خارج القدرة قبل الاتصال. تثبّت قراءات PostgreSQL search_path على pg_catalog وتحتاج أسماء جداول مؤهلة. تعمل معاملات %s الموضعية في كلا مشغّلي SQL. تُرفض العروض والجداول الخارجية والموروثة وRLS وأنواع PostgreSQL المخصصة والأعمدة المولّدة؛ فقد تشغّل قراءتها كودًا خارج القدرة المعلنة.

استخدم حساب قاعدة بيانات مخصصًا، وليس مالك التطبيق أو مشرفه:

PostgreSQL: بلا امتيازات دور مرتفعة أو عضويات، ولا CREATE/TEMP للقاعدة، ولا CREATE للمخطط، ولا منح كتابة للجداول أو الأعمدة، ولا EXECUTE لإجراءات التطبيق والإضافات. امنح CONNECT وUSAGE للمخطط وSELECT للجداول العادية المعلنة. اسحب TEMP الافتراضي من PUBLIC في قاعدة التقارير المخصصة، وEXECUTE من PUBLIC لإجراءاتها غير الكتالوجية؛ يجب أن يقيّم مشرف هذه التغييرات قبل تطبيقها على قاعدة تطبيق مشتركة. تتحقق الأداة من الشروط في كل اتصال وترفض انحراف الامتيازات.
MySQL 8: منح SELECT/USAGE فقط، دون خيار منح أو عضويات أدوار؛ يجب أن تكون الجداول المعلنة جداول InnoDB أساسية. لم يُؤهّل MariaDB: يرفض الخادم الذي يفتقر إلى إعداد مهلة عبارات MySQL القراءة.
MongoDB: دور مخصص بصلاحيات find للمجموعات فقط، مطابق للقاعدة والمجموعات المعلنة. تُرفض أدوار read القياسية الأوسع. تدعم المرشحات مقارنات البيانات والشروط المنطقية؛ وتُرفض $where و$expr و$function والتعابير النمطية والعوامل الأخرى. يختار params[0] مجموعة مسموحة.

مهلة تنفيذ الاستعلام ثانيتان على الخادم أو SQLite، والحدود 1,000 صف و16,384 محرفًا للاستعلام ومليون محرف للنتيجة المعادة. انتظار الاتصال والمقبس البعيد محدود، وتُغلق الاتصالات بعد كل نداء. تُفحص حدود المخرجات بعد الجلب؛ لذلك ينبغي للمشغّل إتاحة أعمدة محدودة الحجم وحصص موارد للقاعدة. تحتاج الاتصالات غير المحلية TLS متحققًا منه (يستخدم PostgreSQL شهادة الجذر المضبوطة؛ ويستخدم MySQL وMongoDB إعداد الثقة في المشغّل). تُرفض خيارات الاستعلام في DSN. ثبّت الإضافة [database] للحصول على SQLGlot والمشغّلات البعيدة.

مهارات أصلية أخرى

المهارة	الأدوات	ملاحظات
`email_manager`	email_accounts/list/get/send/delete/categorize/analyze	Gmail، وMS Graph، وIMAP/POP، وsandbox
`git_github_manager`	git_status/log/diff/commit/push/pull/checkout/merge, github_create_pr/merge_pr/create_issue/comment_issue/list_issues	`git_log` و`git_diff` للقراءة فقط (دون موافقة)
`secret_vault`	vault_store/retrieve/list/delete	مشفَّر AES-256-GCM
`advanced_web_crawler`	web_search_duckduckgo, crawl_page, parse_document	تحليل CSV/JSON/XLS/PDF
`system_health_monitor`	get_system_stats, list_active_processes, read_system_logs
`task_scheduler_cron`	schedule_task, list_scheduled, edit_scheduled, cancel_scheduled	الحجز والتعديل والإلغاء مقيَّدة بـHITL. انظر التذكيرات والمهام المجدولة
`x_publisher`	x_status, x_post, x_delete_post, x_schedule_post, x_list_scheduled, x_cancel_scheduled_post, x_download_media, x_draft_posts	واجهة X API v2 الرسمية. كتابات الدردشة HITL دائمًا. التحرير/التخطيط على الويب هو X Studio (`/x`)
`environment_bootstrapper`	install_python_packages, install_npm_packages, check_environment	مقيَّد بـHITL
`visual_interpreter_generator`	analyze_local_image, generate_ui_mockup
`arabic_bilingual_nlp`	arabic_translate, hijri_convert, insert_diacritics
`chat_platform_dispatcher`	dispatch_notification, send_approval_request, send_message	إشعار عبر المنصات
`code_analyzer_linter`	lint_code, format_code, run_unit_tests	ruff + pytest
`code-review`, `fix-lint`, `refactor-file`, `write-tests`	(بالبيان فقط، بلا أدوات)	مهارات موجِّه/سير عمل

التذكيرات والمهام المجدولة

تحجز schedule_task مهمةً مجدولة؛ وتقرأ list_scheduled وedit_scheduled وcancel_scheduled المهام المجدولة لتثبيت المحادثة وتغيّرها. وتعرض صفحة المهام المجدولة (/scheduled) المهام نفسها، مع منشورات X المحجوزة في استوديو X. ويطلب كلٌّ من الحجز والتعديل والإلغاء موافقة.

ما تستطيع المهمة المجدولة فعله حين تنطلق

المهمة المجدولة أحد نوعين، يُختار عند حجزها:

النوع	حين تنطلق	الأدوات
`reminder` (الافتراضي)	ترسل نصها المخزَّن، كما كُتب، إلى المحادثة التي حُجزت منها. بلا استدعاء نموذج.	لا شيء
`task`	تشغّل دورًا واحدًا للوكيل على تعليمتها المخزَّنة، ثم ترسل الإجابة إلى تلك المحادثة.	المجموعة المعلنة عند الحجز فقط: `read` (أدوات القراءة فقط، الافتراضي) أو `read_write` (أدوات الكتابة أيضًا). لا أدوات MCP أبدًا، ولا الأدوات التي تحتاج موافقة دائمًا.

تذكر بطاقة موافقة الحجز أيّ النوعين هي، والأدوات التي ستُتاح للمهمة. ويُرفض استدعاء أي أداة أخرى حين تنطلق المهمة المجدولة.
تصل التعليمة إلى النموذج موسومةً بأنها تعليمة خُزِّنت من قبل، لا بأنها شيء قاله المستخدم للتو.
لا تنطلق مهمة من نوع task ما دامت الموافقات (HITL) معطَّلة، ما لم يكن المشغّل قد فعّل safety.cron_fire_without_hitl. ولا يستطيع الوكيل تفعيله بنفسه. أما التذكير فينطلق مع ذلك: فهو لا يشغّل أي نموذج.
لدور المهمة من نوع task ميزانية زمنية (cron.task_budget_seconds، والافتراضي 300). والدور الذي يفشل — لأن مزوّد النموذج متوقف، أو لأن الدور يقع في خطأ أو ينفد وقته — إطلاقٌ فاشل: يُحتسب على المهمة المجدولة ويرفع تنبيهًا. ولا يُرسل نص الخطأ أبدًا كأنه التذكير. وبعد 3 إخفاقات متتالية تتوقف المهمة المتكررة، مع تنبيه.

التسليم والمهام المتأخرة والفائتة

لا تُعدّ الرسالة مُرسَلة إلا حين يقبلها تطبيق المحادثة. وتُعاد محاولة الرسالة المرفوضة بانتظار متزايد، لمدة تصل إلى ساعتين. ثم تنتهي المهمة المجدولة بحالة لم تُسلَّم (undeliverable)، مع تنبيه واحد. وإن توقفت كاظمه في منتصف الإرسال، تنتهي المهمة بحالة الإرسال غير مؤكد (delivery unknown)، مع تنبيه واحد، ولا تُرسل الرسالة مرة ثانية.
المهمة التي حلّ موعدها وكاظمه متوقفة تنطلق مع ذلك إن لم يتجاوز تأخرها cron.catchup_minutes (الافتراضي 60)، وتذكر مقدار تأخرها. والمهمة المتأخرة أكثر من ذلك فاتت (missed): لا تعمل، وتتلقى محادثتها إشعارًا واحدًا. ثم تنتقل المهمة المتكررة إلى موعدها التالي. والنافذة المعطاة عند حجز المهمة تتقدّم على الإعداد.
الإطلاق المقطوع يعمل مرة أخرى بعد إعادة التشغيل. وإعادة التحميل بـ --when-idle تنتظر الإطلاق الجاري.
لا تُضيِّع أي إعادة تشغيل أحد هذه التنبيهات. فكلٌّ منها يُسجَّل مع الإخفاق الذي يبلّغ عنه، ويُرفع بعد ذلك. وإن توقفت كاظمه بعد رفع تنبيه وقبل تسجيل أنها رفعته، يُرفع التنبيه مرة أخرى حين تبدأ كاظمه.

الأوقات

تُقرأ الأوقات في المنطقة الزمنية لـ cron (الإعدادات، cron.timezone؛ وإلا KAZMA_TZ؛ وإلا UTC). وتقبل كاظمه هذه الصيغ:

مدة تأخير: 30m، و2h، و3d؛
وقت ISO: ‏2026-12-01T09:00، يُقرأ في تلك المنطقة؛ وتُحترم Z والإزاحات؛
تكرار: daily at 9am، أو weekdays at 08:00، أو every mon,wed at 21:00، أو قاعدة RRULE مثل FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0;COUNT=10.

ترفض كاظمه وقتًا في الماضي أو بعد أكثر من سنتين. وترفض أيضًا وقتًا لمرة واحدة لا وجود له في يوم تغيير الساعة، أو يقع مرتين؛ فأعطِ إزاحة بدلًا منه. وتستخدم المهمة المتكررة أبكر الوقتين المكرَّرين، وتقدّم الوقت غير الموجود بمقدار التغيير. ولا تقبل منشورات X إلا أوقاتًا لمرة واحدة.

تغيير مهمة

يذكر التعديل أو الإلغاء نسخة المهمة التي قرأها. والمهمة التي تغيّرت في الأثناء تجيب بتعارض؛ حدِّث ثم حاول مجددًا.
المهمة التي تعمل الآن تأخذ التعديل أو الإلغاء حين ينتهي تشغيلها.
لا تعود المهمة المنتهية إلا عبر شغّل مرة أخرى (Run again).
التعديل الذي يقتصر على التوقيت لا يغيّر الموجِّه المخزَّن أبدًا.
يسجّل كل تغيير من أجراه ومن أين.

على تثبيت فيه مستخدمو منصات (وضع تعدد المستخدمين)، تكون الجدولة معطَّلة: تعرض الصفحة السبب، وترفض الأدوات والمسارات. فالمهام المجدولة لم تُفصل لكل مستخدم بعد.

تأليف مهارتك الخاصة

انظر إنشاء المهارات و مواصفات بيان المهارة. المهارة الدنيا هي دليل تحت native/<name>/ يحوي skill_manifest.yaml (بيانات وصفية + مفاتيح أدوات) وtools.py (دوال غير متزامنة تطابق أسماؤها مفاتيح البيان). الأدوات تُكتشف تلقائيًا — لا حاجة إلى أي استدعاء تسجيل.