【2026 最新】Mellum 2.1 本機 Coding Agent 怎麼接 Pi？小型 Repo 修補六步教學

你讓本機模型回答一道程式題，它講得頭頭是道；換成「請讀專案、改檔案、重跑測試」，卻可能停在一段建議。Mellum 2.1 本機 Coding Agent 教學要解決的，就是從「會說」走到「有可檢查的修改」這段距離。

這篇寫給第一次接觸本機 Agent、願意把指令貼進終端機的讀者。先分清模型、執行程式與工具，再用 Pi 修一個只有兩份 JavaScript 檔案的小專案。你會學會接入 GGUF、檢查工具是否真的執行、保留差異，以及遇到錯誤時怎麼停下來。

以下依截至 2026 年 10 月 10 日的官方文件整理。本次執行環境未備妥 Mellum 推論 runtime 與模型權重，因此沒有進行 Mellum／Pi 端到端跑次；小專案是本文自建的練習，標準答案由本機 Node.js 驗算。模型接入與故障流程是供你操作、逐項填結果的驗收方法。

先說結論：Mellum 2.1 本機 Coding Agent 要過三關

可用的修補＝模型回應＋工具真的執行＋固定測試通過。把它想成請師傅修門：師傅說得出做法、拿得動工具、修完門能開關，是三件不同的事。第一天只修一個可逆的小問題，比一次請它做完整網站更容易知道哪裡成功。

五個零件：誰負責想、誰負責動手？

① Mellum：「提出下一步的腦」。JetBrains 原始模型卡將它描述為 Thinking 模型，可用於 repository、命令與工具任務。MoE（Mixture of Experts，混合專家）像一個部門有很多專家，每一步只派一部分出場；12B 是總參數，2.5B 是活躍參數，不等於只要放下一個 2.5B 模型的記憶體。

② GGUF：「裝好權重的檔案」。量化是在保留模型可用性的前提下，用較低精度保存部分數值。檔案較小有助於載入，但選了量化名稱，仍要核對實際檔案與機器能留給推論的空間。

③ llama.cpp：「把模型跑起來的引擎」。它的 server 接收請求、套用聊天模板，再把輸出交回用戶端。聊天模板像包裝規則：同一句工具要求，必須用模型認得的格式放進去；只看 HTTP 回傳 200，還不足以驗收格式。

④ Pi：「把建議接成動作的執行層」。Pi 1.1.0 的 CLI 文件列出 read、bash、edit、write 等工具。模型提出工具名稱和參數，Pi 才執行讀檔或修改，把結果送回模型。這就是 Agent Harness 的分工。

⑤ Git 與測試：「交付收據」。Git 保存修改前後；測試回答行為是否符合題目。二者放在模型之外，就像修門前先拍照、修門後照同一份檢查單驗收。把這種流程寫成系統，可接著讀 建立 Agent Harness。

① 先選檔案與記憶體：別把活躍參數當成容量

痛點是「我的顯卡有 8GB，是否就能跑？」先看 官方 GGUF 檔案頁：圖中的容量是下載檔大小，另有 KV cache（保存對話計算狀態的快取）、runtime 與工作區開銷。顯卡記憶體、系統 RAM、Apple 統一記憶體，也不是同一個容量欄位。

本篇用官方推薦的 Q4_K_M 做設定示例，先以 CPU、較短 context 起步。下載前留出檔案、建置與日誌空間，再檢查可用 RAM；如果載入失敗或系統大量交換記憶體，就停在容量關，先降低 context 或改用能承載的機器。改量化時另開一份設定紀錄，不要和 runtime 升級一起做。

官方寫的 131,072 tokens 是模型 context 規格；本練習把 server 設為 16,384，是為了小專案驗收而選的值，並非最低需求或效能保證。先把一個小任務跑清楚，再試較長上下文。

② 固定版本：建立自己的練習資料夾

先在新的空資料夾工作，使用 macOS／Linux 的 shell。需要已安裝 Node.js 22.19 或更新版本、npm、Git、CMake 與 C++ 編譯工具；用 node --version、npm --version、git --version、cmake --version 逐項檢查。缺哪個就先完成該工具的官方安裝，不要直接跳到模型錯誤排查。

mkdir mellum-lab
cd mellum-lab
mkdir models
npm install --prefix ./pi-cli --ignore-scripts --save-exact @earendil-works/pi-coding-agent@1.1.0
git clone --branch v0.6.0 --depth 1 https://github.com/ggml-org/llama.cpp.git llama-runtime
cmake -S llama-runtime -B llama-runtime/build
cmake --build llama-runtime/build --config Release --target llama-server -j 2

這是專案內的 Pi 安裝與固定版號的 llama.cpp 原始碼建置。--ignore-scripts 跳過 npm 依賴生命週期腳本；保留 pi-cli/package-lock.json，才能記錄這輪解析到的依賴。建置方式對照 llama.cpp v0.6.0 建置文件；GPU 後端與 Windows 的選項另有差異，本篇先不混入。

接著下載固定模型 revision。下面會下載約 8.1GB 權重；先完成容量判斷，再執行。模型 revision 固定為 20b439426f1e997ba575eaccaf4856ac0f76f5d5，不使用會移動的 main。

curl --fail --location --retry 3 \
  "https://huggingface.co/JetBrains/Mellum2.1-12B-A2.5B-Thinking-GGUF/resolve/20b439426f1e997ba575eaccaf4856ac0f76f5d5/Mellum2.1-12B-A2.5B-Thinking-Q4_K_M.gguf" \
  --output models/Mellum2.1-12B-A2.5B-Thinking-Q4_K_M.gguf
./pi-cli/node_modules/.bin/pi --version
./llama-runtime/build/bin/llama-server --version
git -C llama-runtime rev-parse HEAD
shasum -a 256 models/Mellum2.1-12B-A2.5B-Thinking-Q4_K_M.gguf

將版號、Git commit、權重檔名和 SHA-256 摘要存成筆記。最後一行是 macOS 的檔案雜湊命令；Linux 可用 sha256sum 計算同一檔案。它是這輪的檔案識別紀錄，請另與固定 revision 的官方檔案 metadata 核對，別把自行算出的摘要當成原廠認證。

③ 啟動本機端點：先驗連線，再驗工具

./llama-runtime/build/bin/llama-server \
  -m models/Mellum2.1-12B-A2.5B-Thinking-Q4_K_M.gguf \
  --alias mellum-local --host 127.0.0.1 --port 8080 \
  --ctx-size 16384 --parallel 1 --n-gpu-layers 0 --jinja --reasoning-format deepseek \
  --temp 0.6 --top-p 0.95 --top-k 20

這個終端機保持開著。127.0.0.1 讓端點只綁本機 loopback；--n-gpu-layers 0 選 CPU 起步，速度需在你的機器量。--alias mellum-local 則讓用戶端用一致名稱請求，不必猜模型檔案路徑。參數可查 固定版本 server 文件。

另開一個終端機，回到 mellum-lab。先用 curl --fail http://127.0.0.1:8080/health 看載入狀態，再執行下列小請求，把原始回應留下：

curl --fail http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  --data '{"model":"mellum-local","messages":[{"role":"user","content":"Reply with READY."}],"max_tokens":512,"temperature":0.6}' \
  --output chat-check.json

這只驗請求有沒有到正確端點，以及回答是否完整。Thinking 可能先消耗輸出額度；若回應截斷，先看 finish_reason 和回傳內容，再調整輸出上限。不要把純文字裡的工具標籤當作已執行：工具必須由 server 解析，並由 Pi 留下執行結果。

④ Mellum 2.1 本機 Coding Agent 接上 Pi：設定只放這一輪

先建專用 profile，讓練習設定和你原有的 Pi 設定分開。將下面 JSON 存成 pi-profile/models.json；先執行 mkdir pi-profile，再用文字編輯器建立檔案。Pi 的自訂 endpoint 文件確認這條路用 openai-completions，名字雖然有 completions，對應的是聊天介面。

{
  "providers": {
    "mellum-lab": {
      "baseUrl": "http://127.0.0.1:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "mellum-local",
          "name": "Mellum local lab",
          "reasoning": true,
          "input": [
            "text"
          ],
          "contextWindow": 16384,
          "maxTokens": 4096,
          "compat": {
            "supportsReasoningEffort": false,
          "supportsStore": false,
          "supportsDeveloperRole": false,
          "maxTokensField": "max_tokens"
          }
        }
      ]
    }
  }
}

apiKey: none 是本機示例的假值，不是向雲端取得的金鑰。contextWindow 要與這輪 server 設定一致；maxTokens 是包含思考的總生成預算，不能把它讀成會產出這麼長的可見答案。相容性設定使用固定版 server 的 max_tokens 欄位，不傳 store、developer role 或 reasoning_effort；這些欄位不代表關閉模型思考。

⑤ 建一個兩檔 Repo：驗收答案先寫好

本例只改「去除輸入文字首尾空白」一個行為，保留大小寫轉換、內部空格與既有連字號規則。repository（Repo，程式碼資料夾與版本紀錄）放在 mellum-lab/toy-repo。先執行 mkdir toy-repo，再建立兩份檔案。

slug.mjs 是故意留了一個問題的程式：

export function slugify(text) {
  return text.toLowerCase().replaceAll(' ', '-');
}

slug.test.mjs 是固定驗收清單，Agent 全程不得修改：

import test from 'node:test';
import assert from 'node:assert/strict';
import { slugify } from './slug.mjs';

for (const [input, expected] of [
  ['Hello World', 'hello-world'],
  ['  Hello World  ', 'hello-world'],
  ['', ''],
  ['   ', ''],
  ['Keep--Dash', 'keep--dash'],
]) {
  test(JSON.stringify(input), () => {
    assert.equal(slugify(input), expected);
  });
}

先自己執行測試，再存起點。此處預期五個案例中，首尾空白與全空白兩題失敗；這是本文對 fixture 的本機驗算結果，與 Mellum 成績無關。Node.js test runner是這份驗收的執行工具。

cd toy-repo
node --test slug.test.mjs
git init
git add slug.mjs slug.test.mjs
git -c user.name="Tutorial Learner" -c user.email="learner@example.invalid" commit -m "baseline fixture"

接著先開只提供 read 的 Pi；這輪不提供 bash、edit 或 write。先在 pi-profile 資料夾執行 pwd，複製印出的完整路徑。回到 toy-repo，把下方 /absolute/path/to/mellum-lab/pi-profile 換成剛才的路徑：

export PI_CODING_AGENT_DIR="/absolute/path/to/mellum-lab/pi-profile"
../pi-cli/node_modules/.bin/pi \
  --offline --no-extensions --no-mcp --no-skills \
  --no-prompt-templates --no-context-files --no-approve \
  --provider mellum-lab --model mellum-local --tools read

貼入：請用 read 工具讀取 slug.mjs；只報告實際讀到的函式名稱，不修改檔案。你要看到 Pi 的 read 呼叫與檔案內容結果，才算第二關通過。如果只看到模型描述「我已讀取」，先停下來核對工具紀錄。可參考 本機模型工具呼叫驗收 的分層思路。

離開只讀 session，再用同樣參數把最後一段改成 --tools read,bash,edit,write，開始修補。這些開關用來減少本輪自動載入資源；--offline 抑制自動網路活動，read 工具也不限制可讀路徑。Pi 的工具仍以目前使用者權限執行，這不是作業系統沙箱。依 Pi 安全文檔，應以隔離環境承載需要硬性權限邊界的任務。這裡只放自己建立的無憑證練習檔。

只處理目前 toy-repo。先讀 slug.mjs 與 slug.test.mjs，
再執行 node --test slug.test.mjs，根據失敗定位原因。
只修 slugify 對輸入首尾空白的處理；保留既有大小寫、
內部空格與連字號行為。不修改測試、不安裝套件、
不連外、不提交 commit。完成後重跑同一測試，
報告工具錯誤、修改差異及測試結果。
若需要擴大任務範圍，先停下來說明。

這段提示是任務規格，不是強制權限政策。正確修補的一個答案是把回傳式改成 text.trim().toLowerCase().replaceAll(' ', '-')。Agent 結束後，由你在另一個終端機獨立執行下列驗收，別讓它自己改標準答案：

git diff --check
git diff -- slug.mjs slug.test.mjs
git status --short
node --test slug.test.mjs

接受條件是測試檔零差異、只有 slug.mjs 的預定行為被改、五題全過。模型說「完成」只是一則訊息；這四個檢查才是交付收據。

⑥ 故意讀錯一個檔案：練習停手、重試與回復

另開只讀 session，先給它一個明確錯誤任務：只呼叫一次 read，讀取 missing-demo.mjs。遇到錯誤就停止並轉述工具回傳，不猜內容，也不改其他檔案。這個檔案刻意不存在。你要保存原始工具錯誤、是否真的停下，以及它有沒有聲稱成功。

若停下，再發第二則提示：剛才指定錯檔；現在只讀 slug.mjs，回報實際內容。第一輪錯誤與第二輪成功分開記。若它持續重試、虛構內容或轉去別的路徑，用 Esc 中止，保留 session；不要讓錯誤靠更多自動步驟被蓋掉。這是錯誤恢復練習，不是本文已觀察到的 Mellum 失敗率。

回復也只針對自己剛建立的 fixture：先保存 git diff -- slug.mjs 的內容，再執行 git restore --source=HEAD -- slug.mjs，核對差異清空、原本兩題失敗重新出現。這個 restore 會丟棄 slug.mjs 尚未提交的修改；不要搬去有他人未保存工作的資料夾。

三個常見坑：從出錯的位置往回查

連線成功，工具卻沒動。先核對 endpoint、模型 alias、工具是否有列出，以及 Jinja 模板與解析。不要先換五個參數；把「server 收到」「回傳可解析呼叫」「Pi 有執行結果」各存一份證據。

測試全綠，但題目被改了。看測試檔是否有差異，再看未追蹤檔案。刪掉失敗案例、增加跳過條件，也可能讓測試變綠；所以測試通過要和修改範圍一起驗。

一個成功跑次被當成全面能力。官方模型卡的 Agent 評測有自己的 harness、context 與 sampling；本篇選的量化、CPU、短 context 不是那套配置。不同測試／版本不可直接互比。將同一任務重跑，記錄每次錯誤、時間與差異，才有你自己的使用證據。

常見問題：八個直接答案

1. 2.5B 活躍參數，代表只占 2.5B 的記憶體嗎？

不是。活躍參數描述每一步計算；權重檔與其他記憶體開銷另算。

2. 8GB 顯卡一定能跑完整長 context 嗎？

不能由容量標籤推定。先核對量化檔、快取與 runtime，再量自己的載入與任務。

3. 一定要把原有 Pi 設定覆蓋掉嗎？

本篇不用。專用 PI_CODING_AGENT_DIR 保存這輪 models.json，原設定另留。

4. apiKey 的 none 是不是免費雲端方案？

不是。它是本機未配置驗證端點的假值，運算在你指定的 server。

5. 模型輸出工具格式，就算讀檔成功嗎？

還要看 Pi 執行結果。名稱與參數被解析後，檔案內容才是這輪讀取證據。

6. –no-approve 能隔離檔案權限嗎？

不能。它忽略信任門控的專案設定與資源，工具仍有使用者權限。

7. 第一個任務應該做大型新專案嗎？

先選小修補。已知標準答案與可回復起點，讓你容易定位錯在模型、工具或驗收。

8. 五題全過後，下一步做什麼？

先重跑同題並保留紀錄，再增加一個邊界案例；不要同時換模型、量化與 runtime。

給新手的三個重點

先固定檔案與版本，再談速度；先讀一份檔案，再開修改工具；先保持測試不動，再接受修補。每次任務留下一份版本筆記、工具結果、Git 差異與測試輸出，出錯時才知道要從哪一層修。