diff --git a/DOCS/GUIDE.md b/DOCS/GUIDE.md new file mode 100644 index 0000000..ff560cc --- /dev/null +++ b/DOCS/GUIDE.md @@ -0,0 +1,163 @@ +# spacesh — руководство пользователя + +spacesh — терминал-воркспейс для параллельного запуска AI-агентов (Claude Code, +Codex, Gemini, opencode, shell) на macOS. Сессиями владеет фоновый демон, а не +окно: закрыл GUI, обновил приложение или словил краш — агенты продолжают +работать, а при следующем открытии экран восстанавливается из снапшота. + +> Сборка и ручное тестирование описаны отдельно в [`RUNNING.md`](./RUNNING.md). +> Техническая спецификация — в [`MAIN.md`](./MAIN.md). + +--- + +## Как это устроено + +- **`spaceshd` (демон)** — единственный источник истины. Владеет живыми + PTY-сессиями, держит грид-модель экрана, слушает один Unix-socket + (`~/.spacesh/sock`), хранит конфиг и лог событий. +- **GUI (Tauri)** и **CLI `spacesh`** — тонкие клиенты. Состояния не хранят, + только шлют команды и подписываются на события. Клик в GUI и `spacesh focus` + из скрипта — одна и та же операция. +- GUI/CLI **поднимают демон лениво**, если он не запущен. + +Следствие: GUI можно перезапускать и обновлять, не теряя сессии агентов. + +--- + +## Установка + +- **Готовый билд:** скачать `.dmg`, перетащить `spacesh.app` в `/Applications`. + Сборка пока без подписи — при первом запуске снять карантин: + ```bash + xattr -dr com.apple.quarantine /Applications/spacesh.app + ``` +- **Из исходников** (нужны Rust + Node ≥ 20): + ```bash + make reinstall # собирает .app, ставит в /Applications, перезапускает демон + ``` + Полный список целей — `make help`. + +--- + +## Главное окно + +![Главное окно spacesh](./images/app-overview.png) + +Три зоны: + +1. **Сайдбар (слева)** — список воркспейсов и групп. Кнопка **New workspace** + (⌘N). У каждого воркспейса слева — кольцо агрегированного статуса (см. ниже), + справа на наведении — звезда (избранное) и корзина (удаление). + - Сворачивается кнопкой-гамбургером в шапке: вместо полного списка остаётся + узкий **rail** со статус-кольцами — активность видна даже в свёрнутом виде. +2. **Сетка панелей (центр)** — терминалы агентов в выбранной раскладке. +3. **Центр событий (справа)** — лента уведомлений о сменах статуса и выходах. + +--- + +## Воркспейсы + +- **Создание:** New workspace (⌘N) → выбрать папку проекта, раскладку (пресет) + и агентов по слотам. +- **Переименование:** двойной клик по названию в сайдбаре → ввести новое → + Enter (Esc — отмена). +- **Избранное:** звезда на строке. Запиненные собираются в секцию **FAVORITES** + сверху. +- **Порядок:** перетаскивание строк внутри секции мышью. +- **Удаление:** корзина на строке → модалка с подтверждением. Если в воркспейсе + есть живые терминалы — предупреждение, что они будут завершены. + +## Панели + +- **Раскладки/пресеты:** `1`, `2↔`, `2↕`, `2+1`, `1+2`, `3`, `2×2`, `4`, `2×3`, + `2×4` — кнопки в тулбаре над сеткой. +- **Ресайз:** тянуть разделитель между панелями. +- **Перетаскивание:** взять панель за шапку (иконка‐грип) и бросить к краю + другой — переставляется местами/делится. +- **Зум:** иконка разворота в шапке панели — панель на весь грид; повторный клик + возвращает. +- **Перезапуск:** если процесс вышел, в панели кнопка **Restart**. + +--- + +## Статусы агентов + +Статус приходит **пушем** — от хуков агентов (`spacesh notify`), маркеров +OSC 133 для shell и паттернов как запасной вариант: + +| Статус | Значение | Цвет | +|---------|-----------------------------------|----------| +| `work` | агент работает | синий | +| `wait` | ждёт ввода/лимита | жёлтый | +| `done` | задача завершена | зелёный | +| `error` | ошибка | красный | +| `idle` | простаивает | серый | + +Статус виден кольцом в шапке панели и в сайдбаре (агрегат по воркспейсу). + +### Центр событий + +Лента справа. Вкладки **All / Unread / Errors**. Клик по записи — фокус на +нужной панели. Действия в шапке: + +- **Mark all read** — пометить всё прочитанным. +- 🗑 (красная корзина) — очистить весь лог событий (на пустом списке неактивна). + +--- + +## Поиск по скроллбэку + +`⌘F` на сфокусированной панели открывает строку поиска **в её заголовке** — +видно, где именно ищем. Поиск инкрементальный (по мере ввода), с подсветкой и +счётчиком совпадений; Enter / Shift+Enter — следующее/предыдущее. Поиск +привязан к панели, на которой открыт, и не «уезжает» при переключении фокуса. + +--- + +## Настройки + +![Модалка настроек](./images/settings.png) + +Шестерёнка в шапке. Всё хранится демоном в `~/.spacesh/config.toml` и +применяется на лету ко всем окнам. Закрыть — крестик справа сверху или Esc. + +- **Terminal** — шрифт (курированный список) и размер (10–20). +- **Appearance** — тема **Dark / Light** и акцентный цвет. +- **Default shell** — shell для plain-панелей; пусто = автоопределение + (env `SPACESH_SHELL` → config → login-shell из passwd → `$SHELL` → `/bin/sh`). +- **Daemon** — версия, build-id, pid, uptime и кнопка **Restart** + (перезапускает демон; панели переподцепляются автоматически). + +--- + +## CLI + +`spacesh` — те же операции, что и в GUI, поверх той же шины: + +```bash +spacesh status --json # состояние воркспейсов/панелей +spacesh focus s_8f3 # сфокусировать панель +spacesh open # открыть/создать воркспейс +spacesh new-surface ... # добавить панель +spacesh notify ... # сообщить статус (для хуков агентов) +``` + +`$SPACESH_SURFACE_ID` инъектируется в окружение каждой панели — хуки знают, о +какой панели рапортуют. + +--- + +## В планах + +- Внешние уведомления в **Telegram** и **MAX** (подписчик на шине событий). +- Diff-просмотр изменений агента. +- Удалённая работа через SSH-туннель к демону. + +--- + +## Где что лежит + +- Конфиг: `~/.spacesh/config.toml` +- Socket: `~/.spacesh/sock` +- Lock: `~/.spacesh/daemon.lock` +- Состояние воркспейсов и лог событий: `~/.spacesh/` (персист демона) diff --git a/DOCS/images/app-overview.png b/DOCS/images/app-overview.png new file mode 100644 index 0000000..d6805ad Binary files /dev/null and b/DOCS/images/app-overview.png differ diff --git a/DOCS/images/settings.png b/DOCS/images/settings.png new file mode 100644 index 0000000..3f8d484 Binary files /dev/null and b/DOCS/images/settings.png differ