134 lines
6.4 KiB
Markdown
134 lines
6.4 KiB
Markdown
# 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`.
|