Git-операции

Инструмент git_operations предоставляет агентам PRX возможности управления версиями через унифицированный интерфейс. Вместо требования вызывать команды git через инструмент shell (который подчиняется ограничениям песочницы), git_operations предлагает структурированный безопасный API для наиболее распространённых Git-сценариев: проверка статуса, просмотр различий, создание коммитов, push, pull, просмотр истории и управление ветками.

Инструмент работает с репозиторием рабочего пространства, который обычно является каталогом проекта, где работает агент. Он зарегистрирован в реестре all_tools() и всегда доступен при запуске агента с полным набором инструментов.

Предоставляя Git как полноценный инструмент, а не shell-команду, PRX может применять детальные политики безопасности, валидировать аргументы и выдавать структурированный вывод, который LLM может надёжно разобрать.

Конфигурация

Инструмент git_operations не имеет отдельного раздела конфигурации. Его поведение контролируется путём рабочего пространства и политикой безопасности:

# Политика инструмента для git-операций
[security.tool_policy.tools]
git_operations = "allow"    # "allow" | "deny" | "supervised"

Репозиторий рабочего пространства определяется текущим рабочим каталогом сессии агента. Если агент запущен внутри Git-репозитория, используется этот репозиторий. В противном случае инструмент возвращает ошибку об отсутствии репозитория.

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

Инструмент git_operations принимает параметр operation, указывающий выполняемое Git-действие:

status

Проверка текущего состояния репозитория (подготовленные, неподготовленные, неотслеживаемые файлы):

{
  "name": "git_operations",
  "arguments": {
    "operation": "status"
  }
}

Возвращает структурированный вывод, показывающий:

• Имя текущей ветки
• Файлы, подготовленные для коммита
• Изменённые, но неподготовленные файлы
• Неотслеживаемые файлы
• Статус отслеживания upstream

diff

Просмотр изменений в рабочем дереве или между коммитами:

{
  "name": "git_operations",
  "arguments": {
    "operation": "diff"
  }
}

{
  "name": "git_operations",
  "arguments": {
    "operation": "diff",
    "args": ["--staged"]
  }
}

{
  "name": "git_operations",
  "arguments": {
    "operation": "diff",
    "args": ["HEAD~3..HEAD"]
  }
}

commit

Создание коммита с сообщением:

{
  "name": "git_operations",
  "arguments": {
    "operation": "commit",
    "message": "fix: resolve race condition in session cleanup"
  }
}

{
  "name": "git_operations",
  "arguments": {
    "operation": "commit",
    "message": "feat: add web search provider selection",
    "args": ["--all"]
  }
}

push

Отправка коммитов в удалённый репозиторий:

{
  "name": "git_operations",
  "arguments": {
    "operation": "push"
  }
}

{
  "name": "git_operations",
  "arguments": {
    "operation": "push",
    "args": ["origin", "feature/web-search"]
  }
}

pull

Получение изменений из удалённого репозитория:

{
  "name": "git_operations",
  "arguments": {
    "operation": "pull"
  }
}

log

Просмотр истории коммитов:

{
  "name": "git_operations",
  "arguments": {
    "operation": "log",
    "args": ["--oneline", "-20"]
  }
}

branch

Список, создание или переключение веток:

{
  "name": "git_operations",
  "arguments": {
    "operation": "branch"
  }
}

{
  "name": "git_operations",
  "arguments": {
    "operation": "branch",
    "args": ["feature/new-tool"]
  }
}

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
operation	string	Да	--	Git-операция: "status", "diff", "commit", "push", "pull", "log", "branch"
message	string	Условно	--	Сообщение коммита (обязательно для операции "commit")
args	array	Нет	[]	Дополнительные аргументы, передаваемые Git-команде

Возвращает:

Поле	Тип	Описание
success	bool	true если Git-операция завершилась успешно
output	string	Вывод Git-команды (текст статуса, содержимое различий, записи журнала и т.д.)
error	string?	Сообщение об ошибке при неудачной операции

Типичные сценарии

Рабочий процесс с feature-веткой

Типичный сценарий работы агента с feature-веткой:

1. [git_operations] operation="branch", args=["feature/add-search"]
2. [file_write] запись новых файлов
3. [git_operations] operation="status"  -- проверка изменений
4. [git_operations] operation="diff"    -- обзор изменений
5. [git_operations] operation="commit", message="feat: add search functionality", args=["--all"]
6. [git_operations] operation="push", args=["-u", "origin", "feature/add-search"]

Подготовка к код-ревью

Проверка изменений перед коммитом:

1. [git_operations] operation="status"
2. [git_operations] operation="diff", args=["--staged"]
3. [git_operations] operation="log", args=["--oneline", "-5"]
4. Агент анализирует diff и предлагает улучшения

Разрешение конфликтов

Проверка и разрешение конфликтов слияния:

1. [git_operations] operation="pull"
2. При наличии конфликтов: [git_operations] operation="status"
3. [file_read] чтение конфликтующих файлов
4. [file_write] разрешение конфликтов
5. [git_operations] operation="commit", message="merge: resolve conflicts in config.toml"

Безопасность

Сравнение с Shell

Использование git_operations вместо запуска git через инструмент shell обеспечивает несколько преимуществ безопасности:

• Валидация аргументов: Параметры проверяются перед выполнением, предотвращая атаки внедрения
• Структурированный вывод: Результаты разбираются и возвращаются в предсказуемом формате
• Без shell-раскрытия: Аргументы передаются напрямую в Git без интерпретации shell
• Детальная политика: git_operations может быть разрешён, в то время как shell запрещён или переведён в режим наблюдения

Защита от деструктивных операций

Инструмент включает защиту от распространённых деструктивных операций:

• Принудительная отправка: Аргументы --force и --force-with-lease логируются с предупреждениями
• Удаление веток: Операции -D (принудительное удаление) отмечаются в журнале аудита
• Операции сброса: Жёсткие сбросы не предоставляются напрямую через инструмент

Для максимальной безопасности отметьте git_operations как supervised:

[security.tool_policy.tools]
git_operations = "supervised"

Обработка учётных данных

Инструмент git_operations использует системное хранилище учётных данных Git (помощник учётных данных, SSH-ключи и т.д.). Он не раскрывает и не логирует учётные данные. Удалённые операции (push, pull) полагаются на предварительно настроенные учётные данные Git на хосте.

Журнал аудита

Все Git-операции записываются в журнал аудита при его включении:

• Тип операции (status, commit, push и т.д.)
• Аргументы
• Статус успешности/неудачи
• SHA коммита (для операций commit)

Связанные разделы

• Выполнение shell -- альтернатива для продвинутых Git-команд
• Файловые операции -- чтение/запись файлов в репозитории
• Сессии и агенты -- делегирование Git-задач специализированным агентам
• Движок политик -- контроль доступа для Git-операций
• Обзор инструментов -- все инструменты и система реестра