Files
shtil/docs/research/helper-tray-poc.md
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

149 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PoC «Штиль Помощник»: Tauri только с иконкой в трее
Задачи #1.8.1–1.8.2, задел для решения ADR-0005 (выбор технологии Помощника — #1.8.3).
Код — `poc/helper-tray/`. Папка `poc/` временная: после принятия ADR-0005 удаляется.
## Что проверяем
Рекомендация карты: Tauri 2 в режиме «только трей» — при старте окно не создаётся,
WebView не запускается; окно создаётся по клику и уничтожается при закрытии.
Цели из дорожной карты:
| Метрика | Цель |
|---|---|
| ОЗУ в покое (только трей) | ≤ 40 МБ |
| ОЗУ с открытым окном | ≤ 150 МБ |
| Время открытия окна | ≤ 1 с |
Если цели не достигаются — запасной вариант: трей на Go + окно Tauri по запросу.
## Как устроен PoC
- `src-tauri/tauri.conf.json`: `app.windows: []` — окна при старте нет; строгий CSP
(`default-src 'self'; style-src 'self' 'unsafe-inline'; connect-src ipc: http://ipc.localhost`
— последнее нужно IPC по кастомному протоколу на Linux/macOS, иначе Tauri
переходит на postMessage-запасной вариант); identifier `ru.tbsoft.shtil.helper.poc`.
- `src-tauri/src/lib.rs`:
- трей (`tray-icon`) с меню «Сообщить о проблеме» / «Мои обращения» / «О программе»;
пункт «Выход» есть только в debug-сборке (`cfg!(debug_assertions)`);
- каждый пункт создаёт окно через `WebviewWindowBuilder` с меткой `win-<view>-<n>`;
закрытие окна уничтожает его (не `hide`), повторный клик — новое окно;
- `RunEvent::ExitRequested` → `prevent_exit()` только при `code.is_none()`:
закрытие последнего окна не завершает приложение в трее, а программный
`app.exit(0)` (сценарий замера, «Выход (debug)») работает;
- замер времени открытия: `Instant` перед `build()` окна → фронтенд после
`mounted` + двойной `requestAnimationFrame` (вторая рамка = первая уже
отрисована) вызывает команду `first_paint` → разница в мс пишется в лог.
Команды приложения не входят в ACL, плагинов нет — capability окон `win-*`
имеет пустой `permissions`;
- флаг `--measure-scenario` (только для замера): приложение по таймеру делает
30 с покоя → открывает окно → 10 с → закрывает → 10 с → открывает повторно →
10 с → закрывает и завершается. Отметки этапов пишутся в
`helper-tray-poc.measure.log` (рядом с exe, при недоступности — в `%TEMP%`)
за ~1,5 с до действия, чтобы скрипт успел снять ОЗУ.
- `src/App.vue`: форма по прототипу — кнопки-категории, поле описания, кнопка
«Отправить» (отправки нет). «Мои обращения» и «О программе» — заглушки.
- `measure.ps1`: запускает exe с `--measure-scenario`, читает отметки из лога,
снимает два счётчика дерева процессов (приложение + все дочерние
`msedgewebview2.exe`, по цепочке родителей и по user-data-dir в командной
строке) из `Win32_PerfFormattedData_PerfProc_Process`:
- **PrivateBytes** — committed private memory. **Решение принимаем по ней:**
Windows урезает рабочий набор у простаивающих процессов, поэтому
WorkingSetPrivate для покоя занижен;
- **WorkingSetPrivate** — private working set, для справки.
5 прогонов, медиана и разброс.
## Сборка и запуск
Версии инструментов — `docs/environment.md`.
```bash
cd poc/helper-tray
pnpm install
pnpm tauri build # release-сборка: exe и установщики в src-tauri/target/release/
# без установщиков быстрее: pnpm tauri build --no-bundle
```
Запуск: `src-tauri/target/release/helper-tray.exe` — появляется только иконка
в трее, окна нет. В release-режиме выхода из меню нет: завершение — через
диспетчер задач или `taskkill /IM helper-tray.exe /F`.
Разработка: `pnpm tauri dev` (в debug-сборке есть пункт «Выход (debug)»).
### Linux (Astra 1.8 / Debian 12)
Зависимости из `docs/environment.md` (включая `libayatana-appindicator3-dev`).
Дальше те же `pnpm install` и `pnpm tauri build`. Примечания:
- иконка в трее требует работающего AppIndicator/StatusNotifier (в Astra —
через расширение трея, если трей пустой — это ограничение среды, не PoC);
- `measure.ps1` — только Windows. Для Linux замер вручную: запуск с
`--measure-scenario`, в моменты отметок лога снять PSS дерева процессов
(`smem -P <pid>` или сумма `Private_*` из `/proc/<pid>/smaps_rollup`
по дереву `pstree -p <pid>`). Строку для результатов см. в таблице.
## Методика замера (как в задании)
- Только release-сборка. Каждый замер — 5 прогонов сценария, в отчёт — медиана
и разброс (min–max).
- ОЗУ в покое — через 30 с после старта, до первого окна.
- ОЗУ с открытым окном — через 10 с после открытия.
- ОЗУ после закрытия окна — через 10 с (проверка освобождения).
- Время открытия — холодное (первое окно) и тёплое (повторное), из лога.
- ОЗУ — **PrivateBytes** всего дерева процессов (решающая метрика) и
WorkingSetPrivate для справки. Обычный working set завышает цифру на общую
память WebView2, а private working set занижает её для простаивающих
процессов — Windows вытесняет их страницы.
## Результаты
ОС: Windows 11 · машина Frontend-разработчика · дата: 2026-11-09 · сборка release.
PB — PrivateBytes (решающая метрика), WS — WorkingSetPrivate (для справки).
| Метрика | Цель | Медиана (5 прогонов) | Разброс | Итог |
|---|---|---|---|---|
| ОЗУ в покое, PB | ≤ 40 МБ | 2,0 МБ | 2,0 – 2,0 | ✅ |
| ОЗУ в покое, WS | — | 1,5 МБ | 1,5 – 1,5 | — |
| ОЗУ с окном, PB | ≤ 150 МБ | 155,3 МБ | 154,9 – 158,3 | ⚠ +4 % к цели |
| ОЗУ с окном, WS | — | 97,3 МБ | 96,9 – 100,3 | — |
| ОЗУ после закрытия, PB | освобождение | 5,2 МБ | 5,0 – 5,2 | ✅ |
| ОЗУ после закрытия, WS | — | 3,6 МБ | 3,5 – 3,6 | — |
| Открытие окна, холодное | ≤ 1 с | 580 мс | 570 – 622 | ✅ |
| Открытие окна, тёплое | ≤ 1 с | 555 мс | 540 – 648 | ✅ |
| ОЗУ повторного окна, PB | — | 157,4 МБ | 155,6 – 160 | — |
| ОС | Покой, PB | Окно, PB | После закрытия, PB | Открытие хол./тёпл. | Дата |
|---|---|---|---|---|---|
| Windows 11 | 2,0 МБ | 155,3 МБ | 5,2 МБ | 580 / 555 мс | 2026-11-09 |
| Astra 1.8 | — ждём VM #1.12.5 — | | | | |
## Выводы
- Покой и скорость открытия — с большим запасом: **2,0 МБ PB** (цель ≤ 40),
открытие **~0,58 с** (цель ≤ 1 с). «Только трей» реально не запускает
WebView2 до первого окна — 2 МБ это весь процесс.
- Окно по решающей метрике **155,3 МБ PB — на ~4 % выше цели 150 МБ**
(по WorkingSetPrivate — 97 МБ и цель формально выполнена). Это честный
предел WebView2 на Windows 11: private bytes включают зарезервированную,
но не вытянутую память рендерера. Обсуждение того, насколько цель жёсткая
и считаем ли проходом, — в #1.8.3.
- `destroy()` при закрытии освобождает память полностью — через 10 с остаётся
~5,2 МБ PB самого процесса.
- Холодное и тёплое открытие почти не различаются (~0,6 с); повторное окно по
памяти такое же (~157 МБ PB).
- Для ADR-0005: на Windows 11 режим «Tauri только трей» выполняет цели по
покою и скорости и не дотягивает ~5 МБ по окну. Запасной вариант «трей на
Go + окно Tauri» по памяти окна ничего не даст — окно в обоих вариантах на
Tauri/WebView2, выигрыш был бы только в покое, а там уже 2 МБ.
Решающий фактор — повторение замера на Astra 1.8 (WebKitGTK): Максим, после
появления VM #1.12.5.
- Что переносить в Помощник при выборе Tauri: паттерн `app.windows: []` +
`prevent_exit` при `code.is_none()`, фабрика окон с `destroy`, замер
`first_paint` (двойной rAF → invoke), пустой `permissions` у capability,
строгий CSP с `connect-src ipc: http://ipc.localhost`, меню без «Выход».
## Что PoC не делает (вне задания)
Нет IPC с агентом, отправки обращений, уведомлений, i18n, дизайн-системы,
автозапуска, установщика-поставки. Решение по технологии Помощника принимается
в #1.8.3 совместно с Backend — по этим замерам.