open-code-review/README.ru-RU.md

AI-агент код-ревью с открытым исходным кодом.

English | 简体中文 | 日本語 | 한국어 | Русский

---

Что такое Open Code Review?

Open Code Review — это CLI-инструмент для код-ревью на основе ИИ. Он появился как внутренний официальный ИИ-ассистент код-ревью Alibaba Group: за последние два года им воспользовались десятки тысяч разработчиков, и он выявил миллионы дефектов в коде. После тщательной проверки в огромных масштабах мы превратили его в open-source-проект для сообщества. Чтобы начать работу, достаточно настроить эндпоинт модели.

Инструмент читает git-диффы, отправляет изменённые файлы настраиваемой LLM через агента с поддержкой вызова инструментов (tool use) и генерирует структурированные ревью-комментарии с точностью до строки. Агент может читать полное содержимое файлов, искать по кодовой базе, заглядывать в другие изменённые файлы за контекстом и выполнять глубокое ревью — а не только давать поверхностные замечания по диффу.

Бенчмарк

По сравнению с агентами общего назначения (Claude Code), Open Code Review при той же базовой модели достигает значительно более высоких показателей Precision и F1, потребляя лишь ~1/9 токенов и выполняя ревью быстрее. При этом показатель Recall ниже, чем у агентов общего назначения — это осознанный компромисс в пользу точности и минимального шума.

Бенчмарк на основе реальных код-ревью: 50 популярных open-source-репозиториев, 200 реальных Pull Request, 10 языков программирования — перекрёстная валидация 80+ старшими инженерами (1 505 размеченных дефектов).

Метрика	Что измеряет	Почему важна
F1	Гармоническое среднее precision и recall	Лучший единый показатель качества ревью
Precision	% найденных проблем, являющихся реальными дефектами	Выше = меньше ложных срабатываний
Recall	% реальных дефектов, которые были найдены	Выше = меньше пропущенных проблем
Avg Time	Время выполнения одного ревью	Влияет на задержки в CI-пайплайне
Avg Token	Суммарное потребление токенов за ревью	Прямо влияет на стоимость API

Почему Open Code Review?

Проблема агентов общего назначения

Если вы использовали для код-ревью агентов общего назначения, например Claude Code со Skills, вы наверняка сталкивались с этими болевыми точками:

• Неполное покрытие — на крупных ченджсетах агенты склонны «срезать углы»: выборочно проверяют часть файлов и пропускают остальные.
• Дрейф позиций — найденные проблемы часто не совпадают с реальным местом в коде: номера строк и ссылки на файлы «уезжают» от цели.
• Нестабильное качество — Skills, управляемые естественным языком, трудно отлаживать, и качество ревью заметно колеблется при небольших изменениях промпта.

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

Ключевая идея: детерминированная инженерия × агент

Ключевая философия Open Code Review — сочетать детерминированную инженерию и агента так, чтобы каждый занимался тем, что у него получается лучше всего.

Детерминированная инженерия — жёсткие гарантии

Для тех шагов ревью, где нельзя ошибаться, корректность гарантирует инженерная логика, а не языковая модель:

• Точный отбор файлов — точно определяет, какие файлы нуждаются в ревью, а какие следует отфильтровать, гарантируя, что ни одно важное изменение не будет упущено.
• Умный бандлинг файлов — группирует связанные файлы в одну единицу ревью (например, message_en.properties и message_zh.properties объединяются вместе). Каждый бандл выполняется как суб-агент с изолированным контекстом — стратегия «разделяй и властвуй», которая сохраняет стабильность на очень больших ченджсетах и естественным образом поддерживает конкурентное ревью.
• Тонкий матчинг правил — сопоставляет правила ревью с характеристиками каждого файла, удерживая внимание модели сфокусированным и устраняя информационный шум у самого источника. По сравнению с чисто языковым управлением правилами матчинг правил на основе шаблонизатора стабильнее и предсказуемее.
• Внешние модули позиционирования и рефлексии — независимые модули позиционирования комментариев и рефлексии над комментариями системно повышают точность как расположения, так и содержания замечаний ИИ.

Агент — динамические решения

Сильные стороны агента сосредоточены там, где они важнее всего, — в динамических решениях и динамическом доборе контекста:

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

Как использовать

CLI

Установка

Через NPM (рекомендуется)

npm install -g @alibaba-group/open-code-review

После установки команда ocr доступна глобально.

Из GitHub Release

Скачайте свежий бинарный файл со страницы GitHub Releases:

# macOS (Apple Silicon)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# macOS (Intel)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Linux (x86_64)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Linux (ARM64)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Windows (x86_64) — переместите ocr.exe в каталог из вашего PATH
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe

# Windows (ARM64) — переместите ocr.exe в каталог из вашего PATH
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe

Из исходников

git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
sudo cp dist/opencodereview /usr/local/bin/ocr

Быстрый старт

1. Настройте LLM

Перед запуском ревью необходимо настроить LLM.

Вариант A: интерактивная настройка (рекомендуется)

ocr config provider          # Выбрать встроенного провайдера или добавить пользовательский
ocr config model             # Выбрать модель для активного провайдера

Вариант B: ручная настройка

ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token your-api-key-here
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true

Конфигурация хранится в ~/.opencodereview/config.json.

auth_header (необязательно): определяет, в каком HTTP-заголовке передаётся API-ключ при работе с Anthropic. Если не задан, по умолчанию используется authorization (Bearer-токен). Если у вас стандартный API-ключ вида sk-ant-*, необходимо установить значение x-api-key:

ocr config set llm.auth_header x-api-key

Поддерживаемые значения: x-api-key, authorization (алиас: bearer). Прочие значения отклоняются с ошибкой.

Вариант C: переменные окружения (наивысший приоритет)

export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=your-api-key-here
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

Инструмент также совместим с переменными окружения Claude Code (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL) и разбирает ~/.zshrc / ~/.bashrc в поисках соответствующих export'ов.

Примечание для пользователей CC-Switch: если вы используете CC-Switch с включённым routing service, можно указать в llm.url адрес прокси CC-Switch без дополнительной настройки:

• для провайдера Claude: установите llm.url в http://127.0.0.1:15721
• для провайдера Codex: установите llm.url в http://127.0.0.1:15721/v1
• llm.model задайте в соответствии с настройками вашего провайдера
• llm.auth_token может быть любым
• настройки extra_body продолжают действовать

2. Проверьте подключение

ocr llm test

3. Запустите ревью

cd your-project

# Режим рабочей копии — ревью всех staged, unstaged и untracked изменений
ocr review

# Диапазон веток — сравнение двух ref'ов
ocr review --from main --to feature-branch

# Один коммит
ocr review --commit abc123

Интеграция с кодинг-агентами

OCR легко встраивается в ИИ-агентов для разработки в виде slash-команды, позволяя выполнять код-ревью прямо в рабочем процессе агента.

Вариант 1: установка как Skill

Установите скилл OCR в свой проект через npx:

npx skills add alibaba/open-code-review --skill open-code-review

Это установит скилл open-code-review из реестра скиллов, который объясняет вашему кодинг-агенту, как вызывать ocr для код-ревью, классифицировать найденные проблемы по приоритету и при необходимости применять исправления.

Вариант 2: установка как плагин Claude Code

Для Claude Code установите плагин с командой, выполнив в Claude Code:

/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

Это зарегистрирует slash-команду /open-code-review:review, которая запускает OCR и автоматически фильтрует и исправляет найденные проблемы.

Вариант 3: установка как плагин Codex

Для локального Codex установите плагин Open Code Review из этого репозитория:

codex plugin marketplace add alibaba/open-code-review
codex
/plugins

Для локального чекаута или форка:

codex plugin marketplace add .
codex
/plugins

Установите и включите Open Code Review, затем начните новый тред Codex и вызывайте плагин явно:

@Open Code Review review my current changes
@Open Code Review review this branch against main
@Open Code Review review and fix high-confidence issues

Это зарегистрирует Codex-скилл, запускающий локальный CLI OCR:

ocr review --audience agent

Эта интеграция не меняет внутренний LLM-бэкенд OCR и не требует настройки эндпоинта OpenAI Responses API для Codex. Самому OCR по-прежнему нужен установленный и настроенный CLI ocr, как описано в разделе про настройку CLI.

Руководство на корейском: plugins/open-code-review/CODEX.ko-KR.md

Вариант 4: просто скопировать файл команды

Для быстрой настройки без пакетных менеджеров достаточно скопировать файл команды, чтобы использовать slash-команду /open-code-review в Claude Code.

На уровне проекта (общий для команды через git):

mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

На уровне пользователя (личное глобальное использование во всех проектах):

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

Требование: для всех способов интеграции необходим установленный CLI ocr и настроенная LLM. См. разделы Установка и Настройте LLM выше.

Интеграция с CI/CD

OCR можно встроить в CI/CD-пайплайны для автоматического код-ревью Merge Request'ов / Pull Request'ов.

Базовая команда для интеграции с CI:

ocr review \
  --from "origin/main" \
  --to "<commit_sha>" \
  --format json

Флаг --from принимает в качестве базы ref ветки (например, origin/main) или SHA коммита, а --to — SHA коммита или ref ветки в качестве head. В CI-окружениях для --to рекомендуется использовать SHA коммита: это корректно обрабатывает PR/MR из форков, у которых исходная ветка отсутствует в remote origin.

Флаг --format json выводит машиночитаемый результат, удобный для разбора в CI-скриптах.

Примеры интеграции — в каталоге examples/:

• github_actions/ — пример интеграции с GitHub Actions
• gitlab_ci/ — пример интеграции с GitLab CI

Команды

Команда	Алиас	Описание
ocr review	ocr r	Запустить код-ревью
ocr rules check <file>	—	Показать, какое правило ревью применяется к пути файла
ocr config provider	—	Интерактивная настройка провайдера (встроенный, пользовательский или ручной)
ocr config model	—	Интерактивный выбор модели для активного провайдера
ocr config set <key> <value>	—	Установить значения конфигурации
ocr llm test	—	Проверить подключение к LLM
ocr llm providers	—	Показать список встроенных LLM-провайдеров
ocr viewer	ocr v	Запустить WebUI-просмотрщик сессий на localhost:5483
ocr version	—	Показать информацию о версии

Флаги ocr review

Флаг	Короткая форма	По умолчанию	Описание
--repo	—	текущий каталог	Корень git-репозитория
--from	—	—	Исходный ref (например, main)
--to	—	—	Целевой ref (например, feature-branch)
--commit	-c	—	Один коммит для ревью
--preview	-p	false	Показать, какие файлы попадут в ревью, без запуска LLM
--format	-f	text	Формат вывода: text или json
--concurrency	—	8	Максимум одновременных ревью файлов
--timeout	—	10	Таймаут конкурентной задачи в минутах
--audience	—	human	human (показывать прогресс) или agent (только сводка)
--background	-b	—	Необязательный контекст требований/бизнес-логики для ревью; при --commit автоматически заполняется из сообщения коммита
--model	—	—	Выбрать или переопределить LLM-модель для этого ревью
--rule	—	—	Путь к пользовательским JSON-правилам ревью
--max-tools	—	встроенное	Максимум раундов вызова инструментов на файл; действует, только если больше значения шаблона по умолчанию
--max-git-procs	—	встроенное	Максимум одновременных git-подпроцессов
--tools	—	—	Путь к пользовательскому JSON-конфигу инструментов

Примеры

# Интерактивная настройка провайдера и модели
ocr config provider
ocr config model
ocr llm providers

# Показать, какие файлы попадут в ревью (без вызовов LLM)
ocr review --preview
ocr review -c abc123 -p

# Ревью изменений рабочей копии с настройками по умолчанию
ocr review

# Ревью диффа веток с заданной конкурентностью
ocr review --from main --to my-feature --concurrency 4

# Ревью конкретного коммита с подробным JSON-выводом
ocr review --commit abc123 --format json --audience agent

# Выбрать или переопределить модель для этого ревью
ocr review --model claude-opus-4-6
ocr review --commit abc123 --model claude-sonnet-4-6

# Передать контекст требований для более прицельного ревью
ocr review --background "Добавляем rate limiting в API логина"

# Использовать собственные правила ревью
ocr review --rule /path/to/my-rules.json

# Посмотреть, какое правило применяется к файлу
ocr rules check src/main/java/com/example/Foo.java
ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml

# Открыть историю сессий ревью в браузере
ocr viewer
ocr viewer --addr :3000

Безопасность viewer'а

Viewer отдаёт содержимое сессионных JSONL-файлов (сообщения запросов к LLM и ответы) по HTTP. На каждый запрос применяется allowlist по заголовку Host: loopback-имена (localhost, 127.0.0.0/8, ::1) и конкретный хост привязки разрешены всегда. Wildcard-привязки (--addr :3000, --addr 0.0.0.0:3000) и прочие не-loopback имена хостов нужно добавлять через переменную окружения OCR_VIEWER_ALLOWED_HOSTS (через запятую):

OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000

Это блокирует атаки DNS rebinding на локальный viewer.

Правила ревью

OCR разрешает правила ревью по цепочке приоритетов из четырёх уровней. На каждом уровне действует принцип «первое совпадение побеждает»: если путь файла совпал с паттерном, используется это правило; иначе поиск продолжается на следующем уровне.

Приоритет	Источник	Путь	Описание
1 (высший)	Флаг --rule	Путь, указанный пользователем	Явное переопределение из CLI
2	Конфиг проекта	<repoDir>/.opencodereview/rule.json	Правила уровня проекта, можно коммитить в git
3	Глобальный конфиг	~/.opencodereview/rule.json	Личные настройки пользователя
4 (низший)	Системные по умолчанию	Встроенный system_rules.json	Встроенные правила для распространённых языков и типов файлов

Формат файла правил

Уровни 1–3 используют один и тот же JSON-формат:

{
  "rules": [
    {
      "path": "force-api/**/*.java",
      "rule": "Все новые методы должны проверять обязательные параметры на null"
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Проверять SQL на риски инъекций, ошибки в параметрах и незакрытые теги"
    }
  ]
}

• path поддерживает рекурсивное сопоставление ** и расширение фигурных скобок {java,kt}.
• Внутри каждого уровня правила проверяются в порядке объявления — побеждает первое совпадение.
• Если файл правил не существует, он молча пропускается.

Фильтрация путей

Файлы правил также поддерживают поля include и exclude, управляющие тем, какие файлы попадают в область ревью:

{
  "rules": [
    {"path": "**/*.java", "rule": "Проверять null-безопасность"}
  ],
  "include": ["src/main/**/*.java", "lib/**/*.kt"],
  "exclude": ["**/generated/**", "vendor/**"]
}

Приоритет решений фильтра (от высшего к низшему):

Шаг	Условие	Результат
1	Файл бинарный	Исключён
2	Путь совпадает с пользовательским паттерном exclude	Исключён
3	Расширение файла не входит в список поддерживаемых	Исключён
4	include настроен и путь совпадает	В ревью (шаг 5 пропускается)
5	Путь совпадает со встроенным паттерном исключения по умолчанию (тестовые файлы и т. п.)	Исключён
6	Ничего из перечисленного	В ревью

Как это работает:

• include и exclude следуют той же цепочке приоритетов, что и правила ревью (--rule > конфиг проекта > глобальный конфиг). Действует целиком самый приоритетный уровень, на котором include/exclude настроены — паттерны разных уровней не объединяются.
• exclude всегда сильнее include — файл, совпавший с обоими, исключается.
• include работает как обход встроенных паттернов исключения по умолчанию (например, тестовых файлов), а не как эксклюзивный allowlist: файлы, не совпавшие ни с одним паттерном include, всё равно обычным образом проходят проверки фильтра по умолчанию.
• Синтаксис паттернов: поддерживаются рекурсивное сопоставление **, односегментное * и расширение фигурных скобок {a,b}. Сопоставление регистронезависимое.

Встроенные паттерны исключения по умолчанию (отфильтровывают тестовые файлы и т. п. — можно переопределить через include):

**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
**/src/test/java/**/*.java, **/src/test/**/*.kt,
**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**

Справочник по конфигурации

Файл конфигурации: ~/.opencodereview/config.json

Ключ	Тип	Пример
provider	string	anthropic | openai | dashscope | deepseek | z-ai
providers.<name>.api_key	string	API-ключ провайдера
providers.<name>.url	string	Переопределение base URL провайдера
providers.<name>.protocol	string	anthropic | openai
providers.<name>.model	string	Имя модели провайдера
providers.<name>.models	array	Необязательный список моделей для интерактивного выбора
providers.<name>.auth_header	string	x-api-key | authorization
custom_providers.<name>.*	—	Те же поля, что и providers.<name>.*, включая необязательное models
llm.url	string	https://api.openai.com/v1/chat/completions
llm.auth_token	string	sk-xxxxxxx
llm.auth_header	string	Только для Anthropic: x-api-key | authorization
llm.model	string	claude-opus-4-6
llm.use_anthropic	boolean	true | false
language	string	Любое название языка, например English, Chinese (по умолчанию: English)
telemetry.enabled	boolean	true | false
telemetry.exporter	string	console | otlp
telemetry.otlp_endpoint	string	Адрес OTLP-коллектора
telemetry.content_logging	boolean	Включать промпты в телеметрию

Переменные окружения имеют приоритет над файлом конфигурации.

Переменные окружения

Переменная	Назначение
OCR_LLM_URL	URL эндпоинта LLM API
OCR_LLM_TOKEN	API-ключ / токен авторизации
OCR_LLM_AUTH_HEADER	Заголовок авторизации Anthropic (x-api-key или authorization)
OCR_LLM_MODEL	Имя модели
OCR_USE_ANTHROPIC	true = Anthropic, false = OpenAI

Телеметрия

Интеграция с OpenTelemetry для наблюдаемости (спаны, метрики). По умолчанию выключена.

ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp
ocr config set telemetry.otlp_endpoint localhost:4317

Установите telemetry.content_logging, чтобы включать промпты и ответы LLM в экспортируемые данные.

Участие в разработке

В CONTRIBUTING.ru-RU.md описаны настройка окружения разработки, рекомендации по коду и порядок отправки pull request'ов.

История звёзд

Лицензия

Apache-2.0 — Copyright 2026 Alibaba