ModelRouter/docs/adapters.md

适配器协议

本文档由 README 拆分而来：Lua 适配器协议与内置适配器清单。 编写适配器的完整参考见 lua-adapters.md。 返回 README。

Lua 适配器协议

完整 API 见 Lua 适配器 API 文档（English）。

每个适配器是一个返回 table 的 Lua 脚本（internal/lua/adapters/<name>.lua）， 加载时可被 adapter_dir 下的同名脚本覆盖——改 Lua 脚本无需重编译， 重启即生效；通过 WebUI 上传的适配器与在线编辑的源配置则即时生效。

return {
  name = "mysrc",
  version = "1.0.0",
  endpoint = "/chat/completions",        -- 上游路径（可被 source.endpoint 覆盖）
  headers = { ["X-Static"] = "v" },      -- 静态默认请求头（build_headers 缺省时使用）

  -- 请求转换：把 OpenAI 格式 req 转成上游原生格式，返回字符串
  transform_request = function(raw_json) ... end,

  -- 响应转换：把上游原生响应转成统一格式字符串
  --   { content, reasoning_content, finish_reason, token_usage{...}, tool_calls[{...}] }
  transform_response = function(raw_json) ... end,

  -- 流式分块转换：把上游 SSE data 转成 { content, done, ... }，返回 "" 则跳过
  transform_stream_chunk = function(raw_chunk) ... end,

  -- [可选] 动态请求头/签名钩子
  -- meta = { url, method, body, api_key, timestamp, source={ name, meta={...} } }
  build_headers = function(meta) return { ["X-App-Sign"] = sign } end,

  -- [可选] 出向序列化（契约 v2）：上游不是 OpenAI 协议时接管写给客户端的字节。
  -- 不声明则沿用内核的 OpenAI 兜底；声明即完全取代，内核不再混合字段。
  serialize_response = function(result) return body_str end,
  serialize_open_preamble = function(result) return bytes end,
  serialize_chunk = function(delta) return bytes end,
  serialize_close = function(result) return bytes end,
}

内置信号辅助：hmac_sha256_hex(key, data)、sha256_hex(data)、base64_encode(s)、 tohex(s)、json.encode/decode、log(level, msg)。

内置适配器

openai deepseek anthropic gemini github groq mistral ollama kimicode qwen38 sensenova trae。

anthropic/gemini/ollama 适配器内置多模态转换（image_url → 各自上游格式）； 推理开关由中立的 thinking 字段表达，deepseek 适配器把它映射为 thinking.type = "disabled"。

kimicode 是展示 build_headers 的样例：云端校验调用方 app，需要按 meta.app_secret 对时间戳+URL+请求体哈希做 HMAC 签名并附 X-App-Sign 等头。 配好 sources[].meta.{app_id, app_secret, app_agent} 即可。