Зовнішній доступ (CLI та AI-клієнти)

Зовнішній доступ дозволяє локальним програмам командного рядка та AI-клієнтам із підтримкою 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, щоб відрізнити його від випуску з впровадженою версією, комітом та метаданими часу збирання; це не заважає йому підключатися до 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. У налаштуванні ScriptCat адреса sctl введіть адресу, до якої розширення може фактично дістатися, наприклад 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, дійсний протягом 2 хвилин і працює один раз. Він не надсилається до розширення через WebSocket. Ніколи не вставляйте його в AI-чат, issue, журнал або конфігурацію MCP; якщо він закінчився, запустіть connect знову.

3. Дозволи та підтвердження

Можливість	Типова поведінка
Список скриптів і читання метаданих	Повертати безпосередньо
Читання або пошук вихідного коду скрипта	Дотримуватися політики читання джерела
Встановлення, редагування, увімкнення, вимкнення або видалення скрипта	Дотримуватися політики запису

Обидві політики пропонують "Вимагати підтвердження" (за замовчуванням) та "Дозволяти безпосередньо".

З "Вимагати підтвердження" запити відкривають сторінку підтвердження в браузері. Ви можете відхилити, дозволити один раз або вибрати "Дозволяти для цієї сесії". Дозволи сесії прив'язані до скрипта та виду операції і очищаються, коли браузер перезапускається, розширення перезавантажується або Зовнішній доступ зупиняється. Запит завершується через 5 хвилин без рішення; відключення запитувача або Ctrl-C також анулює його.

"Дозволяти безпосередньо" пропускає сторінку підтвердження для цього класу операцій. Джерело може містити ключі API, cookie та інші секрети, а записи можуть безпосередньо змінювати скрипти, тому вмикайте це лише тоді, коли приймаєте цей ризик.

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 обмежує збіги. Немає збігів — це успіх, і команда завершується з кодом 0.

edit прив'язаний до вмісту, а не до номерів рядків. Кожен oldText за замовчуванням має зустрічатися рівно один раз; --replace-all замінює кожен збіг. Ви також можете передати масив {oldText,newText,replaceAll?} з -f <file>. До розширення надсилаються лише правки; немає потреби спочатку читати або завантажувати повне джерело.

Записи та розкриття джерела блокуються для рішення браузера. Коди виходу CLI:

Код виходу	Значення
0	Схвалено та успішно, або команда читання завершилася нормально
1	Користувач відхилив запит
2	Термін запиту минув, скасовано через Ctrl-C або розширення відключилося
3	Інші помилки, такі як аргументи, з'єднання або відсутній скрипт

Виконайте sctl <command> --help для кожного параметра.

5. Підключення AI-клієнта (MCP)

Спочатку переконайтеся, що sctl serve запущено, а status повідомляє про підключене розширення. Потім налаштуйте MCP-клієнт на запуск окремого процесу sctl mcp. У GUI-клієнтах використовуйте абсолютні шляхи до бінарного файлу та даних:

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

Багато GUI-застосунків не розгортають ~, $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 повертає повні події.
• "Зупинити зовнішній доступ" відключається, видаляє стан сполучення на боці розширення та очищає дозволи сесії. Після цього потрібна повторна реєстрація.
• Щоб вимкнути лише одного AI-клієнта, видаліть 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/