【2026 最新】Gauge 教學：改好 CLI Help 後，怎麼用前後配對驗收 Agent？

你替命令列工具改了 --help，覺得說明清楚多了；Agent 下一輪卻還在猜參數。這篇 Gauge 教學帶你把「應該比較好懂」變成可以查證的問題：同一張考卷、同一個模型，換掉說明後，任務真的比較順嗎？

寫給第一次接觸 Agent 評估、願意開終端機貼指令的讀者。你會認識五個零件，建立一個只在練習目錄寫假筆記的小 CLI，再設計三題與一題保留題。程式可先交給既有 Coding Agent 協助建檔；每一步都附上要核對的東西。

以下依 2026 年 11 月 6 日查閱的官方文件與原始碼整理，工具固定 @withgauge/cli@0.28.0。AlphaLab 已做 CLI 範例檢查與四題的靜態驗證；本次環境缺少 Docker，未執行代理工作階段。後面的配對流程是可操作的實驗設計，結果欄留給實際執行後填寫。

先說結論：Gauge 教學的口訣是「同題、同版、換說明、看證據」

Gauge 迭代＝固定考卷＋保存原版＋一次改一件事＋前後驗收。把它想成替工具安排試用考試：Gauge 準備考場和保存過程，Agent 是考生，你用完成條件檢查交付。所謂 hillclimbing，就是改一小步、量一次，再決定保留或回復。

• 先測 CLI 在已提供給 Agent 時能否用對；這和「它會不會主動選你的產品」是兩個問題。
• Help 寫得更長不等於更好；要看檔案是否正確、錯誤後怎樣恢復，以及走了多少冤枉路。
• 本機 Docker 執行仍會呼叫模型服務，模型用量由你的供應者或訂閱承擔。

一、Gauge 是什麼？先分清五個零件

① 「考場」是 Docker。Gauge 本機模式為工作階段建立新容器。② 「考生」是 Agent 與模型。Harness 是讓模型讀檔、執行工具的外層；同個模型換外層，行為也可能不同。初學者可先讀 Agent Harness 的分工。

③ 「考卷」是任務與 criteria。criteria 就是完成條件，例如筆記檔的文字必須等於 green。④ 「教材」是輸入套件。這次用打包後的 npm tarball，也就是 .tgz 壓縮檔。⑤ 「錄影與批改」是 transcript 和 analysis。前者記錄過程，後者把判斷連回證據。

依 官方 README，本機模式的執行與證據收集由 CLI 處理，結果分析交給你的 Coding Agent；託管服務有另一套管理與自動分析流程。本篇全程明寫 --local，只教 npm CLI 套件，避免把不同後端的能力混用。

二、Gauge 教學第一步：版本與費用先對齊

痛點是「兩次跑的根本不是同一套東西」。解法是固定工具，再記錄模型與執行層。這組命令適用已有 Node.js 22.13 以上、npm 與可用 Docker 的 macOS／Linux 環境；Windows 依官方本機指南在 WSL 內操作。先在新練習目錄執行：

node --version
npm install -g @withgauge/cli@0.28.0
gauge --version
mkdir gauge-cli-lab
cd gauge-cli-lab
export GAUGE_TELEMETRY_DISABLED=1
gauge instructions
gauge init --local
gauge local runtime inspect
gauge models list --local -o json > models.json

安裝後確認版本印出 0.28.0。inspect 只檢查；若缺少 Docker，先停在這裡完成安裝環境。若 Docker 可用但尚未取得映像，再執行 gauge local runtime pull，它會下載該 CLI 版本固定的執行映像。保留 inspect 輸出中的映像參照，並從 models.json 選你有使用權限的目標。

模型名稱能固定，遠端服務的實作仍可能更新；因此另記測試時間、實際模型、Harness 版本與映像 digest。兩輪之間先別執行 gauge update。完整設定可對照 官方 CLI 指南；供應端先設定可接受的用量上限，初次只安排一個目標、每題一份樣本。

本機模式使用你的代理憑證。把正式客戶資料、雲端管理金鑰與公司私有套件留在練習外；只提供測試所需的模型登入。GAUGE_TELEMETRY_DISABLED=1 關閉 Gauge CLI 的使用遙測，不會關閉代理對模型供應者的請求。本機是考場位置，並非模型一定離線。

三、建立小 CLI：先讓完成條件能被人核對

痛點是「Agent 說做完了，卻不知道交了什麼」。解法是把產物縮成一個 JSON 檔。在練習根目錄建立 pkg 與 artifacts，把下列內容存為 pkg/package.json：

{"name":"alphalab-memo-lab","version":"1.0.0","type":"module","bin":{"memo-lab":"cli.js"},"files":["cli.js"]}

再把以下內容存為 pkg/cli.js。它只示範單一筆記；每次 add 會覆寫當前目錄的 note.json，因此要在專用練習資料夾內操作。

#!/usr/bin/env node
import { readFileSync, writeFileSync } from 'node:fs';
const args = process.argv.slice(2);
const [command] = args;
const fail = message => { console.error(message); process.exit(2); };
if (!command || command === '--help') {
  console.log('memo-lab: add | show');
} else if (command === 'add') {
  const index = args.indexOf('--text');
  const text = index >= 0 ? args[index + 1] : undefined;
  if (!text || text.startsWith('--')) fail('Missing text');
  writeFileSync('note.json', JSON.stringify({ text }) + '\n');
  console.log('Saved note.json');
} else if (command === 'show') {
  try {
    const note = JSON.parse(readFileSync('note.json', 'utf8'));
    console.log(args.includes('--json') ? JSON.stringify(note) : note.text);
  } catch { fail('Cannot read note.json'); }
} else if (command === 'create') {
  fail('Deprecated command');
} else {
  fail('Unknown command');
}

先人工執行 node pkg/cli.js add --text green，接著執行 node pkg/cli.js show --json，核對 text 是 green。再各跑一次 node pkg/cli.js add 與 node pkg/cli.js create：前者應缺參數、後者應報棄用，結束碼皆為 2。這些是教學程式預設的行為，不是 Gauge 自帶的筆記功能。

此程式省略多筆資料、並行寫入與完整檔案錯誤處理；用途是驗證一段說明能否幫 Agent 完成小任務。Node.js 的 檔案系統文件可查同步讀寫介面。正式 CLI 仍需另做功能測試；Gauge 增加的是 Agent 使用它時的行為證據。

把原版打包，避免測到舊材料

mkdir -p artifacts
cd pkg
npm pack --pack-destination ../artifacts --ignore-scripts
cd ..
cp artifacts/alphalab-memo-lab-1.0.0.tgz artifacts/candidate.tgz
cp artifacts/candidate.tgz artifacts/before.tgz
shasum -a 256 artifacts/before.tgz

依 npm pack 文件，pack 會產生套件壓縮檔；此處的 --ignore-scripts 適合沒有建置步驟的練習包。換成自己的 TypeScript CLI 時，先執行原有 build，再打包並檢查壓縮檔內容。存下 SHA-256 指紋，能核對兩輪究竟交付哪份位元。

將以下存為根目錄的 gauge.json。install: environment 把 CLI 提供到測試環境；固定檔名則讓每輪都明確選中一個 tarball。

{"version":2,"inputs":{"cli":{"type":"npm-package","path":"artifacts/candidate.tgz","install":"environment"}}}

四、三張考卷與保留題：先寫答案標準，再跑代理

痛點是「一邊看答案、一邊改考卷」。解法是先固定題目、criteria 與樣本數。建立 gauge-cases/cli；第一題存為 choose.md，將 你的模型識別字 換成剛才模型清單中、有權使用的實際模型：

---
criteria:
  - name: 筆記交付
    rubric: note.json 是 JSON 且 text 等於 green。 手動偽造檔案不算完成。
config:
  agents:
    - agent: CODEX_CLI
      models: ["你的模型識別字"]
  sampleCount: 1
  inputs: [cli]
---
請用已安裝的 memo-lab 保存一則文字為 green 的筆記，交付 note.json。
請先讀 memo-lab --help；只能經此 CLI 建立筆記，不修改套件程式。

同一份模板再存成三個檔案，保留 config 不變，只換任務正文與 rubric：

• missing.md：前次執行 memo-lab add 缺少內容，請用此 CLI 保存 blue。驗收 note.json 的 text 為 blue，並從過程確認確由 CLI 寫入。
• deprecated.md：舊說明使用已棄用的 memo-lab create，請查現行用法保存 orange。驗收文字與真實 CLI 寫入。
• holdout.md：用 memo-lab 保存 quiet，再以 JSON 顯示並核對。驗收檔案及可解析的 CLI 輸出都含 quiet；這題先封存，不用它決定怎麼改 Help。

這裡刻意要求先看 Help，量到的是讀到說明後能否用對，不包含自然探索或網路搜尋的發現率。criteria 要檢查結果與執行證據，別把「只能打一條指定指令」當成功條件。這個分界可參照 Agent Experience 文件，也可搭配 AI Evals 的基本觀念。

gauge run --verify --local -o json > verify.json
gauge run --dry-run --local -o json > preview-before.json
gauge run --local
gauge run list --local -o json > runs-before.json

先讀 verify.json 的各項狀態；它驗語法與設定，不等於容器安裝或任務成功。--dry-run 再預覽輸入與 Docker、憑證就緒情況；確認四題各一份樣本，共四個工作階段，再正式啟動。保存 CLI 回傳的真實 batch ID，不用檔名猜。AlphaLab 本次四題靜態驗證通過，但 Docker 檢查失敗，因此沒有執行上方正式 run。

五、只改 Help 與錯誤訊息，完成前後配對

痛點是「跑完有紀錄，仍說不出卡在哪」。解法是先讀過程，再改一處。對每個實際 run ID 使用下列命令；尖括號要換成回傳的識別字：

gauge instructions session-analysis --local
gauge run get <run-id> --local --logs -o json > session-before.json
gauge run diff <run-id> --local
gauge run analysis schema > analysis.schema.json
gauge run analysis save <run-id> --local --file analysis.json
gauge run insight <run-id> --local

讓協助你的 Coding Agent 按第一行指引讀 transcript、檔案差異與交付，依 schema 寫出 analysis.json；這個檔案要先產生才執行 save。每個 verdict 附上對應事件證據，操作者再讀回 JSON 產物和 CLI 呼叫。缺少產物、環境故障與答案錯誤分別記錄，別全部塞成模型不會用。

第一輪若顯示參數探索卡住，只把 console.log('memo-lab: add | show') 的字串改為 memo-lab add --text <文字>：保存 note.json；memo-lab show --json：顯示 JSON。另一次迭代才改 Missing text 為 Missing --text. Example: memo-lab add --text hello；再下一次才改 Deprecated command 為 create is deprecated. Use: memo-lab add --text hello。每輪保存程式差異，核心寫檔邏輯保持一致。

修改後重新執行上一節的 npm pack 與 candidate 複製步驟，保留 before.tgz 不動，再存候選包指紋。Gauge 讀的是套件壓縮檔，單改工作目錄的原始碼不會自動重新打包；官方 隨版 run 指引特別區分這兩件事。

gauge run --dry-run --local -o json > preview-after.json
gauge run --local
gauge run list --local -o json > runs-after.json
# 兩輪各 run 的分析都保存後，再替換下列 batch ID
gauge run compare --local --baseline batch=<before-id> --candidate batch=<after-id>

重新核對 preview 的來源路徑與 input snapshot，確定拿到新包。比較前，兩輪都要完成 analysis save。compare 能彙整通過率與回合、時間等資料；本機判分使用你保存的 criteria 結果。若警告題目 revision 改變，先排除換考卷造成的差異。官方 CLI 參考記錄了這些比較邊界。

怎麼判斷這次修改值得留下？

• 結果先看：逐題列出實際交付、criteria verdict、環境失敗與未完成數，分母清楚才看通過率。
• 摩擦再看：對齊同題兩輪的錯誤命令、恢復路徑、回合與時間；錯命令減少但產物錯了，仍需修正。
• 用量另外記：從實際可取得的代理或供應端紀錄抄入 token／費用，並標清來源；缺值留空，不拿回合數換算成金額。
• 保留題最後看：候選說明定下後才檢查 holdout。若把它拿來調整，另設新保留題。保存失敗候選與原版，回復時複製 before.tgz 到 candidate.tgz，再預覽確認。

每題一份樣本只是找問題的起點。前後配對指的是對齊題目與設定，並不保證模型採用同一隨機路徑。值得保留的候選再增加重複次數，交錯測原版與候選，觀察改善是否持續。這是本篇的實驗設計建議，不是已得到的統計結論。

六、常見問題：八個先講答案的判斷

1. Gauge 就是另一個 Coding Agent 嗎？

它負責安排測試、收證據與比較；真正操作 CLI 的是你選定的 Agent／模型。可用 建立 Harness 教學補上執行迴圈。

2. 本機執行等於不用付模型費嗎？

仍會使用你的代理登入或 API 額度。先確認供應者的計費方式與預算，再增加樣本。

3. verify 通過就表示任務成功嗎？

還要跑代理並驗交付。靜態設定、環境就緒、工作階段完成、criteria 通過是不同檢查。

4. 改了 cli.js，直接重跑就行嗎？

先重新打包並核對 candidate.tgz 的指紋。否則測試可能仍安裝上一版包。

5. 錯過一次指令就該判失敗嗎？

看 criteria。過程走錯後能恢復，結果仍可通過；把錯誤命令另外記作摩擦，才看得見改善。

6. 一次四題全過，就能說新 Help 比較好嗎？

證據還太少。先看原版是否也全過、過程是否不同，再增加重複與新任務。

7. 會選你的產品，代表能用對嗎？

需分開量。Preference 測選擇，Experience 測指定產品後的完成情況；本篇測後者。

8. Docker 能讓正式祕密隨便放進去嗎？

仍要限制掛載、憑證與網路。只放練習套件和假資料，逐項確認 preview 交付的輸入；transcript 分享前也先檢查敏感內容。

給新手的三個重點

• 先讓完成條件有可讀回的產物，再談成功率。
• 改說明後重新打包，保留原版、指紋與真實 batch ID。
• 看結果、過程與保留題，才決定留下修改或回復。