# pi-session-resources

面向 [Pi 编码助手](https://github.com/earendil-works/pi) 的被动会话资源引用扩展。它从成功的工具活动中收集文件、网页和 PR/MR；在输入框键入 `#` 时，在编辑器上方打开带类型 Tab 的资源选择器。

[English](./README.md)

## 功能

- 跟踪内置工具和自定义工具读取、修改、检查或打开的文件。
- 跟踪结构化 HTTP(S) URL 字段，以及浏览器、shell、MR/PR 创建工具输出的链接。
- 识别 GitHub Pull Request 与 GitLab Merge Request，并标记 `gh pr create`、`glab mr create` 等创建动作。
- 在 reload、resume、fork 或 `/tree` 导航后，从当前会话分支重建状态；不会向模型上下文写入跟踪条目。
- 只在键入 `#` 时显示圆角高亮边框的资源选择器，不保留常驻面板；面板随终端窗口匹配编辑器宽度，文件、PR/MR、URL 按 Tab 分开。
- 按资源标签、目标、类型、动作和来源工具模糊筛选最近资源；边框、选中箭头和选中资源名称复用 subagent 组件固定的 `#4DA3FF` 强调色，选中名称加粗，动作信息保持弱化。
- 候选标签使用 OSC 8 超链接：文件使用 `file://`，网页和 PR/MR 保留原 URL。
- Pi fullscreen 模式下在输入框上方显示一行 `查看资源` 按钮，后面跟着各类型的计数；点击计数可以直接打开对应 Tab，打开后可以完全用鼠标切换 Tab、查看高亮、点 `✕` 关闭和打开资源。
- 通过 `pi-extensions-i18n` 提供 `zh-CN` 和 `en-US` 文案。

## 使用

在输入框中的词边界键入 `#`，或点击 fullscreen 模式下的资源按钮：

```text
╭─ 会话资源 ─────────────────────────────────────────────╮
│  FILE 8   PR/MR 2   URL 3                              │
├────────────────────────────────────────────────────────┤
│ → src/index.ts                               修改 · 读取 │
│   tests/index.test.ts                               修改 │
├────────────────────────────────────────────────────────┤
│ ←/→ 或 Tab/Shift+Tab 切换类型 · ↑/↓ 选择 · Enter 插入 │
╰────────────────────────────────────────────────────────╯
请检查 #ind
```

- 继续在 `#` 后输入可实时筛选当前类型。
- 选择器打开时，←/→ 切换资源类型；Tab 切换到下一个类型，Shift+Tab 切换到上一个类型。
- ↑/↓ 循环选择当前类型中的资源。
- Enter 插入当前引用，Esc 关闭选择器并保留已输入文本。
- 当前类型每次最多显示 6 个最近匹配资源。

文件引用使用会话中的显示路径，例如 `#src/index.ts`；含空格的路径会插入为 `#"docs/design notes.md"`。网页和 PR/MR 会插入完整 URL。引用只是普通提示文本，不会额外读取文件或向会话写入隐藏上下文。

候选标签是 OSC 8 超链接，且整行都是链接目标；不支持 OSC 8 的终端仍会显示可读标签。

## 鼠标浏览（fullscreen）

Pi 只在 fullscreen 模式把鼠标事件交给组件，所以需要用 `pi --tui-mode fullscreen` 启动，或在 settings 中配置 `"tuiMode": "fullscreen"`。只有已经收集到资源时才会显示按钮：

```text
 查看资源 FILE 3 · PR/MR 1 · URL 2
╭─ 会话资源 ────────────────────────────────────────── ✕ ─╮
│  FILE 8   PR/MR 2   URL 3                               │
├─────────────────────────────────────────────────────────┤
│ → src/index.ts                                修改 · 读取 │
│   tests/index.test.ts                                修改 │
├─────────────────────────────────────────────────────────┤
│ ←/→ 类型 · ↑/↓ 选择 · 点击打开 · ✕ 关闭          3/8   │
╰─────────────────────────────────────────────────────────╯
```

- 点击「查看资源」即可打开面板，不需要先键入 `#`。这种打开方式没有查询词，因此再输入字符会回到输入框，而不是继续筛选。
- 直接点击后面的计数块（比如 `PR/MR 1`）会直接打开到对应的 Tab，不用先打开面板再手动切换。
- 点击提示行末尾的 `✕ 关闭` 可以关闭面板；这段文字本身就是点击区，效果和按 Esc 一样。
- Enter 仍然可以插入当前引用，键盘和鼠标可以混用。
- 点击 Tab 切换资源类型；鼠标悬停时按钮、计数块、Tab 和资源行会高亮。
- 点击资源行会打开资源，效果与 Cmd+click 点击 OSC 8 链接一致：Pi 的 fullscreen 渲染器会对被点中的链接调用自带的打开器。
- 单个类型超出面板行数时，用 ↑/↓ 滚动列表，提示行右侧会显示当前位置（`3/8`）。
- 在选择器里拖拽仍然可以选择文本，滚轮仍然滚动会话内容，头部区域不拦截滚轮。
- Esc 关闭面板；原来的 `#` 流程保持不变。

按钮和鼠标处理需要支持组件鼠标 API 的 Pi 版本（`@earendil-works/pi-tui` 0.85 及以上）。旧版本不会渲染按钮，仍然只有键盘 `#` 选择器。

## 命令

```text
/config:session-resources             显示 # 引用使用提示
/config:session-resources enable      启用 # 资源选择器
/config:session-resources disable     禁用 # 资源选择器
```

`show`/`hide` 分别兼容 `enable`/`disable`，`/session-resources` 继续作为命令别名保留。配置保存在 `<Pi agent 目录>/extensions/pi-session-resources/config.json`，可参考 [`config.example.json`](./config.example.json)：

```json
{
  "enabled": true
}
```

使用 `/config:session-resources enable|disable` 会写入配置文件；手动修改文件后执行 `/reload`。

## 安装

```bash
pi install npm:pi-session-resources
```

然后在 Pi 中执行 `/reload`。

## 识别方式

扩展监听 Pi 原生 `tool_result` 事件，只记录成功调用。

- 内置 `read`、`write`、`edit`、`grep`、`find`、`ls` 会得到准确的动作标签。
- 自定义工具通过 `path`、`filePath`、`files`、`directory`、`outputPath` 等常见路径字段识别文件。
- 会递归提取结构化 URL/路径字段；shell、浏览器和 MR/PR 创建工具还支持纯文本 URL 输出。
- 浏览器打开和 MR/PR 创建动作会根据工具名与命令文本做保守推断。
- 不会从文件正文和普通描述中宽泛抓取 URL 或路径，避免读取 README 或源码后被无关链接刷满候选。

扩展不会把任意 shell 命令中的相对路径当作 shell 语法解析。内置文件工具、结构化自定义工具路径字段、绝对路径和 URL 可以可靠跟踪；这一限制可以避免把普通命令文本误判成文件。

## 隐私与可移植性

本包不发起网络请求，也不启动后台进程。收集状态只保存在内存中，并从当前 Pi 会话分支重建；来源数据本来就存在于工具调用和结果中。显示标签会省略 URL 查询参数，但插入引用和 OSC 8 点击目标保留原始 URL。