Интеграция Агентских Навыков (Agent Skills)

Обзор

В состав пакета codex-django входит опциональный автономный (offline) установщик и набор инструкций для AI-агентов под модулем codex_django.agent_skills.

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

Ключевые особенности:

Часть runtime-пакета и полная автономность: Установщик встроен в базовый пакет codex-django. Для его работы не требуется companion-пакет codex-django-cli (extra [cli]) или сконфигурированный Django (DJANGO_SETTINGS_MODULE не нужен).
Целевая директория: Устанавливается в .agents/skills/codex-django/ целевого проекта, а в корневой AGENTS.md добавляется ограниченный служебными маркерами блок.
Манифест владения: Файлы и их SHA-256 хэши фиксируются в .agents/skills/codex-django/.manifest.json.
Безопасные изменения: Команда update перезаписывает только файлы, принадлежащие установленной версии пакета. Проектные инструкции и правила должны размещаться в отдельных skills.
Строгие проверки целостности: Отказ от перезаписи при конфликтах с не принадлежащими библиотеке файлами, проверка повреждений разметки AGENTS.md, запрет symlinks и reparse points, а также staged транзакции с откатом (rollback) и сохранением резервных копий при сбое.

[!NOTE] Установщик записывает .agents/skills/ и корневой AGENTS.md. Файлы CLAUDE.md и настройки других агентов он пока не изменяет.

Команды

Установщик запускается через стандартный модуль Python в окружении, где установлен codex-django:

Параметр --project обязателен и должен указывать на существующую папку проекта. Для обычного использования Python-библиотеки устанавливать навык не требуется.

Windows (PowerShell / Командная строка)

# Проверка текущего статуса установки
python -m codex_django.agent_skills status --project D:\path\to\project

# Установка навыка в целевой проект
python -m codex_django.agent_skills install --project D:\path\to\project

# Обновление после повышения версии пакета codex-django
python -m codex_django.agent_skills update --project D:\path\to\project

# Удаление и очистка управляемых файлов
python -m codex_django.agent_skills delete --project D:\path\to\project

POSIX (Linux / macOS)

# Проверка текущего статуса установки
python -m codex_django.agent_skills status --project /path/to/project

# Установка навыка в целевой проект
python -m codex_django.agent_skills install --project /path/to/project

# Обновление после повышения версии пакета codex-django
python -m codex_django.agent_skills update --project /path/to/project

# Удаление и очистка управляемых файлов
python -m codex_django.agent_skills delete --project /path/to/project

Коды Возврата И Статус (Status)

Команда status позволяет программно проверить состояние навыка:

Код возврата 0: Возвращается только тогда, когда навык установлен, не поврежден, файлы соответствуют манифесту и версия совпадает с текущим установленным пакетом codex-django.
Код возврата 1: Возвращается, если навык отсутствует, устарел или повреждён: например, изменён управляемый файл, отсутствует манифест или нарушен блок AGENTS.md. Наличие дополнительных посторонних файлов само по себе не делает корректную установку повреждённой.

Примеры сообщений команды status:

Актуален: Installed and up to date. (код 0)
Не установлен: Not installed. (код 1)
Требуется обновление: Installed package version differs. Needs update. (код 1)
Поврежден/изменен файл: File on disk modified or corrupt: SKILL.md (код 1)
Ошибка маркеров: AGENTS.md instruction missing. или Orphan AGENTS.md block without ownership manifest. (код 1)

Жизненный Цикл Обновления

Обновление Python-библиотеки и синхронизация агентских навыков в проекте — это две независимые операции:

Обновление Python-пакета в окружении:
```
python -m pip install --upgrade codex-django
```
Обновление навыка в проекте из нового пакета:
```
python -m codex_django.agent_skills update --project /path/to/project
```

Команда update синхронизирует содержимое .agents/skills/codex-django/ с новой версией библиотеки, удаляет устаревшие файлы (если они были исключены из новой версии), обновляет .manifest.json и проверяет блок в корневом AGENTS.md.

Компактный Роутер И References vs Полная Документация

Структура навыка оптимизирована специально для работы языковых моделей:

Компактный роутер (SKILL.md): Легковесная точка входа, связывающая задачи разработчика (навигация в кабинете, бронирование, отправка сообщений, Redis) с целевыми файлами-справками. Агент читает SKILL.md, не перегружая контекстное окно.
Тематические справки (references/*.md): Описывают нужные API, точки расширения, пути к шаблонам и границы ответственности библиотеки и проекта. Агент читает относящиеся к задаче справки, а точные сигнатуры проверяет в установленном коде.
Полная документация (docs/ и MkDocs): Развернутые руководства, обучающие материалы, архитектурные схемы и API reference для чтения человеком на сайте или в репозитории.

Владение Файлами, Безопасность И Гарантии Отката

Ограниченный Блок В Корневом `AGENTS.md`

Установщик управляет изолированным блоком в файле AGENTS.md:

<!-- codex-django:skill:start -->
<!-- codex-django:skill:separator=1 -->
Use [codex-django](.agents/skills/codex-django/SKILL.md) for codex_django work.
<!-- codex-django:skill:end -->

Если в проекте уже есть AGENTS.md, блок аккуратно дописывается в конец с метаданными разделителя.
При удалении (delete): если AGENTS.md был создан установщиком с нуля и в него ничего не добавлялось, файл удаляется целиком; если в нем были другие инструкции, удаляется только изолированный блок библиотеки.
При ручном повреждении маркеров или тела блока мутации (update/delete) блокируются, защищая проектные правки от случайного стирания.

Разделение Прав Владения

В .manifest.json перечислены управляемые файлы навыка и их SHA-256. Дополнительные посторонние файлы в манифест не включаются.
update перезаписывает только файлы, принадлежащие библиотеке.
delete удаляет файлы из манифеста, в том числе отредактированные, и освобождённые папки этих файлов внутри каталога навыка. Посторонние файлы и родительская папка проекта .agents/skills сохраняются.
При обнаружении коллизии (в целевом пути уже существует файл, которого нет в манифесте) установка прерывается с ошибкой.
Проектные инструкции и кастомные правила необходимо размещать в отдельных skills проекта, а не дописывать в управляемый библиотекой SKILL.md.

Файловая Транзакция И Откат При Сбоях

Защита от symlinks: Каждый компонент пути проверяется через lstat. Наличие символических ссылок или точек повторной обработки Windows (reparse points) приводит к ошибке для исключения path traversal.
Staged запись: Изменения подготавливаются во временном каталоге на том же дисковом томе (.codex-django-tx-*).
Отсутствие ACID-гарантий при сбоях ОС: Механизм не гарантирует многофайловую атомарность при падении питания, ядра ОС или при параллельном запуске нескольких экземпляров утилиты.
Откат и сохранение резервных копий:
Перед началом перезаписи или удаления создаются копии всех затрагиваемых файлов.
При возникновении стандартных ошибок ввода-вывода (I/O error) процесс выполняет rollback к исходному состоянию.
Если откат по какой-либо причине не удался, временная папка с резервными копиями намеренно не удаляется, а путь к ней выводится в сообщении об ошибке для ручного восстановления.