1C AI Sandbox Client Server

Песочница для ИИ‑агента под 1С (клиент + серверная инфраструктура)

Этот репозиторий — песочница под ИИ‑агента и инфраструктура, где агент работает с платформой 1С. Зачем это нужно? - Что бы ИИ-агент по ошибке вам что нито не удалил (например, весь диск D... или C) Думаете с Вами точно такого не случится? - Я тоже так думал. А потом потерял 10 лет семейных фото и пошел делать песочницу :)

Всё разделено на две части:

• Клиентская часть (Dev Container): Linux‑контейнер с установленной платформой 1С для клиента (толстый/тонкий клиент, в т.ч. Конфигуратор) + “обвязка”, чтобы инструменты 1С стабильно работали в headless‑режиме.
• Серверная часть (VM в Hyper‑V): отдельная Ubuntu VM, внутри неё Docker Compose со связкой 1С сервер + Postgres + Apache (веб‑публикации).
• разработано под VSC/Cursor. Совместимпость с другими IDE не гарантирована

Архитектура (схема)

                        Windows host
┌───────────────────────────────────────────────────────────────────────────┐
│  Cursor / VS Code + Dev Containers                                        │
│  Docker Desktop                                                           │
│  Hyper‑V                                                                  │
└───────────────┬───────────────────────────────┬───────────────────────────┘
                │                               │
                │ Dev Container                 │ VM (Hyper‑V)
                v                               v
┌───────────────────────────────────┐   ┌──────────────────────────────────┐
│ Клиентская песочница (container)  │   │ Серверная часть (Ubuntu VM)      │
│                                   │   │                                  │
│  agent (Linux)                    │   │  docker + docker compose         │
│   - 1С клиент + Конфигуратор      │   │   - onec-server                  │
│   - Xvfb :99 (headless display)   │   │   - postgres                     │
│                                   │   │   - onec-web (Apache)            │
│   - community-активация КЛИЕНТА   │   │                                  │
│     (если заданы DEV_* креды)     │   │  Порты наружу: 1540/1541/1545,   │
│                                   │   │  1560-1591, 5432, 8080           │
│                                   │   └──────────────────────────────────┘
│  Volumes:                         │
│   - workspace volume              │
│   - onec-licenses volume          │
│                                   │
│  Networking:                      │
│   - docker network "infra"        │
│   - /etc/hosts: onec-infra ->     │
│     management IP VM (если задан) │
└───────────────────────────────────┘

Связь: контейнер управляет/подключается к 1С‑серверу в VM по MGMT IP или имени onec-infra.

Ограничения

• Хост‑окружение, где проверено: Windows (Hyper‑V + PowerShell) как хост для серверной части.
• Linux‑хосты (KVM/QEMU/VirtualBox, бриджи/iptables и т.п.) не тестировались.

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

1) Серверная инфраструктура (Hyper‑V VM)

Сначала подними серверную часть — без неё клиентская песочница не сможет нормально подключаться к 1С‑серверу.

• Подготовь non‑secret конфиг VM:
  • скопируй infra/vm/.env.example → infra/vm/.env
  • в основном можно оставить параметры по-умолчанию; обрати внимание на FORCE_RECREATE_VM (принудительно Пересоздает виртуальную машину) и на размер диска виртуальной машины.
• Подготовь локальные секреты:
  • скопируй secrets/.env.example → secrets/.env
  • заполни нужные логин/пароли
  • DEV_LOGIN и DEV_PASSWORD сейчас рекомендуется не заполнять: авто‑активация community‑лицензии на стороне платформы сейчас сломана. В личном кабинете активация проходит, но платформа отвечает ошибкой формата. Если эти секреты оставить пустыми, шаг активации будет пропущен и сценарии установки не будут считать это ошибкой.
• Перед запуском скрипта убедись, что Docker Desktop / Docker Engine на хосте уже запущен: он используется в процессе подготовки образа виртуалки.
• Запускай скрипт из корня этого репозитория и из PowerShell от администратора.
• Рекомендуемый запуск:

pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\tests\SmokeTest-OnecInfra.ps1

• Дождись успешного завершения скрипта (PASS).
• Для удобства работы с сервером 1С с хост‑системы рекомендуется добавить запись в hosts, чтобы VM резолвилась по имени:
  • <MGMT_VM_IP> onec-infra
  • MGMT_VM_IP — management IP VM из infra/vm/.env
  • (прим.: 192.168.254.2 onec-infra)

После успешной развёртки у тебя есть VM с Ubuntu + Docker и внутри неё подняты контейнеры onec-server, postgres и onec-web (Apache для веб‑публикаций).

Веб‑публикация (web‑клиент + HTTP‑сервисы)

pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\hyperv\Publish-OnecInfobase.ps1 -Action Publish -InfobaseName demo
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\hyperv\Publish-OnecInfobase.ps1 -Action Update  -InfobaseName demo
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\hyperv\Publish-OnecInfobase.ps1 -Action Unpublish -InfobaseName demo

По умолчанию Apache слушает ONEC_WEB_PORT_HOST=8080 (настраивается в infra/vm/.env).

Что делает скрипт развёртки (в общих чертах)

Серверный сценарий рассчитан на Windows‑хост и делает примерно так:

1. Берёт значения из secrets/.env и готовит Docker‑secrets файлы (без печати значений).
2. Скачивает официальный Ubuntu Server ISO, патчит его под autoinstall и использует уже пропатченный ISO для установки VM.
3. Создаёт VM в Hyper‑V, настраивает доступ по SSH и дожидается, пока VM станет доступна.
4. Загружает на VM нужные файлы и поднимает Docker Compose стек: 1С сервер + Postgres + Apache (веб‑публикации).
5. Дожидается health‑состояния 1С‑сервера и делает базовые проверки (порты/кластер).

Как запускать серверный сценарий

Запускать PowerShell от администратора, лучше pwsh (PowerShell 7), а не Windows PowerShell 5.1. Перед запуском проверь, что Docker уже поднят, и запускай сценарий из корня репозитория:

pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\tests\SmokeTest-OnecInfra.ps1

2) Клиентская песочница (Cursor/VS Code)

Требования:

• Docker Desktop запущен
• расширение Dev Containers (ms-vscode-remote.remote-containers)

Дальше так:

• Перед первой сборкой контейнера клиентской песочницы обязательно выполни именно scripts/ensure-devcontainer-prereqs.ps1: этот скрипт проверит и при необходимости создаст external volumes agent-work-sandbox-1c, onescript-cache-1c, onec-licenses и общую Docker network infra для клиентской песочницы и локальных вспомогательных сервисов:

powershell -ExecutionPolicy Bypass -File .\scripts\ensure-devcontainer-prereqs.ps1

• Скрипт читает настройки сети из .devcontainer/.env (AGENT_INFRA_*) и проверяет, что существующая сеть infra совпадает с ожидаемой конфигурацией.
• Если менялся список external volumes или настройки сети в .devcontainer/docker-compose.yml / .devcontainer/.env, просто запусти этот скрипт ещё раз перед следующим Rebuild Container.
• Именованный volume agent-home-1c docker compose создаст сам.
• Данные в volume (agent-work-sandbox-1c, onescript-cache-1c, onec-licenses, agent-home-1c) сохраняются при rebuild/recreate контейнера. Они удалятся только если удалить volume явно.
• Открываешь Cursor/VS Code
• Команда Dev Containers: Open Folder in Container и выбираешь папку этого репозитория
• Откроется новое окно, уже подключённое к клиентскому контейнеру
• Уже в новом окне делаешь File → Open Folder… и выбираешь рабочую папку конкретного проекта, с которым будет работать агент

Что настроено

Клиентская песочница сделана так, чтобы 1С‑инструменты работали предсказуемо внутри контейнера:

• Headless display: поднимается Xvfb (некоторые режимы 1С требуют X‑сервера даже без UI).
• Активация community‑лицензии клиента: механизм сейчас сломан со стороны платформы. Активация в личном кабинете проходит, но сама платформа затем ругается на ошибку формата. Решение пока не найдено. Временный обходной путь: не заполнять секреты developer.1c.ru (DEV_LOGIN, DEV_PASSWORD) в secrets/.env , тогда шаг авто‑активации будет пропущен и установочные скрипты не будут считать это ошибкой.
• Лицензии не теряются: лицензии лежат в отдельном volume и переживают пересборку контейнера.
• Маппинг имени VM внутрь контейнера: при старте может обновляться /etc/hosts, чтобы имя onec-infra указывало на management‑IP VM (если этот IP задан в локальной конфигурации инфраструктуры).
• Анти‑футган для git: стоит pre‑push хук, блокирующий push прямо в main/master (чтобы случайно не убить публичный репо). В принципе не обязательно для 1С проектов, т.к. код регулярно бекапится "в базу" при запуске юнит-тестов (а для версионирования достаточно локального репо), но если нужно, то агенту выделяется отдельная ветка и хук запрещает пушить мейн ветку (только через PR)
• CLI‑инструменты: внутри есть базовые утилиты (git, gh, docker cli и т.п.), чтобы агент мог работать “из коробки”.
• OneScript/Vanessa не качаются заново на каждом rebuild: они кэшируются в отдельном volume и переиспользуются новым контейнером.

Секреты: единый источник истины

Источник истины — secrets/.env (локально, не коммитится). Из него автоматически генерируются файлы secrets/*, которые уже используются как Docker secrets (/run/secrets/*).

Версия платформы 1С: один источник истины

Единый источник истины — infra/vm/.env (переменная ONEC_VERSION). Серверная часть фиксируется на конкретной версии платформы, а клиентская песочница и прочие компоненты подхватывают ту же версию.

Обновление платформы 1С без пересоздания песочницы

Обновление платформы в этом репозитории делается не через развёртывание всего с нуля, а через пересборку контейнеров с новой версией платформы:

• клиентский devcontainer пересобирается локально;
• серверные контейнеры onec-server и onec-web пересобираются внутри уже существующей VM;
• сама VM, её ОС, Docker volumes Postgres/1С и лицензии при штатном обновлении не пересоздаются.

Важно

• Для сценария обновления существующей VM параметр FORCE_RECREATE_VM в infra/vm/.env должен быть строго false.
• Если поставить FORCE_RECREATE_VM=true, вместо обновления платформы можно получить пересоздание виртуальной машины с нуля.
• Для обновления платформы не использовать ResetOnecData и ResetPgData: эти режимы предназначены для сброса данных, а не для обычного апгрейда.

Подготовка

1. Положи дистрибутив новой версии платформы в .devcontainer/distr/: setup-full-<ONEC_VERSION>-x86_64.run
2. Измени ONEC_VERSION в infra/vm/.env.
3. Проверь, что в infra/vm/.env задано: FORCE_RECREATE_VM=false
4. Перед апгрейдом сделай backup/снимок:
   • checkpoint/backup VM;
   • backup баз Postgres;
   • при необходимости backup docker volumes vm_pgdata, vm_onec-data, vm_onec-licenses.

Порядок обновления

1. Останови активные сеансы и фоновые работы, которые используют сервер 1С.
2. Обнови серверную часть в уже существующей VM:

pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\hyperv\Deploy-OnecInfra.ps1 -VmIp <MGMT_VM_IP> -SshIdentityFile .\.cache\hyperv\_ssh\onec-infra\id_ed25519

Этот сценарий копирует актуальные файлы в существующую VM и запускает infra/vm/up.sh, который выполняет docker compose up -d --build. При штатном запуске это означает пересборку контейнеров onec-server / onec-web на новой платформе без пересоздания VM и без удаления volumes.

Если VM была создана штатными Hyper-V скриптами этого репозитория, для воспроизводимого запуска лучше явно передавать -SshIdentityFile и использовать repo-managed ключ:

• .\.cache\hyperv\_ssh\onec-infra\id_ed25519

Без явного ключа PowerShell/SSH может попытаться использовать другой профиль/ключ пользователя и Deploy-OnecInfra.ps1 завершится на preflight-проверках подключения к VM.

3. Проверь сервер после обновления:
   • контейнер onec-server в состоянии healthy;
   • rac cluster list отрабатывает;
   • базы открываются;
   • web-публикации отвечают, если используются.
4. После успешной проверки сервера пересобери клиентский devcontainer:
   • в VS Code / Cursor: Dev Containers: Rebuild Container.
5. Проверь клиент:
   • платформа открывается;
   • подключение к серверу работает;
   • Конфигуратор / толстый клиент / пакетные вызовы стартуют на новой версии.

Что при этом сохраняется

• VM в Hyper-V;
• Ubuntu внутри VM;
• Docker volumes серверной части (pgdata, onec-data, onec-logs, onec-licenses, onec-web-data);
• Docker volumes клиентской части (agent-work-sandbox-1c, onescript-cache-1c, onec-licenses, agent-home-1c).

Что не нужно делать для обычного апгрейда

• не пересоздавать VM вручную;
• не включать FORCE_RECREATE_VM=true;
• не запускать сценарии с очисткой volumes;
• не удалять volumes Docker клиентской и серверной части.

Что обычно лежит в secrets/.env:

• releases.1c.ru (ONEC_USERNAME, ONEC_PASSWORD) — нужно только если сборка должна скачать дистрибутив платформы (когда локального установщика нет).
• developer.1c.ru (DEV_LOGIN, DEV_PASSWORD) — сейчас лучше не заполнять. На текущий момент авто‑активация community‑лицензии сломана со стороны платформы: в личном кабинете активация происходит, но платформа возвращает ошибку формата. Если эти секреты оставить пустыми, шаг авто‑активации будет пропущен и сценарии установки не будут считать это ошибкой.
• Postgres (PG_PASSWORD) — опционально. Если не задан, пароль генерируется один раз и сохраняется, чтобы деплой был воспроизводимым.

Шаблоны репозиториев

В templates/ лежат “seed”‑шаблоны, чтобы быстро стартовать новый репозиторий под проект/агента на базе этой песочницы.

AI-инструменты

Claude Code — cc / сс

Запускается через wrapper ~/bin/claude-safe.sh. Настройки берутся из .devcontainer/.env и секрета cc_api_key.

Настройка 9Router для Claude Code

Claude Code обращается к моделям по фиксированным именам: opus, sonnet, haiku. В 9Router нужно создать Combo с точно таким именем, и прописать в него один или несколько реальных бэкендов. Через файл конфига можно принудительно переопределить имена моделей, но на мой взгляд работа через Комбо удобнее.

Combo name	Что подставить
opus	В идеале модели Opusa из разных доступных вам подписок. На крайний случай любую "топовую")
sonnet	Аналогично. Собираем сюда Соннетов из всех подписок
haiku	Любые быстрые дешевые модели приемлимого качества

В Combo можно указать любой провайдер, однако наиболее стабильное поведение достигается с оригинальными моделями Anthropic — Claude изначально обучен управлять инструментами и форматировать вывод в своём нативном формате.

Codex CLI — cx / сч

Запускается через wrapper ~/bin/codex-safe.sh. При старте контейнера скрипт codex-bootstrap.sh генерирует ~/.codex/config.toml с профилями моделей.

Алиасы cc/сс и cx/сч — латиница и кириллица соответственно, оба варианта работают.

Настройка Codex для работы с 9Router

Codex использует кастомный список моделей, который bootstrap собирает из двух источников:

1. codex-model-map.json — маппинг на официальные модели Codex

Сопоставляет имена в 9Router (cx/*) с оригинальными slug-ами из официального репозитория Codex. Благодаря этому bootstrap заполняет метаданные модели (контекстное окно, описание, возможности) так же, как в оригинале.

{
  "cx/gpt-5.3-codex": "codex-1",
  "cx/gpt-5.1-codex-mini": "codex-mini-latest"
}

2. codex-model-overrides.json — ручные описания для моделей без upstream

Для моделей, которых нет в официальном списке (например ag/gemini-3.1-pro-high), поля задаются вручную. Описание всех полей: docs/codex-model-catalog-fields.md

Системный промт для Gemini

Для моделей, в имени которых содержится gemini, bootstrap при старте контейнера скачивает системный промт напрямую из официального репозитория Codex:

codex-rs/core/prompt_with_apply_patch_instructions.md

Настройка Codex для работы с 9Router

Gemini CLI поддерживает работу с фиксированным набором моделей (только свои). Через настройки в .devcontainer\.env их можно переопределить на любые нужные (наприм. ag/gemini-3.1-pro-high), а можно создать Комбо и переопределить на их названия.

Переменные окружения .devcontainer/.env

Переменная	Назначение
OPENAI_BASE_URL	URL 9Router (или другого прокси)
CODEX_MODEL	Модель по умолчанию для Codex
CODEX_MODELS	Список моделей → генерирует профили в config.toml
CODEX_MODEL_PROVIDER_ID/NAME	Имя провайдера в Codex UI
CODEX_MODEL_MAP_FILE	JSON с маппингом cx/* → upstream slug
CODEX_MODEL_OVERRIDES_FILE	JSON с ручными описаниями моделей (ag/* и др.)
CODEX_GEMINI_PROMPT_FILE	Системный промт для моделей Gemini

Проброс скриншотов в контейнер (Clipboard Sync)

CLI-агенты (Claude Code, Codex CLI) работают в терминале контейнера и не имеют прямого доступа к буферу обмена Windows. Для вставки скриншотов используется схема через bind mount:

Windows clipboard ──► tray app (хост) ──► PNG файл (%TEMP%\cb-x11-sync\img.png)
                                               │
                                          bind mount :ro
                                               │
                          clipboard-watch ◄─────┘  (контейнер)
                               │
                            xclip ──► X11 clipboard (Xvfb :99) ──► CLI агент (Alt+V / Ctrl+V)

Настройка хоста (одноразово)

Тресй-приложение одно на все контейнеры — любой контейнер с bind mount на cb-x11-sync автоматически получает скриншоты.

powershell -ExecutionPolicy Bypass -File .\scripts\setup-clipboard-sync.ps1

Скрипт создаёт %TEMP%\cb-x11-sync\, ярлык на рабочем столе и добавляет в автозагрузку Windows.

Что настроено в контейнере

Всё работает из коробки после Rebuild Container:

• Dockerfile: пакеты xclip, xsel; скрипт clipboard-watch копируется в /usr/local/bin/
• docker-compose.yml: bind mount ${TEMP}/cb-x11-sync:/tmp/cb-x11-sync:ro
• entrypoint.sh: демон clipboard-watch стартует автоматически после Xvfb (polling 100ms, проверка по mtime+size файла)
• claude/bootstrap.sh: keybinding Alt+V → imagePaste (Ctrl+V перехватывается терминалом Cursor)

Вставка скриншота

1. Сделай скриншот (Win+Shift+S)
2. Тресй-иконка мигнёт зелёным
3. В CLI-агенте внутри контейнера:
   • Codex CLI: Ctrl+V
   • Claude Code: Alt+V

Проверка работоспособности

# Внутри контейнера:
echo $DISPLAY                                      # → :99
ps aux | grep clipboard-watch                      # → процесс запущен
xclip -selection clipboard -t TARGETS -o           # → image/png
ls -la /tmp/cb-x11-sync/img.png                   # → файл существует

Troubleshooting

Симптом	Причина	Решение
Тресй-иконка не появляется	Приложение не запущено	Запустить ярлык с рабочего стола
xclip: Cannot open display	Xvfb не запущен	ps aux | grep Xvfb
Нет файла /tmp/cb-x11-sync/img.png	Bind mount не подключён	Rebuild Container
Claude Code не реагирует на Alt+V	Нет keybindings.json	Проверить /home/vscode/.claude/keybindings.json
Изображение не обновляется	Watcher не запущен	ps aux | grep clipboard-watch

Улучшения

• криво работает очистка папки кеш. не всегда удаляет старые образы после создания нового (или вообще не удаляет?)
• протестить сборку на линукс окружении (не тестировалось, разрабатывалось под windows)