Unity SDD: настройка рабочего каталога

Этот инструмент настраивает плагин для выбранного проекта без ручного обхода конфигов. Он хранится в том же GitHub-репозитории, что и плагин. Опубликованная версия CLI 0.2.0 поддерживает Codex и Claude Code. Рабочая версия исходников также добавляет Kimi; до отдельной публикации команды @latest эту возможность не получают. Grok пока не поддерживается установщиком: его выбор останавливает настройку до записи файлов.

Kimi: локальные компоненты, не глобальный плагин

Kimi получает во wrapper 21 маршрут навыков в .kimi-code/skills/, локальную запись unity_sdd_blender в .kimi-code/mcp.json и привязку .unity-sdd/kimi.json. Существующий AGENTS.md сохраняется с --keep-agents. Общие инструкции pipeline находятся в проверенном кэше ~/.unity-sdd/kimi/; UNITY_SDD_HOME позволяет выбрать другое место. Это не профиль Kimi: аккаунт, модели и авторизация остаются прежними. Запускайте обычный kimi из wrapper. Доверие к каталогу подтверждаете вы; установщик его не выдаёт. При доверенном запуске локальный Blender MCP может стартовать автоматически.

Для проверки неопубликованной реализации из каталога packages/cli:

node src/cli.js setup --client kimi --workspace "../MyGame-workspace" --kimi-bundle "../../plugins/kimi/unity-sdd-pipeline" --keep-agents
node src/cli.js setup --client kimi --workspace "../MyGame-workspace" --kimi-bundle "../../plugins/kimi/unity-sdd-pipeline" --keep-agents --apply
node src/cli.js doctor --client kimi --workspace "../MyGame-workspace"

После публикации используется обычный npm CLI без --kimi-bundle: пакет компонентов загружается из GitHub; нужен доступ к приватному репозиторию через Git. Локальный параметр предназначен для разработки и требует доверенного источника. Можно выбрать сразу --client codex,claude,kimi; настройки клиентов сосуществуют, документы pipeline общие.

Обновление общих ресурсов действует для всех wrapper этого кэша, без фиксации версии в документах проекта. Изменение списка/описаний навыков или конфигурации MCP требует отдельного обновления локальных проекций: текущий установщик обнаруживает такое изменение и останавливается, не оставляя другие workspace с несовместимыми настройками. Чужие записи MCP и навыки не перезаписываются; обнаруженный глобальный Unity SDD plugin или конфликт имён требует ручного согласования. Прочие глобальные инструменты Kimi не отключаются и не относятся к гарантии изоляции этого пакета.

В текущем pipeline нет отдельных файлов custom agents — они не создаются искусственно. doctor проверяет файлы, хеши и доступность CLI, но не заменяет проверку видимости навыков в новой сессии, доверия к workspace или подключения MCP.

На Windows поддерживаются как kimi.exe, так и npm-установка Kimi Code: установщик запускает её JavaScript entrypoint через Node без shell и без выполнения текста .cmd/.ps1. Для npm-версии Kimi соблюдайте также её собственные требования к Node — они могут быть строже требований этого установщика.

Новый wrapper можно настроить для нескольких клиентов без --keep-agents: текст генерируемых инструкций общий. Если инструкции уже существуют и отличаются (включая старый шаблон с упоминанием Codex), сначала прочитайте их и используйте --keep-agents для сохранения. Установщик не переписывает прежние инструкции автоматически.

Если настройка Kimi прервалась

Не повторяйте --apply вслепую и не удаляйте общий кэш или current.json. Сохраните сообщение ошибки и каталог backup, указанный установщиком. В <UNITY_SDD_HOME>/kimi/backups/<operation>/receipt.json записаны целевые пути, исходные хеши и ссылки на резервные копии; копии MCP могут содержать секреты, поэтому их нельзя публиковать целиком.

1. Убедитесь, что другой установщик не работает. Наличие install.lock само по себе не доказывает зависание: не удаляйте lock активного процесса.
2. Сопоставьте receipt, резервные копии, текущие файлы wrapper и общий указатель. Не восстанавливайте файлы поверх изменений другого пользователя или процесса.
3. После адресного восстановления либо завершения операции проверьте хеши бандла, локальные маршруты, MCP и общий указатель. Только после этого можно записать ручное решение о reconciliation и отметить receipt как reconciled.
4. Если доказано, что lock осиротел, его удаление допустимо только для этой операции. Затем повторите preview и doctor; отсутствие pending ещё не означает runtime PASS.

Автоматической команды repair/migrate в 0.3.0 нет. При конфликте состава навыков или MCP оставьте рабочий кэш нетронутым: нужен отдельный план обновления всех его wrapper. Удаление указателя ради обхода проверки не является поддерживаемой миграцией.

Порядок выпуска Kimi

До публикации npm сначала разместите проверенный plugins/kimi/unity-sdd-pipeline в GitHub main. Затем на чистом тестовом кэше проверьте setup без --kimi-bundle: локальный источник и существующий кэш не доказывают доступность доставки из GitHub. Только после успешной проверки публикуйте npm-кандидат. Живой запуск Kimi во wrapper остаётся отдельной проверкой после установки.

Несколько harness, один pipeline

После публикации 0.2.0 из одного wrapper:

npx --yes @6reduk/unity-sdd@latest setup --client codex --client claude --workspace "../MyGame-workspace"
npx --yes @6reduk/unity-sdd@latest setup --client codex --client claude --workspace "../MyGame-workspace" --apply
npx --yes @6reduk/unity-sdd@latest doctor --client codex --client claude --workspace "../MyGame-workspace"

Допустима также запись --client codex,claude. Для обновления замените setup на update. Все выбранные harness получают одинаковый путь к репозиторию и читают его общие AGENTS.md, governance и артефакты задач. Совместная установка не разрешает двум агентам одновременно перезаписывать один артефакт: распределяйте задачи/file scope.

У Codex остаются AGENTS.md, .codex/config.toml, .unity-sdd/workspace.json. Claude получает CLAUDE.md, .claude/settings.local.json, .unity-sdd/claude.json. Существующие файлы другого клиента не перезаписываются; разные repository bindings отклоняются. --keep-agents сохраняет существующий файл инструкций выбранного клиента (для Claude это CLAUDE.md), не подтверждая корректность его содержания.

Claude устанавливается штатно с --scope local. В пользовательском settings.json нашего плагина выставляется enabledPlugins["unity-sdd-pipeline@unity-sdd"] = false, во wrapper — true. Остальные поля, модели, auth и чужие плагины сохраняются. Используется CLAUDE_CONFIG_DIR либо стандартный ~/.claude. CLI нужно запускать с тем же окружением, что и соответствующий harness. GLM через Claude Code выбирается как --client claude; модель и её авторизация установщиком не настраиваются.

Установка клиентов выполняется последовательно и не является атомарной транзакцией. При ошибке CLI сообщает уже завершённые клиенты и путь к receipt; не повторяйте команду вслепую. Предыдущая установка другого workspace не считается установкой Claude для выбранного wrapper. Локальный marketplace с тем же именем не заменяется автоматически: сначала вручную согласуйте его источник.

Запуск новых сессий — отдельный шаг. Claude может автоматически запустить Blender MCP при загрузке включённого плагина; setup/doctor не запускают сессию модели и не вызывают MCP. Проверки файлов и native inventory не доказывают видимость навыков, соблюдение gates моделью или отсутствие дополнительных managed/ancestor policies.

npm run verify проверяет также установленный tarball: preview/setup/update/doctor, идемпотентность, совместную настройку Codex+Claude, сохранность существующих файлов, неподдержанные клиенты и восстановление global opt-out после ошибки. Native CLI в этом автоматическом тесте заменены синтетическими subprocess fixtures; живой пилот не следует из PASS тестов.

Публичный npm-пакет называется @6reduk/unity-sdd. GitHub-репозиторий плагина остаётся приватным: установка CLI не выдаёт доступ к нему.

Запуск из npm

После выхода первой версии клонировать исходники установщика не требуется:

npx --yes @6reduk/unity-sdd@latest setup --client codex --workspace "../MyGame-workspace"
npx --yes @6reduk/unity-sdd@latest setup --client codex --workspace "../MyGame-workspace" --apply
npx --yes @6reduk/unity-sdd@latest doctor --client codex --workspace "../MyGame-workspace"

Обновление: update вместо setup, сначала без --apply. @latest выбирает актуальный установщик. Версия плагина общая для всех workspace; глобальное включение выключается, проектные включения сохраняются. Ниже также описан запуск из исходников.

Что такое wrapper

Обычная папка, из которой запускается Codex. Внутри неё — репозиторий игры:

MyGame-workspace/               ← запускать Codex здесь; НЕ Git-репозиторий
  AGENTS.md                    ← короткий указатель на проект и его правила
  .codex/config.toml           ← включение плагина для этого wrapper
  .unity-sdd/workspace.json    ← относительный путь к репозиторию
  project/                    ← Git-репозиторий игры
    .git/
    AGENTS.md                 ← общие инструкции проекта для всей команды
    docs/                     ← регламенты, архитектура, backlog, задачи, архив
      governance/pipeline.yaml
    Assets/                   ← пример: Unity может лежать и глубже
    Packages/
    ProjectSettings/

Настройки wrapper остаются на компьютере разработчика. Общая документация и проектные инструкции коммитятся внутри project. Путь к Unity определяется pipeline.yaml, не именем папки. Инструмент не переносит и не клонирует игру, не архивирует старую документацию и не создаёт второй pipeline во wrapper.

Подготовка

Нужны Node.js 22+ с npm, установленный Codex CLI, Git-доступ к приватному 6reduk/unity-sdd-pipeline. Для клонирования ниже нужен авторизованный gh. Проверьте node --version, npm --version, codex --version, gh auth status. Установка клиентов и авторизация не автоматизируются. Python нужен отдельно валидаторам самого плагина — см. руководство Codex.

Откройте терминал в папке для инструментов:

gh repo clone 6reduk/unity-sdd-pipeline
cd unity-sdd-pipeline
npm --prefix packages/cli ci --ignore-scripts

Если репозиторий уже есть — откройте его вместо повторного клонирования. Не вставляйте токены в команды. CLI не копирует ключи.

Установка

Замените ../MyGame-workspace на путь к вашему wrapper. Все команды ниже выполняются из репозитория плагина. Путь с пробелами оставляйте в кавычках.

node packages/cli/src/cli.js setup --client codex --workspace "../MyGame-workspace"

Это предварительный просмотр: файлы не создаются, команды Codex не запускаются. План показывает пути/действия, но не содержимое секретов. Если репозиторий игры лежит не в project, добавляйте --repository "имя-папки" во все команды.

Закройте параллельные редакторы конфигов. После проверки плана примените его:

node packages/cli/src/cli.js setup --client codex --workspace "../MyGame-workspace" --apply

Инструмент:

1. Проверит CLI и адрес marketplace; сохранит резервные копии изменяемых файлов. Для нового профиля сначала создаст пустой CODEX_HOME: этого требует native CLI.
2. Выключит плагин в пользовательском конфиге и включит во wrapper .codex/config.toml.
3. Создаст wrapper AGENTS.md, запись относительного пути и пустую папку project, если их ещё нет. Игру нужно поместить туда отдельно.
4. Зарегистрирует отсутствующий marketplace и установит отсутствующий плагин штатными командами Codex. Затем повторно применит глобальное отключение.

Модель, авторизация, доверие, сторонние плагины и MCP не перенастраиваются. Если wrapper AGENTS.md уже есть и отличается, CLI остановится. Прочитайте файл: если он правильно направляет агента в проект, передайте --keep-agents — текст останется без изменений. Это не делает старый pipeline совместимым автоматически. Вложенный project/.codex/config.toml требует отдельного разбора, а не удаления.

Откройте Codex из wrapper, рассмотрите запрос доверия и создайте новую сессию. Доверие подтверждает пользователь: недоверенный проектный конфиг может игнорироваться. Запуск из вложенного Git-каталога имеет другую область настроек.

Проверка

node packages/cli/src/cli.js doctor --client codex --workspace "../MyGame-workspace"

Команда ничего не исправляет. Проверяет конфиги, источник marketplace, относительный путь, наличие репозитория/инструкций/регламента, журнал операций и plugin list. Код выхода 0 — проверки прошли, 2 — есть непройденные пункты, 1 — ошибка запуска/формата. Наличие pipeline.yaml не доказывает корректность его содержимого. Новая пустая папка игры ожидаемо не пройдёт все проверки.

В новой сессии Codex отдельно попросите:

Проведи read-only preflight Unity SDD. Покажи, доступны ли навыки unity-*; прочитай wrapper AGENTS.md, определи Git root и Unity root по регламенту проекта. Ничего не меняй, не запускай Unity/Blender. Отдели установленный пакет, навыки текущей сессии и непроверенную связь с Editor.

В другом проекте codex plugin list --json должен показывать enabled: false, если там нет собственного включения. CLI не сканирует и не отключает другие wrapper: ранее настроенные Unity-проекты могут оставаться включёнными.

Первичная инициализация AGENTS.md самой игры

Автоматически создаётся только wrapper AGENTS.md. Инструкции игры нельзя угадать. После проверки установки передайте Codex такой запрос:

Изучи выбранный репозиторий только на чтение. Найди настоящий Unity root, существующие инструкции и документацию. Предложи минимальный проектный AGENTS.md, docs/governance/pipeline.yaml и структуру docs для Unity SDD. Сохрани ссылки на существующую истину, перечисли конфликты старого workflow. Не изменяй код, сцены, ассеты и старые документы. Покажи план и дождись моего согласия перед записью.

Для уже мигрированного проекта повторная инициализация не нужна.

Обновление

Сначала обновите инструмент в его Git-каталоге. Собственные изменения не сбрасывайте:

git pull --ff-only
npm --prefix packages/cli ci --ignore-scripts
node packages/cli/src/cli.js update --client codex --workspace "../MyGame-workspace"
node packages/cli/src/cli.js update --client codex --workspace "../MyGame-workspace" --apply
node packages/cli/src/cli.js doctor --client codex --workspace "../MyGame-workspace"

Для сохранённых нестандартных wrapper-инструкций снова передавайте --keep-agents. update обновляет marketplace и переустанавливает пакет. Установка общая в CODEX_HOME: обновление затронет все использующие её проекты. Только включение ограничивается проектными конфигами; отдельных версий по проектам CLI не обещает.

Если операция прервалась

Копии и журнал: CODEX_HOME/unity-sdd-backups/<run-id>/; обычно CODEX_HOME — .codex в домашней папке. Путь выводится в результате. Копии могут содержать секреты: не коммитьте и не отправляйте их в отчёты. Проверьте ACL на общей машине.

CLI старается вернуть глобальное отключение даже после ошибки установки. Если конфиг стал невалидным/недоступным, это нельзя гарантировать: результат будет ошибкой. Журнал pending/needs_reconciliation блокирует повторный apply в этом CODEX_HOME. Автоматического отката нет: он мог бы уничтожить новые изменения другого процесса. Preview и doctor остаются доступны.

Попросите специалиста сопоставить receipt.json, конфиги и вывод codex plugin marketplace list --json / codex plugin list --json, восстановить только необходимые значения и проверить глобальное отключение. После фактической сверки можно отметить журнал state: "reconciled" и записать пояснение сверки. Не ставьте статус только для обхода ошибки. Осиротевший lock удаляют лишь убедившись, что установщик не работает. Не заменяйте весь конфиг старой копией вслепую.

Разработка и ограничения

npm --prefix packages/cli test
npm --prefix packages/cli run check
npm pack ./packages/cli --dry-run

Один пакет: общий scaffold/план/резервирование и адаптеры harness в src/adapters/. GLM через Claude Code не требует отдельного установочного движка. Для Grok сначала нужно выбрать agent host. Будущие адаптеры должны проверять свои правила project scope. Нет postinstall, shell-интерполяции путей, автоматической установки клиентов. Необычные TOML-layouts и symlink/junction-пути блокируются. Таймаут CLI не доказывает отсутствия побочных эффектов — для этого существует сверка журнала. Конкурентная правка внешним процессом не является транзакцией: закрывайте редакторы конфигов.

Unit-тесты используют временные каталоги и имитацию Codex. Отдельный smoke-test на Windows/Codex 0.153.4 установил плагин из GitHub в пустой изолированный CODEX_HOME: global opt-out и wrapper opt-in подтверждены. Недоверенный wrapper ожидаемо остался неактивным; выдача доверия и доступность навыков в новой сессии не проверялись этим CLI. macOS/Linux требуют отдельного smoke-test. Автоматизация выпуска: RELEASING.md. Kimi поддерживается рабочим кандидатом 0.3.0 через проектные компоненты. Grok npm-адаптер пока не реализован.