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.

CommandeFonctionCas d'utilisation
/resumeParcourir et reprendre les sessions historiquesPasser à une conversation précédente et continuer à travailler
/newDémarrer une nouvelle sessionDémarrer une toute nouvelle tâche sans rapport avec l'historique
/name <name>Définir le nom de la sessionDonner à la session un nom facile à mémoriser
/sessionAfficher les informations de sessionAfficher le chemin de fichier, le nombre de messages, l'utilisation des tokens et le coût
/treeOuvrir le navigateur d'arborescence des sessionsAccéder à n'importe quel nœud de l'arborescence de conversation
/forkDupliquer la sessionCréer une nouvelle session à partir d'un message utilisateur précédent
/cloneCloner la sessionCopier la branche active courante vers un nouveau fichier de session
/export <file>Exporter en fichier HTML ou JSONLArchivage local ou partage hors ligne
/sharePartager la sessionTé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 :

ActionToucheDescription
Filtrer les sessionsSaisir directement les caractèresFiltrer en temps réel la liste des sessions du projet actuel en fonction de la saisie
Afficher/masquer le cheminCtrl+PAfficher ou masquer le chemin du répertoire de travail des sessions
Basculer le triCtrl+SBasculer entre les méthodes de tri
Afficher uniquement les sessions nomméesCtrl+NFiltrer sur les sessions qui ont été nommées
RenommerCtrl+RModifier le nom de la session sélectionnée
DeleteCtrl+DConfirmé 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.

ActionRaccourciDescription
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évelopperCtrl+←/Ctrl+→ ou Alt+←/Alt+→Réduire/développer les segments de branche ou sauter
Définir l’étiquetteShift+LDéfinir une étiquette pour le nœud sélectionné
Afficher/masquer l’horodatageShift+TAfficher/masquer les horodatages sur les étiquettes d’entrée (les étiquettes sont définies avec Shift+L)
Confirmer la sélectionEntréeSélectionner le nœud actuel
CancelÉchap / Ctrl+CQuitter l'explorateur d'arborescence
Basculer le mode de filtreCtrl+OParcourir 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.

ModeContenu affiché
defaultVue par défaut, replie les détails des appels d'outils
no-toolsMasquer tous les appels d'outils et leurs résultats
user-onlyAfficher uniquement les messages utilisateur
étiquetés uniquementAfficher uniquement les entrées étiquetées
allAfficher 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.

CommandeSortieVueUtilisation typiqueRésumé de brancheMémoire en une phrase
/treeMême fichier de sessionArborescence complète de la conversationExplorer des approches alternatives dans la même sessionRésumé facultatifGérer plusieurs idées ensemble pour faciliter la comparaison
/forkNouveau fichier de sessionAfficher uniquement les messages utilisateurDémarrer une nouvelle session à partir d’un prompt antérieurAucuneRedémarrer à partir d’un point historique, de manière totalement indépendante
/cloneNouveau fichier de sessionBranche active actuelleCopier le travail actuel et continuerAucuneFaire 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 :

ModeComportementScénario applicable
Aucun résumé généréPasser directement sans conserver aucune information sur la branche abandonnéeLa tentative abandonnée n’a aucune valeur qui vaille la peine d’être conservée
Résumé par défautUtiliser le prompt par défaut pour laisser l'IA résumer la branche abandonnéeVous 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 besoinsBesoin 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)

Si 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.

Autres extensions