docs: README in Polish with requirements, usage, permissions, migration, troubleshooting
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
1 parent
ad8c25c713
commit
7fc7d0202c
1 file changed
+76
-44
@@ -1,74 +1,106 @@
|
|||||||
# herdr-composer
|
# herdr-composer
|
||||||
|
|
||||||
A message bar for [Herdr](https://herdr.dev) agents: one field under the terminal
|
Pasek wiadomości dla agentów w [Herdr](https://herdr.dev). Jedno pole pod terminalem pisze do agenta, który ma fokus. Do tego:
|
||||||
that writes to the focused agent, with per-agent drafts that survive a restart, a
|
|
||||||
queue that waits for the agent's turn, history and favourites, `/` and `@`
|
|
||||||
suggestions, and one pipeline for attachments (drop, `+`, Ctrl+V).
|
|
||||||
|
|
||||||
The package lives in [`herdr/herdr-composer/`](herdr/herdr-composer/) and has the
|
- drafty per agent, które przetrwają restart,
|
||||||
layout Herdr expects for shared mods and layouts:
|
- kolejka czekająca na koniec tury agenta,
|
||||||
|
- historia i ulubione,
|
||||||
|
- podpowiedzi `/` i `@`,
|
||||||
|
- jeden sposób dodawania załączników: upuszczenie, przycisk `+`, Ctrl+V.
|
||||||
|
|
||||||
- `layouts/herdr-composer.json` - the layout (a clone of `main` with the composer block)
|

|
||||||
- `mods/herdr-composer/` - the mod (ES modules)
|
|
||||||
- `keys.json` - the key it expects (`ctrl-shift-space` focuses the composer)
|
|
||||||
- `RECIPE.md` - the brief to build it from scratch, and what it runs and reads
|
|
||||||
|
|
||||||
Other folders: `tests/` (Node tests for the pure modules, `npm test`), `scripts/`
|
## Wymagania
|
||||||
(the installer), `docs/` (spec, plan, verification).
|
|
||||||
|
|
||||||
## Install
|
- **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**.
|
||||||
|
|
||||||
Two ways, the same result.
|
## Instalacja
|
||||||
|
|
||||||
**1. Through an agent** (the way herdr.dev layouts are added):
|
Obie drogi dają ten sam wynik.
|
||||||
|
|
||||||
|
**1. Przez agenta** (tak jak layouty z herdr.dev). Wklej agentowi w Herdr:
|
||||||
|
|
||||||
```text
|
```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
|
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. One command** (Windows):
|
**2. Jedną komendą** (`cmd`):
|
||||||
|
|
||||||
```cmd
|
```cmd
|
||||||
git clone http://git.mkali.pl/Factor/herdrMario.git "%USERPROFILE%\herdrMario" && "%USERPROFILE%\herdrMario\install.cmd"
|
git clone http://git.mkali.pl/Factor/herdrMario.git "%USERPROFILE%\herdrMario" && "%USERPROFILE%\herdrMario\install.cmd"
|
||||||
```
|
```
|
||||||
|
|
||||||
The installer:
|
`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:
|
||||||
|
|
||||||
- pulls the repo (`git pull --ff-only`, only when it is a clean clone; a failure is a warning);
|
- **Aktualizuje repo:** robi `git pull --ff-only`, ale tylko w czystym klonie. Błąd pull to ostrzeżenie, nie przerwanie.
|
||||||
- **copies** the mod to `~\.config\herdr-app\mods\herdr-composer` (a mirror) and the
|
- **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ą.
|
||||||
layout to `layouts\herdr-composer.json`, so Herdr loads the new files by itself (a layout that
|
- **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.
|
||||||
is already there and differs is saved first; an identical one is left alone);
|
- **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)).
|
||||||
- merges `keys.json` of the package into yours. **The installer rewrites `keys.json`**: the
|
- **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`.
|
||||||
formatting changes (indentation, line breaks), the meaning does not. A copy is saved first, and a
|
|
||||||
key you bind to something else is left alone, with a warning;
|
|
||||||
- clears away the earlier version, `ovis-composer` (a junction is unlinked, a directory or
|
|
||||||
layout is moved out, its key is removed) - your history, favourites, drafts and queue are
|
|
||||||
kept: the mod reads what the earlier version stored;
|
|
||||||
- runs `herdr-app check` on the mod and switches to the `herdr-composer` layout - on the first
|
|
||||||
install, or when the earlier `ovis-composer` layout was the shown one; otherwise it only says
|
|
||||||
how to switch (`ctrl-shift-l`). Without `herdr-app` on the PATH these are warnings, not errors.
|
|
||||||
|
|
||||||
Every copy the installer makes (the earlier mod, layouts, `keys.json`) goes to
|
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.
|
||||||
`~\.config\herdr-app\backups\herdr-composer\<yyyyMMdd-HHmmss>\`, never next to the originals:
|
|
||||||
Herdr loads whatever it finds in `mods\` and `layouts\`, so a backup left there would be loaded.
|
|
||||||
|
|
||||||
Files of this repo are never deleted.
|
## Aktualizacja
|
||||||
|
|
||||||
## Update
|
Uruchom ponownie `install.cmd` albo poproś agenta jeszcze raz. Herdr sam przeładuje mod, bez restartu.
|
||||||
|
|
||||||
Run `install.cmd` again (or ask the agent again). It is the same command: pull, copy, check.
|
## Odinstalowanie
|
||||||
There is no junction and no reload step - the copy is what Herdr sees.
|
|
||||||
|
|
||||||
## Uninstall
|
|
||||||
|
|
||||||
```cmd
|
```cmd
|
||||||
install.cmd -Uninstall
|
install.cmd -Uninstall
|
||||||
```
|
```
|
||||||
|
|
||||||
Removes `mods\herdr-composer`, `layouts\herdr-composer.json` and its key from `keys.json`, and
|
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\`.
|
||||||
switches to the `main` layout. Only the copies in `backups\herdr-composer\` stay.
|
|
||||||
|
|
||||||
## Develop
|
## Użycie
|
||||||
|
|
||||||
Edit the files in `herdr/herdr-composer/`, run `npm test`, then `install.cmd` to copy the
|
| Klawisz / akcja | Co robi |
|
||||||
change into Herdr (`herdr-app check <mods>\herdr-composer` and `herdr-app status` show problems).
|
|---|---|
|
||||||
|
| 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` lub prawy klik dodaje do ulubionych, `Esc` lub ✕ zamyka |
|
||||||
|
| ☆ | zapisuje bieżący tekst w ulubionych |
|
||||||
|
| `+`, 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`).
|
||||||
|
|
||||||
|
**Dane:** historia (500 wpisów), ulubione (100), 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.
|
||||||
|
|
||||||
|
## 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 `.claude/` projektu. Ś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, oraz `.claude/commands` i `.claude/skills` projektu.
|
||||||
|
- **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`.
|
||||||
Reference in new issue
Block a user