sting8k/pi-vcc

pi‑vcc 是什么？

pi‑vcc 是 Pi 编程助手（帮助您编写代码的开源 LLM 驱动的聊天机器人）的插件。它会自动将冗长的聊天历史压缩为简洁、可搜索的摘要，无需调用任何语言模型。摘要通过从对话中提取关键信息（目标、更改的文件、最近的提交、运行的命令、未解决的问题、用户偏好和简短记录）并格式化为固定部分来构建。

---

为什么使用它？

功能	Pi 的内置压缩	pi‑vcc
方法	将整个剪切内容发送给 LLM 生成摘要	纯算法提取 – 无 LLM，无 token 成本
确定性	非确定性，可能产生幻觉	相同输入 → 相同输出
大小缩减	变化不定	中位数缩减 97.6%（第 10 百分位为 89%）
延迟	等待 LLM 调用（秒级）	中位数 1ms，90% 分位 11ms，最差 348ms
成本	消耗 token 进行摘要请求	免费
压缩后的历史	被丢弃	仍可通过 vcc_recall 搜索
重复压缩	每次可能丢失更多	部分合并并保持上限
结构	自由形式散文	最多六个带标签的部分 + 简短记录

该插件还替换了 Pi 的默认 /compact 命令，添加了用于按需压缩的 /pi‑vcc 命令，并可干预自动压缩。

---

如何获取

# 从 npm 注册表
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 会压缩对话中最旧的部分。
• 按需 – 输入 /pi‑vcc 立即压缩，保留最后一轮用户消息。
• 尾部控制 – /pi‑vcc keep:N [prompt] 保留最后 N 轮用户消息（例如 keep:0 压缩所有内容），并可在摘要后向代理发送可选提示。
• 回退 – 在配置中设置 overrideDefaultCompaction: false 让 Pi 核心处理正常的 /compact，同时仍允许 /pi‑vcc。

---

摘要的样子

[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

[Tracked Commands]
- docker: docker compose restart api 2>&1

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

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

---
...(28 earlier lines omitted)
[user]
Fix the auth bug, users can't log in after password reset

[assistant]
Root cause is a missing token refresh after password reset... (#11)
* bash "bun test tests/auth.test.ts" (#12)
* edit "src/auth/session.ts" (#14)
* bash "docker compose restart api 2>&1" (#15)
* bash "bun test tests/auth.test.ts" (#16)
---
Use `vcc_recall` to search for prior work, decisions, and context from before this summary.

只有有内容的部分才会出现；没有提交的会话会省略 [Commits] 块。

---

搜索隐藏历史 – vcc_recall

即使在对话的一部分被压缩后，您也可以检索它：

vcc_recall({ query: "auth token" })          // 关键字 OR 搜索，排名
vcc_recall({ query: "auth token", page: 2 }) // 分页（每页 5 条结果）
vcc_recall({ query: "hook|inject" })        // 正则表达式回退
vcc_recall({ query: "auth token", scope: "all" }) // 搜索所有谱系

// 直接范围或扩展
vcc_recall({ range: [1250, 1290] })
vcc_recall({ expand: [1253] })

同样的功能也以斜杠命令的形式提供，例如 /pi‑vcc‑recall auth token scope:all。

---

工作原理（不涉及 AI）

1. 选择剪切点 – 保留尾部之前的所有内容都是要摘要的材料。
2. 规范化 – 将 Pi 消息变成统一的块，删除系统消息和空块。
3. 提取并格式化 – 提取可能的六个部分和简短记录，然后渲染它们。
4. 合并 – 如果存在先前的摘要，将新部分合并到其中并重新封顶。 Token 数根据 Pi 自身的统计进行估算；不调用任何外部模型。

---

配置（pi‑vcc‑config.json）

位于 ~/.pi/agent（或 $PI_CODING_AGENT_DIR）。默认值在首次运行时创建：

{
  "overrideDefaultCompaction": true,
  "smartKeepTail": true,
  "continueAfterThresholdCompact": true,
  "debug": false,
  "skipForProviders": [],
  "skipCustomTypes": [],
  "trackCommands": []
}

• overrideDefaultCompaction – 让 pi‑vcc 替换 Pi 的 /compact 和自动压缩。
• smartKeepTail – 当默认的 keep:1 尾部很小时，将保留的尾部扩展到最多 25k token。
• continueAfterThresholdCompact – 自动压缩后，告诉代理继续（适用于旧版 Pi）。
• debug – 将每次压缩的详细诊断写入 /tmp/pi‑vcc‑debug.json。
• skipForProviders – 列出 pi‑vcc 不介入的提供程序 ID（例如 groq、openai）。
• skipCustomTypes – 从摘要输入中省略自定义消息类型。
• trackCommands – 指定要在 [Tracked Commands] 部分保留的 shell 命令（例如 ["docker", "kubectl"]）。

---

基准测试

存储库包含一个 benchmarks/README.md，比较了 pi‑vcc（v0.3.18）与 Pi 的默认压缩器在 1,884 个真实会话上的表现，报告了召回率、事实密度、精确度和大小缩减等指标。

---

谁构建的？

• 灵感来自 VCC（面向视图的对话编译器）项目。
• 召回相关功能（mode:"touched"、#N:path）借用自 @k0valik 的 pi‑blackhole。
• 自动继续逻辑来自 @monotykamary 的一个分支。

---

许可证

MIT – 自由使用、修改和分发。

---

TL;DR

pi‑vcc 为您提供了一种快速、确定性、零成本的方式，将冗长的 Pi 聊天会话缩减为结构化摘要，同时保持完整历史可搜索。通过 pi install npm:@sting8k/pi-vcc 安装，让它自动运行或通过 /pi‑vcc 触发，并使用 vcc_recall 在需要时深入挖掘压缩部分。