Files
herdrMario/docs/superpowers/specs/2026-11-20-agent-profiles-design.md
2026-11-20 08:47:20 +01:00

123 lines
9.7 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.
# 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`.