164 lines
8.7 KiB
Markdown
164 lines
8.7 KiB
Markdown
# spacesh — руководство пользователя
|
||
|
||
spacesh — терминал-воркспейс для параллельного запуска AI-агентов (Claude Code,
|
||
Codex, Gemini, opencode, shell) на macOS. Сессиями владеет фоновый демон, а не
|
||
окно: закрыл GUI, обновил приложение или словил краш — агенты продолжают
|
||
работать, а при следующем открытии экран восстанавливается из снапшота.
|
||
|
||
> Сборка и ручное тестирование описаны отдельно в [`RUNNING.md`](DOCS/RUNNING.md).
|
||
> Техническая спецификация — в [`MAIN.md`](DOCS/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`.
|
||
|
||
---
|
||
|
||
## Главное окно
|
||
|
||
|
||
|
||
Три зоны:
|
||
|
||
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 — следующее/предыдущее. Поиск
|
||
привязан к панели, на которой открыт, и не «уезжает» при переключении фокуса.
|
||
|
||
---
|
||
|
||
## Настройки
|
||
|
||
|
||
|
||
Шестерёнка в шапке. Всё хранится демоном в `~/.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 <path> # открыть/создать воркспейс
|
||
spacesh new-surface ... # добавить панель
|
||
spacesh notify ... # сообщить статус (для хуков агентов)
|
||
```
|
||
|
||
`$SPACESH_SURFACE_ID` инъектируется в окружение каждой панели — хуки знают, о
|
||
какой панели рапортуют.
|
||
|
||
---
|
||
|
||
## В планах
|
||
|
||
- Внешние уведомления в **Telegram** и **MAX** (подписчик на шине событий).
|
||
- Diff-просмотр изменений агента.
|
||
- Удалённая работа через SSH-туннель к демону.
|
||
|
||
---
|
||
|
||
## Где что лежит
|
||
|
||
- Конфиг: `~/.spacesh/config.toml`
|
||
- Socket: `~/.spacesh/sock`
|
||
- Lock: `~/.spacesh/daemon.lock`
|
||
- Состояние воркспейсов и лог событий: `~/.spacesh/` (персист демона)
|