# pi-session-mentions

[English](README.md)

在 Pi 消息中引用本机的 Pi、Claude Code 和 Codex 会话。

输入 `@@` 查看最近会话，继续输入关键词即可筛选。用方向键选择，按 Tab
或 Enter 插入，再正常发送消息。多个关键词用引号包住，例如 `@@"构建 缓存"`。

只有发送已选中的引用时才增加模型上下文。

普通 `@` 文件菜单只增加一个 **Sessions** 入口，选中后插入 `@@`。会话使用
独立候选列表，每行显示标题、来源、项目和日期。用方向键可继续滚动查看全部匹配，
文件候选保留原有顺序。

## 安装

需要 Pi 1.2.0 或更高版本，以及 Node.js 22.19.0 或更高版本。通过 npm 安装：

```sh
pi install npm:pi-session-mentions
```

已有 Pi 会话执行 `/reload`。这是全局安装，所有项目都可使用。运行时只依赖
Pi 和 Node.js，不需要安装或运行 `ah`。

## 搜索范围

用简短前缀选择来源：

| 前缀 | 会话来源 |
| --- | --- |
| `@@` 或 `@@all:` | 全部 |
| `@@cc:` | Claude Code |
| `@@cx:` | Codex |
| `@@pi:` | Pi |

前缀后直接输入关键词，例如 `@@cx:cache`、`@@cc:"构建 缓存"`。
输入 `@@:` 可打开 All、CC、CX、Pi 四项来源菜单，按 Tab 或 Enter 填入前缀后，
继续输入关键词，或再按 Tab 浏览该来源的会话。输入 `@@c` 也会提示 CC 和 CX。

匹配标题、用户消息、项目路径和会话 ID，不区分大小写，支持中文。
多个关键词必须全部匹配。优先显示标题匹配的会话，再考虑当前项目和最近活动时间。
排除当前会话及子代理会话。

不索引助手回复、工具输出和思考内容，以减少索引大小及生成文本带来的干扰。

后台线程建立索引并缓存未变化的文件。首次扫描期间，状态栏显示已索引的会话数；
扫描完成后显示候选列表，并清除进度提示。期间可以继续输入。
已有完整缓存时，加载缓存后即可显示结果。后续文件刷新在后台执行，
搜索时最多每 15 秒触发一次。输入时查询内存索引，不调用模型，也不使用向量索引。

搜索耗时取决于索引文本量和匹配数量。后台线程在内存中保留用户文本，
因此内存占用随历史会话量增加。首次无缓存扫描还需要读取源文件。
切换或关闭 Pi 会话时，会停止后台线程并释放索引。

| 来源 | 默认会话目录 | 环境变量 |
| --- | --- | --- |
| Pi | `~/.pi/agent/sessions/` | `PI_CODING_AGENT_DIR`、`PI_CODING_AGENT_SESSION_DIR` |
| Claude Code | `~/.claude/projects/` | `CLAUDE_CONFIG_DIR` |
| Codex | `~/.codex/sessions/`、`~/.codex/archived_sessions/` | `CODEX_HOME` |

使用 Pi 自定义会话目录时，也会纳入当前目录。没有设置面板或额外命令。

## 实际发送的内容

选中会话后，输入框中插入一段带标题的引用。发送时，将其替换为编号引用，
并附上来源工具、项目目录、原始文件路径和精简文本的本地路径。
同一消息多次引用同一个会话，只附加一份说明。

精简文本按 `user:`、`assistant:` 保存对话及来源信息，去除工具调用、工具结果、
图片、系统指令和思考内容。原会话保持不变，每次导出生成独立快照，
原会话后续变化不会改变已经发出的引用。

初始消息只携带引用与路径。模型通过文件工具按需读取精简文本，因此初始 token
成本较低；后续读取对话仍然消耗 token。模型需要可用的本地文件读取工具。

代码块、行内代码及用 `\` 转义的引用保持原样。源文件无法读取时，会在发送的消息
中明确说明。原有图片附件会保留。

Pi 导出采用最后记录的会话分支，Claude Code 按父消息关系读取，Codex 应用已记录的
回退操作。分支中的上游记录缺失时，文本会明确标注历史不完整。若导出期间源文件
发生变化，需要等当前写入完成后重新选择。

## 本地数据

搜索索引保存在 `~/.pi/agent/session-mentions/`，也会遵循
`PI_CODING_AGENT_DIR`。文本快照保存在 `/tmp/pi-sessions-mentions/`。
两者都包含私有对话文本，目录和文件仅允许当前用户访问。搜索不会将数据发送到
独立服务；模型读取引用后，相关文本仍可能发送到模型提供商。这个扩展不负责敏感信息脱敏。

每次发送会话引用都会重新生成文本快照，同一条消息多次引用同一会话时共用一份。
删除搜索索引后会自动重建。临时快照被手动删除或系统清理后，旧消息中的文件路径
将无法读取；重新选择并发送会话即可生成新的快照。原始会话文件不会被修改。

## 开发

在仓库根目录执行：

```sh
npm install
npm run check --workspace pi-session-mentions
```

MIT 许可证，见 [LICENSE](LICENSE)。