# pi-session-tools

Pi 会话辅助扩展包，默认加载 bash 管道输出缓存和对话压缩。

[English](./README.md)

## 安装

```bash
pi install npm:pi-session-tools
```

随后执行 `/reload`。

## 功能

- 当 bash 管道中使用 `grep`、`tail` 或 `head` 过滤输出时，将过滤前的完整输出写入系统临时目录下的 `pi-pipe-cache/`，并在结果中给出路径，可以直接对缓存文件重新过滤而不用重跑命令。
- 提供 `session_log`：按原索引列出 active branch 的用户消息和可选起点。已经作为压缩起点保留的 user anchor 仍可重复选择，从而把上次快照之后新增的自动续接内容折叠进下一份快照；原分支仍可通过 `/tree` 找回。
- 提供 `session_squash`：接收总结和接续模式，并把从指定消息开始的对话压缩为该总结。原对话不删，可通过 Pi 的 `/tree` 找回。生成的快照消息默认收起成一行（`▸ 压缩快照 · 从 #N 起 · 压缩前 X tokens`），按 `Ctrl+O` 或点击这一行展开完整快照；这样压缩前的最后一条回答不会被一份长快照顶出屏幕。展开时只显示任务状态正文，不显示只给接手模型看的指令段。
- 总结由主 agent 基于完整对话上下文生成，并直接随 `session_squash` 调用提交（不发独立 LLM 请求，也没有 finalize 步骤）；被压缩范围内修改过的文件会自动附上，读取过的文件不会批量复制到快照。

调用 `session_squash` 前先调用 `session_log`，用已完成回合的编号作为 `from`，并把完整任务状态快照传给 `session_squash`。summary 支持自由格式，不会因缺少标题、章节或 `User`/`Agent` 时间线而拒绝压缩；如需便于接手，可以按 `# Handoff: <topic>`、`Timeline of user and agent work`、`Current focus`、`Errors and resolutions`、`Code and artifact state`、`Environment and repository state`、`Completed work and decisions`、`Active issues and next actions`、`Important context and boundaries` 和 `Suggested skills` 组织。若未提供标题或时间线，扩展会自动补齐一份标题或紧凑事实时间线；自动时间线只保留 User 与 Agent 的文本，不记录工具调用或工具结果。选中的 user turn 会作为新分支锚点保留，以维持后续 user turn 索引稳定；任务状态快照作为被压缩后缀的权威状态，并在下一轮模型上下文中以 Pi 原生 compaction summary 语义呈现，明确告知接手 Agent 从快照继续。该锚点会继续出现在后续 `session_log` 中，可重复选择，从而让新快照吸收“上次快照之后、下一条 user turn 之前”的自动续接内容；也可以从更早索引重新压缩更大范围。

任务或阶段到达安全停点时都可以压缩，例如阶段完成、验证完成、关键决策落定或准备进入下一阶段；无需等整个任务交付。摘要重点说明被压缩范围内做了什么、作用对象、最终结果和验证，并明确当前准确停点、剩余事项、制品状态和下一步。已完成工作不得重复列入剩余事项；必要时使用 `VERIFIED`、`INFERRED`、`UNKNOWN`、`NOT VERIFIED` 或 `BLOCKED`。摘要只保留有效任务状态，不记录上下文阈值、`session_log`、`session_squash` 或会话切换等维护过程。每次压缩都必须显式选择接续模式：仍有可立即执行的工作时使用 `continuation: "auto"`；当前任务已完成且下一步必须等待用户新输入时使用 `continuation: "next-user"`，只保存快照而不额外触发模型回合。若摘要与 workspace、Git 或测试证据冲突，以实际证据为准并报告冲突。

## 上下文阈值提示

对话变长跨过阈值时（默认 150k / 200k / 250k / 300k tokens），会向主 agent 显示“已用 tokens / context window（占比）”，并提醒它在最近的任务或阶段安全停点压缩，不必等待整个任务结束。提醒不强制；仅在模型正常停止时触发，用户手动终止或提供方异常不会触发。可配置：

```jsonc
// ~/.pi/agent/extensions/pi-session-tools/config.json
{ "squashContextThresholds": ["150k", "200k", "75%"] }   // k、数字与百分比可混合
```

也可用交互式命令 `/config:session-tools`（别名 `/pi-session-tools`）配置。

也支持环境变量 `PI_SESSION_TOOLS_SQUASH_THRESHOLDS`（逗号分隔，如 `150k,75%`）。

## 强制压缩

强制压缩默认关闭。在同一个配置文件中设置 `0` 到 `1` 的 JSON 数字，表示模型上下文窗口占比：

```jsonc
{
  "squashContextThresholds": ["150k", "200k", "75%"],
  "forceSquashContextThreshold": 0.9 // 表示上下文窗口的 90%；null 表示关闭
}
```

也可执行 `/config:session-tools force 0.9`；使用 `/config:session-tools force off` 关闭。强制压缩不再接受 `"90%"` 这类百分比字符串。

每个 assistant 工具批执行完成后，扩展都会检查上下文用量。达到强制阈值时，会在下一次模型调用前中止当前 agent loop，保存原活动工具集合，并只开放 `session_log` 和 `session_squash`；其他工具调用会被阻止。如果 agent 停止但没有压缩，扩展会自动再次触发强制回合，限制持续到 `session_squash` 成功。成功后恢复原工具并基于摘要继续。已经开始执行的工具会先完成，避免文件修改停在半完成状态。

## 本地化

全部用户可见文案通过 `pi-extensions-i18n` 提供中英双语（zh-CN / en-US）。