Внешний доступ (CLI и ИИ-клиенты)

Внешний доступ позволяет локальным программам командной строки и ИИ-клиентам с поддержкой MCP управлять скриптами ScriptCat через sctl.

ИИ-клиент ── stdio MCP ──▶ sctl mcp ── локальный 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-<версия>-<ОС>-<архитектура>.<расширение> для вашей платформы, проверяет его sha256 по checksums.txt из того же релиза и устанавливает sctl в ~/.local/bin (macOS/Linux) или %LOCALAPPDATA%\sctl\bin (Windows). SCTL_VERSION задаёт конкретную версию; SCTL_INSTALL_DIR переопределяет каталог установки. Если каталог установки отсутствует в PATH, установщик выводит подсказку для вашей платформы — он никогда не изменяет ваш shell-профиль или пользовательский PATH.

sctl поставляется одним исполняемым файлом. Если на странице GitHub Releases опубликован архив для вашей платформы, вы также можете скачать и распаковать его, затем добавить sctl (sctl.exe в Windows) в PATH.

sctl version

Обычная сборка из исходников имеет версию 0.0.0-dev, чтобы отличаться от релиза с указанными версией, коммитом и временем сборки; это не мешает подключению к ScriptCat. Если готового релиза нет, sctl можно собрать из исходников из репозитория 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, используется стандартный пользовательский каталог платформы. Не размещайте его в репозитории или общей синхронизируемой папке и не передавайте модели ИИ файлы 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. Не вставляйте его в чат с ИИ, 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|файл>
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 <файл>. Расширению отправляются только правки — предварительно читать или загружать весь исходник не нужно.

Изменения и выдача исходного кода ожидают решения в браузере. Коды завершения CLI:

Код	Значение
0	Запрос одобрен и выполнен либо команда чтения завершилась нормально
1	Пользователь отклонил запрос
2	Запрос истёк, отменён через Ctrl-C или расширение отключилось
3	Другие ошибки: аргументы, соединение, отсутствующий скрипт и т. п.

Все параметры доступны через sctl <команда> --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/
Windows	%LOCALAPPDATA%\sctl\logs\
Linux	~/.config/sctl/logs/