hum1izer

module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 11, 2026 License: MIT

README

hum1izer

CLI на Go: проверяет текст, комментарии в коде и сообщения коммитов на следы нейросети, канцелярит и штампы, показывает находки с номерами строк и говорит, что с каждой делать. Русский и английский.

Считается только то, что берётся грепом и арифметикой: 21 хард-бан, 19 категорий маркеров, ритм, номинальность, структура документа, балл чистоты 0-100.

Идея и первоначальные наборы правил - из ilyautov/humanizer-ru (MIT, (c) Ilya Utov), там же корпусное обоснование порогов: AINL-Eval, LLMTrace, M4-ru. Движок здесь свой, правила вынесены в YAML и дополняются.

Установка

Готовый бинарь под macOS, Linux и Windows лежит в релизах: скачай архив под свою платформу, распакуй, положи в PATH.

go install github.com/haiodo/hum1izer/cmd/hum1izer@latest   # из исходников
make build                                                  # локальная сборка
make install                                                # в GOBIN

Одна зависимость - gopkg.in/yaml.v3 для чтения правил, остальное стандартная библиотека.

Скиллы для агентов

hum1izer install --claude --codex --opencode --hermes --pi
hum1izer install --all              # все сразу
hum1izer install --claude --dir .   # в проект, а не в домашний каталог
hum1izer install --print            # посмотреть SKILL.md, ничего не ставя
make skills                         # собрать и поставить всем

Формат общий - Agent Skills, различаются только шапка и путь:

Флаг Куда
--claude ~/.claude/skills/hum1izer/SKILL.md
--codex ~/.codex/skills/hum1izer/SKILL.md
--opencode ~/.config/opencode/skill/hum1izer/SKILL.md
--hermes ~/.hermes/skills/devops/hum1izer/SKILL.md
--pi ~/.pi/agent/skills/hum1izer/SKILL.md
--agents ~/.agents/skills/hum1izer/SKILL.md

opencode читает ещё и ~/.claude/skills с ~/.agents/skills, так что ему хватит и --claude, и --agents - отдельный флаг нужен, только если хочется держать скилл в его собственном каталоге.

Существующий файл не перезаписывается без --force. Скилл описывает цикл правки, правила хорошего комментария и список того, что трогать нельзя: лицензионные шапки, //go:generate, //nolint, eslint-disable, прагмы.

Использование

hum1izer текст.md                      # отчёт с рекомендациями
hum1izer --lang en post.md             # английский набор правил
hum1izer --genre academic статья.md    # снять маркеры, законные для регистра
hum1izer --quiet docs/*.md             # одна строка на файл
hum1izer --json текст.md               # машинный вывод
cat draft.txt | hum1izer -             # из stdin

hum1izer --code ./src                  # комментарии в коде
hum1izer --code .                      # то же плюс последние 20 коммитов
Флаг Что делает
--genre marketing (по умолчанию), academic, legal, fiction, news
--lang набор правил для прозы: ru (по умолчанию) или en
--format text (по умолчанию), jsonl, json, quiet
--limit N сколько блоков отдать, 0 - все. Первыми идут самые грязные
--json то же, что --format json
--top N сколько мягких маркеров показать, 0 - все (по умолчанию 12)
--quiet только итоговая строка на файл
--rules свой файл правил вместо встроенного
--code разбирать аргументы как исходники, а не как прозу
--commits N сколько последних коммитов проверить, 0 - не проверять (20)
--max-lines N комментарий длиннее скольких строк - находка, 0 - не считать (2)
--skip-tests пропускать _test.go, *.test.*, *.spec.*
--config F взять этот файл настроек вместо поиска .hum1izer.yaml
--no-config игнорировать .hum1izer.yaml
--baseline F сверяться со снимком, ругаться только на новое
--write-baseline перезаписать снимок текущими находками

Код возврата: 0 чисто, 1 найдены хард-баны, 2 ошибка. Годится для pre-commit и CI.

Что считается

Хард-баны - конструкции из таблицы «Жёсткие запреты»: в современном мире, данный, стоит отметить, комплексный подход, длинное тире и так далее. Каждая находка идёт с рекомендацией из той же таблицы.

Маркеры - лексические категории каталога: канцелярит, кальки, раздувание значимости, формульные выводы, артефакты чат-бота, мотивационные клише, маркетинговые штампы, эмодзи-декор, подмена символов и ещё десяток. Рекомендация одна на категорию.

Ритм - коэффициент вариации длин предложений. У человека обычно выше 0.45, у генерации ровнее. Плюс тире, многоточия, скобки, вопросы.

Номинальность - плотность отглагольных существительных на 100 слов.

Структура - разброс длин абзацев, доля пунктов списка (listicle-сигнатура), Title Case в заголовках, обрыв текста на полуслове.

У .md, .mdx и .markdown перед разбором гасится разметка: YAML-шапка, блоки кода, код в строке, импорты MDX, теги HTML и JSX, адреса ссылок, строки таблиц. Гасится пробелами, поэтому номера строк и позиции находок остаются верными. Без этого блок кода без единой точки становится одним предложением на полторы тысячи слов, и ритм не мерится вообще: на посте блога CV падал с 5.04 до 0.82, стоило вырезать код.

Балл - агрегат всего перечисленного, 0-100. Полосы: ≥85 чисто, 60-84 точечная правка, <60 рерайт.

Балл это правила сканера, а не вероятность ИИ и не вердикт об авторстве. Он нужен, чтобы сравнивать «было и стало» на одном и том же тексте.

Плотность маркеров считается на 100 слов, а не штуками: семь маркеров на тысячу слов и семь на сотню - разные вещи, и абсолютный счёт на длинном тексте всегда давал «AI с высокой вероятностью».

Жанры

Без жанра режим строгий, под него откалиброваны пороги оригинала (маркетинг, блоги). Для научного, юридического, художественного и новостного текста часть банов - норма регистра, а не признак машины: --genre их снимает.

$ hum1izer --quiet ai-sample.txt
ai-sample.txt   19/100 [рерайт] банов: 14, маркеров: 13

$ hum1izer --genre academic --quiet ai-sample.txt
ai-sample.txt   35/100 [рерайт] банов: 9, маркеров: 5

Комментарии в коде и коммиты

hum1izer --code ./repos/platform

Список файлов в git-репозитории берётся у самого git (git ls-files --cached --others --exclude-standard), поэтому .gitignore соблюдается точно, вместе с вложенными и глобальными правилами: собранный код в lib/ и bundle/ под проверку не попадает. Вне git идёт обычный обход с пропуском node_modules, vendor, dist и подобного.

Пропускаются также сгенерированные файлы (Code generated ... DO NOT EDIT, @generated, sourceMappingURL в хвосте) и лицензионные шапки: SPDX в любом месте, Copyright или Licensed under в первых пяти строках файла.

Разбираются .go, .ts, .tsx, .js, .jsx, .mjs, .cjs, .svelte, .swift, .java, .kt, .kts. Go читается через go/parser, остальное - посимвольным сканером, который знает про строки и шаблоны, поэтому // внутри строки за комментарий не принимается. Сканер разведён по языкам: литералы регулярок только в JS и TS, тройные кавычки в Java и Kotlin, вложенные блочные комментарии в Kotlin. Границы блока берутся по байтовым смещениям, а не по строкам: у хвостового комментария x := 1 // счётчик в raw попадает только сам комментарий, а кодом для проверки пересказа считается то, что стоит перед ним на той же строке.

Закомментированный код определяется не регуляркой, а разбором: тело комментария отдаётся настоящему парсеру, и если оно разобралось - это код. Для .go это go/parser из стандартной библиотеки, как делает go-critic. Для .ts, .tsx, .js, .jsx и .svelte - esbuild (MIT). Для Swift парсера нет, там осталась доля строк, похожих на код.

Разница заметная. На платформе в 6942 файла регулярка находила 76 кусков закомментированного кода, парсер находит 187, и это // export let attributeKey: string | undefined, // createAction(builder, {...}) - настоящий мёртвый код, который регулярка не опознавала.

За это платим размером: бинарь растёт с 3.8 до 8.9 МБ. Скорость не меняется, 12 секунд на те же 6942 файла.

Почему не typescript-go: его парсер, сканер и AST лежат под internal/, то есть импортировать их нельзя. Обойти можно только вендорингом - положить исходник внутрь своего дерева и написать адаптер рядом с ним. Git-submodule не поможет: у typescript-go свой go.mod, а каталог со своим go.mod компилятор считает отдельным модулем, и правило internal снова включается. Цена вендоринга - примерно 1.4 МБ чужого исходника (parser, ast, core, scanner) плюс форк архивированного репозитория навсегда. esbuild даёт то же самое одной строкой go get. В .svelte отдельно берутся <script>, <style> и <!-- -->. Соседние строки склеиваются в один блок: шапка из десяти // - это один текст, а не десять находок. Сгенерированные файлы (Code generated ... DO NOT EDIT, @generated), node_modules, vendor, dist, gen пропускаются.

Язык каждого блока определяется по нему самому: кириллица от 30% - русский набор, иначе английский. Поверх языкового всегда идёт rules-code.yaml.

Сбор блоков вырос из platform-go/tools/longcomments и platform/scripts/find-long-comments.{go,mjs}: оттуда взяты разбор Go через go/parser, посимвольный сканер для TS и склейка соседних комментариев.

Если в аргументе лежит git-репозиторий, туда же попадают последние --commits N сообщений коммитов: тот же прозаический разбор плюс проверки формы заголовка.

Что проверяется дополнительно к прозаическим правилам:

Находка Почему
Пересказ кода // set user name над setUserName() не несёт информации
Закомментированный код история кода живёт в git
Пересказ кода комментарий повторяет имя рядом, в том числе хвостовой
Длинный комментарий длиннее --max-lines строк, по умолчанию 2
Баннер-разделитель // ========= разделяет файлами, а не линиями
TODO без владельца без имени или ссылки на задачу это вечный TODO
Ченджлог в комментарии «Updated X to Y», «Author:», дата - это git blame
Markdown-эссе заголовки и списки внутри комментария
Пошаговая инструкция «Step 1, Step 2» дублирует сам код
Комментарий-пустышка // constructor, // imports, // инициализация
Пустая важность «ensures that», «отвечает за», «под капотом»
Учебный тон «as you can see», «давайте», «теперь мы»
Извинение «почему-то», «костыль», «hopefully», «not sure why»
Комментарий-обещание «временно», «for now», «will be removed»
Эмодзи в дифф и в grep попадают шумом
Метка инструмента ponytail:, caveman:, claude:, AI: - следы плагина или модели
Длинная строка склеить три строки в одну на 140 символов не значит сократить

Для коммитов сверх этого: длина заголовка больше 72 символов, точка в конце заголовка, заголовок вида «Update» или «Fix», AI-подпись в трейлере, «This commit adds ...», список из пяти и более пунктов.

Тире в комментариях по умолчанию не считается (жанр code его глушит): их там столько, что отчёт превращается в список тире. Типографику правь отдельным проходом без --code.

Настройки проекта

.hum1izer.yaml ищется от проверяемого каталога вверх до корня файловой системы, поэтому из любого подкаталога монорепы находятся настройки её корня. Флаги командной строки перекрывают файл; --config F берёт конкретный файл, --no-config игнорирует любой.

hum1izer init            # просканировать и записать .hum1izer.yaml
hum1izer init --print    # посмотреть, ничего не записывая
hum1izer init --force    # перезаписать существующий

init гоняет обычную проверку, вписывает в файл найденные языки и списком комментариев показывает, какие правила шумят в этом проекте сильнее всего - остаётся перенести лишнее в rules.disable.

version: 1

comments:
  max_lines: 2      # комментарий длиннее скольких строк - находка, 0 отключает
  commits: 20       # сколько последних коммитов проверять, 0 отключает
  skip_tests: false

languages:
  only: []          # go, ts, js, svelte, swift, java, kotlin. Пусто - все
  ignore: [swift]

exclude:            # ** проходит через каталоги, * внутри сегмента
  - "**/testdata/**"
  - "docs/legacy/**"

baseline: .hum1izer-baseline   # путь к снимку, считается от файла настроек

rules:
  only: []          # белый список. Пусто - все
  disable:
    - Длинное тире            # имя правила
    - Структура комментария   # или имя категории целиком

genre: code         # жанр для правил прозы
rules_file: ""      # свой rules.yaml, путь от файла настроек

Имена в rules берутся прямо из отчёта: что напечатано после ! или *, то и пишется в disable. Работает и имя категории - тогда глушится вся группа. Категории структурных проверок: Структура комментария и Форма коммита.

Неизвестный ключ, неизвестный язык или битый glob ломают загрузку с ошибкой: молча не работающая настройка хуже её отсутствия.

Снимок для CI

На живом репозитории находок тысячи, и красный CI с первого дня никого ничему не учит. Поэтому есть снимок: прогон сверяется с файлом и ругается только на то, чего в нём нет.

hum1izer --code --baseline .hum1izer-baseline --write-baseline .   # записать
hum1izer --code --baseline .hum1izer-baseline .                    # проверить

Файл кладётся в git. Он отсортирован и хранит относительные пути, чтобы диффы читались:

# hum1izer baseline v1
55dc2ad977ba	TODO без владельца	internal/code/check.go

Ключ - хэш текста комментария, а не номер строки: код можно двигать и переотступать, находка останется той же. Отредактировал комментарий - он считается новым, и это правильно: раз тронул, приведи в порядок.

В stderr идёт в базе 1200, новых 0, исправлено 7 - прогресс виден, и его никто не может незаметно отмотать назад.

Код возврата с --baseline ставится за новое, а не за жёсткое. Коммиты в снимок не попадают: каждый новый коммит был бы новой находкой. Если --commits не задан явно, при работе со снимком он выключается.

Формат для агента

hum1izer --code --format md --limit 20 ./src

Блок на комментарий: заголовок, список замечаний, сам текст в огороженном блоке байт-в-байт. Забор подбирается длиннее самой длинной цепочки кавычек внутри, поэтому комментарий с блоком кода разметку не ломает.

Для машинной обработки есть --format jsonl, по строке JSON на блок. Агенту он подходит хуже: в JSON текст экранирован, и реальный комментарий выглядит как [id=\"app-recruit\\\\:string\\"] - чтобы заменить его точным совпадением, модели придётся развернуть экранирование в уме.

Одна строка JSON на блок, самые грязные первыми, сводка в stderr: remaining=43 shown=20 findings=61 comments=15035 files=4157.

{"id":"src/a.ts:1-4","file":"src/a.ts","start":1,"end":4,"lang":"ts",
 "kind":"comment","score":7,
 "raw":"/**\n * This function is responsible for handling the request.\n */",
 "findings":[{"rule":"this function is responsible for","line":2,"hard":false,
              "fix":"Скажи, почему так сделано, а не что делает строка ниже"}]}

raw - исходный текст байт-в-байт, вместе с // и /* */. Агент правит блок целиком и заменяет raw точным совпадением: номера строк после первой же правки уезжают, а raw нет. Дальше перезапуск, пока remaining падает.

Один блок - одна правка, а не отдельная находка на каждое совпадение правила. --limit режет работу на итерации, score задаёт порядок.

Вес находки в score берётся из поля lift правила: во сколько раз маркер чаще встречается у машины, чем у человека. Жёсткая находка идёт с тройным весом, потолок 10, у неизмеренных правил вес равен единице.

Замер свой, на корпусе LLMTrace (Apache-2.0): 2708 человеческих и 1455 машинных текстов на русском, 2056 и 1352 на английском. Генераторы - gpt-4, o3-2025, gigachat, Qwen2.5-72B, Magistral, command-r, DeepSeek-R1, gemini-2.5-flash. Пересчитывается одной командой:

go run ./eval/lift --file valid.jsonl --lang ru        # таблица
go run ./eval/lift --file valid.jsonl --lang ru --tsv  # машинный вывод для переноса в rules.yaml

Что показал замер:

Маркер lift
Эмодзи-декор (ru) у человека нет вовсе идеальный разделитель
seamless(ly) (en) 21.0
crucial (en) 17.7
Важно понимать/помнить, что (ru) 15.1
not only X but also Y (en) 12.5
Канцелярит (ru) 2.8
Em dash (en) 1.7 в английском сигнал есть
Длинное тире (ru) 0.94 у человека чаще, чем у машины
Латиница внутри кириллицы 0.28 это опечатки людей, не след машины
Tutorial voice (en) 0.79 у человека чаще

Правила с lift ниже 1.2 веса не получают. Русское тире остаётся хард-баном как типографика, но детектором генерации оно не является, и жанр code его глушит ровно поэтому.

Числа домен-зависимы: «Является» даёт 2.5 у нас, 4.5 на смешанном регистре и 0.1 на научном по замерам humanizer-ru. Жанр важнее веса. Четыре правила, на которые в нашем корпусе не хватило попаданий, сохранили чужие значения из каталога humanizer-ru - они помечены комментарием прямо в rules.yaml.

Свои правила

Правила лежат в трёх файлах, все вшиты в бинарник:

Файл Что в нём
internal/humanize/rules.yaml русская проза: баны, маркеры, пороги, жанры
internal/humanize/rules-en.yaml то же для английского
internal/humanize/rules-code.yaml комментарии и коммиты, поверх языкового набора

Русский набор подменяется флагом:

hum1izer --rules my-rules.yaml текст.md

Формат одного правила:

hard_bans:
  - name: Синергия
    fix: Скажи, что конкретно с чем соединяется
    word_re: 'синерги[\p{L}]+'

categories:
  - name: Мой канцелярит
    fix: Разверни в глагол
    rules:
      - lit: осуществлени          # подстрока, регистронезависимо
      - re: 'посвящен[ао]\s+анализ' # регулярка RE2 как есть
      - word_re: 'важн[\p{L}]+ шаг' # то же, но с границами слова
      - builtin: en_dash            # правило, которое считает код

Три вещи, о которых стоит помнить при правке:

  • в Go \b и \w работают только по ASCII, поэтому для кириллицы пиши word_re вместо \b и [\p{L}]+ вместо \w;
  • lookaround и обратных ссылок в RE2 нет: то, что без них не выражается, живёт в коде как builtin (en_dash, fake_range, latin_in_cyrillic);
  • невидимые символы в наборе пиши кодами (\x{200b}), а не литералами: в дифф они не видны, и GitHub ругается на bidirectional Unicode.

Загрузчик проверяет набор при старте: если жанр глушит бан, которого нет, hum1izer падает с ошибкой вместо того, чтобы молча ничего не делать.

Отличия от оригинального сканера

Порт сверен с scripts/scan.py на общем тексте: балл, состав штрафов и список находок совпадают. Три отличия в реализации:

  1. Номинальность. Оригинал считает сущ./глаг. через pymorphy3. Здесь словаря нет, вместо отношения считается плотность отглагольных существительных по суффиксам. Сигнал тот же (канцелярит), вес штрафа тот же. Потолок эвристики: не отличает «решение задачи» от «решение принято».
  2. Границы слов и lookaround. В Go \b и \w работают только по ASCII, а lookaround и обратных ссылок нет вовсе. Границы расставлены явно, три правила (короткое тире, ложный диапазон «от X до Y», латиница внутри кириллицы) считаются кодом.
  3. Номера строк. Точнее, чем в оригинале: там позиция берётся от начала совпадения, поэтому паттерн с ведущим разделителем (. Таким образом,) показывает строку предыдущего предложения.

Заголовки в Title Case оригинал отсеивает по словарю имён собственных, здесь словаря нет: заголовок из нескольких имён даст ложное срабатывание.

Чего тут нет

Семантика: кальки по смыслу, ирония, translationese, пустая образность, «фигуративный ноль». Это принципиально не ловится регулярками, для этого нужен сам скилл humanizer-ru с моделью.

Переписывания текста тоже нет: hum1izer только показывает и советует.

Разработка

cmd/hum1izer/       флаги, вывод, подкоманды install и init
internal/baseline/  снимок находок для CI
eval/lift/          пересчёт весов lift на парном корпусе
internal/config/    .hum1izer.yaml: поиск вверх, языки, исключения, правила
internal/humanize/  правила, разбор прозы, балл + rules*.yaml
internal/code/      комментарии из исходников, коммиты, структурные проверки
internal/skill/     SKILL.md и раскладка по агентам
make check   # fmt + vet + golangci-lint + test
make build   # бинарь с версией из git describe

CI гоняет go vet, gofmt -l, golangci-lint и go test -race на каждый пуш. Релиз собирается по тегу v*: darwin/arm64, darwin/amd64, linux/amd64, linux/arm64, windows/amd64, архивы и SHA256SUMS уезжают в GitHub Release.

git tag v0.1.0 && git push --tags

Лицензия

MIT, (c) 2026 Andrey Sobolev.

Наборы правил, пороги, корпусные веса lift и процедура правки в скилле изначально взяты из humanizer-ru (MIT, (c) Ilya Utov).

Directories

Path Synopsis
cmd
hum1izer command
Command hum1izer проверяет текст, комментарии в коде и сообщения коммитов на следы нейросети, канцелярит и штампы.
Command hum1izer проверяет текст, комментарии в коде и сообщения коммитов на следы нейросети, канцелярит и штампы.
eval
lift command
Command lift считает подъём каждого правила на парном корпусе: во сколько раз маркер чаще встречается у машины, чем у человека.
Command lift считает подъём каждого правила на парном корпусе: во сколько раз маркер чаще встречается у машины, чем у человека.
internal
baseline
Package baseline - снимок находок проекта.
Package baseline - снимок находок проекта.
config
Package config читает .hum1izer.yaml: настройки проекта рядом с кодом.
Package config читает .hum1izer.yaml: настройки проекта рядом с кодом.
skill
Package skill раскладывает SKILL.md по каталогам агентов.
Package skill раскладывает SKILL.md по каталогам агентов.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL