دسترسی خارجی (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 و لینوکس:

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 (ویندوز) نصب می‌کند. SCTL_VERSION نسخه خاصی را ثابت می‌کند؛ SCTL_INSTALL_DIR دایرکتوری نصب را بازنویسی می‌کند. اگر دایرکتوری نصب در PATH شما نیست، نصب‌کننده راهنمای دقیق PATH را برای پلتفرم شما چاپ می‌کند — هرگز پروفایل شل یا PATH کاربری شما را برای شما ویرایش نمی‌کند.

sctl یک فایل اجرایی واحد است. اگر GitHub Releases بایگانی منتشرشده‌ای برای پلتفرم شما داشته باشد، می‌توانید آن را دانلود و استخراج کنید و سپس sctl (sctl.exe در ویندوز) را روی PATH قرار دهید.

sctl version

یک ساخت ساده از منبع 0.0.0-dev گزارش می‌دهد تا آن را از ساخت انتشار با نسخه، کامیت و فراداده زمان ساخت تزریق‌شده متمایز کند؛ این مانع اتصال آن به 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. کد ۸ کاراکتری ترمینال را در کادر گفتگوی «ثبت sctl» وارد کنید.

5. اتصال را تأیید کنید:

   sctl status

وضعیت باید یک افزونه متصل را گزارش دهد و نسخه دیمن را نشان دهد.

کد جفت‌سازی فقط برای ترمینال است

کد شبیه A1B2-C3D4 است، پس از ۲ دقیقه منقضی می‌شود و یک بار کار می‌کند. از طریق WebSocket به افزونه ارسال نمی‌شود. هرگز آن را در چت هوش مصنوعی، issue، لاگ یا پیکربندی MCP قرار ندهید؛ اگر منقضی شد دوباره connect را اجرا کنید.

3. مجوزها و تأیید

قابلیت	رفتار پیش‌فرض
فهرست‌کردن اسکریپت‌ها و خواندن فراداده	مستقیم برگردانده می‌شود
خواندن یا جستجوی منبع اسکریپت	پیروی از سیاست خواندن منبع
نصب، ویرایش، فعال‌سازی، غیرفعال‌سازی یا حذف اسکریپت	پیروی از سیاست نوشتن

هر دو سیاست گزینه‌های «نیاز به تأیید» (پیش‌فرض) و «اجازه مستقیم» را ارائه می‌دهند.

با «نیاز به تأیید»، درخواست‌ها یک صفحه تأیید مرورگر باز می‌کنند. می‌توانید رد کنید، یک بار اجازه دهید یا «اجازه برای این جلسه» را انتخاب کنید. اجازه‌های جلسه بر اساس اسکریپت و نوع عملیات کلید می‌خورند و وقتی مرورگر راه‌اندازی مجدد می‌شود، افزونه بارگذاری مجدد می‌شود یا دسترسی خارجی متوقف می‌شود پاک می‌شوند. یک درخواست پس از ۵ دقیقه بدون تصمیم منقضی می‌شود؛ قطع اتصال درخواست‌کننده یا Ctrl-C نیز آن را بی‌اعتبار می‌کند.

«اجازه مستقیم» صفحه تأیید را برای آن دسته از عملیات رد می‌کند. منبع می‌تواند شامل کلیدهای API، کوکی‌ها و سایر اسرار باشد، در حالی که نوشتن‌ها می‌توانند مستقیماً اسکریپت‌ها را تغییر دهند، بنابراین فقط زمانی آن را فعال کنید که آن ریسک را می‌پذیرید.

4. استفاده از خط فرمان

sctl get                         # فهرست اسکریپت‌ها
sctl get <uuid>                  # خواندن فراداده
sctl get <uuid> -o source        # چاپ منبع کامل
sctl get <uuid> -o source --lines 20-80
sctl grep <uuid> "fetch("         # جستجوی تحت‌اللفظی منبع
sctl grep <uuid> "pattern" -E    # عبارت باقاعده
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 تعداد مطابقت‌ها را محدود می‌کند. هیچ مطابقتی موفق است و با کد ۰ خارج می‌شود.

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 یک برچسب ممیزی است، نه یک هویت احراز شده یا مرز مجوز. stdout MCP برای فریم‌های پروتکل رزرو شده است؛ sctl را در اسکریپتی که بنری به stdout چاپ می‌کند نپیچید.

ابزارهای فعلی:

ابزار	هدف	سیاست تأیید
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/
ویندوز	%LOCALAPPDATA%\sctl\logs\
لینوکس	~/.config/sctl/logs/