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

English | 程序中文文档

pi-workflow

Workflow orchestration extension for pi — subagent spawning, research workflow, and output capture.

Why You Need It

Complex AI tasks often need structured multi-step workflows — search → evaluate → synthesize → conclude. A single agent context can't handle this well: it loses track, mixes concerns, or runs out of tokens.

pi-workflow solves this by providing subagent spawning and structured research pipelines where each step runs in a focused, isolated context.

Use it when: Your task is too complex for a single agent pass — research, multi-perspective analysis, or parallel investigation.

• Subagent spawning — Launch child pi processes with isolated context for independent tasks
• Research pipeline — Structured multi-round research with search, evaluation, synthesis, and conclusion phases
• Output capture — Save and retrieve subagent outputs for downstream processing
• State management — Track workflow state across steps with automatic persistence

Installation

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

Tool: workflow

The extension registers a workflow tool with multiple actions for the research pipeline:

| Action | Description | |--------|-------------| | start | Start a new research workflow with a topic | | search | Execute a search round | | evaluate | Evaluate search results for relevance | | synthesize | Synthesize findings from multiple rounds | | conclude | Generate final conclusions |

How Subagents Work

Main Agent
  └── workflow tool → runSubagent()
        └── Child pi process (isolated context)
              ├── Own tools and system prompt
              ├── Own context window
              └── Result → saved to file

Key features:

• Isolation — Each subagent runs in its own context window, doesn't pollute the main conversation
• Model selection — Subagents can use different (cheaper) models
• Output persistence — Results saved to disk for later retrieval
• Status tracking — Main agent can check subagent success/failure

Use Cases

| Scenario | How It Works | |----------|-------------| | Literature research | Search → Evaluate → Synthesize → Conclude pipeline | | Multi-perspective analysis | Spawn subagents with different viewpoints | | Parallel investigation | Run independent research threads simultaneously | | Factor research | Search indicators → Evaluate quality → Combine signals |

Best Practices

✅ Recommended

• Use subagents for tasks > 30 minutes — they keep context fresh
• Choose cheaper models for subagents when possible (e.g., Haiku for search rounds)
• Always check subagent output before synthesizing — catch failures early
• Save workflow state between steps for resumability

❌ Not Recommended

• Don't use subagents for simple tasks (< 5 minutes) — overhead isn't worth it
• Don't spawn too many subagents simultaneously — resource contention
• Don't pass huge contexts to subagents — that defeats the isolation purpose

Limitations

| Limitation | Detail | |------------|--------| | Subagent overhead | Each spawn takes time to initialize | | No streaming | Subagent output is available only after completion | | File-based output | Results are saved to disk, not streamed back | | Sequential pipeline | Research pipeline steps run one at a time |

Architecture

pi-workflow/
├── index.ts         # Entry: register workflow tool
├── subagent.ts      # Subagent spawning + output capture
├── pipeline.ts      # Research pipeline (search → evaluate → synthesize → conclude)
├── state.ts         # Workflow state management + persistence
└── package.json

Dependencies:

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

License

MIT