open-code-review/README.ru-RU.md at v1.3.16

mirror of https://github.com/alibaba/open-code-review.git synced 2026-07-09 17:28:58 +00:00

kite 9f06912755 fix: apply language directive even when config file is missing

ApplyLanguage was only called when the config file existed, so without
~/.opencodereview/config.json no language instruction was injected and
the LLM picked its own language. Now ApplyLanguage is called
unconditionally, defaulting to English via resolveLang("").

Update all README translations to reflect the corrected default
(English) and clarify that any language name is accepted.

2026-06-17 10:56:35 +08:00

32 KiB

Raw Permalink Blame History

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

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

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

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

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

Почему 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'ов.

32 KiB

Raw Permalink Blame History

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

Почему Open Code Review?

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

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

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

CLI

Установка

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

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

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

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

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

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

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

Команды

Флаги `ocr review`

Примеры

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

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

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

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

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

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

Телеметрия

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

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

Лицензия

32 KiB Raw Permalink Blame History Unescape Escape

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

Почему Open Code Review?

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

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

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

CLI

Установка

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

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

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

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

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

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

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

Команды

Флаги ocr review

Примеры

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

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

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

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

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

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

Телеметрия

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

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

Лицензия

32 KiB

Raw Permalink Blame History

Флаги `ocr review`