📖 pi-atelier 实战指南 — 从零教会你使用 pi-atelier 扩展生态，包含完整示例和最佳实践。

English | 程序中文文档

pi-smart-compact

Intelligent context compaction for pi — two-phase LLM-driven compression that preserves critical context while aggressively trimming noise.

Why You Need It

When pi's context window fills up, it compacts old messages — but the default compaction is lossy and indiscriminate. It summarizes everything equally, losing track of key decisions, code changes, and error fixes that happened 20 turns ago.

pi-smart-compact replaces this with targeted, intelligent compaction:

• Phase 1 — Intent extraction — Extracts user and AI non-tool text, feeds it to an LLM to generate a concise intent summary of the conversation
• Phase 2 — Tool verdict — Evaluates each tool call against the intent: keep the ones still relevant, discard the rest
• Result — A compact context that preserves why you're doing something and the important tool outputs, while dropping routine read/grep noise

How It Works

Context window full → pi triggers compaction
        │
        ▼
┌─── Phase 1: Intent Extraction ────────────┐
│                                            │
│  User + AI text (no tool noise)            │
│         │                                  │
│         ▼                                  │
│  LLM → "User is refactoring auth module,   │
│         migrating from JWT to session       │
│         cookies, 3 of 5 files done"         │
│                                            │
└────────────────────────────────────────────┘
        │
        ▼
┌─── Phase 2: Tool Verdict ─────────────────┐
│                                            │
│  For each tool call pair:                  │
│    [read src/auth/jwt.ts] → ❌ Discard     │
│    [edit src/auth/cookie.ts] → ✅ Keep     │
│    [bash npm test] → ✅ Keep (last result) │
│    [grep "import auth"] → ❌ Discard       │
│                                            │
└────────────────────────────────────────────┘
        │
        ▼
Compressed context = Intent summary + Kept tool results + File tracking

Installation

pi install git:github.com/catlain/pi-smart-compact

Restart pi to activate. Auto-compaction is off by default — use /smart-compact-config auto to enable.

Prerequisite: pi must be installed.

Commands

Command	Description
/smart-compact	Manually trigger two-phase enhanced compaction
/smart-compact-config	View current config
/smart-compact-config auto	Enable automatic compaction takeover
/smart-compact-config manual	Disable auto — only manual /smart-compact triggers

Configuration

Stored in .pi/smart-compact.json (project-level). Defaults are sensible for most cases.

{
  "enabled": false,
  "intentModel": "glm-4-flash",
  "filterModel": "glm-4-flash",
  "thinkingTruncateChars": 500,
  "toolCallTruncateChars": 1000,
  "toolResultTruncateChars": 2000,
  "filterBatchSize": 20
}

Field	Type	Default	Description
enabled	boolean	false	Auto-takeover of pi's compaction. false = manual only
intentModel	string?	—	Model for intent extraction (empty = session default)
filterModel	string?	—	Model for tool verdict (empty = same as intentModel)
thinkingTruncateChars	number	500	Max chars kept from LLM thinking blocks
toolCallTruncateChars	number	1000	Max chars kept from tool call arguments
toolResultTruncateChars	number	2000	Max chars kept from tool results
filterBatchSize	number	20	Tools per batch for verdict LLM call

Model recommendations:

• Use a fast, cheap model (glm-4-flash, deepseek-chat) for both phases
• The intent and filter models can differ — e.g., heavier model for intent, lighter for batch verdicts

Use Cases

Scenario	Benefit
Long coding sessions (50+ turns)	Agent stays focused on the current task after compaction
Multi-file refactoring	Preserves cross-file dependency knowledge — doesn't lose what you changed in file A when compacting before editing file B
Research workflows	Keeps key findings while discarding intermediate grep/search noise
Debug sessions	Preserves error messages and root-cause analysis, drops exploratory reads

Best Practices

✅ Recommended

• Start with manual mode — run /smart-compact when you feel context is getting bloated
• Switch to auto once you trust the results
• Use fast models for compaction — it's a classification/summarization task, not complex reasoning
• Adjust truncation limits based on your typical tool output sizes

❌ Not Recommended

• Don't use expensive models (GPT-4, Claude Opus) for compaction — it runs on every compaction event
• Don't set truncation limits too low — you'll lose important context in the verdict phase
• Don't enable auto without testing manual mode first

Limitations

Limitation	Detail
LLM dependency	Requires at least one LLM call per compaction (cost + latency)
Truncation-based	Tool results are truncated, not intelligently summarized
No cross-session learning	Each compaction is independent — no memory of past verdict patterns
Single model per phase	Can't use different models for different tool types

Architecture

pi-smart-compact/
├── index.ts              # Entry: register commands + session_before_compact hook
├── config.ts             # Config load/save to .pi/smart-compact.json
├── types.ts              # Type definitions + defaults
├── intent-extractor.ts   # Phase 1: extract non-tool text → summarize intent
├── tool-filter.ts        # Phase 2: batch tool verdict (keep/discard)
├── llm-caller.ts         # Unified LLM call abstraction (uses pi's model routing)
├── prompts.ts            # LLM prompt templates for intent + verdict
├── serializer.ts         # Message serialization helpers
├── tests/                # Unit tests
└── package.json

Dependencies:

• @earendil-works/pi-coding-agent — ExtensionAPI (peer)

License

MIT