# OneC Remote EPF

**Подключите AI-ассистента к удалённой 1С — достаточно открыть одну обработку.**

[![Tests](https://github.com/MaryginR/onec-remote-epf/actions/workflows/tests.yml/badge.svg)](https://github.com/MaryginR/onec-remote-epf/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue)](pyproject.toml)

Есть RDP на сервер клиента и доступ к базе 1С, но нет возможности подключиться
к ней со своего компьютера? Откройте `OneCRemoteAgent.epf` в удалённой 1С
и работайте через MCP из Codex или другого MCP-совместимого ассистента.

Изучайте метаданные, выполняйте запросы и BSL, читайте документы, передавайте
файлы и настраивайте базу через её штатные механизмы.

## Почему это удобно

- **Без публикации базы и COM.** Не нужно поднимать IIS/Apache или обеспечивать
  прямой доступ к кластеру 1С. Конфигурация не изменяется установкой моста.
- **На стороне клиента — только EPF.** Python и MCP работают у разработчика.
  Локальная копия базы и совпадающая локальная платформа 1С не нужны.
- **Без своего VPS и домена.** Очередь разворачивается в вашем Cloudflare-аккаунте
  с постоянным адресом `workers.dev`. С обеих сторон нужен исходящий HTTPS.
- **Код подключения вводится один раз.** Адрес и секрет запоминаются для
  пользователя базы. В следующий раз достаточно нажать «Подключить».
- **Новые сценарии без новой обработки.** Серверный и клиентский BSL передаётся
  по каналу — не нужно каждый раз переносить EPF через RDP.
- **Управляемые задания.** У команды есть ID, статус и результат. При сетевом
  сбое повторяется доставка результата, а не уже выполненный BSL.

## Как это работает

```mermaid
flowchart LR
    A[AI-ассистент] --> B[Локальный MCP]
    B -->|HTTPS| C[Ваш Cloudflare Worker + D1]
    D[EPF в удалённой 1С] -->|Исходящий HTTPS| C
    D --> E[База 1С]
```

Cloudflare — очередь команд и результатов. Модель и MCP остаются на вашем
компьютере. Обработка работает с правами открытого пользователя 1С.

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

Нужны **Python 3.11+**, **1С:Предприятие 8.3.27 с управляемым клиентом**
и **Cloudflare-аккаунт**. Для готовой EPF Конфигуратор не требуется.

### 1. Скачайте проект

```powershell
git clone https://github.com/MaryginR/onec-remote-epf.git
cd onec-remote-epf
```

Или скачайте **Code → Download ZIP** и откройте терминал в распакованной папке.

### 2. Подготовьте Cloudflare — один раз

1. Войдите в [Cloudflare Dashboard](https://dash.cloudflare.com/).
2. Скопируйте **Account ID** своего аккаунта.
3. В [API Tokens](https://dash.cloudflare.com/profile/api-tokens) выберите
   **Create Token → Create Custom Token**. Добавьте права
   **Account → Workers Scripts → Edit** и **Account → D1 → Edit**.
   В **Account Resources** выберите только свой аккаунт и создайте токен.

Не используйте Global API Key. Купленный домен и DNS-настройки не нужны.
Проект рассчитан на Free-план, но его квоты конечны:
[Workers](https://developers.cloudflare.com/workers/platform/pricing/),
[D1](https://developers.cloudflare.com/d1/platform/pricing/).

### 3. Запустите мастер установки

```powershell
python scripts/setup_cloud.py
```

Мастер создаст локальное Python-окружение, установит зависимости и запросит
Account ID и API-токен. **Ввод токена скрыт.** Затем автоматически создаст Worker,
базу очереди D1 и ежедневную очистку. Готовый HTTPS-адрес появится в терминале.

Токен и настройки сохраняются в исключённой из Git папке `.runtime`.
На сервер клиента их переносить не нужно. Токен Cloudflare используется
только для развёртывания и обновления, а не для обычной работы с базой.

### 4. Подключите MCP к ассистенту

Для Codex выполните команду, которую напечатает мастер. Пример для Windows:

```powershell
codex mcp add onec_remote_epf -- "C:\path\to\onec-remote-epf\.venv\Scripts\python.exe" -m onec_remote.cli mcp --state "C:\path\to\onec-remote-epf\.runtime"
```

Для другого MCP-клиента укажите **stdio**, тот же Python и аргументы:

```json
{
  "mcpServers": {
    "onec_remote_epf": {
      "command": "C:/path/to/onec-remote-epf/.venv/Scripts/python.exe",
      "args": ["-m", "onec_remote.cli", "mcp", "--state", "C:/path/to/onec-remote-epf/.runtime"]
    }
  }
}
```

На Linux/macOS Python окружения находится в `.venv/bin/python`.
Если инструменты ещё не появились, обновите подключение MCP в своём клиенте.

### 5. Откройте обработку в удалённой 1С

Получите код у ассистента инструментом `create_pairing` либо локально:

```powershell
.\.venv\Scripts\python.exe -m onec_remote.cli pair --label "Тестовая база"
```

На компьютере с 1С:

1. Перенесите **[build/OneCRemoteAgent.epf](build/OneCRemoteAgent.epf)**.
2. Откройте его через **Файл → Открыть / Ctrl+O** в нужной базе.
3. Введите свой адрес `workers.dev` и код. Код действует 10 минут.
4. Для BSL и изменений включите **«Разрешить административные BSL-сценарии
   и изменения»**. Для обычных запросов флаг не обязателен.
5. Нажмите **«Подключить»** и оставьте форму открытой.

Готово. Попросите ассистента показать базы, проверить нужный сеанс и выполнить
первый запрос. При повторном подключении код не нужен. Положение флага тоже
запоминается. Отозвать доступ можно инструментом `revoke_session`.

## Что можно поручить ассистенту

> Покажи документы и реквизиты этой конфигурации.

> Найди, из каких связанных документов можно получить данные для заполнения.

> Сохрани текущие настройки и загрузи подготовленный файл штатным механизмом.
> После записи прочитай результат повторно.

> Выполни BSL на сервере и верни итог проверки.

В проекте **14 MCP-инструментов**: подключения и контекст, метаданные, запросы,
чтение объектов, BSL на сервере/клиенте, экспортные функции, файлы и задания.
[Описание инструментов](docs/TOOLS.md).

[Skill для агента](skills/onec-remote-epf/SKILL.md) объясняет выбор базы,
работу с командами и сбоями. Установить skill и собрать комплект для клиента:

```powershell
.\.venv\Scripts\python.exe scripts/build_handoff.py --install-skill
```

Результат — `delivery/OneCRemoteKit/` и ZIP рядом. На сервер переносится только `client/`.

## Что важно учитывать

- **Это административный инструмент.** BSL не является песочницей и выполняется
  с правами пользователя. Начинайте с согласованной тестовой копии.
- **Данные проходят через ваш Cloudflare.** Завершённые задания хранятся до 7 дней,
  аудит до 30 дней при работающей очистке. Согласуйте канал с владельцем базы.
  Встроенной анонимизации нет.
- **Форма 1С должна оставаться открытой.** Завершение сеанса останавливает канал;
  модальные окна могут задерживать обмен. Постоянного фонового сервиса пока нет.
- **Таймаут не означает откат.** Проверяйте то же задание и не повторяйте запись
  вслепую. [Диагностика](docs/TROUBLESHOOTING.md).
- Лимиты: файл до **600 КБ**, ответ EPF до **900 КБ**, задание облака до **1 МБ**.
  Результаты передаются частями, большие входные параметры пока не фрагментируются.
- Полный текст модулей не доступен из runtime-метаданных: нужны отдельные исходники.

**Статус:** ранняя версия. Удалённая работа проверена на серверной платформе
8.3.27.2214 с EPF 0.1.3. Текущая 0.1.4 собрана с исправлением JSON/Null,
но отдельная runtime-приёмка этой сборки ещё не выполнена.

## Для разработки

[Сборка и тесты](docs/DEVELOPMENT.md) · [История изменений](CHANGELOG.md) ·
[Лицензия MIT](LICENSE)

Нашли проблему или полезный сценарий? Создайте issue с версией платформы и
обезличенным текстом ошибки. Не прикладывайте токены, пароли и клиентские данные.