Skip to content

README.ru.org

Latest commit

 

History

History
310 lines (256 loc) · 29.1 KB

README.ru.org

File metadata and controls

310 lines (256 loc) · 29.1 KB

MaGPT — универсальный и безопасный AI‑помощник для Git/Magit в Emacs

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

  • Если вы осваиваете Git, он показывает реальные команды Git и сочетания клавиш Magit в вашем текущем контексте — так вы понимаете «что» и «почему» в нужный момент, без необратимых действий.
  • Если вы опытный пользователь, он вовремя и ненавязчиво подсказывает, помогая избегать ошибок в сложных ситуациях — при этом вы всё время «держите руль».

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

Видение / Зачем и что это такое

MaGPT дополняет повседневную работу с Git в Emacs практичной поддержкой «preview‑first». Он начинался как качественный генератор сообщений коммитов и эволюционировал в небольшой расширяемый набор задач, помогающих:

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

MaGPT для тех, кому нужна надёжная помощь без сюрпризов: минимум контекста, явные подтверждения для «чувствительных» отправок, только обратимые действия и плотная интеграция с Emacs, Magit и gptel.

Возможности

  • Сообщения коммитов (Conventional Commits): створите ясный, лаконичный черновик по застейдженному диффу. Вставка — только по вашему выбору и только в обычный буфер коммита. Или оставьте превью и скопируйте.
  • AI‑обзор в Magit Status: компактная сводка с рисками и конкретными следующими шагами, включая:
    • Реальные команды Git, которые можно предварительно просмотреть/скопировать/вставить в eshell,
    • Сочетания клавиш Magit (по возможности, настраивается), чтобы учиться и быстро действовать.
  • Задачи без изменений (read‑only): объяснить текущее состояние, пролинтить уже написанное сообщение коммита, предложить имя ветки, объяснить хунк/регион.
  • Задачи «рекомендовать/разрешить» (всегда с превью): планы «stage‑by‑intent» (уровень файла, обратимые «Apply»), патч‑предложения для хунков (валидация через git apply –cached –check; применение только в индекс — под флагом), компактные сводки PR/диапазона коммитов, эскиз разрешения конфликта (только превью и проверка).

Все AI‑взаимодействия асинхронные и логируются; ничего не меняется без явного предпросмотра и подтверждения. Magit не обязателен, но является естественной средой.

Скриншот

Скрин MaGPT, встроенного в Magit Status, и transient меню AI‑действий:

./magpt.png

Установка

MaGPT — это один файл Emacs Lisp. Требуется Emacs 28.1+ и gptel 0.9+. Magit и transient — опциональны и используются при наличии.

  • Через MELPA (когда будет опубликован):
(package-install 'magpt)
(require 'magpt)
(magpt-mode 1)  ;; Необязательно: интеграция с Magit
  • С use-package (после установки gptel):
(use-package gptel :ensure t)

(use-package magpt
  :ensure nil                      ;; замените на t, когда появится в MELPA
  :load-path "/path/to/magpt/"
  :commands (magpt-generate-commit-message
             magpt-commit-staged
             magpt-explain-status)
  :init
  (magpt-mode 1))
  • С straight.el:
(straight-use-package '(magpt :type git :host github :repo "11111000000/magpt"))
(use-package magpt
  :after gptel
  :init (magpt-mode 1))
  • Вручную:
(add-to-list 'load-path "/path/to/magpt/")
(require 'magpt)
(magpt-mode 1)

Magit/transient — опциональны. Если они есть, MaGPT добавляет ненавязчивый пункт в меню коммита и компактный обзор в Magit Status.

Быстрый старт

  • Застейджьте изменения, откройте буфер коммита и выполните M-x magpt-generate-commit-message.
    • Вы увидите, что будет отправлено, и точный размер в байтах. Вы решаете — отправлять или нет.
    • Пока запрос выполняется, в буфере коммита появляется небольшая плашка (оверлей).
    • Результат вставляется сверху (над блоком комментариев) только если включена вставка; иначе — открывается в режиме только чтения и копируется в kill‑ring.
  • В Magit Status нажмите «.» для AI‑действий, затем «g» для обзора Explain Status. В предложениях:
    • Первая конкретная команда (например, «$ git …») — прямо в строке,
    • Сочетания клавиш Magit — при наличии,
    • Превью всех команд — через действие «p».

Почему это безопасно для новичков (и полезно для профи)

  • Превью‑сначала и обратимость: «Apply» ограничены естественно обратимыми шагами (напр., stage/unstage файлов, патчи только в индекс) и всегда требуют явного подтверждения.
  • Прозрачность: вы видите и можете копировать точные команды Git. Сочетания Magit берутся из ваших актуальных keymap’ов — без догадок.
  • Никакой фоновой автоматики: обзор сам по себе не запускает запросы. Ничего не коммитится и не применяется автоматически.
  • Минимальный контекст: запросы используют только необходимый минимум (напр., porcelain, staged‑дифф). Большие диффы безопасно усекутся по границам UTF‑8.
  • Можно полностью локально: используйте локальный бэкенд через gptel (напр., Ollama), чтобы не отправлять данные наружу.

Подсказка: пресет «режима обучения» (полностью без изменений):

(setq magpt-allow-apply-safe-ops nil)        ;; не изменять; только превью
(setq magpt-insert-into-commit-buffer nil)   ;; не вставлять в буфер коммита
(setq magpt-confirm-before-send t)           ;; всегда спрашивать подтверждение

Настройка провайдера (через gptel)

MaGPT не привязан к провайдеру и наследует конфигурацию gptel, если вы явно не задаёте magpt-model.

  • OpenAI:
(setq gptel-api-key (getenv "OPENAI_API_KEY"))
(setq magpt-model "gpt-4o-mini")   ;; или nil, чтобы наследовать из gptel
  • Anthropic (Claude):
(require 'gptel)
(setq gptel-backend
      (gptel-make-anthropic "anthropic"
                            :key (getenv "ANTHROPIC_API_KEY")
                            :chat-model "claude-3-5-sonnet"
                            :stream t))
(setq magpt-model nil)  ;; наследовать бэкенд/модель выше
  • Локально (Ollama):
(require 'gptel)
(setq gptel-backend (gptel-make-ollama "ollama" :host "localhost:11434"))
(setq magpt-model "llama3")  ;; или nil, чтобы наследовать выбор gptel

Использование (основные точки входа)

  • magpt-generate-commit-message Сгенерировать сообщение коммита по застейдженному диффу. Если открыт буфер коммита и включена вставка — записывает результат над блоком комментариев. Иначе — открывает read‑only буфер и копирует текст в kill‑ring.
  • magpt-commit-staged Если доступен Magit, открыть (или переиспользовать) буфер коммита и запросить сообщение для застейдженного диффа. Эквивалентно открытию буфера коммита и выполнению magpt-generate-commit-message.
  • magpt-mode Глобальный минор‑режим интеграции: добавляет пункт в коммит‑транзиент, компактный AI‑обзор в Magit Status и прямую клавишу «.» для AI‑действий.
  • magpt-explain-status Суммирует текущее состояние репозитория с обоснованием, рисками и конкретными следующими командами. Результаты записываются в историю и показываются в обзоре Magit.
  • magpt-show-log Открыть диагностический лог активности MaGPT (полезно при отладке провайдера или потока задач).

Примеры:

;; Черновик сообщения из застейдженного диффа в буфере коммита:
(M-x magpt-generate-commit-message)

;; Открыть буфер коммита Magit и заполнить его AI‑сообщением:
(M-x magpt-commit-staged)

;; Получить компактный обзор состояния и набор действий:
(M-x magpt-explain-status)

;; Включить интеграцию и обзор при старте Emacs:
(add-hook 'after-init-hook (lambda () (magpt-mode 1)))

Интеграция с Magit

При активном magpt-mode MaGPT интегрируется без изменения стандартных настроек Magit. В transient меню коммита появляется пункт для запроса сообщения по застейдженному диффу. В Magit Status добавляется компактный «AI overview (magpt)» с последним Explain Status и карточками отдельных задач.

Удобная связка — [. g]:

  • «.» в Magit Status открывает AI‑действия,
  • «g» запрашивает новые рекомендации и обновляет обзор.

Transient‑клавиши:

  • В magit-commit transient:
    • i — Commit with AI message (magpt) ⇒ magpt-commit-staged
  • В magit-dispatch (может варьироваться по версиям Magit/Transient; MaGPT добавляет надёжный «.»):
    • . — AI actions (magpt) ⇒ magpt-ai-actions
  • В magpt-ai-actions:
    • p — Предпросмотр команд предложения (read‑only shell‑буфер; показывает клавиши Magit при наличии)
    • y — Скопировать команды предложения в kill‑ring
    • s — Скопировать последнюю сводку в kill‑ring
    • g — Запросить новые рекомендации (Explain Status)
    • r — Перезагрузить действия из обзора

Предложения Explain Status включают сочетания клавиш Magit, если они известны. Клавиши выводятся в обзоре как «[keys: …]» и в заголовке превью AI‑действий. Модель получает «шпаргалку» клавиш, сформированную из ваших актуальных keymap’ов, и просят использовать только их (или оставлять пустой список). Переключение:

(setq magpt-include-magit-keys-in-suggestions t)  ;; по умолчанию t

Как снизить «шум»:

  • Включите компактный режим обзора:
(setq magpt-ui-density 'compact)
(setq magpt-overview-compact-max-risks 3)
(setq magpt-overview-compact-max-suggestions 3)

Концепции и архитектура

MaGPT использует малый реестр задач: каждая — это конвейер «собрать минимальный контекст → построить ясный промпт → отправить через gptel → отрисовать результат (опционально — безопасный Apply)». Задачи не зависят от провайдера и могут расширяться/заменяться. Эволюция проста:

  1. Наблюдать состояние,
  2. Рекомендовать безопасные действия с явными командами/клавишами,
  3. Помогать в сложных потоках — минимально и обратимо, через превью.

Расширенные задачи (включаются через magpt-enable-task-registry)

Реестр задач обеспечивает несколько read‑only и «preview‑first» операций:

  • Explain Status (объяснить текущее состояние; записать summary, риски и предложенные команды).
  • Commit Lint / Fix Suggest (проверить ваше сообщение и предложить вариант, совместимый с Conventional Commits).
  • Branch Name Suggest (безопасные имена веток в kebab‑case, с обоснованием и альтернативами).
  • Explain Hunk/Region (read‑only: объяснить выделенный регион в файле или хунк в Magit diff).
  • Stage by Intent (сгруппировать изменения в действия уровня файла stage/unstage; обратимый «Apply», под контролем magpt-allow-apply-safe-ops).
  • Stage by Intent (hunks via patch) (предложение патча в формате unified diff; проверка git apply –cached –check; опциональное применение только в индекс — под флагом).
  • PR/Range Summary (краткие title/summary/highlights/checklist по диапазону коммитов).
  • Resolve Conflict (here) (эскиз минимального патча; только превью и проверка).

Применить последний план Stage by Intent:

(M-x magpt-stage-by-intent)            ;; записать план в историю
(M-x magpt-stage-by-intent-apply-last) ;; stage/unstage на уровне файлов с подтверждением

Для патч‑предложений:

  • magpt-open-response-patch
  • magpt-check-response-patch

Все действия «Apply» защищены флагом magpt-allow-apply-safe-ops и явным подтверждением (y-or-n-p).

Безопасность и конфиденциальность

  • Подтверждение: большинство задач спрашивают разрешение перед отправкой содержимого. Explain Status умышленно «лёгкая» и использует минимальный контекст — по умолчанию без подтверждения. Вы всё равно можете посмотреть, что было отправлено, в истории/логе.
  • Контроль размера: перед отправкой показывается точный размер; большие диффы безопасно усекутся по границам UTF‑8.
  • Без скрытых изменений: без вашего согласия ничего не меняется. Сообщения вставляются только в обычные буферы коммита; «Apply» ограничен обратимыми действиями уровня файла или применением патча в индекс с проверками и подтверждением.
  • Только локально: можно держать всё локально через бэкенд gptel (например, Ollama).
  • Логи: диагностика пишется в буфер Emacs (magpt-log-buffer-name). Телеметрии нет.

Настройка

Опции можно задавать через Customize, init‑файлы или переопределять на проектном уровне через .magptrc в корне репозитория. Пользовательский RC (~/.magptrc) загружается первым; проектный имеет приоритет.

Пример проектного .magptrc:

'(
  (magpt-info-language . "English")
  (magpt-commit-language . "English")
  (magpt-enable-task-registry . t)
  (magpt-model . "gpt-4o-mini")
  (magpt-allow-apply-safe-ops . t))

Настройки (переменная, значение по умолчанию, описание):

ПеременнаяПо умолчаниюОписание
magpt-modelnilИмя модели для запросов gptel; nil — наследовать текущий бэкенд/модель gptel.
magpt-info-language“English”Предпочтительный язык для информативного контента (задачи, обзоры).
magpt-commit-languagenilПредпочтительный язык для сообщений коммита; nil — «без предпочтения».
magpt-commit-promptдлинный шаблонШаблон промпта для генерации сообщения коммита; дифф добавляется с явными маркерами.
magpt-max-diff-bytes200000Максимальный размер диффа (байты UTF‑8) при генерации; безопасная усечка при превышении.
magpt-insert-into-commit-buffertЕсли не nil — вставлять в живой буфер коммита; иначе открыть read‑only и копировать в kill‑ring.
magpt-project-root-strategyprefer-magitПоиск корня репозитория: prefer-magit, prefer-vc или prefer-project.
magpt-diff-args(“–staged” “–no-color”)Доп. аргументы для git diff при сборе застейдженных изменений.
magpt-confirm-before-sendtЗапрашивать подтверждение перед отправкой (зависит от задачи; Explain Status — исключение по замыслу).
magpt-allow-apply-safe-opstГейт для обратимых «Apply» (stage/unstage уровнем файла, применение патча в индекс).
magpt-rc-file-name“.magptrc”Имя проектного RC в корне репозитория.
magpt-user-rc-file”~/.magptrc”Путь к пользовательскому RC; грузится до проектного (nil — отключить).
magpt-log-enabledtВключить диагностическое логирование в magpt-log-buffer-name.
magpt-log-buffer-name”magpt-log”Имя буфера для диагностики.
magpt-commit-overlay-text“Message generation…”Текст оверлея в буфере коммита во время генерации.
magpt-enable-task-registrytВключить экспериментальный реестр задач (observe/recommend/resolve).
magpt-ui-densityregularПлотность UI в AI‑обзоре: regular или compact.
magpt-overview-compact-max-risks3Макс. число рисков в compact‑режиме для Explain Status.
magpt-overview-compact-max-suggestions3Макс. число предложений в compact‑режиме для Explain Status.
magpt-magit-overview-enabledtВставлять компактный «AI overview (magpt)» в Magit Status.
magpt-include-magit-keys-in-suggestionstДобавлять в подсказки клавиши Magit (из ваших keymap’ов), если применимо.

Примечание по локализации: MaGPT управляет языком модели по вашим настройкам (info/commit). Некоторые элементы UI локализованы на английский, русский и французский.

Сообщения коммитов — слово скептикам

Здесь коммиты не «автоматизируются»:

  • MaGPT создаёт аккуратный черновик (дружественный Conventional Commits) — и только.
  • Можно оставить режим только превью (без вставки).
  • Commit Lint / Fix Suggest проверяет ваше сообщение и предлагает минимальный, разумный вариант.
  • Никаких автокоммитов — никогда. Завершаете коммит как обычно (C-c C-c в Magit).

Если «называть вещи» трудно — MaGPT даёт надёжную базу, а «зачем» вы допишете своими словами.

Диагностика неполадок

  • «No staged changes found»: застейджьте что‑нибудь через Magit или git add и повторите.
  • Сообщение не вставилось: убедитесь, что открыт буфер коммита и magpt-insert-into-commit-buffer не nil. Иначе результат попадёт в read‑only буфер и в kill‑ring.
  • Медленные/пустые ответы модели: попробуйте другой бэкенд gptel или посмотрите лог через M-x magpt-show-log.
  • Git не найден: проверьте PATH внутри Emacs.
  • AI‑обзор пуст: откройте AI‑действия «.» и нажмите «g» для обновления. Обзор сам не делает фоновых запросов.

Совместимость и требования

  • Emacs 28.1+ и gptel 0.9+.
  • Git в PATH.
  • Magit и transient — опциональны; при наличии MaGPT добавляет пункты меню и обзор без изменения встроенных потоков.

FAQ

  • Это испортит мой репозиторий? Нет. «Apply» ограничены обратимыми шагами, защищены magpt-allow-apply-safe-ops и явным подтверждением (y-or-n-p). Можно полностью отключить Apply.
  • Автокоммиты есть? Нет. Никогда. Вы всё просматриваете и коммитите сами.
  • Нужен ли OpenAI? Нет. Используйте любой бэкенд gptel (Anthropic/Claude, Ollama локально и т.п.). MaGPT не привязан к провайдеру.
  • Что отправляется модели? Только минимально необходимый контекст для задачи (напр., porcelain, застейдженный дифф). Большие диффы безопасно усекутся; размер показывается заранее.
  • Можно убрать подсказки «keys» или уменьшить «шум»? Да. Установите magpt-include-magit-keys-in-suggestions в nil и включите magpt-ui-density ‘compact.

Участие

Issues и PR приветствуются. Пожалуйста, держите пользовательские изменения безопасными и обратимыми, предпочитайте провайдер‑агностичные промпты и документируйте новые задачи как конвейер «контекст → промпт → рендер/применение». Особая ценность — тесты для усечки UTF‑8, границ буфера коммита и обратимых операций.

Лицензия

MIT. См. LICENSE в репозитории.

Ссылки