docs: Unified Prompt Experience design spec
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
commit
cca08c5645
1 file changed
+235
@@ -0,0 +1,235 @@
|
|||||||
|
# Herdr — Unified Prompt Experience: projekt
|
||||||
|
|
||||||
|
Data: 2026-11-19 · Gałąź: `feature/unified-prompt` · Status: projekt (bramka A), przed makietą
|
||||||
|
|
||||||
|
## 1. Cel i powód
|
||||||
|
|
||||||
|
Jeden, stale widoczny Prompt Composer w Herdr do pracy z agentami AI uruchomionymi w terminalach
|
||||||
|
(Claude Code, Codex itd.). Wygoda pisania dłuższych promptów, załączniki (także obraz ze schowka),
|
||||||
|
historia, ulubione, autouzupełnianie i kolejka — jako jeden przepływ, wzorowany na UX Ovis.
|
||||||
|
|
||||||
|
## 2. Fakty z audytu (podstawa decyzji)
|
||||||
|
|
||||||
|
| # | Fakt | Źródło |
|
||||||
|
|---|---|---|
|
||||||
|
| F1 | Herdr to natywna aplikacja GPUI; rozszerzenia to mody JS (gpui-kit), layouty JSON, `keys.json`; wszystko przeładowuje się na żywo, bez rekompilacji. | `~/.config/herdr-app/AGENTS.md` |
|
||||||
|
| F2 | Agent w Herdr = terminal z programem TUI raportującym status (OSC 7501: `working/blocked/done/idle`). **Herdr nie ma widoku Chat.** | `AGENTS.md` („Agents are terminals…”) |
|
||||||
|
| F3 | Mod `prompt` to okno nazwy (rename), nie pole czatu. Pole wpisywania widoczne w terminalu rysuje program agenta. Mod nie może zmienić rysowania terminala. | `mods/prompt/main.js`, `AGENTS.md` („You can't … change how a terminal itself draws text”) |
|
||||||
|
| F4 | Istnieje mod `ovis-composer` (~2,3 tys. linii) i layout `ovis-composer` (klon `main`) z composerem w bloku `composer` (260 px) pod `work-body`. | `layouts/ovis-composer.json`, `mods/ovis-composer/*` |
|
||||||
|
| F5 | `ovis-composer` ma: drafty/załączniki/kolejkę per agent, wysyłkę `hc send`, załączniki przez `hc put` + `@path`, Drag & Drop (`on_drop`), autouzupełnianie `/` i `@` (`suggest.js`, `catalog.js`), stop (`hc interrupt`). | pliki modu |
|
||||||
|
| F6 | `storage.js` ma History (limit 500) i Favorites (limit 100), ale UI ich nie używa. Drafty nie są trwałe. Brak katalogu `tests/`, choć komentarze go wskazują. | `storage.js`, `main.js` |
|
||||||
|
| F7 | Composer dziś zabiera klawiaturę terminalowi (`reclaim`/`watchFocus`). | `main.js:401-430` |
|
||||||
|
| F8 | Mody czytają ze schowka tylko tekst; `Textarea` emituje `paste_other`, gdy schowek nie ma tekstu. | `gpui-kit.d.ts:346, 21469` |
|
||||||
|
| F9 | Mody mają `pickFolder`, nie mają wyboru pliku. Mają `exec`, `hc`, `shared/setShared`, `openOverlay`. | `herdr.d.ts` |
|
||||||
|
| F10 | `hc send` wkleja tekst i naciska Enter; nie potwierdza dostarczenia (zawsze `exit 0`). | `delivery.js` (pomiar 2026-11-17) |
|
||||||
|
| F11 | Ovis dostarcza obraz agentowi jako plik w `<cwd>/.ovis/` (z `.gitignore` `*`) + wzmianka `@<path>` w tekście. To jedyny kanał obrazu przez strumień PTY. | Ovis `server/paste.ts`, `lib/compose.ts:177` |
|
||||||
|
| F12 | `powershell Clipboard::GetImage()` działa na tej maszynie z poziomu `exec`. | próba 2026-11-19 |
|
||||||
|
|
||||||
|
## 3. Cele, nie-cele, anty-cele
|
||||||
|
|
||||||
|
**Cele**
|
||||||
|
- Jeden composer w globalnym layoucie, widoczny cały czas, jedna instancja i jeden stan.
|
||||||
|
- Drafty, załączniki i kolejka per agent; przełączanie agenta, zakładki, przestrzeni i layoutu nic nie gubi.
|
||||||
|
- History i Favorites w jednym panelu.
|
||||||
|
- Załączniki z trzech źródeł (przycisk, Drag & Drop, Ctrl+V) przez jeden mechanizm.
|
||||||
|
- Obraz realnie trafia do agenta jako plik + `@path`.
|
||||||
|
- Kolejka wiadomości podczas pracy agenta, bez dublowania.
|
||||||
|
- Fokus zawsze tam, gdzie kliknął użytkownik.
|
||||||
|
|
||||||
|
**Nie-cele**
|
||||||
|
- Widok Chat (transkrypt) — ewentualnie osobny, późniejszy projekt.
|
||||||
|
- Ukrywanie pola wpisywania w TUI agenta — technicznie niemożliwe bez rekompilacji i zmiany samego agenta (F3).
|
||||||
|
- Wsparcie macOS/Linux dla wyboru pliku i schowka obrazów w tym etapie.
|
||||||
|
|
||||||
|
**Anty-cele (porażka, nawet jeśli „działa”)**
|
||||||
|
- Composer przechwytuje klawisze, gdy fokus jest w terminalu.
|
||||||
|
- Załącznik widoczny w UI, który nie trafia do agenta.
|
||||||
|
- Utrata draftu lub wiadomości z kolejki przy przełączaniu, restarcie lub przerwaniu agenta.
|
||||||
|
- Podwójne wysłanie tej samej wiadomości.
|
||||||
|
- Zmiany w plikach dostarczanych przez Herdr (layout `main`, mody shipped).
|
||||||
|
|
||||||
|
## 4. Ograniczenia
|
||||||
|
|
||||||
|
- Bez rekompilacji Herdr. Tylko mod, layout-klon, `keys.json`.
|
||||||
|
- Mody shipped są tylko do odczytu; pracujemy wyłącznie na `ovis-composer` (nasz klon) i layoucie `ovis-composer`.
|
||||||
|
- Dane tylko lokalnie (`shared.json` przez `setShared`); nic do usług zewnętrznych.
|
||||||
|
- Wysyłka tylko przez `hc` (`send`, `put`, `interrupt`, `keys`, `wait`).
|
||||||
|
|
||||||
|
## 5. Rozważone podejścia (decyzje użytkownika z 2026-11-19)
|
||||||
|
|
||||||
|
**Widok Chat**
|
||||||
|
- A — bez widoku Chat, composer pod terminalem agenta. **Wybrane.** Najmniej pracy, zgodne z architekturą Herdr (F2).
|
||||||
|
- B — mod Chat renderujący transkrypt + stack Chat/Terminal. Odrzucone na ten etap: parser per agent, duży zakres.
|
||||||
|
|
||||||
|
**Baza kodu**
|
||||||
|
- Rozbudowa istniejącego `ovis-composer`. **Wybrane.** Działa już globalny blok, kolejka, `hc put`, autocomplete (F4, F5).
|
||||||
|
- Pisanie od zera. Odrzucone: powiela gotową, zmierzoną logikę (F10).
|
||||||
|
|
||||||
|
**Fokus i klawiatura**
|
||||||
|
- 1a — fokus tam, gdzie klik; powrót do composera kliknięciem lub skrótem. **Wybrane.**
|
||||||
|
- 1b — composer stale zabiera fokus (stan obecny). Odrzucone: łamie wymóg pisania wprost w terminalu.
|
||||||
|
|
||||||
|
**History i Favorites**
|
||||||
|
- 2a — jeden panel z zakładkami `Historia | Ulubione`. **Wybrane.**
|
||||||
|
- 2b — osobne przyciski i panele. Odrzucone: więcej kontrolek.
|
||||||
|
|
||||||
|
**Przycisk „dodaj plik”**
|
||||||
|
- 3a — systemowy dialog Windows przez `exec` PowerShell. **Wybrane.**
|
||||||
|
- 3b — bez przycisku. Odrzucone.
|
||||||
|
|
||||||
|
## 6. Projekt
|
||||||
|
|
||||||
|
### 6.1. Układ (layout `ovis-composer`)
|
||||||
|
|
||||||
|
Bez zmian strukturalnych: blok `composer` pod `work-body`, nad `status`. Rozmiar bloku: wysokość dopasowana
|
||||||
|
do treści — edytor auto 1–10 linii (wzór Ovis), ręczne przeciąganie granicy bloku (`resizable` layoutu).
|
||||||
|
Panel History/Favorites, menu autouzupełniania i podgląd obrazu otwierają się jako nakładki nad composerem
|
||||||
|
(`openOverlay` / floating), więc nie zmieniają wysokości obszaru terminala.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌ tabs ─────────────────────────────────────────────────────┐
|
||||||
|
│ terminal agenta (TUI z własnym polem — zostaje widoczne) │
|
||||||
|
├ kolejka (tylko gdy niepusta) ──────────────────────────────┤
|
||||||
|
│ ⏳ Następna tura: „popraw testy…” [↑ Teraz][✎][✕] │
|
||||||
|
├ composer ──────────────────────────────────────────────────┤
|
||||||
|
│ [img][plik.ts ✕] │
|
||||||
|
│ Napisz do Claude Code… │
|
||||||
|
│ [+][🕘] /komenda @plik Claude Code · working [■]│
|
||||||
|
│ ~/repo · main │
|
||||||
|
└────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2. Fokus i klawiatura
|
||||||
|
|
||||||
|
- Usuwamy `reclaim`/`watchFocus` (F7). Composer nigdy sam nie zabiera fokusu.
|
||||||
|
- Fokus do composera: kliknięcie w composer lub skrót `ctrl-shift-space` (wpis w `keys.json` wysyłający komendę
|
||||||
|
`focus` do modu; mechanizm `nextCommand` już istnieje, `main.js:165`).
|
||||||
|
- W composerze: Enter — wyślij; Shift+Enter — nowa linia; Ctrl+Enter — wyślij teraz (gdy agent pracuje);
|
||||||
|
Alt+Enter — wstrzymaj (do kolejki bez automatycznej wysyłki); Esc — zamyka menu/panel, a gdy nic nie jest
|
||||||
|
otwarte i agent pracuje — przerywa agenta tylko przy pustym polu (wzór Ovis, ochrona przed przypadkiem).
|
||||||
|
Strażnik IME (`isComposing`).
|
||||||
|
- Fokus w terminalu: composer nie reaguje na żaden klawisz. Ctrl+V, `/`, `@` działają po stronie terminala.
|
||||||
|
|
||||||
|
### 6.3. Model danych
|
||||||
|
|
||||||
|
Klucz kontekstu: **adres agenta** (np. `t2`), bo to on jest celem `hc`. (Uwaga: `state.js` w komentarzu mówi
|
||||||
|
„agent name”, `main.js` — adres; ujednolicamy na adres.)
|
||||||
|
|
||||||
|
| Byt | Cykl życia | Przechowywanie |
|
||||||
|
|---|---|---|
|
||||||
|
| Draft `{text, caret}` | od pisania do wysłania | `shared("ovis-composer.draft:<agent>")`, zapis z opóźnieniem ~500 ms — **nowe**: drafty przeżywają restart |
|
||||||
|
| Załącznik `{id, kind:image/file, name, localPath, remotePath, bytes, state: adding/ready/error, error}` | od dodania do wysłania/usunięcia | razem z draftem |
|
||||||
|
| Wpis kolejki `{id, text, attachments, state, createdAt, reason}` | od zakolejkowania do wysłania/usunięcia | `ovis-composer.queue:<agent>` (istnieje) |
|
||||||
|
| Wpis historii `{id, text, sentAt, agent, agentName, space, spaceName}` | po faktycznym `hc send` z `exit 0` | `ovis-composer.history`, limit 500, duplikaty zachowane |
|
||||||
|
| Ulubiony `{id, text, createdAt}` | od oznaczenia do usunięcia | `ovis-composer.favorites`, limit 100 |
|
||||||
|
|
||||||
|
Historia i ulubione są niezależne: gwiazdka na wpisie historii kopiuje tekst do ulubionych.
|
||||||
|
|
||||||
|
### 6.4. Załączniki — jeden potok
|
||||||
|
|
||||||
|
Trzy wejścia → jedna funkcja `addFiles(paths)`:
|
||||||
|
1. **Przycisk `+`** → `exec powershell` z `OpenFileDialog` (multi-select) → lista ścieżek.
|
||||||
|
2. **Drag & Drop** → `on_drop` → `event.paths` (istnieje).
|
||||||
|
3. **Ctrl+V z obrazem** → zdarzenie `paste_other` → `exec powershell` zapisuje `Clipboard::GetImage()` jako PNG
|
||||||
|
do `<cwd agenta>/.ovis/paste-<czas>.png` (katalog dostaje `.gitignore` z `*`) → ścieżka. Brak obrazu → komunikat
|
||||||
|
„Schowek nie zawiera tekstu ani obrazu”. Ctrl+V z tekstem — standard pola tekstowego, bez zmian.
|
||||||
|
Schowek z plikami (skopiowanymi w Eksploratorze) → `Clipboard::GetFileDropList()` → te same ścieżki.
|
||||||
|
|
||||||
|
`addFiles`: walidacja (`attachments.js`: 32 MiB, typy, 100 na akcję) → kafelek w stanie `adding` →
|
||||||
|
`hc put <agent> <plik> --json` → `remotePath` → stan `ready` + wzmianka `@<remotePath>` w tekście
|
||||||
|
(istniejący mechanizm `mention`). Błąd → kafelek `error` z powodem i przyciskiem ponów.
|
||||||
|
Usunięcie kafelka usuwa wzmiankę (`removeMention`, istnieje). Miniatura obrazu: `image(localPath)`;
|
||||||
|
kliknięcie → nakładka podglądu (proporcje zachowane, `fit: contain`), Esc zamyka.
|
||||||
|
|
||||||
|
Gdy obraz jest dodany, a program agenta nie jest znany jako obsługujący obrazy (lista: claude, codex, gemini,
|
||||||
|
opencode), composer pokazuje ostrzeżenie przed wysłaniem — nie blokuje.
|
||||||
|
|
||||||
|
### 6.5. History / Favorites
|
||||||
|
|
||||||
|
- Przycisk 🕘 w pasku composera i skrót `ctrl-r` (tylko gdy fokus w composerze) otwierają panel nad composerem.
|
||||||
|
- Zakładki `Historia | Ulubione` (Tab przełącza), pole wyszukiwania z fokusem na starcie.
|
||||||
|
- Wyszukiwanie na żywo, bez wielkości liter, po fragmentach; dopasowania podświetlone; `×` czyści.
|
||||||
|
- Wiersz: tekst (2 linie, skrót), data i godzina, przestrzeń · agent; gwiazdka.
|
||||||
|
- Historia od najnowszych, ze wszystkich przestrzeni i agentów. Lista wirtualna (`v_virtual_list`).
|
||||||
|
- Strzałki — wybór; Enter — wstaw; Esc — zamknij i wróć do edytora.
|
||||||
|
- Wstawienie do niepustego draftu → mały wybór w panelu: `Zastąp` / `Dopisz na końcu` / `Anuluj`.
|
||||||
|
Pusty draft — wstawia od razu. Kursor na końcu tekstu, fokus w edytorze. Nigdy nie wysyła.
|
||||||
|
- Stany: pusta historia, brak wyników.
|
||||||
|
- Gwiazdka w composerze (przy niepustym drafcie) dodaje bieżący tekst do Ulubionych.
|
||||||
|
|
||||||
|
### 6.6. Autouzupełnianie
|
||||||
|
|
||||||
|
Bez zmian koncepcyjnych (F5): `/` na początku słowa — komendy i skille z katalogu (`catalog.js`), `@` — pliki
|
||||||
|
(`git ls-files`). Menu nad composerem, max 5 widocznych wierszy, grupy, ranking po użyciu (`ovis-composer.usage`).
|
||||||
|
Strzałki, Enter/Tab — akceptuj, Esc — zamknij. `/` i `@` zawsze wpisują się normalnie.
|
||||||
|
|
||||||
|
### 6.7. Kolejka i stany wiadomości
|
||||||
|
|
||||||
|
Decyzja wg statusu agenta (istnieje, `delivery.decide`): `idle/done` → wyślij; `working` → kolejka;
|
||||||
|
`blocked` → Enter z composera wysyła od razu (odpowiedź na pytanie agenta); kolejka stoi, dopóki agent nie
|
||||||
|
wróci do `working`/`idle` (decyzja użytkownika 2026-11-19, 2a).
|
||||||
|
|
||||||
|
Automatyczna wysyłka z kolejki (agent `working → idle/done`) poprzedzona jest 3-sekundowym odliczaniem
|
||||||
|
„Wysyłam za 3 s [Anuluj]” na wierszu; Anuluj → `held`. Powód: Ctrl+C wciśnięte bezpośrednio w terminalu
|
||||||
|
wygląda dla Herdr jak koniec tury (decyzja użytkownika 2026-11-19, 1a). Stop/Esc z composera → cała kolejka `held` od razu.
|
||||||
|
|
||||||
|
| Stan wewnętrzny | Co widzi użytkownik |
|
||||||
|
|---|---|
|
||||||
|
| `idle` (brak wiadomości w locie) | nic |
|
||||||
|
| `queued` | „Następna tura” |
|
||||||
|
| `held` | „Wstrzymana — wyślij ręcznie” |
|
||||||
|
| `sending` | spinner na wierszu |
|
||||||
|
| `sent` | wiadomość znika z kolejki, trafia do historii; krótko „Wysłano do terminala” |
|
||||||
|
| `uncertain` / `delivery_error` | „Nie potwierdzono” + [Ponów] [Edytuj] [Usuń] |
|
||||||
|
| `stopped` (agent przerwany) | kolejka **wstrzymana** (wszystko → `held`), nic nie wysyła się samo |
|
||||||
|
|
||||||
|
Akcje wiersza: Wyślij teraz, Edytuj (wraca do edytora; jeśli draft niepusty — ten sam wybór co w historii),
|
||||||
|
Usuń. Ochrona przed duplikatem: stan `sending` zapisywany przed `hc send` (istnieje), przycisk Wyślij
|
||||||
|
nieaktywny w `sending`. Po restarcie `sending` → `uncertain` (istnieje, `onRestart`).
|
||||||
|
|
||||||
|
### 6.8. Kontekst
|
||||||
|
|
||||||
|
Pasek pod edytorem: nazwa agenta + status (kropka), przestrzeń, folder i gałąź (z `panes()`), liczba załączników.
|
||||||
|
Bez modelu — Herdr go nie udostępnia. Gdy fokus Herdr nie wskazuje agenta: composer nieaktywny z napisem
|
||||||
|
„Wybierz agenta”, draft zachowany.
|
||||||
|
|
||||||
|
### 6.9. Obsługa błędów (wspólna)
|
||||||
|
|
||||||
|
Jedno miejsce na komunikat (`notice`, istnieje) + stan na konkretnym elemencie (kafelek, wiersz kolejki).
|
||||||
|
`hc` z `error` w JSON lub kodem ≠ 0 → komunikat ze `stderr`. Błąd zapisu `shared` → komunikat, dane w pamięci.
|
||||||
|
|
||||||
|
## 7. Repozytorium, instalacja, testy
|
||||||
|
|
||||||
|
- Źródła modu i testy w repo `herdrMario`: `mod/ovis-composer/*`, `layouts/ovis-composer.json`, `keys` (fragment),
|
||||||
|
`tests/*.test.mjs` (Node, `node --test`) dla modułów czystych (`state`, `delivery`, `storage`, `suggest`,
|
||||||
|
`attachments`, `view`, nowe: `history`, `clipboard`).
|
||||||
|
- Instalacja: junction `~/.config/herdr-app/mods/ovis-composer` → `herdrMario/mod/ovis-composer`
|
||||||
|
(najpierw kopia zapasowa obecnego katalogu). Layout kopiowany skryptem.
|
||||||
|
- Weryfikacja w aplikacji: `herdr-app check mods/ovis-composer`, `herdr-app status` (brak `errors`),
|
||||||
|
`herdr-app shot` do zrzutów.
|
||||||
|
- Weryfikacja obrazu end-to-end: wklej obraz → wyślij do Claude Code → agent opisuje treść obrazu.
|
||||||
|
|
||||||
|
## 8. Ryzyka
|
||||||
|
|
||||||
|
- `paste_other` może nie odpalać przy obrazie z niektórych programów → próba na starcie implementacji (spike).
|
||||||
|
- Opóźnienie `exec powershell` (~300–800 ms) → kafelek w stanie `adding` od razu.
|
||||||
|
- Aktualizacja Herdr zmienia API modów → `herdr-app check` po każdej aktualizacji; `.d.ts` są przepisywane przy starcie.
|
||||||
|
- `hc send` nie potwierdza dostarczenia (F10) → stan „Wysłano do terminala”, potwierdzenie ze statusu agenta.
|
||||||
|
|
||||||
|
## 8a. Decyzje po przeglądzie wykonawcy (decyzje architekta, do korekty przez użytkownika)
|
||||||
|
|
||||||
|
- **Obrazy i agenci zdalni:** obraz ze schowka zapisywany lokalnie w `~/.config/herdr-app/data/ovis-composer/paste/`
|
||||||
|
(nie w repo agenta), potem zawsze `hc put` — działa dla agenta lokalnego i zdalnego, jedna ścieżka dla
|
||||||
|
wszystkich trzech źródeł. Pliki starsze niż 7 dni są usuwane przy starcie modu. Zastępuje `<cwd>/.ovis/` z 6.4.
|
||||||
|
- **Ponowne użycie adresu agenta:** draft i kolejka zapisują też `program` i czas startu terminala
|
||||||
|
(z `terminals()`/`hc get`). Niezgodność po restarcie → kolejka cała `held`, draft przywrócony z komunikatem
|
||||||
|
„Szkic z poprzedniej sesji agenta”. Nic nie wysyła się samo do innego agenta.
|
||||||
|
- **Ctrl+C w composerze:** kopiuje zaznaczenie (standard). Przerwanie agenta: przycisk Stop lub Esc przy pustym polu.
|
||||||
|
- **Historia:** wpis po `hc send` bez błędu (kod 0 i brak `error` w JSON) — zgodnie z F10 oznacza „wklejono
|
||||||
|
do terminala”, nie „agent przyjął”.
|
||||||
|
- **Aktywny layout:** instalacja przełącza na `ovis-composer` (`layout.switch`); `main` pozostaje nietknięty.
|
||||||
|
|
||||||
|
## 9. Pozostawione wykonawcy
|
||||||
|
|
||||||
|
Nazwy funkcji i podział `main.js` na moduły; dokładne kolory i odstępy (wg makiety i `theme()`);
|
||||||
|
sposób zapisu draftu z opóźnieniem; komunikaty — w języku polskim, spójne z istniejącymi.
|
||||||
Reference in new issue
Block a user