Выполнение скриптов навыка

Что вы сможете сделать после изучения

• Использовать инструмент run_skill_script для выполнения исполняемых скриптов в каталоге навыка
• Передавать параметры командной строки в скрипты
• Понимать контекст рабочего каталога при выполнении скриптов
• Обрабатывать ошибки выполнения скриптов и коды выхода
• Освоить настройку разрешений скриптов и механизмы безопасности

Ваша текущая проблема

Вы хотите, чтобы ИИ выполнял автоматизированные скрипты определённого навыка, например сборку проекта, запуск тестов или развёртывание приложения. Но вы не уверены, как вызывать скрипты, или сталкиваетесь с проблемами, такими как ошибки разрешений, невозможность найти скрипты и т. д.

Когда использовать этот метод

• Автоматизация сборки: выполнение скриптов build.sh или build.py навыка для сборки проекта
• Запуск тестов: запуск тестового набора навыка для генерации отчёта о покрытии кодом
• Процесс развёртывания: выполнение скриптов развёртывания для публикации приложения в производственной среде
• Обработка данных: запуск скриптов для обработки файлов и преобразования форматов данных
• Установка зависимостей: выполнение скриптов для установки зависимостей, требуемых навыку

Основная идея

Инструмент run_skill_script позволяет вам выполнять исполняемые скрипты в контексте каталога навыка. Преимущества этого подхода:

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

Правила обнаружения скриптов

Плагин рекурсивно ищет исполняемые файлы в каталоге навыка (максимальная глубина 10 уровней):

• Пропускаемые каталоги: скрытые каталоги (начинающиеся с .), node_modules, __pycache__, .git, .venv и т. д.
• Проверка на исполняемость: только файлы с правами на выполнение (mode & 0o111) будут включены в список скриптов
• Относительные пути: пути скриптов указываются относительно каталога навыка, например tools/build.sh

Сначала просмотрите доступные скрипты

Перед выполнением используйте get_available_skills для просмотра списка скриптов навыка:

docker-helper (project)
  Руководство по контейнеризации и развёртыванию Docker [scripts: build.sh, deploy.sh]

::

Пошаговое руководство

Шаг 1: Выполнение скрипта навыка

Предположим, у вас есть навык docker-helper, содержащий скрипт build.sh:

Ввод пользователя:
Выполните скрипт build.sh навыка docker-helper

Ответ системы:
Building Docker image...
Successfully built abc123def456
Tagged as myapp:latest

Что вы должны увидеть: вывод скрипта отображается в ответе.

При выполнении скрипта рабочий каталог уже переключён на каталог навыка, поэтому build.sh может корректно получить доступ к ресурсам навыка, таким как Dockerfile.

Шаг 2: Передача параметров командной строки

Многие скрипты поддерживают параметры. Например, deploy.sh может требовать указания среды:

Ввод пользователя:
Выполните deploy.sh навыка docker-helper с параметром production

Ответ системы:
Deploying to production environment...
Uploading image to registry...
Deployment successful: https://myapp.example.com

Вы также можете передать несколько параметров:

Ввод пользователя:
Разверните с помощью deploy.sh с параметрами staging и --force

Ответ системы:
Deploying to staging environment (--force mode)...
Skipping validation...
Deployment successful

Что вы должны увидеть: скрипт получает параметры и выполняет соответствующие операции.

Шаг 3: Выполнение скриптов из вложенных каталогов

Скрипты могут находиться в подкаталогах навыка, например tools/setup.sh:

Ввод пользователя:
Выполните tools/setup.sh навыка docker-helper

Ответ системы:
Setting up Docker environment...
✓ Docker network created
✓ Volume mounted
✓ Environment configured

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

Что вы должны увидеть: скрипты из вложенных каталогов также выполняются корректно.

Шаг 4: Обработка ошибки отсутствия навыка

Если вы ввели неправильное название навыка:

Ввод пользователя:
Выполните build.sh навыка docker-asistant

Ответ системы:
Skill "docker-asistant" not found. Did you mean "docker-helper"?

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

Что вы должны увидеть: сообщение об ошибке и предлагаемое правильное название.

Шаг 5: Обработка ошибки отсутствия скрипта

Если скрипт отсутствует в списке скриптов навыка:

Ввод пользователя:
Выполните run.sh навыка docker-helper

Ответ системы:
Script "run.sh" not found in skill "docker-helper". Did you mean "build.sh"?
Available scripts: build.sh, deploy.sh

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

Что вы должны увидеть: сообщение об ошибке и список доступных скриптов.

Шаг 6: Понимание сбоя выполнения скрипта

Если выполнение скрипта завершилось неудачей (код выхода не равен 0), плагин вернёт информацию об ошибке:

Ввод пользователя:
Выполните build.sh навыка docker-helper

Ответ системы:
Script failed (exit 1): Dockerfile not found in /path/to/skill

Информация об ошибке включает:

• Код выхода: exit 1 означает, что скрипт завершился с ненулевым статусом
• Вывод ошибки: содержимое stderr или stdout скрипта
• Причина сбоя: конкретная информация об ошибке скрипта

Что вы должны увидеть: подробная информация об ошибке поможет вам локализовать проблему.

Контрольная точка ✅

• [ ] Можете ли вы выполнять исполняемые скрипты в каталоге навыка?
• [ ] Можете ли вы передавать параметры командной строки в скрипты?
• [ ] Понимаете ли вы контекст рабочего каталога при выполнении скриптов?
• [ ] Можете ли вы выявлять и обрабатывать ошибки выполнения скриптов?
• [ ] Знаете ли вы, как проверить настройки разрешений скриптов?

Предупреждения о подводных камнях

Ловушка 1: Скрипт не имеет прав на выполнение

Если вы создали новый скрипт, но забыли установить права на выполнение, он не появится в списке скриптов.

Проявление ошибки:

Available scripts: build.sh  # Ваш новый скрипт new-script.sh отсутствует в списке

Причина: у файла нет прав на выполнение (mode & 0o111 равно false).

Решение: установите права на выполнение в терминале:

chmod +x .opencode/skills/my-skill/new-script.sh

Проверка: снова вызовите get_available_skills для просмотра списка скриптов.

Ловушка 2: Неверный путь к скрипту

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

Неверный пример:

# ❌ Ошибка: использование абсолютного пути
Выполните /path/to/skill/build.sh навыка docker-helper

# ❌ Ошибка: попытка доступа к родительскому каталогу (хотя пройдёт проверку безопасности, но путь неверный)
Выполните ../build.sh навыка docker-helper

Верный пример:

# ✅ Правильно: использование относительного пути
Выполните build.sh навыка docker-helper
Выполните tools/deploy.sh навыка docker-helper

Причина: плагин проверяет безопасность пути, предотвращая атаки directory traversal, и при этом относительный путь основывается на каталоге навыка.

Ловушка 3: Скрипт зависит от рабочего каталога

Если скрипт предполагает, что текущий каталог — это корневой каталог проекта, а не каталог навыка, выполнение может завершиться неудачей.

Неверный пример:

# build.sh в каталоге навыка
#!/bin/bash
# ❌ Ошибка: предполагается, что текущий каталог — корневой каталог проекта
docker build -t myapp .

Проблема: при выполнении текущий каталог — это каталог навыка (.opencode/skills/docker-helper), а не корневой каталог проекта.

Решение: скрипты должны использовать абсолютные пути или динамически определять корневой каталог проекта:

# ✅ Правильно: использование относительного пути для определения корневого каталога проекта
docker build -t myapp ../../..

# Или: использование переменных окружения или файлов конфигурации
PROJECT_ROOT="${SKILL_DIR}/../../.."
docker build -t myapp "$PROJECT_ROOT"

Примечание: в каталоге навыка может отсутствовать Dockerfile проекта, поэтому скрипты должны самостоятельно находить файлы ресурсов.

Ловушка 4: Чрезмерно длинный вывод скрипта

Если скрипт выводит много журнальных сообщений (например, ход загрузки при npm install), ответ может стать очень длинным.

Проявление:

Ответ системы:
npm WARN deprecated package...
npm notice created a lockfile...
added 500 packages in 2m
# Возможно, сотни строк вывода

Рекомендация: скрипты должны иметь краткий вывод, отображающий только ключевую информацию:

#!/bin/bash
echo "Installing dependencies..."
npm install --silent
echo "✓ Dependencies installed (500 packages)"

Итог урока

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

• Передачу параметров: передача параметров командной строки через массив arguments
• Переключение рабочего каталога: при выполнении скрипта CWD переключается на каталог навыка
• Обработку ошибок: перехват кодов выхода и вывода ошибок для упрощения отладки
• Проверку разрешений: выполняются только файлы с правами на выполнение
• Безопасность путей: проверка пути скрипта для предотвращения directory traversal

Правила обнаружения скриптов:

• Рекурсивное сканирование каталога навыка, максимальная глубина 10 уровней
• Пропуск скрытых каталогов и распространённых каталогов зависимостей
• Включаются только файлы с правами на выполнение
• Путь является относительным путём относительно каталога навыка

Лучшие практики:

• Вывод скриптов должен быть кратким, отображать только ключевую информацию
• Скрипты не должны предполагать, что текущий каталог — корневой каталог проекта
• Используйте chmod +x для установки прав на выполнение для новых скриптов
• Сначала используйте get_available_skills для просмотра доступных скриптов

Предварительный обзор следующего урока

В следующем уроке мы изучим Чтение файлов навыков.

Вы узнаете:

• Использование инструмента read_skill_file для доступа к документации и конфигурации навыка
• Понимание механизма проверки безопасности пути для предотвращения атак directory traversal
• Освоение форматов чтения файлов и внедрения содержимого XML
• Научитесь организовывать вспомогательные файлы в навыках (документация, примеры, конфигурация и т. д.)

---

Приложение: Справочник по исходному коду

Нажмите, чтобы просмотреть расположение исходного кода

Время обновления: 2026-01-24

Функция	Путь к файлу	Номер строки
Определение инструмента RunSkillScript	src/tools.ts	137-198
Функция findScripts	src/skills.ts	59-99

Ключевые типы:

• Script = { relativePath: string; absolutePath: string }: метаданные скрипта, содержащие относительный и абсолютный пути

Ключевые константы:

• Максимальная глубина рекурсии: 10 (skills.ts:64) — ограничение глубины поиска скриптов
• Список пропускаемых каталогов: ['node_modules', '__pycache__', '.git', '.venv', 'venv', '.tox', '.nox'] (skills.ts:61)
• Маска прав на выполнение: 0o111 (skills.ts:86) — проверка, является ли файл исполняемым

Ключевые функции:

• RunSkillScript(skill: string, script: string, arguments?: string[]): выполнение скрипта навыка, поддерживает передачу параметров и переключение рабочего каталога
• findScripts(skillPath: string): рекурсивный поиск исполняемых файлов в каталоге навыка, возвращает отсортированный по относительным путям список

Бизнес-правила:

• При выполнении скрипта переключение рабочего каталога на каталог навыка (tools.ts:180): $.cwd(skill.path)
• Выполняются только скрипты из списка scripts навыка (tools.ts:165-177)
• При отсутствии скрипта возвращается список доступных скриптов, поддерживаются предложения по нечёткому сопоставлению (tools.ts:168-176)
• При сбое выполнения возвращаются код выхода и вывод ошибки (tools.ts:184-195)
• Пропускаются скрытые каталоги (начинающиеся с .) и распространённые каталоги зависимостей (skills.ts:70-71)