Управление сессиями Pi Agent
Система управления сессиями Pi Agent — одна из самых мощных её функций.
В этой главе подробно описываются сохранение, возобновление, ветвление и экспорт сессий.
Механизм хранения сессий
Каждый разговор автоматически сохраняется как файл сессии в формате JSONL, хранящийся в~/.pi/agent/sessions/— каталоге, классифицированном по пути проекта.
Имя каталога формируется из абсолютного пути проекта: слэши заменяются дефисами, и оно заключается в -- с обеих сторон.
Имя файла формируется путём объединения временной метки создания и UUID сессии.
Внутри каждая сессия организована как древовидная структура — это означает, что вы можете ответвляться в любом историческом узле, не теряя содержимое предыдущего разговора.
~/.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
Внутренняя структура файлов сессий
Первая строка файла сессии — это фиксированные метаданные, в которых записаны версия формата сессии, идентификатор сессии, время создания и рабочий каталог.
Эти метаданные не имеют полей id и parentId и не участвуют в дереве диалога.
Начиная со второй строки каждая строка — это запись, и все они имеют поля id и parentId, которые вместе образуют древовидную структуру.
Типы записей включают message, compaction, branch_summary, label, custom и т. д.
Сессии, созданные с помощью /fork или /clone, также имеют дополнительное поле parentSession в метаданных первой строки, указывающее на исходный файл сессии.
{"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 来实现"}]}}
Каталог сессий также можно настроить; приоритет от высокого к низкому: аргумент --session-dir, переменная окруженияPI_CODING_AGENT_SESSION_DIR, и параметр в settings.jsonsessionDir。
Параметры сессии при запуске
Управляйте поведением сессии при запуске с помощью аргументов командной строки:
$ 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)
Команды управления сессиями
После перехода в интерактивный режим следующие команды охватывают повседневное управление сессиями.
| Команда | Функция | Сценарий использования |
|---|---|---|
| /resume | Просмотр и возобновление исторических сессий | Переключитесь на предыдущий диалог и продолжите работу |
| /new | Начать новую сессию | Начать совершенно новую задачу, не связанную с историей |
| /name <name> | Задать имя сессии | Дать сессии легко запоминающееся имя |
| /session | Просмотреть информацию о сессии | Просмотреть путь к файлу, количество сообщений, использование токенов и стоимость |
| /tree | Открыть браузер дерева сессий | Перейти к любому узлу в дереве разговора |
| /fork | Ответвить сессию | Создать новую сессию из предыдущего сообщения пользователя |
| /clone | Клонировать сессию | Скопировать текущую активную ветку в новый файл сессии |
| /export <file> | Экспорт в файл HTML или JSONL | Локальное архивирование или офлайн-обмен |
| /share | Поделиться сессией | Загрузить как GitHub Gist, создав ссылку, которой можно поделиться |
/resume Селектор сессий
Ввод /resume или запуск с pi -r открывает селектор сессий для текущего проекта.
Можно вводить символы прямо в списке для фильтрации сессий; остальные клавиши управления перечислены ниже:
| Действие | Клавиша | Описание |
|---|---|---|
| Фильтровать сессии | Вводите символы напрямую | Фильтровать список сессий текущего проекта в реальном времени на основе ввода |
| Переключить отображение пути | Ctrl+P | Показать или скрыть путь рабочего каталога сессий |
| Переключить сортировку | Ctrl+S | Переключаться между способами сортировки |
| Показывать только именованные сессии | Ctrl+N | Фильтровать только сессии, которым присвоено имя |
| Переименовать | Ctrl+R | Изменить название выбранной сессии |
| Delete | Ctrl+D | Подтверждается перед выполнением; если в системе есть команда trash, перемещает в корзину вместо прямого удаления. |
Дерево сессий (/tree)
Это самая уникальная особенность Pi Agent — сессии хранятся в виде древовидной структуры, и вы можете ответвляться в любом историческом узле.
Древовидная структура
Ниже показана типичная структура дерева сессий:
├─ user: "帮我实现一个登录功能..." │ └─ assistant: "好的，我来实现..." │ ├─ user: "用 JWT 方案..." │ │ └─ assistant: "使用 JWT 实现..." │ │ └─ user: "测试通过了" ← 当前活跃分支 │ └─ user: "还是用 Session 方案..." │ └─ assistant: "使用 Session 实现..."
В этом примере, начиная с одной и той же исходной точки, вы исследовали два подхода — JWT и Session, — и диалоги для каждого подхода полностью сохранены.
Операции в браузере дерева
После открытия /tree используйте следующие клавиши для перемещения и выбора в дереве.
| Действие | Горячая клавиша | Описание |
|---|---|---|
| Перемещение вверх/вниз | ↑/↓ | Перемещает курсор среди видимых записей |
| Страница вверх/вниз | ←/→ | Страница вверх / страница вниз |
| Свернуть/Развернуть | Ctrl+←/Ctrl+→ или Alt+←/Alt+→ | Свернуть/развернуть сегменты ветвей или перейти |
| Установить метку | Shift+L | Установить метку для выбранного узла |
| Переключить временную метку | Shift+T | Показать/скрыть временные метки на метках записей (метки устанавливаются с помощью Shift+L) |
| Подтвердить выбор | Enter | Выбрать текущий узел |
| Cancel | Escape / Ctrl+C | Выйти из браузера дерева |
| Переключить режим фильтрации | Ctrl+O | Перебирать режимы фильтрации (действует только в браузере /tree) |
Режимы фильтрации
Режимы фильтрации определяют, какие записи отображаются в браузере дерева; нажмите Ctrl+O, чтобы переключать их.
| Mode | Отображаемое содержимое |
|---|---|
| default | Вид по умолчанию, сворачивает подробности вызовов инструментов |
| no-tools | Скрыть все вызовы инструментов и результаты |
| user-only | Показывать только сообщения пользователя |
| только помеченные | Показывать только помеченные записи |
| all | Показывать все записи |
При выборе сообщения пользователя его текст подставляется в редактор, что позволяет отредактировать и отправить его повторно, создавая новую ветку.
При выборе ответа ИИ или вызова инструмента происходит переход непосредственно к этой позиции, что позволяет продолжить разговор с этого места.
Различия между /tree, /fork и /clone
Все три позволяют вернуться к исторической позиции; разница в том, создаётся ли новый файл сессии и какую часть разговора можно увидеть.
| Команда | Вывод | Представление | Типичное использование | Сводка по ветке | Памятка в одном предложении |
|---|---|---|---|---|---|
| /tree | Тот же файл сессии | Полное дерево разговора | Исследовать альтернативные подходы в рамках той же сессии | Необязательное резюме | Управление несколькими идеями вместе для удобного сравнения |
| /fork | Новый файл сессии | Показывать только сообщения пользователя | Начать новую сессию с более раннего запроса | Отсутствует | Перезапустить с исторической точки, полностью независимо |
| /clone | Новый файл сессии | Текущая активная ветка | Скопировать текущую работу и продолжить | Отсутствует | Сделать копию перед продолжением, сохранив резервный вариант |
Сводка по ветке
Когда вы переходите с одной ветки на другую через /tree, Pi Agent может создать для вас сводку покинутой ветки.
Эта сводка прикрепляется к новому месту, чтобы вы знали, что делала предыдущая ветка:
| Mode | Поведение | Применимый сценарий |
|---|---|---|
| Сводка не создана | Перейти напрямую, не сохраняя никакой информации о покинутой ветке | Покинутая попытка не имеет ценности, которую стоит сохранять |
| Сводка по умолчанию | Использовать запрос по умолчанию, чтобы ИИ сделал сводку по заброшенной ветке | Нужно только приблизительное представление о том, что было сделано раньше |
| Пользовательская сводка | Укажите фокус, и ИИ создаст сводку в соответствии с вашими потребностями | Нужно получить конкретные выводы, например о встреченных подводных камнях |
Вы можете управлять поведением сводки в~/.pi/agent/settings.json:
Пример
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
НастройкаskipPromptУстановите значение true, чтобы пропустить запрос "создавать ли сводку" при навигации с помощью /tree.
После пропуска запроса сводка по умолчанию не создаётся, и происходит прямой переход к целевой позиции.
Экспорт и общий доступ к сессиям
Сессии можно экспортировать как локальные файлы или загружать напрямую, чтобы создать ссылку для обмена.
Экспортировать как HTML
При экспорте создаётся страница в виде одного файла, которую можно открыть прямо в браузере; подходит для офлайн-просмотра.
# 导出到默认位置 /export # 导出到指定文件 /export ~/Desktop/my-session.html
Поделиться как GitHub Gist
Если вы не хотите загружать файлы, используйте команду /share, чтобы создать онлайн-ссылку.
/share
После выполнения будет создан приватный GitHub Gist и сгенерирована HTML-ссылка, которой можно поделиться.
Экспорт из командной строки
Существующие сессии можно экспортировать без входа в интерактивный режим.
$ pi --export session.jsonl output.html Exported to output.html (128 KB)
Другие расширенияЕсли вы работаете над проектом с открытым исходным кодом и хотите публиковать сессии в исследовательских целях, обратите внимание наpi-share-hf— инструмент, который может публиковать сессии в наборах данных Hugging Face.