From 9c0c6f23933146488c8cb4b84c3511885019da85 Mon Sep 17 00:00:00 2001 From: Fedor Date: Fri, 12 Jun 2026 06:49:04 +0300 Subject: [PATCH] docs: add Russian translations for README and CONTRIBUTING (#101) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add README.ru-RU.md and CONTRIBUTING.ru-RU.md following the existing localization pattern (zh-CN, ja-JP, ko-KR), and add the Русский link to the language switcher line in all README and CONTRIBUTING variants. Also add the previously missing 한국어 link to the CONTRIBUTING.zh-CN.md and CONTRIBUTING.ja-JP.md switchers. Closes #100 --- CONTRIBUTING.ja-JP.md | 2 +- CONTRIBUTING.ko-KR.md | 2 +- CONTRIBUTING.md | 6 +- CONTRIBUTING.ru-RU.md | 224 ++++++++++++++++++++ CONTRIBUTING.zh-CN.md | 2 +- README.ja-JP.md | 2 +- README.ko-KR.md | 2 +- README.md | 2 +- README.ru-RU.md | 476 ++++++++++++++++++++++++++++++++++++++++++ README.zh-CN.md | 2 +- 10 files changed, 711 insertions(+), 9 deletions(-) create mode 100644 CONTRIBUTING.ru-RU.md create mode 100644 README.ru-RU.md diff --git a/CONTRIBUTING.ja-JP.md b/CONTRIBUTING.ja-JP.md index 36559e0..ca6c8b0 100644 --- a/CONTRIBUTING.ja-JP.md +++ b/CONTRIBUTING.ja-JP.md @@ -2,7 +2,7 @@ OpenCodeReviewへのコントリビューションに興味を持っていただきありがとうございます！タイポの修正、バグ報告、新機能の実装など、あらゆる貢献が重要です。 -[English Version](CONTRIBUTING.md) | [简体中文版](CONTRIBUTING.zh-CN.md) +[English Version](CONTRIBUTING.md) | [简体中文版](CONTRIBUTING.zh-CN.md) | [한국어](CONTRIBUTING.ko-KR.md) | [Русский](CONTRIBUTING.ru-RU.md) ## 行動規範 diff --git a/CONTRIBUTING.ko-KR.md b/CONTRIBUTING.ko-KR.md index a1a057a..1f69ee2 100644 --- a/CONTRIBUTING.ko-KR.md +++ b/CONTRIBUTING.ko-KR.md @@ -2,7 +2,7 @@ OpenCodeReview에 기여해 주셔서 감사합니다. 오타 수정, bug report, 새 기능 구현 등 모든 기여는 프로젝트에 도움이 됩니다. -[English](CONTRIBUTING.md) | [简体中文版](CONTRIBUTING.zh-CN.md) | [日本語版](CONTRIBUTING.ja-JP.md) | 한국어 +[English](CONTRIBUTING.md) | [简体中文版](CONTRIBUTING.zh-CN.md) | [日本語版](CONTRIBUTING.ja-JP.md) | 한국어 | [Русский](CONTRIBUTING.ru-RU.md) ## Code of Conduct diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77591f6..e042ef4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thank you for your interest in contributing to OpenCodeReview! Every contribution matters — whether it's fixing a typo, reporting a bug, or implementing a new feature. -[简体中文版](CONTRIBUTING.zh-CN.md) | [日本語版](CONTRIBUTING.ja-JP.md) | [한국어](CONTRIBUTING.ko-KR.md) +[简体中文版](CONTRIBUTING.zh-CN.md) | [日本語版](CONTRIBUTING.ja-JP.md) | [한국어](CONTRIBUTING.ko-KR.md) | [Русский](CONTRIBUTING.ru-RU.md) ## Code of Conduct @@ -135,7 +135,7 @@ Documentation is a crucial part of OpenCodeReview. We welcome improvements to RE - Clarifying confusing explanations or adding missing context - Adding usage examples for commands or configuration options - Updating outdated content (e.g., after a feature change) -- Translating or improving localized documentation (`README.zh-CN.md`, `README.ja-JP.md`, `README.ko-KR.md`, `CONTRIBUTING.zh-CN.md`, `CONTRIBUTING.ja-JP.md`, `CONTRIBUTING.ko-KR.md`) +- Translating or improving localized documentation (`README.zh-CN.md`, `README.ja-JP.md`, `README.ko-KR.md`, `README.ru-RU.md`, `CONTRIBUTING.zh-CN.md`, `CONTRIBUTING.ja-JP.md`, `CONTRIBUTING.ko-KR.md`, `CONTRIBUTING.ru-RU.md`) ### Documentation Workflow @@ -151,10 +151,12 @@ Documentation is a crucial part of OpenCodeReview. We welcome improvements to RE | `README.zh-CN.md` | Chinese translation | | `README.ja-JP.md` | Japanese translation | | `README.ko-KR.md` | Korean translation | +| `README.ru-RU.md` | Russian translation | | `CONTRIBUTING.md` | Contribution guide (English) | | `CONTRIBUTING.zh-CN.md` | Contribution guide (Chinese) | | `CONTRIBUTING.ja-JP.md` | Contribution guide (Japanese) | | `CONTRIBUTING.ko-KR.md` | Contribution guide (Korean) | +| `CONTRIBUTING.ru-RU.md` | Contribution guide (Russian) | ## Submitting Changes diff --git a/CONTRIBUTING.ru-RU.md b/CONTRIBUTING.ru-RU.md new file mode 100644 index 0000000..a1b6f59 --- /dev/null +++ b/CONTRIBUTING.ru-RU.md @@ -0,0 +1,224 @@ +# Участие в разработке OpenCodeReview + +Спасибо за интерес к развитию OpenCodeReview! Важен любой вклад — будь то исправленная опечатка, сообщение о баге или новая функциональность. + +[English](CONTRIBUTING.md) | [简体中文版](CONTRIBUTING.zh-CN.md) | [日本語版](CONTRIBUTING.ja-JP.md) | [한국어](CONTRIBUTING.ko-KR.md) | Русский + +## Кодекс поведения + +Участвуя в этом проекте, вы соглашаетесь поддерживать уважительную и инклюзивную атмосферу. Пожалуйста, будьте доброжелательны и конструктивны в любом взаимодействии. + +## Как можно помочь + +Помимо написания кода, есть много способов внести вклад: + +- **Сообщайте о багах** — нашли поломку? Заведите issue с шагами воспроизведения. +- **Предлагайте улучшения** — есть идея? Начните обсуждение в [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions/categories/ideas) или заведите issue [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml). +- **Улучшайте документацию** — исправляйте опечатки, проясняйте формулировки, добавляйте примеры. Чтобы сообщить о проблеме, можно также завести [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml). +- **Ревьюйте pull request'ы** — помогайте нам проверять код других контрибьюторов. +- **Пишите код** — исправляйте баги, добавляйте функциональность, улучшайте производительность. + +## С чего начать + +### Требования + +- [Go 1.25+](https://go.dev/dl/) +- [Git](https://git-scm.com/) +- [Make](https://www.gnu.org/software/make/) + +### Настройка + +```bash +# 1. Сделайте форк репозитория на GitHub + +# 2. Склонируйте свой форк +git clone https://github.com//open-code-review.git +cd open-code-review + +# 3. Добавьте remote upstream (для синхронизации с основным репозиторием) +git remote add upstream https://github.com/alibaba/open-code-review.git + +# 4. Соберите проект +make build + +# 5. Запустите тесты +make test +``` + +Если всё прошло успешно — вы готовы контрибьютить. + +> **Примечание:** remote `upstream` для контрибьюторов доступен только на чтение — он используется, чтобы подтягивать свежие изменения из основного репозитория. Пушить напрямую в upstream нельзя. Все изменения отправляются в ваш форк (`origin`) и подаются через Pull Request. + +## Процесс разработки + +### Ветки + +Создайте feature-ветку от `main`: + +```bash +git checkout main +git pull upstream main +git checkout -b feat/your-feature-name +``` + +Используйте префиксы, обозначающие тип изменения: + +| Префикс | Назначение | +| ----------- | --------------------------------------- | +| `feat/` | Новая функциональность | +| `fix/` | Исправление бага | +| `docs/` | Только документация | +| `refactor/` | Рефакторинг (без изменения поведения) | +| `test/` | Добавление или обновление тестов | +| `chore/` | Сборка, CI или инструментарий | + +### Сообщения коммитов + +Следуйте формату [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): <краткое описание> + +[необязательное тело] +``` + +Примеры: + +``` +feat(agent): add support for custom tool definitions +fix(llm): handle timeout errors in Anthropic API calls +docs(README): update configuration examples +``` + +### Качество кода + +Перед отправкой изменений убедитесь, что они проходят все проверки: + +```bash +# Форматирование и линт (стандартный инструментарий Go) +go fmt ./... +go vet ./... + +# Тесты с детектором гонок +make test + +# Успешная сборка +make build +``` + +### Структура проекта + +``` +├── cmd/opencodereview/ # Точка входа CLI +├── internal/ +│ ├── agent/ # Логика ревью-агента +│ ├── config/ # Управление конфигурацией +│ ├── diff/ # Разбор git-диффов +│ ├── llm/ # Клиент LLM API (Anthropic и OpenAI) +│ ├── model/ # Модели данных +│ ├── session/ # Управление сессиями ревью +│ ├── tool/ # Встроенные инструменты (file_read, code_search и др.) +│ ├── telemetry/ # Интеграция с OpenTelemetry +│ └── viewer/ # WebUI-просмотрщик сессий +├── pages/ # Фронтенд WebUI +├── scripts/ # Скрипты сборки и установки +└── bin/ # NPM-обёртка +``` + +## Вклад в документацию + +Документация — важнейшая часть OpenCodeReview. Мы приветствуем улучшения README-файлов, комментариев в коде, примеров конфигурации и любых текстов, обращённых к пользователю. + +### Что считается вкладом в документацию + +- Исправление опечаток, грамматических ошибок и битых ссылок +- Прояснение запутанных объяснений и добавление недостающего контекста +- Добавление примеров использования команд и параметров конфигурации +- Обновление устаревшего содержимого (например, после изменения функциональности) +- Перевод и улучшение локализованной документации (`README.zh-CN.md`, `README.ja-JP.md`, `README.ko-KR.md`, `README.ru-RU.md`, `CONTRIBUTING.zh-CN.md`, `CONTRIBUTING.ja-JP.md`, `CONTRIBUTING.ko-KR.md`, `CONTRIBUTING.ru-RU.md`) + +### Процесс работы с документацией + +1. Если вы заметили проблему, но не планируете исправлять её сами, заведите [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml). +2. Если хотите исправить сами — сделайте форк, внесите изменения и подайте PR с префиксом ветки `docs/` (например, `docs/fix-config-example`). +3. PR, затрагивающие только документацию, не требуют изменений в тестах, но, пожалуйста, проверяйте точность всех приводимых команд и фрагментов кода. + +### Файлы документации + +| Файл | Назначение | +| ----------------------- | ------------------------------------------- | +| `README.md` | Основная документация проекта (английский) | +| `README.zh-CN.md` | Китайский перевод | +| `README.ja-JP.md` | Японский перевод | +| `README.ko-KR.md` | Корейский перевод | +| `README.ru-RU.md` | Русский перевод | +| `CONTRIBUTING.md` | Руководство контрибьютора (английский) | +| `CONTRIBUTING.zh-CN.md` | Руководство контрибьютора (китайский) | +| `CONTRIBUTING.ja-JP.md` | Руководство контрибьютора (японский) | +| `CONTRIBUTING.ko-KR.md` | Руководство контрибьютора (корейский) | +| `CONTRIBUTING.ru-RU.md` | Руководство контрибьютора (русский) | + +## Отправка изменений + +### Заведение issue + +Прежде чем браться за существенное изменение, пожалуйста, сначала заведите issue и обсудите подход. Это предотвращает дублирование работы и гарантирует, что ваш вклад согласуется с направлением развития проекта. + +Сообщая о баге, укажите: + +1. Версию OpenCodeReview (`ocr version`) +2. ОС и архитектуру +3. Шаги воспроизведения +4. Ожидаемое и фактическое поведение +5. Релевантные логи или сообщения об ошибках + +### Процесс Pull Request + +1. **Держите PR сфокусированным** — одно логическое изменение на PR. Несколько независимых изменений лучше подать отдельными PR. +2. **Пишите тесты** — добавляйте или обновляйте тесты при любых изменениях поведения. +3. **Обновляйте документацию** — если изменение затрагивает видимое пользователю поведение, обновите соответствующую документацию. +4. **Подпишите CLA** — прежде чем PR может быть принят, все контрибьюторы должны подписать Contributor License Agreement (см. ниже). +5. **Заполните шаблон PR** — опишите, что делает ваше изменение и зачем оно нужно. + +### Формат заголовка PR + +Используйте тот же формат Conventional Commits, что и для сообщений коммитов: + +``` +feat(agent): add support for custom tool definitions +``` + +### Процесс ревью + +- Мейнтейнер посмотрит ваш PR — обычно в течение нескольких рабочих дней. +- Мы можем попросить внести изменения — это нормальная совместная работа, а не противостояние. +- После одобрения мейнтейнер смёржит ваш PR. + +## Лицензионное соглашение контрибьютора (CLA) + +Прежде чем мы сможем принять ваш вклад, необходимо подписать Alibaba Open Source Contributor License Agreement. Это гарантирует, что проект может распространяться на условиях своей лицензии. + +Когда вы откроете свой первый PR, CLA-бот оставит комментарий с инструкциями. Просто перейдите по ссылке и подпишите соглашение электронно — это занимает минуту. + +## Новичкам + +Впервые в проекте? Ищите issues с метками: + +- [`good first issue`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue) — небольшие, хорошо очерченные задачи, идеальные для старта. +- [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted) — задачи, где мы будем рады помощи сообщества. + +С чего удобно начать: + +- Улучшение сообщений об ошибках и вывода CLI +- Написание тестов для непокрытых участков кода +- Улучшение документации + +## Сообщество + +- **Сообщения о багах** — [GitHub Issues](https://github.com/alibaba/open-code-review/issues) +- **Предложения функциональности** — [GitHub Discussions (Ideas)](https://github.com/alibaba/open-code-review/discussions/categories/ideas) или issue [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml) +- **Вопросы и помощь** — если у вас есть вопросы об использовании OpenCodeReview, задавайте их в [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions) + +## Лицензия + +Внося вклад в OpenCodeReview, вы соглашаетесь с тем, что ваш вклад будет лицензирован на условиях [Apache License 2.0](LICENSE). diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md index 7cd25de..0abd432 100644 --- a/CONTRIBUTING.zh-CN.md +++ b/CONTRIBUTING.zh-CN.md @@ -2,7 +2,7 @@ 感谢你对 OpenCodeReview 的关注！无论是修复拼写错误、报告 Bug，还是实现新功能，每一份贡献都很有价值。 -[English version](CONTRIBUTING.md) | [日本語版](CONTRIBUTING.ja-JP.md) +[English version](CONTRIBUTING.md) | [日本語版](CONTRIBUTING.ja-JP.md) | [한국어](CONTRIBUTING.ko-KR.md) | [Русский](CONTRIBUTING.ru-RU.md) ## 行为准则 diff --git a/README.ja-JP.md b/README.ja-JP.md index 599f1e0..159a1ff 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -11,7 +11,7 @@ License

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

--- diff --git a/README.ko-KR.md b/README.ko-KR.md index 3376fc7..ef85b01 100644 --- a/README.ko-KR.md +++ b/README.ko-KR.md @@ -11,7 +11,7 @@ License

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

--- diff --git a/README.md b/README.md index fcac1b5..56af8e8 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ License

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

--- diff --git a/README.ru-RU.md b/README.ru-RU.md new file mode 100644 index 0000000..3e4e9d5 --- /dev/null +++ b/README.ru-RU.md @@ -0,0 +1,476 @@ +

+ + OpenCodeReview logo + +

+

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

+

+ npm + Build status + Go Report Card + License +

+

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

+ +--- + +## Что такое Open Code Review? + +Open Code Review — это CLI-инструмент для код-ревью на основе ИИ. Он появился как внутренний официальный ИИ-ассистент код-ревью Alibaba Group: за последние два года им воспользовались десятки тысяч разработчиков, и он выявил миллионы дефектов в коде. После тщательной проверки в огромных масштабах мы превратили его в open-source-проект для сообщества. Чтобы начать работу, достаточно настроить эндпоинт модели. + +Инструмент читает git-диффы, отправляет изменённые файлы настраиваемой LLM через агента с поддержкой вызова инструментов (tool use) и генерирует структурированные ревью-комментарии с точностью до строки. Агент может читать полное содержимое файлов, искать по кодовой базе, заглядывать в другие изменённые файлы за контекстом и выполнять глубокое ревью — а не только давать поверхностные замечания по диффу. + +![Highlights](imgs/highlights-en.png) + +## Почему Open Code Review? + +### Проблема агентов общего назначения + +Если вы использовали для код-ревью агентов общего назначения, например Claude Code со Skills, вы наверняка сталкивались с этими болевыми точками: + +- **Неполное покрытие** — на крупных ченджсетах агенты склонны «срезать углы»: выборочно проверяют часть файлов и пропускают остальные. +- **Дрейф позиций** — найденные проблемы часто не совпадают с реальным местом в коде: номера строк и ссылки на файлы «уезжают» от цели. +- **Нестабильное качество** — Skills, управляемые естественным языком, трудно отлаживать, и качество ревью заметно колеблется при небольших изменениях промпта. + +Первопричина: чисто языковая архитектура не накладывает жёстких ограничений на процесс ревью. + +### Ключевая идея: детерминированная инженерия × агент + +Ключевая философия Open Code Review — сочетать детерминированную инженерию и агента так, чтобы каждый занимался тем, что у него получается лучше всего. + +**Детерминированная инженерия — жёсткие гарантии** + +Для тех шагов ревью, где *нельзя ошибаться*, корректность гарантирует инженерная логика, а не языковая модель: + +- **Точный отбор файлов** — точно определяет, какие файлы нуждаются в ревью, а какие следует отфильтровать, гарантируя, что ни одно важное изменение не будет упущено. +- **Умный бандлинг файлов** — группирует связанные файлы в одну единицу ревью (например, `message_en.properties` и `message_zh.properties` объединяются вместе). Каждый бандл выполняется как суб-агент с изолированным контекстом — стратегия «разделяй и властвуй», которая сохраняет стабильность на очень больших ченджсетах и естественным образом поддерживает конкурентное ревью. +- **Тонкий матчинг правил** — сопоставляет правила ревью с характеристиками каждого файла, удерживая внимание модели сфокусированным и устраняя информационный шум у самого источника. По сравнению с чисто языковым управлением правилами матчинг правил на основе шаблонизатора стабильнее и предсказуемее. +- **Внешние модули позиционирования и рефлексии** — независимые модули позиционирования комментариев и рефлексии над комментариями системно повышают точность как расположения, так и содержания замечаний ИИ. + +**Агент — динамические решения** + +Сильные стороны агента сосредоточены там, где они важнее всего, — в динамических решениях и динамическом доборе контекста: + +- **Промпты, заточенные под сценарий** — шаблоны промптов, глубоко оптимизированные под код-ревью: выше качество при меньшем расходе токенов. +- **Набор инструментов, заточенный под сценарий** — выведен из глубокого анализа трейсов вызовов инструментов на больших продакшен-данных, включая распределение частоты вызовов, долю повторных вызовов каждого инструмента и влияние новых инструментов на всю цепочку вызовов. В результате получился специализированный набор инструментов, который для код-ревью стабильнее и предсказуемее, чем универсальный агентский тулкит. + +## Как использовать + +### CLI + +#### Установка + +**Через NPM (рекомендуется)** + +```bash +npm install -g @alibaba-group/open-code-review +``` + +После установки команда `ocr` доступна глобально. + +**Из GitHub Release** + +Скачайте свежий бинарный файл со страницы [GitHub Releases](https://github.com/alibaba/open-code-review/releases): + +```bash +# 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 +``` + +**Из исходников** + +```bash +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.** + +```bash +# Вариант A: настройка через CLI +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 + +# Вариант B: переменные окружения (наивысший приоритет) +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 +``` + +Конфигурация хранится в `~/.opencodereview/config.json`. + +**`auth_header` (необязательно):** определяет, в каком HTTP-заголовке передаётся API-ключ при работе с Anthropic. Если не задан, по умолчанию используется `authorization` (Bearer-токен). Если у вас стандартный API-ключ вида `sk-ant-*`, необходимо установить значение `x-api-key`: + +```bash +ocr config set llm.auth_header x-api-key +# или +export OCR_LLM_AUTH_HEADER=x-api-key +``` + +Поддерживаемые значения: `x-api-key`, `authorization` (алиас: `bearer`). Прочие значения отклоняются с ошибкой. + +Инструмент также совместим с переменными окружения Claude Code (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) и разбирает `~/.zshrc` / `~/.bashrc` в поисках соответствующих export'ов. + +> **Примечание для пользователей CC-Switch**: если вы используете [CC-Switch](https://github.com/farion1231/cc-switch) с включённым [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=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. Проверьте подключение** + +```bash +ocr llm test +``` + +**3. Запустите ревью** + +```bash +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`: + +```bash +npx skills add alibaba/open-code-review --skill open-code-review +``` + +Это установит скилл `open-code-review` из [реестра скиллов](skills/open-code-review/SKILL.md), который объясняет вашему кодинг-агенту, как вызывать `ocr` для код-ревью, классифицировать найденные проблемы по приоритету и при необходимости применять исправления. + +#### Вариант 2: установка как плагин Claude Code + +Для [Claude Code](https://docs.anthropic.com/en/docs/claude-code) установите плагин с командой, выполнив в Claude Code: + +```bash +/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 из этого репозитория: + +```bash +codex plugin marketplace add alibaba/open-code-review +codex +/plugins +``` + +Для локального чекаута или форка: + +```bash +codex plugin marketplace add . +codex +/plugins +``` + +Установите и включите `Open Code Review`, затем начните новый тред Codex и вызывайте плагин явно: + +```text +@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: + +```bash +ocr review --audience agent +``` + +Эта интеграция не меняет внутренний LLM-бэкенд OCR и не требует настройки эндпоинта OpenAI Responses API для Codex. Самому OCR по-прежнему нужен установленный и настроенный CLI `ocr`, как описано в разделе про настройку CLI. + +Руководство на корейском: [`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md) + +#### Вариант 4: просто скопировать файл команды + +Для быстрой настройки без пакетных менеджеров достаточно скопировать файл команды, чтобы использовать slash-команду `/open-code-review` в Claude Code. + +**На уровне проекта** (общий для команды через git): + +```bash +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 +``` + +**На уровне пользователя** (личное глобальное использование во всех проектах): + +```bash +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: + +```bash +ocr review \ + --from "origin/main" \ + --to "" \ + --format json +``` + +Флаг `--from` принимает в качестве базы ref ветки (например, `origin/main`) или SHA коммита, а `--to` — SHA коммита или ref ветки в качестве head. В CI-окружениях для `--to` рекомендуется использовать SHA коммита: это корректно обрабатывает PR/MR из форков, у которых исходная ветка отсутствует в remote `origin`. + +Флаг `--format json` выводит машиночитаемый результат, удобный для разбора в CI-скриптах. + +Примеры интеграции — в каталоге [`examples/`](./examples/): + +- [`github_actions/`](./examples/github_actions/) — пример интеграции с GitHub Actions +- [`gitlab_ci/`](./examples/gitlab_ci/) — пример интеграции с GitLab CI + +## Команды + +| Команда | Алиас | Описание | +|---------|-------|----------| +| `ocr review` | `ocr r` | Запустить код-ревью | +| `ocr rules check ` | — | Показать, какое правило ревью применяется к пути файла | +| `ocr config set ` | — | Установить значения конфигурации | +| `ocr llm test` | — | Проверить подключение к 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` автоматически заполняется из сообщения коммита | +| `--rule` | — | — | Путь к пользовательским JSON-правилам ревью | +| `--max-tools` | — | встроенное | Максимум раундов вызова инструментов на файл; действует, только если больше значения шаблона по умолчанию | +| `--max-git-procs` | — | встроенное | Максимум одновременных git-подпроцессов | +| `--tools` | — | — | Путь к пользовательскому JSON-конфигу инструментов | + +## Примеры + +```bash +# Показать, какие файлы попадут в ревью (без вызовов 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 --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` (через запятую): + +```bash +OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 +``` + +Это блокирует атаки DNS rebinding на локальный viewer. + +## Правила ревью + +OCR разрешает правила ревью по цепочке приоритетов из четырёх уровней. На каждом уровне действует принцип «первое совпадение побеждает»: если путь файла совпал с паттерном, используется это правило; иначе поиск продолжается на следующем уровне. + +| Приоритет | Источник | Путь | Описание | +|-----------|----------|------|----------| +| 1 (высший) | Флаг `--rule` | Путь, указанный пользователем | Явное переопределение из CLI | +| 2 | Конфиг проекта | `/.opencodereview/rule.json` | Правила уровня проекта, можно коммитить в git | +| 3 | Глобальный конфиг | `~/.opencodereview/rule.json` | Личные настройки пользователя | +| 4 (низший) | Системные по умолчанию | Встроенный `system_rules.json` | Встроенные правила для распространённых языков и типов файлов | + +### Формат файла правил + +Уровни 1–3 используют один и тот же JSON-формат: + +```json +{ + "rules": [ + { + "path": "force-api/**/*.java", + "rule": "Все новые методы должны проверять обязательные параметры на null" + }, + { + "path": "**/*mapper*.xml", + "rule": "Проверять SQL на риски инъекций, ошибки в параметрах и незакрытые теги" + } + ] +} +``` + +- `path` поддерживает рекурсивное сопоставление `**` и расширение фигурных скобок `{java,kt}`. +- Внутри каждого уровня правила проверяются в порядке объявления — побеждает первое совпадение. +- Если файл правил не существует, он молча пропускается. + +### Фильтрация путей + +Файлы правил также поддерживают поля `include` и `exclude`, управляющие тем, какие файлы попадают в область ревью: + +```json +{ + "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` + +| Ключ | Тип | Пример | +|------|-----|--------| +| `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` (по умолчанию: Chinese) | +| `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 для наблюдаемости (спаны, метрики). По умолчанию выключена. + +```bash +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](CONTRIBUTING.ru-RU.md) описаны настройка окружения разработки, рекомендации по коду и порядок отправки pull request'ов. + +## История звёзд + +[![Star History Chart](https://api.star-history.com/svg?repos=alibaba/open-code-review&type=Date)](https://star-history.com/#alibaba/open-code-review&Date) + +## Лицензия + +[Apache-2.0](LICENSE) — Copyright 2026 Alibaba diff --git a/README.zh-CN.md b/README.zh-CN.md index 3fdde23..d82715a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -11,7 +11,7 @@ License

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

---