# 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`: ”. ## 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 `` – 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`.