# pi-tools-info

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

一个用于 [Pi](https://github.com/earendil-works/pi) 的工具查看扩展，通过 `/tools-info` 查看当前会话已注册工具的暴露方式、激活状态、来源和完整描述。

## 安装

```bash
pi install npm:@jy02414216/pi-tools-info
```

临时试用而不写入 Pi 设置：

```bash
pi -e npm:@jy02414216/pi-tools-info
```

卸载：

```bash
pi remove npm:@jy02414216/pi-tools-info
```

## 本地开发

从仓库根目录临时加载，不修改 Pi 设置：

```bash
pi -e ./packages/pi-tools-info
```

修改已加载的扩展后，可以在 Pi 中执行 `/reload` 重新加载。基于 Pi 0.99.1 开发；开发测试使用 Node.js 24 或更新版本：

```bash
npm test --workspace @jy02414216/pi-tools-info
```

## 功能

- 按工具名列出当前会话已注册的工具，包括未激活和隐藏的工具。
- 通过关键词、激活状态和暴露方式组合筛选，支持命令参数补全。
- 打开工具详情，查看完整描述、来源、namespace 和行为提示。
- 只读展示，不执行工具、不修改工具状态，也不向模型发送消息。

## 工具查看

在 Pi 中输入：

```text
/tools-info
```

界面提示统一使用英文，仅支持交互式 TUI。列表和详情显示在终端底部的临时浮层中，关闭后恢复原界面，不加入会话记录或模型上下文。

列表示例（示意数据）：

```text
Tools · Registered: 3 · Active: 2
  Tool                         Exposure    Active  Source
> ask_user                     model-only  Yes     npm:@example/pi-ask…
  mcp__github__search_code      deferred    No      builtin:mcp
  read                         direct      Yes     builtin:read
Esc/q Close · Enter Details · ↑↓/jk Select · PgUp/PgDn Page · 1-3/3
```

列表按工具名排序，区分大小写，不采用自然数字排序。长名称和来源以 `…` 截断；详情显示完整内容。窗口较窄时隐藏来源列，空间不足时提示调整窗口。

默认快捷键：

| 按键 | 列表 | 详情 |
| --- | --- | --- |
| `↑` / `k`、`↓` / `j` | 选择工具 | 滚动内容 |
| `PageUp` / `PageDown` | 按页移动 | 按页滚动 |
| `Enter` | 打开详情 | — |
| `Esc` / `q` | 关闭面板 | 返回列表，保留选中项和位置 |
| `Ctrl+C` | 关闭面板 | 关闭面板 |

导航、确认和取消快捷键遵循 Pi 的 `tui.select.*` 配置；`q` 固定用于返回或关闭，详情中的 `Esc` 固定返回列表。

### 搜索与过滤

```text
/tools-info [关键词...] [--active | --inactive] [--exposure <值>]
```

常用示例：

```text
/tools-info github search
/tools-info --active
/tools-info --exposure deferred
/tools-info github --inactive --exposure direct
```

- **关键词**：按空白分词，忽略大小写，在完整工具名、描述、namespace 名称、来源名称和路径中进行包含匹配；多个词取 AND，可以分别命中不同字段。不搜索参数 Schema 或 annotations，不支持正则、模糊匹配、引号短语和转义。
- **激活状态**：`--active` 只显示已激活工具，`--inactive` 只显示未激活工具；两者互斥，省略时不限制状态。
- **暴露方式**：`--exposure <值>` 精确匹配 `direct`、`model-only`、`codemode`、`deferred` 或 `hidden`，值使用小写；省略时不限制暴露方式。

三个条件取交集，参数与关键词顺序不限。`--exposure` 的值必须紧跟参数，以空白分隔，不支持 `--exposure=direct`。重复相同参数值不影响结果；未知选项、缺值、非法值或冲突值会报错并显示用法。

可按 `Tab` 补全选项和 exposure 值。例如，`--ex` 补全为 `--exposure `，随后输入 `d` 可选择 `direct` 或 `deferred`。补全保留已有关键词和参数，并根据光标前的内容隐藏已选或冲突选项；不补全工具名和搜索关键词。

### 工具详情

选择工具后按 `Enter`，查看完整名称、暴露方式、激活状态和描述，以及：

- 来源的 `source`、`path`、`scope`、`origin` 和 `baseDir`。
- namespace 的名称与描述。
- `readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint` 四项行为提示。

描述按纯文本显示，保留换行，不执行其中的指令。行为提示按原值展示，未声明时显示 `Not declared`，不会当作 `false`；这些提示未经验证，不是安全保证。

### 结果说明

- **Registered**：当前已注册工具总数。尚未注册的工具不会出现，例如 MCP 尚未连接成功；服务器状态请查看 `/mcp`。
- **Active**：处于当前激活集合中的工具数，不等于可调用工具数。其他扩展也可能调整最终发给模型的工具声明。
- **Shown**：使用搜索或过滤时显示的匹配数。`Registered` 和 `Active` 始终是整个快照的总数，不受过滤影响。

| 暴露方式 | 含义 |
| --- | --- |
| `direct` | 激活时向模型声明，并可被其他工具调用 |
| `model-only` | 激活时向模型声明，但不能被其他工具调用 |
| `codemode` | 注册后可被其他工具调用，也可显式激活 |
| `deferred` | 注册后可被其他工具调用，不在 codemode 常规列表中展示；可搜索并激活 |
| `hidden` | 已注册，但不可调用 |

**未激活不等于不可调用**：`codemode` 和 `deferred` 不依赖激活状态即可被其他工具调用。这里显示的是运行时暴露方式，MCP 配置的 `codemode-deferred` 对应 `deferred`。

无匹配结果时显示 `No matching tools.`；会话没有已注册工具时显示 `No tools registered.`。未知暴露方式保留原值，不猜测为 `direct`。

### 性能与隐私

- 只在打开面板时读取 `pi.getAllTools()` 和 `pi.getActiveTools()`；列表与详情使用同一份快照，查看期间不自动刷新。
- 加载和参数补全阶段不读取工具注册表，不启动计时器或后台任务。
- 不调用工具、不修改配置或激活状态、不主动连接 MCP，也不写入 Session 或发送模型请求。
- 工具元数据按纯文本展示，并清理终端控制序列。来源路径可能包含本地用户名，分享截图时请注意隐私。

## License

[MIT](./LICENSE)