Pi Code Agent 教學手冊

# 啟用全部 7 個內建工具
pi --tools read,bash,edit,write,grep,find,ls

# 唯讀模式（Code Review 用）
pi --tools read,grep,find,ls -p "Review the code"

# 禁用所有工具
pi --no-tools

# 禁用內建工具但保留 Extension 工具
pi --no-builtin-tools

# 排除特定工具（保留其餘）
pi --exclude-tools bash,write

// ~/.pi/agent/settings.json — v0.84.2 起可設定啟動預設工具組合
{
  "defaultTools": ["bash", "edit", "write"]
}

# Session 儲存位置
~/.pi/agent/sessions/<encoded-cwd>/

# 也可自訂 Session 目錄
pi --session-dir /path/to/sessions

# 1. 確認 Node.js 版本
node --version  # 需 >= 18

# 2. 全域安裝 Pi Coding Agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 3. 確認安裝成功
pi --version

# 1. 確認 Node.js 版本
node --version  # 需 >= 18

# 2a. 全域安裝（npm）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 2b. 替代方式：使用 Installer Script
curl -fsSL https://pi.dev/install.sh | sh

# 3. 確認安裝
pi --version

# npm 安裝的解安裝
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm 安裝的解安裝
pnpm remove -g @earendil-works/pi-coding-agent

# yarn 安裝的解安裝
yarn global remove @earendil-works/pi-coding-agent

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-xxx

# OpenAI
export OPENAI_API_KEY=sk-xxx

# DeepSeek
export DEEPSEEK_API_KEY=xxx

# Google Gemini(注意:官方環境變數名稱為 GEMINI_API_KEY,並非 GOOGLE_API_KEY)
export GEMINI_API_KEY=xxx

# Google Vertex AI(使用 Application Default Credentials)
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

# Azure OpenAI(Chat Completions 與 Responses API 共用同一組金鑰)
export AZURE_OPENAI_API_KEY=xxx
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# 亦支援 cognitiveservices.azure.com / openai.azure.com,或改用資源名稱:
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Amazon Bedrock
# 使用 AWS CLI 預設認證鏈,或設定:
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx
export AWS_REGION=us-east-1
# 替代方式:Bearer Token(亦可用 /login amazon-bedrock 儲存)
export AWS_BEARER_TOKEN_BEDROCK=xxx

# Mistral
export MISTRAL_API_KEY=xxx

# Groq
export GROQ_API_KEY=xxx

# Cerebras
export CEREBRAS_API_KEY=xxx

# xAI(Grok)——亦可 /login xai 使用 X 訂閱登入
export XAI_API_KEY=xxx

# Ant Ling
export ANT_LING_API_KEY=xxx

# NVIDIA NIM
export NVIDIA_API_KEY=xxx

# Hugging Face
export HF_TOKEN=xxx

# Kimi For Coding(Moonshot AI)
export KIMI_API_KEY=xxx

# MiniMax(國際版)/ MiniMax 中國區(各自獨立金鑰)
export MINIMAX_API_KEY=xxx
export MINIMAX_CN_API_KEY=xxx

# OpenRouter——亦可 /login openrouter 走 PKCE OAuth,由 OpenRouter 額度計費
export OPENROUTER_API_KEY=xxx

# Radius(動態 pi-messages 閘道,建議以 /login radius 取得 OAuth)
export RADIUS_API_KEY=xxx

# Cloudflare AI Gateway 與 Cloudflare Workers AI 共用同一把金鑰,僅差在帳號/閘道參數
export CLOUDFLARE_API_KEY=xxx
export CLOUDFLARE_ACCOUNT_ID=xxx
export CLOUDFLARE_GATEWAY_ID=xxx   # 僅 AI Gateway 需要,於 dash.cloudflare.com 建立

# Fireworks
export FIREWORKS_API_KEY=xxx

# Together AI
export TOGETHER_API_KEY=xxx

# Baseten
export BASETEN_API_KEY=xxx

# Qwen Token Plan(國際版 / Individual 版共用同一組金鑰,僅目錄不同;中國區獨立)
export QWEN_TOKEN_PLAN_API_KEY=xxx
export QWEN_TOKEN_PLAN_CN_API_KEY=xxx

# Xiaomi MiMo(全球)與 Xiaomi MiMo Token Plan(中國 / 阿姆斯特丹 / 新加坡三個區域版本)
export XIAOMI_API_KEY=xxx
export XIAOMI_TOKEN_PLAN_CN_API_KEY=xxx
export XIAOMI_TOKEN_PLAN_AMS_API_KEY=xxx
export XIAOMI_TOKEN_PLAN_SGP_API_KEY=xxx

# ZAI Coding Plan(全球 / 中國區獨立金鑰)
export ZAI_API_KEY=xxx
export ZAI_CODING_CN_API_KEY=xxx

# OpenCode Zen 與 OpenCode Go 共用同一把金鑰
export OPENCODE_API_KEY=xxx

# Vercel AI Gateway(注意:官方環境變數名稱為 AI_GATEWAY_API_KEY,並非 VERCEL_API_KEY)
export AI_GATEWAY_API_KEY=xxx

# llama.cpp 本地路由(見 §4.3.1)
export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret

pi
/login  # 在互動模式中登入

# 1. 以 Router 模式啟動 llama-server(不可傳入 --model / -m,否則會變成單模型模式)
llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

# 2. 在 Pi 中設定連線(或用 LLAMA_BASE_URL / LLAMA_API_KEY 環境變數)
pi
/login llama.cpp

# 3. 管理模型:搜尋、下載、載入、卸載 GGUF 模型(支援直接從 Hugging Face 抓取)
/llama

# 4. 已載入的模型才會出現在 /model 選單中
/model

# 驗證某 Provider 或模型的憑證是否可用(CI 前置檢查極為實用)
pi auth check anthropic

# 匯出目前解析出的 API Key / Bearer Token,供外部工具(如自建 curl 腳本)使用
pi auth print-api-key anthropic
pi auth print-bearer-token amazon-bedrock

# 確認安裝完整性
npm ls -g @earendil-works/pi-coding-agent

# 離線模式（不檢查更新、不送遙測資料）
pi --offline
# 或設定環境變數
export PI_OFFLINE=true

# 進入專案目錄
cd /path/to/your-project

# 建立 Pi 專案配置目錄
mkdir -p .pi/extensions .pi/skills .pi/prompts .pi/themes

# 建立 AGENTS.md（專案指引）
cat > AGENTS.md << 'EOF'
# 專案指引

## 技術棧
- 後端：Java 21 + Spring Boot 3.5
- 前端：Vue 3 + TypeScript + Tailwind CSS
- 資料庫：PostgreSQL 16
- 快取：Redis 7
- 訊息佇列：Kafka 3.x

## 程式碼規範
- 使用 Clean Architecture
- Controller → Service → Repository 分層
- 所有 API 必須有 Swagger 文件
- 測試覆蓋率 > 80%

## 命名規範
- 類別：PascalCase
- 方法/變數：camelCase
- 常數：UPPER_SNAKE_CASE
- 資料表：snake_case
EOF

# 建立全域配置目錄
mkdir -p ~/.pi/agent/prompts ~/.pi/agent/skills ~/.pi/agent/extensions

# 編輯全域設定(鍵名請以官方 settings.md 為準:defaultProvider / defaultModel / defaultThinkingLevel / defaultTools)
cat > ~/.pi/agent/settings.json << 'EOF'
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "enableInstallTelemetry": false,
  "defaultProjectTrust": "ask",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}
EOF

cat > .pi/settings.json << 'EOF'
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "high",
  "defaultTools": ["read", "write", "edit", "bash", "grep", "find", "ls"]
}
EOF

your-project/
├── .pi/                          # Pi 專案配置(需通過 Project Trust 才會載入,見 §6.1)
│   ├── settings.json             # 專案設定（覆蓋全域，唯讀版控用）
│   ├── SYSTEM.md                 # 自訂系統提示（取代預設系統提示;注意路徑在 .pi/ 之下,非專案根目錄)
│   ├── APPEND_SYSTEM.md          # 附加到系統提示末尾（不取代;同樣位於 .pi/ 之下)
│   ├── extensions/               # 專案 Extension
│   ├── skills/                   # 專案 Skill
│   ├── prompts/                  # 專案 Prompt Template
│   ├── themes/                   # 專案 Theme
│   ├── npm/                      # `pi install -l` 安裝的 npm 套件（建議 .gitignore）
│   └── git/                      # `pi install -l` 安裝的 git 套件（建議 .gitignore）
├── .agents/                      # Agent Skills 標準路徑（替代 .pi/skills/）
│   └── skills/                   # 依 Agent Skills 標準組織
├── AGENTS.md                     # 專案指引（Pi 啟動時自動載入,不受 Project Trust 限制,位於專案根目錄）
├── AGENTS.override.md            # v0.84+:若存在,「取代」而非疊加該目錄層的 AGENTS.md/CLAUDE.md(同樣位於根目錄,不受 Project Trust 限制)
├── CLAUDE.md                     # AGENTS.md 的別名（相容 Claude Code 用戶）
├── PLAN.md                       # 開發計畫（手動維護）
├── src/                          # 原始碼
├── test/                         # 測試
└── ...

~/.pi/agent/                      # 全域配置
├── auth.json                     # API Key 與 OAuth Token（建立時權限固定 0600）
├── settings.json                 # 全域設定
├── models.json                   # 自訂模型定義（每次開啟 /model 都會重新讀取，免重啟）
├── keybindings.json              # 自訂快捷鍵（v0.8x 起採命名空間 id,如 tui.editor.cursorUp）
├── trust.json                    # Project Trust 決策紀錄（/trust 寫入）
├── models-store.json             # 各 Provider 型錄快取（供離線使用）
├── sessions/                     # Session 儲存
│   └── <encoded-cwd>/           # 依專案路徑編碼
├── extensions/                   # 全域 Extension
├── skills/                       # 全域 Skill（也支援 ~/.agents/skills/）
├── npm/                          # 全域安裝的 npm Pi Packages
├── git/                          # 全域安裝的 git Pi Packages
├── prompts/                      # 全域 Prompt Template
└── themes/                       # 全域 Theme

# 基本啟動（互動模式）
pi

# 帶初始 Prompt 啟動
pi "列出 src/ 下所有 Java 檔案"

# 繼續上次 Session
pi -c

# 瀏覽並選擇 Session
pi -r

# 無 Session 模式（不儲存歷史）
pi --no-session

# 指定模型啟動
pi --provider anthropic --model claude-sonnet-4-20250514

# 簡寫模型指定
pi --model anthropic/claude-sonnet-4-20250514

# 指定思考等級（含 xhigh 超高思考）
pi --model sonnet:high "解決這個複雜問題"
pi --thinking xhigh "設計整個微服務架構"

# 從先前 Session 分支（fork）
pi --fork <session-id-or-path>

# 恢復指定 Session
pi --session <session-id-or-path>

# 不載入任何 Context Files
pi --no-context-files
pi -nc

# 附加系統提示
pi --append-system-prompt "所有回應使用繁體中文"

# 限制可用工具
pi --tools read,grep,find,ls  # 唯讀模式
pi --no-tools                  # 完全禁用工具

> 請幫我建立一個 UserController，包含 CRUD API，使用 Clean Architecture 分層：
> - Controller：處理 HTTP 請求
> - Service：業務邏輯
> - Repository：資料存取
> - Entity：資料模型
> 使用 JPA + PostgreSQL

> 建立一個 UserList.vue 元件：
> - 使用 Composition API + TypeScript
> - 使用 Tailwind CSS 排版
> - 包含搜尋、分頁功能
> - 呼叫 /api/users GET API

> 在 UserService.java 中新增一個 searchUsers 方法：
> - 參數：keyword (String), pageable (Pageable)
> - 回傳：Page<UserDTO>
> - 支援模糊搜尋 name 和 email

> 執行 Maven 測試

mvn test

!mvn clean compile    # 執行並將輸出傳給 LLM
!!mvn clean compile   # 執行但不傳給 LLM

> 這個測試失敗了，請分析原因：
> @src/test/java/com/example/UserServiceTest.java
> 
> 錯誤訊息：
> java.lang.NullPointerException at UserService.java:42

# 情境範例：Agent 正在修改 UserService.java
# 你突然想到還需要加入驗證邏輯：

Steering（Enter）: "等等，請在 createUser 方法中加入 email 格式驗證"
→ Agent 會在完成當前工具操作後讀取此訊息，改變方向

Follow-up（Alt+Enter）: "完成後請一併寫測試"
→ Agent 會先完成所有手頭工作，然後才處理此訊息

# 為 Session 命名（方便 /resume 搜尋）
pi --name "feature-login-refactor"
pi -n "fix bug #1234"

# 離線模式（不檢查更新、不送遙測）
pi --offline

# 排除特定工具（保留其餘）
pi --exclude-tools bash,write
pi -xt bash,write

# 僅使用 Extension 工具，不載入內建工具
pi --no-builtin-tools
pi -nbt

# 停用所有資源探索，只載入指定的
pi --no-extensions -e ./my-ext.ts  # 僅載入指定 Extension
pi --no-skills --skill ./my-skill  # 僅載入指定 Skill
pi --no-prompt-templates           # 停用 Prompt Template 探索
pi --no-themes                     # 停用 Theme 探索

# 附加系統提示（可重複使用）
pi --append-system-prompt "所有回應使用繁體中文"
pi --append-system-prompt "遵循 Clean Architecture"

# 指定 API Key（覆蓋環境變數）
pi --api-key sk-ant-xxx

# 指定模型循環清單（Ctrl+P 使用）
pi --models "claude-*,gpt-4o"

# 列出可用模型
pi --list-models
pi --list-models "claude"  # 搜尋篩選

# Project Trust 控制（v0.80+ 新增）
pi --approve       # 信任專案本地設定（僅本次）
pi -a              # 簡寫
pi --no-approve    # 忽略專案本地設定（僅本次）
pi -na             # 簡寫

# 實驗性 Fullscreen TUI 模式(v0.84+):逐字稿獨立捲動、常駐編輯器/頁尾、可拖曳捲軸
pi --tui-mode fullscreen

# 指定本次啟動的佈景主題,不寫回 settings.json(v0.84.2+)
pi --use-theme dark
pi --use-theme corporate/dark   # 主題名稱/變體

# 以 @ 前綴直接在啟動參數帶入檔案(等同互動模式輸入 @file)
pi @src/app.ts @src/app.test.ts "Review these together"
pi -p @screenshot.png "這張截圖裡有什麼？"

# 印出回應後退出
pi -p "分析 pom.xml 的依賴是否有安全漏洞"

# 管線輸入
cat README.md | pi -p "幫我翻譯成英文"

# 唯讀模式審查
pi --tools read,grep,find,ls -p "Review src/ 的程式碼品質"

# 指定思考等級
pi -p --thinking high "重構 UserService 為 Clean Architecture"

# 結構化輸出（適合程式處理）
pi --mode json -p "列出所有 TODO" | jq '.result'

# JSON 協議透過 stdin/stdout（適合 IDE 整合）
pi --mode rpc
# 送入 JSON 命令，接收 JSON 事件

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";

// 建構 Model Runtime(內部整合認證與模型型錄)
const modelRuntime = await ModelRuntime.create();

// 建立 Agent Session;未指定 resourceLoader 時預設使用 DefaultResourceLoader
// 會自動探索 Extension / Skill / Prompt Template / Theme / Context Files
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(), // 或改用持久化 Session
  modelRuntime,
});

// 訂閱事件流(串流輸出文字)
session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

// 送出訊息
await session.prompt("請審查 src/main/java 目錄下的 Controller 是否符合 RESTful 規範");

// 進階：多 Session 管理（使用 AgentSessionRuntime / createAgentSessionRuntime()）
// 適合需要同時管理多個 Session 並在運行時替換的場景
// 詳見 docs/sdk.md 與 examples/sdk/(從最小範例到完整控制皆有涵蓋)

~/.pi/agent/AGENTS.md           ← 全域指引（個人偏好）
  ↓
~/projects/company/AGENTS.md    ← 公司層級指引
  ↓
~/projects/company/my-app/AGENTS.md  ← 專案層級指引（cwd）

# 在互動模式中儲存信任決策(僅寫入 trust.json,當次 Session 不會重新載入,需重啟生效)
/trust

# 全域設定預設行為(僅能設定於全域 settings.json,專案層級無法覆寫此欄位)
{
  "defaultProjectTrust": "ask"  // "ask" | "always" | "never"
}

# AGENTS.md - Spring Boot 微服務專案

## 技術棧
- Java 21 + Spring Boot 3.5 + Spring Cloud 2024
- PostgreSQL 16 + Redis 7 + Kafka 3.x
- Vue 3 + TypeScript + Tailwind CSS

## 架構原則
- Clean Architecture：Controller → Service → Repository
- 所有 API 必須有 OpenAPI 3.0 文件
- 禁止在 Controller 中寫業務邏輯

## 程式碼規範
- 測試覆蓋率 > 80%
- 所有 public 方法需有 JavaDoc
- 使用 Lombok @Slf4j 記錄日誌
- 例外處理使用 @ControllerAdvice

## 禁止事項
- 不得使用 System.out.println
- 不得在程式碼中硬編碼密碼或金鑰
- 不得跳過測試

# 範例：使用 .pi/SYSTEM.md 建構唯讀稽核 Agent
mkdir -p .pi
cat > .pi/SYSTEM.md << 'EOF'
You are a code auditor. You can only use read, grep, and find tools.
Never modify any files. Report findings in a structured format.
EOF

# 範例：附加安全檢查到現有提示
cat > .pi/APPEND_SYSTEM.md << 'EOF'
## Additional Security Requirements
- Always check for SQL injection vulnerabilities
- Flag any hardcoded credentials
- Verify input validation on all API endpoints
EOF

# PLAN.md - 使用者管理模組

## 專案資訊
- **模組名稱**：User Management
- **負責人**：@chihhung
- **Sprint**：Sprint 23（2026/04/21 - 2026/05/02）
- **狀態**：🔄 進行中

## 目標
建立完整的使用者管理功能，包含 CRUD、搜尋、權限控制。

## 任務分解

### Phase 1：後端 API（預估 3 天）

- [x] 建立 User Entity + JPA 設定
- [x] 建立 UserRepository
- [ ] 建立 UserService（含業務邏輯）
  - [ ] createUser()
  - [ ] updateUser()
  - [ ] deleteUser()
  - [ ] searchUsers()
- [ ] 建立 UserController
  - [ ] POST /api/users
  - [ ] PUT /api/users/{id}
  - [ ] DELETE /api/users/{id}
  - [ ] GET /api/users?keyword=xxx&page=0&size=20
- [ ] 建立 UserDTO + Mapper
- [ ] 撰寫 JUnit 測試（覆蓋率 > 80%）

### Phase 2：前端 UI（預估 2 天）

- [ ] UserList.vue - 使用者列表
- [ ] UserForm.vue - 新增/編輯表單
- [ ] UserDetail.vue - 使用者詳情
- [ ] API 整合（axios）
- [ ] 元件測試

### Phase 3：進階功能（預估 2 天）

- [ ] 角色權限（RBAC）
- [ ] 操作日誌（Audit Log）
- [ ] 匯出 Excel

## 技術決策
- 使用 Spring Data JPA Specification 做動態查詢
- DTO 轉換使用 MapStruct
- 密碼加密使用 BCrypt
- API 文件使用 SpringDoc OpenAPI

## 注意事項
- 所有 API 需加入 @PreAuthorize 權限控制
- 密碼欄位不得出現在 Response 中
- 刪除改用軟刪除（isDeleted flag）

# Sprint 23 PLAN.md

## Sprint 目標
完成使用者管理模組的後端 API 與前端 UI。

## 每日任務安排

### Day 1（Mon）
- [ ] 設計 DB Schema（users, roles, user_roles）
- [ ] 建立 Entity + Repository
- [ ] Pi Prompt: "根據 PLAN.md 的 DB Schema 建立 JPA Entity"

### Day 2（Tue）
- [ ] 建立 Service Layer
- [ ] Pi Prompt: "建立 UserService，實作 PLAN.md Phase 1 的所有方法"

### Day 3（Wed）
- [ ] 建立 Controller + DTO
- [ ] 撰寫 Swagger 文件
- [ ] Pi Prompt: "建立 UserController，使用 SpringDoc 註解"

### Day 4（Thu）
- [ ] 撰寫 JUnit 測試
- [ ] Pi Prompt: "為 UserService 撰寫完整的 JUnit 5 測試"

### Day 5（Fri）
- [ ] 前端 UserList.vue
- [ ] Pi Prompt: "建立 UserList.vue，使用 Composition API + Tailwind"

## Retrospective（Sprint 結束後填寫）
- 什麼做得好：
- 什麼需要改進：
- Pi 使用心得：

> 請讀取 PLAN.md，然後開始執行 Phase 1 中尚未完成的第一個任務

> @PLAN.md 目前進度到哪了？請繼續下一個待辦事項

> 我完成了 UserService，請更新 PLAN.md 將該項標記為完成，
> 並告訴我下一步該做什麼

<!-- .pi/prompts/review.md -->
請對以下程式碼進行 Code Review，檢查：

1. **安全性**：SQL Injection、XSS、CSRF、敏感資訊洩漏
2. **效能**：N+1 Query、不必要的迴圈、記憶體洩漏
3. **可維護性**：命名規範、方法長度、單一職責
4. **測試**：是否有對應測試、邊界條件
5. **Clean Architecture**：是否違反分層規則

目標檔案：{{file}}

請用表格格式輸出發現的問題，包含：嚴重度、行號、問題描述、建議修改。

/review

<!-- .pi/prompts/gen-test.md -->
請為 {{file}} 生成完整的 JUnit 5 測試：

要求：
1. 使用 @ExtendWith(MockitoExtension.class)
2. 每個 public 方法至少 3 個測試案例（正常、邊界、異常）
3. 使用 @DisplayName 描述測試目的
4. Mock 外部依賴
5. 使用 AssertJ 斷言
6. 測試覆蓋率目標 > 80%

---
argument-hint: 要產生 API 的資源名稱（如 User, Order）
---
請為 {{input}} 資源建立完整的 RESTful API：

1. Entity + JPA 註解
2. Repository（Spring Data JPA）
3. Service（含 DTO 轉換）
4. Controller（含 Swagger 註解）
5. JUnit 測試

{
  "skills": ["~/.claude/skills", "~/.codex/skills"]
}

<!-- .pi/skills/db-migration/SKILL.md -->
# Database Migration Skill

使用此 Skill 管理資料庫 Schema 遷移。

## 工具

### flyway-migrate

執行 Flyway 遷移：

```bash
mvn flyway:migrate
```

### flyway-info

查看遷移狀態：

```bash
mvn flyway:info
```

## 步驟

1. 在 `src/main/resources/db/migration/` 下建立遷移檔案
2. 命名規範：`V{版號}__{描述}.sql`（如 `V1.0__create_users_table.sql`）
3. 執行 `flyway-migrate` 套用變更
4. 執行 `flyway-info` 確認狀態

## 注意事項

- 已套用的遷移檔案**不可修改**
- 使用 `V` 前綴做版本遷移，`R` 前綴做可重複遷移
- 生產環境遷移前必須先在 SIT/UAT 驗證

/skill:db-migration

pi starts
  ├─► project_trust（僅使用者/全域與 CLI -e Extension 參與,決定是否信任專案）
  ├─► session_start { reason: "startup" }
  └─► resources_discover { reason: "startup" }
      │
user sends prompt ─────────────────────────────────────────┐
  ├─► （Extension 命令優先比對，命中則直接執行並跳過 input 事件）      │
  ├─► input（可攔截、轉換或處理；此時 /skill:xxx、/template 尚未展開） │
  ├─► （若未攔截，展開 Skill / Prompt Template）                    │
  ├─► before_agent_start（可注入訊息、修改系統提示）                 │
  ├─► agent_start                                                  │
  ├─► message_start / message_update / message_end（訊息串流生命週期）│
  │   ┌─── turn（LLM 呼叫工具時重複） ───────────────────┐          │
  │   ├─► turn_start                                     │          │
  │   ├─► context（可修改訊息歷史）                        │          │
  │   ├─► before_provider_headers（可增刪 HTTP 標頭）      │          │
  │   ├─► before_provider_request（可檢視/替換請求 payload）│          │
  │   ├─► after_provider_response（HTTP 狀態碼與標頭）      │          │
  │   │     ├─► tool_execution_start                      │          │
  │   │     ├─► tool_call（可阻擋、可修改參數）              │          │
  │   │     ├─► tool_execution_update（串流進度）           │          │
  │   │     ├─► tool_result（可修改結果）                   │          │
  │   │     └─► tool_execution_end                        │          │
  │   └─► turn_end                                        │          │
  ├─► agent_end                                                    │
  └─► agent_settled（確認不會再自動重試/壓縮/接續執行）                │
                                                                     │
user 送出下一則訊息 ◄─────────────────────────────────────────────────┘

/model 或 Ctrl+P 循環模型      → model_select（含 thinking_level_select,若思考等級隨模型變動）
思考等級變更                    → thinking_level_select
!/!! 使用者輸入的 Shell 命令     → user_bash（可攔截、轉發至遠端如 SSH，或完全取代結果）
/compact 或自動壓縮觸發          → session_before_compact → session_compact
/tree 導覽                     → session_before_tree → session_tree
/new、/resume                  → session_before_switch → session_shutdown → session_start
/fork、/clone                  → session_before_fork → session_shutdown → session_start
退出（Ctrl+C/Ctrl+D/SIGTERM）   → session_shutdown

// .pi/extensions/git-checkpoint.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // 在每次工具呼叫後自動 Git Commit
  pi.on("tool_result", async (event, ctx) => {
    if (event.toolName === "write" || event.toolName === "edit") {
      const filePath = event.args?.filePath || event.args?.file_path;
      if (filePath) {
        await ctx.bash(`git add ${filePath} && git commit -m "pi: auto-checkpoint ${filePath}" --no-verify`, {
          silent: true,
        });
      }
    }
  });

  // 註冊 rollback 命令
  pi.registerCommand("rollback", {
    description: "回滾到上一個 Git checkpoint",
    handler: async (args, ctx) => {
      await ctx.bash("git log --oneline -10");
      ctx.ui.notify("使用 git revert <commit> 來回滾特定變更", "info");
    },
  });
}

// .pi/extensions/permission-gate.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    // 攔截危險的 bash 命令
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("⚠️ 危險操作", "確定要執行 rm -rf 嗎？");
      if (!ok) return { block: true, reason: "使用者取消了危險操作" };
    }
  });
}

// .pi/extensions/deploy-tool.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "deploy",
    label: "Deploy",
    description: "部署應用程式到指定環境",
    parameters: Type.Object({
      // 使用 StringEnum 確保 Google API 相容性
      environment: StringEnum(["dev", "sit", "uat"] as const, {
        description: "目標環境",
      }),
      version: Type.String({ description: "版本號（如 1.2.3）" }),
    }),
    // 注意參數順序：(toolCallId, params, signal, onUpdate, ctx) —— signal 在 onUpdate 之前，ctx 最後
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      if (params.environment === "prod") {
        return {
          content: [{ type: "text", text: "生產環境部署必須透過 CI/CD Pipeline" }],
          details: { blocked: true },
        };
      }

      ctx.ui.notify(`開始部署 v${params.version} 到 ${params.environment}...`, "info");

      const result = await ctx.bash(
        `./scripts/deploy.sh --env ${params.environment} --version ${params.version}`
      );

      return {
        content: [{ type: "text", text: result }],
        details: { environment: params.environment, version: params.version },
      };
    },
  });
}

import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { readFile, writeFile } from "node:fs/promises";
import { resolve } from "node:path";

async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
  const absolutePath = resolve(ctx.cwd, params.path);

  // 佇列化整個讀取-修改-寫入操作
  return withFileMutationQueue(absolutePath, async () => {
    const current = await readFile(absolutePath, "utf8");
    const next = current.replace(params.oldText, params.newText);
    await writeFile(absolutePath, next, "utf8");

    return {
      content: [{ type: "text", text: `Updated ${params.path}` }],
      details: {},
    };
  });
}

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_event, ctx) => {
    // 從 GitHub CLI 預載 issue 列表
    const result = await pi.exec("gh", ["issue", "list", "--json", "number,title", "-L", "50"]);
    const issues = JSON.parse(result.stdout || "[]");

    ctx.ui.addAutocompleteProvider((current) => ({
      triggerCharacters: ["#"],
      async getSuggestions(lines, line, col, options) {
        const beforeCursor = (lines[line] ?? "").slice(0, col);
        const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
        if (!match) return current.getSuggestions(lines, line, col, options);

        return {
          prefix: `#${match[1] ?? ""}`,
          items: issues.map((i: any) => ({
            value: `#${i.number}`,
            label: `#${i.number}`,
            description: i.title,
          })),
        };
      },
      applyCompletion: current.applyCompletion,
      shouldTriggerFileCompletion: current.shouldTriggerFileCompletion,
    }));
  });
}

import { CustomEditor, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { matchesKey } from "@earendil-works/pi-tui";

class VimEditor extends CustomEditor {
  private mode: "normal" | "insert" = "insert";

  handleInput(data: string): void {
    if (matchesKey(data, "escape") && this.mode === "insert") {
      this.mode = "normal";
      return;
    }
    if (this.mode === "normal" && data === "i") {
      this.mode = "insert";
      return;
    }
    super.handleInput(data); // 委派給內建的 app 快捷鍵 + 文字編輯
  }
}

export default function (pi: ExtensionAPI) {
  pi.on("session_start", (_event, ctx) => {
    ctx.ui.setEditorComponent((_tui, theme, keybindings) =>
      new VimEditor(theme, keybindings)
    );
  });
}

> 幫我寫一個 Pi Extension，功能如下：
> 1. 註冊一個 /stats 命令，顯示目前專案的程式碼統計（行數、檔案數）
> 2. 在每次 Session 開始時，自動載入 PLAN.md 的內容
> 3. 把 Extension 放在 .pi/extensions/ 目錄下

// package.json
{
  "name": "@myteam/pi-enterprise-tools",
  "version": "1.0.0",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

# 從 npm 安裝
pi install npm:@myteam/pi-enterprise-tools

# 從 npm 安裝指定版本（pinned version）
pi install npm:@myteam/pi-enterprise-tools@1.2.3

# 從 Git 安裝（支援多種 URL 格式）
pi install git:github.com/myteam/pi-enterprise-tools
pi install git:github.com/myteam/pi-enterprise-tools@v1.3.0  # pin 到 tag
pi install git:git@github.com:myteam/pi-enterprise-tools       # SSH 格式
pi install https://github.com/myteam/pi-enterprise-tools        # HTTPS 格式(不加 git: 前綴時僅接受完整協議網址)
pi install ssh://git@github.com/myteam/pi-enterprise-tools      # SSH URL 格式

# 從本機路徑安裝(適合企業內部尚未發佈到 npm/git 的套件,僅登記路徑不會複製檔案)
pi install /absolute/path/to/my-package
pi install ./relative/path/to/my-package

# 專案本地安裝（僅當前專案，寫入 .pi/settings.json,不影響全域）
pi install npm:@myteam/pi-enterprise-tools -l

# 僅本次執行試用套件(裝進暫存目錄,不寫入任何 settings.json)
pi -e npm:@myteam/pi-enterprise-tools
pi -e git:github.com/myteam/pi-enterprise-tools

# 列出已安裝套件
pi list

# 更新所有套件（跳過 pinned 版本）
pi update

# 更新 Pi 本體 + 所有已安裝套件（含 reconcile pinned git refs）
pi update --all

# 僅更新 Pi 本體
pi update --self

# 強制重新安裝 Pi 本體
pi update --self --force

# 僅更新所有已安裝 Extension 套件（含 reconcile pinned git refs）
pi update --extensions

# 僅重新整理模型型錄快取(不更新套件本身)
pi update --models

# 更新特定套件（--extension 為單數形式,與 --extensions 複數形式意義不同）
pi update npm:@myteam/pi-enterprise-tools
pi update --extension npm:@myteam/pi-enterprise-tools

# 移除套件（remove 與 uninstall 為同義）
pi remove npm:@myteam/pi-enterprise-tools
pi uninstall npm:@myteam/pi-enterprise-tools

# 啟用/停用已安裝資源(全域模式,按 Tab 切換至專案模式)
pi config
# 直接以專案覆寫模式開啟(全域資源以淡色顯示)
pi config -l

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:@myteam/pi-enterprise-tools",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

// .pi/themes/corporate.json
{
  "name": "Corporate Blue",
  "colors": {
    "primary": "#0078D4",
    "secondary": "#106EBE",
    "accent": "#FFB900",
    "background": "#1E1E1E",
    "text": "#D4D4D4",
    "success": "#4CAF50",
    "error": "#F44336",
    "warning": "#FF9800"
  }
}

{
  "theme": "corporate"
}

> @PLAN.md 請針對使用者管理模組進行威脅模型分析（Threat Modeling），
> 使用 STRIDE 方法，並產出安全設計文件

<!-- .pi/prompts/secure-code.md -->
請在撰寫程式碼時遵循以下安全規範：

1. **輸入驗證**：所有外部輸入必須驗證（使用 Jakarta Validation）
2. **SQL 防注入**：使用 JPA Parameterized Query，禁止字串拼接
3. **XSS 防護**：輸出編碼，使用 OWASP Java Encoder
4. **CSRF 防護**：啟用 Spring Security CSRF Token
5. **認證授權**：使用 @PreAuthorize 控制 API 存取
6. **敏感資料**：密碼使用 BCrypt，日誌不得記錄敏感欄位
7. **錯誤處理**：不得將堆疊追蹤回傳給客戶端
8. **依賴安全**：不使用已知漏洞的依賴

# 使用唯讀模式進行安全審查
pi --tools read,grep,find,ls -p \
  "請對 src/main/java/com/example/controller/ 目錄下的所有 Controller 進行安全審查，
   檢查 OWASP Top 10 風險，以表格格式輸出結果"

<!-- .pi/skills/security-scan/SKILL.md -->
# Security Scan Skill

## SAST（靜態分析）
```bash
# SpotBugs 安全掃描
mvn spotbugs:check

# SonarQube 掃描
mvn sonar:sonar -Dsonar.host.url=http://sonarqube:9000
```

## Dependency Scan
```bash
# OWASP Dependency Check
mvn org.owasp:dependency-check-maven:check
```

## 步驟
1. 執行 SAST 掃描
2. 分析報告
3. 修復發現的漏洞
4. 重新掃描驗證

# .github/workflows/ssdlc.yml
name: SSDLC Pipeline

on:
  pull_request:
    branches: [main, develop]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'

      - name: SAST - SpotBugs
        run: mvn spotbugs:check

      - name: Dependency Check
        run: mvn org.owasp:dependency-check-maven:check

      - name: Unit Tests
        run: mvn test

      - name: AI Code Review (Pi)
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g --ignore-scripts @earendil-works/pi-coding-agent
          # --approve 用於信任專案內 .pi/(prompts、skills 等),CI 為非互動模式,
          # 若省略此旗標,預設 defaultProjectTrust=ask 會直接略過受信任範圍內的專案資源
          pi --approve --tools read,grep,find,ls -p \
            "Review all changed files for security issues. Output as JSON." \
            --mode json > review-results.json

      - name: Upload Results
        uses: actions/upload-artifact@v4
        with:
          name: security-reports
          path: |
            target/spotbugsXml.xml
            target/dependency-check-report.html
            review-results.json

> 請幫我用 Spring Initializr 建立一個 Spring Boot 3.5 專案：
> - Group: com.example
> - Artifact: task-manager
> - Dependencies: Spring Web, Spring Data JPA, PostgreSQL Driver,
>   Spring Validation, SpringDoc OpenAPI
> - Java 21
> - 使用 Maven

> 設計 Task Manager 的資料庫 Schema：
> 
> tasks 表：
> - id (BIGSERIAL, PK)
> - title (VARCHAR 200, NOT NULL)
> - description (TEXT)
> - status (VARCHAR 20: TODO/IN_PROGRESS/DONE)
> - priority (VARCHAR 10: LOW/MEDIUM/HIGH)
> - assignee (VARCHAR 100)
> - due_date (TIMESTAMP)
> - created_at (TIMESTAMP, DEFAULT NOW())
> - updated_at (TIMESTAMP)
> - is_deleted (BOOLEAN, DEFAULT FALSE)
> 
> 請產生 Flyway 遷移腳本 V1.0__create_tasks_table.sql

> 根據 tasks 表建立完整的後端程式碼：
> 
> 1. TaskEntity.java - JPA Entity
> 2. TaskRepository.java - Spring Data JPA Repository
> 3. TaskService.java - 業務邏輯（含 DTO 轉換）
> 4. TaskController.java - REST API Controller
> 5. TaskDTO.java - 資料傳輸物件
> 6. TaskStatus.java / TaskPriority.java - Enum
> 
> API 規格：
> - POST   /api/tasks         建立任務
> - GET    /api/tasks          查詢任務列表（支援分頁、篩選）
> - GET    /api/tasks/{id}     查詢單一任務
> - PUT    /api/tasks/{id}     更新任務
> - DELETE /api/tasks/{id}     軟刪除任務
> 
> 要求：
> - 使用 Clean Architecture 分層
> - 加入 Jakarta Validation
> - 加入 SpringDoc Swagger 註解
> - 使用 Specification 做動態查詢

> 為 TaskService 撰寫完整的 JUnit 5 測試：
> - 使用 MockitoExtension
> - 每個方法至少 3 個測試案例
> - 包含正常流程、邊界條件、異常處理
> - 使用 AssertJ 斷言

> 使用 Vue 3 + TypeScript + Tailwind CSS 建立前端頁面：
> 
> 1. TaskList.vue - 任務列表頁
>    - 表格顯示所有任務
>    - 支援狀態篩選、搜尋
>    - 分頁功能
>    
> 2. TaskForm.vue - 新增/編輯任務的表單
>    - 表單驗證
>    - 日期選擇器
>    
> 3. api/taskApi.ts - API 呼叫層
>    - 使用 axios
>    - 統一錯誤處理

> 建立部署配置：
> 
> 1. Dockerfile（多階段建置）
> 2. docker-compose.yml（含 PostgreSQL）
> 3. application-dev.yml
> 4. application-prod.yml（敏感資訊用環境變數）

# Session 儲存位置
ls ~/.pi/agent/sessions/

# 匯出 Session 為 HTML（方便閱讀與分享）
pi --export session-file.jsonl output.html

# 上傳為 GitHub Gist 分享
# 在互動模式中使用 /share 命令

# 定期清理過舊的 Session
find ~/.pi/agent/sessions/ -name "*.jsonl" -mtime +30 -delete

# 保留重要 Session（加入 Git 追蹤）
cp ~/.pi/agent/sessions/important-session.jsonl \
   ./docs/ai-sessions/

# 使用 JSON 模式監控 Agent 行為
pi --mode json -p "執行安全掃描" 2>&1 | tee agent-log.json

# 監控 Token 使用量
# 在互動模式中，Footer 會即時顯示：
# - Total Tokens
# - Cache Usage
# - Cost（美元）

/session
# 輸出：
# Session ID: abc123
# Messages: 45
# Total Tokens: 125,000
# Cache Tokens: 89,000
# Cost: $0.42

# Verbose 模式啟動（顯示詳細載入資訊）
pi --verbose

# 延長 Prompt Cache（降低重複成本）
export PI_CACHE_RETENTION=long
# Anthropic: 1 小時快取
# OpenAI: 24 小時快取

// ~/.pi/agent/settings.json 或 .pi/settings.json
{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "branchSummary": {
    "reserveTokens": 16384,
    "skipPrompt": false
  }
}

# 檢視 Session 檔案最後一筆記錄(可用於監控腳本判斷是否已完成回應)
tail -n 1 ~/.pi/agent/sessions/<encoded-cwd>/<session-id>.jsonl

# 搭配 jq 統計某 Session 中所有 assistant 訊息的累積花費
jq -s '[.[] | select(.type=="message" and .message.role=="assistant") | .message.usage.cost.total // 0] | add' \
  session-file.jsonl

# 查看當前版本
pi --version

# 升級到最新版（建議方式）
pi update --self

# 強制重新安裝（即使版本相同）
pi update --self --force

# 或使用 npm 手動升級
npm update -g @earendil-works/pi-coding-agent

# 安裝特定版本
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.2

# 查看更新日誌
# 在互動模式中
/changelog

# 建議將 Pi 配置納入 Git 版控
your-project/
├── .pi/
│   ├── settings.json          # Git 追蹤
│   ├── extensions/            # Git 追蹤
│   │   ├── git-checkpoint.ts
│   │   └── permission-gate.ts
│   ├── skills/                # Git 追蹤
│   ├── prompts/               # Git 追蹤
│   └── .gitignore             # 排除 npm/git 安裝的套件
├── AGENTS.md                  # Git 追蹤
├── PLAN.md                    # Git 追蹤
└── ...

# 安裝的第三方套件
npm/
git/

# 前置需求
# 1. Hugging Face 帳戶
# 2. Hugging Face CLI
# 3. pi-share-hf 工具

# 安裝 pi-share-hf
git clone https://github.com/badlogic/pi-share-hf
cd pi-share-hf
# 依照 README.md 完成設定

# Pi 內建的分享方式
/share  # 上傳為 private GitHub Gist，產生可分享 HTML 連結
/export session.html  # 匯出為 HTML 檔案

# 在專案根目錄放置 .nvmrc
echo "20" > .nvmrc

# 在 AGENTS.md 中明確指定規範
# 所有成員使用相同的 AGENTS.md

❌ 不好的 Prompt：
"幫我寫一個 API"

✅ 好的 Prompt：
"建立 GET /api/tasks API，支援以下查詢參數：
- status (enum: TODO/IN_PROGRESS/DONE)
- priority (enum: LOW/MEDIUM/HIGH)
- keyword (模糊搜尋 title 和 description)
- page (預設 0)
- size (預設 20)
回傳 Page<TaskDTO>，使用 Spring Data JPA Specification"

✅ 好的做法：
> @src/main/java/com/example/entity/Task.java
> @src/main/java/com/example/repository/TaskRepository.java
> 基於這些既有檔案，建立 TaskService

✅ 好的做法：
第一步：> 建立 TaskEntity.java
第二步：> 確認後，建立 TaskRepository.java
第三步：> 確認後，建立 TaskService.java

❌ 不好的做法：
> 幫我一次建立完整的後端，包含 Entity、Repository、Service、Controller、Test

（Pi 正在寫 Service...）
> 記得加入交易管理 @Transactional
（Pi 收到後會在當前工具完成後調整）

問題：在同一個 Session 中做了太多不同的事，AI 開始混淆上下文。
解法：一個功能一個 Session。用 /new 開新 Session。

問題：AI 生成了不存在的 API 或方法。
解法：
1. 提供明確的上下文（@file）
2. 使用高思考等級（--thinking high）
3. 要求 AI 先讀取相關檔案再回答

問題：全域和專案層級的 Prompt Template 名稱衝突。
解法：專案層級優先。使用有意義的命名前綴，如 proj-review。

問題：Pi 升級後自訂 Extension 無法載入。
解法：
1. 查看 CHANGELOG 中的 Breaking Changes
2. 使用 --verbose 查看錯誤訊息
3. 更新 Extension API 呼叫

問題：月底發現 API 費用超出預算。
解法：
1. 使用 /session 定期檢視成本
2. 簡單任務用低成本模型（Ctrl+P 切換）
3. 善用 Prompt Cache（PI_CACHE_RETENTION=long）
4. Code Review 用唯讀模式（--tools read）

# 安裝範例 Extension(需 Node.js >= 23.6.0 供 @earendil-works/gondolin 使用,並透過套件管理器安裝 QEMU)
cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts

# 於欲掛載的專案目錄中啟動
cd /path/to/project
pi -e ~/.pi/agent/extensions/gondolin

# Dockerfile.pi-agent
FROM node:20-slim

# 安裝 Pi
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 安裝常用工具
RUN apt-get update && apt-get install -y git curl jq && rm -rf /var/lib/apt/lists/*

# 設定非 root 使用者
RUN useradd -m -s /bin/bash piuser
USER piuser
WORKDIR /workspace

ENTRYPOINT ["pi"]

# 建構映像
docker build -f Dockerfile.pi-agent -t pi-agent .

# 執行（掛載專案目錄，傳入 API Key）
docker run --rm -it \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  pi-agent -p "Review the code for security issues"

# CI/CD 中的唯讀審查模式
docker run --rm \
  -v $(pwd):/workspace:ro \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  pi-agent --tools read,grep,find,ls -p "Audit this codebase"

# 1. 註冊並選定閘道(僅需執行一次)
openshell gateway add <gateway-url> --name <name>
openshell gateway select <name>

# 2. 建立沙箱並在其中啟動 pi(整個 pi 行程,含內建工具、!命令、Extension 皆在沙箱邊界內執行)
openshell sandbox create --name pi-sandbox --from pi -- pi

openshell sandbox upload pi-sandbox ./repo /workspace
openshell sandbox download pi-sandbox /workspace/repo ./repo-out