@link17528/pi-session-deck1.0.3
Keyboard-first session browsing and management for Pi
Untested on omp
This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.
Reports 0
No reports yet.
Readme
PiSessionDeck
English | 简体中文
面向 Pi 的键盘优先会话浏览器。在终端中定位历史对话、预览上下文，并回到原项目继续工作。
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。
pi install npm:@link17528/pi-session-deck
需要固定版本时使用 npm:@link17528/pi-session-deck@1.0.3。也可通过 Git 安装，此方式还需 Git：
pi install git:github.com/De0ta/PiSessionDeck@v1.0.3
重启 Pi，然后输入：
/session-browser
也可以在主编辑器完全为空时按 ←。编辑器包含文字、空格或换行，或自动补全处于活动状态时，保留原生按键行为。其他扩展已接管自定义编辑器时，请使用命令入口。
Pi 直接加载 TypeScript 扩展，无需编译、手动复制文件或单独配置 API 密钥。自动命名复用你已有的 Pi 模型配置与凭据。
默认安装到个人配置，以便跨项目切换后继续使用。除非明确需要项目级安装，否则不要添加 --local。不要同时加载已安装副本和 pi -e . 开发副本。
更新： 未指定版本的 npm 来源可通过 pi update --extensions 跟进新版本；指定的 npm 版本、Git 标签与提交保持固定，升级时应移除旧来源，再安装目标版本。请只保留一个安装来源。详见安装、更新与卸载指南。
快速开始
- 打开
/session-browser，默认显示全部项目的会话。 - 按
F3搜索，按Tab限定当前项目，或按g切换分组。 - 使用
↑/↓选择对话，在详情栏查看最近一轮问答。 - 按
Enter或→进入恢复确认页。 - 核对目标后确认，由 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 提交。删除只影响单个会话文件，不删除项目或分叉，也不停止其他进程。置顶与历史标题别名独立于会话历史存储。
文件格式、存储限制和操作细节见会话管理专题。
快捷键
下表列出浏览器导航操作；会话管理操作见上节。
| 按键 | 操作 |
|---|---|
↑ / ↓ |
选择会话，遵循 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。
开发
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 安装。检查公开版本的匿名安装可使用：
npm run smoke:install -- --public --ref v1.0.3
文档与支持
报告问题时，请提供操作系统、终端、Node/Pi 版本与复现步骤。截图和日志应先脱敏，不要附上凭据或完整私人会话。
许可证
采用 MIT 许可证。