# 策展 · X (Twitter) 🔥

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 作者：Kieran Zhang (@ninthbit_ai) · 平台：X (Twitter) · 日期：2026-06-01

> 原始來源：https://x.com/ninthbit_ai/status/2060711641378119824

## 中文摘要

# Pi Agent 配置指南：打造你的專屬 AI 程式開發助手

> 在玩 Pi 的過程中，感覺又回到了折騰 Neovim 的時期，這種自己構建樂高玩具的過程，無論何時都深深吸引著我。

## 什麼是 Pi ？

Pi 又叫 Pi coding agent，如果你沒有聽說過它，那你一定聽說過 OpenClaw。而 Pi 則是 OpenClaw 背後的編碼 Agent 框架。極簡的設計哲學，是大家對它最大的共識。

所以我們我們先來了解一下，Pi 的能力邊界是什麼。

一切都圍繞著極簡二字，0 配置的 Pi Agent 只支援 4 種工具：bash、read、write 和 edit，沒有 MCP、沒有 sub-agents、沒有 plan mode、沒有 permission popups。一切都沒有，都需要自己配置。看到這，如果你想要一個開箱即用的 coding agent，那麼可以轉向 Codex 和 Claude Code。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1780273887929-iaHJkchSaaYAAVSc9jpg.jpg)

正如作者的設計原則中所說，Pi 保持核心精簡，將工作流相關行為推向了拓展（Extensions）、skills、提示詞模板（Prompt Templates）以及套件（Packages）中。後文中我將重點介紹這些可自訂化的部分，以及如何搭建起屬於自己的 Harness。

## 什麼是 Extension ？

這是 Pi 框架中的第一個抽象，擴展是 TypeScript 模組，用於擴展 Pi 的行為。它們可以訂閱生命週期事件、註冊可由 LLM 呼叫的自訂工具、添加命令等。位置在 `.pi/agent/extensions/*` 目錄下，Pi 會自動發現這些拓展，或者可用 `/reload` 命令進行熱更新。

下面會重點講拓展的關鍵能力：

1. **自訂工具/自訂命令**：分別透過 `pi.registerTool()` 和 `pi.registerCommand()` 註冊大模型自訂工具和斜線命令。

2. **事件攔截**：阻止或修改工具呼叫、注入上下文、自訂壓縮。Pi 提供了非常豐富的生命週期（LifeCycle）事件用來註冊，基本可以滿足大部分需求。官方文件。

3. **使用者互動/介面渲染**：Pi 也允許使用者自訂互動邏輯和渲染邏輯，比如寫一個提問 QA 的問答框、自訂 Editor 樣式或者寫一個等待模型輸出時的小遊戲（例如：貪食蛇、飛機大戰等）。

4. **會話持久化**：透過 `pi.appendEntry()` 儲存重啟後仍保留的狀態。可以用來做一個類似 todo 的拓展。

### 如何寫一個 Pi 拓展？

在 AI 時代，我們不必再像 Neovim 時期，自己動手寫 Lua 程式碼，最簡單的方式或許就是和 Pi 說清楚你的需求，讓它自己去寫一個，並且透過熱載入馬上生效。所以你可以對 Pi 說：

> 我想寫一個叫做 permission-gate 的 Pi Extension，作用是 Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.)

再比如，我想透過插件形式，完全實現像 Claude Code 格式的 hooks 功能，你可以對 Pi 說：

> 我想寫一個叫做 CC-hooks 的插件，用來將 Pi 原生的事件攔截能力，包裝成像 Claude Code Hooks 一樣的用法。

## 什麼是 Prompt Templates ？

其實這個更像 Claude Code 的自訂斜線命令，而上面拓展中的自訂命令更加的強大，可以呼叫 Pi 內部提供的 API。

格式：一個帶 front-matter 的 Markdown 檔案。

front-matter：包括 `description` 和 `argument-hint`，這兩個都是可選的，會顯示在下拉選單中的描述和參數。

模板還支援位置參數和切片，比如用 `$1` 和 `$2` 以及 `${@:N}` 這種使用方式，具體說明見 [模板參數](https://pi.dev/docs/templates)。

## 什麼是 Pi Package ？

Pi Package 是 Pi 的另一抽象，簡單來說就是 extensions, skills, prompt templates, or themes 的集合，這讓 Pi 的配置可以很方便地透過 git 或者 npm 分享和安裝。說起來有點像發行版的概念，但又不完全是，因為 Pi Package 可以多個共存，這是 Pi 配置可分享的最小單元。

但是便捷背後也意味著可能出現的安全隱患，Pi 作者特意強調了安全問題：Pi 包以完整系統權限執行。擴展程式可執行任意程式碼，skills 則能指示模型執行包括執行可執行檔在內的任何操作。所以安裝第三方包前請務必先審查原始程式碼。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1780273887961-iaHJkcobKbEAEtp7ajpg.jpg)

當然，Pi 包的建立也可以直接透過 Pi 去完成，官方文件參考[這裡](https://pi.dev/docs/packages)。

## Pi Package 推薦

截至 2026 年 5 月，pi.dev/packages 已收錄 3,328+ 個包。這裡我推薦 10 個自己安裝的。文末會給出我蒐集的 awesome-pi-list 倉庫供大家選擇。

1. **context-mode**：節省 98% 上下文視窗，提供沙盒程式碼執行、FTS5 知識庫和意圖驅動搜尋，Pi 使用者幾乎必裝。

2. **pi-subagents**：子 Agent 任務委派，支援鏈式呼叫、並行執行和 TUI 互動確認，讓一個主 Agent 排程多個子 Agent 協作完成複雜任務。

3. **pi-mcp-adapter**：MCP (Model Context Protocol) 轉接器，讓 Pi 能連接外部 MCP 伺服器，擴展工具能力（資料庫、API、檔案系統等）。

4. **pi-web-access**：Web 搜尋、URL 抓取、GitHub 專案複製、PDF 提取、YouTube 影片理解，彌補 Pi 無法存取網路的短板。

5. **pi-lens**：即時程式碼回饋 —— LSP、linter、formatter、型別檢查、結構分析。

6. **pi-simplify**：自動審查最近變更程式碼的清晰度、一致性和可維護性，程式碼品質守門員。

7. **@juicesharp/rpiv-todo**：給模型一個持久化 TODO 清單，以即時覆蓋層渲染，即使 `/reload` 或上下文壓縮也能保留。

8. **@plannotator/pi-extension**：互動式計畫審查與批註，支援對 Agent 訊息做標註、審查程式碼/PR，適合複雜任務前的方案評審。

9. **@narumitw/pi-goal**：`/goal` 模式，保持 Agent 工作直到任務完成。

10. **@narumirw/statusline**：豐富的狀態列，顯示模型、工具、git 分支、上下文使用、token 總計、費用和時間。

推薦 @9hills 老師的 Pi Agent 配置。

下面是我收錄的列表倉庫：

## 標籤

Agent, 教學資源, 開源專案, CLI, Bash, OpenClaw, Pi Agent