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

pi-context

源码仓库 | npm

Context management extension for pi-coding-agent — tool result formatting, distillation, context panel, and aging.

What It Does

AI coding agents accumulate context quickly — tool outputs pile up, old messages become irrelevant, and the agent loses track of what matters. pi-context automatically manages your agent's context window:

• Tool result processing — Formats and truncates tool outputs (bash, web search, web reader, MCP errors) to keep context lean
• Distillation — Replaces verbose tool results with compact summaries, preserving key information
• Context aging — Marks older messages for compaction based on configurable rules
• Context panel — Displays a TUI sidebar showing context usage, distillation stats, and message metadata
• Payload recording — Records provider payloads for debugging token usage

Installation

pi install git:github.com/catlain/pi-context

Commands

Command	Description
/context	Toggle context panel visibility
/record [on/off]	Enable/disable provider payload recording
/distill-config	Configure distillation rules
/aging-config	Configure context aging rules
/processor-config	Configure tool result processor rules

How It Works

Tool Result Processing Chain

When a tool returns a result, pi-context runs it through a chain of formatters:

1. Web search → Extract titles, URLs, summaries; strip boilerplate
2. GitHub → Compact issue/PR/commit data
3. Web reader → Truncate large pages, extract key content
4. Bash → Strip ANSI codes, truncate long output
5. MCP errors → Clean up verbose error traces

Distillation

After processing, distillation replaces old tool results with compact summaries. Configure which tools to distill and retention rules via /distill-config.

Context Aging

Messages older than a configurable threshold get marked for compaction, keeping the context window focused on recent, relevant information.

Configuration

Settings are stored in ~/.pi/agent/settings.json under the context section:

{
  "context": {
    "distill": true,
    "aging": true,
    "record": false
  }
}

Use Cases

Scenario	Feature	Benefit
Long coding sessions	Distillation + Aging	Context stays focused on recent work
Web research	Web search/reader processing	Clean summaries instead of raw HTML
Debugging token usage	Payload recording + Context panel	See exactly where tokens go
MCP tool cleanup	MCP error processing	Readable errors instead of raw traces

Best Practices

✅ Recommended

• Enable distillation for long sessions — saves significant token budget
• Use /context panel to monitor token usage during complex tasks
• Record payloads (/record on) when debugging context issues, then turn off
• Configure aging thresholds based on your typical session length

❌ Not Recommended

• Don't disable distillation for sessions > 1 hour — context will bloat
• Don't leave payload recording on permanently — files grow large
• Don't set aging too aggressive — you may lose important context

Limitations

Limitation	Detail
Distillation is lossy	Summaries may miss edge-case details
No cross-session memory	Context resets between sessions
Panel requires TUI	Context panel only works in terminal mode
Recording overhead	Payload recording adds slight latency

Architecture

pi-context/
├── index.ts           # Entry: register processors + distillation + panel
├── processors/        # Tool result formatters
│   ├── web-search.ts  # Web search result compaction
│   ├── web-reader.ts  # Web page content truncation
│   ├── github.ts      # GitHub data formatting
│   ├── bash.ts        # ANSI stripping + truncation
│   └── mcp-error.ts   # MCP error cleanup
├── distill.ts         # Distillation engine (replace → summarize)
├── aging.ts           # Context aging rules
├── panel.ts           # TUI context panel
├── recorder.ts        # Provider payload recording
└── package.json

Dependencies:

• @pi-atelier/shared-utils (bundled) — settings management
• @earendil-works/pi-coding-agent — ExtensionAPI (peer)
• @earendil-works/pi-tui — context panel UI (peer)

License

MIT