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 }) // 페이지네이션 (페이지당 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"]).

---

벤치마크

리포지토리에는 1,884개의 실제 세션에서 pi‑vcc(v0.3.18)와 Pi의 기본 압축기를 비교하는 benchmarks/README.md가 포함되어 있으며, 재현율, 사실 밀도, 정밀도, 크기 감소 등의 메트릭을 보고합니다.

---

누가 만들었나요?

• 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을 사용하여 압축된 부분을 필요할 때마다 다시 조사하세요.