extension-dev-guide

分类: 开发与编程 | 上传者: Jitsusama | 下载: 0 | 版本: v1.0（最新）

如何开发 Pi 扩展。 TUI 组件、可用 API、组合模式和常见错误的发现工作流程。在构建或修改扩展时使用。 --- # Pi 扩展开发 ## 发现工作流程在构建任何 UI 之前，请遵循以下顺序： 1. **阅读 Pi 的 TUI 文档** 了解模式和可用组件。主要的 Pi 文档列在系统提示符下的“Pi 文档”下 — 从那里阅读“docs/tui.md”。根据需要点击相关文档的链接。 2. **阅读您需要的特定组件的类型声明**。 `@mariozechner/pi-tui` 包的 `dist/index.d.ts` 和 `dist/components/*.d.ts` 文件显示了确切的 API 界面。 3. **阅读由 `@mariozechner/pi-coding-agent` 在其 `dist/modes/interactive/components/index.d.ts` 中导出的更高级别组件**。 4. **检查此项目的 `lib/ui/`** 是否存在构建在 Pi 基元之上的现有抽象。 `lib/ui/index.ts` 处的桶显示了公共表面。不要重复已有的内容。 5. **浏览 Pi 的示例**以了解有效的实现。系统提示符中列出了示例目录。 ## 架构：扩展与库扩展和库代码扮演着不同的角色。有关完整模式，请参阅 AGENTS.md 的“集成架构”部分。简短版本： - **`lib/`** 包含域逻辑：API 客户端、身份验证、渲染器、类型和 UI 组件。这是其他 Pi 包可以导入的可重用代码。 - **`extensions/`** 保存 Pi 特定的连接：工具注册、`renderCall`/`renderResult`、斜杠命令、确认门、会话状态和生命周期。在构建集成时，扩展应该是其库的瘦消费者。缓存属于扩展；图书馆保持无状态。当构建守护者或工作流时，共享逻辑位于“lib/internal/”中。有关公共代码与内部代码的完整指南，请参阅 AGENTS.md。 ## 可用的内容（仅限方向；根据来源验证） **来自 `@mariozechner/pi-tui`

更新日志: Source: GitHub https://github.com/Jitsusama/agentic-harness.pi

目录结构

当前层级: tree/main/.pi/skills/extension-dev-guide/

📄 README.md 651 B
📄 SKILL.md 7.2 KB

SKILL.md

---
name: extension-dev-guide
description: >
  How to develop Pi extensions. Discovery workflow for TUI
  components, available APIs, composition patterns and common
  mistakes. Use when building or modifying extensions.
---

# Pi Extension Development

## Discovery Workflow

Before building any UI, follow this sequence:

1. **Read Pi's TUI docs** for patterns and available
   components. The main Pi documentation is listed in the
   system prompt under "Pi documentation" — read `docs/tui.md`
   from there. Follow links to related docs as needed.

2. **Read the type declarations** for the specific component
   you need. The `@mariozechner/pi-tui` package's
   `dist/index.d.ts` and `dist/components/*.d.ts` files show
   the exact API surface.

3. **Read the higher-level components** exported by
   `@mariozechner/pi-coding-agent` in its
   `dist/modes/interactive/components/index.d.ts`.

4. **Check this project's `lib/ui/`** for existing
   abstractions built on top of Pi's primitives. The barrel
   at `lib/ui/index.ts` shows the public surface. Don't
   duplicate what's already there.

5. **Browse Pi's examples** for working implementations.
   The examples directory is listed in the system prompt.

## Architecture: Extensions vs Library

Extensions and library code serve different roles. See
AGENTS.md's "Integration Architecture" section for the full
pattern. The short version:

- **`lib/`** holds domain logic: API clients, authentication,
  renderers, types and UI components. This is reusable code
  that other Pi packages can import.
- **`extensions/`** holds Pi-specific wiring: tool
  registration, `renderCall`/`renderResult`, slash commands,
  confirmation gates, session state and lifecycle.

When building an integration, the extension should be a thin
consumer of its library. Caching belongs in the extension;
the library stays stateless.

When building a guardian or workflow, shared logic goes in
`lib/internal/`. See AGENTS.md for the full guidelines on
public vs internal code.

## What's Available (Orientation Only; Verify Against Source)

**From `@mariozechner/pi-tui`:**

| Need | Component |
|------|-----------|
| Group children vertically | `Container` |
| Padded container with background | `Box` |
| Display text with word wrap | `Text` |
| Display text truncated to width | `TruncatedText` |
| Render markdown | `Markdown` |
| Empty vertical space | `Spacer` |
| Single-line text input | `Input` |
| Multi-line editor with autocomplete | `Editor` |
| Pick from a list | `SelectList` |
| Toggle settings | `SettingsList` |
| Spinner animation | `Loader` |
| Cancellable spinner with AbortSignal | `CancellableLoader` |
| Display an image | `Image` |
| Key detection | `matchesKey`, `Key` |
| Text width / truncation / wrapping | `visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi` |
| Fuzzy search | `fuzzyMatch`, `fuzzyFilter` |

**From `@mariozechner/pi-coding-agent`:**

| Need | Component |
|------|-----------|
| Full-width border line | `DynamicBorder` |
| Bordered spinner with cancel | `BorderedLoader` |
| Custom editor with app keybindings | `CustomEditor` |
| Coloured diff output | `renderDiff` |
| Syntax highlighting | `highlightCode`, `getLanguageFromPath` |
| Pre-built themes for components | `getMarkdownTheme`, `getSelectListTheme`, `getEditorTheme`, `getSettingsListTheme` |
| Keybinding hint formatting | `keyHint`, `appKeyHint`, `rawKeyHint` |
| Visual line truncation | `truncateToVisualLines` |

**From `ctx.ui` (ExtensionUIContext):**

| Need | Method |
|------|--------|
| Selection dialog | `select()` |
| Yes/no confirmation | `confirm()` |
| Text input dialog | `input()` |
| Multi-line editor dialog | `editor()` |
| Toast notification | `notify()` |
| Footer status indicator | `setStatus()` |
| Loading message during streaming | `setWorkingMessage()` |
| Persistent widget above/below editor | `setWidget()` |
| Replace footer | `setFooter()` |
| Replace header | `setHeader()` |
| Full custom component | `custom()` |
| Overlay (floating component) | `custom()` with `{ overlay: true }` |
| Replace the input editor | `setEditorComponent()` |
| Manipulate editor text | `setEditorText()`, `getEditorText()`, `pasteToEditor()` |
| Theme access | `theme` property |
| Tool output expansion | `getToolsExpanded()`, `setToolsExpanded()` |
| Terminal title | `setTitle()` |
| Raw terminal input | `onTerminalInput()` |

**From this project's `lib/ui/` (barrel: `lib/ui/index.ts`):**

| Need | Export |
|------|--------|
| Interactive single-choice panel | `promptSingle` |
| Interactive tabbed panel | `promptTabbed` |
| Read-only content display | `view` |
| Stateful workspace prompt | `workspace` |
| Markdown/diff/code rendering | `renderMarkdown`, `renderDiff`, `renderCode` |
| Navigable list rendering | `renderNavigableList`, `renderNavigableSections` |
| Text wrapping | `contentWrapWidth`, `wordWrap` |

Internal files not in the barrel (`redirect.ts`,
`tab-completion.ts`, `navigable-list.ts` input handler,
`text-layout.ts`, `panel-height.ts`) can be imported
directly by extensions in this package when needed.

## Gotchas

These are design decisions in Pi that aren't obvious from the
type signatures. They'll cause real bugs when you miss them.

### Each Render Line Must Be ≤ Width

`render(width)` must return lines no wider than `width` visible
characters. Use `truncateToWidth()` on every line. ANSI escape
codes don't count toward width, but wide characters (CJK,
emoji) count as 2.

### Always Use Theme from the Callback

Never import `theme` directly. Pi's module caching means the
global `theme` may be undefined in extension code loaded via
jiti. Always grab the `theme` parameter from:
- `ctx.ui.custom((tui, theme, kb, done) => ...)`
- `renderCall(args, theme)`
- `renderResult(result, options, theme)`

### Type the DynamicBorder Colour Parameter

```typescript
// Correct: explicit type annotation
new DynamicBorder((s: string) => theme.fg("accent", s))

// Wrong: jiti inference fails
new DynamicBorder((s) => theme.fg("accent", s))
```

### Call tui.requestRender() After State Changes

The TUI doesn't auto-render. After modifying state in
`handleInput`, call `tui.requestRender()` to trigger a
redraw.

### Implement invalidate() for Theme Changes

When the theme changes, the TUI calls `invalidate()` on all
components. If you've baked theme colours into cached strings
(via `theme.fg()`, `theme.bg()`), you need to rebuild them in
`invalidate()`. See the "Rebuild on Invalidate" pattern in
Pi's `tui.md`.

### Overlay Components Are Disposable

Create fresh instances each time; never reuse a reference
after the overlay closes because the component is disposed
when it closes.

### Propagate Focusable for IME Support

Container components that embed `Input` or `Editor` must
implement the `Focusable` interface and propagate the `focused`
property to the child. Without this, IME candidate windows
(CJK input) show up in the wrong position.

### Text(content, 0, 0) Inside Box

When placing `Text` inside a `Box`, use 0,0 padding on the
`Text`. The `Box` handles padding. Double-padding is a common
mistake.

### Dialogs Support Timeout and Signal

All dialog methods (`select`, `confirm`, `input`) accept an
options object with `timeout` (auto-dismiss with countdown)
and `signal` (AbortSignal for manual dismiss).

登录后下载/点赞/收藏 ❤ 5 | ★ 0

extension-dev-guide

目录结构

SKILL.md

举报内容

提示