From 891dd7207cf47701ae8efc0050cc07f02a5dd3f2 Mon Sep 17 00:00:00 2001 From: BrowenSiz Date: Wed, 11 Nov 2026 00:54:05 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20=D1=84=D1=83=D0=BD=D0=BA=D1=86=D0=B8=D0=B8?= =?UTF-8?q?=20=D0=9F=D0=BE=D0=BC=D0=BE=D1=89=D0=BD=D0=B8=D0=BA=D0=B0=20?= =?UTF-8?q?=D0=BF=D0=BE=20=D1=84=D0=B0=D0=B7=D0=B0=D0=BC=20=D0=B8=20=D1=87?= =?UTF-8?q?=D0=B5=D1=80=D0=BD=D0=BE=D0=B2=D0=B8=D0=BA=20ADR-0005?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/architecture/helper.md: фаза 1 (обращения), фаза 2 (удалённый доступ, уведомления, захват экрана), границы, черновой список IPC - docs/adr/0005-agent-and-helper.md: статус «Предложено», решение по технологии открыто до замера на Astra 1.8 (#1.8.3) Refs: 1.8.4, 1.8.5 --- docs/adr/0005-agent-and-helper.md | 37 ++++++++++++++++++++ docs/architecture/helper.md | 56 +++++++++++++++++++++++++++++++ docs/status/frontend.md | 7 ++-- docs/status/shared.md | 3 +- 4 files changed, 99 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0005-agent-and-helper.md create mode 100644 docs/architecture/helper.md diff --git a/docs/adr/0005-agent-and-helper.md b/docs/adr/0005-agent-and-helper.md new file mode 100644 index 0000000..0a7463f --- /dev/null +++ b/docs/adr/0005-agent-and-helper.md @@ -0,0 +1,37 @@ +# ADR-0005: ПО на устройстве — Агент и Помощник + +- **Статус:** Предложено +- **Дата:** 2026-11-11 +- **Задача:** #1.8 +- **Участники:** Oleg, Максим +- **Зоны:** shared + +## Контекст + +Пользователю нужен интерфейс на ПК: сообщить о проблеме, видеть статус обращения, подтвердить удалённое подключение. Агент — служба в Session 0 (Windows) / systemd (Linux) и физически не может показывать окна. Значит на устройстве два компонента: служба-агент и «Штиль Помощник» в сессии пользователя. Оставалось выбрать технологию Помощника: критерии — в покое ≤ 40 МБ ОЗУ, с открытым окном ≤ 150 МБ, открытие ≤ 1 с, общий UI-стек с приложением, работа в изолированном контуре. + +## Решение + +*Черновик до решения #1.8.3: архитектура подтверждена, выбор технологии ждёт замер на Astra 1.8.* + +- На устройстве два компонента: **агент** (служба, SYSTEM/root, единственный канал к серверу по mTLS) и **Помощник** (процесс в сессии пользователя, иконка в трее, без прав администратора). +- Помощник общается только с агентом по IPC (named pipe / unix socket, Protobuf, `proto/helper/v1`); агент проверяет подлинность Помощника (путь, подпись бинарника, пользователь сессии). +- Запуск: Windows — агент отслеживает входы и запускает Помощника в сессиях; Linux — XDG autostart, агент контролирует наличие. Пункта «Выход» нет, при падении агент перезапускает. +- Один установщик «агент + Помощник»; на серверах Помощник по умолчанию выключен. Иконка и название переопределяются конфигом (white-label для MSP). +- **Технология (предложение):** Tauri 2 в режиме «только трей»: окна нет при старте, форма создаётся по клику и уничтожается при закрытии. Подтверждено PoC (`poc/helper-tray`, `docs/research/helper-tray-poc.md`): Windows 11, release, медиана из 5 прогонов — покой 2,0 МБ PrivateBytes, открытие 580/555 мс, окно 155,3 МБ PrivateBytes (цель 150 — превышение ~5 МБ признано допустимым, т.к. расход даёт WebView2-движок, общий с приложением). +- Функции Помощника по фазам — `docs/architecture/helper.md`. + +## Рассмотренные варианты + +| Вариант | Плюсы | Минусы | +|---|---|---| +| **Tauri 2 трей + окно на WebView** | Общий UI-стек и дизайн-система с приложением, один язык для команды, WebView2 уже есть на Windows | Окно ~155 МБ PB > цели 150; на Linux зависит от WebKitGTK 4.1 | +| Трей на Go + окно Tauri по запросу | Покой ещё ниже (~2–3 МБ и так 2 МБ) | Окно всё равно на WebView — выигрыша по памяти с окном нет; второй стек IPC/сборки; выигрыш только в покое, который и так 20× ниже цели | +| Нативный трей + нативные окна (Go/Qt/winfrey) | Минимум памяти | Нет общего UI с приложением, два UI-стека, дороже поддержка — отклонено по трудозатратам | + +## Последствия + +- Нужны `proto/helper/v1` (черновик методов — `docs/architecture/helper.md`) и каркас `apps/helper/` на следующих шагах. +- Запасной путь при провале цели на Astra/РЕД ОС: трей на Go, окно Tauri по запросу. +- Решение пересматривается, если замер на Astra 1.8 (#1.12.5) покажет окно значительно выше ~160 МБ или открытие > 1 с. +- `poc/` удаляется после принятия ADR. diff --git a/docs/architecture/helper.md b/docs/architecture/helper.md new file mode 100644 index 0000000..a94d68b --- /dev/null +++ b/docs/architecture/helper.md @@ -0,0 +1,56 @@ +# Помощник «Штиль» — функции по фазам + +- **Задача:** #1.8.4 · **Статус:** черновик, утверждается решением #1.8.3 → ADR-0005 +- Источники: карточка #1.8 (диаграмма), #1.9 (обращения), #1.10 (удалённый доступ) + +## Роль и ограничения + +Помощник — процесс в сессии пользователя, единственный компонент на устройстве с интерфейсом. + +- Прав администратора нет, установки драйверов/служб не требует. +- С сервером напрямую не общается — только с агентом по IPC (named pipe / unix socket, Protobuf). +- Запуск: Windows — агентом при входе пользователя (служба в Session 0 окон не имеет); Linux — XDG autostart, агент контролирует наличие. +- Пункта «Выход» нет; при падении агент перезапускает. +- На серверах не ставится по умолчанию (параметр установки). +- Устанавливается одним инсталлятором с агентом; иконка и название переопределяются конфигом (white-label). + +## Фаза 1 — обращения (MVP) + +| Функция | Содержание | +|---|---| +| Иконка в трее | Меню: «Сообщить о проблеме», «Мои обращения», «О программе». Без окон при старте; окно создаётся по клику и уничтожается при закрытии | +| Форма обращения | Категории-кнопки: Не печатает · Нет сети/интернета · Медленно работает · Не работает программа · Нужен доступ или ПО · Другое. Описание (обязательно, ≤ 2000), срочность (обычная / срочно — работа стоит), контакт (телефон/кабинет, запоминается) | +| Скриншот | Снимается автоматически, показывается превью, кнопка «Убрать». Организация может отключить политикой | +| Отправка | Помощник → агент по IPC. Агент добавляет автодиагностику и отправляет; без связи копит в своей очереди — у Помощника очереди нет | +| «Мои обращения» | Последние 10: статус и ответы администратора, простая переписка внутри обращения | +| «О программе» | Версия, организация, статус связи с агентом | + +## Фаза 2 — удалённый доступ и уведомления + +| Функция | Содержание | +|---|---| +| Диалог согласия | Кто подключается и причина. Кнопки: Разрешить / Только просмотр / Отклонить. Нет ответа 30 с — отказ | +| Индикатор сеанса | Красная рамка по краю экрана + панель «К вам подключён {имя} · {время} · Завершить». Пользователь может прервать сеанс в любой момент | +| Захват экрана | По команде агента: служба в Session 0 рабочий стол не видит, снимает только процесс сессии. Передача потока агенту | +| Уведомления | Всплывающие: ответ по обращению, сообщения от администратора, события сеанса удалённого доступа | + +## Чего Помощник не делает + +- Не хранит данные дольше сессии, не имеет своей БД и очереди. +- Не показывает настроек пользователю (кроме white-label через конфиг агента). +- Не принимает решений по безопасности: показ диалога согласия решает агент по подписанной политике. +- Не работает в Session 0 и без графической сессии. + +## Черновой список методов IPC (`proto/helper/v1`) + +Для оценки поверхности протокола, детали — в #1.8.5 и позже. + +| Метод | Направление | Фаза | +|---|---|---| +| `TicketSubmit` | Помощник → агент | 1 | +| `TicketList` / `TicketReply` | Помощник ↔ агент | 1 | +| `ConsentRequest` / `ConsentResponse` | агент → Помощник → агент | 2 | +| `SessionIndicator` (start/stop) | агент → Помощник | 2 | +| `Notify` | агент → Помощник | 2 | +| `ScreenCapture` (start/stop) | агент → Помощник | 2 | +| `GetState` | Помощник → агент | 1 (статус связи для «О программе») | diff --git a/docs/status/frontend.md b/docs/status/frontend.md index 73e2686..06033d0 100644 --- a/docs/status/frontend.md +++ b/docs/status/frontend.md @@ -1,6 +1,6 @@ # Состояние: Frontend -Обновлено: 2026-11-09 · Владелец: Frontend-разработчик +Обновлено: 2026-11-11 · Владелец: Frontend-разработчик Снимок, а не история. Внутренние правила зоны — `docs/frontend/`. @@ -11,11 +11,12 @@ ## Сделано в текущем шаге - #1.2 правила git, шаблон PR, хуки, личные заметки `docs/private/`. - #1.3 версии инструментов; hello world Tauri и Go на Windows (#1.3.9, часть Frontend/Windows). -- #1.8.1–1.8.2 PoC трея Помощника (`poc/helper-tray/`): покой 2,0 МБ PB, окно 155,3 МБ PB (цель 150 не дотянута ~5 МБ), открытие ~0,58 с. Замеры — `docs/research/helper-tray-poc.md`. +- #1.8.1–1.8.2 PoC трея Помощника (`poc/helper-tray/`): покой 2,0 МБ PB, окно 155,3 МБ PB (цель 150 не дотянута ~5 МБ), открытие ~0,58 с. Замеры — `docs/research/helper-tray-poc.md`. PR #8 смержен. +- #1.8.4 список функций Помощника по фазам — `docs/architecture/helper.md`; черновик ADR-0005 «Предложено» — `docs/adr/0005-agent-and-helper.md`. ## В работе -- #1.8 · `feat/1.8-helper-tray-poc` · PR на проверке; осталось — замер на Astra 1.8 (Максим, #1.12.5) и решение в #1.8.3 +- #1.8 · `feat/1.8-helper-functions` · осталось — замер на Astra 1.8 (Максим, #1.12.5) и решение в #1.8.3 - #1.4 · без ветки · обсуждение поддерживаемых ОС (взял в работу) ## Ждём от Backend diff --git a/docs/status/shared.md b/docs/status/shared.md index 2dc7c36..3eddf14 100644 --- a/docs/status/shared.md +++ b/docs/status/shared.md @@ -1,6 +1,6 @@ # Состояние: общее (shared) -Обновлено: 2026-11-09 · Шаг 1 «Решения и подготовка» · Версия — +Обновлено: 2026-11-11 · Шаг 1 «Решения и подготовка» · Версия — Снимок, а не история. Правила — `docs/ai/PROTOCOL.md`, разделы 2 и 6. @@ -28,6 +28,7 @@ - 2026-11-08 · frontend → backend · правила git (`docs/contributing.md`), шаблон PR, хуки lefthook: после `git pull` выполнить `mise install && lefthook install` - 2026-11-08 · frontend → backend · версии инструментов зафиксированы: `git pull`, `mise trust && mise install` по `docs/environment.md` - 2026-11-09 · frontend → backend · PoC трея Помощника (#1.8.1–1.8.2): на Windows 11 по PrivateBytes покой 2,0 МБ (≤40 ✅), окно 155,3 МБ (цель 150 — не дотянуто ~5 МБ), открытие ~0,58 с ✅. Методика и как повторить на Astra 1.8 — `docs/research/helper-tray-poc.md`; нужен замер Максима для ADR-0005 (#1.8.3) +- 2026-11-11 · frontend → backend · функции Помощника по фазам (#1.8.4) — `docs/architecture/helper.md` с черновым списком методов IPC для `proto/helper/v1`; черновик ADR-0005 «Предложено» — `docs/adr/0005-agent-and-helper.md` ## Запросы между зонами