用途
llm-router 是面向 AI 编程工具的通用 LLM 路由器。其目标场景是：用户已订阅 Claude Pro 或 Max 计划、并未额外付费，却仍触碰到五小时使用上限——原因并非提问过多，而是所有提示词都被送给了高级模型，诸如“这个错误是什么意思”“重新格式化这段 JSON”“服务是否在线”这类简单问题与真正需要高级模型的问题消耗了同样的配额。llm-router 会在编码工具自身模型看到提示词之前拦截提示词，先用免费或本地模型起草答案，再按需沿降级链逐级向上调用付费模型。
主要能力
- 免费优先降级链：官方称可降低 35–80% 成本。可路由的提示词先由免费/本地模型起草，仅在必要时才沿链向上走向付费模型。
- 订阅感知，无需 API 密钥：在 Claude Pro/Max 订阅下，路由通过 MCP 工具和本地模型运行，不需要 API 密钥；添加提供商密钥可扩大可用池，但并非必需。
- 适配多种宿主：支持 Claude Code、Cursor、Codex、Gemini CLI、Copilot 等。
llm-router install --host all可一次性安装或打印所有宿主配置。 - Hooks 拦截与分类：在编码工具自身模型看到提示词前拦截，使用免费的 regex 启发式即时分类，约一半真实提示词可被高置信度评分（实测 1,571 条中 788 条），其余回退到默认值。
- 可用的草稿与执行模式：草稿默认是建议性的——作为未验证提示交给 Claude，不替代其回合，除非设置
LLM_ROUTER_ZERO_CLAUDE=1。执行在工具调用层面生效：smart（默认）会暂挂选定工具调用直到提示词被路由；off关闭该行为。 - 安全与容错：密钥永不离开本机——包含 API 密钥、令牌或私钥的提示词仅路由到本地模型（fail-closed）。失败或限流的提供商会自动熔断跳过，而非反复重试。
- 可观测性：状态行、终端标题和操作系统通知显示最近路由的模型、节省与健康状态；会话结束总结包含相对基线的节省、层级组合、各提供商成本、延迟 p50/p95/p99 和热门路由。
- 多模态与编排：提供
llm_image/llm_video/llm_audio，以及用于多步研究的llm_orchestrate。 - MCP 工具表面：默认显示 12 个前门工具；
LLM_ROUTER_SLIM=off显示所有已注册工具。 - 本地运行：完全在用户机器上运行，无托管代理，不向 llm-router 服务发送任何内容，无需账户。
- 接地检查：
src/llm_router/grounding.py会丢弃任何引用其上下文和已索引仓库中不存在的文件或函数的草稿，并回退到 Claude。
使用方式
在 Claude Pro/Max 订阅下无需 API 密钥即可使用，路由经由 MCP 工具和本地模型完成；添加提供商密钥可扩展提供商池，具体见 guide/PROVIDERS.md。安装到其他宿主可使用 llm-router install --host all，该命令会一次性安装或打印每个宿主的配置。各宿主的完整细节（包括每个宿主确实做不到的事情）见 guide/HOST_SUPPORT_MATRIX.md。
路由流程为：Hooks 在编码工具自身模型之前拦截提示词 → 免费 regex 启发式即时分类 → 可路由的提示词先获得免费/本地模型草稿 → 必要时沿链向上走向付费模型。草稿默认作为建议性提示交给 Claude，不替代其回合；设置 LLM_ROUTER_ZERO_CLAUDE=1 可改变此行为。执行层面，smart（默认）会暂挂选定工具调用直到提示词被路由，LLM_ROUTER_ENFORCE=off 可关闭该行为。完整模式与各宿主覆盖项见 guide/GETTING_STARTED.md。
适用场景
面向个人开发者和小型团队：本地成本节省、零运维开销、无任何托管组件。若需要团队范围策略执行、审计导出、SSO 或按组织预算，官方指向另一独立产品 Chuzom。
限制与注意事项
- 草稿的默认性质：路由得到的答案默认是建议性的——Claude 仍会接手该回合，除非设置
LLM_ROUTER_ZERO_CLAUDE=1。默认情况下部分工具调用会等待提示词被路由；LLM_ROUTER_ENFORCE=off可关闭。 - 分类覆盖率：免费 regex 启发式仅对约一半真实提示词给出高置信度评分，其余回退到默认值。
- 节省数字的性质：节省数据是反事实估算——相同 token 按 API 列表价计算会花费多少，与实际花费的对比——并非扁平订阅上省下的钱。
llm-router status和llm-router savings-report将已验证与未验证节省分开报告，各自带有自己的 n。该项目不发布通用节省百分比；任何数字取决于用户自身工作负载。方法与局限见docs/MEASUREMENT.md。 - 直接执行的安全风险：
LLM_ROUTER_DIRECT_EXECUTION默认开启，本地模型在受限的允许列表路径下获得write_file、edit_file和run_command，这些都无法阻止定向删除、git push --force或数据外泄。可通过LLM_ROUTER_DIRECT_EXECUTION=false关闭。完整分析见SECURITY.md。 - 基准测试状态：llm-router 在 RouterArena 基准上评分——完整拆分、8,400 条查询、使用本仓库测试框架本地评分，尚未经独立验证。当前 Arena Score 为 72.35。完整方法与负面结果（包括一个使调优偏差 4.25 分的代理拆分）见
docs/ROUTERARENA.md。 - Ground Truth 累积：可选开启（
LLM_ROUTER_GROUND_TRUTH=1），构建可重放的路由决策语料库而非无关联遥测；默认关闭，因为这是唯一会将提示词文本写入磁盘的部分。详情见guide/GROUND_TRUTH.md。 - 自审计：自审计发布在
audit/和docs/repo_goals/AUDIT-2026-09-25.md（13 项达标、6 项部分达标、1 项未达标），包含负面结果。
其他信息
- 完整索引：
guide/README.md - 贡献：见
CONTRIBUTING.md - 许可证：MIT License
- 相关链接：Issues · Discussions · PyPI · Changelog
