Gestion des sessions de Pi Agent
Le système de gestion des sessions de Pi Agent est l'une de ses fonctionnalités les plus puissantes.
Ce chapitre détaille l'enregistrement, la reprise, le branchement et l'exportation des sessions.
Mécanisme de stockage des sessions
Chaque conversation est automatiquement enregistrée sous forme de fichier de session au format JSONL, stocké dans~/.pi/agent/sessions/un répertoire classé par chemin de projet.
Le nom du répertoire est dérivé du chemin absolu du projet : les barres obliques sont remplacées par des tirets, et il est encadré par -- des deux côtés.
Le nom de fichier est formé en concaténant l'horodatage de création et l'UUID de session.
En interne, chaque session est organisée sous forme d'arborescence—cela signifie que vous pouvez créer une branche à n'importe quel nœud historique sans perdre le contenu de la conversation précédente.
~/.pi/agent/sessions/
└── --Users-example-projects-example-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
Structure interne des fichiers de session
La première ligne d'un fichier de session est constituée de métadonnées fixes, qui enregistrent la version du format de session, l'ID de session, l'heure de création et le répertoire de travail.
Ces métadonnées ne comportent pas de champs id et parentId et ne participent pas à l'arbre de conversation.
À partir de la deuxième ligne, chaque ligne est une entrée, toutes avec des champs id et parentId, qui forment ensemble la structure arborescente.
Les types d'entrée incluent message, compaction, branch_summary, label, custom, etc.
Les sessions créées par /fork ou /clone comportent également un champ parentSession supplémentaire dans les métadonnées de la première ligne, pointant vers le fichier de session d'origine.
{"type":"session","version":3,"id":"019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a","timestamp":"2026-08-31T02:40:11.000Z","cwd":"/Users/example/projects/example-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 来实现"}]}}
Le répertoire de session peut également être personnalisé ; la priorité, de la plus élevée à la plus faible, est : l'argument --session-dir, la variable d'environnementPI_CODING_AGENT_SESSION_DIR, et celle dans settings.jsonsessionDir。
Options de session au démarrage
Contrôlez le comportement de session au démarrage via des arguments de ligne de commande :
$ 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-example-projects-example-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)
Commandes de gestion de session
Une fois en mode interactif, les commandes suivantes couvrent la gestion quotidienne des sessions.
| Commande | Fonction | Cas d'utilisation |
|---|---|---|
| /resume | Parcourir et reprendre les sessions historiques | Passer à une conversation précédente et continuer à travailler |
| /new | Démarrer une nouvelle session | Démarrer une toute nouvelle tâche sans rapport avec l'historique |
| /name <name> | Définir le nom de la session | Donner à la session un nom facile à mémoriser |
| /session | Afficher les informations de session | Afficher le chemin de fichier, le nombre de messages, l'utilisation des tokens et le coût |
| /tree | Ouvrir le navigateur d'arborescence des sessions | Accéder à n'importe quel nœud de l'arborescence de conversation |
| /fork | Dupliquer la session | Créer une nouvelle session à partir d'un message utilisateur précédent |
| /clone | Cloner la session | Copier la branche active courante vers un nouveau fichier de session |
| /export <file> | Exporter en fichier HTML ou JSONL | Archivage local ou partage hors ligne |
| /share | Partager la session | Téléverser en tant que GitHub Gist, en générant un lien partageable |
/resume Sélecteur de session
Saisir /resume ou démarrer avec pi -r ouvre le sélecteur de session pour le projet actuel.
Vous pouvez saisir des caractères directement dans la liste pour filtrer les sessions ; les autres touches d'opération sont les suivantes :
| Action | Touche | Description |
|---|---|---|
| Filtrer les sessions | Saisir directement les caractères | Filtrer en temps réel la liste des sessions du projet actuel en fonction de la saisie |
| Afficher/masquer le chemin | Ctrl+P | Afficher ou masquer le chemin du répertoire de travail des sessions |
| Basculer le tri | Ctrl+S | Basculer entre les méthodes de tri |
| Afficher uniquement les sessions nommées | Ctrl+N | Filtrer sur les sessions qui ont été nommées |
| Renommer | Ctrl+R | Modifier le nom de la session sélectionnée |
| Delete | Ctrl+D | Confirmé avant exécution ; si le système dispose de la commande trash, déplace vers la corbeille au lieu d'une suppression directe. |
Arborescence des sessions (/tree)
C'est la fonctionnalité la plus distinctive de Pi Agent — les sessions sont stockées sous forme d'arborescence, et vous pouvez créer une bifurcation à n'importe quel nœud historique.
Structure arborescente
Voici une structure typique d'arborescence de sessions :
├─ user: "帮我实现一个登录功能..." │ └─ assistant: "好的,我来实现..." │ ├─ user: "用 JWT 方案..." │ │ └─ assistant: "使用 JWT 实现..." │ │ └─ user: "测试通过了" ← 当前活跃分支 │ └─ user: "还是用 Session 方案..." │ └─ assistant: "使用 Session 实现..."
Dans cet exemple, en partant de la même origine, vous avez exploré deux approches, JWT et Session, et les conversations pour chaque approche sont entièrement préservées.
Opérations du navigateur d'arborescence
Après avoir ouvert /tree, utilisez les touches suivantes pour vous déplacer et sélectionner dans l'arborescence.
| Action | Raccourci | Description |
|---|---|---|
| Déplacer vers le haut/bas | ↑/↓ | Déplacer le curseur parmi les entrées visibles |
| Page précédente/suivante | ←/→ | Page précédente / page suivante |
| Réduire/Développer | Ctrl+←/Ctrl+→ ou Alt+←/Alt+→ | Réduire/développer les segments de branche ou sauter |
| Définir l’étiquette | Shift+L | Définir une étiquette pour le nœud sélectionné |
| Afficher/masquer l’horodatage | Shift+T | Afficher/masquer les horodatages sur les étiquettes d’entrée (les étiquettes sont définies avec Shift+L) |
| Confirmer la sélection | Entrée | Sélectionner le nœud actuel |
| Cancel | Échap / Ctrl+C | Quitter l'explorateur d'arborescence |
| Basculer le mode de filtre | Ctrl+O | Parcourir les modes de filtre (ne s'applique qu'à l'explorateur /tree) |
Modes de filtre
Les modes de filtre déterminent quelles entrées sont affichées dans l'explorateur d'arborescence ; appuyez sur Ctrl+O pour passer de l'un à l'autre.
| Mode | Contenu affiché |
|---|---|
| default | Vue par défaut, replie les détails des appels d'outils |
| no-tools | Masquer tous les appels d'outils et leurs résultats |
| user-only | Afficher uniquement les messages utilisateur |
| étiquetés uniquement | Afficher uniquement les entrées étiquetées |
| all | Afficher toutes les entrées |
Sélectionner un message d'utilisateur remplit son texte dans l'éditeur, ce qui vous permet de le modifier et de le renvoyer, créant ainsi une nouvelle branche.
Sélectionner une réponse d'IA ou un appel d'outil saute directement à cette position, vous permettant de poursuivre la conversation à partir de là.
Différences entre /tree, /fork et /clone
Les trois peuvent revenir à une position historique ; la différence réside dans le fait qu'un nouveau fichier de session est créé ou non et dans la quantité de conversation visible.
| Commande | Sortie | Vue | Utilisation typique | Résumé de branche | Mémoire en une phrase |
|---|---|---|---|---|---|
| /tree | Même fichier de session | Arborescence complète de la conversation | Explorer des approches alternatives dans la même session | Résumé facultatif | Gérer plusieurs idées ensemble pour faciliter la comparaison |
| /fork | Nouveau fichier de session | Afficher uniquement les messages utilisateur | Démarrer une nouvelle session à partir d’un prompt antérieur | Aucune | Redémarrer à partir d’un point historique, de manière totalement indépendante |
| /clone | Nouveau fichier de session | Branche active actuelle | Copier le travail actuel et continuer | Aucune | Faire une copie avant de continuer, en gardant une solution de repli |
Résumé de branche
Lorsque vous passez d’une branche à une autre via /tree, Pi Agent peut générer pour vous un résumé de la branche abandonnée.
Ce résumé est attaché au nouvel emplacement, afin que vous sachiez ce que la branche précédente a fait :
| Mode | Comportement | Scénario applicable |
|---|---|---|
| Aucun résumé généré | Passer directement sans conserver aucune information sur la branche abandonnée | La tentative abandonnée n’a aucune valeur qui vaille la peine d’être conservée |
| Résumé par défaut | Utiliser le prompt par défaut pour laisser l'IA résumer la branche abandonnée | Vous voulez seulement une idée approximative de ce qui a été fait auparavant |
| Résumé personnalisé | Spécifiez le focus, et l'IA résume selon vos besoins | Besoin de tirer des conclusions spécifiques, comme les pièges rencontrés |
Vous pouvez contrôler le comportement du résumé dans~/.pi/agent/settings.json:
Exemple
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
ParamètreskipPromptDéfini sur true pour ignorer l'invite « faut-il générer un résumé » lors de la navigation avec /tree.
Après avoir ignoré l'invite, aucun résumé n'est généré par défaut, et il saute directement à la position cible.
Exporter et partager les sessions
Les sessions peuvent être exportées sous forme de fichiers locaux, ou téléversées directement pour générer un lien de partage.
Exporter en HTML
L'exportation génère une page d'un seul fichier qui peut être ouverte directement dans un navigateur, adaptée à la consultation hors ligne.
# 导出到默认位置 /export # 导出到指定文件 /export ~/Desktop/my-session.html
Partager en tant que GitHub Gist
Lorsque vous ne voulez pas téléverser de fichiers, utilisez la commande /share pour générer un lien en ligne.
/share
Après l'exécution, un GitHub Gist privé sera créé et un lien HTML partageable sera généré.
Export en ligne de commande
Les sessions existantes peuvent être exportées sans entrer en mode interactif.
$ pi --export session.jsonl output.html Exported to output.html (128 KB)
Autres extensionsSi vous travaillez sur un projet open source et souhaitez publier des sessions à des fins de recherche, vous pouvez consulterpi-share-hfun outil qui peut publier des sessions dans des jeux de données Hugging Face.