Gestión de sesiones de Pi Agent
El sistema de gestión de sesiones de Pi Agent es una de sus características más potentes.
Este capítulo detalla el guardado, la restauración, la ramificación y la exportación de sesiones.
Mecanismo de almacenamiento de sesiones
Cada conversación se guarda automáticamente como un archivo de sesión, almacenado en formato JSONL en~/.pi/agent/sessions/, clasificados por ruta de proyecto.
El nombre del directorio se obtiene convirtiendo la ruta absoluta del proyecto: las barras se reemplazan por guiones y se envuelve con -- al principio y al final.
El nombre del archivo se forma concatenando la marca de tiempo de creación y el UUID de la sesión.
Cada sesión se organiza internamente como una estructura de árbol, lo que significa que puedes ramificarte en cualquier nodo histórico sin perder el contenido de conversaciones anteriores.
~/.pi/agent/sessions/
└── --Users-ejemplo-projects-ejemplo-demo--/ # 目录名为项目路径，斜杠已替换为连字符
├── 2026-08-31T02-40-11-000Z_019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a.jsonl # 时间戳_UUID.jsonl
├── 2026-08-31T04-12-38-000Z_2c8f71ba-4a19-4e63-9d02-7f5a6b8c9d0e.jsonl
└── 2026-08-31T08-55-02-000Z_5e3d92f4-8b26-47ac-a174-9c0d1e2f3a4b.jsonl
Estructura interna del archivo de sesión
La primera línea del archivo de sesión es un metadato fijo que registra la versión del formato de sesión, el ID de sesión, la hora de creación y el directorio de trabajo.
Estos metadatos no tienen campos id ni parentId y no participan en el árbol de conversación.
A partir de la segunda línea, cada línea es una entrada con campos id y parentId, que juntos forman la estructura de árbol.
Los tipos de entrada incluyen message, compaction, branch_summary, label, custom, etc.
Las sesiones creadas con /fork o /clone tienen además un campo parentSession en los metadatos de la primera línea, que apunta al archivo de sesión original.
{"type":"session","version":3,"id":"019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a","timestamp":"2026-08-31T02:40:11.000Z","cwd":"/Users/ejemplo/projects/ejemplo-demo"}
{"type":"message","id":"m1","parentId":null,"message":{"role":"user","content":[{"type":"text","text":"帮我实现登录功能"}]}}
{"type":"message","id":"m2","parentId":"m1","message":{"role":"assistant","content":[{"type":"text","text":"好的，我用 JWT 来实现"}]}}
El directorio de sesiones también se puede personalizar; la prioridad de mayor a menor es: el parámetro --session-dir, la variable de entornoPI_CODING_AGENT_SESSION_DIRy la opción en settings.jsonsessionDir。
Opciones de sesión al inicio
Controla el comportamiento de la sesión al inicio mediante parámetros de línea de comandos:
$ pi -c Resumed session abc123-def456 (42 messages, model claude-sonnet-4-5) $ pi -r ┌ 选择要恢复的会话： │ > abc123 快速审查 3 分钟前 │ def456 重构认证模块 2 小时前 └ $ pi --session ~/.pi/agent/sessions/--Users-ejemplo-projects-ejemplo-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl Resumed session 019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f $ pi --session abc123 Resumed session abc123-def456 $ pi --fork abc123 Forked to session 9f2e7a01-5c48 $ pi --name "重构认证模块" Session renamed: 重构认证模块 $ pi --no-session Temporary session (will not be saved)
Comandos de gestión de sesiones
Una vez en el modo interactivo, los siguientes comandos cubren la gestión diaria de sesiones.
| Comando | Función | Caso de uso |
|---|---|---|
| /resume | Explorar y reanudar sesiones históricas | Cambiar a una conversación anterior y continuar trabajando |
| /new | Iniciar nueva sesión | Iniciar una tarea completamente nueva sin relación con el historial |
| /name nombre | Establecer el nombre de la sesión | Poner un nombre fácil de recordar a la sesión |
| /session | Ver información de la sesión | Ver la ruta del archivo, el número de mensajes, el uso de tokens y el costo |
| /tree | Abrir el navegador de árbol de sesiones | Saltar a cualquier nodo del árbol de conversación |
| /fork | Bifurcar sesión | Crear una nueva sesión a partir de un mensaje de usuario anterior |
| /clone | Clonar sesión | Copiar la rama activa actual a un nuevo archivo de sesión |
| /export archivo | Exportar como archivo HTML o JSONL | Archivo local o compartir sin conexión |
| /share | Compartir sesión | Subir como GitHub Gist y generar un enlace compartible |
Selector de sesiones /resume
Al escribir /resume o iniciar con pi -r, se abre el selector de sesiones del proyecto actual.
En la lista, escribe caracteres directamente para filtrar sesiones; las demás teclas de operación son las siguientes:
| Operación | Tecla | Descripción |
|---|---|---|
| Filtrar sesiones | Escribir caracteres directamente | Filtra la lista de sesiones del proyecto actual en tiempo real según lo escrito |
| Alternar visualización de ruta | Ctrl+P | Mostrar u ocultar la ruta del directorio de trabajo de la sesión |
| Alternar orden | Ctrl+S | Alternar entre modos de ordenamiento |
| Mostrar solo sesiones con nombre | Ctrl+N | Filtrar sesiones que tienen un nombre configurado |
| Renombrar | Ctrl+R | Modificar el nombre de la sesión seleccionada |
| Eliminar | Ctrl+D | Se ejecuta tras la confirmación; si el sistema tiene el comando trash, se mueve a la papelera en lugar de eliminarse directamente. |
Árbol de sesiones (/tree)
Esta es la característica más distintiva de Pi Agent: las sesiones se almacenan en una estructura de árbol y puedes ramificarte en cualquier nodo histórico.
Estructura del árbol
A continuación se muestra una estructura de árbol de sesión típica:
├─ user: "帮我实现一个登录功能..." │ └─ assistant: "好的，我来实现..." │ ├─ user: "用 JWT 方案..." │ │ └─ assistant: "使用 JWT 实现..." │ │ └─ user: "测试通过了" ← 当前活跃分支 │ └─ user: "还是用 Session 方案..." │ └─ assistant: "使用 Session 实现..."
En este ejemplo, partiendo del mismo punto inicial, exploras dos enfoques: JWT y Session. Las conversaciones de cada enfoque se conservan por completo.
Operaciones del navegador de árbol
Después de abrir /tree, usa las siguientes teclas para moverte y seleccionar en el árbol.
| Operación | Atajo de teclado | Descripción |
|---|---|---|
| Moverse arriba/abajo | ↑/↓ | Mueve el cursor entre las entradas visibles |
| Cambiar de página | ←/→ | Página arriba/abajo |
| Plegar/desplegar | Ctrl+←/Ctrl+→ o Alt+←/Alt+→ | Plegar/desplegar segmentos de rama o saltar |
| Establecer etiqueta | Shift+L | Establecer una etiqueta para el nodo seleccionado |
| Alternar marca de tiempo | Shift+T | Mostrar/ocultar la marca de tiempo de las etiquetas de entrada (las etiquetas se establecen con Shift+L) |
| Confirmar selección | Enter | Seleccionar el nodo actual |
| Cancelar | Escape / Ctrl+C | Salir del navegador de árbol |
| Alternar modo de filtrado | Ctrl+O | Cicla entre los modos de filtrado (solo tiene efecto dentro del navegador /tree) |
Modos de filtrado
El modo de filtrado determina qué entradas se muestran en el navegador de árbol; se alterna con Ctrl+O.
| Modo | Contenido mostrado |
|---|---|
| default | Vista predeterminada, pliega los detalles de las llamadas a herramientas |
| no-tools | Oculta todas las llamadas a herramientas y sus resultados |
| user-only | Mostrar solo mensajes de usuario |
| labeled-only | Mostrar solo entradas etiquetadas |
| all | Mostrar todas las entradas |
Seleccionar un mensaje de usuario rellena el área de edición con su texto, lo que te permite volver a editarlo y enviarlo para crear una nueva rama.
Seleccionar una respuesta de IA o una llamada a herramienta salta directamente a esa posición, permitiéndote continuar la conversación desde allí.
Diferencias entre /tree, /fork y /clone
Los tres permiten volver a una posición histórica; la diferencia está en si se genera un nuevo archivo de sesión y en el rango de conversación que se puede ver.
| Comando | Salida | Vista | Uso típico | Resumen de ramas | Resumen en una frase |
|---|---|---|---|---|---|
| /tree | El mismo archivo de sesión | Árbol de conversación completo | Explorar alternativas en la misma sesión | Resumen opcional | Gestionar varias líneas de pensamiento juntas para facilitar la comparación |
| /fork | Nuevo archivo de sesión | Mostrar solo mensajes de usuario | Iniciar una nueva sesión desde un mensaje anterior | Ninguno | Reiniciar desde un punto histórico, completamente independiente |
| /clone | Nuevo archivo de sesión | Rama activa actual | Copiar el trabajo actual y continuar | Ninguno | Hacer una copia antes de continuar para tener una salida de seguridad |
Resumen de ramas
Cuando saltas de una rama a otra mediante /tree, Pi Agent puede generar un resumen de la rama abandonada.
Este resumen se adjunta a la nueva ubicación para que sepas qué hizo la rama anterior:
| Modo | Comportamiento | Caso de uso |
|---|---|---|
| No generar resumen | Saltar directamente sin conservar ninguna información de la rama abandonada | Los intentos abandonados no tienen valor para conservar |
| Resumen predeterminado | Usar el prompt predeterminado para que la IA resuma la rama abandonada | Solo quieres una idea general de lo que se hizo antes |
| Resumen personalizado | Especifica el enfoque y la IA resume según tus necesidades | Necesitas extraer conclusiones específicas, como los errores encontrados |
Puedes, en~/.pi/agent/settings.jsoncontrolar el comportamiento del resumen:
Ejemplos
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
ConfiguraciónskipPromptEstablecer como true permite omitir la pregunta de «¿generar resumen?» durante la navegación con /tree.
Al omitir la pregunta, no se genera resumen por defecto y se salta directamente a la posición de destino.
Exportar y compartir sesiones
La sesión se puede exportar a un archivo local, o subir directamente para generar un enlace de compartir.
Exportar como HTML
La exportación genera una página de un solo archivo que se puede abrir directamente en el navegador, adecuada para visualización sin conexión.
# 导出到默认位置 /export # 导出到指定文件 /export ~/Desktop/my-session.html
Compartir como GitHub Gist
Cuando no quieras subir archivos, usa el comando /share para generar un enlace en línea.
/share
Después de ejecutarlo, se creará un GitHub Gist privado y se generará un enlace HTML compartible.
Exportación desde línea de comandos
También se pueden exportar sesiones existentes sin entrar en el modo interactivo.
$ pi --export session.jsonl output.html Exported to output.html (128 KB)
Otras extensionesSi trabajas en un proyecto de código abierto y deseas publicar la sesión con fines de investigación, puedes consultarpi-share-hfla herramienta, que puede publicar la sesión en el conjunto de datos de Hugging Face.