进阶 📋 6 个步骤 第 628 / 632 篇

用 Mistral Vibe 3.1.2 给 headless Agent 上双预算闸门:--max-tokens / --max-price 与子智能体 fan-out 验收

Mistral Vibe 3.1.2 于 2026 年 11 月 10 日修复了 headless 成本闸门:--max-tokens 与 --max-price 现在会在下一次 root 或 subagent completion 启动前中止运行,不再等一轮 fan-out 结束才结算。本教程按官方程序模式文档六步落地:审阅安装脚本、跑基线读 export.json、分别触发 token_limit 与 price_limit、验证子智能体场景停止时机、把插件与技能开关纳入成本治理,最后收成 CI 可执行的门禁脚本。密钥走环境变量,--auto-approve 只用于隔离仓库。

2026.11.16· 18 分钟阅读· 约 4584 字· 💸 Mistral Vibe 3.1.2 / 🛑 双预算闸门

把 Agent 放进 CI 或定时脚本里跑,最怕的不是它做不完,而是它带着子智能体一路 fan-out、把额度烧穿了才停下来。Mistral Vibe 3.1.2(2026 年 11 月 10 日发布)专门修了这件事:headless 模式的 --max-tokens 与 --max-price 现在会在下一次 root 或 subagent completion 开始前中止运行,而不是等一轮 fan-out 全部结束才结算。本教程用官方程序模式文档,把「双预算闸门」完整跑一遍:从安装、导出文件结构、outcome 与退出码,到子智能体场景下的停止时机、插件与技能开关,最后收成一个可放进流水线的验收脚本。全程不改动业务仓库,练习目录可随时丢弃。

🧩 适合谁:把编码 Agent 接进脚本 / CI / 批量任务的开发者,或需要给团队设定「每次运行最多花多少钱、最多用多少 token」的技术负责人。前置准备:macOS / Linux 或 Windows、Python 3.12 及以上的 GIL 构建(官方说明 free-threaded 构建会装不上)、能联网安装 CLI、一个新建的练习仓库、以及一个 Mistral 账号或可用的模型 API Key。本教程的主线会把预算压得很低,但仍可能产生真实的模型费用;请把密钥放在环境变量或交互式登录里,不要写进脚本、命令行历史或提交记录。

三条必须先看清的风险:① 官方安装方式是 curl ... | bash 与 irm ... | iex 这类管道执行,动手前先下载脚本审阅,确认来源域名与内容再运行;② --auto-approve(也写作 --yolo)会放行所有工具调用,官方明确说明不加它时「需要审批的工具调用会被拒绝」,本教程只在隔离的练习仓库里使用;③ --max-price 依赖模型价格表,官方写明定价为 0 的模型按免费计算,接本地模型或自定义端点时成本可能显示为 0 美元,预算闸门因此不会按你想象的方式生效。这三点在后面的风险提示里还会展开。

先弄清:预算闸门到底在哪个时点生效

官方程序模式文档对两个旗标的定义很精确,理解它们才能设计有效的验收:--max-price 管累计成本,--max-tokens 管累计 token(prompt 与 completion 都算),两者都作用于本次运行的 root session 与 subagents。达到上限后不再启动新的 completion,已获准的调用(含重试)可以跑完,outcome 分别是 price_limit 与 token_limit。

旗标 / 字段官方口径本教程怎么验
--max-price DOLLARSroot 与子智能体累计成本上限;触顶后 outcome 为 price_limit;--max-price 0 只跑免费模型用极小预算触发并读 export.json
--max-tokens N累计 prompt + completion token 上限;触顶后 outcome 为 token_limit;与单次输出上限分开配合 --max-turns 观察退出码
--output json全部消息在结束时以 JSON 输出;另有 text(默认)与 streaming(逐消息 NDJSON)把结果重定向到文件后解析
--output-dir DIR写出 DIR/export.json 并把会话日志复制到 DIR/session/,无论运行以何种方式结束读取 outcome / cost / steps / warnings
退出码 3对应 turn_limit、token_limit、price_limit、deadline、terminated、length、refusal 等「未完成的停止」在 shell 里捕获 $?

3.1.2 修的是「结算时点」:官方 Release 写明,修复前一次 fan-out 到多个子智能体可能把花费推过上限,因为检查发生在一轮结束之后;修复后会在另一个 root 或 subagent completion 启动前就停止。同一版还修了「等待子智能体或后台进程时发的消息要等到等待结束才送达」的问题,并让状态行说明正在等什么。这些都是可观测的行为变化,但不是瞬时硬截断:已获准的调用仍会完成,所以预算要留出一点余量。

Step 1:审阅安装脚本,装好 CLI 并确认版本

1 从官方入口安装,用隔离目录做练习

官方 README 给出三条路线:macOS / Linux 用安装脚本,Windows 先装 uv 再 uv tool install mistral-vibe,已有 uv 的环境在任意平台都可用后者。先把脚本取下来读一遍再执行,装完立刻确认版本与登录方式。

# 新建练习仓库,避免 Agent 误改真实项目
mkdir vibe-budget-demo && cd vibe-budget-demo
git init

# 先把远端脚本下载到文件里审阅,再执行(macOS / Linux)
curl -LsSf https://mistral.ai/vibe/install.sh -o install.sh
less install.sh
bash install.sh

# Windows PowerShell 路线:先装 uv,再用 uv tool install
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# uv tool install mistral-vibe
# 若新终端找不到 vibe,执行 uv tool update-shell 后重开终端

vibe --version
# 按官方说明,在交互模式里用 Mistral 账号登录或填入 API Key;
# 不要在这里把密钥写进命令行参数。
vibe
💡 如果安装报「free-threaded Python」相关错误,官方 README 给了明确做法:uv python install cpython-3.14,然后 uv tool install --python cpython-3.14+gil mistral-vibe。另外在 ~/.vibe/config.toml 里设 enable_telemetry = false 可关闭遥测与崩溃上报;密钥请用环境变量或登录态,别贴进配置文件。

Step 2:跑一次基线,看清 export.json 里有什么

2 先用极低预算跑一轮,把导出结构摸清楚

程序模式的入口是 --prompt(也写作 -p,无文本时从 stdin 读)。官方文档给出的示例是 vibe --prompt "Analyze the codebase" --max-turns 5 --max-price 1.0 --max-tokens 50000 --output json。这里我们先用更小的预算和 --output-dir,让运行大概率被预算拦下,从而拿到一份完整的导出文件作为后续断言的样本。

# 准备一个不会误伤真实文件的小任务
printf '%s\n' "列出当前目录下的文件,写一段 30 字以内的说明,不要修改任何文件。" > task.md

# 低预算跑一轮:--auto-approve 只在练习仓库里使用
vibe --prompt-file task.md \
  --max-turns 3 --max-price 0.01 --max-tokens 2000 \
  --auto-approve --output json --output-dir out/baseline
code=$?
printf 'exit_code=%s\n' "$code"

# 导出文件由 --output-dir 写出,无论运行以何种方式结束
python -c "import json; d=json.load(open('out/baseline/export.json')); print(sorted(d.keys()))"
python -c "import json; d=json.load(open('out/baseline/export.json')); print('outcome=',d.get('outcome'),'cost=',d.get('cost_usd'),'steps=',d.get('steps'))"

官方文档说明 export.json 会记录 Vibe 版本、生效配置(表头与环境变量值已脱敏)、token 用量、成本、模型调用次数 steps、停止原因与 outcome;若存在技能或配置文件加载问题,会出现在 warnings 数组里,每项形如 {"message": str, "source": str 或 null},没有告警时该字段省略但运行照常继续。

💡 --output json 与 --output-dir 是两件事:前者决定标准输出格式,后者负责落盘。官方还说明,在恢复会话时 text 与 streaming 只覆盖新一次运行,而 json 含整个会话;导出的 usage / cost / steps 则只统计本次 run,复制的 journal 才包含完整会话。

Step 3:分别触发 token 与价格闸门,核对退出码

3 让两种 outcome 各自出现一次

门禁脚本必须能区分「做完了」「被预算拦下」「根本没跑起来」。官方退出码表给出:0 是 finished;1 是 usage_error / config_error;2 是 infrastructure_failure;3 是一组「未完成但留下了产物」的 outcome;4 是 aborted(实验性 agent-socket 服务端主动中止)。下面用两组极小预算分别触发 token_limit 与 price_limit。

# A) 极小的 token 预算:预期 outcome = token_limit,退出码 3
vibe --prompt-file task.md --max-tokens 200 --max-turns 8 \
  --auto-approve --output json --output-dir out/token
printf 'token_run_exit=%s\n' "$?"

# B) 极小的价格预算:预期 outcome = price_limit,退出码 3
vibe --prompt-file task.md --max-price 0.0001 --max-turns 8 \
  --auto-approve --output json --output-dir out/price
printf 'price_run_exit=%s\n' "$?"

# C) 对比组:不加预算,正常完成(费用按你的账号计费)
vibe --prompt-file task.md --max-turns 3 \
  --auto-approve --output json --output-dir out/finished
printf 'finished_run_exit=%s\n' "$?"

for d in out/token out/price out/finished; do
  python -c "import json,sys; d=json.load(open(sys.argv[1]+'/export.json')); print(sys.argv[1], d.get('outcome'), d.get('cost_usd'), d.get('steps'))" "$d"
done

不要把这些数字当成承诺:模型价格、缓存命中、任务复杂度都会改变实际触顶时点。官方还说明预算统计包含每次被丢弃但被服务端接受的尝试用量(含不可重试失败);上下文压缩的本地估算是个例外;在服务端上报用量前就结束的尝试(例如流被断开)记作 0 并写入 warning;Agent 循环之外为图片描述等目的发起的模型调用既不计入也不受预算约束。若某次运行没触发预期 outcome,优先检查任务是否太快结束,而不是假定闸门失效。

Step 4:在子智能体 fan-out 场景下核对 3.1.2 的修复点

4 用「会派生子任务」的提示词验证停止时机

这次修复的价值只在 fan-out 场景才看得出来:给一个明确会拆分调查的任务,配上很紧的 token 预算,观察运行是否在下一次 completion 启动前停下,而不是等所有子任务都回来后才发现超支。官方 Release 同时提到,等待子智能体期间发送的消息现在会立刻送达;状态行会说明正在等待什么;工具组标题会把「仍在调用」与「已结束」分开计数。

# 构造一个会拆分的任务描述(只做只读调查,不改文件)
cat > fanout.md <<'EOF'
把当前仓库拆成三块并行调查:目录结构、配置文件、测试入口。
每块分别给出结论,最后汇总成一段不超过 100 字的说明。
全程只读,不要修改、删除或新建任何文件。
EOF

vibe --prompt-file fanout.md \
  --max-tokens 1200 --max-turns 12 --max-price 0.02 \
  --auto-approve --output json --output-dir out/fanout
printf 'fanout_exit=%s\n' "$?"

python -c "import json; d=json.load(open('out/fanout/export.json')); print('outcome=',d.get('outcome')); print('usage=',d.get('usage')); print('cost_usd=',d.get('cost_usd')); print('warnings=',d.get('warnings'))"

# 用 --resume 续跑:官方说明所有预算从新一次运行起点重新计算
SID=$(python -c "import json; print(json.load(open('out/fanout/export.json'))['session_id'])")
vibe --resume "$SID" --prompt "把上次的结论压缩成一行" \
  --max-tokens 600 --max-price 0.01 --auto-approve \
  --output json --output-dir out/resume
printf 'resume_exit=%s\n' "$?"
💡 --resume SESSION_ID 里的 id 取自上一次 export.json 的 session_id 字段,这是官方文档写明的续跑方式。续跑时 --max-turns、--time-limit、--max-tokens、--max-price 都从新 run 起点重新计算,导出的 usage / cost / steps 也只统计新 run;不要把两次导出相加当成总预算,需要在流水线侧自己累计。

fan-out 不是省钱手段:拆出多个子智能体会同时推高 token 与费用,官方 3.1.2 修的是「上限何时生效」,不是「让 fan-out 更便宜」。另外 --auto-approve 会放行所有工具调用,官方说明不加它时会被审批拦下的工具调用改为拒绝;如果确实要在受控环境缩小权限,可用 --enabled-tools bash 只放行指定工具,或在 agent profile 里写 allowlist(官方示例为 ~/.vibe/agents/tester.toml 的 [tools.bash] 段落),链式命令只有每一段都在 allowlist 里才会被放行。

Step 5:把插件与技能开关纳入成本治理

5 用 3.1.2 新增的开关减少不必要的上下文

预算不只由模型调用决定,装了多少插件、加载了多少技能也会占上下文。3.1.2 新增 disabled_plugins(已安装但本次会话不生效)、允许插件用 defaultEnabled: false 默认关闭再用 enabled_plugins 打开,并给 /skills 加了清单、搜索、Space 开关、Shared 标签页与按 scope 固定版本 / 别名的能力。官方还写明:开启 registry skills 时,项目级的技能、文件与 pin 会覆盖同名全局项(包含 skill_paths 来的技能),且 30 天未使用、registry 仍可提供的缓存共享技能版本会被删除。

# 配置层级:用户层 ~/.vibe/config.toml,项目层 .vibe/config.toml(需被信任)
# 先用官方命令查本机实际支持的键名,别凭印象写配置
vibe config schema > vibe-schema.json
python -c "import json; d=json.load(open('vibe-schema.json')); print(type(d).__name__)"

# 严格模式:未知键直接报错,而不是仅告警(两种写法任选)
# 在 ~/.vibe/config.toml 里写: strict_config = true
# 或临时用环境变量: VIBE_STRICT_CONFIG=1
VIBE_STRICT_CONFIG=1 vibe --prompt "只回答 OK 两个字" \
  --max-tokens 300 --max-price 0.005 --auto-approve \
  --output json --output-dir out/strict

# 交互模式里检查技能清单与开关
# vibe  →  输入 /skills  →  Space 切换技能、Shared 标签页里固定版本
# 插件开关示意(键名以 vibe config schema 的输出为准):
# disabled_plugins = ["unused-plugin"]
# enabled_plugins  = ["review-helper"]

配置优先级容易被忽略:官方配置参考给出的层级是默认值 → 模型目录 → 远程实验配置 → 用户 ~/.vibe/config.toml → 项目 .vibe/config.toml → VIBE_* 环境变量 → 会话覆盖 → agent profile → 管理员策略(最高)。项目层只有被信任才会参与合并;管理员层会盖过下面所有层。因此「本地改了没生效」时,先查项目层是否被信任、管理员策略是否覆盖,以及 export.json 的 warnings 里有没有配置加载告警。

Step 6:把验收收成一段 CI 可执行的门禁脚本

6 用 outcome 与退出码做判定,而不是解析人话输出

流程线的正确姿势是:固定预算参数、固定 --output-dir、读 export.json 做机器判定。下面这个脚本把 finished 视为通过,把预算类 outcome 视为「需要人工看产物」,把配置 / 基础设施错误视为失败,并把 warnings 打出来供排查。

# gate.py —— 在 vibe 运行结束后执行,参数为导出目录与退出码
import json, sys

out_dir, exit_code = sys.argv[1], int(sys.argv[2])
d = json.load(open(out_dir + "/export.json"))
outcome = d.get("outcome")
print("vibe_version =", d.get("vibe_version"))
print("outcome      =", outcome)
print("cost_usd     =", d.get("cost_usd"))
print("steps        =", d.get("steps"))
for w in d.get("warnings", []):
    print("warning:", w.get("message"), "from", w.get("source"))

if outcome == "finished":
    print("GATE: PASS")
    sys.exit(0)
if outcome in ("token_limit", "price_limit", "turn_limit", "deadline"):
    print("GATE: BUDGET_STOPPED — 检查产物后决定是否续跑")
    sys.exit(3)
print("GATE: FAIL —", outcome, "exit_code =", exit_code)
sys.exit(1)

# 流水线里的调用形态:
# vibe --prompt-file task.md --max-tokens 5000 --max-price 0.05 \
#   --auto-approve --output json --output-dir out/ci
# code=$?; python gate.py out/ci "$code"
💡 官方说明只有参数解析器直接拒绝(未知旗标、取值格式错)才会以退出码 1 结束且不生成 export;因此门禁脚本可以假定「有导出文件」是常态,把真正的错误判定交给 outcome。若流水线需要累计多次续跑的总成本,请自行把各次 cost_usd 相加,别指望单次导出给出会话总额。

做到哪一步算成功:交付前自查

下面这张表是本轮实操的验收栏。只要能稳定复现前三行,就说明双预算闸门已经在你的环境里真正生效。

检查项预期结果没过怎么办
安装与版本vibe --version 有输出,交互模式可登录或读到密钥检查 Python 是否为 GIL 构建,必要时按官方 cpython-3.14+gil 路线重装
导出文件每个 --output-dir 下都有 export.json,含 outcome / cost_usd / steps确认是否用了解析器拒绝的旗标(退出码 1 且无导出)
token 闸门极小 --max-tokens 得到 token_limit 与退出码 3把任务换成需要多轮推理的只读任务,避免太快结束
价格闸门极小 --max-price 得到 price_limit 与退出码 3核对模型价格表;定价为 0 的模型按免费计算,闸门不会按预期触发
fan-out 场景子任务派生后仍能在下一次 completion 前停下,状态行说明等待对象对照官方 3.1.2 Release 核对版本,旧版可能在一轮结束后才结算
续跑--resume 能接上 session_id,预算从新 run 重新计算从 export.json 取 session_id,别用终端里显示的短 id 猜
配置与技能vibe config schema 可打印键名,/skills 能切换技能查项目层是否被信任、管理员层是否覆盖、warnings 有无加载告警
密钥脚本与导出里没有明文密钥,--auto-approve 只用于隔离仓库改为环境变量注入并缩小工具白名单
🎉 做到这些,你的 Agent 已经从「跑起来看运气」变成「有预算、有导出、有退出码、可续跑、可进 CI」。后续再把同样的门禁套到真实任务上,只需调整 --max-tokens / --max-price 两个数值与 gate.py 的判定分支。

交付前自查的最后一条:本教程命令与字段来自 Mistral Vibe 官方 README、v3.1.2 Release、程序模式文档与配置参考,按 2026-11-16 核对到的版本撰写。官方仍在密集迭代(3.1.0 是 11 月 4 日、3.1.1 是 11 月 9 日、3.1.2 是 11 月 10 日),旗标与导出字段可能变化;上线门禁前请用 vibe --help 与 vibe config schema 复核一次。

常见问题速查

现象大概率原因与处理
新终端提示找不到 vibe官方说明执行 uv tool update-shell 后重开终端
free-threaded Python 装不上按 README 装 cpython-3.14 并用 --python cpython-3.14+gil 安装
工具调用全被拒绝程序模式不加 --auto-approve 时,需要审批的调用会被拒绝;也可改用 --enabled-tools 精确放行
退出码 3,但 export 里没有报错这是预算 / 轮次 / 时间等「未完成但留下产物」的正常 outcome,读 outcome 判定
--max-price 0 没拦住本地模型官方把定价为 0 的模型视为免费;改用 --max-tokens 或 --max-turns 兜底
预算触顶后仍有输出继续出现已获准的调用允许跑完(含重试);闸门阻止的是下一次 completion 启动
等待子智能体时发的消息没反应确认已升到 3.1.2;该版本修了消息即时送达,并让状态行说明等待对象
项目级技能没覆盖全局同名技能registry skills 需开启,且项目 .vibe/config.toml 需被信任;查配置层级与 warnings
改了配置却不生效用 vibe config schema 核对键名;必要时开 strict_config = true 让未知键直接报错
导出里成本比预期低很多检查是否用了免费定价模型、缓存命中,或续跑后只统计本次 run
📌 配套阅读:本中心《Mistral Vibe 使用手册:云端异步 Agent,启动任务就去忙别的》讲的是交互入门与异步用法;本篇只处理 3.1.2 的 headless 预算闸门与配置治理,两者角度不同。
← 返回教程中心