عن المشروع

dsh-sql هو ملحق قاعدة بيانات موجه لـ DSH (DeepSeek Harness)، مما يتيح للوكيل الاتصال بقواعد البيانات وتشغيلها. يوفر ست أدوات تغطي إدارة الاتصال، والاستعلامات للقراءة فقط، وعمليات الكتابة، واستكشاف البنية، ونظرة عامة على الإحصائيات، والفحص الصحي الذاتي. نظرة عامة على الأدوات: - sql_list: يسرد الاتصالات المكونة ويختبر الاتصال. - sql_query: استعلام للقراءة فقط، يدعم SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH، ويستخدم قائمة بيضاء بالكلمات المفتاحية ويرفض العبارات المتعددة. - sql_exec: عمليات الكتابة وDDL، يمكنه تنفيذ نصوص متعددة العبارات، مقيد بمفتاح readOnly وبوابة الموافقة. - sql_schema: يسرد قائمة الجداول أو يعرض بنية جدول محدد، مع التحقق من أسماء الجداول عبر قائمة بيضاء للمعرّفات. - sql_stats: يوفر نظرة عامة على عدد الجداول وعدد الصفوف وحجم قاعدة البيانات، مع عزل فشل الاستعلامات عن بعضها. - sql_health: يختبر الاتصال النشط لكل اتصال ويتحقق من إعدادات الأمان، دون إظهار كلمات المرور. المحركات والاتصالات: يستخدم SQLite node:sqlite المدمج في Node 22.13+ بدون تبعيات؛ يستخدم MySQL تجمع اتصالات mysql2؛ يستخدم PostgreSQL تجمع اتصالات pg. يمكن تعريف اتصالات متعددة مسماة في التكوين، مع تحديد المحرك ومعلمات الاتصال لكل منها. إذا لم يتم توفير تكوين، يتم افتراضيًا توفير اتصال SQLite واحد :memory:؛ ولكن إذا كان التكوين موجودًا وغير صالح، فسيتم إيقاف التحميل مباشرة مع خطأ، دون الرجوع بصمت إلى قاعدة بيانات الذاكرة. التصميم الأمني: - حماية معجمية للقراءة فقط: يزيل sql_query أولاً السلاسل والتعليقات ثم يتحقق، ويرفض CTEs المعدلة للبيانات (WITH…DELETE/UPDATE)، وSELECT INTO، وFOR UPDATE/FOR SHARE، وتعيينات PRAGMA، والعبارات المتعددة. - بوابة موافقة الكتابة: يعرض sql_exec موافقة افتراضيًا، ويرفض التنفيذ في البيئات غير التفاعلية (headless) دون قناة موافقة. - وضع readOnly: يمكن تعطيل عمليات الكتابة بالكامل، مناسب لقواعد بيانات الإنتاج. - تقييد تدفق الصفوف: يجمع مكرر SQLite، وReadable الخاص بـ MySQL، وأحداث صف Query في PostgreSQL بحد أقصى maxRows+1 صفًا، مع وضع علامة truncated عند التجاوز؛ عند الوصول إلى الحد في MySQL وPostgreSQL، يتم إغلاق الاتصال المخصص لذلك الاستعلام، وإلا يتم إرجاعه إلى التجمع، لتجنب بقاء النتائج الكاملة في الذاكرة. - تنفيذ قابل للإلغاء: تلتزم الاستعلامات وعمليات الكتابة بإشارة exec.signal الخاصة بـ Harness، وعند الإلغاء يتم إيقاف الانتظار وتدمير اتصالات MySQL/PostgreSQL المخصصة قيد العمل. - أعداد صحيحة كبيرة بدون فقدان: تُخرج bigint كرقم إذا كانت ضمن نطاق الأعداد الصحيحة الآمنة في JavaScript، وإلا تُخرج كسلسلة عشرية، لتجنب فقدان الدقة الصامت. - التحقق من المعرّفات: تسمح أسماء الجداول فقط بالحروف والأرقام والشرطات السفلية، لمنع حقن المخطط. - عدم تخزين الأسرار في التكوين: تدعم كلمات المرور التوفير عبر متغيرات البيئة DSH_SQL_PASSWORD_<اسم الاتصال>. تشمل عناصر التكوين maxRows (الحد الأقصى لصفوف نتائج الاستعلام، 1-10000)، وqueryTimeoutMs (مهلة الاستعلام الواحد، افتراضي 60 ثانية)، وexecTimeoutMs (مهلة عملية الكتابة الواحدة، افتراضي 120 ثانية)، وreadOnly وwriteApproval. طريقة التثبيت هي dsh plugin --profile web add dsh-sql، وبعد الإلغاء يجب إعادة تشغيل خدمة الويب. المشروع مرخص بموجب MIT، وأثناء التطوير يُستخدم pnpm install وpnpm test (بناء مع مجموعة اختبارات كاملة، بما في ذلك تكامل SQLite حقيقي). يوضح README التحقق على @deepseek-ai/dsh@0.1.5-rc.1 الرسمي وNode 24.16.0، باستخدام نموذج حزمة cordis.patch.yml وdsh.bundle.patch مجتمعين.