opencode-lobster-auth 0.0.0-stage → 0.1.0

package/lib/auth-import.mjs

@@ -0,0 +1,100 @@
+// 从本机 LobsterAI 桌面端的 sqlite 里读出登录信息。
+// 表：CREATE TABLE kv (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at INTEGER NOT NULL)
+//   auth_tokens -> {"accessToken":"…","refreshToken":"…"}
+//   auth_user   -> {"yid","id","nickname"}
+//
+// 必须只读：桌面端可能正在运行，插件绝不写入它的库。
+
+import { Database } from "bun:sqlite"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { jwtExp, accountOf } from "./jwt.mjs"
+
+export function dbPath(env = process.env) {
+  const home = env.HOME || env.USERPROFILE || ""
+  if (process.platform === "win32") {
+    const appdata = env.APPDATA || (home ? join(home, "AppData", "Roaming") : "")
+    return join(appdata, "LobsterAI", "lobsterai.sqlite")
+  }
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Application Support", "LobsterAI", "lobsterai.sqlite")
+  }
+  const cfg = env.XDG_CONFIG_HOME || join(home, ".config")
+  return join(cfg, "LobsterAI", "lobsterai.sqlite")
+}
+
+const parse = (s) => {
+  try {
+    const v = JSON.parse(String(s ?? ""))
+    return v && typeof v === "object" ? v : null
+  } catch { return null }
+}
+
+export function readCredentials(path) {
+  if (!path || !existsSync(path)) return null
+  let db
+  try {
+    // 只读打开：绝不改动桌面端的库
+    db = new Database(path, { readonly: true })
+    const rows = db.query("SELECT key, value FROM kv WHERE key IN ('auth_tokens','auth_user')").all()
+    const byKey = Object.fromEntries(rows.map((r) => [r.key, r.value]))
+    const tokens = parse(byKey.auth_tokens)
+    const accessToken = String(tokens?.accessToken ?? "")
+    if (!accessToken) return null
+    const user = parse(byKey.auth_user) ?? {}
+    const claims = accountOf(accessToken)
+    return {
+      accessToken,
+      refreshToken: String(tokens?.refreshToken ?? ""),
+      yid: user.yid ?? claims.yid,
+      id: user.id ?? claims.id,
+      nickname: user.nickname,
+      expires: jwtExp(accessToken),
+    }
+  } catch {
+    return null
+  } finally {
+    try { db?.close() } catch {}
+  }
+}
+
+// 桌面端这条路只借一个身份，**不存 token**：
+//   access/refresh 都留空，expires 为 0，靠 source:"desktop" 标记来源。
+// token 每次用的时候现读（desktopToken），所以桌面端续期后插件自动跟着用新的。
+//
+// 为什么不把 token 抄一份：抄下来的 refreshToken 会是桌面端和插件共用的，
+// 谁先续期谁就把对方踢下线。留空则 magpie 永不续期（expires 为 0），
+// 桌面端的会话不受任何影响。
+export function desktopSignIn(env = process.env) {
+  const path = dbPath(env)
+  const c = readCredentials(path)
+  if (!c) {
+    throw new Error(
+      `没有在本机找到 LobsterAI 的登录信息（${path}）。` +
+      "请先在 LobsterAI 桌面端登录，或改用「浏览器登录」。",
+    )
+  }
+  return {
+    type: "success",
+    refresh: "",
+    access: "",
+    expires: 0,
+    source: "desktop",
+    accountId: c.yid ?? (c.id !== undefined ? String(c.id) : undefined),
+    uid: c.id,
+  }
+}
+
+// 桌面端账号的 token：每次现读，桌面端换了 token 插件立刻跟上。
+// 读不到就是账号不可用（桌面端退出登录、库被删、文件被加密），
+// 报 signIn:"expired" 让 magpie 给账号打上失效标记，提示用户重新登录。
+export function desktopToken(env = process.env) {
+  const c = readCredentials(dbPath(env))
+  if (!c) {
+    throw Object.assign(
+      new Error("LobsterAI 桌面端未登录，或它的登录信息已不可读"),
+      { signIn: "expired" },
+    )
+  }
+  return c.accessToken
+}

package/lib/auth-login.mjs

@@ -0,0 +1,131 @@
+// 浏览器登录，走 LobsterAI 桌面端自己的通道。
+//
+// portal 的 auth 模块允许把授权码回调到任意
+// http://127.0.0.1:<port>/auth/callback（条件是 http + 127.0.0.1 +
+// /auth/callback + 有端口），因此插件可以自带登录，不依赖桌面端。
+// 参数必须追加到登录页的 hash query，不是 URL query；且必须带
+// source=electron，否则 portal 不会带上 redirect_uri。
+
+import { createServer } from "node:http"
+import { randomBytes } from "node:crypto"
+import { API, LOGIN_URL } from "./constants.mjs"
+import { jwtExp, accountOf } from "./jwt.mjs"
+
+const TIMEOUT_MS = 5 * 60 * 1000
+
+export function authorizeUrl(loginUrl, callbackUrl, state) {
+  const base = loginUrl || LOGIN_URL
+  const hashAt = base.indexOf("#")
+  const head = hashAt === -1 ? base : base.slice(0, hashAt)
+  const hash = hashAt === -1 ? "" : base.slice(hashAt + 1)
+  const [route, query = ""] = hash.split("?")
+  const q = new URLSearchParams(query)
+  q.set("source", "electron")
+  q.set("redirect_uri", callbackUrl)
+  q.set("state", state)
+  return `${head}#${route}?${q.toString()}`
+}
+
+// 起一个只监听 127.0.0.1 的临时服务；端口由系统分配（listen 0）。
+// 返回 { port, result(ms), close() }，把「等回调」和「关服务」分开，
+// 这样调用方可以先拿到端口拼 URL，再去等结果。
+function listenOnce() {
+  return new Promise((resolve, reject) => {
+    let deliver = () => {}
+    const got = new Promise((r) => { deliver = r })
+    let timer = null
+    const server = createServer((req, res) => {
+      const u = new URL(req.url, "http://127.0.0.1")
+      if (u.pathname !== "/auth/callback") { res.writeHead(404).end(); return }
+      const code = u.searchParams.get("code")
+      const state = u.searchParams.get("state")
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" })
+      res.end(code
+        ? "<h2>登录成功，可以关闭此页面。</h2>"
+        : "<h2>登录失败：没有拿到授权码。</h2>")
+      deliver({ code, state })
+    })
+    server.on("error", reject)
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address()
+      resolve({
+        port,
+        close() {
+          if (timer) clearTimeout(timer)
+          try { server.close() } catch {}
+        },
+        result(ms) {
+          const late = new Promise((r) => {
+            timer = setTimeout(() => r({ error: new Error("登录超时（5 分钟）") }), ms)
+          })
+          return Promise.race([got, late]).then((v) => {
+            if (v?.error) throw v.error
+            return v
+          })
+        },
+      })
+    })
+  })
+}
+
+async function exchangeCode(code) {
+  const res = await fetch(`${API}/auth/exchange`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ authCode: code, firstKeyfrom: "official", latestKeyfrom: "official" }),
+    signal: AbortSignal.timeout(30_000),
+  })
+  const text = await res.text()
+  let v
+  try { v = JSON.parse(text) } catch { throw new Error(`LobsterAI 的登录响应无法解析：${text.slice(0, 200)}`) }
+  // /api/* 用 {code, message, data} 信封，业务错误也是 HTTP 200
+  if (v?.code !== 0 || !v?.data) {
+    throw new Error(`LobsterAI 拒绝了登录：${v?.message || `code ${v?.code}`}`)
+  }
+  return v.data
+}
+
+// beginSignIn 起回调服务并拼出授权地址，然后把「等回调并换 token」交给
+// finish()。分成两半是因为由 magpie 负责打开 authorize 返回的 url ——
+// 插件自己再开一次就会开两个标签页。
+export async function beginSignIn({ timeoutMs = TIMEOUT_MS } = {}) {
+  const state = randomBytes(24).toString("base64url")
+  const listening = await listenOnce()
+  const callbackUrl = `http://127.0.0.1:${listening.port}/auth/callback`
+  const url = authorizeUrl(LOGIN_URL, callbackUrl, state)
+
+  const finish = async () => {
+    try {
+      const got = await listening.result(timeoutMs)
+      if (got.state !== state) throw new Error("登录回调的 state 不匹配，已忽略")
+      const data = await exchangeCode(got.code)
+      const access = String(data.accessToken ?? "")
+      if (!access) throw new Error("LobsterAI 没有返回 accessToken")
+      const who = accountOf(access)
+      return {
+        type: "success",
+        refresh: String(data.refreshToken ?? ""),
+        access,
+        expires: jwtExp(access) || Date.now() + 30 * 24 * 3600 * 1000,
+        accountId: who.yid ?? (who.id !== undefined ? String(who.id) : undefined),
+      }
+    } finally {
+      listening.close()
+    }
+  }
+
+  return { url, finish, close: () => listening.close() }
+}
+
+// signIn 是 beginSignIn 的「自己开浏览器」封装：给命令行与测试用。
+// open 可注入，因此测试里不必真的弹浏览器。
+export async function signIn({ open, timeoutMs = TIMEOUT_MS } = {}) {
+  const pending = await beginSignIn({ timeoutMs })
+  try {
+    await open(pending.url)
+    return await pending.finish()
+  } catch (e) {
+    pending.close()
+    throw e
+  }
+}

package/lib/constants.mjs

@@ -0,0 +1,41 @@
+// LobsterAI（有道龙虾）的固定事实：地址、客户端标识、未登录时的兜底模型表。
+// 兜底表只在没登录时显示；登录后由 /api/models/available 的实时结果替换。
+
+export const PROVIDER = "lobster"
+export const NAME = "LobsterAI"
+export const BASE = "https://lobsterai-server.youdao.com"
+export const API = BASE + "/api"
+export const CHAT_BASE = BASE + "/api/proxy/v1"
+export const NPM = "@ai-sdk/openai-compatible"
+
+export const LOGIN_URL = "https://lobsterai.youdao.com/portal#/login"
+export const ICON = "https://lobsterai.youdao.com/portal/lobsterai-logo.png"
+
+// 桌面端 2026.9.23 发的标识头；上游不强制，但可能影响特性开关
+export const CLIENT_VERSION = "2026.9.23"
+export const CAPABILITIES = "kimi-k3-agentic-v1,thinking-level-control-v1"
+
+// 接口不提供输出上限，取一个保守值（见设计文档 §8）
+export const DEFAULT_OUTPUT = 32000
+export const DEFAULT_CONTEXT = 1000000
+
+export function configModel({ name, context, output, reasoning, image }) {
+  const input = ["text"]
+  if (image) input.push("image")
+  return {
+    name,
+    limit: { context: context || DEFAULT_CONTEXT, output: output || DEFAULT_OUTPUT },
+    reasoning: !!reasoning,
+    tool_call: true,
+    modalities: { input, output: ["text"] },
+  }
+}
+
+// 兜底：未登录时让用户看到 provider 存在。字段来自实测的模型目录。
+export const FALLBACK_MODELS = {
+  "deepseek-v4-pro": configModel({ name: "DeepSeek V4 Pro", reasoning: true }),
+  "deepseek-flash": configModel({ name: "DeepSeek Flash", reasoning: true }),
+  "glm-5.3": configModel({ name: "GLM-5.3", reasoning: true }),
+  "kimi-k3": configModel({ name: "Kimi K3", reasoning: true, image: true }),
+  "qwen3.8-max": configModel({ name: "Qwen3.8 Max", reasoning: true }),
+}

package/lib/jwt.mjs

@@ -0,0 +1,34 @@
+// LobsterAI 的 accessToken 是标准 JWT（未加密，仅签名）。
+// 插件只读它的载荷，不校验签名——校验由上游负责。
+
+function decode(part) {
+  try {
+    const s = Buffer.from(String(part).replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8")
+    const v = JSON.parse(s)
+    return v && typeof v === "object" ? v : null
+  } catch {
+    return null
+  }
+}
+
+export function jwtPayload(token) {
+  const parts = String(token ?? "").split(".")
+  if (parts.length < 2) return null
+  return decode(parts[1])
+}
+
+// exp 以秒计；返回毫秒，读不到就是 0（magpie 把 0 当作「不续期」）
+export function jwtExp(token) {
+  const p = jwtPayload(token)
+  const exp = Number(p?.exp)
+  return Number.isFinite(exp) && exp > 0 ? exp * 1000 : 0
+}
+
+export function accountOf(token) {
+  const p = jwtPayload(token)
+  if (!p) return {}
+  const out = {}
+  if (p.yid) out.yid = p.yid
+  if (p.sub !== undefined) out.id = p.sub
+  return out
+}

package/lib/models.mjs

@@ -0,0 +1,77 @@
+// /api/models/available 的条目 → magpie 的运行时模型。
+// 运行时模型用嵌套的 capabilities；config 钩子用扁平字段（见 constants.configModel）。
+
+import { NPM, DEFAULT_OUTPUT, DEFAULT_CONTEXT, configModel } from "./constants.mjs"
+import { variantsOf } from "./thinking.mjs"
+
+export function runtimeModel(entry, base = {}) {
+  const id = String(entry.modelId ?? "")
+  const image = !!entry.supportsImage
+  const profile = entry.thinkingConfig
+  const hasThinking = !!entry.supportsThinking && Array.isArray(profile?.options) && profile.options.length > 0
+
+  return {
+    ...base,
+    id,
+    providerID: base.providerID,
+    name: String(entry.modelName ?? id),
+    api: { id, url: "", npm: NPM },
+    status: "active",
+    headers: {},
+    options: {},
+    cost: { input: 0, output: 0, cache: { read: 0, write: 0 } },
+    limit: { context: Number(entry.contextWindow) || DEFAULT_CONTEXT, output: DEFAULT_OUTPUT },
+    capabilities: {
+      temperature: true,
+      reasoning: hasThinking,
+      attachment: image,
+      toolcall: true,
+      input: { text: true, image, audio: false, video: false, pdf: false },
+      output: { text: true, image: false, audio: false, video: false, pdf: false },
+      interleaved: false,
+    },
+    release_date: "",
+    variants: hasThinking ? variantsOf(profile) : {},
+    // magpie 自己的字段：一次请求消耗的点数倍率
+    rate: Number(entry.costMultiplier) || 0,
+  }
+}
+
+export function modelsFromCatalog(list, provider) {
+  const out = {}
+  for (const entry of Array.isArray(list) ? list : []) {
+    if (!entry || entry.accessible === false) continue
+    const id = String(entry.modelId ?? "")
+    if (!id) continue
+    const was = provider?.models?.[id] ?? {}
+    out[id] = runtimeModel(entry, { ...was, providerID: provider?.id })
+  }
+  return out
+}
+
+export function profileOfFrom(list) {
+  const out = {}
+  for (const entry of Array.isArray(list) ? list : []) {
+    const id = String(entry?.modelId ?? "")
+    if (id && entry.thinkingConfig) out[id] = entry.thinkingConfig
+  }
+  return out
+}
+
+// 未登录时 config 钩子用的扁平形状
+export function configModels(list) {
+  const out = {}
+  for (const entry of Array.isArray(list) ? list : []) {
+    if (!entry || entry.accessible === false) continue
+    const id = String(entry.modelId ?? "")
+    if (!id) continue
+    out[id] = configModel({
+      name: String(entry.modelName ?? id),
+      context: Number(entry.contextWindow) || DEFAULT_CONTEXT,
+      output: DEFAULT_OUTPUT,
+      reasoning: !!entry.supportsThinking,
+      image: !!entry.supportsImage,
+    })
+  }
+  return out
+}

package/lib/proxy.mjs

@@ -0,0 +1,106 @@
+// 请求管线。上游有两个必须处理的行为：
+//   1. 永远以 SSE 作答，即使请求写了 stream:false；
+//   2. 把错误塞进 SSE 的 event:error 且状态码仍是 200，原样透传会让 magpie
+//      永不故障切换。
+// 另外思考档位要翻译成私有字段（见 lib/thinking.mjs）。
+
+import { sse, first } from "./sse.mjs"
+import { respond } from "./assemble.mjs"
+import { applyThinking, applyKimiK3, isKimiK3 } from "./thinking.mjs"
+import { CLIENT_VERSION, CAPABILITIES } from "./constants.mjs"
+
+const LIMIT_WORDS = /限流|频率|过快|过于频繁|rate ?limit|too many/i
+
+export function errorOf(data) {
+  let v
+  try { v = JSON.parse(data) } catch { return { code: 0, message: "" } }
+  const e = v?.error && typeof v.error === "object" ? v.error : v
+  const code = Number(e?.code ?? v?.code ?? 0) || 0
+  const message = String(e?.message ?? v?.message ?? v?.msg ?? "")
+  return { code, message }
+}
+
+export function statusFor(code, message) {
+  if (code === 40100) return 401
+  if (code === 40300) return 403
+  if (code === 42900) return 429
+  if (LIMIT_WORDS.test(String(message ?? ""))) return 429
+  return 400
+}
+
+// 401 带 expired 让 magpie 给账号打上失效标记；其余状态不带这个头
+function errorResponse(status, code, message) {
+  const headers = { "content-type": "application/json" }
+  if (status === 401) headers["X-Magpie-Sign-In"] = "expired"
+  return new Response(
+    JSON.stringify({ error: { message, type: status === 429 ? "rate_limit_error" : "api_error", code: code || null } }),
+    { status, headers },
+  )
+}
+
+// tokenOf 由调用方注入：桌面端导入的账号自己不存 token，得每次现读，
+// 因此这里不能写死「oauth 读 access、api 读 key」。
+export function makeFetch({ getAuth, tokenOf, profileOf, call }) {
+  return async function lobsterFetch(input, init) {
+    const auth = await getAuth()
+    if (auth?.type !== "api" && auth?.type !== "oauth") {
+      return errorResponse(401, 40100, "LobsterAI: 尚未登录")
+    }
+    let token = ""
+    try {
+      token = await tokenOf(auth)
+    } catch (e) {
+      // 桌面端退出登录 / 库读不到：带上失效标记，让 magpie 提示重新登录
+      return errorResponse(401, 40100, e?.message ?? "LobsterAI: 登录信息不可用")
+    }
+    if (!token) return errorResponse(401, 40100, "LobsterAI: 登录信息不完整")
+
+    let req
+    try { req = JSON.parse(typeof init?.body === "string" ? init.body : "{}") } catch { req = {} }
+
+    // 请求体改写
+    const profile = profileOf(req.model)
+    const k3 = isKimiK3(req.model)
+    if (k3) applyKimiK3(req)
+    const translated = applyThinking(req, profile)
+    // 翻译成功才把 magpie 下发的档位名删掉：它下发的是它阶梯里的名字
+    // （最低档叫 none），未必是上游的叫法。没翻译成功（模型没有档位表）
+    // 时保留原字段 —— 上游自己就认 reasoning_effort，删掉等于白扔一个控制。
+    // K3 例外：reasoning_effort 由服务端固定为 max，必须留着。
+    if (!k3 && translated) {
+      delete req.reasoning_effort
+      delete req.reasoningEffort
+    }
+
+    const headers = new Headers(init?.headers)
+    headers.set("authorization", `Bearer ${token}`)
+    headers.set("content-type", "application/json")
+    headers.set("X-LobsterAI-Client-Version", CLIENT_VERSION)
+    headers.set("X-LobsterAI-Client-Capabilities", CAPABILITIES)
+    headers.delete("content-length")
+
+    const res = await call(input, { ...init, method: init?.method ?? "POST", headers, body: JSON.stringify(req) })
+
+    // 上游的鉴权失败是真 401，原样透传但要补上失效标记
+    if (res.status === 401) {
+      const headers = new Headers(res.headers)
+      headers.set("X-Magpie-Sign-In", "expired")
+      return new Response(res.body, { status: 401, statusText: res.statusText, headers })
+    }
+    if (!res.ok) return res
+    const ctype = res.headers.get("content-type") ?? ""
+    // 上游理论上永远给 SSE；真给了 JSON 就直通，不做重组
+    if (!ctype.includes("event-stream")) return res
+
+    const { head, rest } = await first(sse(res.body))
+    if (head && head.event === "error") {
+      const { code, message } = errorOf(head.data)
+      return errorResponse(statusFor(code, message), code, message || "LobsterAI 返回了一个错误")
+    }
+    const out = await respond(req, rest)
+    // 成功也要带 kept：插件不自己续期，用的就是存下来的 token。
+    // magpie 靠这个头把账号上的失效标记清掉。
+    out.headers.set("X-Magpie-Sign-In", "kept")
+    return out
+  }
+}

package/lib/sse.mjs

@@ -0,0 +1,67 @@
+// LobsterAI 的推理端点永远以 SSE 作答，即使请求写了 stream:false。
+// 这里把字节流切成 {event, data} 记录，两种情形都由上层决定怎么用。
+
+const decoder = new TextDecoder()
+
+export async function* sse(body) {
+  let buf = ""
+  let event = ""
+  let data = []
+
+  // 一条空行结束一个事件；没有 data 的事件（只有注释）不产出
+  const flush = () => {
+    if (data.length === 0) { event = ""; return null }
+    const rec = { event, data: data.join("\n") }
+    event = ""
+    data = []
+    return rec
+  }
+
+  const feed = (raw) => {
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw
+    if (line === "") return flush()
+    if (line.startsWith(":")) return null // 注释 / keep-alive
+    const i = line.indexOf(":")
+    const field = i === -1 ? line : line.slice(0, i)
+    let value = i === -1 ? "" : line.slice(i + 1)
+    if (value.startsWith(" ")) value = value.slice(1)
+    if (field === "event") event = value
+    else if (field === "data") data.push(value)
+    return null
+  }
+
+  for await (const chunk of body) {
+    buf += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true })
+    let nl
+    while ((nl = buf.indexOf("\n")) !== -1) {
+      const rec = feed(buf.slice(0, nl))
+      buf = buf.slice(nl + 1)
+      if (rec) yield rec
+    }
+  }
+  buf += decoder.decode()
+  if (buf !== "") {
+    const rec = feed(buf)
+    if (rec) yield rec
+  }
+  const last = flush()
+  if (last) yield last
+}
+
+async function* empty() {}
+
+// first 读一条但把它放回去：上游把错误藏在流里，必须先看一眼首条
+export async function first(it) {
+  const n = await it.next()
+  if (n.done) return { head: null, rest: empty() }
+  return { head: n.value, rest: chain([n.value], it) }
+}
+
+export async function* chain(held, it) {
+  yield* held
+  for (;;) {
+    const n = await it.next()
+    if (n.done) return
+    yield n.value
+  }
+}

package/lib/thinking.mjs

@@ -0,0 +1,98 @@
+// 上游的思考档位走私有字段，不是 reasoning_effort：
+//   {"lobsterai_options":{"version":1,"thinking":{"level":"off"|"high"|"max"}}}
+// 协议来自 LobsterAI 自带的 lobsterai-model-compat 插件
+// （resources/cfmind/third-party-extensions/lobsterai-model-compat）。
+//
+// 实测（deepseek-flash）：level=off 时 reasoning_content 精确为 0 字节，
+// 不带该字段约 300~900 字节 —— 即 off 会真正关掉思考。
+//
+// 档位怎么从用户到达这里：magpie 不用 variants 的值对象，而是维护一条自己的
+// 档位阶梯（none/minimal/low/medium/high/xhigh/max），把入参 reasoning_effort
+// 映射到「模型声明过的那个档位名」，再以 reasoning_effort 下发。阶梯外的名字
+// （off/disabled/enabled/adaptive/空串）会被直接丢掉 —— 所以声明里用 "off"
+// 当档位名，那一档就永远够不着（实测：发 off 被丢弃，发 none 才送得到）。
+// 因此对外一律用 magpie 的 "none" 表示最低档，写给上游时再换回 LobsterAI 的 "off"。
+
+export const OPTIONS_FIELD = "lobsterai_options"
+export const OPTIONS_VERSION = 1
+export const MARKER = "lobsterai_thinking"
+
+const LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
+const isLevel = (s) => LEVELS.includes(s)
+
+// 上游叫 off，magpie 的阶梯里只有 none
+const WIRE_TO_MAGPIE = { off: "none" }
+const MAGPIE_TO_WIRE = { none: "off" }
+const nameForMagpie = (level) => WIRE_TO_MAGPIE[level] ?? level
+const levelForWire = (name) => MAGPIE_TO_WIRE[name] ?? name
+
+// variants 只用到「键名」，值对象不会到达插件（magpie 的 host 只上报
+// Object.keys）。键名必须是 magpie 阶梯内的名字，否则那一档选不中。
+export function variantsOf(profile) {
+  const opts = profile?.options ?? []
+  return Object.fromEntries(opts.map((o) => [nameForMagpie(o.level), { [MARKER]: o.level }]))
+}
+
+// 档位可能以多种形式到达：插件自己的标记、reasoning_effort、reasoningEffort、
+// thinking.level。按 level 或 openclawLevel 查表，未命中用 defaultLevel。
+export function levelOf(req, profile) {
+  const opts = profile?.options ?? []
+  const wanted = [
+    req?.[MARKER],
+    req?.reasoning_effort,
+    req?.reasoningEffort,
+    req?.thinking?.level,
+  ].find((v) => typeof v === "string" && v !== "")
+
+  if (wanted) {
+    // magpie 下发的是它阶梯里的名字（最低档叫 none），先换回上游的叫法
+    const level = levelForWire(wanted)
+    if (isLevel(level) && opts.some((o) => o.level === level)) return level
+    const byOpenclaw =
+      opts.find((o) => o.openclawLevel === wanted) ?? opts.find((o) => o.openclawLevel === level)
+    if (byOpenclaw) return byOpenclaw.level
+    if (isLevel(level)) return level
+  }
+  if (profile?.defaultLevel && isLevel(profile.defaultLevel)) return profile.defaultLevel
+  return "off"
+}
+
+// 上游只在模型自带 thinkingConfig 时才接受 lobsterai_options。对没有档位表的
+// 模型带上该字段是硬错误，实测 code 4000：
+//   "lobsterai_options: model does not have a valid thinkingConfig"
+// 29 个模型里有 21 个 thinkingConfig 是 null，因此必须按「有没有档位表」来
+// 决定写不写 —— 桌面端的 lobsterai-model-compat 插件也是这么做的
+// （index.ts 用 thinkingProfile.requestOptionsVersion 当闸门）。
+// 返回是否真的写了：调用方据此决定要不要把 magpie 下发的 reasoning_effort
+// 删掉（没翻译成功时留着它，上游自己认这个字段，删掉等于白扔一个控制）。
+export function applyThinking(req, profile) {
+  // 先读再删：levelOf 的第一优先级就是插件自己的标记。
+  const level = levelOf(req, profile)
+  delete req[MARKER]
+  const opts = profile?.options
+  if (!Array.isArray(opts) || opts.length === 0) return false
+  req[OPTIONS_FIELD] = { version: OPTIONS_VERSION, thinking: { level } }
+  return true
+}
+
+// Kimi K3 的额外契约（LobsterAI 的 kimiK3StreamWrapper.ts）：
+// 采样参数由服务端固定，必须删掉；reasoning_effort 固定为 max；
+// 历史里缺 reasoning_content 的 assistant tool_call 消息会被拒答。
+const K3_FIXED = ["temperature", "top_p", "n", "presence_penalty", "frequency_penalty"]
+
+export function isKimiK3(modelId) {
+  return /^kimi-k3(?:$|[-.])/i.test(String(modelId ?? ""))
+}
+
+export function applyKimiK3(req) {
+  delete req.thinking
+  delete req.reasoningEffort
+  for (const f of K3_FIXED) delete req[f]
+  req.reasoning_effort = "max"
+  if (!Array.isArray(req.messages)) return
+  for (const m of req.messages) {
+    if (m?.role !== "assistant") continue
+    if (!Array.isArray(m.tool_calls) || m.tool_calls.length === 0) continue
+    if (!("reasoning_content" in m)) m.reasoning_content = ""
+  }
+}