Развёртывание и настройка Skill-Runner

Что такое Skill-Runner?

Skill-Runner — это автономный сервис выполнения навыков агентов. Zotero Agents взаимодействует с Skill-Runner через HTTP API для отправки запросов навыков и получения результатов. Он поддерживает несколько CLI агентов ИИ в качестве бэкенд-движков и может быть развёрнут как независимый контейнер Docker или локальный сервис.

🏆 Приоритет рекомендации: Если у вас уже есть совместимый с ACP инструмент агента на вашем компьютере (Codex, OpenCode, Claude Code и т.д.), пожалуйста, сначала используйте бэкенд ACP, который не требует дополнительной настройки. Skill-Runner подходит для сценариев, требующих постоянного фонового сервиса или общего доступа в локальной сети.

Режимы развёртывания

Рекомендуется: Постоянное развёртывание в Docker

Skill-Runner, развёрнутый в Docker, работает как независимый постоянный сервис, не зависящий от запуска/остановки Zotero — закрытие Zotero позволяет задачам продолжать выполняться в фоновом режиме, а при следующем запуске Zotero вы можете возобновить или напрямую получить завершённые результаты.

Подходит для:

Длительных задач (Topic Synthesis, пакетный анализ литературы и т.д.)
Общего доступа к одному экземпляру Skill-Runner с нескольких устройств в локальной сети
Пользователей с опытом работы с Docker

docker compose (рекомендуется)

version: "3"
services:
  skill-runner:
    image: leike0813/skill-runner:latest
    ports:
      - "9813:9813"
      - "17681:17681"
    volumes:
      - ./skills:/app/skills
      - skillrunner_cache:/opt/cache
      - ./data:/app/data
    environment:
      - SKILL_RUNNER_DATA_DIR=/app/data
      - UI_BASIC_AUTH_ENABLED=false

volumes:
  skillrunner_cache:

mkdir -p data skills
docker compose up -d --build

После запуска:

API Сервис: http://localhost:9813/v1
UI управления: http://localhost:9813/ui

Прямой запуск Docker

docker run --rm -p 9813:9813 -p 17681:17681 \
  -v "$(pwd)/skills:/app/skills" \
  -v skillrunner_cache:/opt/cache \
  -v "$(pwd)/data:/app/data" \
  leike0813/skill-runner:latest

Описание портов:

Порт	Назначение
`9813`	HTTP API + UI управления
`17681`	Встроенный терминал движка в браузере (требует ttyd)

Конфигурация для производства

Для публичных развёртываний рекомендуется включить UI Basic Auth:

docker run --rm -p 9813:9813 \
  -v "$(pwd)/skills:/app/skills" \
  -e UI_BASIC_AUTH_ENABLED=true \
  -e UI_BASIC_AUTH_USERNAME=admin \
  -e UI_BASIC_AUTH_PASSWORD=your-password \
  leike0813/skill-runner:latest

Рекомендуется использовать это с HTTPS обратным прокси (таким как Nginx).

Экстренный случай: Развёртывание локального режима в один клик

⚠️ Этот режим подходит только для пользователей, которые не знают, как устанавливать инструменты агентов и не могут использовать Docker. Если вы способны устанавливать CLI агентов или использовать Docker, пожалуйста, отдайте предпочтение бэкенду ACP или развёртыванию в Docker выше.

Skill-Runner, развёрнутый в один клик, запускается и останавливается автоматически вместе с плагином Zotero — закрытие Zotero завершает все текущие выполняющиеся задачи, и нет фонового выполнения. Прерванные задачи нужно отправлять повторно.

Шаги развёртывания:

Откройте Zotero → Настройки → Zotero Agents
Найдите раздел Локальный бэкенд SkillRunner
Нажмите Развернуть в один клик (если ещё не установлено)
- Плагин автоматически загружает последнюю версию с GitHub Releases
- Устанавливает в каталог данных плагина
- Статус меняется на "Установлено" после завершения
Нажмите Запустить
- Адрес по умолчанию: http://127.0.0.1:29813
- Если порт занят, автоматически пробует следующие 10 портов

Описание кнопок действий:

Кнопка	Функция
Развернуть	Загрузить и установить среду выполнения Skill-Runner
Запустить	Запустить локальный процесс Skill-Runner
Остановить	Остановить работающий процесс Skill-Runner
Удалить	Удалить установленные файлы среды выполнения
Открыть UI управления	Открыть встроенный веб-интерфейс управления Skill-Runner в боковой панели
Открыть папку навыков	Открыть каталог, где хранятся файлы навыков
Обновить кэш моделей	Обновить кэш списка моделей бэкенда
Открыть консоль отладки	Просмотр вывода логов бэкенда

Удалённый режим

Подключение к удалённому или облачному экземпляру Skill-Runner.

⚠️ Уведомление о безопасности: Текущая версия не предоставляет дополнительной защиты безопасности для удалённых подключений (такой как TLS, проверка API-ключа и т.д.), полагаясь только на аутентификацию Bearer Token. Удалённые подключения не рекомендуются в средах вне локальной сети. При развёртывании в локальной сети рекомендуется использовать брандмауэр для ограничения источников доступа.

Шаги настройки:

Откройте Инструменты → Менеджер бэкендов
Переключитесь на вкладку SkillRunner
Нажмите Добавить SkillRunner
Заполните:
- Отображаемое имя: Понятное имя
- Base URL: Адрес удалённого экземпляра (например, http://192.168.1.100:9813)
- Аутентификация: Выберите bearer и заполните Токен авторизации (если бэкенд требует аутентификации)
- Тайм-аут: Тайм-аут запроса (необязательно)
Нажмите Сохранить в правом нижнем углу

Локальное развёртывание (без Docker)

Скрипт быстрого развёртывания

# Linux / macOS
./scripts/deploy_local.sh

# Windows (PowerShell)
.\scripts\deploy_local.ps1

Предварительные требования: uv, Node.js, npm. ttyd необязателен.

CLI управления

# Проверить статус
./scripts/skill-runnerctl status --mode local --json

# Запустить
./scripts/skill-runnerctl up --mode local --json

# Остановить
./scripts/skill-runnerctl down --mode local --json

Параметры локального режима по умолчанию:

Linux/macOS: $HOME/.local/share/skill-runner
Windows: %LOCALAPPDATA%\SkillRunner
Порт: 29813 (резервный 29813-29823)
Привязка: Только 127.0.0.1

Установщик Release

# Linux / macOS
./scripts/skill-runner-install.sh --version v0.4.3

# Windows (PowerShell)
.\scripts\skill-runner-install.ps1 -Version v0.4.3

Скрипт автоматически загружает skill-runner-<version>.tar.gz + .sha256 и проверяет целостность SHA256 перед установкой.

Система движков

Skill-Runner поддерживает несколько CLI агентов ИИ в качестве движков выполнения и предоставляет унифицированный слой адаптации.

Поддерживаемые движки

Движок	Название пакета
Codex	`@openai/codex`
Gemini CLI	`@google/gemini-cli`
OpenCode	`opencode-ai`
Claude Code	`@anthropic-ai/claude-code`
Qwen	`@qwen-code/qwen-cli`

Приоритет конфигурации

Конфигурация движка объединяется из четырёх слоёв (низкий → высокий):

Значения по умолчанию движка: Конфигурация по умолчанию, встроенная в адаптер движка
Рекомендуемые значения навыков: Рекомендуемая конфигурация из пакета навыков assets/<engine>_config.*
Пользовательские опции: Параметры из тела запроса API
Принудительная конфигурация: Принудительная конфигурация из адаптера движка (не может быть переопределена)

Аутентификация движка

Метод	Описание	Рекомендация
OAuth прокси	Завершите OAuth через UI управления; учётные данные сохраняются автоматически	⭐ Рекомендуется
Делегирование CLI	Используйте встроенный локальный процесс входа движка	Альтернатива
Встроенный TUI	Терминал движка в браузере (требует ttyd)	Для отладки
Импорт файла учётных данных	Загрузите файлы учётных данных через UI	Альтернатива
Вход через CLI контейнера	Запустите вход CLI напрямую через `docker exec`	Для сред контейнеров

UI управления

Встроенный веб-интерфейс предоставляет полные операционные возможности для Skill-Runner.

URL доступа: http://localhost:<port>/ui

Функция	Описание
Браузер навыков	Просмотр установленных навыков, исследование структуры пакета и содержимого файлов
Управление движками	Мониторинг статуса движков, запуск обновлений, просмотр логов движков
Каталог моделей	Просмотр и управление снимками моделей движков
Встроенный TUI	Запуск терминалов движков напрямую в браузере (требует ttyd)
Настройки	Уровень логирования, период хранения данных, максимальный размер каталога и т.д.

Обзор REST API

Основные конечные точки выполнения

# Список доступных навыков
curl http://localhost:9813/v1/skills

# Создать задачу (выполнить навык)
curl -X POST http://localhost:9813/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": "my-skill",
    "engine": "gemini",
    "parameter": { "language": "zh-CN" },
    "model": "gemini-3-pro-preview"
  }'

# Получить результаты
curl http://localhost:9813/v1/jobs/<request_id>/result

# Отменить задачу
curl -X POST http://localhost:9813/v1/jobs/<request_id>/cancel

Мониторинг в реальном времени (SSE)

Два канала SSE для наблюдения за процессом выполнения в реальном времени:

Канал	Конечная точка	Назначение
Чат	`GET /v1/jobs/{id}/chat?cursor=N`	Поток сообщений чата
События	`GET /v1/jobs/{id}/events?cursor=N`	Полный поток событий протокола

Оба канала поддерживают повторное подключение на основе курсора после отключения.

API управления

Стабильные JSON конечные точки управления, подходящие для интеграции с фронтендом:

Конечная точка	Назначение
`GET /v1/management/skills`	Сводка по навыкам
`GET /v1/management/engines`	Статус движков
`GET /v1/management/runs`	История запусков (с пагинацией)
`GET /v1/management/runs/{id}/chat`	Поток SSE диалога
`POST /v1/management/runs/{id}/reply`	Отправить ответ интерактивному навыку
`POST /v1/management/runs/{id}/cancel`	Отменить запуск

API аренды локального выполнения

Режим локального выполнения использует управление жизненным циклом на основе аренды:

Конечная точка	Назначение
`POST /v1/local-runtime/lease/acquire`	Получить аренду
`POST /v1/local-runtime/lease/heartbeat`	Продлить аренду (TTL: 60с)
`POST /v1/local-runtime/lease/release`	Освободить аренду

Локальное выполнение автоматически завершается при истечении срока аренды.

Управление пакетами навыков

Постоянная установка

# Загрузить zip-архив пакета навыков
curl -X POST http://localhost:9813/v1/skill-packages/install \
  -H "Content-Type: multipart/form-data" \
  -F "file=@my-skill.zip"

Правила проверки на стороне сервера:

Пакет должен содержать каталог верхнего уровня
Должен иметь SKILL.md + assets/runner.json
Должен иметь три файла схемы (input / parameter / output)
Имя каталога == runner.json.id == имя frontmatter SKILL.md (согласованность идентичности)
Обновления должны строго увеличивать версию

Временный запуск (без установки)

# Создать временный запуск
curl -X POST http://localhost:9813/v1/temp-skill-runs \
  -H "Content-Type: application/json" \
  -d '{ "engine": "gemini", "parameter": {} }'

# Загрузить пакет навыков и запустить
curl -X POST http://localhost:9813/v1/temp-skill-runs/<id>/upload \
  -F "skill_package=@my-skill.zip"

Временные запуски автоматически очищаются после достижения терминального состояния.

Жизненный цикл выполнения

Типичное выполнение навыка включает следующие этапы:

1. Настройка и загрузка
   └── Клиент отправляет POST /v1/jobs
       └── При необходимости загружает входные файлы

2. Оркестрация
   └── Загрузка манифеста навыка
       └── Проверка схемы параметров
       └── Проверка совместимости движка
       └── Применение ограничений параллелизма

3. Адаптация движка
   └── Подготовка окружения (копирование пакета навыков)
       └── Разбор входных файлов
       └── Создание промпта через шаблоны Jinja2
       └── Установка доверия к каталогу выполнения

4. Выполнение
   └── Запуск CLI движка как подпроцесса
       └── Изолированный рабочий каталог
       └── Потоковая передача stdout/stderr в реальном времени

5. Завершение
   └── Проверка вывода (против output.schema.json)
       └── Разбор файлов артефактов
       └── Генерация Bundle (zip + манифест)
       └── Установка статуса в succeeded / failed / canceled

Когда запуск не удаётся, отладочный пакет содержит полные логи и диагностические файлы.

Структура каталога данных

data/
├── runs/<run_id>/              # Рабочее пространство запуска
│   ├── .state/state.json       # Состояние запуска
│   ├── .audit/                 # Логи аудита
│   ├── result/result.json      # Окончательный структурированный вывод
│   ├── artifacts/              # Файлы, сгенерированные навыком
│   └── bundle/                 # Упакованные результаты (zip + манифест)
├── requests/<request_id>/      # Данные фазы запроса
│   ├── uploads/                # Загруженные входные файлы
│   └── request.json            # Исходные параметры запроса
├── logs/                       # Логи приложения (ротируются ежедневно)
└── system_settings.json        # Системные настройки, редактируемые через UI

Справочник переменных окружения

Переменная	Описание	По умолчанию
`SKILL_RUNNER_DATA_DIR`	Каталог данных запусков	`./data`
`SKILL_RUNNER_AGENT_HOME`	Домашний каталог изолированной конфигурации агента	`auto`
`SKILL_RUNNER_RUNTIME_MODE`	Режим выполнения: local / container	`auto`
`UI_BASIC_AUTH_ENABLED`	Включить UI Basic Auth	`false`
`UI_BASIC_AUTH_USERNAME`	Имя пользователя Basic Auth	—
`UI_BASIC_AUTH_PASSWORD`	Пароль Basic Auth	—

Описания статусов запусков

Статус	Описание
unknown	Начальное состояние, ещё не обнаружено
starting	Запускается
running	Работает нормально
stopped	Остановлено
degraded	Работает ненормально
reconciling_after_heartbeat_fail	Обнаружение heartbeat не удалось, восстановление

Описания портов

Порт по умолчанию: 29813 (локальный диапазон плагина)
Порт API автономного развёртывания: 9813
Резервный диапазон: 10 последовательных портов (29813–29822)
Интервал heartbeat: 20 секунд
Обнаружение автозапуска: проверка каждые 15 секунд

Логи

Логи записываются в data/logs/skill_runner.log (ротируются ежедневно). Вы можете настроить уровень логирования, период хранения и максимальный размер каталога через страницу настроек UI управления.

При запуске контейнера также генерируются структурированные диагностические логи начальной загрузки в ${SKILL_RUNNER_DATA_DIR}/logs/bootstrap.log и agent_bootstrap_report.json.

Следующие шаги

Узнать о Workflow — Skill-Runner является одним из основных бэкендов для выполнения Workflow
Введение в Панель мониторинга — Отслеживание статуса выполнения задач
Вкладка SkillRunner — Просмотр и взаимодействие с запусками SkillRunner в боковой панели

Что такое Skill-Runner?​

Режимы развёртывания​

Рекомендуется: Постоянное развёртывание в Docker​

docker compose (рекомендуется)​

Прямой запуск Docker​

Конфигурация для производства​

Экстренный случай: Развёртывание локального режима в один клик​

Удалённый режим​

Локальное развёртывание (без Docker)​

Скрипт быстрого развёртывания​

CLI управления​

Установщик Release​

Система движков​

Поддерживаемые движки​

Приоритет конфигурации​

Аутентификация движка​

UI управления​

Обзор REST API​

Основные конечные точки выполнения​

Мониторинг в реальном времени (SSE)​

API управления​

API аренды локального выполнения​

Управление пакетами навыков​

Постоянная установка​

Временный запуск (без установки)​

Жизненный цикл выполнения​

Структура каталога данных​

Справочник переменных окружения​

Описания статусов запусков​

Описания портов​

Логи​

Следующие шаги​