Files
shtil/AGENTS.md
T
TMSH 22d1698764
ci / smoke (push) Successful in 3s
[1.8] PoC Помощника: трей и замеры на Windows (#8)
**Задача:** #1.8
**Пункты:** 1.8.1, 1.8.2

## Что сделано
- PoC в poc/helper-tray/: Tauri 2 только с иконкой в трее (окна при старте нет), меню из трёх пунктов, окно создаётся по клику и уничтожается при закрытии.
- Форма «Сообщить о проблеме» по прототипу; «Выход» только в debug-сборке.
- Замер времени открытия — команда first_paint (invoke после двойного rAF); сценарий --measure-scenario + measure.ps1: PrivateBytes и WorkingSetPrivate дерева процессов по отметкам этапов в логе.
- Замеры Windows 11 (release, 5 прогонов, медиана): покой 2,0 МБ PB, окно 155,3 МБ PB (цель 150 — не дотянуто ~5 МБ), после закрытия 5,2 МБ, открытие 580/555 мс. Выводы и методика — docs/research/helper-tray-poc.md.
- AGENTS.md: добавлена временная папка poc/ (удаляется после ADR-0005).

## Как проверить
1. cd poc/helper-tray && pnpm install && pnpm tauri build
2. Запустить src-tauri/target/release/helper-tray.exe — только трей, без окна.
3. powershell -ExecutionPolicy Bypass -File measure.ps1 — 5 прогонов, таблица.
4. На Linux: сборка по docs/research/helper-tray-poc.md, замер через PSS.

## Чек-лист
- [x] Коммиты и название PR по-русски, в каждом коммите есть Refs:
- [x] Ветка свежая: git rebase origin/main, конфликтов нет
- [x] Секретов и персональных данных в коде, логах и документах нет
- [x] Документация обновлена: запись журнала, docs/status/, docs/research/
- [ ] Ссылка на этот PR добавлена в «Ссылки» задачи в дорожной карте
<!-- Прочие пункты шаблона неприменимы: нет запросов к БД, прав, миграций, флагов -->

Reviewed-on: #8
Co-authored-by: BrowenSiz <top.timashevsky@gmail.com>
2026-11-10 21:42:07 +00:00

21 KiB
Raw Blame History

AGENTS.md — контекст проекта «Штиль» для разработчиков и AI-ассистентов

1. Что мы строим

«Штиль» — отечественная RMM-платформа (Remote Monitoring & Management) для ИТ-отделов и MSP в РФ/СНГ. Коммерческий продукт T&B.Soft, закрытый код.

Компонент Где работает Что делает
Сервер shtil-server SaaS (ЦОД в РФ) или сервер заказчика Принимает агентов, хранит данные, отдаёт REST API
Приложение «Штиль» (Tauri 2 + Vue 3) ПК администраторов, техников, офисов филиалов Основной интерфейс для всех ролей, подключается к SaaS или on-prem серверу
Агент shtil-agent (Go) Каждое устройство, служба SYSTEM/root, без окон Связь с сервером, инвентаризация, метрики, выполнение подписанных команд, запуск Помощника
Помощник «Штиль Помощник» (Tauri 2) Сессия каждого пользователя ПК, иконка в трее Обращения сотрудников в ИТ-отдел, статусы и ответы, уведомления; фаза 2 — согласие и индикатор удалённого доступа
  • Помощник не имеет прав администратора и не общается с сервером напрямую — только с агентом через IPC (named pipe / unix socket) с проверкой подлинности. На серверах без графической сессии работает только агент.
  • Уровни доступа — роль назначается на область (организация → филиал → отдел), права наследуются вниз. Офис филиала видит только метрики и данные своего филиала, главный админ видит и может всё. ADR-0008.
  • Обращение (ticket) — сообщение сотрудника через Помощника с автодиагностикой. Алерт (alert) — автоматическое событие мониторинга. Оба попадают в раздел «Входящие». ADR-0006.
  • Удалённый доступ — два режима: «с согласием» (запрос пользователю, видимый индикатор сеанса) и «без согласия» (серверы и ПК без людей: отдельное право, повторная 2FA, обязательная причина), плюс смешанный режим. Решение о показе запроса принимает агент по подписанной политике, а не сервер. ADR-0007.

Поставка: SaaS и on-prem (вплоть до изолированного контура) из одной кодовой базы.

2. Команда и реальность

  • 2 разработчика, работают вместе и постоянно на связи. Отдельных DevOps, QA и дизайнера нет.
  • Продуктовый план рассчитан на 16–18 человек, поэтому объём сознательно режется, а технологии выбираются с минимальной операционной нагрузкой.
  • Главный риск — растянуть MVP. Всё, что вне текущего шага дорожной карты, идёт в бэклог.
  • Задачи, статусы, обсуждения и решения ведутся в дорожной карте (shtil-roadmap.html с сервера). Отдельного трекера нет. ID задач (2.11) и пунктов (2.11.4) используются в ветках, коммитах и PR.
  • Код — в Gitea на своём сервере, CI — Gitea Actions (act_runner).
  • Чтобы понять, что решила команда, читай сводку из «Настройки → Сводка для AI» или progress.json: поля decisions, answers, comments, notes, custom.

3. Стек (зафиксирован, менять только через ADR)

Слой Технология
Сервер Go, монолит: один бинарник, одна БД, функции отключаются программно
HTTP API REST + OpenAPI 3 (spec-first), роутер net/http (Go 1.22+) или chi
Протокол агента WebSocket поверх TLS 443 + Protobuf, mTLS-идентификация агента
IPC агент ↔ Помощник Protobuf поверх named pipe (Windows) / unix socket (Linux)
Внутренняя шина NATS (встроенный в бинарник; внешний кластер — при масштабировании SaaS)
БД PostgreSQL 16+ (совместимость с Postgres Pro), pgx/v5 + sqlc, миграции goose
Метрики PostgreSQL (партиционирование) за интерфейсом MetricStore, ClickHouse позже
Файлы S3-совместимое хранилище (MinIO)
Приложение и Помощник Tauri 2 + Vue 3 + TypeScript (strict) + Vite + Pinia + Vue Router + TanStack Query
UI Общая дизайн-система packages/ui: Reka UI (headless) + Tailwind CSS, иконки Lucide
Удалённый доступ WebRTC (Pion) + собственный TURN — фаза 2
Наблюдаемость log/slog (JSON), OpenTelemetry, Prometheus-метрики
Dev-окружение Docker Compose, Taskfile, mise

Версии инструментов (Go, Node LTS, pnpm, Task, Rust, Tauri) зафиксированы в .mise.toml и rust-toolchain.toml, объяснение и установка — docs/environment.md.

4. Архитектурные принципы (обязательны)

  1. Мультиарендность с первого дня. У каждой таблицы организации есть tenant_id. Изоляция двойная: проверка в коде (организация берётся из контекста запроса) и Row-Level Security в Postgres. Доступ к данным организации — только через WithTenantTx. Системные таблицы без tenant_id оформляются явно.
  2. Монолит с понятными границами. Код сервера лежит в internal/server/<область> (access, sites, devices, tickets, remote…). Это организация кода, а не отдельные модули: общая БД и общие транзакции разрешены. Правило: таблицы области меняет только код этой области; другие области вызывают её сервисные функции, а не пишут SQL в чужие таблицы. Слои внутри области: обработчик HTTP → сервис → запросы к БД.
  3. Функции отключаются программно. Каталог функций и лимитов — internal/server/features. Итоговое значение: аварийное отключение в конфиге → редакция лицензии → настройка организации → значение по умолчанию. Проверка в API, фоновых задачах, приложении (/me/features) и агенте (HelloAck). Технические флаги для незаконченной разработки удаляются после релиза функции. Никаких if saas по коду.
  4. Безопасность в основе. RMM имеет права администратора на всех устройствах клиента, поэтому взлом платформы означает взлом всех клиентов.
    • Агент ↔ сервер: mTLS, ключ создаётся на устройстве, сертификат выдаётся при регистрации, CA сервера закреплён в агенте.
    • Каждая команда агенту подписана (Ed25519) и содержит tenant_id, device_id, nonce, expires_at. Агент отклоняет неподписанные, чужие и просроченные команды.
    • Политика удалённого доступа подписана и применяется агентом. Локальный запрет на устройстве сервер снять не может.
    • 2FA (TOTP) для пользователей приложения, повторная 2FA для подключения без согласия.
    • Журнал аудита только дополняется (цепочка хэшей). Каждое действие с устройством и каждая попытка удалённого доступа попадают в журнал.
    • Секреты не попадают ни в логи, ни в git, ни в ответы API. Скриншоты обращений — персональные данные: ограниченный срок хранения и доступ по правам.
  5. Протокол агента и IPC версионируются. Только обратно совместимые изменения, buf breaking в CI, поле protocol_version. Сервер поддерживает агентов N-2 версий.
  6. Агент работает автономно. Без связи события и обращения копятся в локальной очереди; переподключение с exponential backoff и jitter. Сервер выдерживает шторм переподключений.
  7. Маршрутизация команд через NATS subject agent.<tenant>.<device>. Соединения агентов не хранят состояние, которое нельзя потерять (задел под --only=gateway).
  8. Всё асинхронное идемпотентно. Команды, обращения, задачи и вебхуки имеют id, повторная доставка безопасна.
  9. Время в UTC, ID в UUIDv7, деньги — целые копейки, никаких float.
  10. Доступ = право + область. access.Require(ctx, perm, object) для действий, access.ScopesFor(ctx, perm) + SQL-фильтр по поддеревьям sites.path для списков. Приложение только скрывает недоступное, источник истины — сервер.

5. Структура репозитория (монорепо)

cmd/shtil-server            точка входа сервера
cmd/shtil-agent             точка входа агента
internal/server/            серверный монолит
  app/                      сборка зависимостей и запуск
  platform/                 config, log, db, httpx, bus, obs
  access/ features/ audit/ auth/ tenants/ sites/ users/
  devices/ tickets/ commands/ remote/   (следующие шаги)
internal/agent/             агент: transport, collectors, executor, ipc, service, platform/{windows,linux}
internal/shared/            общее для сервера и агента
proto/agent/v1, proto/helper/v1   контракты (buf)
api/openapi.yaml            контракт REST API
migrations/                 SQL-миграции (goose)
apps/console/               приложение «Штиль» (Vue в src/, Tauri в src-tauri/)
apps/helper/                «Штиль Помощник»
packages/ui/                общая дизайн-система
packages/api-client/        сгенерированный TS-клиент
deploy/dev/                 docker-compose для разработки
poc/                        временные прототипы для проверки решений (удаляются после ADR)
docs/                       ai/, status/, journal/, frontend/, backend/, adr/, architecture/, ux/, testing/, research/, glossary.md
roadmap/                    data.js (содержание), app.js + app.css (интерфейс), progress.json (работа команды)
tools/roadmap-server/       сервер дорожной карты (Go, без зависимостей)
tools/roadmap-context/      сводка дорожной карты для AI (Node, только чтение)
shtil-roadmap.html          дорожная карта

6. Правила для кода

Go

  • Go — последняя стабильная версия. Поддерживаемые ОС — ADR-0001 (Go ≥ 1.21 не работает на Windows 7/8.1/Server 2012 R2).
  • gofmt и golangci-lint без предупреждений. Ошибки оборачиваются fmt.Errorf("...: %w", err), panic в бизнес-коде не используется.
  • context.Context — первый аргумент любой функции с I/O.
  • SQL пишется руками и генерируется через sqlc. ORM не используется.
  • Тесты табличные. Интеграционные — против настоящего Postgres (testcontainers-go). Для каждой новой таблицы организации обязателен тест изоляции.

Frontend (приложение и Помощник)

  • TypeScript strict, any запрещён. Типы API генерируются из api/openapi.yaml, руками не пишутся.
  • Composition API + <script setup>. Серверное состояние — TanStack Query, клиентское — Pinia.
  • Все строки интерфейса — через vue-i18n, даже если пока есть только русский.
  • Компоненты — из packages/ui. Новый базовый компонент сначала добавляется туда.
  • Вызовы Tauri API и плагинов — только через слой src/platform/.
  • Видимость элементов — через v-can / useFeature, без ручных проверок ролей.

Общее

  • Термины — по docs/glossary.md. Новый термин сначала добавляется в словарь.
  • Ветки feat/<ID>-кратко, коммиты Conventional Commits с областью (feat(server): …) и строкой Refs: <ID подзадачи>, PR в Gitea «[ID] Название», squash merge.
  • Коммиты и PR пишутся на русском языке, понятно и чётко. Тип и область остаются латиницей (их читают инструменты), всё остальное — по-русски:
    • заголовок: тип(область): что сделано — с маленькой буквы, без точки, до 72 символов, глагол в прошедшем времени (добавлен, исправлена, убрано);
    • тело (если нужно): почему и что важно знать, а не пересказ диффа;
    • последняя строка: Refs: <ID пункта>.
    • Хорошо: feat(server): добавлен WithTenantTx для доступа к данным организации, fix(console): исправлен повтор запроса после истечения токена.
    • Плохо: fix, правки, update files, WIP, английский текст.
    • Заголовок squash-коммита при слиянии PR тоже по-русски, обычно совпадает с названием PR.
    • Формат проверяет хук commit-msg (lefthook), --no-verify не используется. Полные правила git — docs/contributing.md, описание PR — по шаблону .gitea/pull_request_template.md.
  • Изменения api/openapi.yaml, proto/, migrations/ — отдельным PR.
  • Значимое техническое решение — ADR в docs/adr/NNNN-название.md и поле «Решение» в дорожной карте.
  • Без лишних комментариев: комментарий объясняет «почему», а не «что».

7. Чего НЕ делать (особенно AI-ассистентам)

  • Не предлагать микросервисы, Kubernetes, GraphQL, Kafka и прочее «на вырост» без ADR.
  • Не добавлять зависимость без проверки лицензии: AGPL/GPL запрещены (в том числе код RustDesk и MeshCentral). Разрешены MIT, BSD, Apache-2.0, MPL-2.0.
  • Не использовать сервисы и зависимости, которые могут стать недоступны из РФ. Всё работает on-prem без интернета (шрифты и иконки — локально).
  • Не писать запросы к данным организации без tenant_id и мимо WithTenantTx.
  • Не выполнять на агенте ничего без проверенной подписи. Не давать серверу обходить решение агента о согласии пользователя.
  • Не давать Помощнику прав администратора и прямой связи с сервером.
  • Не делать функции вне текущего шага и не делать «не в MVP»: бэкап, MDM, полный ITIL, антивирус, BI, MSP-биллинг, ИИ.
  • Не перенумеровывать ID задач в roadmap/data.js: новые пункты получают следующий свободный номер. Отметки и обсуждения в progress.json привязаны к этим ID.
  • Не редактировать progress.json на сервере руками — его пишет только roadmap-server. Свои пункты команды (custom) при раскрытии следующего шага переносятся в data.js новыми ID.

8. Команды разработки

Появятся в шаге 2.8. Ориентир:

task setup      # установить инструменты и зависимости
task dev        # postgres, nats, minio, mailpit + сервер + приложение
task test       # все тесты
task lint       # все линтеры
task gen        # sqlc + buf + oapi-codegen + openapi-typescript
task migrate    # миграции
task seed       # демо-организация «Ромашка»
task build      # все артефакты

9. Документирование и контекст (обязательно для AI)

Память проекта живёт в файлах, а не в чате. Полный протокол — docs/ai/PROTOCOL.md, выполняй его в каждой сессии.

  • Начало сессии: прочитай docs/status/shared.md, docs/status/<зона>.md, последние записи docs/journal/, сверься с дорожной картой (node tools/roadmap-context/roadmap-context.mjs [ID]), коротко доложи, где мы и что предлагаешь. До этого код не пишется.
  • Зоны: frontend, backend, shared. Читай shared + свою зону, пиши в свою зону + shared. Всё, что видит или от чего зависит другая сторона, — в shared.
  • Перед коммитом: запись журнала ветки, обновлённый статус зоны, shared при влиянии на другую сторону, ADR для значимых решений. PR без документации не готов.
  • Дорожная карта (https://locshare.ru/roadmap/) — трекер задач. AI только читает её (docs/ai/roadmap.md) и в конце работы выдаёт блок «Для дорожной карты»: какие пункты отметить, какой статус поставить, текст сообщения или решения.