拆解Lynkr源码:一个请求从格式转换到分层路由的完整旅程
拆解Lynkr源码:一个请求从格式转换到分层路由的完整旅程
Lynkr 是一个开源的 LLM 网关(LLM Gateway),它拦截 Claude Code、Cursor 等 AI 编程工具的请求,通过格式转换、语义缓存和分层路由,把简单问题派给便宜甚至免费的本地模型,把复杂任务才交给顶级模型——官方数据显示 JSON 工具结果可压缩 84% token,整体可节省 50%~80% 成本。本文将带你完整拆解一个请求在 Lynkr 内部的旅程:从进入网关的那一刻,到最终由哪个模型应答。
一、先认识 Lynkr:它到底解决了什么问题
想象你在用 Claude Code 写代码:每一轮对话都会把完整的会话历史、十几个工具定义、几 KB 的系统提示词一起发给模型。哪怕你只是回了一句 "yes",上游也在按整页内容计费。
Lynkr 的思路是当中间人:
- 客户端把 Lynkr 当作 OpenAI / Anthropic 的 API 地址
- Lynkr 判断这个请求"值多少钱",再路由到合适档位的模型
- 顺手做缓存命中、历史压缩,能省多少算多少
核心数据一览(来自仓库自带的 benchmark):
| 能力 | 效果 |
|---|---|
| JSON 工具结果压缩 | 减少 84% token |
| 工具密集型请求 | 减少 53% token |
| 语义缓存命中 | 延迟 <300ms,0 token 计费 |
| 支持的模型供应商 | 14+ 家 |
| 客户端代码改动 | 0 处 |
想先跑起来的话,官方文档给出了两条路:
- 交互向导:
lynkr init(docs/init.md) - 快速上手与 Wrap 模式说明见 docs/wrap-guide.md
下面我们从源码层面看一个请求是怎么被"拆解"处理的。
二、第一站:服务入口与中间件流水线
请求进入 Lynkr 的第一站是 Express 服务 src/server.js。这里按顺序挂载了一整条中间件流水线:
- 负载shed与请求日志——给每个请求分配 request ID
- 会话中间件——从
x-session-id等头部恢复会话身份 - 循环守卫(loop guard)——防止 Agent 失控死循环烧钱
- 预算与限流——按 token / 请求数设硬上限
- 租户策略——多租户部署时按租户走不同路由规则
主路由定义在 src/api/router.js,核心端点是 POST /v1/messages(Anthropic 协议)和 /v1/chat/completions(OpenAI 协议)。
格式转换:两种 API 协议的同传翻译
这是整个旅程里最基础的一环。OpenAI 协议和 Anthropic 协议的消息结构并不相同——比如 OpenAI 把系统提示词放在 messages 数组里,Anthropic 则要求独立的 system 字段;OpenAI 的 image_url 块在 Anthropic 里要变成 image 块。
Lynkr 在 src/clients/openai-format.js 里做了双向转换(convertOpenAIToAnthropic / 反向),处理了这些差异:
system/developer角色的消息被抽出来拼成独立的system字段image_url(base64 或 URL)转换为 Anthropic 的image/document块tools与tool_choice字段的结构映射
反向转换则发生在响应阶段:无论上游是哪家供应商,返回给客户端的永远是它"说的那门语言"。这层翻译保证了 Cursor(OpenAI 协议)、Claude Code(Anthropic 协议)可以同时挂在同一个网关上,互不干扰。
进入 /v1/messages 后,网关还会做两件"身份识别"的事(见 src/api/router.js):
- 客户端画像检测(
detectClient):认出请求来自 Claude Code 还是 Cursor,后续路由会扣除该客户端自带的"基础工具包",避免把 12 个内置工具误判为"这个用户很复杂" - 认证模式分类(
classifyAuthMode):区分订阅制(subscription)、OAuth 与按量付费(payg)三种流量,分别走不同的透传/优化策略
三、分层路由:判断这个请求"值"哪个模型
这是 Lynkr 最有意思的部分。整个路由决策的文档化视图在 docs/routing-intelligence.md,源码主入口是 src/routing/index.js 中的 determineProviderSmart。
3.1 四档模型:SIMPLE / MEDIUM / COMPLEX / REASONING
Lynkr 把"模型能力"抽象成四个档位,配置在 config/model-tiers.json:
| 档位 | 典型场景 | 示例模型 |
|---|---|---|
| SIMPLE | 打招呼、确认、简单问答 | 本地 Ollama、gpt-4o-mini、haiku |
| MEDIUM | 常规编码、单文件修改 | 中端模型 |
| COMPLEX | 多文件重构、架构设计 | 旗舰模型 |
| REASONING | 深度推理、安全审计 | 带扩展思考的模型 |
每个档位下,14+ 家供应商都有对应的候选模型列表,路由系统会挑当前可用且最划算的那个。
3.2 意图打分:只看"用户真正打了什么"
一个容易踩的坑是:Claude Code 的每个请求都自带 5KB 系统提示词和十几个工具,如果对整个请求体打分,一句 "hi" 也会被算成 COMPLEX。
Lynkr 的解法(pickTierByIntent,见 src/api/router.js)是窗口式意图打分:
- 只取最近 N 条用户亲手输入的消息(剔除工具结果、harness 注入的提示块)
- 按时间衰减加权,得分最高的那条代表"当前意图"
- 再叠加几个快捷规则:
- 出现 "security audit"、"architecture review" 等强制短语 → 直接 COMPLEX
- 命中风险关键词(credential、migration、deploy…)→ 强制 COMPLEX
- 出现 "ultrathink" → REASONING
这个机制的详细设计可参考 docs/intent-window-routing.md。
3.3 会话钉住(Sticky Pin):别每轮都重新纠结
路由决策不是每轮都从头算的。Lynkr 用一个内容指纹(首条用户消息 + 系统提示词头部 + User-Agent 的 SHA256)识别"这是同一场对话",然后把首次决策钉住(pin),后续轮次直接复用,跳过打分、嵌入、kNN 等全部重活。
但钉住不是永久的。文档里把重路由的触发条件称为 "逃生梯"(escape ladder):
- 风险短语出现 → 立即升级到 COMPLEX
- 意图得分超过当前档位上限 → 升级
- 对话超出模型上下文窗口 → 换大窗口模型
- 出现图片 → 本轮临时换视觉模型
- 历史被压缩(compaction)→ 缓存已重置,切换是"免费"的
注意这个梯子只能向上爬:把长对话中途降到便宜模型,意味着整段 prompt 缓存失效重读,通常亏更多。
3.4 学习闭环:kNN + 多臂老虎机
Lynkr 的路由不是静态规则,而是持续学习的:
响应 → 质量评分 → 遥测数据库
├─ 奖励信号 → LinUCB 多臂老虎机更新(档位内选模型)
├─ 高质量结果 → 写入 kNN 索引("类似问题上次谁答得好")
└─ 每 24h → 自动校准档位分数边界
也就是说,用得越久,它越知道"你这类问题该派哪个模型"。kNN 路由器在 src/routing/knn-router.js,奖励管道在 src/routing/reward-pipeline.js,遥测落在本地 .lynkr/telemetry.db。
四、编排器:短路、缓存与 Agent 循环
路由决策只是"派谁去",真正干活的是编排器 src/orchestrator/index.js 中的 processMessage(第 2971 行起)。它的设计哲学是:能不调模型就不调。
请求会依次经过几道"短路闸门":
- Bypass 检测——Claude CLI 的预热 ping、标题生成这类"杂务请求"直接返回预制响应,根本不碰模型
- Preflight 预检——如果请求携带了
preflight_commands且全部通过,说明工作已完成,直接合成响应 - 提示词缓存——请求哈希命中缓存 → 直接回旧答案
- 语义缓存——用嵌入向量找"意思相近"的历史请求,命中即返回(<300ms,0 token)
四道闸门都没拦住,才进入 Agent 主循环 runAgentLoop(第 1452 行起),这里发生两件事:
① 上下文瘦身(src/context/ 目录)
- 历史压缩(compression.js):最近的几轮原文保留,更早的轮次摘要化,老工具结果只留关键信息
- TOON 压缩(toon.js):把大块 JSON 工具输出转成更紧凑的格式,这就是"84% 压缩"的来源
② 调用选定模型并翻译回客户端格式
上游返回的 OpenAI 格式响应,经 toAnthropicResponse 翻译回 Anthropic 格式(含 usage 计费字段对齐),再流式推给客户端。流式转发全程带空闲看门狗(默认 90 秒),上游假死时主动断开重试,而不是让客户端无限挂起。
五、旅程终点:一次完整流程回顾
把整条链路串起来,一个请求在 Lynkr 里的旅程是这样的:
Claude Code 发出 /v1/messages
│
├─ 1. 中间件:会话恢复 · 限流 · 预算 · 循环守卫
├─ 2. 格式转换:OpenAI ↔ Anthropic 协议互译
├─ 3. 身份识别:客户端画像 + 认证模式分类
├─ 4. 意图打分:窗口式评分 → SIMPLE/MEDIUM/COMPLEX/REASONING
├─ 5. 会话钉住:有 pin 且无逃生触发 → 直接复用上次决策
├─ 6. 短路闸门:bypass → preflight → 提示词缓存 → 语义缓存
├─ 7. Agent 循环:历史压缩 · TOON 压缩 · 调用目标模型
├─ 8. 响应翻译:上游格式 → 客户端格式,流式返回
└─ 9. 学习反馈:质量评分 → 遥测 → 老虎机/kNN 更新
整个过程对客户端完全透明——你只需要把 API 地址改成 Lynkr 的本地端口。
六、动手验证:跑一次路由回归测试
最好的源码理解方式是看它"活起来"的样子。仓库根目录的 benchmark-tier-routing.js 是一个 19 场景的路由回归测试套件,覆盖风险强制路由、pin 后逃生、缓存误判防护等历史线上事故。运行方式:
lynkr start
node benchmark-tier-routing.js
打分板中出现 ✗ … ← REGRESSION 意味着某次路由改动破坏了已修复的行为——这也是仓库维护者自己验证路由逻辑的手段,方法详见 docs/benchmarking.md。
总结
Lynkr 源码最值得借鉴的三个设计:
- 窗口式意图打分:只看用户真正输入的文字做路由决策,避免 harness 噪音污染分数
- 单向逃生梯:会话钉住 + 只升不降的升级规则,在"省 token 缓存重读费"和"任务变难及时升级"之间取得平衡
- 学习闭环:每一次响应质量都回流成奖励信号,kNN 索引和多臂老虎机随使用持续变聪明
如果你想进一步阅读,推荐按这个顺序:docs/routing-intelligence.md(路由全貌)→ src/orchestrator/index.js(编排主流程)→ docs/token-optimization.md(压缩细节)。整个仓库的架构索引可参考 integration-map.md。
