docs: INSTALL.ru.md — наша эксплуатация, источники версий и порядок обновления

2026-10-05 17:54:33 +03:00
1 changed files with 121 additions and 0 deletions
@@ -0,0 +1,121 @@
+# AutoCAD MCP Pro — как у нас развёрнут и как обновлять
+
+Этот репозиторий — **зеркало** открытого проекта `U-C4N/Autocad-MCP` (PyPI-пакет
+`autocad-mcp-pro`), которым мы пользуемся для черчения из агентов Hermes.
+
+## 1. Источники версий и обновлений (единственные авторитетные)
+
+| Что | Где смотреть |
+|---|---|
+| Исходный репозиторий | https://github.com/U-C4N/Autocad-MCP |
+| Релизы и теги (что нового) | https://github.com/U-C4N/Autocad-MCP/releases — теги `v1.3.0 … v1.6.0` |
+| Список изменений | `CHANGELOG.md` в корне репозитория (самый подробный источник) |
+| PyPI-пакет и доступные версии | https://pypi.org/pypi/autocad-mcp-pro/json (поле `info.version`, `releases`) |
+| Внутренняя версия сервера | MCP-вызов `system_about` / ответ `initialize` (`serverInfo.version`) |
+
+**Текущий пин зеркала:** ветка `main`, коммит `cdb1063` (после релиза **1.6.0 от 24.09.2026**).
+Релизы: `v1.5.1` → `v1.6.0` (247 зарегистрированных инструментов, 242 отдаётся по умолчанию).
+
+Обновления проверять так (без установки):
+
+```bash
+# последняя версия на PyPI
+curl -s https://pypi.org/pypi/autocad-mcp-pro/json | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['info']['version'], list(d['releases'])[-4:])"
+# свежие релизы на GitHub
+curl -s https://api.github.com/repos/U-C4N/Autocad-MCP/releases | python3 -c "import json,sys;[print(r['tag_name'], r['published_at']) for r in json.load(sys.stdin)[:5]]"
+```
+
+## 2. Как это работает у нас (архитектура)
+
+```
+Hermes (Docker, VM108)  --HTTP MCP (Bearer)-->  контейнер autocad-mcp :30015  --ezdxf-->  DXF/PDF
+                                              контейнер autocad-mcp-160 :30016 (тестовый 1.6.0)
+                                              папка обмена: /var/lib/docker/volumes/hermes_hermes-data/_data/dxf  →  /opt/data/dxf
+```
+
+| Параметр | Значение |
+|---|---|
+| Рабочий контейнер | `autocad-mcp`, образ `autocad-mcp:latest` = **1.5.1 + наш патч**, порт **30015 → 8000** |
+| Тестовый контейнер | `autocad-mcp-160`, образ `autocad-mcp:1.6.0` (апстрим без патча), порт **30016** |
+| Бэкенд | `AUTOCAD_MCP_BACKEND=ezdxf` (headless, без AutoCAD; COM — только на Windows рядом с AutoCAD) |
+| Токен доступа | файл `/opt/data/.autocad_mcp_token` (chmod 600, **в git не попадает**), передаётся как `Authorization: Bearer …` |
+| Папка файлов | `ALLOWED_PATHS=/opt/data/dxf` — сервер принимает файлы **только** оттуда (иначе «Path rejected») |
+| Профиль инструментов | `TOOL_PROFILE=full`; для слабых моделей есть `TOOL_PACKS=core,mech...` и `DISCOVERY_MODE=search` (2 инструмента / 356 токенов вместо 83 921) |
+| Деплой-скрипты | `/opt/data/deploy_autocad_mcp.py` (рабочий, с тегом отката `autocad-mcp:prev`), `/opt/data/work/cad_mcp/deploy_160_test.py` (тестовый 1.6.0) |
+| Логи сборки | `/opt/data/autocad_mcp_build.log`, `/opt/data/autocad_mcp_160_build.log` |
+| Проверка живости | `python3 /opt/data/work/cad_mcp/tools_inventory.py 30015` (делает `initialize` → `tools/list`) |
+
+## 3. Что в нашей рабочей сборке сверх апстрима (патч 01.10.2026)
+
+Оверлей лежит в `/opt/data/autocad-mcp-build/patch/` и копируется поверх `site-packages`
+(см. `Dockerfile` в `/opt/data/autocad-mcp-build/`). Этих инструментов в апстриме нет:
+
+| Инструмент | Зачем |
+|---|---|
+| `titleblock_apply_gost_form3` | основная надпись по **ГОСТ Р 21.1101-2013 форма 3** (апстрим знает только ISO 7200) |
+| `file_put` / `file_get` | передача файлов внутрь `ALLOWED_PATHS` и обратно (без Docker-томов и HTTP-моста) |
+| `drawing_open_base64` / `drawing_save_base64` | обмен чертежами в base64 |
+| `entity_create_attdef`, `block_get_attdefs` | символы-блоки с атрибутами (тип/высота/группа) |
+| параметр `layout=` у инструментов **геометрии** (29 инструментов) | рисовать линии/полилинии прямо на ЛИСТЕ, а не только в модели |
+| параметр `inline_font=True` (5 инструментов) | инлайн-кодировка ISOCPEUR в каждом тексте |
+| `drawing_export_pdf(page_size="layout")` | страница PDF ровно по формату листа (в 1.5.1 апстрим подгонял по содержимому) |
+| `layout_set_paper` | явный размер бумаги листа (A4 книжный и др.) |
+| `template_apply_layers(spds)` | ГОСТ-набор слоёв (RAMKA, STAMPS, 00 БЛОКИ АННОТАЦИЙ, Стены) |
+| `dimstyle_ensure`, `text_apply_style` | размерный стиль СПДС, текстовые стили |
+
+⚠️ **Следствие:** апстрим 1.6.0 нельзя просто «поставить вместо» — часть наших возможностей
+пропадёт (ГОСТ-штамп, file_put/file_get, `layout` у геометрии, `inline_font`). Поэтому 1.6.0
+поднимается **рядом** (порт 30016), а перенос патча делается отдельным шагом.
+
+## 4. Установка с нуля
+
+```bash
+# 1) образ (Docker-контекст: Dockerfile + patch/)
+mkdir -p /opt/data/autocad-mcp-build && cd /opt/data/autocad-mcp-build
+# Dockerfile:
+#   FROM python:3.11-slim
+#   RUN pip install --no-cache-dir autocad-mcp-pro==1.5.1 matplotlib
+#   COPY patch/ /usr/local/lib/python3.11/site-packages/
+#   EXPOSE 8000
+#   CMD ["autocad-mcp","--transport","http","--host","0.0.0.0","--port","8000"]
+
+# 2) сборка и переустановка контейнера (Portainer API, безопасно: сначала образ, потом замена)
+python3 /opt/data/deploy_autocad_mcp.py            # рабочий (с тегом отката autocad-mcp:prev)
+python3 /opt/data/work/cad_mcp/deploy_160_test.py  # тестовый 1.6.0 на :30016
+
+# 3) подключение в Hermes (конфиг защищён, менять через config set)
+export PATH="/opt/hermes/.venv/bin:$PATH" HERMES_HOME=/opt/data HOME=/opt/data
+hermes config set mcp_servers.autocad.type http
+hermes config set mcp_servers.autocad.url http://10.26.5.108:30015/mcp
+hermes config set mcp_servers.autocad.headers.Authorization "Bearer <токен из /opt/data/.autocad_mcp_token>"
+hermes mcp test autocad          # ожидаем "Connected" + число инструментов
+
+# 4) проверка
+python3 /opt/data/work/cad_mcp/tools_inventory.py 30015
+python3 /opt/skills/devops/cad-automation/scripts/mcp_acceptance_test.py   # приёмочный прогон
+```
+
+## 5. Обновление версии
+
+1. Проверить новую версию (п. 1) и прочитать `CHANGELOG.md`.
+2. Собрать **тестовый** образ на новую версию: скопировать
+   `/opt/data/autocad-mcp-build/Dockerfile` в новый каталог, заменить пин версии,
+   запустить `deploy_160_test.py` (порт 30016).
+3. Прогнать инвентаризацию и приёмку по обоим портам, сравнить:
+   `tools_inventory.py 30015` против `tools_inventory.py 30016` — что появилось, что пропало.
+4. Перенести наш патч (см. п. 3) либо решить, что из апстрима заменяет нашу доработку.
+5. Переключить рабочий контейнер (`deploy_autocad_mcp.py`) — он сам ставит тег отката
+   `autocad-mcp:prev`; при проблеме вернуться на него.
+
+**Откат:** остановить контейнер, создать заново из образа `autocad-mcp:prev` с теми же
+параметрами (порт 30015 → 8000, `ALLOWED_PATHS=/opt/data/dxf`, тот же токен, User 10000:10000).
+
+## 6. Грабли, которые уже собирали (не повторять)
+
+- `tools/list` «сырым» POST даёт **HTTP 400** — нужен `initialize` → заголовок `Mcp-Session-Id` → `tools/list`.
+- Файлы внутрь контейнера: только путь из `ALLOWED_PATHS` (`/opt/data/dxf`), иначе «Path rejected».
+- У контейнера **свой том** — это не тот `/opt/data/dxf`, который видит агент; для передачи
+  файлов используем `file_put`/`file_get` или мост `dxf-bridge` (`http://10.26.5.108:30055/`).
+- PDF: проверять медиабокс (`pymupdf` → `page.rect.width/72*25.4` ≈ формат листа) и шрифт (`ISOCPEUR`).
+- Чертёж отдавать пользователю только после проверки движком AutoCAD (`accoreconsole /i … /s …`).
+- COM-режим (живой AutoCAD) **невозможен из Docker** — сервер обязан работать на Windows рядом с AutoCAD.