Gauge CLI 0.28 上手：用本地 Docker 跑真实编程智能体，评测 Agent Experience，并对照改进文档与 Skill

本课对照的官方页面：CLI guide 、Gauge Agents pricing 、GitHub：gauge-sh/gauge-cli 、文档总览 。测试环境：2026-11-07，Asia/Shanghai，Linux x86_64 云主机，Node.js v22.21.0，@withgauge/cli 0.28.0。下面「对照结果」中，安装、init、models list、eval create、--dry-run、local runtime inspect 均为本机真实输出；正式 gauge run 会话因本机无 Docker 守护进程、也未登录 Codex/Claude，按官方说明整理并标注「未实测」。

Gauge 是面向「Agent Experience」的开源 CLI：用真实编程智能体（Claude Code、Codex、Pi、OpenCode 等）去跑你定义的任务，记录它们卡在哪里，方便你改文档、Skill、CLI 或 SDK 后再测一遍。本地模式走 Docker + 你自己的智能体订阅/API Key，不需要 Gauge 账号；托管模式才消耗 Gauge credits。

官方资料

• CLI 指南：https://docs.withgauge.com/agents/guides/cli
• Agents 定价（本地免费；托管 Free / Pro $499）：https://www.withgauge.com/agents/pricing/
• 源码：https://github.com/gauge-sh/gauge-cli
• 文档首页：https://docs.withgauge.com/

绑定工具： Gauge（https://www.kun.net/tools/gauge/ ，本轮备料）

第 1 步：确认 Node.js 版本并安装 CLI

官方要求 Node.js 22.13 或更高。Node 20 会装上包，但运行时报 fs.globSync 一类错误，无法使用。先确认：

node -v
npm install -g @withgauge/cli
gauge --version

对照结果：

v22.21.0
0.28.0

若 node -v 低于 22.13，请先升级 Node（官网二进制、nvm、发行版包均可），再重装 CLI。

更新已安装的 CLI：

gauge update

第 2 步：初始化本地工作区

挑一个要评测的产品仓库（或空目录做试验），执行：

mkdir -p ~/gauge-lab && cd ~/gauge-lab
gauge init --local --cases

对照结果（节选）：

✓ gauge init complete
Created gauge.json. Backend: local (.gauge/config.json). Local state: .gauge/gauge.sqlite. Shared cases: gauge-cases/ (created).

此时目录大致是：

本课实测的 gauge.json 初始内容：

{
  "version": 2,
  "inputs": {}
}

AGENTS.md 会插入一段 <!-- gauge:start --> 到 <!-- gauge:end --> 的指引，提醒智能体先跑 gauge instructions。

可选：安装官方推荐的 agent skill（让编程智能体以后自动发现 Gauge 工作流）：

gauge install-skill

本课未交互安装 skill；你在本机按提示选择 Claude Code / Codex 与 project 或 global 范围即可。不需要 Gauge 账号。

第 3 步：读给智能体看的说明书，并列出模型

gauge instructions --list
gauge instructions
gauge models list -o json

对照结果（instructions --list）：

init
hillclimb
run
lifecycle
cli-rules
eval
preference
session-analysis
issues
optimization

对照结果（models list，本地后端，节选）：

[
  {
    "agent": "CLAUDE_CODE",
    "harness": "claude-code",
    "defaultModel": "claude-sonnet-5-5"
  },
  {
    "agent": "CODEX_CLI",
    "harness": "codex",
    "defaultModel": "gpt-6-astra"
  },
  {
    "agent": "PI",
    "harness": "pi",
    "defaultModel": "openai-codex/gpt-6-astra"
  },
  {
    "agent": "OPENCODE",
    "harness": "opencode",
    "defaultModel": "openai/gpt-6-astra"
  }
]

读命令加 -o json，方便脚本或让智能体解析；表格输出给人看。

第 4 步：检查本地运行时（Docker）

正式跑会话前，先看运行时镜像与 Docker：

gauge local runtime inspect

对照结果（本课测试机）：

Runtime: ghcr.io/gauge-sh/gauge-runtime@sha256:4056830a1efcb0116fb70e25a18576e26ad7222a87683d6f03387eb88f596c32
Status: docker_unavailable
Local runs need a running Docker daemon.

本机没有 Docker 时，后面的 --dry-run 仍能生成计划，但真正启动会话会失败。按官方说明：

gauge local runtime pull
gauge local runtime inspect

pull 会下载与当前 CLI 版本钉死的公开 runtime 镜像。macOS 用 Docker Desktop（Linux 容器）；Windows 建议在 WSL 里跑 CLI。远程 Docker 守护进程不行，因为会话要 bind-mount 本地文件。

凭证方面：Claude Code 用 claude 登录或 ANTHROPIC_API_KEY；Codex / Pi / OpenCode 用 codex login 或 API Key 配置文件（见 gauge local profiles --help）。智能体用量由你的提供商/订阅计费，Gauge 本地模式不收 credits。

第 5 步：创建一条带成功标准的 eval

--criterion 格式是 Name: rubric text（名字 + 冒号 + 评判说明），可重复多次：

gauge eval create --name "Write README greeting" \
  --agent CODEX_CLI --samples 1 \
  --text "Write a short README.md that greets contributors in one paragraph and lists one install step." \
  --criterion "has-readme: README.md exists at the repository root" \
  --criterion "has-greeting: README.md contains a greeting sentence and an Install heading" \
  -o json

对照结果（节选，真实 id 每次不同）：

{
  "name": "Write README greeting",
  "promptText": "Write a short README.md that greets contributors in one paragraph and lists one install step.",
  "criteria": [
    {
      "name": "has-readme",
      "rubric": "README.md exists at the repository root"
    },
    {
      "name": "has-greeting",
      "rubric": "README.md contains a greeting sentence and an Install heading"
    }
  ],
  "agents": [{ "agent": "CODEX_CLI", "models": [] }],
  "sampleCount": 1,
  "id": "ev_b7762eca-dd60-4d2e-9842-8a4824983dd0",
  "measurementKind": "eval",
  "revision": 1
}

本地保存的 eval 在 .gauge/gauge.sqlite。查看：

gauge eval list -o json
gauge eval get ev_b7762eca-dd60-4d2e-9842-8a4824983dd0 -o json

把上面的 ev_... 换成你机器上 eval create 打印的 id。

第 6 步：先 dry-run，再决定是否真跑

gauge run --eval ev_b7762eca-dd60-4d2e-9842-8a4824983dd0 --dry-run

对照结果（本课）：

Local plan: 1 session in local Docker. Nothing started.
Runtime: ghcr.io/gauge-sh/gauge-runtime@sha256:4056830a…
  eval-1: CODEX_CLI gpt-6-astra ×1; 2 criteria
Inputs: none
Warning: Local runs need a running Docker daemon. …
Warning: CODEX_CLI gpt-6-astra: No ChatGPT login found (Codex's ~/.codex/auth.json). Fix: Run `codex login` …
Run it: the same command without --dry-run.

读得懂计划后，在 Docker 与登录都就绪时去掉 --dry-run（自动化脚本可再加 --yes）：

gauge run --eval ev_b7762eca-dd60-4d2e-9842-8a4824983dd0

未实测（正式会话）： 本课测试机无 Docker、无 Codex 登录，没有启动真实 agent 会话。你本机齐备后，可用：

gauge run list
gauge run get <run-id> --logs
gauge run insight <run-id>
gauge instructions session-analysis --local

本地模式下，由你的编程智能体读转录、按 schema 写分析，再 gauge run analysis save <run-id> --file analysis.json 发布 findings；托管模式会自动评判。

第 7 步：hillclimb 回路（改完再测）

官方把改进写成固定循环（gauge instructions hillclimb）：

1. 选好要测的输入（Skill、CLI、SDK、文档文件、web fixture 等）与代表性任务（含边界/易错场景）。
2. 跑 pilot，收集会话。
3. 分析摩擦（本地：session-analysis；托管：自动 issues）。
4. 改文档 / Skill / CLI 行为，保持任务、标准、模型不变，再跑同一 eval。
5. gauge run compare --baseline batch=<before> --candidate batch=<after> 看通过率与标准是否改善。

本地模式免费做满这个回路；托管额外提供自动评判、PR checks、Optimizations、认证 MCP 等。定价：托管 Free（起步 credits，每周补给）到 Pro $499/月（5,000 credits）；详见官方 Agents pricing。credits 仅用于托管跑；本地不消耗。

常见坑

1. Node 太旧：必须 22.13+，否则 CLI 直接 SyntaxError。
2. Criterion 写法：必须是 Name: rubric，不能只写一整句说明。
3. Docker 未开：runtime inspect 会报 docker_unavailable；dry-run 能看计划，真跑不行。
4. 没登录智能体：dry-run 会警告缺少 ~/.codex/auth.json 或 Anthropic 凭证。
5. 把 .gauge/ 提交进 Git：里面有本地测量与转录，应保持私有（init 已写 .gauge/.gitignore）。

小结

你已经：用 Node 22 装好 Gauge CLI 0.28；init --local 建好工作区；列出本地 harness/模型；创建了带两条 rubric 的 eval；用 --dry-run 看清「1 个 Codex 会话、2 条标准」。下一步在本机打开 Docker、登录 Codex 或 Claude Code，去掉 --dry-run 真跑，再按 session-analysis 发布 findings，进入 hillclimb。