123 lines
9.7 KiB
Markdown
123 lines
9.7 KiB
Markdown
# Profile agentów dla menu `/` — projekt
|
||
|
||
Data: 2026-11-20 · Gałąź: `feature/composer-dock` · Mod: `herdr/herdr-composer/mods/herdr-composer/`
|
||
|
||
## Cel i powód
|
||
Menu `/` composera ma podpowiadać komendy każdego agenta, nie tylko Claude Code. Na tej maszynie są Claude Code i codex. Kiro-cli i Antigravity CLI działają na innych komputerach i nie da się ich tu uruchomić. Nie znamy więc ich kluczy `agentName()` ani ich komend i nie wolno ich zgadywać. Rozwiązanie musi działać bez tej wiedzy w kodzie. Użytkownik dopisuje ją w pliku na maszynie, na której agent działa, bez zmian w kodzie i bez reinstalacji moda.
|
||
|
||
## Dziś
|
||
- `agentName(agent)` (`view.js:60`) zwraca `agent.app`, potem `program.key`, a w ostateczności `"default"`.
|
||
- `catalog.js` ma na sztywno:
|
||
- `BUILTINS["claude-code"]` (49 komend) i `BUILTINS.codex` (4 komendy);
|
||
- alias `claude` → `claude-code`;
|
||
- `isClaudeCode()`, które decyduje, czy czytać `.claude/commands`, `.claude/skills` projektu oraz `~/.claude` z pluginami (`globalCommands`).
|
||
- Agent spoza tej listy dostaje w menu `/` tylko snippety, a te dziś są zawsze puste (`snippets: []` w `main.js`).
|
||
- Historia (`storage.loadHistory`, do 500 wpisów, wspólna) zapisuje każdą wysłaną wiadomość z polem `agentName` = `agentName(agent)` (`main.js`, `recordSent`).
|
||
|
||
## Cele
|
||
1. **Profil agenta** opisuje: jakie nazwy z `agentName()` do niego pasują, jakie ma wbudowane komendy i skąd czytać jego własne komendy (folder projektu i folder domowy).
|
||
2. **Domyślne profile w kodzie** dla `claude-code` (z aliasem `claude`) i `codex`. Zachowują dzisiejsze działanie: te same komendy, grupy, kolejność i deduplikację.
|
||
3. **Plik użytkownika** `~/.config/herdr-app/composer-agents.json` (obok `shared.json`) dodaje nowe profile albo nadpisuje domyślne.
|
||
4. **Komendy z historii:** każde `/słowo` z początku wiadomości wysłanej wcześniej do agenta o tym samym `agentName` trafia do menu jako osobna grupa.
|
||
5. **Nieznany agent:** kiedy żaden profil nie pasuje, menu pokazuje wiersz informacyjny z dokładnym kluczem, który trzeba wpisać w pliku.
|
||
|
||
## Układ maszyn
|
||
Każdy komputer ma własną instalację herdr-app z tym modem, a agent działa lokalnie obok GUI (decyzja użytkownika). Plik profili, folder domowy i źródła są czytane lokalnie, bez `on: machine`. Agenci na zdalnych maszynach przez herdr-core są poza zakresem.
|
||
|
||
## Poza zakresem
|
||
- Edytor profili w GUI.
|
||
- Wpisywanie do kodu profili kiro-cli i Antigravity. Dostarczamy tylko przykład w README, wyraźnie oznaczony jako niesprawdzony.
|
||
- Inny wyzwalacz menu niż `/`.
|
||
- Zagnieżdżone skille (`~/.claude/skills/synced/`), czyli znany brak, który zostaje.
|
||
- `clipboard.js` `IMAGE_APPS`.
|
||
|
||
## Anty-cele (porażka, nawet jeśli działa)
|
||
- Jakakolwiek zmiana menu `/` dla Claude Code: inna lista, inne grupy, inna kolejność albo wolniejsze działanie.
|
||
- Uszkodzony lub brakujący plik użytkownika psuje menu. Ma wtedy działać na domyślnych profilach.
|
||
- Zgadywanie w kodzie kluczy lub komend agentów, których nie widzieliśmy.
|
||
|
||
## Podejścia (rozważone)
|
||
- **Skąd brać komendy nieznanego agenta:** (1) profile w pliku, (2) nauka z użycia, (3) oba. **Wybrane: oba** (decyzja użytkownika).
|
||
- **Gdzie trzymać profile:**
|
||
- **A.** Domyślne w kodzie plus plik w home.
|
||
- **B.** `shared()` z edytorem w GUI.
|
||
- **C.** `agents.json` w folderze moda.
|
||
- **Wybrane: A** (decyzja użytkownika). B oznacza dużo GUI do rzadkiej czynności. C nadpisuje `install.ps1` przy aktualizacji.
|
||
- **Nauka z użycia:** nowy magazyn albo odczyt historii. **Wybrane: historia** (moja decyzja). Ma już `agentName`, więc nie trzeba nowego klucza ani nowego zapisu.
|
||
|
||
## Format pliku `composer-agents.json`
|
||
```json
|
||
{
|
||
"agents": [
|
||
{
|
||
"id": "kiro",
|
||
"match": ["kiro-cli", "kiro"],
|
||
"builtins": [
|
||
{ "key": "context", "desc": "Zarządza kontekstem." },
|
||
{ "key": "model" }
|
||
],
|
||
"sources": [
|
||
{ "scope": "project", "path": ".kiro/prompts", "pattern": "*.md" },
|
||
{ "scope": "home", "path": ".kiro/prompts", "pattern": "*.md", "prefix": "@" }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
- `id` (wymagany, string): nazwa profilu. Profil z pliku o tym samym `id` co domyślny **zastępuje go w całości**. Bez łączenia list, żeby zachowanie było przewidywalne.
|
||
- `match` (wymagany, niepusta lista stringów): wartości `agentName()`, które pasują do profilu. Porównanie dokładne, bez rozróżniania wielkości liter. Pierwszy pasujący profil wygrywa, profile z pliku są sprawdzane przed domyślnymi.
|
||
- `builtins` (opcjonalny): `{key, desc?}` trafiają do grupy `Wbudowane`.
|
||
- `sources` (opcjonalny): lista źródeł.
|
||
- `scope`: `"project"` (względem `cwd` panelu, czytane przez `exec` jak dziś `projectItems`) albo `"home"` (względem folderu domowego, czytane jak dziś `globalCommands`). Odpowiadają grupom `Projekt` i `Użytkownik`.
|
||
- `path`: folder względny. Ścieżka bezwzględna i `..` są odrzucane.
|
||
- `pattern`: `"*.md"` (nazwa komendy = nazwa pliku bez `.md`) albo `"*/SKILL.md"`. Inne wzorce są odrzucane. Nazwa skilla zależy od zakresu, tak jak dziś *(moja decyzja: CC bez zmian)*:
|
||
- `home`: `name:` z frontmattera, a gdy go brak, nazwa folderu; pomija `user-invocable: false`;
|
||
- `project`: zawsze nazwa folderu, bez filtra.
|
||
- `prefix` (opcjonalny, domyślnie `"/"`): co wstawia wybór z menu (`insert: prefix + key + " "`). Przydaje się agentowi, który wywołuje prompty inaczej niż `/`.
|
||
- Specjalne `{ "scope": "home", "kind": "claude-plugins" }` oznacza dzisiejszą logikę pluginów (`settings.json` → `enabledPlugins`, `installed_plugins.json`, `plugin.json`) i daje grupę `Pluginy`. Używa go domyślny profil `claude-code`. Inny profil może go użyć, ale nic poza tym nie robi.
|
||
- Domyślny profil `claude-code` w kodzie wyrażony w tym formacie:
|
||
- `match: ["claude-code", "claude"]`;
|
||
- `builtins`: dzisiejsze 49;
|
||
- `sources`: projekt `.claude/commands` `*.md`, projekt `.claude/skills` `*/SKILL.md`, home `.claude/commands` `*.md`, home `.claude/skills` `*/SKILL.md`, `claude-plugins`.
|
||
- Domyślny `codex`: `match: ["codex"]`, dzisiejsze 4 builtins, bez źródeł.
|
||
- `isClaudeCode()` znika z logiki katalogu. To, czy czytać `.claude`, wynika wyłącznie z profilu.
|
||
|
||
**Błędy w pliku.** Brak pliku jest normalny i oznacza same domyślne profile. Nieczytelny JSON albo zły kształt (`agents` nie jest listą) oznacza ignorowanie całego pliku. Pojedynczy zły profil lub źródło jest pomijany, reszta działa. Gdy plik został odrzucony w całości albo częściowo, menu `/` pokazuje u dołu jeden wiersz informacyjny: „`composer-agents.json`: <krótki powód>”.
|
||
|
||
## Komendy z historii
|
||
- Źródło: `storage.loadHistory(store)`. Bierzemy wpisy, których `agentName` jest równe bieżącemu `agentName(agent)` (porównanie bez rozróżniania wielkości liter).
|
||
- Z tekstu wpisu bierzemy pierwszy token, jeśli tekst po `trimStart()` zaczyna się od `/`, a token pasuje do `^/[A-Za-z0-9][\w:.-]*$`. Klucz to token bez `/`.
|
||
- Grupa: nowa `GROUP_HISTORY = "Z historii"`, dopisana na końcu `GROUPS` w `suggest.js` (przed `Terminal`, jeśli ta grupa jest używana w tym menu, inaczej na końcu). Opis to pusty string. `insert: "/" + key + " "`.
|
||
- Działa dla każdego agenta, także Claude Code.
|
||
|
||
## Kolejność i deduplikacja
|
||
Źródła są łączone w tej kolejności: builtins, źródła `project` profilu, źródła `home` profilu (w tym pluginy), snippety, historia. Nazwa pojawia się raz: wygrywa pierwsze źródło, które ją ma, tak jak dziś. Dla Claude Code bez historii lista jest identyczna z dzisiejszą.
|
||
|
||
## Nieznany agent
|
||
Żaden profil nie pasuje: menu pokazuje komendy z historii i snippety oraz jeden wiersz informacyjny „Nieznany agent `<agentName>` – dodaj profil w `~/.config/herdr-app/composer-agents.json`”. Wiersza nie da się wybrać (Enter/Tab go pomija, tak jak dzisiejsze komunikaty `NO_MATCH_MESSAGE` / `READ_ERROR_MESSAGE`). Agent o `agentName` = `"default"` też jest „nieznany”.
|
||
|
||
## Odświeżanie
|
||
Ścieżka pliku pochodzi z `appHome()` modułu `herdr` (honoruje `$HERDR_APP_HOME`), nie jest wpisana na sztywno *(moja decyzja)*. Plik profili i źródła `home` są czytane w tle (dzisiejsze `refreshGlobal`) z tym samym TTL 60 s. Pierwsze `/` po starcie nie czeka na plik. Dopóki plik nie został wczytany ani razu, wiersz „Nieznany agent” się nie pokazuje. Po wczytaniu otwarte menu przeładowuje się tak jak dziś *(moja decyzja: bez spowolnienia CC i bez fałszywego komunikatu)*. Zmiana pliku pojawia się w menu w ciągu minuty, bez restartu. Cache źródeł `home` jest trzymany **per profil** (`id`), bo dwa terminale mogą mieć różnych agentów. Źródła `project` są czytane jak dziś, przy każdym otwarciu menu.
|
||
|
||
## Testy
|
||
- Dzisiejsze testy `catalog.test.mjs` przechodzą bez zmian albo z mechaniczną zmianą wywołania.
|
||
- Nowe przypadki:
|
||
- wynik dla CC identyczny z wynikiem sprzed zmiany (lista kluczy, grup i `insert`);
|
||
- plik nadpisuje profil domyślny;
|
||
- plik dodaje profil z `prefix: "@"`;
|
||
- uszkodzony JSON → domyślne profile i wiersz informacyjny;
|
||
- zły profil pominięty, dobry działa;
|
||
- ścieżka z `..` odrzucona;
|
||
- komendy z historii (filtr agenta, regex, dedup z builtins);
|
||
- nieznany agent → wiersz z kluczem.
|
||
- GUI na tej maszynie: menu `/` dla CC wygląda tak jak przed zmianą. Plik testowy z profilem dla `codex` (albo z fałszywym `match` dla CC) pokazuje własne komendy w ciągu minuty.
|
||
|
||
## README
|
||
Krótka sekcja „Inni agenci”:
|
||
- skąd wziąć klucz (wiersz „Nieznany agent …” w menu);
|
||
- format pliku;
|
||
- przykład dla kiro, oznaczony jako niesprawdzony.
|
||
|
||
## Pozostawione wykonawcy
|
||
Podział funkcji między `catalog.js` a ewentualny nowy `profiles.js`, nazwy funkcji i dokładny kształt cache w `main.js`. Byle `catalog.js` dalej działał w czystym Node z wstrzykniętymi `exec` i `readText`.
|