# pi-calm

让 [Pi](https://github.com/badlogic/pi-mono) 工作时更清爽、更容易跟进。

English | [简体中文](README.zh-CN.md)

**pi-calm** 保留对话内容和 `Working...` 状态，同时把工具执行噪音和可选的思考内容安静地收起来。它只改变终端展示，不会改变工具执行、模型上下文或 session 数据。

## 保留什么，隐藏什么

Calm **默认开启**：

| 保留显示 | 收起（仅展示层） |
| --- | --- |
| 用户真实提示 | 思考 / CoT 区块（`/calm thinking` 可显示） |
| 助手真实文本 | 常规工具执行噪音（内置工具与自定义工具） |
| 交付型关键工具（`plan_mode_complete`, `PI_CALM_VISIBLE_TOOLS`） | 带 `U+2063` envelope 的操作型用户行 |
| Pi 原生 `Working...` 行 | |

隐藏内容仍会保存在 session 中，关闭 Calm 后会恢复显示。

## 安装

### GitHub

```sh
pi install git:github.com/JesseZhang97/pi-calm
```

### npm

```sh
pi install npm:pi-calm
```

### 本地路径

```sh
pi install /path/to/calm-mode
```

本包包含 `pi-package` keyword 和 `pi` manifest，可以被 Pi package gallery/index 发现。

安装后重启 Pi，或执行 `/reload`。

## 使用

```text
/calm on              # 开启 Calm，隐藏思考
/calm thinking        # 保持 Calm，切换思考 / CoT 显示
/calm off             # 关闭 Calm，恢复普通 transcript
```

只有这三个命令。输入 `/calm ` 后，Pi 会提供参数补全。

`Working...` 始终保持显示，扩展加载后不能被关闭。

## 偏好设置

默认保存于：

```text
~/.pi/agent/calm
```

| 文件内容 | 含义 |
| --- | --- |
| `on` | Calm 开启，隐藏思考（默认） |
| `on thinking` | Calm 开启，显示思考 / CoT |
| `off` | Calm 关闭 |

可通过 `PI_CALM_PREFERENCE_PATH` 覆盖保存路径。

## 交付型工具白名单

Calm 默认收起过程型的工具噪音（`read`, `bash`, `edit` 等），但对于结果即为最终交付物的工具，保留在 transcript 中完整呈现：

- **`plan_mode_complete`**：默认放行，确保 [`pi-plan-mode`](https://github.com/narumitw/pi-plan-mode) 生成的计划 Markdown 在终端中清晰可读。
- **`PI_CALM_VISIBLE_TOOLS`**：可通过此环境变量配置需要额外放行的工具名列表（逗号分隔）：

```sh
export PI_CALM_VISIBLE_TOOLS="generate_report,review_summary"
```

## 展示范围

Calm 使用 Pi 的展示层 seam：

- 绝大多数 `ToolExecutionComponent` 工具行都会隐藏，包括任意第三方 custom tools
- 交付型关键工具（如 `pi-plan-mode` 的 `plan_mode_complete`，以及通过 `PI_CALM_VISIBLE_TOOLS` 环境变量指定的工具）会保留正常显示
- custom messages 和 custom entries 仍然显示
- compaction / branch summary 仍然显示
- `!` / `!!` 用户 bash 行仍然显示
- `/export` 和 `/share` 序列化时会临时恢复标准展示

隐藏只影响终端展示，不会删除 session 数据。

## 开发验证

```sh
node --experimental-strip-types tests/self-check.ts
```

## License

MIT