# 策展 · X (Twitter) 🔥

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

> 作者：WquGuru🦀 (@wquguru) · 平台：X (Twitter) · 日期：2026-05-19

> 原始來源：https://x.com/wquguru/status/2056235143623495975

## 中文摘要

# Pi Coding Agent 最全面指南（完美支援 /goal）

如果你已經習慣 Claude Code，Pi 第一眼不會顯得更省心。Claude Code 的優勢是把 subagents、Plan Mode、MCP、權限、上下文壓縮、skills、commands 這些工程特性都焊進產品裡，開箱即用。

但如果你想認真測試非 Anthropic 模型時，Claude Code 未必是最乾淨的環境。模型能力、Claude Code 自身的工作流假設、非 Anthropic 模型的適配摩擦，會混在一起，很難拆開判斷。

Pi 的意義就在這裡：

> Pi 不是另一個 Claude Code，而是一個更可拆解的 Agent 底座。使用者自主決定裝哪些組件、給多少上下文、什麼時候 high / xhigh、哪些工具進入 prompt。代價是要會配置；收益是測試模型時更透明、更可控、更容易復現。

所以我寫這篇文章只做一件事：給 Claude Code 使用者一張 Pi 遷移地圖。看完應該知道 Pi 和 Claude Code 怎麼對應，模型在 Pi 裡怎麼配，最小可用棧（stack）是什麼，哪些坑會影響效果，以及為什麼模型特別需要 plan-first + skill 工作流。

如果只想直接復現，文末有我寫好的 skill，可以一鍵安裝 Pi 並配置好模型。下圖是我用本配置實現的現貨-永續 Carry 監控台（對於套利的朋友來說，一定很熟悉😄）

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

## 一、先給 Claude Code 使用者一張地圖

Claude Code 使用者理解 Pi，最重要的是先換一個心智模型。

Claude Code 是產品化的一整套工程環境。使用者不太需要關心哪些工具被注入上下文、哪些生命週期事件觸發、權限和 Plan Mode 怎麼拼起來。它預設就給你一套強約束工作流。

Pi 是 minimal core：CLI（@earendil-works/pi-coding-agent）+ pi-agent-core + 多 provider 的 pi-ai。核心內建 Tools 極少，基本只有讀寫檔案加 grep/find/ls。你熟悉的那些能力，很多都不是 core，而是擴充套件，大概分四類：

- TypeScript Extensions：用程式碼掛載生命週期事件，對應 Claude Code hooks，但不是宣告式 JSON，而是可以寫邏輯的擴充程式碼

- Skills：SKILL.md + 腳本，和 Claude Code skills 是同一類東西

- Prompt Templates：對應 Claude Code slash commands

- Pi Packages：透過 `pi install npm:<pkg>` 或 `pi install git:<repo>` 安裝，也可以 `-l` 裝到專案級

配置主要在 `~/.pi/agent/`：

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

Pi 註冊的所有 Tools 大約只佔 7.7k 上下文。Pi 不預設給你全家桶，它的設計哲學決定了裝什麼的決定權在於使用者，這裡我給出一個判斷：

> 如果要開箱即用，繼續用 Claude Code 或 Codex
> 如果要更乾淨地測試 Ring、控制上下文預算、接任意 OpenAI 相容模型，Pi 更適合

## 二、Pi <-> Claude Code 對照表

這張表是 Claude Code 使用者理解 Pi 的最短路徑：

- 第一，Pi 的能力很完備，只是把能力拆開了，subagent、plan、MCP、web、context prune 這些東西都能支援；

- 第二，Pi 當然也有缺口，CLAUDE.md 式持久記憶、權限規則引擎、強制唯讀 Plan gate、官方 marketplace 和發現 UI，都沒有 Claude Code 那麼完整；

- 第三，Pi 在模型層更開放（毋庸置疑的優勢）。它能接任意 OpenAI 相容 provider，也能顯式做 fallback chain，這正是我們接 Ring-2.6-1T 的入口。

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

## 三、以開源模型 Ring-2.6-1T 為例，在 Pi 裡的推薦模型配置

為什麼選 Ring-2.6-1T，很簡單，它是 HuggingFace 上最近開源的模型，參數量達到驚人的 1T（1000B），很適合用來測試最新模型的能力。要完整發揮價值，也有一些約束：

> 目標給清楚、上下文給足、流程明確，它擅長先拆解、再落地，把複雜任務持續推進到可用結果

所以 Pi 這套配置的目標，是給模型一個更乾淨的 Agent 執行環境：上下文少一點、工具清楚一點、reasoning effort 可控一點、skill 工作流明確一點。

### provider 選擇

Pi 的 provider 分兩類，處理方式完全不同。

- DeepSeek = 內建 provider：只給 key，絕不手配 `models.json`。內建 provider 的規格會隨 `pi update` 維護，你手抄一份反而可能固化舊值。

- Ring-2.6-1T = 自定義 provider：需要手填 `models.json`。

接 Ring 時，我選 OpenAI 相容端點 `/v1`，而不是 Anthropic 相容層。

原因：Anthropic 相容層通常是薄包裝，`cache_control`、thinking blocks、tool schema 這些特性容易在轉換裡丟失；OpenAI shape 是 vLLM/SGLang 常見匯出路徑，國內廠商對這個形態調 bug 最多，相容性更穩。

這是我最後定下來的 `models.json` 關鍵片段：

```json
{
  "providers": {
    "ant-ling": {
      "baseUrl": "https://api.ant-ling.com/v1",
      "api": "openai-completions",
      "apiKey": "!zsh -ic 'echo $LING_API_KEY' 2>/dev/null | tail -1",
      "authHeader": true,
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "Ring-2.6-1T",
          "reasoning": true,
          "thinkingLevelMap": {
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "xhigh": "xhigh"
          },
          "input": ["text"],
          "contextWindow": 262144,
          "maxTokens": 65536,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}
```

這裡有三處不能省：

1. `compat.supportsDeveloperRole: false`
   不寫的話，部分 OpenAI 相容端點會拒絕 developer 角色，返回 400 Invalid Request Messages。設了它會回退成 system 角色。

2. `thinkingLevelMap` 必須含 `"xhigh": "xhigh"`
   不寫的話，Pi 可能隱藏 xhigh 檔，你在 UI 裡根本選不到最高推理檔。

3. `contextWindow` / `maxTokens` 不要填小
   Ring-2.6-1T 是長上下文模型。這裡填小，最直接的後果是推理預算燒在 `<think>` 裡，答案被截斷，最後你誤以為模型不會做。

### high 和 xhigh 怎麼用

這裡建議跟 Ring 的產品定位保持一致，不要無腦 xhigh。

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

我的分工是：

- Ring-2.6-1T high：預設工程執行檔，適合高頻互動。

- Ring-2.6-1T xhigh：複雜規劃、核心邏輯、最終審查。

- DeepSeek-V4-Pro / Flash：測試、review、非核心程式碼、快速修補。

這不是「誰替代誰」的問題，而是一個現實的成本工程：貴的深推理只花在真正需要的地方，結構清晰的活交給更快更便宜的模型。

## 四、我推薦的 Pi 最小可用棧

篩選組件有幾條推薦原則：

1. 上下文佔用要低

2. 同類裡選更新活躍、功能完整的

3. 純顯示、無上下文副作用的組件，入圍標準可以低一些

如果你只是想試 Ring，不建議一上來裝 22 個組件。先裝核心 5 個就夠了：

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

然後我會額外推薦 5 個增強組件：

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

剩下的 TUI、history、Discord remote、todo、goal、ask-user-question、hashline-readmap 等，可以等你真的長期用 Pi 再裝。這點很重要：Pi 的價值不是外掛越多越強，使用者需要知道每個組件為什麼在上下文裡。

## 五、7 個最容易踩的坑

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

排查 provider 問題時，Pi 往往會把錯誤壓成一行。我的經驗是：不要只看 Pi 輸出，直接 curl 端點，把變數逐個二分。比如測 Ring 的 reasoning effort：

```plaintext
KEY=$(zsh -ic 'echo $LING_API_KEY' 2>/dev/null | tail -1)

for eff in minimal low medium high xhigh; do
  curl -s -X POST https://api.ant-ling.com/v1/chat/completions \
    -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"Ring-2.6-1T\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}],\"max_completion_tokens\":30,\"reasoning_effort\":\"$eff\"}"
done
```

這裡的目標不是 benchmark，而是確認端點真的接受你以為它接受的欄位。

## 六、為什麼特別需要 plan-first + skill

任何模型發揮出最大功效都需要遵循幾點：

1. 目標明確、上下文給足、流程和邊界寫清楚

2. 先 plan，再 execute

3. 用 skill 把領域經驗固化進工作流

這和 Pi 的組件化正好互補。

Claude Code 把很多工程紀律內建了，所以你不一定顯式感知到它們。但是 Pi 預設並沒有這些功能，所以需要以擴充套件形式安裝：

- plan-first：複雜任務先讓模型寫計畫，再評審計畫，再執行

- subagent：planner / executor / reviewer 分工

- skill：把測試規範、設計規範、專案 SOP、除錯流程寫成可複用說明

- context prune：長任務中途清理上下文，保留目標和關鍵狀態

- usage/cache 可見性：知道成本花在哪

這也是我更願意把 skill 當成工作流，而不是安裝器的原因。

skill 的價值不在給模型外掛能力，而是把隱性經驗顯式化：測試應該怎麼寫、UI 應該怎麼驗收、repo bug fix 應該先看哪些檔案、什麼情況下要停止舊上下文重開。

對 Ring 這樣的開源模型來說很關鍵，因為它已經能比較好地「先拆解、再落地」，但你要給模型一個明確的拆解框架和驗收標準。

## 七、一個真實工程任務裡的觀察

我用一份真實的現貨-永續資金費率監控設計文件，觀察 Pi + Ring-2.6-1T 在完整工程任務裡的表現。

任務大概是這樣：

- 後端：Python 3.11 + httpx + FastAPI + Decimal + pytest

- 前端：Vite + React + TypeScript + Tailwind

- 資料：BTC/ETH/SOL × Binance/Bybit 的 spot/perp BBO、mark-index、funding rate、結算時間

- 核心要求：不用 last price、不用 mark 替代盤口、funding APR 按真實 interval 年化、狀態優先級鏈要完整、每個狀態要有人類可讀 reason、核心層不解析 raw JSON、不含 venue 分支

- UI：高密度 fintech 控制台，Carry Scanner / Basis Matrix / Funding Watch / Pair Detail

這個目標是我精心設計的，它同時考察了三類東西：

- 模型是否理解複雜 spec

- 模型是否能進入真實倉庫持續推進

- 工作流是否能攔住工程細節錯誤

我的觀察可以彙整成這張表：

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

這次任務裡，Ring 暴露出的幾個問題，並不太像模型完全不會，更像是 Pi 這套環境裡沒有預設裝回 Claude Code 那些工程紀律後，工作流沒有把問題攔在實現前：

- UI 狀態契約沒有在 plan 階段鎖死，導致控制項互動出問題；

- funding interval 的 symbol 級 override 沒有被測試明確覆蓋；

- 測試有同義反覆傾向，沒有真正跑狀態鏈；

- 前端 polish 沒有接 design / UI skill，結果能出但不夠可交付

這幾個問題很適合拿來說明 Ring 的正確用法：

> Ring 不應該被當成「一次性生成完整系統」的黑盒。
> 它更適合被放進一個 plan-first、skill-amplified、review-driven 的工作流裡。

這也和 Ring-2.6-1T 的大定位一致：它不是什麼都能自動搞定的模型，而是在目標清晰、流程明確、資訊給足的情況下，能把複雜任務持續推進到可用結果的推理模型。

## 八、我的推薦工作流

如果你是 Claude Code 使用者，想認真在 Pi 裡試試，我建議這樣開始：

1. **先只裝核心棧**
   先裝核心的 5 個包：
   - pi-mcp-adapter
   - pi-web-access
   - @tintinweb/pi-subagents
   - @ff-labs/pi-fff
   - pi-context-prune
   不要一上來裝滿全部外掛，先讓上下文乾淨。

2. **預設 high，複雜點切 xhigh**
   日常工程任務預設 high，只有這些場景切到 xhigh：
   - 跨模組 plan
   - 狀態機 / 金融計算 / 複雜數學
   - 架構取捨
   - 最終 review
   - 長材料綜合分析
   這樣更符合 Ring「該快則快、該深則深」的產品價值。

3. **強制 plan-first**
   複雜任務不要直接開幹，先讓模型輸出：
   - 要讀哪些檔案
   - 風險點是什麼
   - 驗收標準是什麼
   - 分幾步做
   - 哪些地方需要測試覆蓋
   然後你評審 plan，再讓它執行。

4. **用 skill 固化工作流**
   推薦給這幾類任務寫 skill：
   - repo-level debugging
   - 前端設計 polish
   - 測試規範
   - Deep Research
   - 財務/資料分析
   - 專案 SOP / 會議材料整理
   skill 不是外掛，是把模型接進成熟工作流的方式。

5. **讓更貴的腦子做 plan，讓便宜快的模型做執行**
   一種很現實的省錢做法是：
   - Ring xhigh：複雜 plan / 核心邏輯 / 最終 review
   - Ring high：普通工程推進
   - DeepSeek：測試、樣板程式碼、局部 review
   Pi 的 subagent 和 fallback 機制很適合做這種分工。

當然，這套配置不是銀彈，Ring-2.6-1T 仍然是純文字模型，不能直接看圖。視覺還原類任務應該先用多模態模型做理解，再交給 Ring 實現和修復。此外，Pi 沒有 Claude Code 那種完整權限 / sandbox 體系。需要強安全邊界的場景，要自己額外處理。真實的工程表現和配置強綁定，`models.json`、`maxTokens`、thinking 檔、外掛上下文，都會顯著影響結果。

我的大概體驗：

> 給清楚目標、配好工作流、接上 skill，Ring-2.6-1T 此類模型已經能在真實工程裡表現出不錯的持續推進能力。

## 附：連結與參考

- skill 倉庫（一鍵安裝 Pi + 配置模型）：https://github.com/wquguru/skills/tree/main/skills/pi-setup
- Pi 官方倉庫：https://github.com/earendil-works/pi
- Pi CLI：@earendil-works/pi-coding-agent
- Ring-2.6-1T Hugging Face：https://huggingface.co/inclusionAI/Ring-2.6-1T
- Ling Studio：https://ling.tbox.cn/chat

最後再強調一次這篇的核心結論：

> Pi 的價值，不是讓 Claude Code 使用者換一個更省心的工具。
> 它的價值是給開源模型一個更乾淨、更透明、更可控的 Agent 執行環境。
> 真正的關鍵，不是「模型是否無所不能」，而是「目標、上下文、工具、plan、skill 和驗收標準有沒有配好」。

鳴謝：感謝 @9hills 對於 Pi Agent 的持續分享，如果您對 Pi 有興趣，非常推薦關注一下 @9hills

## 標籤

Claude Code, Agent, 教學資源, CLI, Anthropic, Claude, Pi