# pi-lean-grep

[English README](README.md)

一个给 pi 内置 `grep` 做**轻量优化**的 extension。

> 在真实测试里，`pi-lean-grep` 不只是更省 token，也能明显压低当前上下文负担。

它的定位很简单：
- 不重写 grep
- 不搞复杂策略引擎
- 尽量保留原生用法
- 只对最容易浪费 token 的地方做轻量约束

---

## 真实效果

测试模型：**GPT-5.4 mini**

| 实验 | 插件 | 累计 Input | Cost | Context 占比 |
|---|---|---:|---:|---:|
| 1 | 无插件 | 4.2k | $0.003 | 1.0% |
| 1 | 有插件 | 2.7k | $0.002 | 0.5% |
| 2 | 无插件 | 7.3k | $0.006 | 2.2% |
| 2 | 有插件 | 2.4k | $0.002 | 0.4% |

可以直接看出两件事：

1. **累计成本下降了**
   - 例如实验 2：`7.3k -> 2.4k`
2. **当前上下文占比也下降了**
   - 例如实验 2：`2.2% -> 0.4%`

> 这里的 `Input / Cost` 是累计 usage，`Context 占比` 是 footer 的当前快照。前者更像账单，后者更像当前上下文负担。

---

## 它做了什么

`pi-lean-grep` 只做 3 件事：

| 机制 | 行为 | 作用 |
|---|---|---|
| 默认 `limit` | 未传 `limit` 时自动补成 `20` | 防止默认回太多条 |
| 宽搜索 + `context` 约束 | 对明显宽泛且带 `context` 的搜索返回提示，不直接放大结果 | 避免 grep 变成批量阅读工具 |
| 大结果摘要 | 结果太大时返回 summary，而不是整坨低密度文本 | 减少上下文污染 |

一句话：

> **默认少回一点，宽搜索别轻易放大，太大的结果先压缩。**

---

## 它没有做什么

为了尽量轻改动，这个插件**刻意不做**很多重型事情：

- 不重写 grep 搜索内核
- 不改变 regex / literal 的真实匹配语义
- 不改工具名
- 不改参数 schema
- 不搞复杂策略引擎

也就是说：

> **它优化的是 grep 的使用成本，不是 grep 的搜索能力。**

---

## 加载后，AI 实际看到哪些变化？

我们只改了 `grep` 的两类提示信息。

### 1) description
**内置 grep：**
```text
Search file contents for a pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Output is truncated to 100 matches or 50KB (whichever is hit first). Long lines are truncated to 500 chars.
```

**pi-lean-grep：**
```text
Search file contents for a pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Large results may be limited or summarized, and broad searches with context may be refused to avoid large noisy result sets.
```

### 2) 1 条新增 guideline
这条会进入 pi 系统提示里的 `Guidelines:` 段落：

```text
Use grep to locate candidate files or lines first. Use read when surrounding code is needed. Avoid broad grep searches with context.
```

### 没改的东西
这些都没动：
- 工具名：`grep`
- 参数 schema
- `promptSnippet`
- grep 底层搜索实现

---

## 安装

### 从 npm 安装
```bash
pi install npm:pi-lean-grep
```

### 仅安装到当前项目
```bash
pi install -l npm:pi-lean-grep
```

### 临时加载
```bash
pi -e npm:pi-lean-grep
```

### 本地开发时加载
```bash
pi -e ./pi-lean-grep
```

### 减少额外噪音的测试方式
```bash
pi -e ./pi-lean-grep --tools grep --no-skills --no-prompt-templates --no-context-files
```

### 作为项目本地 extension
放到：
```text
.pi/extensions/pi-lean-grep/index.ts
```

---

## 测试

```bash
npm test
```

当前自动化覆盖：
- 精确 grep 在显式 limit 下保持正常结果
- 未传 `limit` 时默认落到 `20`
- 宽搜索 + `context` 返回约束提示

---

## 当前 v1 的取舍

这个版本不是追求“最聪明”，而是追求：

- 简单
- 可控
- 对原生 grep 干扰尽量小

如果你想要的是：
- 少烧 token
- 少污染上下文
- 让 AI 先定位、再细读

那它会很有用。

如果你想要的是：
- 每次都尽量拿到 grep 原始全文

那它会显得偏保守——这是有意设计的。