Metadata-Version: 2.5
Name: aiw-ru
Version: 2.0.0rc1
Summary: Приметы ИИ-стиля в русском тексте: канцелярит, кальки, шаблонная структура; оценка по фрагментам в духе «Антиплагиата»
Project-URL: Homepage, https://github.com/ormeilu/avoid-ai-writing-russian
Project-URL: Repository, https://github.com/ormeilu/avoid-ai-writing-russian
Project-URL: Changelog, https://github.com/ormeilu/avoid-ai-writing-russian/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/ormeilu/avoid-ai-writing-russian/issues
Author-email: Ilya Lubenets <lubenets.ilya.igorevich@gmail.com>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE.md
Keywords: ai-detection,ai-writing,antiplagiat,claude-code,editing,russian,style,канцелярит
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.13.5
Requires-Dist: regex>=2026.9.10
Requires-Dist: rich>=15.0.0
Provides-Extra: ml
Requires-Dist: huggingface-hub>=1.33.0; extra == 'ml'
Requires-Dist: lightgbm>=4.7.0; extra == 'ml'
Description-Content-Type: text/markdown

# avoid-ai-writing-russian

[![CI](https://github.com/ormeilu/avoid-ai-writing-russian/actions/workflows/ci.yml/badge.svg)](https://github.com/ormeilu/avoid-ai-writing-russian/actions/workflows/ci.yml)
[![Выпуск](https://img.shields.io/github/v/release/ormeilu/avoid-ai-writing-russian?label=выпуск)](https://github.com/ormeilu/avoid-ai-writing-russian/releases)
[![Лицензия: MIT](https://img.shields.io/badge/лицензия-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/aiw-ru?label=PyPI)](https://pypi.org/project/aiw-ru/)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776ab?logo=python&logoColor=white)](pyproject.toml)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Модель на Hugging Face](https://img.shields.io/badge/Hugging%20Face-russian--ai--text--detector--lightgbm-ffd21e?logo=huggingface)](https://huggingface.co/toiletsandpaper/russian-ai-text-detector-lightgbm)
[![prek](https://img.shields.io/badge/хуки-prek-orange)](https://prek.j178.dev)
[![Апстрим](https://img.shields.io/badge/апстрим-avoid--ai--writing-555)](https://github.com/conorbronsdon/avoid-ai-writing)

<p align="center">
  <img src="docs/demo.gif" alt="Детектор aiw-ru находит 14 примет ИИ-стиля в рекламном абзаце, ставит правке 0/100, проверяет сохранность чисел и оценивает главу по фрагментам в духе «Антиплагиата»" width="800">
</p>

Скилл для ИИ-агентов (Claude Code, Codex, Cursor и других), который находит и убирает из русских текстов приметы машинной генерации: канцелярит, кальки с английского, «не просто X, а Y», тире-связки, одинаковый ритм предложений. К нему прилагается детектор на Python (`aiw-ru`) и под-скилл `antiplagiat`, который оценивает текст по фрагментам в духе модуля ИИ-детекции системы «Антиплагиат».

Это русская адаптация [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) Конора Бронсдона. Устройство скилла взято оттуда, каталог примет переписан под русский язык, детектор написан заново. Подробности в разделе [«Благодарности»](#благодарности).

## Содержание

- [Зачем](#зачем)
- [Пример](#пример)
- [Установка](#установка)
- [Как пользоваться](#как-пользоваться)
- [Под-скилл antiplagiat](#под-скилл-antiplagiat)
- [Детектор](#детектор)
- [Что ловит каталог](#что-ловит-каталог)
- [Ограничения](#ограничения)
- [Разработка](#разработка)
- [Выпуски](#выпуски)
- [Как сослаться](#как-сослаться)
- [Благодарности](#благодарности)
- [Лицензия](#лицензия)

## Зачем

Английские «очеловечиватели» на русском почти бесполезны. Они ищут *delve* и *tapestry*, а русский текст модели выдаёт себя другим: «является», «осуществляется», «в рамках данной работы», «играет ключевую роль», «на ежедневной основе», цепочками вроде «обеспечение повышения эффективности проведения мониторинга» и прямыми кавычками там, где нужны «ёлочки». Половина этого — канцелярит, которым люди писали задолго до нейросетей; модели выучили его из госдокументов и рефератов и воспроизводят с удвоенной частотой. Другая половина — синтаксис, протащенный из английского черновика, на котором модель «думала».

Скилл помогает двум группам:

- тем, кто хочет меньше ИИ-стиля в своих текстах: статьях, документации, постах, письмах;
- тем, чей текст пойдёт на проверку в «Антиплагиат» и кому не нужны ложные срабатывания модуля ИИ-детекции на собственном тексте.

## Пример

До (типичный ответ модели на просьбу написать абзац про ИИ в медицине):

> В современном мире искусственный интеллект играет ключевую роль в развитии здравоохранения. Данная технология открывает новые возможности для диагностики и лечения заболеваний. Стоит отметить, что внедрение ИИ осуществляется в рамках комплексного подхода к цифровой трансформации отрасли. Кроме того, нейросетевые модели позволяют значительно повысить точность диагностики. Исследования показывают, что такие системы обеспечивают высокую эффективность при анализе медицинских изображений.

Детектор: 98/100, «сильный ИИ-стиль». В пяти предложениях он нашёл размытую ссылку на авторитет («Исследования показывают»), пять слов-маркеров, две оценки без чисел, пять случаев канцелярита, шаблонный переход и скопление слов второго уровня.

После правки скиллом:

> ИИ в медицине пока применяют в основном для анализа изображений и помощи в диагностике. Насколько такие системы точнее врача, в исходном тексте не сказано. Нужны цифры и ссылка на исследование, иначе утверждение не проверить.

Проверка: один проход. Скилл убрал разбег, штампы и пустые оценки. Число и источник он не выдумал, а пометил как пробел: исходник их не давал. Это правило «никогда не добавляй» из исходного проекта. Для научного текста оно важнее всего остального.

## Установка

### Claude Code: плагин

```bash
claude plugin marketplace add ormeilu/avoid-ai-writing-russian
claude plugin install avoid-ai-writing-russian@avoid-ai-writing-russian
```

Плагин ставит оба скилла, `avoid-ai-writing-russian` и `antiplagiat`, вместе с детектором. Детектору нужен [uv](https://docs.astral.sh/uv/getting-started/installation/).

### Claude Code, Codex и другие агенты: папка скилла

Клонируйте репозиторий и скопируйте папки скиллов туда, где агент их ищет. Детектор лежит в корне репозитория, а скиллы зовут его командой `uv run --project ../.. aiw-ru …`, поэтому удобнее ссылка, а не копия:

```bash
git clone https://github.com/ormeilu/avoid-ai-writing-russian.git ~/src/avoid-ai-writing-russian
```

```bash
ln -s ~/src/avoid-ai-writing-russian/skills/avoid-ai-writing-russian ~/.claude/skills/avoid-ai-writing-russian
```

```bash
ln -s ~/src/avoid-ai-writing-russian/skills/antiplagiat ~/.claude/skills/antiplagiat
```

Для Codex используйте `~/.codex/skills/` или `~/.agents/skills/`, для Cursor — правила проекта. Агентам без поддержки SKILL.md можно передать текст `SKILL.md` и `references/patterns.md` как инструкцию.

### Детектор

Скиллам нужен [uv](https://docs.astral.sh/uv/getting-started/installation/): при первом запуске он сам поставит Python 3.12 или новее и зависимости детектора (regex, rich, pydantic). Без uv скилл работает, но проверки будут только модельными, и он об этом скажет.

Отдельно от скиллов детектор ставится из PyPI:

```bash
uv tool install aiw-ru
```

Или запускается без установки: `uvx aiw-ru scan статья.md`. Подойдёт и `pip install aiw-ru`.

### Только команда, без плагина

Скиллы лежат и в пакете. Если стоит только `aiw-ru`, их выводит сама команда:

```bash
aiw-ru skill
```

```bash
aiw-ru skill avoid-ai-writing-russian
```

Первая показывает список скиллов, вторая печатает SKILL.md для агента. Вызовы детектора в нём уже переписаны на `aiw-ru …`, а каталог примет выводит `aiw-ru skill avoid-ai-writing-russian references/patterns.md`. Агенту достаточно сказать: «выполни `aiw-ru skill avoid-ai-writing-russian` и работай по этому скиллу».

### Необязательная модель

Кроме правил, у детектора есть модель LightGBM, обученная на русской части корпуса LLMTrace: она оценивает вероятность, что текст написала модель. Вместе со скиллами она не ставится, агент предложит её сам и поставит, только если вы согласитесь. Вручную:

```bash
uv tool install "aiw-ru[ml]"
```

```bash
aiw-ru models install
```

Файлы модели (около 10 МБ) скачиваются с [Hugging Face](https://huggingface.co/toiletsandpaper/russian-ai-text-detector-lightgbm) в общий кэш `~/.cache/huggingface`. Карточка модели там же: результаты на LLMTrace по жанрам, длине текста и моделям-генераторам.

## Как пользоваться

Обычной фразой агенту:

- «убери ИИ-стиль из этого абзаца»;
- «просканируй `glava2.md`, ничего не правь»;
- «почисти `README.md` на месте, профиль docs»;
- «перепиши прямее для Telegram-канала»;
- «подготовь главу к антиплагиату» (включается под-скилл).

Режимы: `rewrite` (по умолчанию, вернуть исправленный текст), `detect` (только найти), `edit` (править файл на месте точечными правками).

Профили контекста меняют строгость правил:

| Профиль | Для чего |
|---|---|
| `vak` | диссертация, автореферат, статьи ВАК/РИНЦ, отчёты по НИР |
| `docs` | документация, README, инструкции |
| `blog` | статьи, эссе, Хабр (по умолчанию) |
| `telegram` | посты в каналах и соцсетях |
| `business-email` | деловые письма, КП, письма инвесторам |
| `chat` | переписка и комментарии: только грубые приметы |

Профили голоса (`casual`, `professional`, `technical`, `warm`, `blunt`) задают звучание правки. Голос проявляет то, что уже есть в тексте, но не придумывает автору мнений и опыта.

Скилл сохраняет цитаты, код, формулы, таблицы, ссылки на литературу и числа. Правку он заканчивает отчётом: сколько было проходов, какие проверки запускались, какие находки оставлены и почему.

## Под-скилл antiplagiat

Включается, когда текст идёт на проверку. Порядок работы:

1. Замер: оценка доли «ИИ-текста» по фрагментам и список рискованных абзацев с причинами.
2. Чистка технических артефактов: невидимые символы и латинские буквы внутри русских слов. Из-за них система помечает документ как подозрительный, и это хуже любого процента.
3. Правка подсвеченных фрагментов по правилам основного скилла, в первую очередь ритма и пунктуации: классификаторы смотрят на структуру сильнее, чем на слова.
4. Повторный замер и проверка сохранности формул, чисел и ссылок.
5. Калибровка детектора по вашим реальным отчётам. Если модель ещё не откалибрована, агент сам попросит прошлые отчёты «Антиплагиата»: с ними оценка ближе к тому, что система скажет именно о ваших текстах. Всё считается локально.

Скилл работает с вашим собственным текстом. Заимствования он помогает оформить как цитирования (кавычки и ссылка на источник), чтобы система засчитала их законно. Маскировать чужой текст перефразированием, синонимайзером или подменой символов он не будет: это выдача чужой работы за свою, а не спор с плохим детектором.

## Детектор

```bash
aiw-ru scan статья.md --context vak
```

```bash
aiw-ru antiplagiat глава1.md
```

```bash
aiw-ru validate исходник.md правка.md
```

```bash
aiw-ru calibrate --doc глава1.md --marked глава1-подсвечено.txt
```

```bash
aiw-ru calibrate --doc глава2.md --share 34
```

```bash
aiw-ru classify статья.md
```

`scan` печатает оценку 0–100, статистику ритма и таблицу находок: уровень P0–P2, строка и столбец, примета, фрагмент и подсказка. Таблица подстраивается под ширину терминала, длинный текст переносится внутри ячейки. Цвет включается только в терминале; `NO_COLOR=1` его выключает, `FORCE_COLOR=1` включает принудительно. Параметр `--json` даёт машиночитаемый вывод, `--jsonl` проверяет пачку документов (по документу в строке, `{"text": "…"}`, ответ тоже по строке на документ), `--fail-above N` возвращает код 1, если оценка выше N (удобно в CI для документации).

`antiplagiat` делит текст на фрагменты (абзацы, короткие склеиваются), описывает каждый семью признаками и переводит их в вероятность логистической моделью. Признаки: плотность примет, однообразие длины предложений, типичная для моделей длина предложения, канцелярит, бедная пунктуация, однообразные начала предложений, бедный словарь. Доля ИИ-текста считается по знакам, как в отчёте системы.

`validate` сравнивает исходник и правку. Код, формулы, URL, числа, ссылки `[12]` и `[@key]`, таблицы, цитаты и структура заголовков должны остаться на месте, а находок должно стать не больше. Разрешённые правки нарушением не считаются: «ёлочки» вместо прямых кавычек, запятая вместо десятичной точки, удалённый `utm_source=chatgpt.com`.

`calibrate` дообучает модель `antiplagiat` на ваших отчётах. Лучше всего работает разметка фрагментов: текстовый файл с кусками, которые система подсветила как сгенерированные, по одному на абзац через пустую строку. Собирать его руками не обязательно: агент выпишет фрагменты сам из PDF отчёта или скриншотов. Если под рукой только итоговая цифра, передайте её через `--share`: так подстраивается общая строгость модели, но не веса признаков. Образцы накапливаются в `.aiw-ru.json`, и с каждым отчётом оценка точнее отражает поведение системы на ваших текстах. Отчёты, где система ничего не пометила, тоже пригодятся: это примеры человеческого текста. В файле калибровки только модель и числовые признаки фрагментов, самого текста там нет. В общий репозиторий его всё равно не коммитьте: `antiplagiat` читает `.aiw-ru.json` из текущей папки, и ваша калибровка исказит оценку соавторам (в этом репозитории файл уже в `.gitignore`). Текст есть в файлах с фрагментами из отчётов, их держите вне публичных репозиториев.

`skill` печатает скиллы для агента, у которого нет плагина: без аргументов список, с именем SKILL.md, с именем и путём файл скилла (`references/patterns.md`).

`classify` отвечает вероятностью от необязательной модели LightGBM: какая доля похожих текстов в корпусе LLMTrace написана моделью. Без установленной модели команда подскажет, как её поставить. Если модель есть, `scan` и `antiplagiat` показывают эту вероятность рядом со своей оценкой.

Из Python:

```python
from aiw_ru import analyze

result = analyze(text, "academic")
print(result.score, len(result.issues))
```

Результаты — модели pydantic: `result.to_dict()` даёт тот же JSON, что и `aiw-ru scan --json`.

## Что ловит каталог

Полный каталог — в [`skills/avoid-ai-writing-russian/references/patterns.md`](skills/avoid-ai-writing-russian/references/patterns.md). Коротко:

| Группа | Примеры |
|---|---|
| Следы чат-бота | «Надеюсь, это поможет», «Отличный вопрос!», «как языковая модель» |
| Словарь уровня 1 | «является», «играет ключевую роль», «уникальный», «открывает новые возможности», «в современном мире» |
| Канцелярит (1Б) | «осуществляется», «данный», «в рамках», «в целях», «посредством» — совет по стилю, не довод об авторстве |
| Кальки | «адресовать проблему», «это про», «на ежедневной основе», «имеет смысл», «в моменте» |
| Синтаксис | «не просто X, а Y», цепочки родительного падежа, пассив без деятеля, навязчивые тройки |
| Авторитет и значимость | «исследования показывают», «эксперты считают», «знаменует новую эру», оценки без чисел |
| Соцсети | «И вот тут начинается самое интересное», «Сохраняйте, пригодится», «Встречайте:» |
| Типографика | тире-связки, дефис вместо тире, прямые и английские кавычки, десятичная точка, Title Case |
| Ритм | одинаковая длина предложений и абзацев, бедный словарь, одинаковые начала |
| Технические отпечатки | невидимые символы, подмена букв, `[Вставьте источник]`, `oaicite`, `utm_source=chatgpt.com` |

## Ограничения

- Приметы — это сигналы, а не доказательство авторства. Их выдают и люди, особенно в научном и канцелярском регистре. Не используйте детектор как единственное основание для решений об академической нечестности, найме или публикации.
- Как классификатор детектор слабый, и это видно по цифрам. На русской части тестового набора [LLMTrace](https://huggingface.co/datasets/iitolstykh/LLMTrace_classification) оценку «много примет» и выше получили 5,9 % из 21 417 человеческих текстов (у новостей 13 %) и 16,7 % из 14 064 сгенерированных. Больше половины сгенерированных текстов детектор счёл чистыми. Он показывает, что править в тексте, а не кто его написал.
- Модель `antiplagiat` — приближение. Классификатор системы «Антиплагиат» закрыт. Веса по умолчанию подобраны вручную на небольших примерах, а не обучены на корпусе. Калибровка подстраивает веса под то, как система ведёт себя на ваших текстах, но точную цифру отчёта не гарантирует.
- Морфология упрощена: основы со звёздочкой вместо полноценного морфологического анализатора. Редкие формы могут проскочить, омонимы могут дать ложное срабатывание.
- Регулярные выражения не видят смысла. Правила, которые требуют суждения (ложный деятель, бег на месте, выдуманный контраст), есть только в скилле, детектор их не ищет.

## Разработка

```bash
uv sync --group dev --group train
```

```bash
uv run prek install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push
```

```bash
uv run pytest
```

```bash
uv run prek run --all-files
```

`uv sync --group dev --group train` ставит детектор, инструменты разработки (группа `dev`) и зависимости для обучения модели (группа `train`); без групп ставится только детектор, как у пользователя скилла. Хуки prek прогоняют ruff, ty, самопроверку документации детектором и синхронность версий. Тесты покрывают разбор текста, каждое правило детектора, корпус живых и шаблонных текстов шести жанров, CLI, скрипты выпуска и сами скиллы: шапки SKILL.md, ссылки, связь разделов каталога с типами находок детектора, примеры из каталога.

Поведение скилла на живом агенте проверяет `uv run python evals/run.py`: двенадцать случаев (защищённые цитаты, попытка внедрить инструкцию в текст, ловушка на выдуманные числа, режим только поиска и другие) с автоматической оценкой ответа. В CI этот прогон не входит.

Хуки prek перед коммитом проверяют гигиену файлов, секреты, формат, типы, невидимые символы и сообщение коммита (на русском); перед отправкой запускают тесты. Правила участия — в [CONTRIBUTING.md](CONTRIBUTING.md), история изменений — в [CHANGELOG.md](CHANGELOG.md).

## Выпуски

```bash
uv run python scripts/release.py patch
```

```bash
git push --follow-tags
```

Скрипт переносит раздел «Не выпущено» из CHANGELOG в новую версию, обновляет версию в `pyproject.toml`, манифестах, скиллах и `CITATION.cff`, делает коммит и тег. По тегу GitHub Actions публикует пакет на [PyPI](https://pypi.org/project/aiw-ru/) через доверенную публикацию (без токенов в секретах) и создаёт [выпуск](https://github.com/ormeilu/avoid-ai-writing-russian/releases) с архивом скиллов, контрольными суммами и заметками из CHANGELOG.

## Как сослаться

Если проект пригодился в исследовании, данные для ссылки лежат в [CITATION.cff](CITATION.cff); GitHub показывает их кнопкой «Cite this repository».

## Благодарности

Огромное спасибо **[Конору Бронсдону](https://github.com/conorbronsdon)** за [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing). Без этого проекта русской версии не было бы. Оттуда взяты режимы работы, договор о правке, уровни серьёзности, трёхуровневый словарь, профили контекста и голоса, самоисключение для текстов о приметах и правило «никогда не добавляй». Отдельно спасибо за то, что исходный проект честно называет свои находки сигналами, а не доказательствами, и держит это правило во всех решениях.

Спасибо авторам и участникам, на чьи находки опирается исходный проект и, через него, этот: [blader/humanizer](https://github.com/blader/humanizer), [brandonwise/humanizer](https://github.com/brandonwise/humanizer), [Aboudjem/humanizer-skill](https://github.com/Aboudjem/humanizer-skill), [isatimur/de-slop](https://github.com/isatimur/de-slop), [welttowelt/stop-slop-refined](https://github.com/welttowelt/stop-slop-refined), [LLM cliché highlighter](https://tools.simonwillison.net/llm-cliche-highlighter) Саймона Уиллисона и [tropes.fyi](https://tropes.fyi).

Русская часть многим обязана традиции борьбы с канцеляритом, которая старше нейросетей на полвека: Корнею Чуковскому, придумавшему само слово «канцелярит» в книге «Живой как жизнь», Норе Галь с её «Словом живым и мёртвым» и Максиму Ильяхову и Людмиле Сарычевой с книгой «Пиши, сокращай».

## Лицензия

[MIT](LICENSE). Copyright (c) 2026 Conor Bronsdon — исходный проект; Copyright (c) 2026 Ilya Lubenets — русская адаптация. Подробности о происхождении частей — в [NOTICE.md](NOTICE.md).
