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

9.7 KiB
Raw Blame History

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

{
  "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.