docs: plan for agent profiles in the / menu
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
1 parent
2631d86f0e
commit
89ac517cab
1 file changed
+184
@@ -0,0 +1,184 @@
|
||||
# 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 dla `agentName`.
|
||||
- `catalog.js` przestaje znać Claude Code: czyta źródła, które daje profil, a komendy z historii buduje osobną funkcją.
|
||||
- `main.js` w tle trzyma plik profili i cache źródeł `home` per `id` profilu, 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`; `exec` i `readText` wstrzyknięte). GPUI jest tylko w `main.js`.
|
||||
- Ścieżki do skryptów PowerShell trafiają wyłącznie przez `decode()` z `powershell.js` (Base64).
|
||||
- Menu `/` dla Claude Code (bez historii) daje **identyczną** listę jak przed zmianą: te same `key`, `group`, `insert`, `desc` i 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 (obecne `GLOBAL_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>` to `agentName`);
|
||||
- problem z plikiem: `` `composer-agents.json`: <powód> ``.
|
||||
|
||||
## Review Focus
|
||||
1. `agentName` w innej wielkości liter niż `match` (np. `Kiro-CLI`): profil ma pasować. Test w Task 1.
|
||||
2. Plik z BOM, CRLF albo komentarzem-śmieciem: BOM jest usuwany, zły JSON daje domyślne profile i powód. Test w Task 1.
|
||||
3. Wpis historii zaczynający się ścieżką (`/c/Users/x`), samym `/` albo `/ cos` nie jest komendą. Test w Task 2.
|
||||
4. Dwa panele z różnymi agentami: menu codex nie pokazuje komend `~/.claude`, bo cache jest per `id`. Test cache w Task 3 (czysta funkcja).
|
||||
5. Profil z pliku nadpisujący `claude-code` bez `claude-plugins` nie 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ś `BUILTINS` i `AGENT_ALIASES` do `profiles.js`, w `catalog.js` zostaw `export { 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: `desc` domyślnie `""`, `prefix` domyś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:
|
||||
1. project `.claude/commands` `*.md`;
|
||||
2. project `.claude/skills` `*/SKILL.md`;
|
||||
3. home `.claude/commands` `*.md`;
|
||||
4. home `.claude/skills` `*/SKILL.md`;
|
||||
5. `{scope:"home", kind:"claude-plugins"}`.
|
||||
- `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 `agents` albo `agents` nie jest tablicą: `problem: "brak listy agents"`.
|
||||
- Profil bez `id` (string) albo bez niepustego `match` (lista stringów) jest pomijany. Źródło z `path` bezwzględnym (`/x`, `C:/x`, `C:\x`, `\\x`) lub z segmentem `..`, nieznanym `scope` albo nieznanym `pattern` jest pomijane. Builtin bez `key` (string) jest pomijany.
|
||||
- Coś pominięto, a reszta działa: `problem: "pominięto <n> wpisów"`, gdzie `n` to liczba pominiętych profili, źródeł i builtinów razem.
|
||||
- `export function resolveProfile(userProfiles: Profile[], agent: string): Profile|null`: najpierw `userProfiles`, potem `DEFAULT_PROFILES`; pierwszy, którego `match` zawiera `agent` (bez rozróżniania wielkości liter, po `trim()`). `""` i `"default"` dają `null`, chyba że ktoś jawnie wpisał je w `match`.
|
||||
|
||||
- [ ] **Krok 1: testy (RED)** w `tests/profiles.test.mjs`:
|
||||
- `resolveProfile([], "claude")` i `resolveProfile([], "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: `builtins` to tylko `x`, a `sources` jest puste (brak `claude-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 z `prefix:"@"`, `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 `match` jest pominięty, drugi dobry zostaje.
|
||||
- `pattern:"**/*.md"` jest odrzucony.
|
||||
- `DEFAULT_PROFILES[0].builtins` ma te same klucze co `BUILTINS["claude-code"]`.
|
||||
- [ ] **Krok 2:** `npm test` daje FAIL (brak modułu).
|
||||
- [ ] **Krok 3:** zaimplementuj `profiles.js` i przenieś `BUILTINS` z re-eksportem w `catalog.js`.
|
||||
- [ ] **Krok 4:** `npm test` daje 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"`, w `GROUPS` po `GROUP_PLUGIN`, przed `GROUP_TERMINAL`.
|
||||
- `commands(cwd, exec, options)` z `options = {profile?: Profile|null, snippets?, global?: Item[], history?: Item[], onReadError?}`:
|
||||
- `profile` null lub brak: tylko `snippets` i `history`, bez `exec`;
|
||||
- w przeciwnym razie kolejność: builtins profilu, źródła `project` profilu (czytane przez `exec` w `cwd`), `global`, `snippets`, `history`;
|
||||
- deduplikacja po `key`: pierwszy wygrywa;
|
||||
- `insert` = `source.prefix + key + " "`.
|
||||
- Źródła `project` listuje **jedno** `exec` (sh, a PowerShell jako zapas, jak dziś `listProjectFiles`). Ścieżki i wzorce idą jako argumenty (sh) lub przez `decode()` (PS), nie są sklejane w skrypt. Nazwa skilla projektu: zawsze nazwa folderu, bez filtra `user-invocable` (jak dziś).
|
||||
- `globalCommands(home, exec, readText, options)` z `options = {sources: Source[], onReadError?}`:
|
||||
- czyta tylko źródła `scope:"home"` z `sources`; `kind:"claude-plugins"` daje dzisiejszą logikę pluginów (`~/.claude/settings.json` itd.);
|
||||
- źródło `home` `{path, pattern}` daje dzisiejszy spec `md` / `skills` dla `${home}/${path}`;
|
||||
- nazwy i filtr `user-invocable` jak dziś; `insert` z `prefix` źródła (plugin: `"/"`);
|
||||
- brak `sources` lub pusta lista: `[]` bez `exec`.
|
||||
- `export function historyCommands(history: HistoryEntry[], agent: string): Item[]`:
|
||||
- wpisy z `agentName` równym `agent` (bez wielkości liter, `trim`), od najnowszego `sentAt`;
|
||||
- pierwszy token `text.trimStart()` pasujący do `/^\/[A-Za-z0-9][\w:.-]*$/`;
|
||||
- `key` bez `/`, `desc: ""`, `group: GROUP_HISTORY`, `insert: "/"+key+" "`;
|
||||
- bez duplikatów.
|
||||
- `export function unknownAgentMessage(agent: string): string` oraz `export function profileProblemMessage(problem: string): string`: teksty z Ograniczeń globalnych.
|
||||
- Usuń `isClaudeCode` i `LIST_SH`/`LIST_PS` na sztywno. Test `isClaudeCode` zastępują testy `resolveProfile` z 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` (z `name: 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_CC` w teście. Commit tylko testu: `test: pin the / menu of Claude Code before profiles`. `npm test` daje PASS.
|
||||
- [ ] **Krok 2: przepisz ten test na nowe API** (`profile: resolveProfile([], "claude-code")`, `globalCommands(..., {sources: profile.sources})`) z tym samym `EXPECTED_CC`. Dodaj testy (RED):
|
||||
- `commands` z `profile: null`, `history: [h]` daje `[h]` i `exec` nie zostaje wywołane;
|
||||
- profil `kiro` ze źródłem project `.kiro/prompts` `*.md` `prefix:"@"` daje `{key:"review", insert:"@review ", group:"Projekt"}`;
|
||||
- `globalCommands` z `sources: []` daje `[]`, bez `exec`;
|
||||
- `globalCommands` ze źródłem home `.kiro/prompts` daje 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"]` (gdy `brainstorming` jest nowszy), w grupie `Z historii`;
|
||||
- `commands` z builtin `clear` i historią `clear` daje jedno `clear` z grupy `Wbudowane`;
|
||||
- `GROUPS` zawiera `"Z historii"` zaraz po `"Pluginy"`;
|
||||
- istniejące testy `globalCommands` dostają mechanicznie `{sources: DEFAULT_PROFILES[0].sources}`.
|
||||
- [ ] **Krok 3:** `npm test` daje FAIL na nowych testach.
|
||||
- [ ] **Krok 4:** zaimplementuj.
|
||||
- [ ] **Krok 5:** `npm test` daje PASS, z `EXPECTED_CC` bez 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 w `init` ~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)]`, gdy `problem`;
|
||||
- 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()` (klucz `profile.id`, wartość `Item[]`) i `this.globalLoadedAt = new Map()`, zamiast dzisiejszych pojedynczych pól;
|
||||
- flaga `this.globalLoading` jak dziś.
|
||||
- `refreshGlobal(cx)`:
|
||||
1. gdy minęło 60 s od ostatniego odczytu pliku: `readTextFile([appHome(), PROFILES_FILE].join("\\"))`, potem `parseProfiles` i ustawienie trzech pól oraz `profilesLoaded = true`;
|
||||
2. `profile = resolveProfile(this.userProfiles, agentName(target))`; gdy profil ma źródła `home` i cache dla `profile.id` jest pusty lub starszy niż 60 s, `globalCommands(home(), exec, readTextFile, {sources: profile.sources, onReadError})` zapisuje wynik pod `profile.id`;
|
||||
3. po zakończeniu, gdy menu `/` jest otwarte, przeładuj menu tak jak dziś.
|
||||
|
||||
W `updateSuggestions` wołaj `refreshGlobal` dla **każdego** agenta przy `/` (usuń warunek `isClaudeCode`). `checking()` blokuje jak dziś.
|
||||
- `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`: `notes` jako szare (`t.dim`, `text_size(11.5)`) wiersze **pod** pozycjami, w tej samej przewijanej liście. Nie da się ich wybrać, a indeksy pozycji i `scroll_to_item` się nie zmieniają. Komunikat „Żadna komenda nie pasuje” nie pojawia się, gdy pozycji nie ma, a są `notes` z 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 `id` w 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:false` daje `[]`;
|
||||
- profil plus `problem:"nieczytelny JSON"` daje `["`composer-agents.json`: nieczytelny JSON"]`;
|
||||
- `profile:null`, `problem` i `profilesLoaded:true` dają 2 wiersze, najpierw nieznany agent.
|
||||
- [ ] **Krok 2:** `npm test` daje FAIL.
|
||||
- [ ] **Krok 3:** zaimplementuj `menuNotes`, zmiany w `main.js` i README.
|
||||
- [ ] **Krok 4:** `npm test` daje PASS. `grep -n isClaudeCode herdr/herdr-composer/mods/herdr-composer/*.js` nic 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`, potem `herdr-app status` musi dać `"errors": []`.
|
||||
- GUI: menu `/` w CC wygląda tak jak przed zmianą.
|
||||
- Plik testowy `composer-agents.json` z profilem `codex` ze źródłem home `.claude/commands` daje `handoff` w menu codex w ciągu 60 s.
|
||||
- Uszkodzony plik daje wiersz z powodem. Po teście usuń plik.
|
||||
Reference in new issue
Block a user