Publica agent-switcher: extensión de pi para cambio de agentes estilo opencode
This commit is contained in:
sargatxet committed
commit
e4b86fc6eb
7 files changed
+1156
No files matched your search
@@ -0,0 +1,133 @@
|
||||
# Agent Switcher
|
||||
|
||||
Cambio de agentes estilo **opencode** para pi: alterna entre agentes (p. ej.
|
||||
`planner` y `build`) y cada agente aplica **su propio modelo**, nivel de
|
||||
thinking, allowlist de herramientas, rol de solo lectura y system prompt.
|
||||
|
||||
## Instalación
|
||||
|
||||
- Instalación permanente:
|
||||
`pi install https://git.sargatxet.cloud/sargatxet/pi-agent-switcher`
|
||||
- Una sola sesión:
|
||||
`pi -e https://git.sargatxet.cloud/sargatxet/pi-agent-switcher`
|
||||
- Manual (fallback):
|
||||
`git clone https://git.sargatxet.cloud/sargatxet/pi-agent-switcher.git ~/.pi/agent/extensions/agent-switcher`
|
||||
o probar sin instalar:
|
||||
`pi --extension <ruta-del-repo>/extensions/agent-switcher/index.ts`
|
||||
|
||||
## Comandos
|
||||
|
||||
| Comando / atajo | Acción |
|
||||
|---|---|
|
||||
| `/agent` | Selector de agentes (lista si no hay TUI) |
|
||||
| `/agent <nombre>` | Cambiar al agente `<nombre>` (también alias) |
|
||||
| `/agents` | Listar agentes con su estado y modelo |
|
||||
| `/agent model` | Modelo efectivo del agente activo |
|
||||
| `/agent model <ref>` | Fijar el modelo del agente activo **para esta sesión** |
|
||||
| `/agent model reset` | Quitar el override y volver al `model:` del archivo |
|
||||
| `F5` / `F6` | Cambiar al agente planner/build (configurable con `shortcut:`) |
|
||||
| `pi --agent planner` | Arrancar con un agente concreto |
|
||||
|
||||
El agente activo se confirma con el aviso `Agente activo: … · modelo …` al
|
||||
cambiar, y con `/agent list`. La línea de estado del footer se eliminó por
|
||||
resultar confusa.
|
||||
|
||||
## Definir agentes
|
||||
|
||||
Cada agente es un Markdown con frontmatter en:
|
||||
|
||||
- `~/.pi/agent/agents/*.md` — agentes de usuario
|
||||
- `<proyecto>/.pi/agents/*.md` — agentes de proyecto (sobrescriben al mismo nombre)
|
||||
|
||||
Ejemplo (`~/.pi/agent/agents/build.md`):
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: build
|
||||
description: Implementation agent running on the fast model
|
||||
aliases: constructor, implement
|
||||
advertise: true
|
||||
model: provider/model-id
|
||||
thinking: medium
|
||||
systemPromptMode: append
|
||||
inheritProjectContext: true
|
||||
inheritSkills: true
|
||||
---
|
||||
|
||||
You are `build`: the implementation agent. ...
|
||||
```
|
||||
|
||||
### Claves del frontmatter
|
||||
|
||||
| Clave | Defecto | Significado |
|
||||
|---|---|---|
|
||||
| `name` | nombre del archivo | Identificador único para `/agent <nombre>` |
|
||||
| `description` | — | Texto mostrado en el selector |
|
||||
| `aliases` | — | Nombres alternativos, separados por comas |
|
||||
| `advertise` | `true` | `false` = oculto en el selector y en el ciclo |
|
||||
| `shortcut` | — | Atajos directos al agente, separados por comas (p. ej. `f5`). Conflicto con atajos nativos: pi lo descarta con aviso |
|
||||
| `model` | — | `provider/id` o un `id` único. **Sin valor = conserva el modelo actual** |
|
||||
| `thinking` | — | `off\|minimal\|low\|medium\|high\|xhigh\|max` |
|
||||
| `systemPromptMode` | `append` | `replace` = el cuerpo sustituye el prefijo del prompt; `append` = se añade |
|
||||
| `inheritProjectContext` | `true` | `false` = el agente no ve `AGENTS.md`/archivos de contexto |
|
||||
| `inheritSkills` | `true` | `false` = el agente no ve las skills |
|
||||
| `tools` | — | Allowlist de herramientas activas (separadas por comas o espacios) |
|
||||
| `acceptanceRole` | — | `read-only` = bloquea `edit`/`write` y restringe `bash` a comandos de solo lectura |
|
||||
| `defaultContext` | — | Aceptado e ignorado (fresco no aplica al cambio inline) |
|
||||
|
||||
El cuerpo del archivo (tras el frontmatter) es el system prompt del agente.
|
||||
|
||||
## Semántica (equivalente a opencode)
|
||||
|
||||
- **El agente activo gobierna**: su `model` y `thinking` se aplican al
|
||||
activarse y se reafirman en cada `before_agent_start`; su `tools` y su
|
||||
prompt también se aplican cada run (todo idempotente).
|
||||
- **Agente sin `model`** = no toca el modelo: conserva el de la sesión
|
||||
(útil para un `build` que simplemente hereda el modelo por defecto de pi).
|
||||
- **Overrides de sesión**: solo `/agent model <ref>` crea un override para el
|
||||
agente activo y se restaura al volver a él. Los cambios con `/model` o
|
||||
`Ctrl+P` aplican de inmediato, pero **el modelo del agente se reafirma en
|
||||
cada prompt** (los eventos de modelo ya no se autograban: así los cambios
|
||||
de otras extensiones no pueden intercambiar los modelos de los agentes).
|
||||
El override lleva memoria del valor del archivo que tenía al crearse:
|
||||
**si editas `model:` en el `.md`, el archivo manda** y el override se
|
||||
descarta. `/agent model reset` lo borra a mano; `/agent list`
|
||||
marca los agentes con modelo «(sesión)». Para fijarlo de forma permanente,
|
||||
edita el `model:` del archivo del agente.
|
||||
- **Persistencia**: el agente activo y los overrides se guardan en la
|
||||
sesión y se restauran al reanudarla.
|
||||
- **Solo lectura**: además de desactivar las herramientas de escritura,
|
||||
hay una segunda barrera en `tool_call` que bloquea `edit`/`write` y
|
||||
cualquier comando bash que no esté en la lista de solo lectura
|
||||
(`policy.ts`).
|
||||
|
||||
## Notas
|
||||
|
||||
- Los agentes se recargan en cada inicio de sesión; tras editar un `.md`
|
||||
durante la sesión usa `/reload` (también recarga los atajos nuevos).
|
||||
|
||||
## Los atajos de teclado no funcionan
|
||||
|
||||
1. **¿La sesión cargó la extensión?** Ejecuta `/hotkeys`: debe aparecer
|
||||
`Cambiar al agente …`. Si no aparece, ejecuta `/reload` (o reinicia pi):
|
||||
las sesiones abiertas antes de instalar el plugin no lo cargan solas.
|
||||
2. **¿El terminal entrega la combinación?** La configuración por defecto usa
|
||||
**teclas de función** (`f5`, `f6`) precisamente porque llegan en todos los
|
||||
terminales. Si cambias a combinaciones como `ctrl+alt+x`, estas solo llegan
|
||||
a pi si el terminal usa el protocolo kitty/CSI-u (kitty, Ghostty, WezTerm
|
||||
con `enable_kitty_keyboard`, VS Code ≥ 1.109.5) o si envía `ESC + carácter
|
||||
de control`; fallan en terminales clásicas, dentro de tmux y con teclado
|
||||
español donde **AltGr = Ctrl+Alt**.
|
||||
3. En tmux, habilita `set -s extended-keys on` para que lleguen las teclas
|
||||
modificadas (ver la doc de pi sobre tmux).
|
||||
4. Cambia las teclas editando `shortcut:` en el `.md` del agente y
|
||||
ejecutando `/reload`. Cualquier combinación que aparezca en `/hotkeys`
|
||||
es válida.
|
||||
- Si otra extensión también llama a `setModel` en `before_agent_start`
|
||||
(p. ej. un cambio de modelo automático por fases), las dos competirán
|
||||
en cada run: mantén solo una estrategia activa.
|
||||
- Con **pi-subagents** instalado, `subagents_enable` se fuerza siempre en
|
||||
las herramientas activas. En agentes con `tools:`/`read-only` esa
|
||||
llamada se bloquea en `tool_call` (delegar permitiría escribir ficheros);
|
||||
el resto de su comportamiento no se ve afectado.
|
||||
- Para probar sin instalar nada: `pi --extension <ruta-del-repo>/extensions/agent-switcher/index.ts`.
|
||||
Reference in new issue
Block a user