github-agent: гигиена репозитория одной командой

Репозиторий редко проваливается по коду — он проваливается по документации: в README нет раздела установки, в CHANGELOG нет дат, вики из трёх страниц без навигации, баннер не отображается, описание состоит из одного слова. git push при этом проходит успешно, поэтому дефект живёт годами. Гигиена репозитория — это попытка превратить такие дефекты в проверяемый контракт: github-agent (команда ghagent, версия 1.2.2) даёт по одной команде на каждую повторяющуюся задачу и возвращает код 0, 1 или 2 вместо абзаца рассуждений. Ниже — разбор по установленной версии: я поставил пакет, прогнал проверки на подготовленной песочнице и получил свои числа, включая одно место, где инструмент ведёт себя не так, как ожидает рука.

TL;DR: что это и как проверить за десять минут

1. Что это. Python-CLI без зависимостей для проверки и приведения в порядок репозитория и его вики.
2. Что проверяет. Обязательные файлы, контракт README и CHANGELOG, markdown, ссылки и якоря, секреты и машинные пути, картинки, метаданные.
3. Оценка. audit считает процент гигиены по весам: у отсутствующей лицензии вес 8, у ссылки на соцпревью — 4.
4. Коды возврата. 0 — ошибок нет, 1 — есть находки уровня error, 2 — ошибка вызова или окружения.
5. Главное ограничение. Колесо с PyPI несёт только CLI: selftest и install в такой установке отказывают — для них нужен клон.

uv tool install github-agent-cli     # или pipx, или pip
ghagent --version                    # github-agent 1.2.2
ghagent audit .                      # оценка гигиены, код 1 при ошибках
ghagent doc --root .                 # markdown, ссылки, якоря, оглавление

Проблема, которую это решает

Проверки качества кода стали нормой: линтер, тесты, CI. Проверки качества документации — почти нет, хотя именно документация определяет, воспользуются ли проектом. Причины понятны: «хороший README» плохо формализуется, а «нет раздела установки» не ломает сборку.

В результате накапливается типовой набор: README без установки и без лицензии, CHANGELOG с версиями без дат, CONTRIBUTING, которого нет, SECURITY, о котором вспоминают после первого отчёта об уязвимости, вики, где страницы не связаны ссылками, и социальное превью, которое GitHub показывает как пустую карточку.

github-agent формализует это как измеримый набор пунктов с весами и печатает находки в виде файл:строка плюс идентификатор правила. Практическая ценность не в проценте как таковом, а в том, что процент можно поставить в CI и не давать ему падать, а находки — разбирать машинно.

Что такое github-agent и из чего он состоит

flowchart TB
  CLI["ghagent: 13 команд, Python 3.11+, без зависимостей"] --> CHECK["проверки: audit, doc, privacy, assets, wiki, changelog, meta"]
  CLI --> ACT["действия: changelog release, meta apply, assets render, wiki publish"]
  CLI --> PACK["упаковка навыка: install, verify-install, uninstall, snippet"]
  CLI --> SELF["selftest и report"]
  CHECK --> OUT["file:line плюс идентификатор правила, ключ --json"]
  ACT --> REPO["дерево репозитория и API GitHub"]
  PACK --> SKILL["каталог навыка агента"]
  OUT --> CODE{"код возврата"}
  CODE -- 0 --> OK["ошибок уровня error нет"]
  CODE -- 1 --> ERR["есть ошибки, каждая с адресом"]
  CODE -- 2 --> USAGE["ошибка вызова или окружения"]

Лицензия — MIT, одна строка, как и договаривались.

Тринадцать команд делятся на три группы: проверки (audit, doc, privacy, assets, wiki, changelog, meta), действия (changelog release, meta apply, assets render, wiki publish) и упаковка навыка (install, verify-install, uninstall, snippet). Отдельно стоят report — сводный markdown по всем проверкам — и selftest.

Возможности: что проверяется и что правится

Проверки: обязательные файлы и контракт README

Веса — не украшение: из них складывается процент, и по таблице видно, что дешевле всего закрыть (support, citation, codeowners), а что даёт больше всего очков (README с H1 и установкой, лицензия, CI).

Проверки документов, ссылок и приватности

Действия и упаковка

Как это устроено внутри

Каждая проверка — это проход по текстовым файлам дерева с набором правил. Правило, которое не осмотрело ни одного объекта, попадает в coverage.skipped и не считается пройденным: пустое дерево даёт отдельную находку doc.no-text-files. Это важное проектное решение, и оно прямо названо в правилах: ложный PASS хуже ложного FAIL.

Второе проектное решение — отказ от сети. Линтер не ходит по внешним адресам: проверяются относительные пути, якоря и структура. Сетевая проверка ссылок — отдельная задача со своими проблемами (таймауты, антибот-защита, ложные отказы), и встраивать её в линтер значило бы сделать прогон недетерминированным. Из этого же следует, что зелёный doc не означает «все ссылки живые»: он означает «все локальные ссылки разрешаются».

flowchart LR
  ARGS["аргументы: --root, пути, --json"] --> LOAD["чтение дерева: только текстовые файлы"]
  LOAD --> RULES["набор правил: текст, структура, ссылки, приватность, метаданные"]
  RULES --> SKIP{"правило осмотрело хоть один объект?"}
  SKIP -- нет --> COV["coverage.skipped: не считается пройденным"]
  SKIP -- да --> FIND["находка: уровень, идентификатор, файл:строка"]
  COV --> REPORT["отчёт: текст или JSON"]
  FIND --> REPORT
  REPORT --> SCORE["оценка гигиены в процентах по весам"]

Коды возврата одинаковы для всех проверок, и это делает инструмент пригодным для CI без разбора текста:

flowchart TD
  ROOT["--root: каталог проверки"] --> BEH["поведение команды"]
  JSON["--json: машиночитаемый вывод"] --> BEH
  IGNORE["--ignore: список идентификаторов правил"] --> BEH
  WIKI["--include-wiki: осматривать исходники вики"] --> BEH
  NOPRIV["--no-privacy, --no-toc"] --> BEH
  PILLOW["Pillow: только PNG, ставится extras png"] --> PNG["assets render пишет SVG или PNG"]
  WHEEL["установка из колеса"] --> LIM["нет tests/ и шаблонов: selftest и install отказывают"]

Отдельного разговора заслуживают три команды, которые не проверяют ничего, но связывают набор с практикой. report собирает все проверки в один markdown-файл — его удобно положить в задачу или приложить к ревью, потому что человеку нужен один документ, а не шесть экранов вывода. snippet печатает готовый блок для AGENTS.md, который указывает другому агенту на этот набор: то есть передача знаний делается копированием одного блока, а не пересказом. install копирует сам набор — шаблоны, SKILL.md, тесты — в каталог навыков агента, с профилями под разные среды; работает только из клона, потому что в колесе этих файлов нет.

Из этого видна общая идея: инструмент рассчитан на то, что работу делает агент, а человек читает итог. Поэтому вывод любой проверки начинается с файл:строка и идентификатора правила, любая проверка умеет --json, а действия по умолчанию ничего не меняют — сначала отчёт, потом решение.

Замеры и цифры

Числа ниже — мои, получены на этой машине при установленном пакете 1.2.2: pip install --user github-agent-cli, затем запуск команд на подготовленной песочнице (каталог во временной папке, один README на три строки).

Оговорка о границах: замеры сделаны на одной машине (Windows, Python 3.13) и на намеренно бедном дереве. Процент гигиены — не свойство инструмента, а свойство проверяемого репозитория; здесь он показывает, как выглядит «пустой» проект в его глазах: 22,4 % при наличии одного README.

Почему это круто

• Один контракт вместо вкусовщины. «Хороший README» превращается в список пунктов с весами, и спор идёт про пункт, а не про вкус.
• Находки машинночитаемы. файл:строка плюс идентификатор правила и ключ --json — можно разбирать и ставить в CI без регулярных выражений по тексту.
• Ложный PASS наказан. Правило, осмотревшее ноль объектов, отмечается, а пустое дерево даёт отдельную ошибку.
• Ноль зависимостей. Ставится в любое окружение, работает без сети и без gh для большинства проверок.
• Вики — часть репозитория. wiki build, verify и publish работают с исходниками вики в дереве, а не с веб-интерфейсом.
• Публикация по явному флагу. wiki publish без --push — сухой прогон, --prune отдельно: удаление страниц остаётся решением человека.
• Три кода возврата. Ровно столько, сколько нужно CI, и ни одной двусмысленности.
• Готовые шаблоны файлов. В клоне лежит reference/ с шаблонами CONTRIBUTING, SECURITY, SCHEDULED и прочих — не надо сочинять заново.

Установка

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

pip install --user github-agent-cli
ghagent --version
# github-agent 1.2.2

Проверка установки — не «команда запустилась», а «команда отвечает на своём дереве»:

ghagent audit .
ghagent doc --root .

Если оба вернули 0, установка рабочая. Код 2 означает, что проблема в вызове, а не в репозитории.

Настройка

Файла конфигурации нет: всё задаётся аргументами. Это осознанно — инструмент должен работать в чужом репозитории, ничего там не создавая.

Порог в CI собирается из JSON без разбора текста: ghagent audit . --json отдаёт ключи counts (по уровням error, warn, info), data.score и data.rules_examined. Этого достаточно, чтобы валить сборку при появлении новой ошибки или при падении процента ниже зафиксированного.

# пример шага CI: код возврата уже говорит о находках уровня error
ghagent doc --root .
ghagent audit .

Проверка после установки

Вики как часть репозитория

Вики в этом наборе ведётся не через веб-интерфейс, а из самого репозитория: страницы лежат в каталоге wiki/, порядок задаёт wiki/wiki.json, а wiki build переписывает ссылки под плоское пространство имён — внутренние теряют .md, ссылки в дерево репозитория становятся абсолютными. Относительная картинка считается ошибкой, и это логично: вики-репозиторий не видит дерево проекта, поэтому такой путь не разрешится никогда.

Первая публикация упирается в особенность GitHub, о которой легко не знать: репозиторий <owner>/<repo>.wiki.git не существует, пока в веб-интерфейсе не сохранена хотя бы одна страница, и git push его не создаёт. В этом случае wiki publish возвращает отдельную ошибку wiki.remote-missing с указанием на этот шаг — то есть инструмент не делает вид, что проблема в сети.

Границы: что инструмент не проверяет

Последний пункт стоит проговорить: если документация должна находиться поиском, вики — не тот носитель. Для выдачи нужен GitHub Pages, и это решение уровня проекта, а не настройка линтера.

Подводные камни

• doc с каталогом в позиционном аргументе падает. Проверено: ghagent doc <путь-к-каталогу> даёт [ERROR] doc.unreadable … Permission denied и код 1, потому что позиционные аргументы — это файлы. Каталог передаётся через --root. Список правил при этом печатается, поэтому легко принять ошибку за «файл не тот».
• selftest из колеса не работает и не должен. Колесо несёт только CLI; команда завершается кодом 2 и предлагает клонировать репозиторий. Это не поломка, а честный отказ.
• privacy может вернуть 0 при полностью пустом результате. Правила, осмотревшие ноль объектов, попадают в coverage.skipped и печатаются как note: отсутствие находок ещё не означает, что проверка что-то смотрела.
• Оценка зависит от весов, а не от тяжести. Отсутствие лицензии стоит 8 пунктов, отсутствие CI — 6: проект без лицензии и без CI получит почти тот же минус, хотя юридические последствия разные.
• Действия без --write ничего не меняют. Это защита, но её легко принять за «команда не работает»: meta apply без флага — это отчёт о плане.
• Вики живёт в плоском пространстве. В ссылках нет .md, картинки — по абсолютным адресам; перенос обычных markdown-ссылок не работает, для этого и нужен wiki build.
• --prune удаляет страницы на сервере. Это единственная разрушительная операция в наборе, и она вынесена в отдельный флаг не случайно.
• PNG не появится без Pillow. assets render всегда пишет SVG; без extras png команда скажет, почему PNG нет, вместо того чтобы выдать SVG за готовое превью.

Чек-лист внедрения

1. Поставить пакет и зафиксировать версию: pip install --user github-agent-cli, затем ghagent --version.2. Запустить ghagent audit . и сохранить исходный процент — это база для сравнения.
2. Разобрать находки error сверху вниз по весам: сначала README, лицензия, CI.
3. Прогнать ghagent doc --root . и посмотреть не только находки, но и coverage.skipped.
4. Проверить ghagent privacy --root . — отдельно от документации, у неё своя область.
5. Поставить порог в CI: ghagent audit . --json плюс скрипт, который валит сборку при падении процента ниже зафиксированного.
6. Для вики: wiki build → wiki verify → прочитать сухой прогон publish → только потом --push.

Критерий «работает»: audit, doc и privacy возвращают 0 на вашем дереве, процент гигиены не падает между прогонами, а в CI красный статус появляется раньше, чем дефект документации дойдёт до читателя.

FAQ

Итог

github-agent решает узкую, но недооценённую задачу: делает документацию репозитория проверяемой. Тринадцать команд, ноль зависимостей, три кода возврата и находки с адресом — этого достаточно, чтобы поставить гигиену в CI и перестать обнаруживать дефекты документации через год после публикации. Главное, что стоит помнить при внедрении: процент — это сумма весов, а не оценка качества, doc принимает каталог только через --root, а coverage.skipped нужно читать так же внимательно, как сами находки.

Цитата: Репозиторий не падает из-за плохого README — он просто остаётся незамеченным, и именно поэтому проверку документации нужно ставить в CI рядом с тестами.

Связанные материалы

• github-agent — репозиторий — код, правила, шаблоны и документация.
• Релиз v1.2.2 — событийная публикация на PyPI и состав артефактов.
• github-agent-cli на PyPI — установка пакетными менеджерами.
• Плоская сеть и блокировка SMB — пример статьи, где проверки идут по шагам с критерием результата.
• Пакет включения Windows 11: переход на 25H2 и 26H2 — разбор скриптов, где гейты стоят до изменения системы.

LLM Summary

• Тема: github-agent 1.2.2 — Python-CLI ghagent для проверки и приведения в порядок репозитория GitHub и его вики; лицензия MIT, ноль зависимостей при запуске.
• Что проверяет: обязательные файлы с весами, контракт README и CHANGELOG, markdown-структуру, ссылки и якоря, оглавление, секреты и машинные пути, картинки, метаданные.
• Команды: 13 подкоманд — audit, doc, privacy, assets, wiki, changelog, meta, install, verify-install, uninstall, snippet, report, selftest.
• Коды возврата: 0 — ошибок нет, 1 — есть находки уровня error с файл:строка, 2 — ошибка вызова или окружения.
• Мои замеры: установлен 1.2.2; на минимальной песочнице audit дал 22,4 % при 27 пунктах, 12 error / 13 warn / 10 info, код 1; doc --root дал 1 ошибку doc.crlf и 10 правил в coverage.skipped; privacy вернул 0; selftest из колеса отказал с кодом 2.
• Грабли: doc с каталогом в позиционном аргументе падает (doc.unreadable), каталог передаётся --root; действия без --write ничего не меняют; --prune удаляет страницы на сервере; без Pillow PNG не создаётся.
• Установка: uv tool install, pipx, pip, brew, scoop; extras png добавляет Pillow; клон нужен для install, verify-install, snippet и selftest.
• Ограничение: колесо несёт только CLI, поэтому набор шаблонов и тестов доступен лишь из клона; порог по проценту в CI настраивается своим шагом, встроенного нет.
• Ссылки: https://github.com/paulmann/github-agent, https://pypi.org/project/github-agent-cli/

Промт для агента (установка и настройка)

Готовый промт для AI-агента: скопируйте блок целиком кнопкой и отдайте своему ассистенту. Шаги и формулировки взяты из AGENTS.md репозитория — это инструкция автора для агентов, а не пересказ; проверки дополнены моими замерами из раздела «Замеры и цифры».

Задача: привести репозиторий GitHub и его вики к проверяемому состоянию гигиены с помощью github-agent, не меняя ничего без явного флага.

Материалы:
- репозиторий: https://github.com/paulmann/github-agent
- релиз: https://github.com/paulmann/github-agent/releases/tag/v1.2.2
- контракт исполнителя (прочитать первым): https://github.com/paulmann/github-agent/blob/main/AGENTS.md
- правила целиком: docs/RULES.md, вики: docs/WIKI.md

Установка (одна из):
uv tool install github-agent-cli
pipx install github-agent-cli
pip install github-agent-cli
pip install "github-agent-cli[png]"        # только если нужен PNG
ghagent --version                          # ожидается github-agent 1.2.2

Клон нужен для install, verify-install, snippet и selftest:
git clone https://github.com/paulmann/github-agent.git
python tools/ghagent.py install --profile autoclaw --write

Проверка (все шесть должны вернуть 0):
ghagent selftest            # только из клона, из колеса отказ с кодом 2
ghagent doc --root .
ghagent audit .
ghagent changelog check
ghagent assets check
ghagent privacy --root .

Одна команда на задачу:
ghagent audit .                          # гигиена и оценка, код 1 при ошибках
ghagent doc --root .                     # markdown, ссылки, якоря, таблицы, оглавление
ghagent privacy --root .                 # токены, машинные пути, личные адреса
ghagent assets render --write            # баннер и социальное превью
ghagent wiki build && ghagent wiki verify
ghagent changelog release X.Y.Z --write
ghagent meta apply --repo owner/name --write

Непреложные правила из AGENTS.md:
- только измеренные числа, у каждой цифры назван источник;
- ни секретов, ни машинных путей, ни личных адресов в дереве, включая примеры;
- один H1 на документ и язык у каждого блока кода;
- вики — плоское пространство: без .md в ссылках, картинки по абсолютным адресам, есть sidebar и footer;
- публикация только по явному флагу: wiki publish без --push — сухой прогон, --prune удаляет страницы и это решение человека;
- CHANGELOG по Keep a Changelog 2.0.0: ISO-даты, новые сверху, ссылки сравнения;
- AGENTS.md остаётся картой до 120 строк, детали живут в docs/;
- ложный PASS хуже ложного FAIL: правило, осмотревшее ноль объектов, идёт в coverage.skipped, а пустое дерево даёт doc.no-text-files.

Запрещено:
- публиковать вики без wiki verify и без чтения сухого прогона;
- переписывать CHANGELOG из журнала коммитов: changelog suggest черновик, пишет человек;
- добавлять зависимость времени выполнения;
- править только .ru.md, оставляя английский оригинал позади;
- подписывать коммит именем агента;
- передавать каталог в ghagent doc позиционным аргументом: падает с doc.unreadable, каталог идёт через --root.

Что считать успехом: audit, doc и privacy возвращают 0, в CI процент гигиены не падает между прогонами, находки разбираются по file:line и идентификатору правила, а wiki publish выполнен только после verify.