diff --git a/docs/ai/_category_.json b/docs/ai/_category_.json new file mode 100644 index 0000000..720010f --- /dev/null +++ b/docs/ai/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Работа с ИИ", + "position": 65 +} diff --git a/docs/ai/opencode.md b/docs/ai/opencode.md new file mode 100644 index 0000000..f901949 --- /dev/null +++ b/docs/ai/opencode.md @@ -0,0 +1,177 @@ +--- +title: "Работа с OpenCode" +--- + +[Перейти на сайт](https://ru.hexlet.io) + +# Работа с OpenCode + +> Как установить OpenCode, выбрать модель и подключить агента к GitHub Actions. + +OpenCode это агент для разработки на основе языковых моделей, который работает в терминале. На нём построены курсы по разработке с ИИ: агент читает код проекта, правит файлы, запускает команды и в одном из уроков отвечает на задачи в GitHub. + +## Установка + +Скачайте OpenCode со [страницы загрузки](https://opencode.ai/ru/download) и выберите вариант для своей операционной системы. После установки проверьте версию: + +```bash +opencode --version +``` + +В выводе должна быть вторая версия, например `opencode v2.0.13`. Инструкции ниже написаны для неё. Если стоит версия 1.x, удалите её и поставьте OpenCode заново со страницы загрузки. На старой версии часть команд называется иначе, а в списке интеграций нет нужных пунктов. + +Запустите агента командой `opencode` в каталоге проекта. + +## Выбор модели + +Модель выбирается внутри OpenCode командой `/models`. Модели тратят токены по-разному, поэтому под простую задачу стоит брать недорогую модель. + +### Бесплатные модели + +OpenCode даёт набор бесплатных моделей. Для них не нужны ни вход в аккаунт, ни ключ, ни карта: после установки они сразу видны в `/models`. В названии такой модели обычно стоит `free`. + +Состав бесплатных моделей OpenCode меняет, поэтому модель из урока через месяц может пропасть из списка. Актуальный список лежит в [документации OpenCode](https://opencode.ai/docs/zen/). Если модели из урока нет, возьмите любую другую бесплатную. + +У бесплатных моделей есть дневной лимит запросов. Кроме того, запросы к части из них OpenCode и авторы моделей используют для обучения, поэтому личные данные, пароли и чужой закрытый код туда не отправляйте. + +### Платные модели + +Для платных моделей нужен аккаунт OpenCode. Выполните в терминале: + +```bash +opencode auth login opencode +``` + +OpenCode спросит способ входа: + +```text +┌ Connect an integration +│ +◆ Select login method +│ ● OpenCode Console account +│ ○ API key (service account) +└ +``` + +Выберите **OpenCode Console account**, это вход через браузер. Второй пункт нужен для ключа сервисного аккаунта, в терминале он не используется. OpenCode напечатает код и адрес: + +```text +┌ Connect an integration +│ +◇ Select login method +│ OpenCode Console account +│ +◇ Authorization started +│ +● Enter code: CDDW-LVGK +│ +● https://opencode.ai/console/device?user_code=CDDW-LVGK&client_id=opencode-cli +│ +◐ Waiting for authorization. +``` + +Откройте адрес в браузере, проверьте код и войдите через Google или GitHub. После подтверждения команда завершится сама. Внутри OpenCode то же самое делает команда `/connect`. + +![Страница входа в OpenCode Console: кнопки Continue with Google, Continue with GitHub и Continue with email](/img/docs/img-208--opencode-console-login.png) + +Проверить подключение можно командой: + +```bash +opencode auth list +``` + +В выводе стоит интеграция, имя пространства и статус `stored`: + +```text +OpenCode Console Default stored +``` + +Оплата и расход живут в кабинете [opencode.ai/console](https://opencode.ai/console). Ключ другого провайдера, например OpenAI или Anthropic, подключается той же командой `/connect`. + +## Агент в GitHub Actions + +В уроке про GitHub Actions агент запускается на серверах GitHub по комментарию в задаче или пулреквесте. Как поставить приложение и завести файл `.github/workflows/opencode.yml`, рассказывает сам урок. Здесь только про модель и секрет. + +Модель задаётся в воркфлоу полем `model`, и от её провайдера зависит имя секрета с ключом: + +| Модель в воркфлоу | Имя секрета | +| --- | --- | +| `opencode/<модель>` | `OPENCODE_API_KEY` | +| `openai/<модель>` | `OPENAI_API_KEY` | +| `anthropic/<модель>` | `ANTHROPIC_API_KEY` | + +Секрет добавляется в репозитории на GitHub: **Settings → Secrets and variables → Actions**, кнопка **New repository secret**. + +**С бесплатной моделью ключ не нужен.** Укажите `model: opencode/<бесплатная модель>` и уберите из блока `env` строку с `OPENCODE_API_KEY`. Если агент отвечает ошибкой лимита, повторите запуск позже или переключитесь на платную модель. + +**С платной моделью нужен ключ.** Для моделей `opencode/…` его создают в кабинете [opencode.ai/console](https://opencode.ai/console) на вкладке **API Keys**, для остальных в кабинете провайдера. Значение ключа кабинет показывает один раз, поэтому сразу скопируйте его в секрет. Пустой секрет роняет запуск на аутентификации. + +## Если вы купили программу по ИИ + +Студентам, которые купили программу по разработке с ИИ, например [«ИИ для разработчиков»](https://ru.hexlet.io/programs/ai-for-developers), Хекслет даёт доступ к платным моделям через пространство **Hexlet Students** в OpenCode. Устройство OpenCode и команды остаются теми же, что описаны выше. Меняется пространство, из которого идут запросы, и источник ключа для GitHub Actions. + +Если курсы по ИИ входят в ваш тариф другой профессии или в подписку, доступа к **Hexlet Students** у вас нет: в этом случае вы можете использовать бесплатные модели из разделов выше. + +### Приглашение в пространство + +Приглашение приходит на почту, которую вы указали в анкете курса. Войти в OpenCode можно только через Google или GitHub, поэтому почта аккаунта, через который вы входите, должна совпадать с почтой из анкеты. Какая почта привязана к GitHub, видно в [настройках GitHub](https://github.com/settings/emails). + +![Письмо от OpenCode с приглашением в пространство Hexlet Students и кнопкой Join workspace](/img/docs/img-209--opencode-workspace-invite.png) + +Если приглашение пришло на `student@gmail.com`, а вы входите через GitHub с почтой `student@yandex.ru`, OpenCode создаст новый пустой аккаунт без доступа к моделям курса. + +Если письма нет, проверьте папку «Спам» и зайдите на [opencode.ai/console](https://opencode.ai/console) напрямую: доступ уже выдан на почту из анкеты, и письмо для входа не требуется. + +### Подключение + +1. Откройте [opencode.ai/console](https://opencode.ai/console). По умолчанию там открывается ваше личное пространство. В переключателе пространств в левом верхнем углу выберите **Hexlet Students**. + + ![Переключатель пространств в левом верхнем углу кабинета с выбранным Hexlet Students и блок Connect OpenCode CLI с командами для V2 и V1](/img/docs/img-210--opencode-workspace-switch.png) + +2. В терминале выполните `opencode auth login opencode` и войдите через браузер с той же почтой. + +3. Проверьте подключение командой `opencode auth list`. В выводе должна быть строка с **Hexlet Students**: + + ```text + OpenCode Console Hexlet Students stored + ``` + +4. Запустите OpenCode и выберите модель командой `/models`. + +![Список моделей в OpenCode: у каждой модели подпись Hexlet Students / OpenCode](/img/docs/img-211--opencode-models-hexlet-students.png) + +Для проверки напишите агенту `ping`, он должен ответить. + +![Ответ агента pong на сообщение ping в пространстве Hexlet Students](/img/docs/img-212--opencode-ping.png) + +Если OpenCode просит оплату, активен аккаунт личного пространства. Переключитесь командой `opencode auth switch` и выберите **Hexlet Students**. Если пространства **Hexlet Students** нет в переключателе, почта входа не совпала с анкетой: напишите куратору, с какой почты вы вошли. + +![Кабинет OpenCode в личном пространстве Default: этот вариант неверный](/img/docs/img-213--opencode-workspace-default.png) + +![Кабинет OpenCode в пространстве Hexlet Students: этот вариант верный](/img/docs/img-214--opencode-workspace-hexlet-students.png) + +В OpenCode список подключений открывает команда `/connect`. У активного аккаунта курса рядом с **OpenCode Console** стоит **Hexlet Students**. + +![Окно Connect an integration в OpenCode: строка OpenCode Console с подписью Hexlet Students](/img/docs/img-215--opencode-connect-integration.png) + +### Лимит + +Общий лимит на студента составляет $20. Из них $15 в месяц идут на работу в терминале, этот бюджет и расход видны в кабинете на вкладке **Overview**. Остальное лежит на ключе для GitHub Actions. Отдельные запросы с ценой видны на вкладке **Logs**. + +### Ключ для GitHub Actions + +Ключ для урока про GitHub Actions выдаёт куратор. Выпустить его самостоятельно в пространстве **Hexlet Students** нельзя, вкладки **API Keys** у студента там нет. Когда дойдёте до урока, напишите куратору, и он пришлёт ключ в личные сообщения. + +Ключ работает с моделями `opencode/…`, поэтому секрет называется `OPENCODE_API_KEY`. Ключ личный: храните его только в секретах репозитория и не вставляйте в код. + +Если ключ потерялся или попал к посторонним, напишите куратору. Он отключит старый ключ и выдаст новый, после чего замените значение секрета в репозитории. + +## Если остались вопросы + +Купившим программу по ИИ отвечает куратор. Остальным поможет поддержка: support@hexlet.io. + +## Полезные ссылки + +[Документация OpenCode](https://opencode.ai/docs/) + +[Агент OpenCode в GitHub](https://opencode.ai/docs/github/) diff --git a/static/img/docs/img-208--opencode-console-login.png b/static/img/docs/img-208--opencode-console-login.png new file mode 100644 index 0000000..d28d7d3 Binary files /dev/null and b/static/img/docs/img-208--opencode-console-login.png differ diff --git a/static/img/docs/img-209--opencode-workspace-invite.png b/static/img/docs/img-209--opencode-workspace-invite.png new file mode 100644 index 0000000..120d9e0 Binary files /dev/null and b/static/img/docs/img-209--opencode-workspace-invite.png differ diff --git a/static/img/docs/img-210--opencode-workspace-switch.png b/static/img/docs/img-210--opencode-workspace-switch.png new file mode 100644 index 0000000..08a6e5b Binary files /dev/null and b/static/img/docs/img-210--opencode-workspace-switch.png differ diff --git a/static/img/docs/img-211--opencode-models-hexlet-students.png b/static/img/docs/img-211--opencode-models-hexlet-students.png new file mode 100644 index 0000000..2a10baf Binary files /dev/null and b/static/img/docs/img-211--opencode-models-hexlet-students.png differ diff --git a/static/img/docs/img-212--opencode-ping.png b/static/img/docs/img-212--opencode-ping.png new file mode 100644 index 0000000..8d3854f Binary files /dev/null and b/static/img/docs/img-212--opencode-ping.png differ diff --git a/static/img/docs/img-213--opencode-workspace-default.png b/static/img/docs/img-213--opencode-workspace-default.png new file mode 100644 index 0000000..6fa41a5 Binary files /dev/null and b/static/img/docs/img-213--opencode-workspace-default.png differ diff --git a/static/img/docs/img-214--opencode-workspace-hexlet-students.png b/static/img/docs/img-214--opencode-workspace-hexlet-students.png new file mode 100644 index 0000000..171dc92 Binary files /dev/null and b/static/img/docs/img-214--opencode-workspace-hexlet-students.png differ diff --git a/static/img/docs/img-215--opencode-connect-integration.png b/static/img/docs/img-215--opencode-connect-integration.png new file mode 100644 index 0000000..67057c2 Binary files /dev/null and b/static/img/docs/img-215--opencode-connect-integration.png differ