# pi-collapse-failed-attempt

[English](README.md)

一个用于 Pi 的扩展：当 assistant 的流式响应因错误中断时，将已经显示的部分输出折叠起来，避免重试时对话区出现重复内容。

当 Pi 收到错误终止的流式响应时，可能会自动重试请求。如果没有本扩展，已经流出的部分回答会继续完整显示，并与重试后的新回答并列出现。本扩展会将这次失败尝试收起为一行，同时保留原始输出供需要时查看。

## 功能

- 折叠错误终止的 assistant 文本和 thinking 内容；
- 保留 Pi 原有的自动重试和 session 行为；
- 将失败输出保存在仅供 TUI 显示的 session entry 中；
- 不会把捕获的失败输出重新发送给模型；
- 使用 Pi 现有的输出展开快捷键，通常是 `Ctrl+O`；
- 如果错误发生在模型尚未输出文本或 thinking 之前，则保持 Pi 原本的错误显示。

## 要求

- 支持扩展和 package 的 [Pi coding agent](https://github.com/earendil-works/pi)；
- Pi 版本提供以下扩展 API：`message_end`、`registerEntryRenderer` 和 `appendEntry`。

## 安装

从 npm 安装：

```bash
pi install npm:pi-collapse-failed-attempt
```

也可以直接从 GitHub 安装：

```bash
pi install git:github.com/joshua-zyy/pi-collapse-failed-attempt
```

默认安装到用户级 Pi 配置。如果只希望当前项目使用，可以对任一来源执行项目级安装：

```bash
pi install -l npm:pi-collapse-failed-attempt
# 或
pi install -l git:github.com/joshua-zyy/pi-collapse-failed-attempt
```

安装后重启 Pi，或者在已有会话中执行：

```text
/reload
```

卸载：

```bash
pi remove npm:pi-collapse-failed-attempt
```

如果之前是从 GitHub 安装的，则执行：

```bash
pi remove git:github.com/joshua-zyy/pi-collapse-failed-attempt
```

## 使用方式

不需要额外配置。安装后，扩展会自动在交互式 TUI 会话中生效。

当响应已经产生部分内容后发生错误，终端中会显示类似下面的折叠行：

```text
↻ Failed response (Ctrl+O to expand partial output)
```

使用 Pi 当前配置的输出展开快捷键即可查看或隐藏原始部分输出。快捷键提示由 Pi 动态生成，因此会遵循用户自定义的 keybinding 配置。

## 工作原理

扩展监听最终确定的 assistant 消息，并检查：

```ts
stopReason === "error"
```

如果消息包含文本或 thinking 内容，扩展会：

1. 将这些内容保存为 custom session entry；
2. 将原 assistant 消息中可见的正文替换为空；
3. 使用可展开的紧凑行渲染这个 custom entry。

扩展不会修改 Pi 的自动重试策略、重试次数、退避时间、provider 请求或模型上下文处理逻辑。

## 限制

Pi 当前公开的扩展事件不会直接告诉扩展某个 assistant 错误是否一定会自动重试。因此，本扩展会折叠所有包含部分输出的 assistant error 响应，包括不可重试的错误，以及重试次数耗尽后的最终错误。

错误摘要仍然可见，捕获的部分输出也可以展开查看。对于完全没有产生文本或 thinking 内容的错误，扩展不会替换 Pi 原本的错误信息。

本扩展面向 Pi 的交互式 TUI，不会为 print 或 JSON 输出模式提供自定义渲染器。

## 开发

克隆仓库后，可以通过 Pi 自己的扩展加载环境运行。扩展没有额外的运行时依赖；Pi 会提供所需的核心 package。

从仓库根目录验证扩展加载：

```bash
pi --offline -e ./extensions/index.ts --list-models
```

仓库中的 `types/` 目录包含开发期类型声明，使编辑器可以在不向仓库安装 Pi 运行时 package 的情况下检查扩展代码。

## 贡献与反馈

欢迎提交 Issue 和 Pull Request。报告问题时，建议提供：

- Pi 版本；
- provider 和模型；
- 该响应是否触发了自动重试；
- 相关的 session 表现；
- 如果是 UI 问题，请提供终端和操作系统信息。

## 许可证

MIT