summarize refresh-free 命令详解：自动探测 OpenRouter 免费模型并写入配置-平芜编程栈

summarize refresh-free 命令详解：自动探测 OpenRouter 免费模型并写入配置

【免费下载链接】summarizePoint at any URL/YouTube/Podcast or file. Get the gist. CLI and Chrome Extension.项目地址: https://gitcode.com/GitHub_Trending/summarize/summarize

本指南围绕 summarize 项目中的refresh-free子命令展开，讲解如何让 CLI 自动扫描 OpenRouter 的:free免费模型目录、用小基准测试实测可用性、并按智能排序把可用候选写入~/.summarize/config.json的models.free配置。读完本文，你将掌握该命令的完整参数体系、底层实现链路（目录拉取 → 过滤 → 基准测试 → 精炼 → 写配置），以及如何在日常使用中通过--model free免去手动挑选 OpenRouter slug 的麻烦。

命令概述与适用场景

summarize refresh-free是 summarize CLI 的一个专门子命令，核心作用是用真实请求验证 OpenRouter 上哪些:free模型当前可用，并把“幸存者”写入配置文件：

summarize refresh-free [--runs 2] [--smart 3] [--min-params 27b] [--max-age-days 180] [--set-default] [--verbose]

该命令面向的典型场景是：你想使用--model free（见 LLM 模型语法文档），但又不想手工指定具体的openrouter/<author>/<slug>:free。由于 OpenRouter 的免费模型供给是动态的——模型可能下线、被限流、或长期没有可用 provider——一条写死的 slug 随时可能失效。refresh-free把“挑选可用免费模型”这件事自动化：拉目录、过滤、实测、落盘，全程无需人工干预。

前置条件：环境中必须存在OPENROUTER_API_KEY。从源码看，入口函数refreshFree会检查该环境变量（去除首尾空白后非空才通过），否则直接抛出Missing OPENROUTER_API_KEY (required for refresh-free)（见 src/refresh-free.ts）。

命令执行流程

按官方文档，命令执行分 5 个阶段，结合源码可以展开为更细的实现链路（主要实现在 src/refresh-free.ts 及其同目录模块中）：

拉取 OpenRouter 模型目录：调用https://openrouter.ai/api/v1/models获取完整目录。对应 catalog.ts 中的fetchOpenRouterCatalog，请求头带Accept: application/json，非 2xx 响应会抛出OpenRouter /models failed: HTTP <status>。
按标签与参数过滤：先只保留 id 以:free结尾的模型，再依次套用--max-age-days（基于 OpenRouter 元数据created时间戳换算）和--min-params（基于参数规模）两个过滤器。过滤逻辑见 filterOpenRouterFreeModels。
对每个候选跑--runs次基准测试：用一条“sanity prompt”实测每个模型的延迟、完成长度与拒绝率，并按--smart启发式排序。具体探测请求见 benchmark.ts 的runProbe：prompt 为Reply with a single word: OK，temperature: 0、maxOutputTokens: 16、单次超时 10 秒、forceOpenRouter: true、重试 0 次。
把幸存者写入models.free：更新~/.summarize/config.json，结构为models.free = { "rules": [{ "candidates": [...] }] }。
可选设置默认模型：指定--set-default时，额外把配置顶层model字段设为"free"。

运行完成后，执行summarize "https://example.com" --model free时，CLI 会按保存的列表顺序依次尝试，直到某个候选成功为止（旋转式 failover）。

参数（Flags）详解

以下参数均来自官方文档，默认值与解析行为已结合源码（src/run/cli-preflight.ts 的handleRefreshFreeRequest）核实：

参数	作用	默认值	源码侧解析细节
`--runs <n>`	每个候选探测多少次。实际总次数为`1 + --runs`：首轮全量初筛加`--runs`次精炼	`2`	必须`>= 0`，取整
`--smart <n>`	保留多少个排名靠前的候选	`3`	必须`>= 0`，取整；同时受`maxCandidates`（固定 10）上限约束
`--min-params <size>`	最小参数量，接受`7b`、`27b`、`70b`等写法	`27b`	解析时自动剥离末尾`b`；必须`>= 0`
`--max-age-days <n>`	拒绝“年龄”超过 N 天的模型（依据 OpenRouter 元数据）	`180`	必须`>= 0`；设为`0`时跳过该过滤
`--set-default`	同时把配置顶层`model`设为`"free"`	关闭	写配置时执行`root.model = "free"`
`--verbose`	在 stderr 输出每个候选的进度、耗时与拒绝原因	关闭	`--debug`等价于`--verbose`

说明：参数校验失败（如--runs、--smart、--min-params、--max-age-days传入负数或非数字）会直接报错，错误信息分别提示--runs must be >= 0等约束。另外--min-params只接受27b这类带b后缀或纯数字写法，内部统一转为浮点参数量（minParamB）。

基准测试与排序的底层实现

这是refresh-free最有价值的部分：不是“看到目录里有就写进配置”，而是每个候选都真的发一次 LLM 请求，用结果说话。

探测与失败分类

探测请求走项目统一的generateTextWithModelId（见 src/llm/generate-text.ts），强制走 OpenRouter。失败信息会被classifyBenchmarkFailure归类为 7 类（benchmark.ts）：

empty：返回空摘要
rateLimitMin/rateLimitDay：OpenRouter 免费模型的分/日级限流（根据错误文案中的free-models-per-min、free-models-per-day等关键词区分）
noProviders：no allowed providers are available
timeout：超时或中止
providerError：provider 返回错误
other：其他

遇到分钟级限流时，基准测试会触发 65 秒冷却（cooldownMs = 65_000），等待后对该候选重试一次，冷却期间进度输出会提示rate limit hit; sleeping …。

排序启发式

有两套排序，对应“聪明优先”和“快优先”两个维度（selectBenchmarkCandidates）：

smartFirst（智能优先）：依次比较上下文长度、最大输出 token、支持的参数数量、成功率、中位延迟，最终以模型 id 兜底排序；
fastFirst（快速优先）：先比成功率，再比中位延迟。

最终名单先从 smartFirst 中取前min(--smart, 10)个，不足 10 个时再用 fastFirst 补齐到 10 个。--runs指定的额外轮次只对这批精选候选做精炼（refineBenchmarkCandidates），重新计算中位延迟与成功率。

过滤细节

目录解析（catalog.ts）会从模型 id 与名称中正则推断参数量（如27b、70b），推断不出的模型按“不设下限”处理（inferredParamB === null时保留）；年龄过滤基于 OpenRouter 的created字段，单位为毫秒换算。排序进基准前，模型按“发布时间最新 → 上下文最长 → 输出 token 最多 → 支持参数最多”排序（rankOpenRouterModelsForBenchmark），确保较新、能力较强的模型优先被测试。

输出：写入`~/.summarize/config.json`

命令执行成功后，~/.summarize/config.json被原地更新（Wrote <path> (models.free)提示打印在 stdout），相关片段如下：

{ "models": { "free": ["openai/gpt-oss-120b:free", "z-ai/glm-4.6:free", "deepseek/deepseek-r1:free"] } }

写入逻辑（src/refresh-free/config.ts）有几点值得注意：

路径解析：基于HOME环境变量或系统 home 目录，拼接.summarize/config.json；
保留原配置：先以 JSON5 解析现有文件（若文件不存在则视为空对象），只改写models.free字段，其他配置原样保留；解析时若发现//或/* */注释会报错拒绝写入；
原子写入：先写临时文件（config.json.tmp-<pid>-<ts>，权限0600），再rename覆盖，避免写一半留下损坏配置；~/.summarize目录以0700权限创建；
候选前缀：落盘时每个候选自动加上openrouter/前缀（源码第 160 行openrouter/${id}），确保--model free能直接按强制 OpenRouter 语法解析；
--set-default：同时设置顶层"model": "free"（见 config.ts）。

stdout 上还会打印幸存者与拒绝候选的简短摘要；--verbose时每个被跳过的模型（过老、过小）都会以skip <id>形式逐条输出。

使用示例

官方文档给出 4 个典型用法，全部可直接复制运行：

# 快速刷新；保留最佳 3 个 ≥27B、≤180 天内的免费模型 summarize refresh-free # 放宽过滤——接受更小、更旧的模型 summarize refresh-free --min-params 7b --max-age-days 365 # 刷新并把默认模型设为 free summarize refresh-free --set-default # 调试用：更密集的探测与详细排名输出 summarize refresh-free --runs 3 --smart 5 --verbose

与`--model free`的联动

free是项目内置的模型预设：从源码看，内置目录（src/application/model-catalog.ts）中free预设本身就是一个mode: "auto"的 rules 配置，包含一批由summarize refresh-free生成的快照候选（注释标注 Snapshot 日期）。运行refresh-free后，models.free会被用户配置覆盖，之后每次--model free都按新名单轮询。

轮询逻辑由 src/application/model-selection.ts 处理：free被识别为“命名模型选择”（wantsFreeNamedModel），解析为 auto 模式的规则列表，执行时按candidates[]顺序逐个尝试、失败即换下一个。当所有候选都失败时，错误信息会附带一句补救提示（src/engine/summary-execution.ts）：

Tip: run "summarize refresh-free" to refresh the free model candidates (writes ~/.summarize/config.json).

这意味着即使免费模型大面积失效，CLI 也会引导你一键重新探测，而不是让你去手工查目录。

颜色输出与终端行为

输出颜色遵循 CLI 整体约定：FORCE_COLOR=0强制关闭颜色；非零的FORCE_COLOR优先于NO_COLOR；两者都未设置时，只有能力足够的终端才启用颜色。进度行在 TTY 下会实时刷新（每 150ms 一次），非 TTY 下降级为每 1500ms 打印一行（见 presentation.ts 的RefreshFreeReporter）。

测试与验证

仓库为refresh-free提供了多层次的测试佐证，可继续深入阅读：

tests/cli.refresh-free.test.ts：端到端覆盖——验证写入models.free的路径输出（含 en/tr 双语言）、--set-default设置顶层model=free、--runs 0/--min-params 0b等边界参数、失败分支与--verbose输出；
tests/cli.help.test.ts：校验refresh-free --help能打印完整 Usage；
tests/cli.model-presets.free.test.ts：验证--model free失败时错误信息会附带summarize refresh-free提示；
tests/live/free-preset.live.test.ts：带真实 API Key 的 live 测试，覆盖“refresh-free 后--model free返回可用 LLM”的完整闭环。

此外，refresh-free的能力也暴露给了后台守护进程：daemon 提供POST /v1/refresh-free管理路由（见 src/daemon/server-refresh-route.ts），扩展或面板可通过该路由触发同样的刷新流程（对应测试 tests/daemon.server-refresh-route.test.ts）。

summarize refresh-free 命令详解：自动探测 OpenRouter 免费模型并写入配置