# 历史对话

`/pbot history [关键词]` 查询当前工作区的 Pi 历史。留空列出最近会话，选择后可查看正文、父节点和子节点；正文查看器中的修改不保存。无需 `/name`。也可以直接请 agent 查找某件事，agent 使用 `pbot_history`。

## 查询

| 操作 | 参数与行为 |
| --- | --- |
| search | query 是不区分大小写的连续文本，搜索问答原文和所有已生成摘要；省略 query 列会话。sessionId、from、to 限定会话和相交的时间范围，日期按 ISO 解析；offset/limit 分页，默认 20、最多 50 条 |
| read | id 是搜索或导航返回的节点 ID；offset/limit 读取正文，默认 12000、最多 24000 个 UTF-16 单元；childrenOffset 分页子节点，每页 20 个 |

返回的 nextOffset、nextChildrenOffset 非空时可继续读取。parents/children 提供节点 ID 与预览；共享前缀可能有多个父节点。source 给出原始 sessionId 和消息 entryIds，摘要的消息 ID 是覆盖范围的首尾。来源不保存文件路径；原始会话不可用时，已保存的问答仍可直接读取。ready=false 表示摘要尚未生成；completed=false 表示内容包含未完成的问答。

查询不调用模型，不恢复会话或重放旧任务。摘要命中是检索线索，重要结论要展开到问答原文核对。全文搜索依赖词语重合，忘记原词时 agent 可以换几组词查询。不同层级的命中分别返回。

## 收录与整理

加载、查询和交互结束时，通过 Pi SDK 发现当前工作区会话，读取当前会话目录、原生默认目录、当前会话以及该工作区受管子会话的原生引用，按 sessionId 关联已有存档。不在发现范围内的原生会话，可通过 Pi 打开对应会话并加载 pbot 重新关联。存档不保存目录或文件路径。不会导入其他宿主或旧版 pbot 私有会话布局。Pi 分配文件名后，到首条消息写入前，文件可以不存在；扫描静默跳过这类尚未落盘的会话。

原生 JSONL 只读解析。用户输入到无工具调用的最终答复组成问答；回答前的补充输入保留在同一问答。工具调用、工具结果和推理不进入问答。中断或未答记录标为未完成。历史记录缺少完整交互边界时按原生消息顺序重建，不推测隐藏的操作结果。

每条原生分支独立分组，每四个连续节点形成一个摘要，再逐层合并。共同前缀复用节点，摘要不会跨分支合并。会话根节点只做目录，不生成全局摘要；不足四个的尾部节点仍可查询。连续区间与渐进合并的设计参考 [pi-optchat](https://github.com/jonaslsaa/pi-optchat)，实现与提示词由 pbot 自行维护。

主交互正常结束后，在空闲阶段使用当时的 Pi 模型和原生认证串行生成摘要，也补齐已发现的历史。新输入、会话切换或关闭会取消工作；失败节点保留待处理状态，下次正常交互结束再试。加载和查询只收录原文，不启动摘要模型。原文先可查询，已有摘要在追加历史时复用。源文件缺失时继续使用工作区存档；权限、解析等其他读取错误会列出警告，已保存的内容仍可查询。

摘要有额外模型调用。超长输入分段概括后再合并，原文完整保留；摘要失败不妨碍原文查询。后台摘要用量目前不计入 Pi 主会话的用量统计。Pi 原生上下文、压缩和会话恢复继续由宿主管理。

## 存储与实现

工作区内的 `.pi/pbot/history/<id>.json` 保存问答原文、来源消息 ID、节点关系和摘要。来源只保存原生 session ID 与消息 ID，不保存文件路径。目录本身确定工作区归属，不要求新机器的目录名与原机器一致。

复制工作区时包含 `.pi/pbot/history/`，即可在另一台机器搜索和展开已有问答与摘要，继续补齐待生成摘要；原机器的 JSONL 路径不是查询前提。重新发现同一原生会话时复用原节点和摘要。这里分享的是已提取的问答与摘要，Pi 原生 `/resume` 仍需要对应 JSONL；工具日志和图片二进制不在这个存档内。

加载时把当前 Pi agent dir 中旧 `pbot/history/` 下属于当前工作区、且尚未存在于新目录的记录复制过来，保留旧副本，不覆盖新存档。后续收录与摘要写入工作区目录。已有工作区存档在加载时移除旧 file 字段，保留问答、摘要及节点 ID；即使原始会话已不可用，也会完成字段清理。原生 JSONL 不改写，也不移动。

这些文件是可共享的历史资料。原生 JSONL 可读时可以重新提取问答并生成摘要；原始文件已不可用时，删除工作区存档会失去这份历史。

服务位于 services/history，负责分组、查询和摘要队列；integrations/pi/history 负责原生发现、问答提取和模型调用；storage/history-files 复用原子 JSON 写入。命令与工具调用同一服务。首版全文扫描，不维护数据库或向量索引；不保证多个 Pi 进程同时整理同一工作区时只产生一次摘要调用。

本地测试覆盖原文保留、工具过滤、分支分组、全层搜索、分页与重载复用，以及空会话、旧目录复制、跨目录复制、旧路径清理、原始文件缺失和按会话 ID 重新关联。真实摘要质量、按大意回溯的成功率、大历史性能和完整人工浏览尚需验收，见[验证](validation.md)。