Создаём AI-ассистента для код-ревью с нуля

Введение

Каждый разработчик знает эту ситуацию. Вы сделали небольшую правку, создали Pull Request и… ждёте. Иногда ревью затягивается, потому что коллеги заняты, а иногда оно превращается в рутинный пинг-понг из-за пропущенной точки с запятой или несоответствия стайлгайду. Рутинные проверки отнимают драгоценное время и концентрацию, которые можно было бы потратить на обсуждение архитектуры и бизнес-логики.

А что, если делегировать эту первую, самую механическую линию обороны машине? Что, если бы у нас был неутомимый ассистент, который мгновенно проверял бы новый код и указывал на очевидные недочёты?

В этой статье мы с нуля создадим именно такого ассистента. Это не будет очередной «hello world» на модную тему. Это будет подробный, основанный на реальном опыте гайд по созданию Node.js-сервиса, который слушает вебхуки GitHub, отправляет код на анализ большой языковой модели (LLM) и публикует результаты в виде построчных комментариев к Pull Request.

Наш технологический стек:

• Node.js: Простой, быстрый старт и идеальная асинхронная модель для I/O-bound задач, таких как ожидание ответов от внешних API.

• GitHub: Де-факто стандарт для контроля версий с мощной и гибкой системой вебхуков.

• OpenRouter: Универсальный шлюз к десяткам языковых моделей. Он позволяет не привязываться к одному API (например, OpenAI) и даёт доступ к отличным бесплатным моделям, на одной из которых мы и построим наш сервис.

• AI-модель: Мы будем использовать qwen/qwen-2.5-72b-instruct:free — одну из бесплатных моделей, доступных на OpenRouter, которая отлично справляется с анализом кода.

Главная ценность этой статьи — в деталях. Я покажу не только «как надо», но и «как бывает». Мы вместе пройдём через все грабли, на которые я наступил в процессе: будем, отлаживать невалидные подписи вебхуков и, самое интересное, «приручать» LLM, которая не всегда следует инструкциям и возвращает JSON в самых причудливых форматах.

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

Часть 1: Фундамент — Наш первый сервер.

Прежде чем ловить события из внешнего мира, нам нужно построить дом, в котором мы будем их обрабатывать. Этот «дом» — наш Node.js сервер. А его «мозг» — это функция, которая умеет общаться с языковой моделью.

Шаг 1: Идея и архитектура

На высоком уровне наша система будет работать по следующей схеме:

Давайте кратко обоснуем выбор технологий:

• Node.js: Мы не будем усложнять проект фреймворками вроде Express или NestJS. Для нашей задачи — принять один тип POST-запроса и обработать его — достаточно встроенного в Node.js модуля http. Это делает наш сервер легковесным и избавляет от лишних зависимостей. Асинхронная природа Node.js идеально подходит для работы с внешними API, где большую часть времени мы будем просто ждать ответа.

• OpenRouter: Вместо того чтобы привязываться к API одного конкретного провайдера, мы будем использовать OpenRouter. Это агрегатор, который предоставляет единый API, совместимый с API OpenAI, для доступа к десяткам моделей от разных разработчиков (Google, Anthropic, Mistral и др.). Главные плюсы это — возможность легко менять модели «на лету» и доступ к очень мощным бесплатным моделям, которые идеально подходят для нашего MVP.

Шаг 2: Создание базового Node.js сервера

Начнём с самого простого. Создадим в директории проекта файл index.js и напишем код веб-сервера, который будет слушать входящие запросы.

import http from ‘http’; const server = http.createServer((req, res) => { // Пока просто отвечаем на любой запрос res.writeHead(200, { ‘Content-Type’: ‘text/plain’ }); res.end(‘Server is alive!’); }); const port = 3000; server.listen(port, () => { console.log(`Server is listening on http://localhost:${port}`); });

Этот код использует встроенный модуль http для создания сервера. Он принимает любой запрос (req), отправляет в ответ статус 200 OK и простое текстовое сообщение.

Запустим его в терминале:

node index.js

Вы должны увидеть сообщение: Server is listening on http://localhost:3000. Наш фундамент готов.

Шаг 3: Первое обращение к AI

Теперь научим наш проект общаться с «мозгом». Для взаимодействия с API OpenRouter мы будем использовать официальную библиотеку от OpenAI, так как их API полностью совместимы.

Сначала установим её:

npm install openai

Для безопасного хранения нашего API-ключа мы будем использовать переменные окружения. Создайте в корне проекта файл .env и добавьте в него ваш ключ от OpenRouter. (сгенерировать апи ключ можно по адресу https://openrouter.ai/settings/keys)

OPENROUTER_API_KEY=»…»

Чтобы Node.js «увидел» этот файл, установим пакет dotenv:

npm install dotenv

Теперь обновим наш index.js, добавив логику для вызова AI.

import http from ‘http’; import OpenAI from ‘openai’; import ‘dotenv/config’; // Загружаем переменные из .env // НАСТРОЙКА КЛИЕНТА ДЛЯ OPENROUTER const openai = new OpenAI({ baseURL: «https://openrouter.ai/api/v1», apiKey: process.env.OPENROUTER_API_KEY, }); // АСИНХРОННАЯ ФУНКЦИЯ ДЛЯ ТЕСТА AI async function testAI() { console.log(«Отправляем тестовый запрос ИИ…»); try { const completion = await openai.chat.completions.create({ model: «qwen/qwen-2.5-72b-instruct:free», messages: [ { role: «user», content: «Ответь на главный вопрос жизни, вселенной и вообще. (The Hitchhiker’s Guide to the Galaxy)» } ], }); console.log(«Ответ ИИ:», completion.choices[0].message.content); } catch (error) { console.error(«Ощибка вызова AI:», error); } } // СЕРВЕР (остается без изменений) const server = http.createServer((req, res) => { res.writeHead(200, { ‘Content-Type’: ‘text/plain’ }); res.end(‘Server is alive!’); }); const port = 3000; server.listen(port, () => { console.log(`Server is listening on http://localhost:${port}`); // Вызываем тестовую функцию при старте сервера testAI(); });

Что мы сделали:

1. Импортировали dotenv/config, чтобы загрузить переменные из .env в process.env.

2. Инициализировали клиент openai, указав baseURL от OpenRouter и наш API-ключ.

3. Создали асинхронную функцию testAI, которая отправляет простой текстовый запрос модели и выводит её ответ в консоль.

4. Вызвали эту функцию один раз при старте сервера для проверки.

Теперь, если вы запустите node index.js, вы увидите не только сообщение о старте сервера, но и ответ от языковой модели.

Итак, наш фундамент готов: у нас есть сервер, способный принимать запросы, и «мозг», способный генерировать осмысленные ответы.

Часть 2: Подключаемся к реальному миру — Вебхуки GitHub

Наш сервер работает, AI готов к труду и обороне. Но пока они существуют в вакууме на localhost. Чтобы наш ассистент мог реагировать на события в репозитории, нам нужно научить GitHub отправлять ему уведомления. Эти уведомления называются вебхуками.

Шаг 4: Проблема локальной разработки

Здесь мы сталкиваемся с первой фундаментальной проблемой. Наш сервер работает по адресу http://localhost:3000 — этот адрес доступен только на нашем компьютере. GitHub, находясь в глобальной сети, понятия не имеет, как отправить запрос на ваш localhost. Ему нужен публично доступный URL.

Классическое решение этой задачи — ngrok. Это утилита, которая создает безопасный туннель от публичного URL к вашему локальному порту. Это отличный инструмент, но для работы с GitHub есть решение элегантнее и удобнее, интегрированное в экосистему самого GitHub.

Шаг 5: Правильный инструмент — GitHub CLI

Вместо сторонних утилит мы воспользуемся официальным инструментом — GitHub CLI (gh). Это консольная утилита, которая позволяет делать с GitHub практически всё, не выходя из терминала. Одна из её самых полезных функций для нас — перенаправление вебхуков.

Сначала установим gh. Инструкции для всех ОС есть на официальной странице. После установки нужно будет авторизоваться, выполнив gh auth login.

Далее, установим специальное расширение для работы с вебхуками:

gh extension install cli/gh-webhook

Теперь у нас есть всё необходимое. Одной командой мы можем «сказать» GitHub: «Все вебхуки, связанные с Pull Request в этом репозитории, пожалуйста, пересылай на мой локальный сервер».

Убедитесь, что ваш Node.js сервер запущен, и в новом окне терминала выполните команду:

gh webhook forward —repo=<OWNER>/<REPO> —events=pull_request —url=»http://localhost:3000/webhook»

Давайте разберём её:

—repo=<OWNER>/<REPO>: Укажите владельца и имя вашего репозитория (например, AlekseyVY/leetcode).

—events=pull_request: Мы подписываемся только на события, связанные с Pull Request.

—url=»http://localhost:3000/webhook»: Тот самый адрес, куда gh будет пересылать полученные события. Мы будем обрабатывать их по пути /webhook.

После выполнения вы должны увидеть сообщение Forwarding Webhook events from GitHub…. Поздравляю, мост между GitHub и вашим локальным сервером построен!

Шаг 6: Первая линия обороны — верификация подписи

Теперь наш сервер доступен извне. Но как нам убедиться, что запрос, пришедший на /webhook, был отправлен именно GitHub, а не каким-то злоумышленником? Для этого GitHub подписывает каждый вебхук. Он создает HMAC-хеш от тела запроса (payload), используя секретный ключ, который знаете только вы и он. Этот хеш отправляется в заголовке X-Hub-Signature-256. Наша задача — выполнить ту же операцию у себя на сервере и сравнить результаты. Если хеши совпадают — запрос подлинный. Для начала, обновим наш сервер, чтобы он обрабатывал путь /webhook и читал тело запроса. Нам понадобится пакет raw-body для корректного чтения потока.

npm install raw-body

затем создадим Секретный ключ, который мы будем использовать GITHUB_WEBHOOK_SECRET = ‘my-super-secret-123’в нашем .env. ВАЖНО: Он должен быть таким же, как и тот, что мы укажем для gh.

Теперь напишем саму функцию верификации и интегрируем её в сервер.

// index.js (добавляем новые импорты и логику) import http from ‘http’; import crypto from ‘crypto’; import getRawBody from ‘raw-body’; // … остальной код инициализации … const server = http.createServer(async (req, res) => { if (req.method === ‘POST’ && req.url === ‘/webhook’) { // Верифицируем подпись const signature = req.headers[‘x-hub-signature-256’]; const rawBody = await getRawBody(req); if (!verifySignature(signature, rawBody)) { console.error(‘Невалидная сигнатура, запрос проигнорирован.’); res.writeHead(401, { ‘Content-Type’: ‘text/plain’ }); res.end(‘Unauthorized’); return; } // Если подпись верна, пока просто логируем событие const event = req.headers[‘x-github-event’]; console.log(`Получено валидное событие вебхука: ${event}`); res.writeHead(200, { ‘Content-Type’: ‘text/plain’ }); res.end(‘Webhook received!’); return; } // Для всех остальных запросов res.writeHead(404); res.end(); }); function verifySignature(signature, payloadBody) { if (!signature) { return false; } const hmac = crypto.createHmac(‘sha256’, process.env.GITHUB_WEBHOOK_SECRET); const digest = ‘sha256=’ + hmac.update(payloadBody).digest(‘hex’); // Используем crypto.timingSafeEqual для защиты от атак по времени return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest)); } // … код запуска сервера …

«Ага!» момент: ловушка с «Невалидная сигнатура»

Теперь, если вы запустите сервер и создадите Pull Request, вы, скорее всего, столкнётесь с ошибкой в консоли: Невалидная сигнатура, запрос проигнорирован.. Почему? Ведь код верификации правильный.

Дело в том, что по умолчанию gh webhook forward сам генерирует случайный секрет для создаваемого на лету вебхука. А наш сервер ожидает my-super-secret-123. Секреты не совпадают. Решение простое — нужно явно указать gh, какой секрет использовать, с помощью флага —secret. Остановите предыдущую команду gh и запустите новую, правильную:

gh webhook forward —repo=<OWNER>/<REPO> —events=pull_request —url=»http://localhost:3000/webhook» —secret «my-super-secret-123»

Теперь, когда вы создадите Pull Request, ваш сервер должен будет ответить в консоли Получено валидное событие вебхука: pull_request. Мы успешно и безопасно соединили наш сервер с GitHub. Он готов принимать события и проверять их подлинность.

Часть 3: MVP 1.0 — Общий комментарий к Pull Request

На этом этапе мы создадим первую рабочую версию нашего ассистента (Minimum Viable Product). Он будет выполнять три ключевые действия:

1. Получать изменения кода (diff) из Pull Request.

2. Отправлять их на анализ AI.

3. Публиковать ответ модели в виде общего комментария к Pull Request.

Шаг 7: Получаем изменения кода (diff)

Вся информация о событии, включая Pull Request, приходит к нам в теле вебхука в формате JSON. Среди множества полей там есть одно, которое нам особенно интересно — pull_request.diff_url. Это прямая ссылка на .diff файл, содержащий все изменения кода в данном PR.

Чтобы получить доступ к этому файлу, нам нужно будет сделать аутентифицированный запрос к API GitHub. Для этого понадобится Personal Access Token (PAT).

Создать его можно в настройках вашего профиля GitHub:

• Перейдите в Settings → Developer settings → Personal access tokens → Tokens (classic).

• Нажмите Generate new token (classic).

• Дайте токену имя (например, code-review-bot) и установите срок действия.

• Самое важное — выберите права (scopes). Для наших задач достаточно одного: repo. Он даёт полный контроль над вашими репозиториями, включая чтение PR и написание комментариев.

• Сгенерируйте токен и немедленно скопируйте его. Вы больше никогда не сможете его увидеть.

Добавим этот токен в наш .env файл:

# .env OPENROUTER_API_KEY=»…» GITHUB_WEBHOOK_SECRET=»…» GITHUB_TOKEN=»…»

Теперь напишем асинхронную функцию, которая будет скачивать diff.

// index.js (добавляем эту функцию в файл) async function getPullRequestDiff(diffUrl) { console.log(«Фетчим дифф:», diffUrl); const response = await fetch(diffUrl, { headers: { ‘Authorization’: `token ${process.env.GITHUB_TOKEN}`, ‘Accept’: ‘application/vnd.github.v3.diff’ // Важный заголовок, указывающий нужный формат } }); if (!response.ok) { throw new Error(`Ошибка получения дифф: ${response.statusText}`); } return response.text(); }

Эта функция использует встроенный в Node.js fetch для выполнения запроса, добавляя в заголовки наш PAT для аутентификации.

Шаг 8: Первый промпт для код-ревью

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

// index.js (обновим нашу функцию для общения с AI) async function getCodeReviewFromLLM(diff) { console.log(«Sending diff to LLM for review…»); const prompt = ` Ты — экспертный AI-код-ревьюер. Твоя задача — провести обзор следующего pull request. Пользователь предоставил файл с диффом. Пожалуйста, проанализируй его и предоставь конструктивный отзыв. Сфокусируйся на возможных ошибках, несоответствиях стилю или предложениях по улучшению. Предоставь отзыв в понятной и дружелюбной форме, используя форматирование Markdown. Вот дифф: «`diff ${diff} «` `; try { const completion = await openai.chat.completions.create({ model: «qwen/qwen-2.5-72b-instruct:free», messages: [{ role: «user», content: prompt }], }); return completion.choices[0].message.content; } catch (error) { console.error(«Ошибка вызова LLM API:», error); return «Извините, я не смог провести код-ревью на данный момент.»; } }

Шаг 9: Публикуем ответ

Получив ревью от модели, нам нужно опубликовать его в GitHub. Для этого мы будем использовать pull_request.comments_url из полезной нагрузки вебхука. Это эндпоинт для создания общих комментариев к PR.

// index.js (добавляем ещё одну функцию-хелпер) async function postReviewComment(commentsUrl, reviewText) { console.log(«Публикация комментария к review. :», commentsUrl); await fetch(commentsUrl, { method: ‘POST’, headers: { ‘Authorization’: `token ${process.env.GITHUB_TOKEN}`, ‘Accept’: ‘application/vnd.github.v3+json’, ‘Content-Type’: ‘application/json’ }, body: JSON.stringify({ body: reviewText }) }); }

Теперь соберём всё вместе в главной логике нашего сервера.

// index.js (обновляем обработчик вебхука) const server = http.createServer(async (req, res) => { if (req.method === ‘POST’ && req.url === ‘/webhook’) { // … код верификации подписи … // Парсим payload const payload = JSON.parse(rawBody.toString()); const event = req.headers[‘x-github-event’]; if (event === ‘pull_request’) { if (payload.action === ‘opened’) { const pr = payload.pull_request; console.log(`Обрабатываю PR: ${pr.title}`); // Запускаем процесс ревью const diff = await getPullRequestDiff(pr.diff_url); const review = await getCodeReviewFromLLM(diff); await postReviewComment(pr.comments_url, review); } } res.writeHead(200, { ‘Content-Type’: ‘text/plain’ }); res.end(‘Webhook processed!’); return; } // … });

Наш MVP 1.0 готов! Если сейчас создать PR, наш ассистент скачает diff, отправит его на анализ и опубликует результат в виде комментария. Но… скорее всего, вы столкнётесь с парой неприятных сюрпризов.

Шаг 10: Первые грабли и гонка состояний

Реальный мир сложнее, чем кажется, и при работе с асинхронными системами, такими как вебхуки, это проявляется особенно ярко.

1. Проблема «пустых» или двойных комментариев:

• Симптом: Вы создаете PR и видите, что бот оставляет несколько комментариев, один из которых может быть пустым.

• Причина: Событие pull_request в GitHub срабатывает не только при открытии (opened), но и при других действиях: добавлении коммитов (synchronize), переводе из черновика в готовые (ready_for_review) и т.д. Наш код реагирует на все, что приводит к хаосу.

• Решение: Сделать обработку событий более строгой. Мы должны реагировать только на те действия, которые нас интересуют. Идеально для этого подходит конструкция switch.

1. Проблема пустого diff-файла:

• Симптом: Бот оставляет комментарий, в котором жалуется на пустой diff, хотя в PR очевидно есть изменения.

• Причина: API GitHub работает по принципу «согласованности в конечном счёте» (eventual consistency). Когда GitHub отправляет вебхук opened, это не гарантирует, что diff_url уже на 100% доступен и содержит данные. Наш сервер слишком быстр — он запрашивает diff раньше, чем тот успевает сгенерироваться.

• Решение: Добавить небольшую искусственную задержку перед запросом diff-файла. 3-5 секунд обычно достаточно, чтобы дать API GitHub время «прийти в себя».

Вот как будет выглядеть наш улучшенный, более надёжный обработчик:

// index.js (финальная версия обработчика для MVP 1.0) // … if (event === ‘pull_request’) { const action = payload.action; console.log(`Получил событие pull_request с действием: ${action}`); switch (action) { case ‘opened’: case ‘reopened’: res.writeHead(200, { ‘Content-Type’: ‘text/plain’ }); res.end(‘Webhook accepted. Processing review in the background.’); // Запускаем «медленный» процесс в фоне handlePullRequest(payload); break; default: console.log(`Игнорирую действие «${action}».`); res.writeHead(200, { ‘Content-Type’: ‘text/plain’ }); res.end(`Action «${action}» ignored.`); break; } } // … async function handlePullRequest(payload) { try { const pr = payload.pull_request; console.log(`Обрабатываю PR: «${pr.title}»`); // РЕШЕНИЕ 2: Добавляем задержку await new Promise(resolve => setTimeout(resolve, 5000)); const diff = await getPullRequestDiff(pr.diff_url); if (diff && diff.trim()) { const review = await getCodeReviewFromLLM(diff); await postReviewComment(pr.comments_url, review); console.log(`Ревью орубликованно для PR: «${pr.title}»`); } else { console.log(«Дифф пустой. Пропускаю ревью.»); } } catch (error) { console.error(«Ошибка обработки PR:», error); } }

Обратите внимание на ещё одно улучшение: мы сначала отправляем GitHub ответ 200 OK, а уже потом запускаем handlePullRequest. Это лучшая практика для долгих задач. GitHub не любит, когда вебхуки «висят» без ответа больше нескольких секунд.

Теперь наш MVP не только работает, но и устойчив к основным проблемам реального мира. Однако общий комментарий — это хорошо, но настоящий ревьюер комментирует конкретные строки.

Часть 4: Level Up — От общих фраз к построчным комментариям

Общий комментарий — это уже неплохо, но ценность код-ревью в контексте. Замечания должны быть привязаны к конкретным строкам кода, чтобы разработчик мог сразу понять, о чём идёт речь, и начать обсуждение. Чтобы этого добиться, нам нужно научить модель возвращать структурированные данные и использовать другой, более мощный эндпоинт GitHub API.

Шаг 11: Промпт-инжиниринг для JSON

Просить модель вернуть обычный текст больше не годится. Нам нужно, чтобы на выходе мы получали данные в формате, который легко сможет «прочитать» наша программа. Идеальный кандидат — JSON.

Мы должны кардинально изменить наш промпт. Теперь его главная задача — не просто попросить сделать ревью, а строго указать, в каком формате вернуть результат.

• Формат: Мы будем ожидать JSON-массив.

• Элемент массива: Каждый элемент будет представлять собой один комментарий и должен быть объектом с тремя ключами:

  • path: путь к файлу, к которому относится комментарий.

  • line: номер строки в diff-файле.

  • body: текст самого комментария.

Вот как выглядит новый промпт:

// index.js (внутри функции getCodeReviewFromLLM) const prompt = ` Ты — высококвалифицированный AI-ревьюер кода. Твоя задача — провести ревью pull request на основе предоставленного diff-файла и вернуть свои замечания в формате JSON. Проанализируй следующие изменения. Для КАЖДОГО замечания, которое ты найдешь, укажи путь к файлу и номер строки в diff-файле, к которой относится замечание. Твой ответ ДОЛЖЕН быть валидным JSON-массивом объектов. Каждый объект должен иметь следующие ключи: — «path»: (string) Полный путь к файлу. — «line»: (number) Номер строки в diff-файле, к которой относится комментарий. — «body»: (string) Текст твоего комментария. Пример желаемого формата ответа: [ { «path»: «src/user-service.ts», «line»: 15, «body»: «Здесь лучше использовать ‘const’ вместо ‘let’, так как переменная не переназначается.» } ] Если в коде нет проблем, верни пустой массив []. Вот diff для анализа: «`diff ${diff} «` `;

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

// index.js (обновляем вызов openai.chat.completions.create) const completion = await openai.chat.completions.create({ model: «qwen/qwen-2.5-72b-instruct:free», messages: [{ «role»: «user», «content»: prompt }], // Говорим модели, что ответ должен быть в формате JSON response_format: { type: «json_object» }, }); const responseText = completion.choices[0].message.content; // Модель может вернуть JSON внутри markdown блока, очистим это. const cleanedJson = JSON.parse(responseText.replace(/«`json/g, »).replace(/«`/g, »).trim()); // или обьект с полем comments if(‘comments’ in cleanedJson) { return cleanedJson.comments; } return JSON.parse(cleanedJson);

Теперь наша функция getCodeReviewFromLLM возвращает не просто строку, а готовый JavaScript-массив с объектами комментариев.

Шаг 12: Новый API GitHub — Pull Request Reviews

Просто отправлять комментарии больше не получится. Чтобы привязать их к строкам, нам нужно использовать более сложный механизм — Pull Request Reviews.

Ревью в GitHub — это сущность, которая может объединять:

• Один общий комментарий к Pull Request.

• Несколько построчных комментариев.

• Статус (Approve, Request Changes или просто Comment).

Для создания ревью используется новый эндпоинт: POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews.

Давайте напишем новую функцию для отправки такого ревью. Старая postReviewComment нам больше не понадобится.

// index.js (новая функция вместо postReviewComment) async function postLineByLineReview(owner, repo, pull_number, comments) { const endpoint = `https://api.github.com/repos/${owner}/${repo}/pulls/${pull_number}/reviews`; console.log(«Публикую комментарии:», endpoint); const reviewBody = { body: «AI-ассистент провел ревью кода. Пожалуйста, ознакомьтесь с комментариями.», // Общий комментарий event: «COMMENT», // Мы просто комментируем, не апрувим и не запрашиваем изменения comments: comments, // Массив наших построчных комментариев }; const response = await fetch(endpoint, { method: ‘POST’, headers: { ‘Authorization’: `token ${process.env.GITHUB_TOKEN}`, ‘Accept’: ‘application/vnd.github.v3+json’, ‘Content-Type’: ‘application/json’ }, body: JSON.stringify(reviewBody) }); if (!response.ok) { const errorBody = await response.text(); throw new Error(`Ошибка публикации комментариев: ${response.statusText} — ${errorBody}`); } }

Эта функция принимает все необходимые данные (владельца репо, имя репо, номер PR) и массив комментариев, который мы получили от LLM. Она формирует тело запроса и отправляет его в GitHub.

Осталось только обновить handlePullRequest, чтобы он вызывал новую функцию с правильными параметрами.

// index.js (обновляем handlePullRequest) async function handlePullRequest(payload) { try { const pr = payload.pull_request; const repo = payload.repository; // Получаем нужные данные из payload const owner = repo.owner.login; const repoName = repo.name; const prNumber = pr.number; // … (код с задержкой и получением diff) … if (diff && diff.trim()) { const reviewComments = await getCodeReviewFromLLM(diff); if (reviewComments && reviewComments.length > 0) { await postLineByLineReview(owner, repoName, prNumber, reviewComments); console.log(`Ревью успешно проведено для PR: «${pr.title}»`); } else { console.log(«LLM не вернула комментарии.»); } } else { console.log(«Дифф пустой, скипаю ревью.»); } } catch (error) { console.error(«Ошибк обработки PR:», error); } }

Теперь наш ассистент перешёл на новый уровень. Он не просто бросает общие фразы, а участвует в ревью почти как настоящий член команды, оставляя замечания там, где им и место — в коде.

Казалось бы, работа сделана. Но, как вы догадываетесь, именно здесь и начинается самое интересное. Языковая модель — не компилятор. Она креативна, а иногда — слишком креативна.

Часть 5: Закаляем код — Битва с непредсказуемостью LLM

Теория великолепна: мы просим модель вернуть JSON, она его возвращает, мы его парсим и отправляем. Реальность гораздо интереснее. Языковая модель это не детерминированный API, а творческий партнёр. Иногда её «творчество» ломает наш код. В этой главе мы рассмотрим реальные ошибки, с которыми столкнулись, и превратим наш скрипт в по-настоящему отказоустойчивый инструмент.

Шаг 13: Парсинг и очистка данных

Первая же попытка запустить нашего обновлённого бота привела к ошибке 422 Unprocessable Entity от API GitHub. Сообщение гласило: «Pull request review thread path is invalid».

• Проблема: Мы попросили модель вернуть path и line из diff-файла. Она справилась идеально. Вот только формат diff устроен так, что пути к файлам указываются с префиксами a/ и b/. Модель вернула нам путь вида b/src/index.js. Но API GitHub ожидает «чистый» путь: src/index.js. Он не смог найти файл b/src/index.js в репозитории и отклонил запрос.

• Решение: Добавить простой шаг очистки данных перед отправкой в GitHub.

// index.js (внутри handlePullRequest) // … получили reviewComments от LLM … const cleanedComments = reviewComments.map(comment => ({ …comment, // Если путь начинается с ‘b/’, убираем первые два символа. // Аналогично можно добавить и для ‘a/’, если модель вдруг решит вернуть такой путь. path: comment.path.startsWith(‘b/’) ? comment.path.substring(2) : comment.path })); // Отправляем в GitHub уже очищенные комментарии await postLineByLineReview(owner, repoName, prNumber, cleanedComments);

Просто, но эффективно. Это первый урок: никогда не доверяйте данным от LLM на 100%, всегда валидируйте и очищайте их.

Шаг 14: Делаем код «пуленепробиваемым»

Следующие несколько запусков подарили нам целый каскад ошибок TypeError и SyntaxError. Каждый раз, когда мы думали, что предусмотрели всё, модель находила новый способ нас удивить. Вот наш «хит-парад» проблем и их решений.

1. Проблема: Модель вернула ОБЪЕКТ {} вместо МАССИВА []

   • Симптом: Мы нашли одно замечание. Вместо того чтобы обернуть его в массив [{…}], модель вернула просто один объект {…}.

   • Ошибка: TypeError: reviewComments.map is not a function. Логично, у объектов нет метода .map().

   • Решение: Сделать наш парсер умнее. Если мы получили объект, нужно проверить, не является ли он сам по себе комментарием.

2. Проблема: Модель вернула ОБЪЕКТ С ВЛОЖЕННЫМ МАССИВОМ { «comments»: […] }

   • Симптом: Модель решила быть «полезной» и обернула массив в объект с ключом comments.

   • Ошибка: Та же самая, reviewComments.map is not a function.

   • Решение: Если мы получили объект, нужно не только проверить, не является ли он сам комментарием, но и поискать, нет ли внутри него ключа, значение которого — массив.

3. Проблема: Модель вернула ПУСТУЮ СТРОКУ «»

   • Симптом: Модель не нашла замечаний и вместо пустого массива [] вернула пустой ответ.

   • Ошибка: SyntaxError: Unexpected end of JSON input при попытке JSON.parse(«»).

   • Решение: Добавить проверку на пустую строку перед вызовом JSON.parse.

4. Проблема: API вернул ОТВЕТ БЕЗ поля choices

   • Симптом: Редкий случай, когда API OpenRouter вернул 200 OK, но в теле ответа отсутствовал ключ choices. Это может случиться при внутреннем таймауте у провайдера модели.

   • Ошибка: TypeError: Cannot read properties of undefined (reading ‘0’) при попытке доступа к completion.choices[0].

   • Решение: Добавить проверку на существование и непустоту completion.choices перед доступом к его элементам.

Чтобы решить все эти проблемы разом, мы написали финальную, надёжную логику парсинга в handlePullRequest и getCodeReviewFromLLM.

Вот обновлённый, закалённый в боях код:

// index.js (финальная, отказоустойчивая версия getCodeReviewFromLLM) async function getCodeReviewFromLLM(diff) { // … (промпт без изменений) … try { const completion = await openai.chat.completions.create({ /* … */ }); // РЕШЕНИЕ 4: Проверяем ‘choices’ if (!completion.choices || completion.choices.length === 0) { console.log(«LLM ответ не содержит поля ‘choices’.»); return null; } const responseText = completion.choices[0].message.content; // РЕШЕНИЕ 3: Проверяем на пустую строку if (!responseText || !responseText.trim()) { console.log(«LLM вернула пустую строку.»); return null; } const cleanedJson = responseText.replace(/«`json/g, »).replace(/«`/g, »).trim(); return JSON.parse(cleanedJson); } catch (error) { console.error(«Ошибка парсинга LLM ответа:», error); return null; // Возвращаем null в случае любой ошибки } } // index.js (финальная, отказоустойчивая версия handlePullRequest) async function handlePullRequest(payload) { // … (получение diff) … const rawResponse = await getCodeReviewFromLLM(diff); console.log(«Чистый AI ответ:», rawResponse); let commentsArray = []; // РЕШЕНИЕ 1 и 2: Гибкий парсинг if (Array.isArray(rawResponse)) { commentsArray = rawResponse; // Идеальный случай } else if (typeof rawResponse === ‘object’ && rawResponse !== null) { // Ищем массив внутри объекта let foundArray = false; for (const key in rawResponse) { if (Array.isArray(rawResponse[key])) { commentsArray = rawResponse[key]; foundArray = true; break; } } // Если массив не найден, проверяем, не является ли сам объект комментарием if (!foundArray && rawResponse.path && rawResponse.line && rawResponse.body) { commentsArray = [rawResponse]; } } if (commentsArray.length === 0) { console.log(«Не найдено валидных комментариев. Пропускаю.»); return; } // … (очистка путей и отправка) … }

Шаг 15: Отладка проблем с API OpenRouter

Иногда проблемы возникают не в нашем коде и не в модели, а в конфигурации. Я столкнулся с двумя такими ошибками от OpenRouter:

• 404 No endpoints found matching your data policy: Эта ошибка означает, что ваши настройки приватности в OpenRouter запрещают отправлять данные на бесплатные модели, которые могут использовать их для обучения. Решение — изменить политику на более разрешающую.

• 400 Invalid Model ID: Просто опечатка или использование устаревшего ID модели. Решение — проверить актуальное название на сайте OpenRouter.

Этот опыт учит нас важному правилу: всегда внимательно читать сообщения об ошибках от внешних API.

После всех этих улучшений наш код стал похож на опытного сапёра: он ожидает подвоха на каждом шагу и готов к любым сюрпризам.

Часть 6: Финальные штрихи и взгляд в будущее

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

Шаг 16: Интернационализация

Что, если ваша команда предпочитает получать фидбэк на другом языке? С языковыми моделями это решается элементарно. Нам не нужно менять логику, добавлять файлы локализации или переписывать код. Всё, что требуется — немного изменить наш промпт.

Откроем функцию getCodeReviewFromLLM и добавим в инструкцию для модели несколько фраз на русском:

// index.js (отрывок из промпта в getCodeReviewFromLLM) const prompt = ` Ты — высококвалифицированный AI-ревьюер кода. Твоя задача — провести ревью pull request… // … (описание формата JSON) … Пожалуйста, предоставь весь твой ответ на русском языке. Если в коде нет проблем, верни пустой массив []. Вот diff для анализа: … `;

Этого достаточно. Модель поймёт контекст и переведёт свои ответы. Это яркий пример того, насколько гибкими становятся системы, построенные на LLM: изменение поведения часто сводится к изменению текста на естественном языке, а не переписыванию сложной логики.

Шаг 17: Куда двигаться дальше?

Наш MVP — это только начало. Вот несколько идей, как можно превратить его в полноценный промышленный инструмент:

• Развёртывание в Kubernetes:
  Сейчас мы запускаем сервер локально. Для продакшена его следует упаковать в Docker-контейнер и развернуть в Kubernetes-кластере. Это даст нам масштабируемость, отказоустойчивость и позволит легко управлять секретами (API-ключами) через нативные инструменты K8s.

• Интеграция с GitLab/Bitbucket:
  Демонстрация была сделана на GitHub, но архитектура нашего сервиса универсальна. GitLab, Bitbucket и другие системы контроля версий предоставляют очень похожие механизмы вебхуков. Адаптация нашего сервиса для GitLab сведётся к трём вещам:

  1. Разобраться со структурой JSON-объекта, который присылает GitLab (она будет отличаться от GitHub).

  2. Изменить эндпоинты для публикации комментариев в соответствии с API GitLab.

  3. Реализовать их механизм верификации подписи (например, через X-Gitlab-Token). Сама логика работы с LLM останется неизменной.

• Более сложные промпты:
  Можно создать библиотеку промптов для разных типов файлов. Например, для .sql-файлов просить модель обращать внимание на потенциальные SQL-инъекции и производительность запросов, а для .js-файлов — на асинхронные паттерны и обработку ошибок.

• Анализ изображений и диаграмм:
  Современные модели, такие как Google Gemini, мультимодальны — они могут анализировать не только текст, но и изображения. Можно расширить бота, чтобы он «смотрел» на скриншоты в комментариях и описывал, что на них видит, или даже анализировал загруженные в PR диаграммы архитектуры.

• Сбор статистики и обучение команды:
  Каждый комментарий, оставленный ботом — это ценные данные. Можно сохранять их в базу данных и анализировать: какие типы ошибок встречаются в коде чаще всего? Это позволит выявить «слепые зоны» в знаниях команды и организовать целенаправленное обучение.

Заключение

Мы прошли полный путь от простой идеи до работающего и закалённого в боях MVP. Мы создали не просто «ещё одного бота», а по-настоящему полезный инструмент, который берёт на себя рутину и позволяет команде сосредоточиться на самом важном.

Главный вывод, который мы сделали: создание таких AI-инструментов — это не столько про вызов API, сколько про повышение отказоустойчивости и «приручение» мощной, но не всегда предсказуемой технологии. Каждый TypeError, каждая 422 Unprocessable Entity — это не провал, а возможность сделать систему умнее и надёжнее.

P.S. Полный код проекта доступен в этом GitHub-репозитории.

Источник: habr.com