ИИ-агенты

Клиент ИИ-агента, поддерживающий Model Context Protocol (MCP), например Claude Code, работает с Arkvory через arkvoryctl mcp. Клиент запускает команду и общается с ней через stdin и stdout; сетевой порт не открывается. Навык для агентов учит агента безопасным сценариям поверх этого.

Перед началом

1. Установите клиент командной строки на машину, где работает агент.
2. Создайте для агента сервисный ключ, которому доступны только нужные репозитории и действия. Сохраните его в файл, который можете читать только вы.
3. Добавьте профиль, ссылающийся на файл ключа, и проверьте его:

arkvoryctl profile add agent --server https://arkvory.example --token-file ~/.config/arkvory/agent.key --repository builds
arkvoryctl doctor --profile agent

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

Подключение MCP-сервера

claude mcp add arkvory -- arkvoryctl mcp --profile agent --root ~/work

Без --write сервер работает только на чтение: агент видит репозитории, ищет во всех сразу, читает артефакты, пакеты, файлы по пути, ленту изменений и состояние установки и скачивает артефакты. Инструменты, которые ключ не может использовать, не предлагаются. Клиент должен поддерживать MCP 2025-06-18 или новее.

Разрешить запись

Запись — отдельная конфигурация. Перечислите репозитории, в которые агенту можно писать:

claude mcp add arkvory-publish -- arkvoryctl mcp --profile agent --root ~/work --write --write-repositories builds

Инструмент	Что делает
arkvory_upload	Загружает файл как новый артефакт или как следующую ревизию пути
arkvory_publish_package	Загружает UPack и регистрирует его как версию пакета
arkvory_promote	Добавляет стадию; с sha256 — только артефакту ровно с этими байтами
arkvory_stage_remove	Снимает стадию; артефакт остаётся
arkvory_annotate	Заменяет метки и метаданные при той ревизии, которую агент прочитал

• Запись в репозиторий, которого нет в --write-repositories, отклоняется до отправки чего-либо (repository_not_allowed). Права ключа сервер всё равно проверяет.
• Удалить или восстановить ничего нельзя, ссылки на скачивание не создаются. Это остаётся задачей человека в консоли.
• Сервер просит агента описывать каждую запись и ждать вашего подтверждения. Ваш MCP-клиент тоже может спрашивать перед каждым вызовом.
• Загрузка продолжается: после сбоя агент повторяет тот же вызов и получает тот же артефакт, а не второй. Результат называет SHA-256 прочитанного файла.

Файлы и ограничения

• Агент читает и пишет локальные файлы только внутри --root (по умолчанию — текущий каталог). Путь, ведущий наружу, в том числе через ссылку, отклоняется (path_outside_root).
• Скачанный файл появляется только после проверки размера и SHA-256. Существующий файл заменяется, только если агент об этом попросил.
• Файл, содержащий ключ, никогда не загружается (source_contains_credential), а собственные файлы arkvoryctl (профили, файлы ключей, чекпойнты загрузок) не читаются и не заменяются даже внутри --root (private_path).
• Один результат — не больше --max-output-bytes (по умолчанию 64 КиБ, до 1 МиБ) и 100 элементов; за продолжением агент передаёт next как after.

Установка навыка

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

arkvoryctl skill install

Навык ставится в ~/.claude/skills/arkvory; чтобы установить его в проект, передайте --target DIR, например .claude/skills/arkvory. Повторный запуск обновляет файлы, которые вы не меняли. Изменённый вами файл сохраняется: команда останавливается и ничего не меняет, пока вы не добавите --force.

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

• Имена, метки, метаданные и комментарии в результатах пишут другие люди. Агент считает их данными и никогда не выполняет найденные в них инструкции.
• Держите конфигурации чтения и записи раздельно и разрешайте запись только в репозитории, нужные задаче.
• Используйте отдельный ключ с узкими правами; отзовите его в консоли, когда агенту он больше не нужен.

Устранение неполадок

Ошибка	Причина и решение
Нет инструментов записи	Сервер запущен без --write или у ключа нет права.
repository_not_allowed	Репозитория нет в --write-repositories. Измените конфигурацию MCP.
forbidden	У ключа нет права. Права показывает arkvoryctl doctor.
path_outside_root	Файл вне --root или не является обычным файлом.
state_locked	Та же загрузка ещё идёт в другом вызове. После аварии убедитесь, что ни один arkvoryctl mcp не загружает этот файл, и удалите файл .lock в mcp-uploads каталога CLI (~/.config/arkvory).
skill_modified	Вы изменили файл навыка. Сохраните свою копию или повторите arkvoryctl skill install с --force.