docs: move the user guide to the root README.md
Promotes DOCS/GUIDE.md to the repo root README (image/links repointed to DOCS/). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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`.
|
||||
|
||||
---
|
||||
|
||||
## Главное окно
|
||||
|
||||
|
||||
|
||||
Три зоны:
|
||||
|
||||
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/` (персист демона)
|
||||
Reference in New Issue
Block a user