# 实现与完整特性

> 本文档由 README 拆分而来：架构来源与完整特性清单（README 只保留摘要）。
> 返回 [README](../README.md)。

## 实现

统一 OpenAI 兼容网关：把多个上游 LLM 源（DeepSeek、Qijiar、OpenAI、Anthropic、Gemini、
Groq、Mistral、Ollama、KimiCode…）通过 **Lua 适配器** 做协议转换，对内网暴露
一个标准 `OpenAI Chat Completions` 接口（`/v1/chat/completions` + `/v1/models`），
支持单次结算、SSE 流式、**AUTO 模型路由**与**多模态**透传。

从 [HomeAgent](https://gitcode.com/JianFeeeee/HomeAgent) 的多源 LLM 适配层
（`internal/agent/api/provider.go` + `internal/lua/adapters/*`）抽离而来并独立演进。

## 特性

- **多源**：一个进程内配置任意多个上游源，按请求的 `model` 自动路由。
- **AUTO 模式**：`default_model: AUTO` 时按优先级页保存的 AUTO 链档位逐档调度并发请求。
- **统一输出**：所有源对外都是 OpenAI 格式（含 `reasoning_content`、`tool_calls`、`usage`）。
- **生图**：`POST /v1/images/generations`，`kind: image` 的模型独立路由。
- **多模态**：`content` 数组（`image_url` 等）在多源间无损透传，Anthropic/Gemini/Ollama 自动转换。
- **LuaJIT VM**：基于 golua 绑定的 LuaJIT，每个适配器独立 VM + worker 池，安全并发。
  池是 **弹性** 的：`Σ max_concurrent` 只是上限而非预分配，状态按需创建、空闲时自动回收，
  因此空载网关几乎不持有 Lua 状态（启动 0 个）。
  - 扩容步长由适配器最大并发决定：`clamp(ceil(max/8), 1, 8)`，且仅在**真实并发争用**
    （所有现有状态均已占用）时批量预热，顺序流量始终只用 1 个状态。
  - 缩容步长由当前连接数决定：`clamp(ceil(冗余/(1+占用)), 1, 冗余)`——无连接时一轮收到
    常驻下限，忙时每轮只释放 1 个，保护热路径。WebUI「适配器」页展示实时池指标。
- **thinking 预算**：请求里的推理开关/预算归一为中立的 `thinking:{enabled,budget_tokens}`，
  适配器映射到各自协议（Anthropic `thinking.budget_tokens`、Gemini `thinkingConfig`、
  DeepSeek `thinking.type="disabled"`）。
- **Lua 适配协议**：每个源挂一个 `.lua` 适配器，完成 `transform_request` /
  `transform_response` / `transform_stream_chunk` 双向转换，协议差异全在 Lua 层。
- **签名 / 请求头钩子**：适配器可定义 `build_headers(meta)`，在 Go 发 HTTP 前
  动态注入/签名请求头——用于云端 API 校验调用方 app（如 KimiCode 只放行特定
  agent）。提供 `hmac_sha256_hex` / `sha256_hex` / `base64_encode` 等签名辅助。
- **WebUI**：内置管理界面，可在线查看/新增/编辑上游源与模型、配置 AUTO 优先级链、
  管理密钥模型范围，写入运行时文件持久化。
- **密钥加密存储**：运行时文件中的上游 `api_key`、自定义请求头值、网关 key 均以
  AES-256-GCM 加密落盘（`master.key` 独立 0600，或 `MODELROUTER_MASTER_KEY`）。
- **实时源探测**：状态页探测各源可达性（`GET {base}/models`，失败回退最小请求），
  不污染正常调度的退避状态，错误信息在 UI 可悬停查看。
- **鉴权**：网关自身用 `gateway_keys` 校验客户端 Bearer key；与上游各自的 key 相互独立。
- **流式**：SSE `chat.completion.chunk`，含角色首包与 `[DONE]` 收尾。
- **全链路审计**：HTTP 访问日志、登录/配置变更审计、请求记录 CSV 导出、密钥用量统计 CSV 导出
- **AES-256-GCM 加密存储**：运行时文件敏感字段加密落盘，master.key 0600 权限，支持环境变量注入主密钥