# PiSessionDeck

[English](README.md) | **简体中文**

**面向 Pi 的键盘优先会话浏览器。在终端中定位历史对话、预览上下文，并回到原项目继续工作。**

[![CI](https://github.com/De0ta/PiSessionDeck/actions/workflows/ci.yml/badge.svg)](https://github.com/De0ta/PiSessionDeck/actions/workflows/ci.yml)
[![GitHub release](https://img.shields.io/github/v/release/De0ta/PiSessionDeck)](https://github.com/De0ta/PiSessionDeck/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

PiSessionDeck 在 Pi 内提供全屏、面向项目的本地会话视图。无需离开终端，即可搜索历史、查看最近一轮问答，并恢复目标会话。

## 为什么选择 PiSessionDeck

- **跨项目定位对话。** 按项目、最近活动、模型或状态分组；搜索标题、项目路径、会话 ID 和消息文本，多个关键词采用 AND 匹配。
- **切换前先了解上下文。** 宽屏分栏展示元数据、末次回复及其对应提问，使用 Pi 原生 Markdown 渲染；窄屏提供独立详情视图。
- **以键盘完成操作。** 在空输入框按 `←`，或输入 `/session-browser` 打开。搜索、导航、重命名与帮助各有明确入口。
- **管理不同工作分支。** 新建对话、分叉探索其他方案、置顶常用会话，并清理不再需要的历史。
- **让标题更有辨识度。** 新的未命名会话先使用本地回退标题，首次成功交互后可由当前模型生成标题；用户手动命名始终优先。
- **回到正确的项目继续工作。** 确认页展示目标项目，切换前检查草稿、运行中任务和排队消息。
- **本地浏览。** 搜索与预览直接读取本地会话文件；自动命名复用当前 Pi 模型，详见[数据与模型使用](#数据与模型使用)。

## 典型使用场景

- **接着上次的工作继续。** 按项目或话题定位对话，查看最近一轮问答，再回到原项目恢复。适合在多个仓库之间切换，或隔一段时间后重新接手任务。
- **保留原方案，探索另一条路线。** 选中对话后按 `f`，将有效分支复制为独立会话，从末次回复继续推进，原会话仍可随时回看与比较。
- **快速访问长期任务。** 用 `r` 设置容易辨认的标题，再用 `p` 置顶。切换分组方式时，常用会话仍集中显示在独立的 `Pinned` 区。
- **整理已完成的工作。** 删除前先预览历史，确认弹层会标明目标会话；删除会话后，项目目录与分叉对话仍保留。

## 安装

要求 **Node.js 22.19.0+**，以及 `@earendil-works/pi-coding-agent` 提供的 **Pi 1.4.x**。

```sh
pi install npm:@link17528/pi-session-deck
```

需要固定版本时使用 `npm:@link17528/pi-session-deck@1.0.3`。也可通过 Git 安装，此方式还需 **Git**：

```sh
pi install git:github.com/De0ta/PiSessionDeck@v1.0.3
```

重启 Pi，然后输入：

```text
/session-browser
```

也可以在主编辑器完全为空时按 `←`。编辑器包含文字、空格或换行，或自动补全处于活动状态时，保留原生按键行为。其他扩展已接管自定义编辑器时，请使用命令入口。

Pi 直接加载 TypeScript 扩展，无需编译、手动复制文件或单独配置 API 密钥。自动命名复用你已有的 Pi 模型配置与凭据。

默认安装到个人配置，以便跨项目切换后继续使用。除非明确需要项目级安装，否则不要添加 `--local`。不要同时加载已安装副本和 `pi -e .` 开发副本。

**更新：** 未指定版本的 npm 来源可通过 `pi update --extensions` 跟进新版本；指定的 npm 版本、Git 标签与提交保持固定，升级时应移除旧来源，再安装目标版本。请只保留一个安装来源。详见[安装、更新与卸载指南](https://github.com/De0ta/PiSessionDeck/blob/main/docs/install.md)。

## 快速开始

1. 打开 `/session-browser`，默认显示全部项目的会话。
2. 按 `F3` 搜索，按 `Tab` 限定当前项目，或按 `g` 切换分组。
3. 使用 `↑` / `↓` 选择对话，在详情栏查看最近一轮问答。
4. 按 `Enter` 或 `→` 进入恢复确认页。
5. 核对目标后确认，由 Pi 切换会话及其项目运行时。

按 `Esc` 可返回而不恢复。退出确认页后，原有搜索、分组、展开状态、选中项及详情滚动位置都会保留。

### 界面布局

| 区域 | 显示内容 |
| --- | --- |
| 顶部栏 | 当前分组方式、项目范围与匹配的会话数量。 |
| 会话列表 | 分组后的对话，以及标题、状态和最近更新时间。 |
| 详情栏 | 选中会话的元数据、末次回复及其对应提问。 |
| 快捷键帮助 | 按 `?` 查看导航与会话管理操作。 |

宽屏下，列表与详情并排显示。窄屏下，选中会话后按 `d` 打开详情，再按 `←` 返回。较长回复可用 `Shift+↑` / `Shift+↓` 滚动。

### 主题与终端配色

普通区域保留终端默认背景；文字、选中行、搜索栏、确认面板和会话身份色使用 Pi 当前主题，并跟随运行中的主题变化。不再固定使用黑色背景，也不读取特定终端的配置文件。

如果希望匹配终端配色（例如 Ghostty 或 Windows Terminal 中的 Catppuccin Mocha），请在 `/settings` → **Theme** 中选择 **system**。Pi 会查询终端的前景色、背景色和 ANSI 调色板；终端不返回颜色时，回退为 ANSI 色与终端默认色。同样支持自定义 Pi 主题。

### 分组与预览

按 `g` 可循环切换四种视图：

| 视图 | 适用场景 |
| --- | --- |
| Project | 按工作目录聚合，回到同一项目的相关对话。 |
| Recent | 根据最近更新时间找回正在推进或刚结束的工作。 |
| Model | 按供应商与模型 ID 查看会话。 |
| Status | 区分当前会话的运行状态与已保存历史。 |

每组默认显示五条会话，选择 `Show more` 再展开五条。最近活动按六个互不重叠的区间划分：不足 5 小时、5 小时至 1 天、1–7 天、7–30 天、30–90 天，以及 90 天及以上。置顶会话独立展示，同时遵循当前项目范围与搜索条件。

预览跟随当前分支，尊重已提交的上下文编辑。显示末次回复及其对应提问；尚无回复时显示最新提问。不展示思考内容和工具结果。

运行时状态来自当前 Pi 进程。其他会话显示为 `Saved`，表示已保存的历史记录。

### 搜索会话

按 `F3` 后，可输入话题、项目路径片段、会话 ID 或对话中的文字。搜索不区分大小写，以空白分隔的关键词需要全部匹配。例如，`login api` 会筛选同时匹配两个关键词的会话。按 `Tab` 可以将范围限定为当前项目，也可切回全部项目。

搜索与分组可以配合使用。从恢复确认页返回后，搜索词、选中项、分组展开状态与预览滚动位置都会保留，方便连续比较多个候选会话。

## 会话管理

直接在浏览器中完成新建、分叉、置顶、重命名与删除。

| 按键 | 操作 |
| --- | --- |
| `n` | 在选中会话的项目目录新建空会话；没有选中项时使用当前目录，不发送提问。 |
| `f` | 分叉选中会话的有效分支，保留末次回复，并打开副本。 |
| `p` | 置顶或取消置顶已保存会话；四种分组模式均有独立 `Pinned` 区。 |
| `Delete` | 打开确认弹层，永久删除一个非当前会话文件。 |
| `a` | 打开 New、Fork、Pin / Unpin、Rename、Delete 操作菜单。 |

搜索与重命名时，字母仍作为文本输入。尚未落盘的当前会话显示 `Unsaved`，不能置顶或分叉；当前会话不能删除。

新建时，同项目使用 Pi 原生 New；跨项目则创建只含原生会话头的新文件，再切换进入。选中会话的项目目录缺失或无效时会报错，不回退到当前目录。新建不发送提问、不复制历史；文件已创建但打开失败或取消时，在原确认页重试会复用该文件。

分叉具有独立身份，标题追加 ` · Fork`，不继承置顶。历史分叉通过验证后的只读快照创建，不先恢复或改写源会话。如果副本已创建但打开失败，会保留该副本；在原确认页重试会复用它。

删除默认选中 **Cancel**。数字键仅改变选择，只有 `Enter` 提交。删除只影响单个会话文件，不删除项目或分叉，也不停止其他进程。置顶与历史标题别名独立于会话历史存储。

文件格式、存储限制和操作细节见[会话管理专题](https://github.com/De0ta/PiSessionDeck/blob/main/docs/management.md)。

## 快捷键

下表列出浏览器导航操作；会话管理操作见上节。

| 按键 | 操作 |
| --- | --- |
| `↑` / `↓` | 选择会话，遵循 Pi 配置的列表方向键。 |
| `PageUp` / `PageDown` | 翻页选择。 |
| `Enter` / `→` | 进入恢复确认页、返回当前会话，或展开 `Show more`。 |
| `Tab` / `Shift+Tab` | 切换全部项目 / 当前项目；兼容 `Ctrl+O`。 |
| `F3` | 显示或隐藏搜索。 |
| `g` | 循环切换 Project → Recent → Model → Status。 |
| `r` | 编辑选中标题；`Enter` 保存，`Esc` 取消。 |
| `Shift+↑` / `Shift+↓` | 滚动末次回复，保留提问与元数据。 |
| `d` / `←` | 窄屏打开详情 / 返回列表。 |
| `Ctrl+R` | 重新扫描会话。 |
| `?` | 打开快捷键帮助。 |
| `Esc` | 退出帮助或搜索；普通模式下关闭浏览器。 |
| `Ctrl+C` | 关闭浏览器，不切换会话。 |

搜索与重命名模式保留普通文本输入及光标移动，不触发字母快捷操作。

恢复页使用 `↑` / `↓` 或 `1` / `2` 选择，`Enter` / `→` 确认，`Esc` / `Ctrl+C` 返回；`PageUp` / `PageDown` 滚动长路径或错误。只读预检可以取消；切换提交给 Pi 后，公开 API 无法撤销，页面会等待完成。

## 数据与模型使用

### 本地历史

浏览、搜索与预览均在本地运行，直接读取 Pi 会话文件。历史重命名仅写入扩展专用别名；当前会话重命名使用 Pi 原生名称元数据。恢复历史会话后，别名才转为原生名称。

预览中的每条提问和回复各限制为 6,000 字符。超过 16 MiB 的文件跳过预览及模型元数据读取，但仍可恢复。Pi 发现 API 为建立搜索索引仍会扫描历史；会话较多时可限定当前项目。

### 自动标题

符合条件的未命名会话在首次成功交互后先保存本地回退标题，再向当前配置的模型额外请求至多一次。请求使用首问最多 4,000 字符和对应最终文本回复最多 2,000 字符，尊重已提交的上下文编辑并去除包装内容；不包含思考、工具结果或图片。

请求输出上限为 256 token，超时为 15 秒。它可能产生模型费用，用量不会自动计入 Pi 主对话统计。失败时保留回退标题，不自动重试；不覆盖已有名称或用户手动命名，也不批量重命名历史。模型生成的标题会去除通用标题标签前缀。

### 会话切换与删除

恢复时，会话和项目运行时一并切换。目标项目目录需要存在且可访问；切换前会检查会话身份与文件修订。Pi 打开旧格式会话时可能进行格式迁移。

恢复或删除前，请关闭正在写入该会话的其他 Pi 实例。删除会永久移除选中的会话文件，保留项目目录和分叉会话。

## 兼容性

运行环境为 **Pi 1.4.x** 与 **Node.js 22.19.0+**。

| 检查项目 | 覆盖范围 |
| --- | --- |
| CI 矩阵 | Windows、Ubuntu × Node 22.19、24。 |
| 本地回归测试 | Windows / Node 24：188 项测试，187 项通过，1 项符号链接测试因账号权限跳过。 |
| 本地打包检查 | 类型检查通过；21 文件包通过隔离 Pi 扩展加载检查。 |

Linux 使用原生 POSIX 路径。请使用运行 Pi 的环境所对应的项目路径；Windows 路径不会自动转换为 Linux 或 WSL 路径。各版本执行结果见 [GitHub Releases](https://github.com/De0ta/PiSessionDeck/releases)。

## 开发

```sh
git clone https://github.com/De0ta/PiSessionDeck.git PiSessionDeck
cd PiSessionDeck
npm ci
npm run check
npm test
npm run smoke:package
npm run smoke:install
```

直接运行源码可使用 `pi -e /absolute/path/to/PiSessionDeck`，同时禁用已安装副本。

测试使用临时会话数据。`smoke:package` 通过 Pi 扩展加载器检查当前工作树；`smoke:install` 检查已提交 `HEAD` 的 Git 安装。检查公开版本的匿名安装可使用：

```sh
npm run smoke:install -- --public --ref v1.0.3
```

## 文档与支持

- [安装、更新、卸载与故障排查](https://github.com/De0ta/PiSessionDeck/blob/main/docs/install.md)
- [会话管理与存储细节](https://github.com/De0ta/PiSessionDeck/blob/main/docs/management.md)
- [版本记录](CHANGELOG.md)
- [技术文档与设计记录](https://github.com/De0ta/PiSessionDeck/tree/main/docs)
- [提交问题](https://github.com/De0ta/PiSessionDeck/issues)

报告问题时，请提供操作系统、终端、Node/Pi 版本与复现步骤。截图和日志应先脱敏，不要附上凭据或完整私人会话。

## 许可证

采用 [MIT](LICENSE) 许可证。