Каталог навыков и песочница

Навык состоит из описания в SKILL.md, скриптов, шаблонов и материалов, а песочница предоставляет среду для выполнения скриптов. После добавления навыка в каталог пространства и установки его в песочницу выберите соответствующую песочницу и навык в агенте, чтобы использовать их в диалоге интеллектуального рассуждения.

Настройка и использование навыков

1. Admin/Owner пространства создаёт конфигурацию в разделе «Настройки → Конфигурация песочницы», выбирает Docker, CubeSandbox или E2B и заполняет данные подключения.
2. Следуя мастеру, подключите кластер и выберите шаблон; для проверки всей цепочки запустите «Полную проверку». Полная проверка фактически создаёт песочницу, выполняет пробники и выполняет очистку.
3. На боковой панели в разделе «Инструменты → Управление навыками» добавьте ZIP-архив или ссылку на источник, затем выберите песочницу для установки (старая ссылка «Настройки → Управление навыками» автоматически перенаправляет сюда). Успешное добавление в каталог означает лишь, что установочный пакет сохранён; выполнять навык можно только после того, как состояние установки станет «готово».
4. Откройте раздел «Навыки» в редакторе агента, выберите песочницу и задайте область навыков: все, указанные или отключено. Выполнение навыков используется в режиме интеллектуального рассуждения.
5. Перейдите в диалог и задайте вопрос либо используйте @навык, чтобы подсказать агенту отдать приоритет этому навыку. При необходимости файлов загрузите вложения; созданные итоговые файлы можно просмотреть и скачать на вкладке «Артефакты» панели «Визуализация песочницы» справа от диалога.

@навык не отменяет доступ агента к другим авторизованным навыкам. Если песочница не выбрана (Lite-версия для рабочего стола на macOS переключается на локальную песочницу), в пространстве отключены скрипты или недоступна необходимая возможность бэкенда, инструменты выполнения не регистрируются; подсказки в промпте не могут обойти эти условия.

Управление установкой и обновлением

Страница управления навыками поддерживает поиск по названию и описанию. Поиск не зависит от регистра, ключевые слова через пробел должны совпадать все. При отсутствии совпадений можно очистить поиск или продолжить добавление навыков.

Каталог пространства хранит одну копию пакета навыка; для каждой конфигурации песочницы ведутся отдельные записи установки и снимок образа с включённым навыком. Один и тот же навык можно установить в несколько песочниц, а ход установки и причины сбоев записываются раздельно.

Действие	Результат
Добавить в каталог	Сохраняет пакет, имя, версию и описание, установка не выполняется
Установка	Собирает среду выполнения в выбранной песочнице, устанавливает зависимости и проверяет загружаемость, после успеха публикует новый снимок
Повтор	Повторно устанавливает сохранённый в этой песочнице пакет, можно приложить инструкцию по установке; если тот же пакет уже готов, можно пропустить
Обновление	После повторной регистрации новой версии в каталоге старая установка помечается как обновляемая; обновление устанавливает новую версию из каталога в выбранную песочницу
Остановить установку	Прерывает текущую установку, состояние становится failed, после чего можно повторить или удалить
Отключить	Сохраняет запись установки, только запрещает агенту выбирать этот навык
Удалить из песочницы	Обновляет образ навыков этой песочницы, сохраняя установочный пакет в каталоге, чтобы другие песочницы могли продолжить установку
Удалить запись каталога	Требует, чтобы не осталось ссылок на установку в песочницах; не выполняет неявное удаление из всех песочниц

На странице установки отображаются процент выполнения, этап и журнал; подробный ход процесса можно посмотреть в записи установки. Закрытие панели прогресса или разрыв потока прогресса не останавливает установку. Если прогресс в реальном времени отсутствует, можно обновить состояние навыка; истечение срока хранения подробного журнала событий не означает, что установочный пакет навыка потерян.

Установку выполняет встроенный агент установки: он читает SKILL.md, устанавливает зависимости и проверяет предварительные условия запуска, например необходимые навыку внешние инструменты командной строки. При отсутствии обязательных команд или наличии нерешённых предварительных условий (например, сервиса, требующего отдельного развёртывания) установка признаётся неудачной с указанием причины; она не помечается как готовая только из-за отсутствия списка зависимостей. Во время установки администратор может в «Процессе установки» дополнить инструкцию по установке, например требуемый CLI, документацию по установке или ограничения среды; после завершения установки также можно переустановить с инструкцией.

При сбое обновления или повтора песочница продолжает предоставлять предыдущую готовую версию, которой агент всё ещё может пользоваться; замена происходит только после успешной установки новой версии.

skill_rollout управляет обновлением образа: значение по умолчанию next_turn пересоздаёт песочницу на следующем ходу существующей сессии; new_session позволяет использовать новый образ только сессиям, создающим песочницу после этого. Пересоздание песочницы теряет временное состояние выполнения старого экземпляра; файлы, которые нужно передать, следует записывать в /workspace/output, откуда их соберёт система.

Поддерживаемые источники

Ввод	Описание
ZIP-файл	Загружается после экспорта каталога навыка
@owner/slug, @owner/slug@1.2.0	Указанный автор/версия в ClawHub
slug, slug@1.2.0	slug в ClawHub
Страницы ClawHub, SkillHub, самостоятельно размещённого SkillHub	Разрешается через соответствующий источник
URL репозитория или каталога GitHub/GitLab	Получает соответствующий пакет навыка
https://skills.sh/owner/repo/slug, страница skills.sh в ClawHub	Установочный резолвер разрешает конкретную версию и каталог в репозитории
Прямой URL ZIP или SKILL.md	Загружает пакет или входной файл

Источник должен быть доступен для анонимного чтения; при загрузке не используются личные учётные данные пользователя для приватных репозиториев. Приватный навык можно сначала экспортировать в ZIP. owner/slug неоднозначен, поэтому следует использовать @owner/slug или полный URL.

Ограничение размера пакета навыка не зависит от обычных документов: MAX_SKILL_BUNDLE_SIZE_MB по умолчанию равен 256 MiB, при отсутствии значения он составляет как минимум MAX_FILE_SIZE_MB и не более 512 MiB. Загрузка с GitHub считается по архиву всего репозитория, а не только по подкаталогу навыка. После изменения перезапустите app и frontend, чтобы ограничения приложения и Nginx совпадали.

Выбор бэкенда песочницы

Бэкенд	Что нужно заполнить	Способ запуска
Docker	Образ; опционально адрес daemon, каталог TLS-сертификатов, ограничения CPU/памяти/PID, режим сети, runtime, TTL простоя	Один долгоживущий контейнер на сессию
CubeSandbox	Адрес плоскости управления, прокси плоскости данных, домен песочницы, шаблон; API Key настраивается для кластера	Удалённая песочница уровня сессии
E2B	API Key, шаблон; при самостоятельном размещении дополнительно API-адрес, домен песочницы и прокси плоскости данных	E2B Cloud или совместимая с E2B плоскость управления
host	Заполнять не нужно. Только Lite-версия для рабочего стола, сейчас только macOS	Когда в агенте не выбрана конфигурация песочницы, выполняется в каталоге локального проекта, выход за границы блокирует операционная система

Бэкенд процесса на хост-машине local удалён: он выполнялся на локальной машине без какой-либо изоляции. host в Lite не относится к перечисленным именованным конфигурациям пространства и не является заменой local. Полный набор полей текущей конфигурации см. в API песочницы и навыков.

Бэкенд Docker по умолчанию отключён. Системный администратор включает его в «Системные настройки → Сетевая безопасность» либо использует WEKNORA_SANDBOX_DOCKER_ENABLED=true как резервный вариант, пока настройка не сохранена в базе. Для локального подключения также нужно смонтировать реальный Docker socket в app; это даёт app возможность управлять Docker на хост-машине. Для удалённого TCP daemon нужно настроить каталог TLS-сертификатов, включающий ca.pem, cert.pem, key.pem. Сеть Docker принимает только bridge или none; можно выбрать установленный OCI runtime, например runsc.

proxy_url при самостоятельном размещении E2B/Cube указывает на шлюз плоскости данных: WikiNG подключается к шлюзу, но сохраняет Host песочницы — для кластеров без wildcard DNS. allow_private_endpoints разрешает подключение к адресам кластера в частной сети/loopback, но по-прежнему не пропускает link-local/адреса облачных метаданных; это отдельная настройка от того, может ли скрипт в песочнице выходить в сеть.

По умолчанию скрипты выполняются от учётной записи root внутри песочницы; учётную запись user из шаблона нужно выбирать явно. Изоляцию выполнения обеспечивает контейнер или удалённая песочница; /workspace только задаёт рабочий каталог и не ограничивает доступ команд root к файлам.

Сетевая политика

config.network в Cube/E2B используется одновременно для песочницы диалога, установки навыков и полной проверки:

• По умолчанию исходящие разрешены; deny_egress_by_default=true меняет поведение на запрет по умолчанию, после чего через allow_out разрешаются IP, CIDR или домены.
• deny_out принимает IPv4/CIDR; правила разрешения доменов требуют режима «запрещено по умолчанию».
• cube_rules в Cube позволяет задавать правила по Host/SNI, методу и пути, менять порядок, настраивать аудит и инъекцию заголовков HTTPS; e2b_host_rules в E2B настраивает инъекцию заголовков запроса для уже разрешённых доменов.
• Внедряемые учётные данные хранятся в зашифрованном виде, ответы маскируются. Входящие подключения всегда требуют учётных данных; старое поле allow_public_inbound не открывает анонимный входящий доступ.
• В Docker исходящий доступ управляется docker.network_mode, тонкие правила Cube/E2B здесь не применимы. После включения запрета исходящих по умолчанию источники, необходимые для установки зависимостей, тоже нужно разрешить явно.

Существующие экземпляры не получают новую конфигурацию автоматически при изменении политики, поэтому проверку следует выполнять после создания или пересоздания песочницы. Перед изменением идентичности бэкенда или удалением конфигурации система запрашивает работающие и приостановленные экземпляры и связанные агенты; при наличии использования операция отклоняется, а на странице настроек отображается информация об использовании.

Локальная песочница Lite (host)

Начиная с v0.8.2 Lite-версия для рабочего стола в macOS изолированно выполняет команды агента и файловые инструменты с помощью системного Seatbelt. Если в агенте выбрана конфигурация Docker, E2B или Cube, по-прежнему используется удалённая песочница; локальная песочница применяется только когда конфигурация песочницы не выбрана. Windows и Linux пока не поддерживают эту возможность, поэтому в этом случае агент без выбранной конфигурации не может выполнять команды.

• Рабочий каталог: на странице нового диалога нажмите «Выбрать проект» и выберите папку проекта в системном диалоге выбора каталога; имя проекта отобразится в заголовке диалога. Если не выбирать, отображается «Временное рабочее пространство», и каталог сессии автоматически создаётся в ~/Documents/WeKnoraLite/<дата>/session-*. Нельзя выбрать сам домашний каталог, каталог, содержащий домашний каталог, или каталог внутри ~/Library.
• Пути: рабочее пространство — это реальные локальные пути, без /workspace, /workspace/input и /workspace/output. Агент изменяет файлы прямо в проекте, и эти файлы не попадают в список артефактов диалога; удаление диалога также не удаляет локальный каталог.
• Ограничения: по умолчанию команды не имеют доступа в сеть и могут записывать только в каталог проекта; .git внутри проекта доступен только для чтения. В домашнем каталоге для чтения недоступно всё, кроме распространённых цепочек инструментов разработки (например, .nvm, .pyenv, .cargo); такие места с учётными данными, как .ssh, .aws, связка ключей, всегда недоступны для чтения.
• Откат: откат диалога не восстанавливает локальные файлы проекта; при необходимости управляйте версиями самостоятельно через Git.

Установка локальных навыков в настольной версии Lite

В настольной версии для macOS можно установить навык в «Локально» через «Инструменты → Управление навыками», при этом Агент может выбирать только установленные и включённые локальные навыки. Каталог навыков хранит переиспользуемый пакет, а локальная установка поддерживает каталоги версий в ~/.weknora/skills; активная версия переключается только после успешной установки и проверки, при сбое используемая старая версия не заменяется. Локальная установка не создаёт снимки Docker/E2B/Cube.

Выполнение навыков по-прежнему использует локальную песочницу, а файлы проекта не попадают автоматически в список артефактов удалённой песочницы. Локальные навыки настольной версии и удалённые песочницы стандартного развёртывания имеют разные цели установки; не следует напрямую переносить пути удалённой установки в локальные.

Переменные среды и учётные данные

Личные переменные настраиваются в разделе «Настройки → Ключи песочницы»; переменные навыков уровня пространства настраиваются на карточке навыка в разделе «Инструменты → Управление навыками». Список показывает только объявление переменной, факт установки и источник, но не раскрывает секретные значения.

Уровень	Назначение
config.env_vars песочницы пространства	Внедряются в песочницы, созданные этой конфигурацией, и используются их скриптами
Переменные навыка пространства	Администратор задаёт значения по умолчанию для объявленных навыком переменных
Личные переменные песочницы	Используются при выполнении команд в этой конфигурации песочницы от имени пользователя
Личные переменные навыка	Используются при выполнении этого навыка от имени пользователя

При разборе переменных навыка действует приоритет личное значение навыка > личное значение песочницы > значение навыка пространства; резервный вариант используется только для неустановленных имён. Среда песочницы пространства — часть среды выполнения, и не следует помещать в неё секреты, которые скрипт не должен читать. После удаления личного переопределения снова используются значения нижнего уровня; отключение навыка не удаляет личные учётные данные.

Личные переменные навыка могут использовать только имена, объявленные навыком, включая необходимые навыку учётные данные WEKNORA_*. Личные переменные песочницы не принимают зарезервированные имена, такие как WEKNORA_*, PATH. Переменные, распознанные системой из выполняемой команды, только дополняют неустановленные личные значения и не переопределяют существующую личную или пространственную конфигурацию. Поля и примеры см. в API личных переменных.

Создание и загрузка файлов

read_file(path="skill://<name>/SKILL.md") читает описание; скрипты, прилагаемые к навыку, выполняются через shell_exec(skill_name=..., command=...). $WEKNORA_SKILL_DIR в команде указывает на фактический каталог установки навыка; skill:// — это адрес чтения, его нельзя напрямую использовать как путь shell.

Вложения временно сохраняются в /workspace/input, рабочие скрипты размещаются в /workspace, а доступные для скачивания артефакты — в /workspace/output. Используйте write_sandbox_file для создания и дозаписи, edit_sandbox_file для точечной замены, read_file для постраничного чтения. Границы файловых инструментов, бюджет вывода и поведение при пересоздании см. в Движок агента, точки передачи результатов — в Сессии и опыт диалога.

Во время выполнения команды карточка инструмента в диалоге в реальном времени показывает последние несколько строк вывода, помогая оценить ход выполнения длинной команды; эти промежуточные данные вывода не записываются в контекст модели.

Панель визуализации песочницы

В диалогах, использующих удалённую песочницу, панель «Визуализация песочницы» справа имеет три вкладки:

Вкладка	Содержимое	Условия доступности
Артефакты	Доступные для скачивания файлы, созданные в текущем ходу или во всех ходах, с поиском по имени файла	Все удалённые песочницы
Терминал	Интерактивный Shell (xterm), подключающийся к песочнице этой сессии. В Cube и E2B после обновления страницы можно снова подключиться к ещё работающему терминалу; в Docker при отключении Shell завершается (фоновые задачи, запущенные через nohup, сохраняются), а при переподключении открывается новый Shell	Cube, E2B, Docker
Рабочий стол	Управление графическим рабочим столом XFCE внутри песочницы через браузер; для каждой сессии допускается одновременно только одно подключение	Шаблоны рабочего стола Cube, E2B при включённой в конфигурации опции desktop_enabled

Открытие панели не создаёт и не пробуждает песочницу: если песочница уже работает, терминал и рабочий стол подключаются напрямую; если песочница приостановлена или ещё не создана, нужно нажать «Запустить терминал», «Подключить рабочий стол» или «Создать и запустить», а пробуждённая или новая песочница тарифицируется согласно конфигурации пространства. Терминал или рабочий стол автоматически отключаются после длительного простоя, после чего песочница приостанавливается согласно TTL провайдера; время до отключения задаётся параметром «Отключение терминала / рабочего стола при простое (секунды)» в конфигурации песочницы, по умолчанию 900 секунд, диапазон от 60 секунд до 24 часов. После пересоздания песочницы из-за обновления навыков несохранённое содержимое исходного терминала и рабочего стола теряется.

Развёртывание и диагностика

Требования к сборке для Docker socket/TLS, версий шаблонов, удалённого шлюза, многокопийного Redis, дискового пространства под снимки навыков, реле терминала и рабочего стола, а также локальной песочницы Lite см. в Развёртывание и диагностика песочницы.

Справочник по реализации

• internal/handler/sandbox_config.go, sandbox_skill.go, skill_catalog.go, me_env_var.go
• internal/application/service/tenant_skill_install.go, tenant_skill_runtime_verify.go, tenant_skill_steer.go, user_env_resolver.go
• internal/types/tenant.go, sandbox_network_policy.go
• internal/sandbox/remote_client.go, docker_remote_client.go, gateway_transport.go, terminal.go
• internal/localsandbox/ (локальная песочница Lite: core/policy_builder.go, seatbelt/, adapter/)