前言¶

在 DeepSeek Harness（DSH）里做智能体或日常对话，通常要先选 provider、再配 API Key，还要自己处理某个免费端点 429 或 5xx 之后换哪家。社区插件 dsh-freellmapi（维护者 lion231226）把「按请求选模型、失败自动换候选、流式回传」收进一条 DSH provider 路由：安装后在模型选择器里选 FreeLLMAPI (Auto) 和模型 auto 即可。默认 direct 模式不需要单独跑网关或 Docker，也不强制先填 Key——内置池里包含维护者用无凭证请求验证过的 provider。

README 明确说明：这是社区项目，与 DeepSeek、各上游厂商均无隶属或背书关系；使用各 provider 免费档时需自行遵守其服务条款，并注意免费档可能记录或用于训练的数据。插件在 当前 DSH 进程权限 下运行，安装前建议查看 GitHub 仓库 源码与 MIT License。

这是什么¶

dsh-freellmapi 是 DSH 的 Free-tier multi-provider routing 插件：在 Cordis bundle 里注册 provider 路由 freellmapi，对外呈现为 FreeLLMAPI (Auto)，核心模型 id 为 auto。每次请求会先做一次复杂度分类（simple / medium / complex），再按能力、速度等元数据排序候选模型；遇到 429、5xx、超时或 model_unavailable 会在 尚未发出第一个 chunk 之前 尝试下一个候选，避免同一条回答被两个模型拼接。

与「自己维护一长串 OpenAI 兼容 base URL」相比，插件自带 17 个 provider、46 个模型 的目录（README 表格写 18 provider entries；package 描述为 18 catalogued providers），其中 默认只启用 5 个，且这 5 个均含免费档。未配置 Key 的 provider 在模型列表里会收成 setup:<provider> 指引，而不是一堆无法调用的死模型；若你 固定（pin）某个具体 model id，则不会静默换成别的模型——无 Key、不存在或冷却中会返回明确错误。

另保留 gateway 模式：行为与 v0.1.0 一致，把请求转发到外部的 freellmapi 网关（需自行部署），适合仍想用网关侧 bandit、缓存、fusion 的用户。默认 direct 则路由逻辑全在插件内完成。

分类上，SkillHub 目录将其归为 模型推理。当前 package 版本为 0.7.18（见仓库 package.json）。

核心功能¶

下面按 README「What you get」归纳，均可在仓库文档中核对。

自包含路由（direct）
不依赖外部进程；DSH 启动并加载 bundle 后即可使用。

内置模型池与默认启用范围
目录覆盖 Groq、Cerebras、OpenRouter、Mistral、Z.ai、Volcengine Ark、LongCat、LLM7、Kilo、NVIDIA NIM、OVH AI Endpoints，以及 ModelScope、讯飞星火、SiliconFlow、SambaNova、HuggingFace Router、Routeway 等；每个模型带有能力、速度、上下文、视觉与 tool calling 等事实字段。开箱仅启用其中五个 provider。

按请求复杂度选模型
简单列举类任务与多工具重构类任务不会强制走同一模型；tier 决定排序时更偏重能力还是速度。

失败转移与健康度
首个可重试失败即将候选 park（默认 2 分钟），连续失败按 2 分钟 → 10 分钟 → 1 小时 → 24 小时升级；provider 返回的 Retry-After 优先；401/403 会将该 provider park 24 小时。评分惩罚约 60 秒半衰期，单次 429 不会长期封死路由。

零配置可用
维护者于 2026-10-13 用无 Authorization 请求验证过 keyless 线路（详见仓库 _lead/live-probe-2026-10-13.md）。其中 Kilo、LLM7 默认启用且可无 Key 完成补全；OVH 同样 keyless 但默认关闭。

可观测
默认开启 logRouting 时，每个请求一行日志，例如：

dsh-freellmapi: tier=complex -> openrouter/nvidia/nemotron-3-ultra-550b-a55b:free (capability=5, speed=3, 2 candidates tried)

失败以 in-band finish chunk 返回稳定错误码，而不是未捕获异常。

安装与启用¶

DSH 生态强调「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。安装 spec 以 README 为准。

1、通过 Web GUI（推荐）¶

1. 打开 DSH Web 界面，侧边栏进入 Plugins 管理器。
2. 安装 bundle，粘贴下列之一并确认（若 DSH 提示则重启）：

github:lion231226/dsh-freellmapi          # from GitHub (no npm publish needed)
github:lion231226/dsh-freellmapi#v0.7.18   # pinned to a tag
dsh-freellmapi                            # from npm, once published

插件自带 cordis.patch.yml，正确安装后 不要 在 profile 的 cordis.patch.yml 里再插入相同 id: freellmapi 的行，否则会因 duplicate loader entry 导致 bundle 组合失败。

2、CLI（需对照你的 DSH 构建确认）¶

README 给出等价命令（文档注明未在此端到端验证）：

dsh plugin --profile desktop add github:lion231226/dsh-freellmapi

3、手动放置¶

将包复制到 $DSH_HOME/profiles/<profile>/node_modules/dsh-freellmapi/，在该 profile 的 package.json 中同时写入 dependencies 与 dsh.profile.bundles，执行 dsh plugin --profile <profile> install 并重启。仅写在 dependencies 不会加载 bundle。

运行环境：package.json 要求 Node ^22.19.0 || >=24.0.0。

典型用法¶

Quick start 概括为四步：

install the plugin  →  start DSH  →  pick provider "freellmapi" + model "auto"  →  it answers

具体对应关系如下。

1. 完成安装并启动 DSH。
2. （可选）在插件配置中粘贴部分 provider 的 API Key，见 README Adding keys；跳过此步时，默认启用的 keyless provider 仍可响应。
3. 在模型选择器中选择 provider FreeLLMAPI (Auto)（路由 id 为 freellmapi），模型选 auto。
4. 发起对话或 Agent 任务；若需排查路由决策，保持默认 logRouting 并查看上述单行日志。

若你固定使用某个 catalog 中的 model id 而非 auto，插件会 严格 只调该模型；不满足条件时返回说明，不会偷偷改用其他免费模型。

长跑 Agent 会话：README 专节 Long-running agent sessions 建议在长时间多轮任务里谨慎使用 auto，必要时改 pin 具体模型或调整配置；写 Agent 前建议先读该节。

gateway 模式：在 Configuration 中将 mode 设为 gateway，并指向你自建的 freellmapi 网关；行为与早期版本一致，与 direct 的内置排序、failover 是两套路径。

更细的配置项、模型列表读法、故障排除见 README 的 Configuration、Troubleshooting 等章节。

适用场景与注意¶

适合谁

• 希望在 DSH 里 先跑通再慢慢加 Key，利用默认 keyless + 免费档做开发或轻量任务。
• 需要 单次请求内 按复杂度选模型，并在上游限流或故障时自动换候选，且接受「仅在首 chunk 前 failover」的语义。
• 已有 DSH 插件习惯，愿意使用社区维护的路由表（provider 可用性会随上游变化，README 也列出 Limitations and unverified claims）。

使用前请留意

• 插件 非官方，你对发往各免费 API 的内容负责。
• 安装即信任 bundle 代码；仅在当前工作目录写稿约束下，请直接在 GitHub 审阅源码后再安装。
• CLI 安装命令是否与你的 DSH 版本完全一致，以运行时帮助或 GUI 为准。
• 需要网关侧 fusion / 缓存时，用 gateway 模式并自行运维 freellmapi，而不是默认 direct。

结尾¶

dsh-freellmapi 把多厂商免费档收成 DSH 里的一条 FreeLLMAPI (Auto) + auto 路由：默认无需外部网关，可无 Key 起步，按请求复杂度选模型并在首 chunk 前 failover，pin 模型则不做静默替换。

• 目录页：https://www.skillhub.cn/plugins/lion231226/dsh-freellmapi
• 源码与完整文档：https://github.com/lion231226/dsh-freellmapi