github-agent 1.3.0: вики-проверки, сайт документации и упаковка

Обзор инструмента вышел в конце октября, и с тех пор у него появилось то, чего обычно не хватает подобным утилитам: понимание вики, собственный сайт документации и упаковка в пакеты для двух менеджеров. github-agent 1.3.0 — релиз про то, чтобы проверки не спотыкались о вики-разметку, а публикация не уезжала в PyPI без человека. Ниже — что именно изменилось, как это проверить и что показал мой прогон: обновление с 1.2.2 до 1.3.0, те же 13 команд и аудит на живом репозитории с результатом 100 % и кодом 0.

TL;DR: что нового и как проверить

1. Вики-разметка понимается. Ссылки на страницы вики резолвятся в Page.md, включая имена с точками; _Sidebar.md, _Footer.md, _Header.md — служебные файлы, а не «документы без заголовка».
2. Сайт документации. mkdocs.yml, страницы в docs/, сборка на каждый pull request и выкладка с main.
3. Статический анализ. ruff и mypy в CI и CodeQL с набором security-and-quality; рантайм-зависимостей по-прежнему ноль.
4. Черновик релиза вместо автопубликации. Workflow собирает тело из CHANGELOG и создаёт draft — PyPI не получает ничего, пока человек не нажмёт Publish.
5. Пакеты. Формула Homebrew и манифест Scoop плюс Windows-бандл в ассетах; отдельная CI-задача скачивает и сверяет хеши.

pip install --user --upgrade "github-agent-cli==1.3.0"
ghagent --version                 # github-agent 1.3.0
ghagent audit . --min-score 90    # у меня: score 100.0%, код 0
python tests/run_tests.py         # по заметкам к релизу: 194 из 194

Что нового в 1.3.0

flowchart TB
  REPO["репозиторий"] --> DOCS["документация: mkdocs, GitHub Pages"]
  REPO --> CI["CI: ruff, mypy, CodeQL, manifests"]
  REPO --> REL["release-draft: черновик из CHANGELOG"]
  REL --> HUMAN{"человек нажимает Publish?"}
  HUMAN -- да --> PYPI["публикация пакета"]
  HUMAN -- нет --> STOP["ничего не уходит"]
  REPO --> PKG["упаковка: Homebrew, Scoop, Windows-бандл"]

Ключевые изменения

Вики перестала быть «чужим форматом»

Раньше проверка локальных ссылок исходила из обычного репозитория: ссылка на Page без расширения — это ошибка, потому что на GitHub Pages такой файл даст 404. В вики правило другое: страница называется Page.md, и ссылка на неё корректна. Теперь инструмент определяет вики-чекаут по служебным файлам (_Sidebar.md или _Footer.md) и резолвит имена страниц, включая варианты с точками вроде Migration-3.x-to-4.0.

Заодно служебные файлы вики (_Sidebar.md, _Footer.md, _Header.md) перестали считаться документами без заголовка: им выставляется замечание, а не ошибка. Это мелочь ровно до того момента, когда CI краснеет из-за файла, который по определению не имеет H1.

Сборка документации и упаковка

Сайт на mkdocs — не «красивость», а способ держать документацию проверяемой: сборка идёт на каждом pull request, а хук hooks/repo_links.py перенаправляет ссылки, которые уводят за пределы docs/, на репозиторий, а не на несуществующую страницу.

Упаковка закрывает вопрос «а как это поставить без pip»: формула Homebrew ставит sdist из PyPI в виртуальное окружение с Python 3.13, манифест Scoop — Windows-бандл. В CI появилась задача, которая скачивает обе ссылки, сверяет SHA-256 и проверяет раскладку бандла: неверный хеш или устаревшая версия валят pull request.

Публикация перестала быть необратимой

release-draft.yml собирает тело релиза из CHANGELOG и создаёт черновик. Черновик не запускает publish.yml, поэтому в PyPI ничего не попадает до нажатия кнопки. Для инструмента, который сам проверяет чужие репозитории, это логично: ошибка в релизных заметках не должна становиться необратимой публикацией.

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

Снято 08.11.2026: обновление пакета через pip и аудит на реальном репозитории (PHP-Shield, 16 страниц вики, MIT).

Три вывода. Первый: набор команд не изменился — 13 и было 13, релиз про качество проверок, а не про новые подкоманды. Второй: аудит на ухоженном репозитории даёт ровно 100 % и код 0 — то есть проверки не «всегда что-то находят», а действительно различают состояние. Третий: хеши в заметках даны отдельно для сборок на раннере и для ассетов из тега, и это разные файлы одного коммита — сравнивать надо каждый со своим, а не один с другим.

Чего замеры не показывают: я не проверял работу вики-резолвера на реальном вики-чекауте и не собирал сайт на mkdocs — в репозитории, где гонялся аудит, сайт не настроен. Установку через Homebrew и Scoop тоже не проверял: у меня Windows без этих менеджеров и без Ruby. Эти части — по заметкам к релизу.

Установка и обновление

flowchart LR
  A["pip install --user -U github-agent-cli==1.3.0"] --> B["ghagent --version"]
  B --> C["ghagent audit . --min-score 90"]
  C --> D{"код 0?"}
  D -- да --> E["проход по репозиторию"]
  D -- нет --> F["смотреть таблицу проверок"]
  E --> G["ghagent doc, wiki verify, report"]

# обновление пакета
pip install --user --upgrade "github-agent-cli==1.3.0"
ghagent --version

# проверка на своём репозитории
cd /путь/к/репозиторию
ghagent audit . --min-score 90

Проверка после обновления

flowchart TD
  V1["версия: ghagent --version"] --> V2["свои тесты: python tests/run_tests.py"]
  V2 --> V3["аудит на живом репозитории: score и код"]
  V3 --> V4["док-проверки: ссылки, якоря, приватность"]

Совместимость

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

• Черновик релиза — это черновик. Он не публикует пакет, и если ждать автопубликации, релиз просто не выйдет: Publish нажимается руками.
• Хеши сборок разные. В заметках прямо сказано: файлы из PyPI собраны на раннере, ассеты релиза — из дерева тега. Сверять каждый со своим хешем, иначе получите ложное расхождение.
• Резолв вики зависит от служебных файлов. Если в каталоге нет _Sidebar.md и _Footer.md, ссылки будут проверяться по обычным правилам репозитория — и «страница без расширения» снова станет ошибкой.
• ignore_rules теперь влияет и на doc. Кто привык, что исключения действуют только в audit, увидит меньше ошибок в doc — это ожидаемо, но лучше знать заранее.
• Смягчённые правила скрывают долг. changelog.link-refs из ошибки стал предупреждением: CI позеленеет там, где раньше падал. Для нового репозитория это удобно, для старого — способ не заметить разъехавшиеся ссылки.
• Формула Homebrew ставит конкретную версию sdist. При обновлении ждите отставания между PyPI и формулой: livecheck подскажет, но обновлять надо отдельным PR.
• Аудит на «своём» репозитории может дать 100 %. Это не значит, что всё хорошо: проверки покрывают гигиену, а не логику. 100 % — про форму, не про содержание.

FAQ

Итог

1.3.0 — релиз зрелости: инструмент перестал спотыкаться о вики, получил проверяемую документацию, статический анализ и упаковку, а публикацию сделал ручной и потому предсказуемой. Мои замеры простые и проверяемые: обновление с 1.2.2 до 1.3.0 прошло, команд по-прежнему 13, аудит на ухоженном репозитории дал 100 % и код 0. Что стоит держать в голове — хеши PyPI-сборок и ассетов из тега не совпадают по определению, а смягчённые правила проверок могут скрыть накопленный долг в старом репозитории.

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

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

• github-agent: гигиена репозитория одной командой — обзор 1.2.2: команды, проверки, первые ловушки.
• Релиз v1.3.0 — заметки: вики, сайт документации, упаковка, хеши ассетов.
• Репозиторий github-agent — код, AGENTS.md, полевые заметки о дефектах.
• PHP Shield: файрвол для PHP — репозиторий, на котором я гонял аудит.
• Bash WP-CLI Update 8.1.0 — другой инструмент того же автора, тоже про проверяемость.

LLM Summary

• Тема: github-agent 1.3.0 — инструмент гигиены репозитория: вики-aware проверки, сайт документации, статический анализ, черновик релиза, упаковка.
• Новое: понимание вики в md.link-local (имена с точками), служебные файлы вики как замечание, сайт на mkdocs Material с хуком для внешних ссылок, ruff/mypy/CodeQL в CI, release-draft.yml (draft вместо автопубликации), Homebrew-формула, Scoop-манифест, Windows-бандл.
• Изменено: changelog.link-refs — предупреждение, changelog.types понимает подзаголовки, doc и privacy используют один обход дерева, doc читает ignore_rules, meta check --repo работает через gh api, audit пропускает отсутствующую вики.
• Замеры 08.11.2026: обновление github-agent-cli==1.3.0 через pip —user, ghagent --version → 1.3.0; в CLI 13 команд; ghagent audit . --min-score 90 на живом репозитории → score 100.0 %, 34 проверки, 0 пропущено, код 0.
• Хеши релиза: wheel 71 318 Б 1769712f…ff76; sdist 317 245 Б 759b65f4…e7ae; Windows-бандл 72 886 Б cd88d485…77fe.
• Важно: сборки PyPI и ассеты из тега — разные файлы одного коммита, сверять каждый со своим хешем.
• Не проверялось: вики-резолвер на реальном вики-чекауте, сборка mkdocs, установка через Homebrew и Scoop.
• Ссылки: https://github.com/paulmann/github-agent/releases/tag/v1.3.0, https://sysadministrator.ru/github-agent/

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

Готовый промт для AI-агента: скопируйте блок целиком. Шаги опираются на AGENTS.md репозитория github-agent и раздел Verification заметок к релизу.

Задача: обновить github-agent до 1.3.0 и прогнать проверки на своём репозитории, не меняя его содержимое.

Материалы:
- репозиторий: https://github.com/paulmann/github-agent
- контракт для агентов: https://github.com/paulmann/github-agent/blob/main/AGENTS.md
- релиз: https://github.com/paulmann/github-agent/releases/tag/v1.3.0

Шаг 1. Установить или обновить:
pip install --user --upgrade "github-agent-cli==1.3.0"
ghagent --version            # ожидается github-agent 1.3.0

Шаг 2. Сверить набор команд: ghagent --help
# ожидается 13 команд: audit, doc, privacy, assets, wiki, changelog, meta, install,
# verify-install, uninstall, snippet, report, selftest

Шаг 3. Аудит репозитория без изменений:
cd /путь/к/репозиторию && ghagent audit . --min-score 90
# код 0 — порог пройден; строки fail называют правило и объект

Шаг 4. Проверки документации: ghagent doc --root .
# в вики-чекауте (есть _Sidebar.md или _Footer.md) ссылки на страницы резолвятся в Page.md

Шаг 5. Свои тесты пакета: python tests/run_tests.py (по заметкам к релизу — 194 из 194)
Шаг 6. Единый отчёт: ghagent report .

Запрещено:
- править репозиторий во время аудита: проверки должны читать, а не менять;
- ждать автопубликации релиза: release-draft создаёт черновик, Publish нажимает человек;
- сверять хеш PyPI-сборки с хешем ассета релиза: это разные файлы одного коммита;
- считать score 100 % доказательством корректности кода: проверки про гигиену, а не про логику;
- отключать ignore_rules «чтобы позеленело»: правило теперь влияет и на doc, и на audit.

Что считать успехом: версия 1.3.0, 13 команд, аудит с кодом 0 и понятным score, отчёт без новых fail.