@bd7pil/reeve 0.1.6 → 0.1.7

package/default-fallback.json

@@ -1,5 +1,5 @@
 {
-  "//": "GATE 的兜底配置（机器上没有任何 reeve-fallback.jsonc 时用它）。刻意只放付费候选——免费车道（9router）属于每台机器自己的选择，写在用户配置里。",
+  "//": "GATE 的兜底配置（机器上没有任何 reeve-fallback.jsonc 时用它）。刻意只放付费候选——免费车道（@free）属于每台机器自己的选择，写在用户配置里。",
   "//cells": "providers.<id>：base_url + path（默认 /v1/chat/completions）+ auth（auth.json 里的 id，按序取第一个有 key 的）+ key（env.X 引用或公开字面量，覆盖 auth）+ lane（native | passthrough）+ models/models_fetch（目录来源）。",
   "//tiers": "chain_for_model 里的 `reeve/*` 三条 = 引擎档位模型（插件注册的 reeve/flash|pro|multimodal）。引擎发**全名**进请求体，键必须写全名。没有免费车道时：flash → tier2a（便宜付费链）、multimodal → tier2a（bundle 里没有视觉专链）。",
   "schema": 1,
@@ -14,14 +14,26 @@
     "session_ttl_seconds": 1800
   },
   "providers": {
-    "9router": { "base_url": "http://127.0.0.1:20128", "key": "none", "models": ["*"], "models_fetch": true },
+    "opencode": { "base_url": "https://opencode.ai/inference/openai/v1", "path": "/chat/completions", "key": "public", "lane": "passthrough", "models": ["*"] },
+    "openrouter": { "base_url": "https://openrouter.ai/api/v1", "auth": ["openrouter"], "models": [] },
+    "nvidia": { "base_url": "https://integrate.api.nvidia.com/v1", "auth": ["nvidia"], "models": [] },
     "zhipuai-coding-plan": { "base_url": "https://open.bigmodel.cn", "path": "/api/coding/paas/v4/chat/completions", "auth": ["zhipuai-coding-plan"] },
     "xxyapi-deepseek": { "base_url": "https://www.xxyapi.com", "auth": ["xxyapi-deepseek"] },
     "lmuai": { "base_url": "https://api.lmuai.com", "auth": ["lmuai", "lmuai-glm"] },
     "deepseek": { "base_url": "https://api.deepseek.com", "auth": ["deepseek", "deepseek-api"] },
     "xiaomi": { "base_url": "https://api.xiaomimimo.com", "auth": ["xiaomi"] },
-    "alibaba-cn": { "base_url": "https://dashscope.aliyuncs.com", "path": "/compatible-mode/v1/chat/completions", "auth": ["alibaba-cn"] },
-    "opencode": { "base_url": "https://opencode.ai/inference/openai/v1", "path": "/chat/completions", "key": "public", "lane": "passthrough", "models": ["*"] }
+    "alibaba-cn": { "base_url": "https://dashscope.aliyuncs.com", "path": "/compatible-mode/v1/chat/completions", "auth": ["alibaba-cn"] }
+  },
+  "free": {
+    "enabled": true,
+    "max": 3,
+    "providers": ["opencode", "openrouter", "nvidia"],
+    "refresh_seconds": 300,
+    "failure_threshold": 3,
+    "failure_cooldown_seconds": 600,
+    "prefer": [],
+    "deny": [],
+    "static": {}
   },
   "chains": {
     "tier1": { "targets": ["zhipuai-coding-plan/glm-5.3", "deepseek/deepseek-flash"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bd7pil/reeve",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "REEVE 编排层（opencode v2 插件）：agent/skill 注册 + 子任务台账 + GATE 代理层（路由/回退/台账）+ 性能统计",
   "type": "module",
   "main": "index.js",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node test/unit.mjs && node test/reconcile.mjs && node test/snapshot.mjs && node test/gate.mjs && node test/guard.mjs && node test/stats.mjs && node test/entry.mjs && node test/wiring.mjs && node test/runtime.mjs",
+    "test": "node test/unit.mjs && node test/reconcile.mjs && node test/snapshot.mjs && node test/gate.mjs && node test/free.mjs && node test/guard.mjs && node test/stats.mjs && node test/entry.mjs && node test/wiring.mjs && node test/runtime.mjs",
     "test:coverage": "c8 --reporter=text --reporter=json-summary --reports-dir=coverage --exclude=test/** --exclude=bench.mjs npm test",
     "check:coverage": "node ../scripts/check-coverage.mjs",
     "prepublishOnly": "npm test"

package/provision.json

@@ -1,7 +1,7 @@
 {
   "schema": 1,
   "name": "reeve",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "license": "MIT",
   "//": "REEVE 在 ocrc 实例里的装配说明。**没有二进制工件** —— 代理层是插件内的 GATE（纯 JS），不需要任何本地服务（Bifrost 时代已结束）。",
   "host": {
@@ -15,7 +15,7 @@
     ]
   },
   "enginePlugin": {
-    "spec": "@bd7pil/reeve@0.1.6",
+    "spec": "@bd7pil/reeve@0.1.7",
     "kind": "package",
     "entry": "~/.ocrc/components/reeve/node_modules/@bd7pil/reeve",
     "requiresPeer": []

package/src/gate/config.js

@@ -35,6 +35,24 @@ export const POLICY_DEFAULTS = Object.freeze({
 const DEFAULT_PATH = '/v1/chat/completions'
 export const LANES = Object.freeze({ NATIVE: 'native', PASSTHROUGH: 'passthrough' })
 
+/** 免费车道的默认值（面板可改；见 docs/FREE-LANE.md）。 */
+export const FREE_DEFAULTS = Object.freeze({
+  enabled: true,
+  max: 3,
+  providers: Object.freeze(['opencode', 'openrouter', 'nvidia']),
+  refresh_seconds: 300,
+  failure_threshold: 3,
+  failure_cooldown_seconds: 600,
+  prefer: Object.freeze([]),
+  deny: Object.freeze([]),
+  static: Object.freeze({}),
+  sources: Object.freeze({
+    // 公开模型列表（不需要键；拉不到只影响该 provider，请求照常降级到付费）
+    opencode: Object.freeze({ url: 'https://opencode.ai/zen/v1/models', filter: 'opencode-free' }),
+    openrouter: Object.freeze({ url: 'https://openrouter.ai/api/v1/models', filter: 'openrouter-free' }),
+  }),
+})
+
 export function stripLineComments(text) {
   return String(text)
     .split('\n')
@@ -87,6 +105,44 @@ export function normalizeGateConfig(raw) {
     }
   }
 
+  // 免费车道：发现源 + @free 展开的偏好。全部有默认值；坏字段进 problems，不影响其余配置。
+  const asInt = (v, min, max, dflt) => {
+    const n = Number(v)
+    return Number.isFinite(n) ? Math.min(max, Math.max(min, Math.trunc(n))) : dflt
+  }
+  const fSrc = asRecord(src.free) ?? {}
+  const freeProviders = asStrings(fSrc.providers).length > 0 ? asStrings(fSrc.providers) : [...FREE_DEFAULTS.providers]
+  const free = {
+    enabled: fSrc.enabled !== false,
+    max: asInt(fSrc.max, 0, 8, FREE_DEFAULTS.max),
+    providers: freeProviders,
+    refresh_seconds: asInt(fSrc.refresh_seconds, 30, 86_400, FREE_DEFAULTS.refresh_seconds),
+    failure_threshold: asInt(fSrc.failure_threshold, 1, 20, FREE_DEFAULTS.failure_threshold),
+    failure_cooldown_seconds: asInt(fSrc.failure_cooldown_seconds, 60, 86_400, FREE_DEFAULTS.failure_cooldown_seconds),
+    prefer: asStrings(fSrc.prefer),
+    deny: asStrings(fSrc.deny),
+    static: {},
+    sources: { ...FREE_DEFAULTS.sources },
+  }
+  for (const [id, list] of Object.entries(asRecord(fSrc.static) ?? {})) {
+    if (!Array.isArray(list)) {
+      problems.push(`free.static.${id} 不是数组（忽略）`)
+      continue
+    }
+    free.static[id] = asStrings(list)
+  }
+  for (const [id, v] of Object.entries(asRecord(fSrc.sources) ?? {})) {
+    const s = asRecord(v)
+    if (!s || typeof s.url !== 'string' || s.url.length === 0) {
+      problems.push(`free.sources.${id} 缺 url（忽略）`)
+      continue
+    }
+    free.sources[id] = { url: s.url, filter: typeof s.filter === 'string' && s.filter.length > 0 ? s.filter : FREE_DEFAULTS.sources[id]?.filter ?? 'opencode-free' }
+  }
+  for (const id of free.providers) {
+    if (!providers[id]) problems.push(`free.providers 含未配置的 provider：${id}（会被跳过）`)
+  }
+
   const chains = {}
   for (const [name, v] of Object.entries(asRecord(src.chains) ?? {})) {
     const targets = asStrings(asRecord(v)?.targets)
@@ -118,7 +174,7 @@ export function normalizeGateConfig(raw) {
   const defaultChain = typeof src.default_chain === 'string' && chains[src.default_chain] ? src.default_chain : Object.keys(chains)[0] ?? null
   if (defaultChain === null) problems.push('没有可用的链（default_chain 缺失）')
 
-  return { schema: 1, policy, providers, chains, agents, chain_for_model: chainForModel, default_chain: defaultChain, problems }
+  return { schema: 1, policy, providers, chains, agents, chain_for_model: chainForModel, default_chain: defaultChain, free, problems }
 }
 
 /**

package/src/gate/free.js

@@ -0,0 +1,271 @@
+// GATE 的自动免费车道。
+//
+// 为什么需要它：免费档（OpenCode Free / OpenRouter `:free` / NVIDIA 免费额度）的**模型列表会变**
+// 且**时好时坏**。写死候选会腐坏；写一个"管理器"定时改配置又会 churn 用户的文件。这里的做法是：
+//   · 链里只写占位符 `@free`；
+//   · 请求时按"发现到的、未冷却的、有键的"候选**展开**成真实 provider/model；
+//   · 发现结果带 TTL（`free.refresh_seconds`），失败保留上一份好列表并如实记错误；
+//   · 失败的免费模型按 **ref** 进全局冷却（连续 `failure_threshold` 次 → `failure_cooldown_seconds`），
+//     全部冷却/不可用 → 本次直接走链里的付费候选（不硬撞限流）。
+//
+// 时间与 IO 全部注入（`now` / `fetchImpl`），测试用假时钟 + 发现源 stub，不 sleep、不出网。
+import { parseTarget, resolveKeyFor, targetKey } from './lanes.js'
+
+export const FREE_TOKEN = '@free'
+
+/** 免费过滤规则（与上游自己的"免费"口径对齐；opencode 排掉已知非免费的 v4-flash）。 */
+export const FREE_FILTERS = Object.freeze({
+  'opencode-free': (id) => id !== 'deepseek-v4-flash-free' && (id.endsWith('-free') || id === 'big-pickle'),
+  'openrouter-free': (id) => id.endsWith(':free'),
+  all: () => true,
+})
+
+const asList = (v) => (Array.isArray(v) ? v.map((x) => String(x)).filter((x) => x.length > 0) : [])
+
+/**
+ * @param {object} opts
+ * @param {() => object|null} opts.getConfig 归一化后的当前配置（热更后即时生效）
+ * @param {() => object} [opts.getAuth] auth.json
+ * @param {() => number} [opts.now]
+ * @param {Function} [opts.fetchImpl]
+ * @param {{debug?: Function}|null} [opts.logger]
+ * @param {number} [opts.timeoutMs] 发现请求超时（不能把首笔请求拖太久）
+ */
+export function createFreeLane({ getConfig, getAuth = () => ({}), now = Date.now, fetchImpl = fetch, logger = null, timeoutMs = 2500 } = {}) {
+  /** providerId -> { at, models: string[], error: string|null, from: string|null, sig: string } */
+  const cache = new Map()
+  /** ref -> { fails: number, until: number }（全局，跨 session：坏模型对所有人都坏） */
+  const cooldowns = new Map()
+  const inflight = new Map()
+
+  const freeCfg = () => {
+    const f = getConfig()?.free
+    return f && typeof f === 'object' ? f : { enabled: false, max: 0, providers: [], prefer: [], deny: [], static: {}, sources: {} }
+  }
+  const providers = () => getConfig()?.providers ?? {}
+  const policy = () => getConfig()?.policy ?? {}
+
+  const hasKey = (provider) => {
+    try {
+      return resolveKeyFor(provider, { env: process.env, auth: getAuth() ?? {} }) !== null
+    } catch {
+      return false
+    }
+  }
+
+  const sourceOf = (free, id) => {
+    const staticList = free.static?.[id]
+    if (Array.isArray(staticList)) return { kind: 'static', models: asList(staticList) }
+    const src = free.sources?.[id]
+    if (src && typeof src.url === 'string' && src.url.length > 0) {
+      return { kind: 'fetch', url: src.url, filter: FREE_FILTERS[src.filter] ?? FREE_FILTERS['opencode-free'] }
+    }
+    return null
+  }
+
+  const doLoad = async (id, { force = false } = {}) => {
+    const free = freeCfg()
+    const provider = providers()[id]
+    // 调用方（discovered/warm）已保证 provider 存在且带 base_url；这里不再重复判空（否则是测不到的死分支）
+    const src = sourceOf(free, id)
+    if (!src) {
+      const st = { at: now(), models: [], error: '没有发现源（static 或 sources）', from: null, sig: `none:${id}` }
+      cache.set(id, st)
+      return st
+    }
+    if (src.kind === 'static') {
+      const st = { at: now(), models: src.models, error: null, from: 'static', sig: `static:${id}` }
+      cache.set(id, st)
+      return st
+    }
+    const ttlMs = Math.max(30, Number(free.refresh_seconds ?? 300)) * 1000
+    const prev = cache.get(id)
+    if (!force && prev && prev.sig === src.url && now() - prev.at < ttlMs && prev.error === null) return prev
+    try {
+      const res = await fetchImpl(src.url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const body = await res.json()
+      const raw = Array.isArray(body?.data) ? body.data : Array.isArray(body?.models) ? body.models : []
+      const models = [...new Set(raw.map((m) => (typeof m === 'string' ? m : m?.id)).filter((x) => typeof x === 'string' && x.length > 0).filter(src.filter))]
+      const next = { at: now(), models, error: null, from: src.url, sig: src.url }
+      cache.set(id, next)
+      return next
+    } catch (err) {
+      // 拉不到就**保留上一份好列表**（免费池抖一下不该让链里突然没有免费候选）
+      const next = { at: now(), models: prev?.models ?? [], error: String(err?.message ?? err).slice(0, 140), from: src.url, sig: src.url }
+      cache.set(id, next)
+      logger?.debug?.(`[gate] 免费车道发现失败 ${id}：${next.error}`)
+      return next
+    }
+  }
+
+  const load = (id, opts) => {
+    if (!inflight.has(id)) {
+      const p = doLoad(id, opts).finally(() => inflight.delete(id))
+      inflight.set(id, p)
+    }
+    return inflight.get(id)
+  }
+
+  const isCooling = (ref) => {
+    const c = cooldowns.get(ref)
+    if (!c) return false
+    // until=0 表示"失败次数还没到阈值"：**保留计数**，不能当成已过期删掉（否则永远攒不到阈值）
+    if (c.until === 0) return false
+    if (now() >= c.until) {
+      cooldowns.delete(ref)
+      return false
+    }
+    return true
+  }
+
+  const denySet = () => new Set(asList(freeCfg().deny))
+  const denied = (c, deny) => deny.has(c.ref) || deny.has(c.model)
+
+  /** 当前可发现的免费候选（provider 顺序 × 目录顺序）。不发请求时靠 TTL 缓存。 */
+  const discovered = async () => {
+    const free = freeCfg()
+    if (!free.enabled) return []
+    const out = []
+    for (const id of asList(free.providers)) {
+      const provider = providers()[id]
+      if (!provider?.base_url || !hasKey(provider)) continue
+      const st = await load(id)
+      for (const model of st.models ?? []) out.push({ provider: id, model, ref: `${id}/${model}` })
+    }
+    return out
+  }
+
+  /** prefer 里可以是 full ref（`opencode/x`）或裸模型名；命中的排最前，其余保持发现序。 */
+  const rank = (list, prefer) => {
+    const out = []
+    const seen = new Set()
+    for (const p of prefer) {
+      for (const c of list) {
+        if (seen.has(c.ref)) continue
+        if (c.ref === p || c.model === p) {
+          out.push(c)
+          seen.add(c.ref)
+          break
+        }
+      }
+    }
+    for (const c of list) if (!seen.has(c.ref)) out.push(c)
+    return out
+  }
+
+  const capFor = () => {
+    const free = freeCfg()
+    const maxAttempts = Math.max(1, Number(policy().max_fallback_attempts ?? 3))
+    // 永远给付费兜底留一跳：免费最多占 maxAttempts - 1
+    return Math.max(0, Math.min(Number(free.max ?? 0), maxAttempts - 1))
+  }
+
+  /**
+   * 把 targets 里的 `@free` 换成本次要试的真实候选。
+   * @returns {{targets: Array<object>, expanded: string[], dynamic: boolean}}
+   */
+  const expand = async (targets, { maxAttempts = null } = {}) => {
+    const list = Array.isArray(targets) ? targets : []
+    const hasToken = list.some((t) => t?.free)
+    if (!hasToken) return { targets: list, expanded: [], dynamic: false }
+    const base = list.filter((t) => !t?.free)
+    const free = freeCfg()
+    const cap = maxAttempts === null ? capFor() : Math.max(0, Math.min(Number(free.max ?? 0), Math.max(1, Number(maxAttempts)) - 1))
+    if (!free.enabled || cap === 0) return { targets: base, expanded: [], dynamic: true }
+    const deny = denySet()
+    const explicit = new Set(base.map((t) => targetKey(t)))
+    const all = (await discovered()).filter((c) => !denied(c, deny) && !isCooling(c.ref) && !explicit.has(c.ref))
+    const picked = rank(all, asList(free.prefer)).slice(0, cap)
+    const expandedTargets = picked.map((c) => ({ provider: c.provider, model: c.model, auto: true }))
+    const out = []
+    let injected = false
+    for (const t of list) {
+      if (t?.free) {
+        if (!injected) {
+          out.push(...expandedTargets)
+          injected = true
+        }
+        continue
+      }
+      out.push(t)
+    }
+    return { targets: out, expanded: picked.map((c) => c.ref), dynamic: true }
+  }
+
+  /** 只对 `@free` 展开出来的候选记全局健康（显式候选沿用按 session 的冷却）。 */
+  const noteAttempt = (attempt, ok) => {
+    if (attempt?.auto !== true) return
+    const providerId = attempt.provider?.id ?? attempt.provider
+    const ref = `${providerId}/${attempt.model}`
+    if (ok) {
+      cooldowns.delete(ref)
+      return
+    }
+    const free = freeCfg()
+    const threshold = Math.max(1, Number(free.failure_threshold ?? 3))
+    const cur = cooldowns.get(ref) ?? { fails: 0, until: 0 }
+    cur.fails += 1
+    if (cur.fails >= threshold) cur.until = now() + Math.max(0, Number(free.failure_cooldown_seconds ?? 600)) * 1000
+    cooldowns.set(ref, cur)
+  }
+
+  /** 面板/快照用的运行态（不触发新的发现请求：只读缓存；缓存为空则如实报 0/未刷新）。 */
+  const runtime = () => {
+    const free = freeCfg()
+    const provs = []
+    for (const id of asList(free.providers)) {
+      const provider = providers()[id]
+      const st = cache.get(id)
+      provs.push({
+        id,
+        ready: Boolean(provider?.base_url) && hasKey(provider),
+        models: st?.models?.length ?? 0,
+        error: st?.error ?? null,
+        at: st?.at ?? null,
+        source: st?.from ?? null,
+      })
+    }
+    const cooling = [...cooldowns.entries()]
+      .filter(([, c]) => now() < c.until)
+      .map(([ref, c]) => ({ ref, fails: c.fails, until: c.until }))
+    return {
+      enabled: free.enabled !== false,
+      max: Number(free.max ?? 0),
+      cap: capFor(),
+      providers: provs,
+      cooling,
+      prefer: asList(free.prefer),
+      deny: asList(free.deny),
+    }
+  }
+
+  /** 当前展开预览（面板用；会按 TTL 触发发现）。 */
+  const snapshot = async () => {
+    const free = freeCfg()
+    const cfg = getConfig()
+    let chain = null
+    let expandedRefs = []
+    if (free.enabled !== false && cfg?.chains) {
+      const hit = Object.entries(cfg.chains).find(([, c]) => (c.targets ?? []).some((t) => t === FREE_TOKEN))
+      if (hit) {
+        chain = hit[0]
+        const parsed = (hit[1].targets ?? []).map(parseTarget).filter(Boolean)
+        const out = await expand(parsed, { maxAttempts: policy().max_fallback_attempts })
+        expandedRefs = out.expanded
+      }
+    }
+    return { ...runtime(), chain, expand: expandedRefs }
+  }
+
+  /** 启动/热更后的后台预热（失败静默，不阻塞）。 */
+  const warm = () => {
+    const free = freeCfg()
+    if (free.enabled === false) return
+    for (const id of asList(free.providers)) {
+      if (providers()[id]?.base_url && hasKey(providers()[id])) void load(id).catch(() => {})
+    }
+  }
+
+  return { expand, noteAttempt, isCooling, discovered, snapshot, runtime, warm, capFor }
+}

package/src/gate/gate.js

@@ -5,6 +5,7 @@
 //   POST /gate/session          插件侧的 session→agent 桥（把"这个 session 是 scout"告诉 GATE）
 //   POST /gate/session/:id/next 插件侧要"下一个候选"（流已开始/沉默这两类层内换不了的情形）
 //   GET  /gate/version          探针/测试用
+//   GET  /gate/free             免费车道运行态（发现源/展开预览/冷却）——面板只读它
 //
 // 纪律：① 只记录、不泄漏——台账里没有密钥（只记键的"名字"）；② 时间与 IO 全可注入（测试零 sleep、零真实出网）；
 // ③ 管理面只认环回；④ dispose 尽力而为、绝不因为清理炸掉（含"定时器已开"的情况）。
@@ -16,7 +17,8 @@ import { Readable } from 'node:stream'
 
 import { classifyFailure } from './classify.js'
 import { BUNDLED_FALLBACK_PATH, defaultFallbackConfigPath, loadGateConfig, normalizeGateConfig, watchGateConfig } from './config.js'
-import { attemptKey, attemptRow, buildUpstreamRequest, modelsPathOf, planAttempts, resolveKeyFor, routeFor } from './lanes.js'
+import { createFreeLane } from './free.js'
+import { attemptKey, attemptRow, buildUpstreamRequest, modelsPathOf, parseTarget, planAttempts, resolveKeyFor, routeFor } from './lanes.js'
 import { createSessionStore } from './state.js'
 
 export const GATE_VERSION = '0.1.0'
@@ -143,6 +145,10 @@ export async function startGate({
     return { key: auth[id].key, name: `auth:${id}` }
   }
 
+  // 免费车道：发现（公开模型列表/静态白名单）+ `@free` 展开 + 按 ref 的全局冷却。
+  // 读的是**当前** config（热更即时生效）；时间/IO 注入，测试零出网。
+  const freeLane = createFreeLane({ getConfig: () => config, getAuth: () => auth, now, fetchImpl, logger })
+
   const note = (row) => ledger.write(row)
 
   /** 模型目录：声明 ∪ 运行时池（TTL）∪ 链名。池拉不到就降级（只回声明），不报错。 */
@@ -173,6 +179,12 @@ export async function startGate({
         logger?.debug?.(`[gate] 拉 ${provider.id} 的模型池失败（降级）：${String(err).slice(0, 120)}`)
       }
     }
+    // 免费车道发现到的模型也进目录（面板的选择器才能看到并固定它们；`@free` 本身不需要进）
+    try {
+      for (const c of await freeLane.discovered()) push(c.ref, c.provider)
+    } catch {
+      /* 发现失败只影响目录的完整性，不影响请求 */
+    }
     for (const name of Object.keys(config.chains)) push(name, 'reeve')
     modelsCache.data = data
     modelsCache.at = now()
@@ -200,7 +212,9 @@ export async function startGate({
     const sessionID = typeof req.headers['x-opencode-session-id'] === 'string' ? req.headers['x-opencode-session-id'] : null
     const route = routeFor({ model, sessionID }, { config, sessions })
     if (!route) return sendJson(res, 404, { error: { message: `未知模型或链：${model}` } })
-    const plan = planAttempts(route, { config, sessions, sessionID, keyPicker })
+    // `@free` → 当前可发现、未冷却、有键的真实候选（动态链不复用按索引的粘性指针）
+    const expanded = await freeLane.expand(route.targets, { maxAttempts: config.policy.max_fallback_attempts })
+    const plan = planAttempts({ ...route, targets: expanded.targets, dynamicFree: expanded.dynamic }, { config, sessions, sessionID, keyPicker })
 
     if (plan.ordered.length === 0) {
       return sendJson(res, 502, {
@@ -247,12 +261,14 @@ export async function startGate({
         note(attemptRow({ ts: new Date(t0).toISOString(), chainName: plan.chainName, agent: plan.agent, attempt, status: 'error', code: null, latencyMs: now() - t0, retries, detail, req: reqId, n: i + 1 }))
         attemptsSeen.push({ provider: attempt.provider.id, model: attempt.model, code: null, reason: 'network' })
         sessions.noteFailure(sessionID ?? '(anon)', plan.chainName, attemptKey(attempt))
+        freeLane.noteAttempt(attempt, false)
         continue
       }
 
       if (upstream.ok) {
         note(attemptRow({ ts: new Date(t0).toISOString(), chainName: plan.chainName, agent: plan.agent, attempt, status: 'ok', code: upstream.status, latencyMs: now() - t0, retries, req: reqId, n: i + 1 }))
         sessions.noteSuccess(sessionID ?? '(anon)', plan.chainName, attemptKey(attempt), plan.keys)
+        freeLane.noteAttempt(attempt, true)
         res.writeHead(upstream.status, {
           'content-type': upstream.headers?.get?.('content-type') ?? 'application/json',
           'x-reeve-fallback': `${i + 1}/${attempt.provider.id}/${attempt.model}`,
@@ -276,6 +292,7 @@ export async function startGate({
         return
       }
       sessions.noteFailure(sessionID ?? '(anon)', plan.chainName, attemptKey(attempt))
+      freeLane.noteAttempt(attempt, false)
     }
 
     sendJson(res, 502, { error: { message: '所有候选都失败', chain: plan.chainName, req: reqId, attempts: attemptsSeen } })
@@ -306,6 +323,19 @@ export async function startGate({
           agents: { ...config.agents },
           chain_for_model: { ...config.chain_for_model },
           default_chain: config.default_chain ?? null,
+          // 免费车道的**配置**（运行态在 /gate/free；面板的"已生效"比对用这一份）
+          free: {
+            enabled: config.free.enabled,
+            max: config.free.max,
+            providers: [...config.free.providers],
+            refresh_seconds: config.free.refresh_seconds,
+            failure_threshold: config.free.failure_threshold,
+            failure_cooldown_seconds: config.free.failure_cooldown_seconds,
+            prefer: [...config.free.prefer],
+            deny: [...config.free.deny],
+            static: { ...config.free.static },
+            sources: { ...config.free.sources },
+          },
           problems,
           sessions: sessions.snapshot(),
           ledger: ledger.path,
@@ -313,6 +343,9 @@ export async function startGate({
       }
       if (url.startsWith('/gate/')) {
         if (!LOOPBACK.has(remote)) return sendJson(res, 403, { error: { message: '管理面只认环回' } })
+        if (req.method === 'GET' && url === '/gate/free') {
+          return sendJson(res, 200, await freeLane.snapshot())
+        }
         if (req.method === 'POST' && url === '/gate/session') {
           const bodyText = await readBody(req, 1024 * 1024).catch(() => '{}')
           const { sessionID, agent } = JSON.parse(bodyText || '{}')
@@ -328,7 +361,10 @@ export async function startGate({
           const agent = sessions.agentOf(sessionID)
           const chainName = agent && config.agents[agent] ? config.agents[agent] : config.default_chain
           if (!chainName || !config.chains[chainName]) return sendJson(res, 200, { model: null, chain: null })
-          const keys = config.chains[chainName].targets
+          // 动态链（含 `@free`）在调用时展开，插件侧拿到的才是真实候选而不是占位符
+          const parsed = config.chains[chainName].targets.map(parseTarget).filter(Boolean)
+          const expanded = await freeLane.expand(parsed, { maxAttempts: config.policy.max_fallback_attempts })
+          const keys = expanded.targets.filter((t) => !t.free).map((t) => `${t.provider}/${t.model}`)
           const out = sessions.advance(sessionID, chainName, keys, { dedupeKey })
           return sendJson(res, 200, { model: out.model, chain: chainName, index: out.index })
         }
@@ -368,11 +404,14 @@ export async function startGate({
         problems = [...(next.problems ?? [])]
         modelsCache.data = null
         logger?.debug?.(`[gate] 配置热更：${next.from}`)
+        freeLane.warm()
       } else {
         logger?.debug?.(`[gate] 配置读不动，保留上一份：${next.error ?? '?'}`)
       }
     },
   })
+  // 免费车道后台预热（不阻塞启动；失败只影响免费候选，请求照常降级到付费）
+  freeLane.warm()
 
   const disposeFns = [() => watch.stop(), () => ledger.flush(), () => new Promise((r) => server.close(() => r()))]
   let sweep = null
@@ -399,6 +438,17 @@ export async function startGate({
       agents: { ...config.agents },
       chain_for_model: { ...config.chain_for_model },
       default_chain: config.default_chain ?? null,
+      free: {
+        enabled: config.free.enabled,
+        max: config.free.max,
+        providers: [...config.free.providers],
+        refresh_seconds: config.free.refresh_seconds,
+        failure_threshold: config.free.failure_threshold,
+        failure_cooldown_seconds: config.free.failure_cooldown_seconds,
+        prefer: [...config.free.prefer],
+        deny: [...config.free.deny],
+        static: { ...config.free.static },
+      },
       ledger: ledger.path,
       problems,
       sessions: sessions.snapshot(),

package/src/gate/lanes.js

@@ -13,15 +13,18 @@
 // 冷却跳过、上限）。**第一个尝试永远保留**：哪怕全在冷却，请求也得有人接。
 import { LANES } from './config.js'
 
-/** `"provider/model"`：只在**第一个** `/` 切分（模型名本身可以带斜杠，如 9router 的 `oc/xxx`）。 */
+/** `"provider/model"`：只在**第一个** `/` 切分（模型名本身可以带斜杠，如 9router 的 `oc/xxx`）。
+ *  `@free` 是链里的**免费车道占位符**（请求时由 free.js 展开成真实候选；不是 provider）。
+ *  `parseTarget('@free')` → `{ free: true }`。 */
 export function parseTarget(spec) {
   const s = String(spec ?? '').trim()
+  if (s === '@free') return { free: true }
   const i = s.indexOf('/')
   if (i <= 0 || i === s.length - 1) return null
   return { provider: s.slice(0, i), model: s.slice(i + 1) }
 }
 
-export const targetKey = (t) => `${t.provider}/${t.model}`
+export const targetKey = (t) => (t?.free ? '@free' : `${t.provider}/${t.model}`)
 
 /** 尝试的键（注意：attempt.provider 是**完整的 provider 对象**，要取 .id）。 */
 export const attemptKey = (attempt) => `${attempt.provider.id}/${attempt.model}`
@@ -86,6 +89,10 @@ export function planAttempts(route, { config, sessions, sessionID = null, keyPic
   const seen = new Set()
   const staticTargets = []
   for (const t of route.targets) {
+    if (t?.free) {
+      skipped.push({ target: '@free', why: 'unexpanded' })
+      continue
+    }
     const key = targetKey(t)
     if (seen.has(key)) {
       skipped.push({ target: key, why: 'no-op' })
@@ -102,10 +109,12 @@ export function planAttempts(route, { config, sessions, sessionID = null, keyPic
       skipped.push({ target: key, why: 'no-key' })
       continue
     }
-    staticTargets.push({ provider, model: t.model, key: resolved.name, authorization: resolved.key === null ? null : `Bearer ${resolved.key}` })
+    staticTargets.push({ provider, model: t.model, auto: t.auto === true, key: resolved.name, authorization: resolved.key === null ? null : `Bearer ${resolved.key}` })
   }
   const keys = staticTargets.map((t) => `${t.provider.id}/${t.model}`)
-  const start = config.chains[route.chain] && route.kind === 'chain' ? sessions.startIndex(sid, chainName, keys) : 0
+  // `@free` 展开出来的候选是**逐请求动态**的（列表会变），所以不能用按索引的粘性指针：
+  // 动态链从 0 起，靠按 ref 的冷却（会话 + 免费车道全局）跳过刚失败过的项。
+  const start = config.chains[route.chain] && route.kind === 'chain' && !route.dynamicFree ? sessions.startIndex(sid, chainName, keys) : 0
   let ordered = staticTargets.slice(start)
   const notCooling = ordered.filter((t) => !sessions.isCooling(sid, chainName, `${t.provider.id}/${t.model}`))
   if (notCooling.length > 0) ordered = notCooling
@@ -175,7 +184,7 @@ export function buildUpstreamRequest({ attempt, inHeaders, bodyText, version = '
 /** 台账一行（**不带任何密钥**：只记 provider id、模型、键的"名字"）。
  *  `req` = 本次调用在本进程内的序号（把同一请求的多次尝试串起来）；`n` = 第几次尝试（1 起）。 */
 export function attemptRow({ ts, chainName, agent, attempt, status, code, latencyMs, retries = 0, detail = null, req = null, n = null }) {
-  return {
+  const row = {
     ts,
     req,
     n,
@@ -191,4 +200,7 @@ export function attemptRow({ ts, chainName, agent, attempt, status, code, latenc
     retries,
     detail,
   }
+  // 只有 `@free` 展开出来的候选才带这个标记（面板/统计据此区分"自动免费"与显式候选）
+  if (attempt.auto === true) row.auto = true
+  return row
 }

package/src/index.js

@@ -36,7 +36,7 @@ import { SUBAGENT_ROSTER, withRoster } from './roster.js'
 import { probeGate, startGate } from './gate/gate.js'
 import { defaultFallbackConfigPath } from './gate/config.js'
 import { REEVE_TIERS, BUILTINS_TO_HIDE, mergeTierModels, pickDefaultAgent, readEndpoint, resolveGateEndpoint } from './models.js'
-import { STATS_DEFAULTS, aggregateGateRows, aggregateLedger, buildStats, fetchGateModels, mergeModelCandidates, readLedgerTail } from './stats.js'
+import { STATS_DEFAULTS, aggregateGateRows, aggregateLedger, buildStats, fetchGateFree, fetchGateModels, mergeModelCandidates, readLedgerTail } from './stats.js'
 import { loadAgents, loadSkills } from './register.js'
 import { ensureProviderBlock, reeveProviderBlock } from './config-write.js'
 
@@ -80,6 +80,8 @@ export default {
     let statsState = null
     /** 模型候选（面板的链编辑选择器用）。必须在快照块之前声明。 */
     let modelsState = null
+    // 免费车道运行态（/gate/free）：面板的"当前展开 / 冷却 / 发现源"读它
+    let freeState = null
     /** 从插件包注册进去的 agent / skill 名单（进快照，便于上机核对"没往配置目录拷文件"）。 */
     let registeredAgents = []
     let registeredSkills = []
@@ -130,6 +132,7 @@ export default {
           agents: agentTable,
           roster,
           models: modelsState,
+          free: freeState,
           registered: { agents: registeredAgents, skills: registeredSkills },
           endpoint: endpointState,
           stats: statsState,
@@ -254,6 +257,7 @@ export default {
           },
         })
         gateState = gateHandle.snapshot()
+        freeState = await fetchGateFree({ port: gateHandle.port, host: gateHandle.host })
         // 顺手把模型候选也刷一遍（半小时一次；链编辑器的选择器用它）
         if (nowMs - lastModelsAt >= modelsIntervalMs) {
           const discovered = await fetchGateModels({ port: gateHandle.port, host: gateHandle.host })

package/src/snapshot.js

@@ -92,7 +92,7 @@ export class SnapshotWriter {
  */
 export function buildSnapshot(
   records,
-  { now = Date.now(), version = null, agents = null, roster = null, registered = null, endpoint = null, models = null, stats = null, gate = null } = {},
+  { now = Date.now(), version = null, agents = null, roster = null, registered = null, endpoint = null, models = null, free = null, stats = null, gate = null } = {},
 ) {
   const tasks = records
     .map((r) => ({
@@ -125,6 +125,7 @@ export function buildSnapshot(
     roster,
     gate,
     models,
+    free,
     registered,
     endpoint,
     stats,

package/src/stats.js

@@ -299,6 +299,21 @@ export async function readLedgerTail({ path, limit = STATS_DEFAULTS.limit, tailB
   }
 }
 
+/**
+ * 免费车道运行态（`/gate/free`）：发现源状态、当前展开、冷却。
+ * 读不到不算错——面板会显示"未就绪"，请求侧照常降级到付费。
+ */
+export async function fetchGateFree({ port, host = '127.0.0.1', fetchImpl = fetch, timeoutMs = STATS_DEFAULTS.timeoutMs } = {}) {
+  try {
+    const res = await fetchImpl(`http://${host}:${port}/gate/free`, { signal: AbortSignal.timeout(timeoutMs) })
+    if (res.status !== 200) return { error: `HTTP ${res.status}` }
+    const doc = await res.json()
+    return doc && typeof doc === 'object' ? { ...doc, error: null } : { error: '空响应' }
+  } catch (err) {
+    return { error: String(err?.message ?? err).slice(0, 140) }
+  }
+}
+
 /** GATE 自己的模型目录（`provider/model` ∪ 链名）—— 面板选择器的候选来源之一。 */
 export async function fetchGateModels({ port, host = '127.0.0.1', fetchImpl = fetch, timeoutMs = STATS_DEFAULTS.timeoutMs } = {}) {
   try {