# pi-blackbox

[English](README.md)

`pi-blackbox` 会记录当前 Pi 会话中由模型发起的每一条工具调用，在 Pi footer 中显示实时数量，并提供交互式 `/blackbox` 检视器。

## 功能

- 统计每个 `tool_call` 事件，包括 `read`、`write`、`edit`、`bash` 等内置工具，以及其他扩展注册的工具。
- 在恢复会话、fork 或切换会话树节点后，从当前分支重新构建工具调用记录。
- 通过 Pi 原生 `ctx.ui.setStatus()` 数据源发布键为 `blackbox`、值为 `<数量> tool calls` 的扩展状态，并以相同的 dim 颜色显示在原生统计行。
- 输入 `/blackbox` 后打开与终端等高、顶栏和快捷键栏固定的检视器；按 Enter 可从参数开头展开所选调用的完整参数。
- 可将所选调用发送给当前会话的主模型，并使用配置的语言进行简短解释，不会向对话追加消息。
- 首次启动时从操作系统检测中文或英文，并将结果持久化到 `~/.pi/agent/extensions/blackbox.json`。

## 安装

作为已发布的 Pi package 安装：

```bash
pi install npm:pi-blackbox
```

本地开发时运行：

```bash
pi install ./pi-blackbox
```

也可以不安装，直接试用：

```bash
pi -e ./pi-blackbox/src/index.ts
```

安装或修改扩展后，可以在已有 Pi 会话中执行 `/reload`。

## 使用

输入 `/blackbox` 后，最新的工具调用默认显示在最上面，顶栏会标明当前顺序。可以使用以下按键：

| 按键 | 操作 |
| --- | --- |
| `↑` / `↓` | 选择工具调用 |
| `j` / `k` | 向下/向上移动；当所选展开项高于视口时逐行滚动 |
| `Enter` | 展开或收起完整参数 |
| `e` | 调用当前 Pi 主模型解释实际效果 |
| `r` | 在最新优先和最早优先之间翻转顺序 |
| `q`、`Esc` 或 `Ctrl+C` | 关闭视图 |

解释 prompt 要求模型简短、精确地说明调用会读取、修改、创建、删除、执行或影响什么；禁止实际执行和无依据猜测，只允许在调用复杂时给出简短示例。所选工具名和参数会被发送给当前选中的模型。

执行 `/blackbox-explain-language` 可以选择自动检测、常用语言，或者选择 Other 后输入任意语言名称。选择结果会持久化到 `~/.pi/agent/extensions/blackbox.json`：

```json
{
  "explainLanguage": "Chinese"
}
```

首次启动时，macOS 读取 `AppleLanguages`，Linux 读取 `LC_ALL` / `LC_MESSAGES` / `LANG`，Windows 优先读取当前用户的首选语言列表，然后依次尝试 PowerShell 7（`pwsh.exe`）、Windows PowerShell 和终端 locale 环境变量；平台专用来源不可用时回退到 `Intl`。自动检测遇到中文 locale 时选择中文，否则选择英文。选择 Auto-detect 会重新检测并保存结果。

## 配合 pi-powerline-footer

Pi 默认 footer 会把计数直接显示在 token/context 统计之后，而不是另起一行。要让同一个 `blackbox` 状态成为 `pi-powerline-footer` 的独立 segment，请把下面配置合并到 `~/.pi/agent/settings.json`（或当前项目的 `.pi/settings.json`）：

```json
{
  "powerline": {
    "preset": "default",
    "customItems": [
      {
        "id": "blackbox",
        "statusKey": "blackbox",
        "position": "right",
        "color": "accent",
        "hideWhenMissing": true,
        "excludeFromExtensionStatuses": true
      }
    ]
  }
}
```

最终显示值仍严格为 `<数量> tool calls`，不会增加前缀。`hideWhenMissing` 会在 `pi-blackbox` 未加载时隐藏该项，`excludeFromExtensionStatuses` 则避免它同时出现在聚合的扩展状态 segment 中。

如果你已经配置了 `powerline.customItems`，请把上面的对象追加到现有数组，不要覆盖数组。编辑配置后重启 Pi 或执行 `/reload`。

## 开发

```bash
npm install
npm run verify
```