15 KiB
Profile agentów dla menu / — plan implementacji
Dla wykonawcy (Ovis Fast): zadania wykonuj po kolei, każde osobnym commitem. Kroki mają checkboxy (
- [ ]).
Cel: menu / podpowiada komendy dowolnego agenta. Wiedza o agencie pochodzi z profilu: domyślnego w kodzie albo z pliku composer-agents.json użytkownika. Do tego dochodzą komendy wysłane wcześniej do tego agenta, wzięte z historii.
Architektura:
- Nowy czysty moduł
profiles.js: domyślne profile, parsowanie i walidacja pliku, wybór profilu dlaagentName. catalog.jsprzestaje znać Claude Code: czyta źródła, które daje profil, a komendy z historii buduje osobną funkcją.main.jsw tle trzyma plik profili i cache źródełhomeperidprofilu, a pod pozycjami menu pokazuje wiersze informacyjne.
Stack: JS (ESM), GPUI z gpui-kit, testy node --test (npm test).
Spec: docs/superpowers/specs/2026-11-20-agent-profiles-design.md. Przeczytaj cały plik przed startem.
Ograniczenia globalne
- Nie zmieniamy Herdr ani jego plików. Pracujemy tylko na gałęzi
feature/composer-dock. Bez push. - Logika testowalna siedzi w czystych modułach (
profiles.js,catalog.js;execireadTextwstrzyknięte). GPUI jest tylko wmain.js. - Ścieżki do skryptów PowerShell trafiają wyłącznie przez
decode()zpowershell.js(Base64). - Menu
/dla Claude Code (bez historii) daje identyczną listę jak przed zmianą: te samekey,group,insert,desci kolejność. - Plik:
[appHome(), "composer-agents.json"].join("\\"). Brak pliku jest normalny i nie jest błędem. - TTL odświeżania pliku i źródeł
home: 60 s (obecneGLOBAL_TTL_MS). - Teksty dla użytkownika dosłownie:
GROUP_HISTORY = "Z historii";- nieznany agent:
Nieznany agent `<nazwa>` – dodaj profil w ~/.config/herdr-app/composer-agents.json(gdzie<nazwa>toagentName); - problem z plikiem:
`composer-agents.json`: <powód>.
Review Focus
agentNamew innej wielkości liter niżmatch(np.Kiro-CLI): profil ma pasować. Test w Task 1.- Plik z BOM, CRLF albo komentarzem-śmieciem: BOM jest usuwany, zły JSON daje domyślne profile i powód. Test w Task 1.
- Wpis historii zaczynający się ścieżką (
/c/Users/x), samym/albo/ cosnie jest komendą. Test w Task 2. - Dwa panele z różnymi agentami: menu codex nie pokazuje komend
~/.claude, bo cache jest perid. Test cache w Task 3 (czysta funkcja). - Profil z pliku nadpisujący
claude-codebezclaude-pluginsnie pokazuje pluginów, a ścieżka..lub bezwzględna jest odrzucana. Test w Task 1.
Task 1: profiles.js, czyli domyślne profile, parsowanie i wybór
Pliki:
- Utwórz:
herdr/herdr-composer/mods/herdr-composer/profiles.js - Zmień:
herdr/herdr-composer/mods/herdr-composer/catalog.js(przenieśBUILTINSiAGENT_ALIASESdoprofiles.js, wcatalog.jszostawexport { BUILTINS } from "./profiles.js") - Test:
tests/profiles.test.mjs
Interfejsy (produkuje):
-
Typy (JSDoc):
Source = {scope:"project"|"home", path:string, pattern:"*.md"|"*/SKILL.md", prefix:string}, albo{scope:"home", kind:"claude-plugins"};Profile = {id:string, match:string[], builtins:{key:string, desc:string}[], sources:Source[]}(wszystko znormalizowane:descdomyślnie"",prefixdomyślnie"/").
-
export const PROFILES_FILE = "composer-agents.json" -
export const BUILTINS: bez zmian treści. -
export const DEFAULT_PROFILES: Profile[]:claude-code:match ["claude-code","claude"], builtins =BUILTINS["claude-code"], sources w tej kolejności:- project
.claude/commands*.md; - project
.claude/skills*/SKILL.md; - home
.claude/commands*.md; - home
.claude/skills*/SKILL.md; {scope:"home", kind:"claude-plugins"}.
- project
codex:match ["codex"], builtins =BUILTINS.codex,sources [].
-
export function parseProfiles(text: string|null|undefined): {profiles: Profile[], problem: string|null}null/undefined(brak pliku) daje{profiles: [], problem: null}.- Usuwa BOM. Zły JSON daje
{profiles: [], problem: "nieczytelny JSON"}. - Brak
agentsalboagentsnie jest tablicą:problem: "brak listy agents". - Profil bez
id(string) albo bez niepustegomatch(lista stringów) jest pomijany. Źródło zpathbezwzględnym (/x,C:/x,C:\x,\\x) lub z segmentem.., nieznanymscopealbo nieznanympatternjest pomijane. Builtin bezkey(string) jest pomijany. - Coś pominięto, a reszta działa:
problem: "pominięto <n> wpisów", gdziento liczba pominiętych profili, źródeł i builtinów razem.
-
export function resolveProfile(userProfiles: Profile[], agent: string): Profile|null: najpierwuserProfiles, potemDEFAULT_PROFILES; pierwszy, któregomatchzawieraagent(bez rozróżniania wielkości liter, potrim()).""i"default"dająnull, chyba że ktoś jawnie wpisał je wmatch. -
Krok 1: testy (RED) w
tests/profiles.test.mjs:resolveProfile([], "claude")iresolveProfile([], "Claude-Code")→id === "claude-code";resolveProfile([], "codex").id === "codex";resolveProfile([], "kiro-cli") === null;resolveProfile([], "default") === null.- Profil z pliku
{id:"claude-code", match:["claude-code"], builtins:[{key:"x"}]}wygrywa z domyślnym:builtinsto tylkox, asourcesjest puste (brakclaude-plugins). parseProfiles(null)→{profiles:[], problem:null}.parseProfiles("\uFEFF{\"agents\":[{\"id\":\"kiro\",\"match\":[\"kiro-cli\"],\"sources\":[{\"scope\":\"home\",\"path\":\".kiro/prompts\",\"pattern\":\"*.md\",\"prefix\":\"@\"}]}]}\r\n")→ jeden profil, źródło zprefix:"@",problem:null.parseProfiles("{nope")→problem:"nieczytelny JSON",profiles:[].parseProfiles('{"agents":{}}')→problem:"brak listy agents".- Profil z dwoma źródłami
{path:"../x"}i{path:"C:/x"}oraz jednym dobrym → zostaje 1 źródło,problem:"pominięto 2 wpisów". - Profil bez
matchjest pominięty, drugi dobry zostaje. pattern:"**/*.md"jest odrzucony.DEFAULT_PROFILES[0].builtinsma te same klucze coBUILTINS["claude-code"].
-
Krok 2:
npm testdaje FAIL (brak modułu). -
Krok 3: zaimplementuj
profiles.jsi przenieśBUILTINSz re-eksportem wcatalog.js. -
Krok 4:
npm testdaje PASS, łącznie z dzisiejszymi 190 testami. -
Krok 5: commit
feat: agent profiles describe each agent's commands
Task 2: catalog.js czyta źródła profilu i komendy z historii
Pliki:
- Zmień:
herdr/herdr-composer/mods/herdr-composer/catalog.js,herdr/herdr-composer/mods/herdr-composer/suggest.js - Test:
tests/catalog.test.mjs
Interfejsy:
-
Konsumuje z Task 1:
Profile,Source,DEFAULT_PROFILES,resolveProfile. -
Produkuje:
suggest.js:export const GROUP_HISTORY = "Z historii", wGROUPSpoGROUP_PLUGIN, przedGROUP_TERMINAL.commands(cwd, exec, options)zoptions = {profile?: Profile|null, snippets?, global?: Item[], history?: Item[], onReadError?}:profilenull lub brak: tylkosnippetsihistory, bezexec;- w przeciwnym razie kolejność: builtins profilu, źródła
projectprofilu (czytane przezexecwcwd),global,snippets,history; - deduplikacja po
key: pierwszy wygrywa; insert=source.prefix + key + " ".- Źródła
projectlistuje jednoexec(sh, a PowerShell jako zapas, jak dziślistProjectFiles). Ścieżki i wzorce idą jako argumenty (sh) lub przezdecode()(PS), nie są sklejane w skrypt. Nazwa skilla projektu: zawsze nazwa folderu, bez filtrauser-invocable(jak dziś).
globalCommands(home, exec, readText, options)zoptions = {sources: Source[], onReadError?}:- czyta tylko źródła
scope:"home"zsources;kind:"claude-plugins"daje dzisiejszą logikę pluginów (~/.claude/settings.jsonitd.); - źródło
home{path, pattern}daje dzisiejszy specmd/skillsdla${home}/${path}; - nazwy i filtr
user-invocablejak dziś;insertzprefixźródła (plugin:"/"); - brak
sourceslub pusta lista:[]bezexec.
- czyta tylko źródła
export function historyCommands(history: HistoryEntry[], agent: string): Item[]:- wpisy z
agentNamerównymagent(bez wielkości liter,trim), od najnowszegosentAt; - pierwszy token
text.trimStart()pasujący do/^\/[A-Za-z0-9][\w:.-]*$/; keybez/,desc: "",group: GROUP_HISTORY,insert: "/"+key+" ";- bez duplikatów.
- wpisy z
export function unknownAgentMessage(agent: string): stringorazexport function profileProblemMessage(problem: string): string: teksty z Ograniczeń globalnych.- Usuń
isClaudeCodeiLIST_SH/LIST_PSna sztywno. TestisClaudeCodezastępują testyresolveProfilez Task 1, więc usuwasz go.
-
Krok 1: test „CC bez zmian” PRZED zmianą kodu. Na obecnym kodzie, na fałszywej maszynie z testów (
machine(...)) z plikami:- projekt
.claude/commands/a.md,.claude/skills/s/SKILL.md(zname: inna); - home
~/.claude/commands/handoff.md; - jeden plugin.
Wywołaj
commands(cwd, exec, {agent:"claude-code", global: await globalCommands(...)})i wpisz wynik (lista{key, group, insert, desc}) jako literałEXPECTED_CCw teście. Commit tylko testu:test: pin the / menu of Claude Code before profiles.npm testdaje PASS. - projekt
-
Krok 2: przepisz ten test na nowe API (
profile: resolveProfile([], "claude-code"),globalCommands(..., {sources: profile.sources})) z tym samymEXPECTED_CC. Dodaj testy (RED):commandszprofile: null,history: [h]daje[h]iexecnie zostaje wywołane;- profil
kiroze źródłem project.kiro/prompts*.mdprefix:"@"daje{key:"review", insert:"@review ", group:"Projekt"}; globalCommandszsources: []daje[], bezexec;globalCommandsze źródłem home.kiro/promptsdaje grupęUżytkownik;historyCommands: wpisy"/clear"," /superpowers:brainstorming x","/c/Users/x","/ cos","/","hej /clear"oraz wpis innego agenta dają dokładnie["superpowers:brainstorming","clear"](gdybrainstormingjest nowszy), w grupieZ historii;commandsz builtincleari historiącleardaje jednoclearz grupyWbudowane;GROUPSzawiera"Z historii"zaraz po"Pluginy";- istniejące testy
globalCommandsdostają mechanicznie{sources: DEFAULT_PROFILES[0].sources}.
-
Krok 3:
npm testdaje FAIL na nowych testach. -
Krok 4: zaimplementuj.
-
Krok 5:
npm testdaje PASS, zEXPECTED_CCbez zmian. -
Krok 6: commit
feat: the / menu reads the sources of the agent's profile and its history
Task 3: main.js, czyli plik profili, cache per profil, wiersze informacyjne i README
Pliki:
- Zmień:
herdr/herdr-composer/mods/herdr-composer/main.js(updateSuggestions~2213,refreshGlobal~2228,loadSuggestions~2275,renderMenu~2824, stan winit~199),herdr/herdr-composer/mods/herdr-composer/catalog.js(jedna czysta funkcja niżej), README moda (sekcja „Inni agenci”) - Test:
tests/catalog.test.mjs
Interfejsy:
-
Konsumuje:
parseProfiles,resolveProfile,PROFILES_FILE(Task 1);commands,globalCommands,historyCommands,unknownAgentMessage,profileProblemMessage(Task 2). -
Produkuje w
catalog.js:export function menuNotes({profile, agent, profilesLoaded, problem}): string[]:[profileProblemMessage(problem)], gdyproblem;- plus
unknownAgentMessage(agent), gdy!profile && profilesLoaded; - kolejność: najpierw nieznany agent, potem problem.
-
Stan w
main.js:this.userProfiles = [],this.profileProblem = null,this.profilesLoaded = false;this.globalCommands = new Map()(kluczprofile.id, wartośćItem[]) ithis.globalLoadedAt = new Map(), zamiast dzisiejszych pojedynczych pól;- flaga
this.globalLoadingjak dziś.
-
refreshGlobal(cx):- gdy minęło 60 s od ostatniego odczytu pliku:
readTextFile([appHome(), PROFILES_FILE].join("\\")), potemparseProfilesi ustawienie trzech pól orazprofilesLoaded = true; profile = resolveProfile(this.userProfiles, agentName(target)); gdy profil ma źródłahomei cache dlaprofile.idjest pusty lub starszy niż 60 s,globalCommands(home(), exec, readTextFile, {sources: profile.sources, onReadError})zapisuje wynik podprofile.id;- po zakończeniu, gdy menu
/jest otwarte, przeładuj menu tak jak dziś.
W
updateSuggestionswołajrefreshGlobaldla każdego agenta przy/(usuń warunekisClaudeCode).checking()blokuje jak dziś. - gdy minęło 60 s od ostatniego odczytu pliku:
-
loadSuggestions, gałąź/:profile = resolveProfile(this.userProfiles, agentName(agent));commands(cwd, exec, {profile, snippets: [], global: this.globalCommands.get(profile?.id) ?? [], history: catalog.historyCommands(storage.loadHistory(this.store), agentName(agent)), onReadError});this.menu.notes = catalog.menuNotes({...}).
-
renderMenu:notesjako szare (t.dim,text_size(11.5)) wiersze pod pozycjami, w tej samej przewijanej liście. Nie da się ich wybrać, a indeksy pozycji iscroll_to_itemsię nie zmieniają. Komunikat „Żadna komenda nie pasuje” nie pojawia się, gdy pozycji nie ma, a sąnotesz nieznanym agentem. -
README: sekcja „Inni agenci”:
- klucz bierzesz z wiersza „Nieznany agent …”;
- ścieżka pliku i format (pola z tabeli w specu);
- że plik nadpisuje profil o tym samym
idw całości; - przykład dla kiro z nagłówkiem „przykład niesprawdzony”.
-
Krok 1: testy (RED)
menuNotes:{profile:null, agent:"kiro-cli", profilesLoaded:true}daje 1 wiersz zawierający`kiro-cli`;- to samo przy
profilesLoaded:falsedaje[]; - profil plus
problem:"nieczytelny JSON"daje["composer-agents.json: nieczytelny JSON"]; profile:null,problemiprofilesLoaded:truedają 2 wiersze, najpierw nieznany agent.
-
Krok 2:
npm testdaje FAIL. -
Krok 3: zaimplementuj
menuNotes, zmiany wmain.jsi README. -
Krok 4:
npm testdaje PASS.grep -n isClaudeCode herdr/herdr-composer/mods/herdr-composer/*.jsnic nie znajduje. -
Krok 5: commit
feat: the composer reads agent profiles from composer-agents.json
Po wykonaniu (Ovis Opus, nie wykonawca)
- Instalacja:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1, potemherdr-app statusmusi dać"errors": []. - GUI: menu
/w CC wygląda tak jak przed zmianą. - Plik testowy
composer-agents.jsonz profilemcodexze źródłem home.claude/commandsdajehandoffw menu codex w ciągu 60 s. - Uszkodzony plik daje wiersz z powodem. Po teście usuń plik.