为 Pi coding agent 提供纯算法化的会话压缩，无需 LLM 调用 https://t.co/TGcpQ9VQ1f

sting8k/pi-vcc

来源：https://github.com/sting8k/pi-vcc

pi-vcc

npm (https://www.npmjs.com/package/@sting8k/pi-vcc)
用于 Pi (https://github.com/badlogic/pi-mono) 的算法化会话压缩器。无需 LLM 调用——通过提取和格式化生成简洁的对话记录。灵感来源于 VCC (https://github.com/lllyasviel/VCC) （面向视角的会话编译器）。

演示

pi-vcc 演示

为什么选择 pi-vcc

真实会话指标

在 ~/.pi/agent/sessions 下的真实会话 JSONL 上测量（字符数 = 渲染的消息文本）。

特性

• 无需 LLM——纯算法，零额外 API 成本
• 简洁对话记录——按时间顺序展示对话流程，每个工具调用折叠为单行并附 (#N) 引用，文本截断保持紧凑
• 5 个语义 section——会话目标、文件与变更、提交、未完成上下文、用户偏好
• 有界合并——滚动 section 在合并后重新汇总，而非无限增长
• 无损召回——vcc_recall 直接读取原始会话 JSONL，因此在多次压缩后 active lineage 历史仍可搜索
• 作用域搜索——默认搜索 active lineage；使用 scope:"all" / scope:all 可有意搜索所有 lineage
• 正则搜索——vcc_recall 支持正则模式（hook|inject、fail.*build）以及按 OR 排序的多词查询
• 结果排序——搜索结果按词项相关性排序，罕见词权重高于常见词
• /pi-vcc-recall——斜杠命令直接搜索历史，结果以可折叠消息显示并自动馈送给 agent 作为上下文
• 后备截断——当 Pi 核心未返回任何可摘要内容时仍能工作
• /pi-vcc——按需手动压缩

安装

pi install npm:@sting8k/pi-vcc

或从 GitHub 安装：

pi install https://github.com/sting8k/pi-vcc

或尝试不安装直接运行：

pi -e https://github.com/sting8k/pi-vcc

使用

安装后，pi-vcc 会注册一个 session_before_compact 钩子。

• 运行 /pi-vcc 手动触发 pi-vcc 压缩。
• 可选保留语法：/pi-vcc keep:3 或 /pi-vcc keep:3。
• keep:1 等同于默认行为。
• keep:0 压缩所有内容，不留尾部。
• 默认情况下，/compact 和自动阈值压缩仍通过 Pi 核心（基于 LLM）处理。在配置中设置 overrideDefaultCompaction: true 可让 pi-vcc 处理所有压缩路径。
• 压缩后要搜索较旧的 active lineage 历史，请使用 vcc_recall。
• 要有意搜索所有 lineage，请向 vcc_recall 传递 scope:"all" 或运行 /pi-vcc-recall scope:all。
• 要自行搜索并将结果馈送给 agent，请运行 /pi-vcc-recall [page:N]。
• 提示：输入 /recall，Pi 会自动补全为 /pi-vcc-recall。

压缩工作原理

Pi 默认在最后一条用户消息处拆分会话。之后的部分——保留尾部——保持完整且不受影响。
使用 keep:N 时，pi-vcc 会保留该尾部中最后 N 条用户交互，并汇总切割点之前的所有内容。如果指定 keep:0，则压缩所有内容，不留尾部。

压缩后消息结构

[Session Goal]
- Fix the authentication bug in login flow
- [Scope change]
- Also update the session token refresh logic

[Files And Changes]
- Modified: src/auth/session.ts
- Created: tests/auth-refresh.test.ts

[Commits]
- a1b2c3d: fix(auth): refresh token after password reset

[Outstanding Context]
- lint check still failing on line 42

[User Preferences]
- Prefer Vietnamese responses
- Always run tests before committing

[user] Fix the auth bug, users can't log in after password reset
[assistant] Root cause is a missing token refresh after password reset...
* bash "bun test tests/auth.test.ts" (#12)
* edit "src/auth/session.ts" (#14)
* bash "bun test tests/auth.test.ts" (#16)
...(28 earlier lines omitted)

各 section 仅在相关内容存在时出现——例如没有 git 提交的会话就不会显示 [Commits]。

Sections：

合并策略：

• Session Goal、User Preferences：紧凑的粘性 section
• Outstanding Context：仅全新（每次压缩替换）
• Files And Changes、Commits：跨压缩的唯一并集
• Brief transcript：滚动窗口，旧行丢弃

召回（无损历史）

Pi 的默认压缩会永久丢弃旧消息。压缩后，agent 只能看到摘要。vcc_recall 通过直接读取原始会话 JSONL 文件来绕过此限制。默认情况下，它只搜索当前活跃的对话 lineage，无论发生过多少次压缩。仅在你有意包含非 lineage 分支时，才使用 scope:"all"。

搜索查询支持正则和多词 OR 逻辑，并按相关性排序：

vcc_recall({ query: "auth token" })                // active-lineage OR 搜索，排序
vcc_recall({ query: "auth token", page: 2 })       // 分页（每页 5 条结果）
vcc_recall({ query: "hook|inject" })               // 正则模式
vcc_recall({ query: "fail.*build" })               // 正则模式
vcc_recall({ query: "auth token", scope: "all" })  // 搜索所有 lineage

手动斜杠命令：

/pi-vcc-recall auth token scope:all

浏览

不带查询时，返回最近 25 条记录的简短摘要：

vcc_recall()
vcc_recall({ scope: "all" })  // 浏览所有 lineage 的近期条目

展开

返回搜索中找到的特定索引的完整未截断内容：

vcc_recall({ expand: [41, 42] })                     // active-lineage 展开
vcc_recall({ expand: [41, 42], scope: "all" })       // 跨所有 lineage 展开

典型工作流：搜索 → 找到相关条目索引 → 展开这些索引以获取完整内容。

某些工具结果在保存时已被 Pi 核心截断。expand 返回 JSONL 中的所有内容，但无法恢复 Pi 已经截掉的部分。

处理流程

1. 标准化——原始 Pi 消息 → 统一块（user、assistant、tool_call、tool_result、thinking）
2. 过滤噪音——去除系统消息、空块
3. 构建切割——保留请求的用户交互尾部；压缩全部时使用 firstKeptEntryId: "" 哨兵
4. 构建 section——提取目标、文件路径、阻塞项、偏好
5. 简要对话记录——按时间顺序的对话流程，工具调用折叠为单行，文本截断
6. 格式化——渲染为带括号的 section + 对话记录
7. 合并——如果存在之前的摘要：粘性 section 合并，易失 section 替换，对话记录滚动

配置

配置文件位于 ~/.pi/agent/pi-vcc-config.json（首次加载时自动生成安全默认值）：

{
  "overrideDefaultCompaction": false,
  "debug": false
}

• overrideDefaultCompaction（默认 false）：当为 false 时，pi-vcc 仅对 /pi-vcc 命令生效；/compact 和自动阈值压缩仍通过 Pi 核心处理。设为 true 可使 pi-vcc 处理所有压缩路径。
• debug（默认 false）：当为 true 时，每次压缩会将详细信息写入 /tmp/pi-vcc-debug.json——消息计数、切割边界、摘要预览、sections。

相关项目

• VCC (https://github.com/lllyasviel/VCC)——原始的保留对话记录的会话编译器
• Pi (https://github.com/badlogic/pi-mono)——本扩展所面向的 AI 编程 agent

许可证

MIT