sting8k/pi-vcc

pi‑vccとは？

pi‑vccは、Piコーディングアシスタント（コード作成を支援するオープンソースのLLM搭載チャットボット）向けのプラグインです。長いチャット履歴を、言語モデルを呼び出すことなく、簡潔で検索可能な要約に自動的に圧縮します。要約は、会話から重要な情報（目標、変更ファイル、最近のコミット、実行コマンド、未解決の問題、ユーザー設定、短いトランスクリプト）を抽出し、固定セクションにフォーマットして作成されます。

---

なぜ使うのか？

機能	Piの組み込み圧縮	pi‑vcc
方法	切り取った全体をLLMに送信して要約を生成	純粋なアルゴリズム抽出 – LLMなし、トークンコストなし
決定性	非決定的、幻覚を起こす可能性あり	同じ入力 → 同一の出力
サイズ削減	変動あり	中央値97.6%削減（10パーセンタイルで89%）
レイテンシ	LLM呼び出しを待つ（秒単位）	中央値1ms、90パーセンタイル11ms、最悪348ms
コスト	要約リクエストでトークンを消費	無料
圧縮後の履歴	破棄	vcc_recallで検索可能
繰り返し圧縮	毎回さらに失われる可能性	セクションがマージされ、上限が維持
構造	自由形式の散文	最大6つのラベル付きセクション+短いトランスクリプト

また、このプラグインは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 }) // ページネーション（1ページあたり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. 抽出とフォーマット – 6つの可能なセクションと短いトランスクリプトを抽出し、レンダリングします。
4. マージ – 以前の要約が存在する場合は、新しいセクションをマージして再キャップします。 トークン数は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トークンまで拡張します。
• continueAfterThresholdCompact – 自動圧縮後、エージェントに続行するよう指示します（古いPiバージョン向け）。
• debug – 圧縮ごとの詳細な診断を/tmp/pi‑vcc‑debug.jsonに書き込みます。
• skipForProviders – pi‑vccが介入しないプロバイダーIDのリスト（例：groq、openai）。
• skipCustomTypes – 要約入力からカスタムメッセージタイプを除外します。
• trackCommands – [Tracked Commands]セクションに保持するシェルコマンドを指定します（例：["docker", "kubectl"]）。

---

ベンチマーク

リポジトリにはbenchmarks/README.mdが含まれており、pi‑vcc（v0.3.18）をPiのデフォルトの圧縮ツールと1,884の実際のセッションで比較し、再現率、事実密度、精度、サイズ削減などのメトリクスを報告しています。

---

誰が作ったのか？

• VCC（View‑oriented Conversation Compiler）プロジェクトに触発されました。
• リコール関連機能（mode:"touched"、#N:path）は@k0valikによるpi‑blackholeから借用しています。
• 自動継続ロジックは@monotykamaryによるフォークから来ています。

---

ライセンス

MIT – 自由に使用、変更、配布できます。

---

TL;DR

pi‑vccは、長いPiチャットセッションを構造化された要約に縮小し、完全な履歴を検索可能に保つ、高速で決定的、ゼロコストの方法を提供します。pi install npm:@sting8k/pi-vccでインストールし、自動実行または/pi‑vccでトリガーし、vcc_recallを使用して圧縮部分をいつでも掘り起こせます。