9.7 KiB
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) zwracaagent.app, potemprogram.key, a w ostateczności"default".catalog.jsma na sztywno:BUILTINS["claude-code"](49 komend) iBUILTINS.codex(4 komendy);- alias
claude→claude-code; isClaudeCode(), które decyduje, czy czytać.claude/commands,.claude/skillsprojektu oraz~/.claudez pluginami (globalCommands).
- Agent spoza tej listy dostaje w menu
/tylko snippety, a te dziś są zawsze puste (snippets: []wmain.js). - Historia (
storage.loadHistory, do 500 wpisów, wspólna) zapisuje każdą wysłaną wiadomość z polemagentName=agentName(agent)(main.js,recordSent).
Cele
- 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). - Domyślne profile w kodzie dla
claude-code(z aliasemclaude) icodex. Zachowują dzisiejsze działanie: te same komendy, grupy, kolejność i deduplikację. - Plik użytkownika
~/.config/herdr-app/composer-agents.json(obokshared.json) dodaje nowe profile albo nadpisuje domyślne. - Komendy z historii: każde
/słowoz początku wiadomości wysłanej wcześniej do agenta o tym samymagentNametrafia do menu jako osobna grupa. - 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.jsIMAGE_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.jsonw folderze moda. - Wybrane: A (decyzja użytkownika). B oznacza dużo GUI do rzadkiej czynności. C nadpisuje
install.ps1przy 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 samymidco domyślny zastępuje go w całości. Bez łączenia list, żeby zachowanie było przewidywalne.match(wymagany, niepusta lista stringów): wartościagentName(), 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 grupyWbudowane.sources(opcjonalny): lista źródeł.scope:"project"(względemcwdpanelu, czytane przezexecjak dziśprojectItems) albo"home"(względem folderu domowego, czytane jak dziśglobalCommands). Odpowiadają grupomProjektiUż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; pomijauser-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 profilclaude-code. Inny profil może go użyć, ale nic poza tym nie robi.
- Domyślny profil
claude-codew 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órychagentNamejest równe bieżącemuagentName(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ńcuGROUPSwsuggest.js(przedTerminal, 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.mjsprzechodzą 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.
- wynik dla CC identyczny z wynikiem sprzed zmiany (lista kluczy, grup i
- GUI na tej maszynie: menu
/dla CC wygląda tak jak przed zmianą. Plik testowy z profilem dlacodex(albo z fałszywymmatchdla 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.