Pi AI Agent Toolkit — 完整教學

Pi 是一個開源 AI agent harness (代理框架)，提供可自我擴展的 coding agent (編碼代理) CLI、統一的多供應商 LLM API、以及完整的 extension / skill / SDK 生態系統。60K+ Stars，MIT 授權，TypeScript monorepo (單倉庫)。

目錄

1. 專案定位
2. 安裝指南
3. 核心架構解析
4. 核心功能用法
5. 應用場景
6. 資安掃描報告
7. FAQ
8. 進階技巧
9. 整合其他工作流
10. Checklist
11. 進一步閱讀

1. 專案定位

1.1 Pi 是什麼

Pi 是一個極簡主義 (minimalist) 的 terminal coding harness (終端編碼框架)，核心理念是「讓你適配 Pi 到你的工作流，而非反過來」。它刻意不內建 sub-agent (子代理)、plan mode (計畫模式)、permission popup (權限彈窗)、background bash (背景終端) 等功能，而是透過 extension system (擴充系統) 讓使用者或社群自由實作。

1.2 與同類工具比較

1.3 核心設計哲學

Pi 的設計原則可以用五個「No」概括：

1. No MCP — 用 CLI tool + README 即可達成同效果，或用 extension 加 MCP
2. No sub-agents — 透過 tmux spawn 多個 Pi 實例，或用 extension 實作
3. No permission popups — 用 container 隔離，或用 extension 實作確認流程
4. No plan mode — 將 plan 寫入檔案，或用 extension/package 實作
5. No built-in to-dos — 使用 TODO.md，避免干擾 LLM

這種「核心極簡、擴充無限」的哲學讓 Pi 在不到一年內累積 60K+ stars。

2. 安裝指南

2.1 系統需求

• Node.js >= 18 (建議 20+)
• npm >= 9
• 支援平台：macOS、Linux、Windows、Termux (Android)

2.2 安裝方式

方法一：npm 全域安裝（推薦）

1npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 禁用 dependency lifecycle script (依賴安裝腳本)，Pi 不需要安裝腳本。這是 supply-chain hardening (供應鏈加固) 的一環。

方法二：一鍵安裝腳本

1curl -fsSL https://pi.dev/install.sh | sh

方法三：從 source 建置（開發用途）

1git clone https://github.com/earendil-works/pi.git
2cd pi
3npm install --ignore-scripts
4npm run build
5./pi-test.sh  # 從 source 直接執行

2.3 Provider (供應商) 設定

Pi 支援三種認證方式：

Subscription Login (訂閱登入)

1pi
2/login  # 在互動模式中選擇 provider

支援：

• Anthropic Claude Pro / Max
• OpenAI ChatGPT Plus / Pro (Codex)
• GitHub Copilot

API Key (API 金鑰)

1# 設定環境變數
2export ANTHROPIC_API_KEY=sk-ant-...
3export OPENAI_API_KEY=sk-...
4export GEMINI_API_KEY=...
5
6# 啟動
7pi

常見 provider 環境變數：

Custom Provider (自訂供應商)

Ollama、vLLM、LM Studio 等本地模型，透過 ~/.pi/agent/models.json 設定：

 1{
 2  "providers": [
 3    {
 4      "name": "my-ollama",
 5      "api": "openai",
 6      "baseUrl": "http://localhost:11434/v1",
 7      "models": [
 8        { "id": "llama3.2", "contextWindow": 128000 }
 9      ]
10    }
11  ]
12}

2.4 驗證安裝

1pi --version     # 應顯示 v0.78.1 或更新
2pi --list-models # 列出可用模型
3pi --help        # 顯示 CLI 參考

2.5 更新

1pi update --self           # 更新 Pi 本體
2pi update --extensions     # 更新已安裝的 package
3pi update                  # 更新全部
4pi update --self --force   # 強制重新安裝

3. 核心架構解析

3.1 四層分層架構

Pi 採用 monorepo 架構，由下而上分為四層：

graph TB
    subgraph Layer4["Layer 4: pi-coding-agent (編碼代理 CLI)"]
        CA_CLI["CLI 入口
interactive / print / JSON / RPC"]
        CA_SESSION["Session 管理
JSONL 樹狀結構"]
        CA_EXT["Extension System
70+ 範例"]
        CA_SKILL["Skills / Prompts / Themes"]
        CA_COMPACT["Compaction Engine
自動 context 壓縮"]
        CA_AUTH["Auth & Trust
OAuth + API Key"]
    end

    subgraph Layer3["Layer 3: pi-agent-core (代理核心)"]
        AG_AGENT["Agent Class
狀態管理 + event streaming"]
        AG_LOOP["Agent Loop
prompt → tool → response 循環"]
        AG_TOOL["Tool System
定義 / 執行 / hook"]
        AG_STEER["Steering & Follow-up
中途指令 + 後續任務"]
    end

    subgraph Layer2["Layer 2: pi-ai (統一 LLM API)"]
        AI_STREAM["stream() / complete()
統一串流 & 完成 API"]
        AI_PROV["30+ Provider Adapters
Anthropic / OpenAI / Google / ..."]
        AI_MODEL["Model Registry
自動發現 + 型別安全"]
        AI_TOOL["Tool Schema
TypeBox 定義 + 驗證"]
        AI_CTX["Context
可序列化 / 跨模型交接"]
    end

    subgraph Layer1["Layer 1: pi-tui (終端 UI)"]
        TUI_RENDER["Differential Rendering
三策略 + CSI 2026 同步"]
        TUI_COMP["Built-in Components
Editor / Markdown / SelectList / Image"]
        TUI_INPUT["Input System
快捷鍵 / autocomplete / IME"]
    end

    Layer4 --> Layer3
    Layer3 --> Layer2
    Layer4 --> Layer1
    Layer2 -.-> Layer1

    style Layer4 fill:#1a1a2e,stroke:#e94560,color:#fff
    style Layer3 fill:#16213e,stroke:#0f3460,color:#fff
    style Layer2 fill:#0f3460,stroke:#533483,color:#fff
    style Layer1 fill:#533483,stroke:#e94560,color:#fff

3.2 各 Package 職責

3.3 Extension System 架構

Extension system (擴充系統) 是 Pi 最核心的差異化設計。Extension 是 TypeScript 模組，透過 ExtensionAPI 介面與 Pi 互動：

graph LR
    EXT["Extension
(TypeScript 模組)"] --> API["ExtensionAPI"]
    API --> TOOL["registerTool()
自訂工具"]
    API --> CMD["registerCommand()
自訂命令"]
    API --> EVT["on(event)
事件攔截"]
    API --> PROV["registerProvider()
自訂 provider"]
    API --> UI["ctx.ui
UI 互動"]

    EVT --> EVT_TC["tool_call
攔截/修改/阻擋"]
    EVT --> EVT_SS["session_start
初始化"]
    EVT --> EVT_CMP["compact
自訂壓縮"]
    EVT --> EVT_MOD["model_change
模型切換"]

    UI --> UI_SEL["select()"]
    UI --> UI_CONF["confirm()"]
    UI --> UI_INP["input()"]
    UI --> UI_CUST["custom()
完整 TUI component"]
    UI --> UI_NOT["notify()"]

Extension 可以做到的事情幾乎無限：

• Custom tool (自訂工具) — 或完全替換 built-in tool (內建工具)
• Sub-agent (子代理) — 範例已提供完整實作
• Plan mode (計畫模式) — 範例已提供
• Permission gate (權限閘門) — 危險指令攔截確認
• Path protection (路徑保護) — 禁止寫入特定目錄
• Custom compaction (自訂壓縮) — 自定義 context 摘要策略
• Git checkpoint (Git 檢查點) — 每個 turn 自動 stash
• SSH execution — 將工具路由到遠端機器
• MCP server 整合 — 透過 extension 加入 MCP
• Custom UI — 完整 TUI component，含鍵盤輸入
• Games (遊戲) — 等待時玩 Snake、Space Invaders、甚至 Doom

3.4 Agent Loop 事件流

 1prompt("Read config.json")
 2├── agent_start
 3├── turn_start
 4│   ├── message_start/end   { userMessage }
 5│   ├── message_start       { assistantMessage with toolCall }
 6│   ├── message_update...   { streaming chunks }
 7│   ├── message_end         { complete assistantMessage }
 8│   ├── tool_execution_start  { toolCallId, toolName, args }
 9│   ├── tool_execution_update { partialResult }
10│   ├── tool_execution_end    { toolCallId, result }
11│   └── message_start/end   { toolResultMessage }
12├── turn_end                { message, toolResults }
13│
14├── turn_start              （若需要後續 turn）
15│   ├── message_start       { assistantMessage — 回應 tool result }
16│   ├── message_update...
17│   └── message_end
18├── turn_end
19└── agent_end               { messages: [...] }

Tool execution mode (工具執行模式) 有兩種：

• parallel (並行，預設) — preflight (預檢) 循序，execution (執行) 並行
• sequential (循序) — 一個接一個執行

4. 核心功能用法

4.1 Interactive Mode (互動模式)

啟動 Pi 後進入互動模式，介面從上到下為：

• Startup header — 快捷鍵提示、已載入的 AGENTS.md / extension / skill / prompt template
• Messages — 使用者訊息、助理回應、tool call 與結果、通知
• Editor — 輸入區，邊框顏色指示 thinking level (思考等級)
• Footer — 工作目錄、session 名稱、token 用量、cost (費用)、context usage (上下文使用率)、model

編輯器功能

常用快捷鍵

常用命令

4.2 Built-in Tools (內建工具)

Pi 預設提供七個工具：

可用 CLI flag 控制工具組合：

 1# 唯讀模式
 2pi --tools read,grep,find,ls -p "Review the code"
 3
 4# 排除特定工具
 5pi --exclude-tools bash
 6
 7# 關閉所有內建工具（只保留 extension 工具）
 8pi --no-builtin-tools
 9
10# 關閉所有工具
11pi --no-tools

4.3 Sessions (對話管理)

Session 是 Pi 的核心資料結構，以 JSONL 格式儲存，採用樹狀結構 — 每個 entry (條目) 有 id 和 parentId，支援原地分支而不需建立新檔案。

Session 管理

1pi -c                  # 繼續最近的 session
2pi -r                  # 瀏覽並選擇過去的 session
3pi --no-session        # Ephemeral mode (暫時模式，不儲存)
4pi --name "my task"    # 啟動時設定 session 名稱
5pi --session <path|id> # 使用特定 session
6pi --fork <path|id>    # Fork 特定 session 為新 session

Branching (分支)

• /tree — 在 session 樹中導航，選擇任意節點繼續。支援搜尋、收合展開、filter mode (Ctrl+O 切換：default / no-tools / user-only / labeled-only / all)
• /fork — 從過去的 user message 建立新 session 檔案
• /clone — 複製目前 active branch 到新 session 檔案

4.4 Compaction (上下文壓縮)

長時間對話會耗盡 context window (上下文窗口)。Compaction 將較舊的訊息摘要化，保留近期訊息。

手動壓縮：

1/compact                    # 使用預設策略
2/compact focus on API changes  # 指定摘要重點

自動壓縮： 預設啟用，觸發條件：

• Context overflow (上下文溢出) — 觸發後恢復並重試
• Approaching limit (接近上限) — 主動壓縮

自動壓縮運作流程：

1. 從最新訊息往回走，累計 token 直到 keepRecentTokens（預設 20K）
2. 提取舊訊息交由 LLM 摘要
3. 將 CompactionEntry 寫入 session JSONL
4. Session 重載，使用摘要 + 保留的近期訊息

壓縮是有損的。完整歷史保存在 JSONL 檔案中，可用 /tree 回溯。可透過 extension 自訂壓縮行為。

4.5 Extensions (擴充)

Extension 是 Pi 最強大的功能。一個最小的 extension：

 1// ~/.pi/agent/extensions/hello.ts
 2import { Type } from "@earendil-works/pi-ai";
 3import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 4
 5const helloTool = defineTool({
 6  name: "hello",
 7  label: "Hello",
 8  description: "A simple greeting tool",
 9  parameters: Type.Object({
10    name: Type.String({ description: "Name to greet" }),
11  }),
12  async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
13    return {
14      content: [{ type: "text", text: `Hello, ${params.name}!` }],
15      details: { greeted: params.name },
16    };
17  },
18});
19
20export default function (pi: ExtensionAPI) {
21  pi.registerTool(helloTool);
22}

Extension 放置位置：

• ~/.pi/agent/extensions/ — 全域
• .pi/extensions/ — 專案本地
• Pi Package — 透過 npm 或 git 安裝

Permission gate (權限閘門) 範例：

 1// ~/.pi/agent/extensions/permission-gate.ts
 2import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 3
 4export default function (pi: ExtensionAPI) {
 5  const dangerousPatterns = [
 6    /\brm\s+(-rf?|--recursive)/i,
 7    /\bsudo\b/i,
 8    /\b(chmod|chown)\b.*777/i,
 9  ];
10
11  pi.on("tool_call", async (event, ctx) => {
12    if (event.toolName !== "bash") return undefined;
13
14    const command = event.input.command as string;
15    const isDangerous = dangerousPatterns.some((p) => p.test(command));
16
17    if (isDangerous) {
18      if (!ctx.hasUI) {
19        return { block: true, reason: "Dangerous command blocked" };
20      }
21      const choice = await ctx.ui.select(
22        `Dangerous command:\n\n  ${command}\n\nAllow?`,
23        ["Yes", "No"]
24      );
25      if (choice !== "Yes") {
26        return { block: true, reason: "Blocked by user" };
27      }
28    }
29    return undefined;
30  });
31}

官方範例 extension (70+ 個)：

4.6 Skills (技能)

Skill 是遵循 Agent Skills 標準 的 on-demand (按需) capability package (能力套件)。與 extension 不同，skill 是 Markdown 文件，不執行程式碼本身，而是指導 LLM 完成特定任務。

建立 skill：

 1<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
 2---
 3name: my-skill
 4description: Use this skill when the user asks about X.
 5---
 6
 7# My Skill
 8
 9## Steps
101. Do this
112. Then that
12
13## Scripts
14Run `./scripts/process.sh` to execute.

Skill 放置位置：

• ~/.pi/agent/skills/ — 全域
• ~/.agents/skills/ — 跨工具全域
• .pi/skills/ — 專案本地
• .agents/skills/ — 跨工具專案本地（含向上搜尋至 git root）

使用方式：

• /skill:name — 在互動模式中明確載入
• 自動觸發 — LLM 根據 skill description 判斷是否需要載入

跨工具共用： 可在 settings.json 中加入其他工具的 skill 路徑：

1{
2  "skills": [
3    "~/.claude/skills",
4    "~/.codex/skills"
5  ]
6}

4.7 Pi Packages (套件)

將 extension、skill、prompt、theme 打包為 npm 或 git 套件分享：

 1# 安裝
 2pi install npm:@foo/pi-tools
 3pi install npm:@foo/pi-tools@1.2.3      # 固定版本
 4pi install git:github.com/user/repo
 5pi install git:github.com/user/repo@v1  # 固定 tag 或 commit
 6
 7# 管理
 8pi list                       # 列出已安裝套件
 9pi config                     # 啟用/停用套件資源
10pi update                     # 更新全部
11pi remove npm:@foo/pi-tools   # 移除
12
13# 專案本地安裝
14pi install -l npm:@foo/pi-tools

建立套件： 在 package.json 加入 pi 欄位：

 1{
 2  "name": "my-pi-package",
 3  "keywords": ["pi-package"],
 4  "pi": {
 5    "extensions": ["./extensions"],
 6    "skills": ["./skills"],
 7    "prompts": ["./prompts"],
 8    "themes": ["./themes"]
 9  }
10}

4.8 SDK / RPC (程式化整合)

SDK 嵌入

 1import {
 2  AuthStorage, createAgentSession,
 3  ModelRegistry, SessionManager
 4} from "@earendil-works/pi-coding-agent";
 5
 6const authStorage = AuthStorage.create();
 7const modelRegistry = ModelRegistry.create(authStorage);
 8
 9const { session } = await createAgentSession({
10  sessionManager: SessionManager.inMemory(),
11  authStorage,
12  modelRegistry,
13});
14
15// 訂閱事件
16session.subscribe((event) => {
17  if (event.type === "message_update" &&
18      event.assistantMessageEvent.type === "text_delta") {
19    process.stdout.write(event.assistantMessageEvent.delta);
20  }
21});
22
23// 執行 prompt
24await session.prompt("What files are in the current directory?");

SDK 提供 13 個漸進式範例：

RPC 模式

供非 Node.js 環境整合，透過 stdin/stdout 的 JSONL 協議：

1pi --mode rpc

注意：RPC 使用嚴格 LF 分隔的 JSONL framing。客戶端必須以 \n 分隔 record，不可使用 generic line reader（如 Node readline，它會在 JSON payload 內的 Unicode separator 處斷行）。

4.9 Message Queue (訊息佇列)

在 agent 工作中途可送入訊息：

5. 應用場景

5.1 日常編碼助理

最直接的用法 — 在任何專案目錄啟動 pi，對話式完成開發任務：

1cd my-project
2pi "Refactor the auth module to use JWT instead of session cookies"

5.2 Code Review

1# 唯讀模式，只允許讀取和搜尋
2pi --tools read,grep,find,ls -p "Review this codebase for security issues"

5.3 Multi-Model 工作流

利用 Ctrl+P 快速切換模型，或用 --models 限定循環範圍：

1# 限定可切換的模型
2pi --models "claude-*,gpt-4o"
3
4# 指定 provider + model + thinking level
5pi --model sonnet:high "Solve this complex architectural problem"

5.4 Batch / CI 整合

1# 非互動模式（print mode）
2pi -p "Summarize this codebase"
3
4# 管線輸入
5cat README.md | pi -p "Summarize this text"
6
7# JSON output 模式
8pi --mode json "List all TODO comments"

5.5 Sub-agent 多工任務

使用官方 subagent extension，可將任務委派給 specialized agent (專責代理)：

1# 安裝 subagent extension
2mkdir -p ~/.pi/agent/extensions/subagent
3cp -R path/to/pi/packages/coding-agent/examples/extensions/subagent/* \
4      ~/.pi/agent/extensions/subagent/

支援的 agent 角色：

• scout — 快速偵查，回傳壓縮後的 context
• planner — 建立實作計畫
• reviewer — Code review
• worker — 通用型全能 agent

5.6 Sandbox 開發

1# Docker 容器隔離
2docker run --rm -it \
3  -e ANTHROPIC_API_KEY \
4  -v "$PWD:/workspace" \
5  -v pi-agent-home:/root/.pi/agent \
6  pi-sandbox
7
8# Gondolin micro-VM 隔離
9pi -e ~/.pi/agent/extensions/gondolin

5.7 SDK 嵌入到自有產品

利用 @earendil-works/pi-coding-agent SDK 或 @earendil-works/pi-ai + @earendil-works/pi-agent-core 組合，將 AI coding 能力嵌入自己的應用程式。真實案例：openclaw/openclaw。

6. 資安掃描報告

6.1 掃描範圍

對 Pi monorepo v0.78.1 執行以下掃描：

• Source code grep: eval / exec / token / secret / password / credential
• Dependency 分析：package.json + npm-shrinkwrap.json
• Auth file handling
• Supply-chain hardening 機制檢視

6.2 正面發現

6.3 風險發現

6.4 緩解建議

1. 必做：在非信任環境中使用 container 隔離（Docker / Gondolin / OpenShell）
2. 必做：審查所有第三方 extension 和 skill 的 source code
3. 建議：在 CI/CD 環境使用 --no-session 避免 session 洩漏
4. 建議：使用 --tools flag 限制可用工具（例如唯讀模式）
5. 建議：安裝 permission-gate.ts extension 攔截危險指令

7. FAQ

Q1: Pi 與 Claude Code 最大的區別是什麼？

Pi 是 provider-agnostic (供應商中立) 的開源框架，支援 30+ LLM provider。Claude Code 僅支援 Anthropic 模型但有內建 permission system。Pi 的哲學是「核心極簡、擴充無限」，Claude Code 則是「batteries included (功能完備)」。

Q2: Pi 支援 MCP 嗎？

不內建。Pi 的設計理念認為 MCP 的價值可透過 CLI tool + README (即 skill) 達成，或透過 extension 加入 MCP 支援。參見 Why not MCP?。

Q3: 如何在 Pi 中使用本地模型（如 Ollama）？

在 ~/.pi/agent/models.json 中設定 custom provider：

1{
2  "providers": [{
3    "name": "ollama",
4    "api": "openai",
5    "baseUrl": "http://localhost:11434/v1",
6    "models": [{ "id": "llama3.2", "contextWindow": 128000 }]
7  }]
8}

Q4: 如何安全地在不信任的 repo 中使用 Pi？

1. 啟動時不要信任專案（trust prompt 選 No）
2. 或使用 --no-approve flag
3. 最安全的方式是用 Docker 或 Gondolin 容器隔離

Q5: Session 儲存在哪裡？

~/.pi/agent/sessions/，按工作目錄組織。可用 --session-dir 或 PI_CODING_AGENT_SESSION_DIR 環境變數覆寫。

Q6: 如何離線使用 Pi？

1PI_OFFLINE=1 pi
2# 或
3pi --offline

這會禁用所有啟動時的網路操作（update check、package update check、install telemetry）。

Q7: 如何禁用遙測？

1# 禁用 install/update telemetry
2export PI_TELEMETRY=0
3# 或在 settings.json 中
4{ "enableInstallTelemetry": false }
5
6# 禁用 version check
7export PI_SKIP_VERSION_CHECK=1

Q8: Compaction 會遺失資訊嗎？

Compaction 是有損的摘要，但完整歷史保留在 JSONL session 檔案中。可用 /tree 回到壓縮前的任意節點。可透過 extension 自訂壓縮策略。

Q9: 可以同時跑多個 Pi 實例嗎？

可以。AGENTS.md 中有明確指引：「Multiple pi sessions may be running in this cwd at the same time, each modifying different files.」但 git 操作需小心，只 stage 自己改的檔案。

Q10: 如何使用 extended thinking?

1# CLI flag
2pi --thinking high "Solve this complex problem"
3
4# 模型指定 shorthand
5pi --model sonnet:high "Complex task"
6
7# 互動模式中
8Shift+Tab  # 循環切換 thinking level

Thinking level: off / minimal / low / medium / high / xhigh

8. 進階技巧

8.1 跨 Provider 交接 (Cross-Provider Handoff)

pi-ai 的 Context 是可序列化的，可以在不同 provider 之間無縫交接：

 1import { getModel, stream, Context } from "@earendil-works/pi-ai";
 2
 3const context: Context = {
 4  systemPrompt: "You are helpful.",
 5  messages: [{ role: "user", content: "Analyze this code" }],
 6};
 7
 8// 用 Claude 做分析
 9const claude = getModel("anthropic", "claude-sonnet-4-20250514");
10const result1 = await complete(claude, context);
11context.messages.push(result1);
12
13// 切到 GPT-4o 做 review
14context.messages.push({ role: "user", content: "Now review the analysis" });
15const gpt = getModel("openai", "gpt-4o");
16const result2 = await complete(gpt, context);

8.2 自訂 Compaction 策略

透過 extension 攔截 compact event：

1export default function (pi: ExtensionAPI) {
2  pi.on("compact", async (event, ctx) => {
3    // 自訂摘要邏輯
4    return {
5      summary: "Custom summary of the conversation...",
6      keepRecentTokens: 30000,
7    };
8  });
9}

8.3 Prompt Template (提示範本)

建立可重用的 prompt：

1<!-- ~/.pi/agent/prompts/review.md -->
2Review this code for bugs, security issues, and performance problems.
3Focus on: {{focus}}

使用：在互動模式輸入 /review，Pi 會展開 template 並提示填入 {{focus}}。

8.4 自訂 System Prompt

• 替換：建立 .pi/SYSTEM.md（專案）或 ~/.pi/agent/SYSTEM.md（全域）
• 附加：使用 APPEND_SYSTEM.md
• CLI 覆寫：

1pi --system-prompt "You are a security auditor."
2pi --append-system-prompt "Always check for SQL injection."

8.5 Context Files

Pi 在啟動時載入 AGENTS.md 或 CLAUDE.md（兩者等效），從以下位置串接：

1. ~/.pi/agent/AGENTS.md — 全域
2. 父目錄（從 cwd 往上搜尋，需專案已信任）
3. 目前目錄（需專案已信任）

8.6 Prompt Cache 延長

1export PI_CACHE_RETENTION=long

效果：Anthropic 1 小時 / OpenAI 24 小時（預設為各 provider 的標準 cache TTL）。

8.7 External Editor

Ctrl+G 開啟外部編輯器（由 VISUAL 或 EDITOR 環境變數決定）。

8.8 多 Session 工作流

1# Session 1: 分析
2pi --name "analysis" "Analyze the auth module"
3
4# Session 2: 實作（新終端）
5pi --name "implement" "Implement the changes from analysis"
6
7# Fork 分支
8pi --fork <session-id>

9. 整合其他工作流

9.1 與 CI/CD 整合

1# GitHub Actions 範例
2- name: AI Code Review
3  run: |
4    export ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}
5    npx @earendil-works/pi-coding-agent \
6      --tools read,grep,find,ls \
7      -p "Review the changes in this PR for security issues" \
8      --no-session --no-approve

9.2 與 tmux 整合

Pi 建議用 tmux 替代 background bash：

1# 在 tmux 中測試互動模式
2tmux new-session -d -s pi-test -x 80 -y 24
3tmux send-keys -t pi-test "./pi-test.sh" Enter
4sleep 3 && tmux capture-pane -t pi-test -p
5tmux kill-session -t pi-test

9.3 與 Docker 整合

1FROM node:24-bookworm-slim
2
3RUN apt-get update \
4  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
5  && rm -rf /var/lib/apt/lists/*
6RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
7
8WORKDIR /workspace
9ENTRYPOINT ["pi"]

1docker build -t pi-sandbox -f Dockerfile.pi .
2docker run --rm -it \
3  -e ANTHROPIC_API_KEY \
4  -v "$PWD:/workspace" \
5  -v pi-agent-home:/root/.pi/agent \
6  pi-sandbox

9.4 與 Slack/Chat 整合

earendil-works/pi-chat 提供 Slack 和其他 chat 平台的自動化整合。

9.5 Session 分享

將 coding session 分享到 Hugging Face Dataset：

1# 安裝 pi-share-hf
2git clone https://github.com/badlogic/pi-share-hf
3# 按 README 設定 Hugging Face CLI
4# 發佈 session

9.6 與既有 AI 工具共用 Skill

在 ~/.pi/agent/settings.json 中加入其他工具的 skill 路徑：

1{
2  "skills": [
3    "~/.claude/skills",
4    "~/.codex/skills"
5  ]
6}

10. Checklist

安裝與設定

• 安裝 Pi (npm install -g --ignore-scripts @earendil-works/pi-coding-agent)
• 驗證安裝 (pi --version)
• 設定至少一個 provider（API key 或 subscription login）
• 測試基本對話 (pi "Hello")
• 瀏覽可用模型 (pi --list-models)

安全性

• 決定隔離策略（Docker / Gondolin / OpenShell / 無）
• 安裝 permission-gate.ts extension（可選但建議）
• 審查所有第三方 extension 和 skill 的 source code
• 設定 .pi/settings.json 的 project trust 決定
• 對 CI 環境使用 --no-session 和 --no-approve

自訂化

• 建立 AGENTS.md 或 CLAUDE.md 專案說明
• 建立常用 prompt template（放 ~/.pi/agent/prompts/）
• 評估並安裝需要的 pi package
• 調整 thinking level 預設值
• 設定 keybinding（~/.pi/agent/keybindings.json）

進階

• 建立 project-specific extension（放 .pi/extensions/）
• 建立 project-specific skill（放 .pi/skills/）
• 嘗試 SDK 整合（examples/sdk/01-minimal.ts）
• 嘗試 subagent extension
• 設定 session 分享到 Hugging Face（可選）

11. 進一步閱讀

官方資源

文件頁面（27 頁）

npm 套件

設計哲學文章

• Pi Coding Agent Blog Post — 完整設計理念
• What if you don’t need MCP? — 為何不內建 MCP

相關工具

本教學基於 Pi v0.78.1（2026-06-06），內容可能隨版本更新而變動。建議搭配官方文件閱讀。