الوصول الخارجي (CLI وعملاء الذكاء الاصطناعي)

الوصول الخارجي يتيح لبرامج سطر الأوامر المحلية وعملاء الذكاء الاصطناعي المتوافقين مع MCP إدارة السكرپتات في ScriptCat عبر sctl.

AI client ── stdio MCP ──▶ sctl mcp ── local control API ──▶ sctl serve ── WebSocket ──▶ ScriptCat
CLI ────────────────────────────────────────────────────────▲

sctl serve هو خدمة خلفية محلية منفصلة يجب عليك تشغيلها صراحة. sctl mcp وأوامر الطلب لا تقوم بتشغيلها تلقائياً أبداً. سياسات ScriptCat وواجهة تأكيد المتصفح هي التي تقرر دائماً ما إذا كان كشف المصدر أو الكتابة مسموحاً به؛ لا يمكن لبرنامج خارجي الموافقة على طلبه الخاص.

المستمع محلي افتراضياً

يستمع sctl على 127.0.0.1 افتراضياً. يستمع على واجهة أخرى فقط عند تمرير --listen-address صراحة. ws:// لا تشفر حركة البيانات ولا يوجد عزل لكل عميل بعيد، لذا استخدم عنواناً غير افتراضي فقط على شبكة موثوقة. ومع ذلك، تنشئ الإضافة والخدمة الخلفية مفتاحاً طويل الأمد عبر رمز اقتران لمرة واحدة وتستخدم المصادقة المتبادلة في الاتصالات اللاحقة.

1. تثبيت sctl

قم بتثبيت أحدث إصدار بأمر واحد — macOS و Linux:

curl -fsSL https://raw.githubusercontent.com/scriptscat/sctl/main/scripts/install.sh | sh

أو Windows PowerShell:

irm https://raw.githubusercontent.com/scriptscat/sctl/main/scripts/install.ps1 | iex

يقوم برنامج التثبيت بتنزيل أرشيف الإصدار sctl-<version>-<os>-<arch>.<ext> الخاص بمنصتك، ويتحقق من sha256 الخاص به مقابل checksums.txt من نفس الإصدار، ويثبت sctl في ~/.local/bin (macOS/Linux) أو %LOCALAPPDATA%\sctl\bin (Windows). SCTL_VERSION يثبت إصداراً معيناً؛ SCTL_INSTALL_DIR يتجاوز دليل التثبيت. إذا لم يكن دليل التثبيت في PATH الخاص بك، يطبع برنامج التثبيت تلميح PATH الدقيق لمنصتك — لا يعدّل ملف تعريف الصدفة أو PATH الخاص بالمستخدم أبداً.

sctl هو ملف تنفيذي واحد. إذا كان GitHub Releases يحتوي على أرشيف منشور لمنصتك، يمكنك أيضاً تنزيله وفك ضغطه، ثم وضع sctl (sctl.exe على Windows) في PATH.

sctl version

البناء العادي من المصدر يبلغ عن 0.0.0-dev لتمييزه عن البناء الرسمي الذي يحقن إصداراً و commit وبيانات وقت البناء؛ وهذا لا يمنعه من الاتصال بـ ScriptCat. إذا لم يتوفر إصدار رسمي، يمكن للمساهمين بناؤه من مستودع sctl.

2. تشغيل الخدمة الخلفية والتسجيل

التسجيل خطوة تتم لمرة واحدة. بعد ذلك، تشارك CLI وكل عميل MCP قناة الإضافة-إلى-الخدمة الموثوقة؛ ولا يقترنون بشكل منفصل.

2.1 اختر دليل بيانات

يجب أن تستخدم الخدمة الخلفية و CLI وعملية MCP نفس دليل البيانات. يخزن مفتاح الاقتران طويل الأمد ورمز التحكم المحلي والسجلات. اختر مساراً مطلقاً خاصاً بالمستخدم الحالي:

/absolute/path/to/sctl-data

اضبط نفس متغير البيئة لكل عملية sctl:

export SCTL_DATA_DIR=/absolute/path/to/sctl-data
sctl serve
sctl status
sctl mcp

--data-dir الصريح له الأولوية على متغير البيئة.

إذا لم يتم ضبط --data-dir ولا SCTL_DATA_DIR، يستخدم sctl دليل بيانات التطبيق الافتراضي لكل مستخدم في المنصة. لا تضع دليل البيانات في مستودع أو مجلد مزامنة مشترك، ولا تعطِ pairing.key أو control.token الخاصين به لنموذج ذكاء اصطناعي أبداً.

2.2 تشغيل الخدمة الخلفية

شغّل هذا في طرفية وأبقِ العملية حية:

sctl serve

العنوان الافتراضي هو ws://127.0.0.1:8643. لا يتم تشغيل الخدمة الخلفية تلقائياً أبداً بواسطة connect أو status أو أمر CLI آخر أو sctl mcp. للاستخدام المستمر، شغّل الأمر أعلاه مع مدير خدمة المستخدم في نظام التشغيل الخاص بك.

للاستماع صراحة على كل واجهات الشبكة، شغّل:

sctl --listen-address 0.0.0.0:8643 serve

على مضيف الخدمة، مرر نفس --listen-address إلى connect و status وأوامر CLI الأخرى و sctl mcp. في إعداد عنوان sctl في ScriptCat، أدخل عنواناً يمكن للإضافة الوصول إليه فعلياً، مثل ws://192.168.1.10:8643؛ لا تدخل 0.0.0.0.

2.3 التفعيل والاقتران في ScriptCat

1. افتح الإعدادات ← الأدوات ← الوصول الخارجي في ScriptCat وفعّل المفتاح.

2. تأكد من أن عنوان sctl يطابق الخدمة الخلفية؛ أبقِ الافتراضي ws://127.0.0.1:8643 عادةً.

3. أبقِ sctl serve قيد التشغيل ونفّذ في طرفية أخرى:

   sctl connect

4. أدخل رمز الطرفية المكون من 8 أحرف في مربع حوار "تسجيل sctl".

5. تحقق من الاتصال:

   sctl status

يجب أن تشير الحالة إلى إضافة متصلة وتعرض إصدار الخدمة الخلفية.

رمز الاقتران للطرفية فقط

يبدو الرمز مثل A1B2-C3D4، تنتهي صلاحيته بعد دقيقتين، ويُستخدم مرة واحدة. لا يتم إرساله إلى الإضافة عبر WebSocket. لا تلصقه أبداً في محادثة ذكاء اصطناعي أو issue أو سجل أو إعداد MCP؛ شغّل connect مرة أخرى إذا انتهت صلاحيته.

3. الأذونات والتأكيد

القدرة	السلوك الافتراضي
سرد السكرپتات وقراءة البيانات الوصفية	يُرجع مباشرة
قراءة أو البحث في كود السكرپت	يتبع سياسة قراءة المصدر
تثبيت أو تحرير أو تفعيل أو تعطيل أو حذف سكرپت	يتبع سياسة الكتابة

تقدم كلتا السياستين خيار "طلب الموافقة" (الافتراضي) و"السماح مباشرة".

مع "طلب الموافقة"، تفتح الطلبات صفحة تأكيد في المتصفح. يمكنك الرفض أو السماح مرة واحدة أو اختيار "السماح لهذه الجلسة". تكون السماحات الخاصة بالجلسة مرتبطة بالسكرپت ونوع العملية، وتُمحى عند إعادة تشغيل المتصفح أو إعادة تحميل الإضافة أو إيقاف الوصول الخارجي. تنتهي صلاحية الطلب بعد 5 دقائق دون قرار؛ كما يبطل انقطاع الطالب أو Ctrl-C الطلب.

"السماح مباشرة" يتخطى صفحة التأكيد لهذا النوع من العمليات. يمكن أن يحتوي المصدر على مفاتيح API وكوكيز وأسرار أخرى، بينما يمكن للكتابة تغيير السكرپتات مباشرة، لذا فعّلها فقط إذا كنت تقبل هذا الخطر.

4. الاستخدام من سطر الأوامر

sctl get                         # List scripts
sctl get <uuid>                  # Read metadata
sctl get <uuid> -o source        # Print full source
sctl get <uuid> -o source --lines 20-80
sctl grep <uuid> "fetch("         # Literal source search
sctl grep <uuid> "pattern" -E    # Regular expression
sctl install <url|file>
sctl edit <uuid> --replace OLD --with NEW
sctl enable <uuid>
sctl disable <uuid>
sctl delete <uuid>
sctl status

grep حرفي افتراضياً؛ -E يفعّل التعبيرات النمطية، -i يتجاهل حالة الأحرف، -C N يضيف سياقاً، و -m N يحد من المطابقات. عدم وجود تطابق يعتبر نجاحاً ويخرج بالكود 0.

edit مرتبط بالمحتوى، وليس بأرقام الأسطر أبداً. يجب أن يحدث كل oldText مرة واحدة بالضبط افتراضياً؛ --replace-all يستبدل كل المطابقات. يمكنك أيضاً تمرير مصفوفة {oldText,newText,replaceAll?} مع -f <file>. يتم إرسال التعديلات فقط إلى الإضافة؛ ليست هناك حاجة لقراءة أو رفع المصدر الكامل أولاً.

تنتظر عمليات الكتابة وكشف المصدر قرار المتصفح. أكواد خروج CLI:

كود الخروج	المعنى
0	تمت الموافقة والنجاح، أو اكتمل أمر قراءة بشكل طبيعي
1	رفض المستخدم الطلب
2	انتهت صلاحية الطلب، أو أُلغي بـ Ctrl-C، أو انقطع اتصال الإضافة
3	أخطاء أخرى مثل الوسائط أو الاتصال أو سكرپت مفقود

شغّل sctl <command> --help لكل خيار.

5. توصيل عميل ذكاء اصطناعي (MCP)

أولاً تأكد من أن sctl serve يعمل وأن status يبلغ عن إضافة متصلة. ثم قم بتهيئة عميل MCP لتشغيل عملية sctl mcp منفصلة. استخدم مسارات مطلقة للملف التنفيذي والبيانات في عملاء الواجهة الرسومية:

{
  "mcpServers": {
    "scriptcat": {
      "command": "/absolute/path/to/sctl",
      "env": {
        "SCTL_DATA_DIR": "/absolute/path/to/sctl-data"
      },
      "args": [
        "mcp",
        "--name",
        "my-ai-client"
      ]
    }
  }
}

العديد من تطبيقات الواجهة الرسومية لا توسع ~ أو $HOME أو تعبيرات الصدفة. --name هو تسمية تدقيق، وليس هوية موثقة أو حد تفويض. مخرجات MCP القياسية محجوزة لإطارات البروتوكول؛ لا تغلف sctl في سكرپت يطبع لافتة إلى المخرجات القياسية.

الأدوات الحالية:

الأداة	الغرض	سياسة التأكيد
scripts_list	سرد ملخصات السكرپتات	لا شيء
scripts_metadata_get	قراءة بيانات وصفية لسكرپت واحد	لا شيء
scripts_source_get	قراءة المصدر بواسطة uuid ونافذة أسطر اختيارية	سياسة قراءة المصدر
scripts_source_grep	البحث في المصدر وإرجاع الأسطر المطابقة	سياسة قراءة المصدر
scripts_install_request	طلب تثبيت سكرپت	سياسة الكتابة
scripts_edit_request	طلب تعديل مرتبط بالمحتوى	سياسة الكتابة
scripts_toggle_request	طلب تفعيل أو تعطيل	سياسة الكتابة
scripts_delete_request	طلب حذف	سياسة الكتابة

6. التدقيق والإلغاء

• "عرض سجل التدقيق" في بطاقة الوصول الخارجي يفتح صفحة السجل مفلترة على هذا المصدر.
• sctl status يعرض إصدار الخدمة الخلفية واتصال الإضافة وأحداث الأمان الأخيرة؛ -o json يعيد الأحداث الكاملة.
• "إيقاف الوصول الخارجي" يفصل الاتصال ويحذف حالة الاقتران من طرف الإضافة ويمسح سماحات الجلسة. يُطلب إعادة التسجيل بعد ذلك.
• لتعطيل عميل ذكاء اصطناعي واحد فقط، أزل sctl من إعداد MCP الخاص بذلك العميل؛ هذا لا يلغي وصول CLI أو العملاء الآخرين.

7. استكشاف الأخطاء وإصلاحها

الخدمة الخلفية غير قابلة للوصول

شغّل sctl serve أولاً. أوامر الطلب لا تشغل الخدمة الخلفية تلقائياً أبداً.

فشل مصادقة قناة التحكم

تأكد من أن serve وأوامر CLI وعملية MCP تحل إلى نفس دليل البيانات المطلق. تحقق من كل من SCTL_DATA_DIR وأي --data-dir صريح، ثم أعد تشغيل عميل MCP.

تقول الحالة "فشل الاتصال"

تأكد من أن الخدمة الخلفية تعمل، وأن عنوان الإضافة يطابقها، وأن برنامج الأمان المحلي لا يحظر 127.0.0.1:8643.

الأمر لا يعيد النتيجة

تحقق من المتصفح بحثاً عن صفحة تأكيد كشف المصدر أو الكتابة. اضغط Ctrl-C لإبطال الطلب.

العثور على السجلات

توجد السجلات تحت <data-dir>/logs/. إذا لم يتم ضبط --data-dir ولا SCTL_DATA_DIR، تكون الافتراضيات:

المنصة	دليل السجلات
macOS	~/Library/Application Support/sctl/logs/
Windows	%LOCALAPPDATA%\sctl\logs\
Linux	~/.config/sctl/logs/