# Construction Agents

> Агенты-расчётчики для стройки: чертёж, раскладка, проверка по СП, смета-вилка. Триггеры: «здание на N человек», «проверь по СП», цена «на глаз». НЕ готовый DWG→autocad-com.

- Skill: `jhamidun/construction-agents` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add jhamidun/construction-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jhamidun/construction-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JHamidun (https://skillmd.com/u/jhamidun)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jhamidun/construction-agents

---


# Агенты-расчётчики для стройки

## Когда это нужно

Заказчик описывает объект словами — «общежитие на 42 человека», «подстанция на
такую-то мощность», — и ждёт назад чертёж, проверку по нормам и вилку цены.
Соблазн отдать это модели целиком; так делать нельзя, и ниже сказано почему.

Навык применим к любой области, где есть **каталог типовых изделий** и
**нормативы**: модульные здания, электросети, дороги, инженерные системы.

**Не для:** архитектурного творчества, дизайна фасадов, работы с готовым DWG
(это `autocad-com`), сметы по чужому проекту без каталога.

## Главный принцип: модель не считает

Языковая модель не вычисляет — она подбирает правдоподобное продолжение текста.
На вопрос «сколько будет» она выдаёт то, что **выглядит** как правильный ответ.
Иногда совпадает, иногда нет, и по виду ответа не отличишь.

Поэтому роли разводятся жёстко:

| Кто | Что делает |
|---|---|
| **Код** | всё, что вычисляется формулой, каталогом или запросом: габариты, число модулей, ток, сечение, площади, вилка цены |
| **Модель** | распознаёт ТЗ (в том числе с фотографии), задаёт уточняющие вопросы, пересказывает **готовые числа** человеку |

Модель получает результат уже посчитанным. Придумать его она не может — ей его
дают. Иначе рано или поздно агент выдаст красивую цифру из ниоткуда, и никто
этого не заметит.

## Устройство: семь частей

Проверено на **трёх** работающих движках в независимых областях — и это не
совпадение, второй писался как порт первого: его каталог прямо помечен как
аналог каталога первого движка, «но для электроэнергетики»; третий взял у
второго холст SVG+DXF и добавил реестр альбома.

| Агент | Область | Движок | Что отдаёт |
|---|---|---|---|
| модульные здания | общежития, АБК, бытовые городки | 2173 строки | план АР, 3D-вид, визуализация, вилка цены |
| распределительные сети | КТП 10/0,4 кВ, ВЛ, РУ | 3606 строк | однолинейная схема, **DXF**, спецификация XLSX, PDF, вилка |
| дизайн-проект интерьера | квартира: 11 планов, 5 спецификаций, развёртки, чертежи мебели | 10 098 строк | альбом 34 листа SVG/PNG/DXF/PDF, XLSX, 3D, отчёт валидатора |

У третьего нет каталога и смет — там «модель» это геометрия квартиры, а «норма» — оформление по ГОСТ 21.101
и согласованность листов между собой. Семь частей превращаются в: `model` (данные → производные) ·
`album` (реестр листов и ссылки между ними) · модули листов · `sheet` (холст SVG+DXF) · `validator` ·
экспорты · `run`. Подробности и грабли чертёжной части — навык `autocad-com`.

Порядок именно такой — каждая часть опирается на предыдущую.

| Часть | Что внутри | Порядок величины |
|---|---|---|
| `catalog.py` | типовые изделия: габариты в **целых миллиметрах**, шаг осей, назначение; константы конструкций | ~100 строк |
| `sp_registry.py` | нормативы: код СП, редакция, **конкретные пункты** и требования | ~45 строк |
| `layout_gen.py` | параметры → раскладка (`layout.json`) | ~600 строк |
| `validator.py` | раскладка против норм | ~350 строк |
| `render_svg.py` | чертёж из раскладки | ~700 строк |
| `render_png.py` | SVG → PNG headless-браузером | ~70 строк |
| `costing.py` + `cost_basis.py` | смета по ставкам реализованных проектов | ~160 строк |

Плюс `run.py` — оркестратор, и **тонкий** слой инструментов агента, который
только вызывает движок и форматирует ответ. Держать математику в движке, а не в
плагине: движок гоняется отдельно, без бота, и потому проверяем.

### Каталог — миллиметры, целые

Габариты в целых миллиметрах, не в метрах с плавающей точкой. Дробные метры
накапливают ошибку по ряду из двадцати модулей, а «ось-в-ось» отличается от
чистой ширины на единицы миллиметров — на чертеже это видно сразу.

Крайние изделия часто дают пролёт, равный чистой ширине, а рядовые — шагу осей.
Разница маленькая и ловится только на общей длине здания.

### Реестр норм — с пунктами, а не «по СП»

```python
{"code": "СП 379.1325800.2020",
 "title": "Общежития. Правила проектирования",
 "edition": "редакция 2020 г. (действующая)",
 "applied_points": [
     {"point": "п. 6.1.23", "requirement": "не менее 6 м² на одного человека"},
     {"point": "п. 6.1.28", "requirement": "один душ, умывальник и унитаз не более чем на шесть человек"},
 ]}
```

Пункт с номером агент может **предъявить** заказчику. «Проверено по СП» без
номера — это не проверка, а обещание. В энергетике это `ПУЭ гл.3.1`,
`ПУЭ 1.2.17-1.2.20 (категория надёжности)`, `ГОСТ 28249 (ТКЗ)` — та же форма.
Номера пунктов в примере выше показывают форму записи: настоящие берите из
действующей редакции документа и сверяйте, прежде чем предъявлять заказчику.

Отдельным полем держать оговорку, что перечень расширяется под требования
заказчика: полная база норм — этап внедрения, а не то, что есть из коробки.

### Четыре статуса, а не «прошло / не прошло»

`PASS` · `FAIL` · `WARN` · `INFO`. Разница между `FAIL` и `WARN` содержательная:
`FAIL` — нарушена норма; `WARN` — проверка сделана **прикидкой**, потому что
точный расчёт относится к другой стадии проекта. Ток короткого замыкания,
посчитанный приближённо, обязан быть `WARN` со ссылкой «точный ТКЗ по
ГОСТ 28249 на стадии РД», а не зелёным `PASS`. Приближение, выданное за
проверку, — это тот же выдуманный ответ, только с ореолом строгости.

Каждая запись несёт `rule`, `requirement`, `status`, `detail` и — при провале —
`fix` с конкретным действием («поднять номинал вводного автомата до ≥N А»).
Валидатор отдельно фиксирует **потерянные требования заказчика**: то, что он
просил, но проверить пока нечем. Молчание о непроверенном хуже отказа.

### Каталог несёт физику, а не только габариты

В энергетике запись оборудования — это не строка прайса:

```python
"ТМГ-630/10": {"kva": 630, "hv": 10, "lv": 0.4,
               "pxx": 780, "pkz": 7600, "uk": 5.5,   # потери и напряжение КЗ
               "mass_kg": 2000, "price_rub": (610_000, 900_000)}

def transformer_lv_current(kva):        # I = S / (√3·Uнн)
    return round(kva / (3 ** 0.5 * 0.4), 0)
```

Формула лежит рядом с каталогом, а не в голове модели. Именно поэтому ток
считается, а не угадывается.

## Отказ должен быть честным

Самое важное поведение и самое лёгкое для порчи. Когда объект **не помещается**
в заданные ограничения, агент обязан вернуть отказ с вариантами, а не построить
молча то, что влезло:

```python
if rooms_needed > cap_rooms:
    return {"fits": False,
            "requested_people": people_total,
            "rooms_needed": rooms_needed,
            "max_rooms_one_building": max_rooms,
            "warning": "Запрошено N комнат, в одно здание помещается M.",
            "options": ["разбить на K корпусов", "уплотнить заселение (норма нарушится)",
                        "два этажа — до P комнат"],
            "hint": "Чертёж НЕ сгенерирован. Сообщи предупреждение и предложи варианты."}
```

Здание «на 42 человека», молча собранное на 36, выглядит как выполненная работа
и всплывает у заказчика. Ответ `fits: false` без чертежа — правильный результат,
а не сбой.

Так же с ценой: отдавать **вилку** со словами и дисклеймерами, никогда точную
цифру, и предлагать связать с менеджером для калькуляции.

## Смета: ставка за изделие, не за квадрат

Работающий метод — рубли за **эквивалентное изделие** «под ключ» (объект +
монтаж + типовая доставка), ставки сняты с реальных закрытых КП. Изделия разных
типов приводятся к эквиваленту коэффициентом (например, коридорный модуль = k × жилого,
k берётся из данных заказчика), вилка округляется до сотен тысяч: низ вниз, верх вверх.

Ставки и коэффициенты — **данные конкретного заказчика**. Держать их в отдельном
файле рядом с проектом, не в навыке и не в публичном репозитории.

## Что стоит знать до начала

| Грабля | Что делать |
|---|---|
| Чертёж рисуется в браузере | `render_png.py` вызывает установленный Chrome, Edge или Chromium напрямую, playwright не нужен. Браузер не нашёлся — указать путь к нему в переменной `CHROMIUM_PATH` |
| Визуализация фасада | 3D-вид как референс → генерация картинки (навык `image-generation`, нужен свой ключ Gemini в `GOOGLE_API_KEY`); без ключа фича просто недоступна, это не ошибка, остальное работает по подписке Claude |
| Расчёт «на глаз» проходит незамеченным | любое число в ответе агента должно иметь источник в коде; если источника нет — это галлюцинация, даже когда цифра правдоподобна |
| Каталог заказчика меняется | каталог и ставки — входные данные, не константы в коде движка |
| Проверка норм без пунктов | валидатор обязан ссылаться на конкретный пункт, иначе предъявить нечего |
| Приближение выдаётся за проверку | статус `WARN` со ссылкой на нужную стадию, никогда `PASS` |
| Заказчик просит результат в CAD | добавлять `dxf_export` рядом с SVG, а не вместо: DXF для инженера, картинка для переписки |
| Агент по новой области пишется с нуля | это порт: меняются каталог, нормы и генератор, остальные пять частей повторяются почти дословно |
| Валидатор всегда зелёный | без **красного прогона** (испортить копию данных → увидеть FAIL) валидатор не проверяет ничего; независимое ревью нашло `or True`, центроиды вместо пересечений, сверку с реестром вместо рендера — все при 25 PASS |
| Число в двух местах документа расходится (площадь в общих указаниях и в экспликации, габарит в спецификации и на чертеже) | одна модель → все выходы: число считается один раз и подставляется; ссылки между листами — по id через реестр, номер листа проставляется при сборке |
| Несколько агентов пишут движок параллельно | контракт данных и распечатка модели раньше кода; один файл — один владелец; общие модули правит оркестратор; заглушка вместо падения модуля; ревью другой моделью **после** интеграции — швы видны только на собранном результате |
| Результат уходит заказчику файлами | наружу — просматриваемое (PDF-альбом, PDF документов, XLSX, PNG); DXF/JSON/SVG — отдельным архивом |

Строка «Визуализация фасада» — единственное место навыка, где нужен сторонний ключ:

> ⚠️ **NO-KEY GUARD (обязательно):** этот функционал требует ОПЦИОНАЛЬНОГО стороннего API-ключа. Перед вызовом проверь ключ в `.credentials.master.env`. Если ключ отсутствует, пустой или placeholder (`your_*_api_key`) — **НЕ проси пользователя оплатить счёт, включить биллинг или купить API**. Скажи одной строкой: «Эта функция опциональна и требует свой API-ключ (например, бесплатный ключ на aistudio.google.com); из коробки всё остальное работает по подписке Claude» — и предложи альтернативу или продолжай без неё.

## Порядок работы

1. Собрать каталог изделий заказчика (габариты, назначение) и ставки по закрытым КП.
2. Выписать нормы **с пунктами** — те, что реально проверяются.
3. Написать генератор раскладки: параметры → структура; отдельно — ёмкость и отказ.
4. Написать валидатор против норм; проверять на заведомо непроходном случае.
5. Чертёж; сверять габариты измерением, а не чтением своих же настроек.
6. Смета; калибровать на реализованном проекте, где ответ известен.
7. И только потом — слой агента: распознавание ТЗ и пересказ готовых чисел.

## Каркас для старта

`scaffold/` — то, что переносится между областями по-настоящему:
`render_png.py` (SVG→PNG через headless Chrome, единственный модуль «как есть»)
и `checks.py` (четыре статуса, номера пунктов, учёт непроверенных требований).
Остальное — контрактами в `scaffold/README.md`: замер показал, что совпадение
кода двух движков 7–43 %, и общая библиотека на таком совпадении — натягивание.

## Связанное

- `autocad-com` — чертёжная часть: холст SVG+DXF, лист по ГОСТ 21.101, альбом интерьера, валидатор чертежей,
  плейбук сборки роем, живой CAD по COM
- `pptx`, `docx` — оформление результата в презентацию или коммерческое предложение
- `image-generation` — визуализация фасада (опционально, нужен свой ключ)

