Files
2026-11-20 08:58:36 +01:00

159 lines
10 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.
# herdr-composer
Pasek wiadomości dla agentów w [Herdr](https://herdr.dev). Jedno pole pod terminalem pisze do agenta, który ma fokus. Do tego:
- drafty per agent, które przetrwają restart,
- kolejka czekająca na koniec tury agenta,
- historia i ulubione,
- dock z przyciskami do często wysyłanych komend (np. `/handoff`),
- podpowiedzi `/` i `@`,
- jeden sposób dodawania załączników: upuszczenie, przycisk `+`, Ctrl+V.
![herdr-composer](herdr/herdr-composer/preview.png)
## Wymagania
- **Windows.** Przycisk `+` i wklejanie obrazów przez Ctrl+V używają PowerShell. Reszta działa wszędzie, gdzie działa Herdr.
- **Herdr** (`herdr-app`, `hc`) w `PATH`. Sprawdzone na herdr-core 0.1.21.
- **Git** z dostępem do `http://git.mkali.pl/Factor/herdrMario.git` (repo prywatne). Klonowanie użyje Twoich zapisanych poświadczeń.
- Do testów: **Node.js ≥ 20**.
## Instalacja
Obie drogi dają ten sam wynik.
**1. Przez agenta** (tak jak layouty z herdr.dev). Wklej agentowi w Herdr:
```text
Read ~/.config/herdr-app/AGENTS.md, then add this layout: clone http://git.mkali.pl/Factor/herdrMario.git and use the folder herdr/herdr-composer
```
**2. Jedną komendą** (`cmd`):
```cmd
git clone http://git.mkali.pl/Factor/herdrMario.git "%USERPROFILE%\herdrMario" && "%USERPROFILE%\herdrMario\install.cmd"
```
`install.cmd` uruchamia `scripts\install.ps1` z `-ExecutionPolicy Bypass`, tylko dla tego jednego wywołania. Działa więc także tam, gdzie uruchamianie skryptów `.ps1` jest wyłączone. Instalator:
- **Aktualizuje repo:** robi `git pull --ff-only`, ale tylko w czystym klonie. Błąd pull to ostrzeżenie, nie przerwanie.
- **Kopiuje mod i layout:** mod trafia do `~\.config\herdr-app\mods\herdr-composer` (kopia lustrzana), layout do `layouts\herdr-composer.json`. Herdr sam wczytuje nowe pliki. Jeśli istnieje inny layout o tej nazwie, najpierw robi jego kopię zapasową.
- **Dopisuje skrót** do Twojego `keys.json`: `ctrl-shift-space` przenosi fokus do composera. Przed zapisem robi kopię. Klawisza, który masz przypisany do czegoś innego, nie rusza i wypisuje ostrzeżenie. Formatowanie `keys.json` się zmienia, znaczenie nie.
- **Usuwa poprzednią wersję `ovis-composer`:** junction albo katalog modu, layout i skrót. Historia, ulubione, drafty i kolejki zostają (patrz [Przejście z ovis-composer](#przejście-z-ovis-composer)).
- **Sprawdza i przełącza:** uruchamia `herdr-app check`. Na layout `herdr-composer` przełącza tylko przy pierwszej instalacji albo wtedy, gdy aktywny był `ovis-composer`. W pozostałych przypadkach podpowiada `ctrl-shift-l`.
Wszystkie kopie zapasowe trafiają do `~\.config\herdr-app\backups\herdr-composer\<rrrrMMdd-HHmmss>\`, nigdy do `mods\` ani `layouts\`, bo Herdr wczytałby je jako mod lub layout. Pliki repo nigdy nie są usuwane.
## Aktualizacja
Uruchom ponownie `install.cmd` albo poproś agenta jeszcze raz. Herdr sam przeładuje mod, bez restartu.
## Odinstalowanie
```cmd
install.cmd -Uninstall
```
Usuwa `mods\herdr-composer`, `layouts\herdr-composer.json` i skrót z `keys.json`, a potem przełącza na layout `main`. Zostają tylko kopie w `backups\herdr-composer\`.
## Użycie
| Klawisz / akcja | Co robi |
|---|---|
| klik w pole, `Ctrl+Shift+Space` | fokus w composerze (klik w terminal oddaje klawiaturę terminalowi) |
| `Enter` / `Shift+Enter` | wyślij / nowa linia |
| `Ctrl+Enter` | wyślij teraz, z pominięciem kolejki |
| `Alt+Enter` | do kolejki jako wstrzymana (wyślesz ręcznie) |
| `Esc` | zamyka menu lub panel; przy pustym polu przerywa pracującego agenta |
| `/`, `@` | podpowiedzi komend, skilli i plików; `↑` `↓` wybór, `Enter`/`Tab` wstaw |
| `Ctrl+R` albo 🕘 | panel Historia / Ulubione: `↑` `↓`, `Enter` wstawia w miejscu kursora (bez wysyłania), `Tab` przełącza zakładki, `Ctrl+D` dodaje do ulubionych, `Esc` lub ✕ zamyka |
| ☆ | zapisuje bieżący tekst w ulubionych; prawy klik przypina go do docka |
| dock (przyciski za ☆) | klik wysyła zapisany tekst do agenta (jak Enter, przez kolejkę) albo, w trybie ✎, wstawia go w miejscu kursora; tekst w polu zostaje |
| prawy klik na przycisk docka | Zmień nazwę, Tylko wstawiaj / Wysyłaj od razu, Przesuń w lewo / w prawo, Usuń z docka |
| prawy klik na wiersz panelu | Wstaw, Dodaj do ulubionych / Usuń z ulubionych; w Ulubionych także Przypnij do docka / Odepnij z docka |
| `+`, upuszczenie pliku, `Ctrl+V` obrazu | załącznik: kopiowany do agenta przez `hc put` i dopisywany jako `@ścieżka` |
**Kolejka:** gdy agent pracuje, `Enter` dodaje wiadomość do kolejki. Po zakończeniu tury pojawia się odliczanie 3 s z przyciskiem Anuluj, a potem wiadomość wychodzi. Stop albo `Esc` wstrzymuje całą kolejkę. Gdy agent czeka na Twoją odpowiedź (`blocked`), `Enter` wysyła ją od razu (`hc send --force`).
**Dock:** wspólny dla wszystkich agentów, do 30 przycisków. Przyciski dodajesz prawym klikiem na wpis w Ulubionych („Przypnij do docka”) albo na ☆ (bieżący tekst). Gdy przycisków jest dużo, dock przewija się w bok.
**Dane:** historia (500 wpisów), ulubione (100), dock (30 przycisków), drafty i kolejki zapisują się lokalnie w `~\.config\herdr-app\shared.json` (klucze `herdr-composer.*`). Obrazy ze schowka trafiają do `~\.config\herdr-app\data\herdr-composer\paste\` i są usuwane po 7 dniach. Nic nie jest wysyłane poza ten komputer.
## Inni agenci
Menu `/` podpowiada komendy według **profilu agenta**. Domyślne profile są dla Claude Code (alias `claude`) i `codex`. Dla innego agenta menu pokazuje komendy, które wysłałeś mu wcześniej (grupa „Z historii”) oraz szary wiersz „Nieznany agent `<klucz>` – dodaj profil w ~/.config/herdr-app/composer-agents.json”. Klucz z tego wiersza wpisz w polu `match`.
Profile dopisujesz w pliku `~\.config\herdr-app\composer-agents.json` (albo `$HERDR_APP_HOME\composer-agents.json`) na komputerze, na którym działa agent. Zmiana pojawia się w menu w ciągu minuty, bez restartu i bez reinstalacji.
```json
{
"agents": [
{
"id": "nazwa-profilu",
"match": ["klucz-agenta"],
"builtins": [{ "key": "model", "desc": "Wybiera model." }],
"sources": [
{ "scope": "project", "path": ".agent/prompts", "pattern": "*.md" },
{ "scope": "home", "path": ".agent/prompts", "pattern": "*/SKILL.md", "prefix": "@" }
]
}
]
}
```
- `id` (wymagany): nazwa profilu. Profil z tym samym `id` co domyślny **zastępuje go w całości**, bez łączenia list.
- `match` (wymagany, niepusta lista): klucze agenta, bez rozróżniania wielkości liter. Najpierw sprawdzane są profile z pliku, potem domyślne.
- `builtins` (opcjonalny): `{ "key", "desc" }`, grupa „Wbudowane”.
- `sources` (opcjonalny): `scope` to `"project"` (względem folderu panelu; grupa „Projekt”) albo `"home"` (względem folderu domowego; grupa „Użytkownik”). `path` jest względna, bez `..`. `pattern` to `"*.md"` (nazwa komendy = nazwa pliku bez `.md`) albo `"*/SKILL.md"` (nazwa skilla z `name:` we frontmatterze, a w projekcie z nazwy folderu). `prefix` (domyślnie `"/"`) to tekst wstawiany przed nazwą. Źródło `{ "scope": "home", "kind": "claude-plugins" }` czyta pluginy Claude Code.
- Brak pliku to norma. Uszkodzony plik jest ignorowany (działają profile domyślne), a menu pokazuje wiersz „`composer-agents.json`: <powód>”.
**Przykład dla kiro-cli: niesprawdzony.** Nie znamy klucza ani komend tego agenta, więc poniższe wartości są tylko ilustracją. Klucz weź z wiersza „Nieznany agent …” na maszynie z kiro.
```json
{
"agents": [
{
"id": "kiro",
"match": ["kiro-cli", "kiro"],
"builtins": [{ "key": "context" }, { "key": "model" }],
"sources": [
{ "scope": "project", "path": ".kiro/prompts", "pattern": "*.md" },
{ "scope": "home", "path": ".kiro/prompts", "pattern": "*.md", "prefix": "@" }
]
}
]
}
```
## Co mod uruchamia i czyta
Agent instalujący paczkę poinformuje o tym przed instalacją.
- **`hc`:** `send`, `put`, `get`, `interrupt`, `keys`. Tak mod rozmawia z terminalami agentów.
- **`powershell`:** odczyt schowka, okno wyboru pliku, rozmiary plików, odczyt komend i skilli z folderów projektu wskazanych w profilu agenta (dla Claude Code `.claude/`). Ścieżki trafiają do skryptów wyłącznie jako Base64.
- **`git ls-files`** w folderze agenta: podpowiedzi `@`.
- **Pliki spoza folderu modu:** pliki, które sam dodajesz jako załączniki, foldery komend z profilu agenta (dla Claude Code `.claude/commands`, `.claude/skills` projektu i `~\.claude`) oraz `composer-agents.json` w `~\.config\herdr-app\`.
- **Sieć:** mod nie korzysta z sieci.
## Przejście z ovis-composer
Wcześniejsza wersja nazywała się `ovis-composer`. Instalator usuwa ją automatycznie. Mod przy pierwszym odczycie przenosi dane z kluczy `ovis-composer.*` do `herdr-composer.*`; starych kluczy nie kasuje. Instalator nie rusza starych kopii `mods\ovis-composer.bak-*` i `layouts\ovis-composer.json.bak-*`. Możesz je usunąć ręcznie.
## Rozwiązywanie problemów
- **Composer się nie pokazuje:** sprawdź `herdr-app status`. Pole `"layout"` powinno mieć wartość `herdr-composer`, a `"errors"` powinno być puste. Layout przełączysz przez `ctrl-shift-l`.
- **Mod nie reaguje po zmianie plików:** uruchom ponownie `install.cmd`. Herdr widzi tylko pliki w `~\.config\herdr-app\mods\`, a nie te w repo.
- **`Ctrl+Shift+Space` nie działa:** sprawdź, czy w `~\.config\herdr-app\keys.json` (sekcja `global`) jest `"ctrl-shift-space": "herdr-composer.focus"` i czy obok nie powstał plik `keys.error`.
- **Coś nie gra po instalacji:** `install.cmd -Uninstall`, a potem przywróć potrzebny plik z `backups\herdr-composer\`. Awaryjnie `ctrl-alt-shift-escape` zawsze wraca do layoutu `main`.
## Rozwój
Struktura repo:
- `herdr/herdr-composer/`: paczka w formacie Herdr (`layouts/`, `mods/herdr-composer/`, `keys.json`, `RECIPE.md`, `preview.png`).
- `tests/`: testy czystych modułów (`npm test`).
- `scripts/install.ps1`: instalator, wywoływany przez `install.cmd`.
- `docs/superpowers/`: specyfikacja, plany, makieta, raporty weryfikacji.
Cykl pracy: edytuj pliki w `herdr/herdr-composer/mods/herdr-composer/`, uruchom `npm test`, potem `install.cmd`, żeby skopiować zmianę do Herdr. Problemy pokażą `herdr-app check "%USERPROFILE%\.config\herdr-app\mods\herdr-composer"` i `herdr-app status`.