# pi-history-tree

**随时回看先前的对话，不打断当前的探索。**

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

## 对话再长，也能找回最初的思路

让 Agent 帮你规划代码阅读路线，然后逐步深入仓库：阅读第一个模块、检查实现、追踪函数调用，再提出一个又一个问题。

几十轮对话后，想重新查看最初的 Roadmap，却发现它已经淹没在大量工具调用和历史消息中。

**pi-history-tree 让你随时找到之前的问题，打开当时保存的完整回答，再回到当前会话继续探索。不必反复向上滚动，也不需要切换 Session 分支。**

输入 `/history-tree` 浏览之前的问题，选中后打开当时的对话。按 `Esc` 返回问题列表，再按一次 `Esc`，就能继续手头的工作。

探索继续向前，先前的思考成果随时可回看。

![浏览先前的问题，打开想要重新阅读的回答](docs/images/history-tree-example.png)

## 找到问题，读到答案，继续探索

- **搜索你记得问过的话。** 你通常记得自己问过“帮我制定这个仓库的阅读路线”，却未必记得 Agent 回答中的确切措辞。因此列表只展示用户消息，方便找到当时的提问。
- **先看结果，不看执行日志。** 打开后默认展示用户输入及其最终回答。Roadmap、架构分析和总结可以直接阅读，Thinking、工具调用和中间过程默认隐藏。
- **回看之后，接着做事。** 阅读不会改变当前会话位置、创建分支、重新执行任务或发送模型请求。返回列表时，搜索词和选中位置也会保留。
- **需要细节时再展开过程。** `Ctrl+P` 可以查看完整的已保存过程，包括工具、Thinking 和压缩摘要。

## 和 pi 自带的 Tree 有什么区别？

想跳到会话中的另一个位置，并从那里继续工作，用 pi 自带的 `/tree`；**只是想回看先前的回答，然后继续当前工作，用 `/history-tree`。**

插件打开的是独立的只读阅读视图，不会切换当前分支。每次只阅读一条分支，不混入其它分支的对话；连续消息保持同层，只有分叉才增加缩进。

它不修改 pi 核心，也不替换原生 `/tree`。

## 安装

需要先安装 pi。已在 `@earendil-works/pi-coding-agent` **1.4.0** 上验证。

### 从 npm 安装（推荐）

直接安装已发布的包，无需克隆仓库：

```bash
pi install npm:pi-history-tree
```

也可以固定安装版本：

```bash
pi install npm:pi-history-tree@0.1.0
```

已经运行的 pi 执行 `/reload` 即可加载；以后启动 pi 会自动加载。

### 从本地仓库安装（适合开发）

如果需要修改插件代码，克隆或下载本仓库后，**在仓库目录内**执行：

```bash
pi install .
```

这会将本地包注册到当前用户的 pi 配置中。请保留仓库目录，pi 会直接从这个目录加载插件。

已经运行的 pi 执行 `/reload` 即可加载；以后启动 pi 会自动加载。

### 不安装，临时体验

只在本次 pi 启动中加载 npm 包：

```bash
pi -e npm:pi-history-tree
```

也可以临时加载本地仓库：

```bash
pi -e /absolute/path/to/pi-history-tree/src/index.js
```

将路径替换为实际仓库路径。两种方式都只对本次启动生效，不修改配置。

如果之前安装了本地版本，切换到 npm 时先移除本地注册，避免重复加载：

```bash
pi remove /absolute/path/to/pi-history-tree
pi install npm:pi-history-tree
```

这只会移除 pi 中的注册，不会删除仓库目录。

## 使用

在 pi 中输入：

```text
/history-tree
```

1. 搜索你之前问过的内容，例如“阅读路线”或“Roadmap”，用 **↑ / ↓** 选择问题。
2. 按 **Enter** 打开当时的回答，阅读位置自动定位到该问题。
3. 用 **↑ / ↓** 滚动，或用 **PgUp / PgDn** 翻页。
4. 按 **Esc** 返回历史树，再按 **Esc** 退出浏览器。

选中的消息属于当前分支时，直接打开当前分支；否则，如果存在多个后续分支，会先让你选择要阅读哪一条。`*` 标记当前分支上的消息。

### 快捷键

**历史树**
- 直接输入搜索，Backspace 编辑搜索词；也支持搜索消息 ID。
- ↑ / ↓ 移动选择，PgUp / PgDn 翻页。
- Enter 打开阅读器；Esc 直接退出，即使搜索框中有文字。

**阅读器**
- ↑ / ↓ 滚动，PgUp / PgDn 翻页，Home / End 跳到开头或结尾。
- Ctrl+P 切换“**用户输入＋最终回复**”和“**完整过程**”。
- Esc 返回历史树。

## 说明

- “最终回复”根据历史记录的结束状态判断，不调用模型生成摘要。未完成或无法确认的回复会显示简短提示，可用 Ctrl+P 查看原始过程。
- 图片显示为占位提示。工具输出以实际保存的内容为准，无法恢复保存前已被截断的内容。
- 阅读器展示打开时的快照。如果模型仍在运行，它会继续正常工作；关闭浏览器后重新打开即可看到更新的消息。

## 许可证

本项目采用 [MIT 许可证](LICENSE)，版权归 2026 JXZxiao5 所有。