dsh-our-free-model 部署指南：DeepSeek Harness 免费模型插件详解

一、项目介绍

dsh-our-free-model 是一款面向 DeepSeek Harness（内核命令名 dsh）的免费模型插件，以独立插件的形式挂载进宿主应用，不改内核、零依赖、无需任何构建步骤。它要解决的问题非常直接：你在 dsh 里装上它之后，不需要登录、不需要注册、不需要填写任何 API Key，就能在模型选择器里直接选用包括 DeepSeek V4.1 Flash、Kimi K3、GLM 5.3 Flash、MiMo V2.6 在内的一批前沿模型，并且没有用量套餐的概念。

这些免费车道的上游来源是公开透明的：免费推理通道直连 OpenCode 的公开网关，模型请求发往其推理端点；另一路 Kilo 渠道直连 Kilo AI 的公共网关免费池，内置实时拉取的免费模型清单与 kilo-auto/free 自动路由。两条通道都不经过任何第三方中转，插件代码中也不持有任何属于用户的密钥。模型集合、上下文长度与能力声明在每次刷新时向上游重新拉取，插件内部不保存静态快照。

除了免费车道本身，插件还提供了一整套工程化能力：选择器只广播当前出口实际可用的模型；仓库维护者推送的公告最迟在一个轮询周期内到达所有已安装实例；设置页支持一键应用内升级，下载、校验、备份、原子替换、热重载全流程闭环，失败自动回滚；本机用量看板的 Token 热力图、总量曲线、首字延迟全部留在本机，不上传任何数据；同时内置一个 OpenAI 兼容的本地转发端口，并额外提供 Anthropic Messages 协议端点，让 Claude Code、各类 SDK 与 curl 都能直接指向它。此外还带有自带 Key 的聚合渠道（内置七十六家提供商注册表）、工具输出压缩等省 Token 能力、跨车道的命名降级链，以及桌面端专属的 EAC 协付渠道。

官方仓库提供的社区认可标识

项目以 MIT 许可证开源，当前处于 beta 状态，源码为明文 JavaScript，作为本地插件这是固有形态；完整代码、发布清单与签名机制都托管在 GitHub 仓库。

二、项目结构

仓库是一个纯插件目录，没有打包产物、没有 install 脚本。宿主半身集中在 index.js 一个文件里：负责适配器注册、模型清单与可用性探测、设置与用量存储、webServer 路由、转发端口的生命周期，以及公告、升级与热重载的接线。adapter/ 目录是全包唯一允许引用内核内部模块的位置，用于把插件能力翻译成内核要求的适配器形态。

src/ 目录按职责拆分：adapter.js 是结构性的模型适配器，实现清单解析、模型解析、调用准备与流式输出；upstream.js 封装上游网关身份、会话与请求标识铸造、工具指纹与端点选择；stream.js 统一解码 chat、messages、responses 三种线协议；messages.js 把 harness 消息映射成各协议形态并修复工具调用配对；effort.js 负责把思考档位换算成输出预算；forward.js 是独立的 OpenAI 兼容监听器，同时挂载 Anthropic Messages 端点。

其余模块各司其职：providers/ 下是七十六家聚合提供商的注册表与复合标识解析；aggregate.js 处理聚合车道的清单行、凭据脱敏与列表探测；anthropic.js 实现 /v1/messages 的编解码与本地 token 估算；token-saver/ 是工具输出压缩管线；combos.js 把降级链实现为虚拟清单行；route/classify.js 统一全车道的失败分类与冷却策略；trust.js 是插件路由的请求信任围栏；push.js 为公告与升级提供 SSE 推送枢纽；feed.js 拉取远程公告并做多源校验；updater.js 完成应用内升级的签名校验、哈希比对、备份与回滚；reload.js 实现自热重载。client.js 是浏览器半身，使用手写模块加载器打包，因此同样没有构建步骤。

架构上有几个值得了解的决定：适配器以结构化方式实现而不直接依赖内核模型模块，因此同一份代码可以同时跑在 0.1.5 与 0.1.7 两版内核上；插件使用自己的 JSON 存储而非内核设置接口，转发密钥存放在权限为 0600 的私有文件中；Token 压缩收口在唯一一处派发函数上，每条车道、每一段恢复请求都经过同一压缩，且每一步失败都开放放行，绝不让一个为了省钱的环节把请求弄失败。仓库另含 packages/standalone 独立本地服务入口，无需安装 dsh 即可作为独立服务运行，目前仍在开发中，制品尚未随 Release 发布。

三、版本与环境要求

运行环境方面，插件适配的 dsh 内核版本范围为 0.1.5 至 0.1.7-rc.2，这是官方明确标注的兼容区间。如果你参与从源码开发插件本体，需要 Node 运行时版本为 ^22.19.0 或 >=24.0.0；普通用户通过 dsh 宿主安装时则由宿主自带的 Node 运行，无需单独准备。

网络方面，机器出口需要能够访问上游推理网关、模型清单接口与公告源仓库，另会访问几个只读 IP 定位服务以判定本机出口国家码，用于区分地区受限模型。短时间高频调用会按会话统计速率并返回限流状态，这属于上游行为而非插件限制。

需要特别警惕的一点：npm 上存在一个同名的 dsh-our-free-model 包，它并非本仓库发布，入口文件被改动过并附带本仓库从未有过的额外模块，安装它既拿不到审核过的构建，也享受不到签名清单校验与应用内升级。请只使用本仓库 Release 发布包或本地源码目录安装，其它渠道出现的同名包一律以仓库为准。

平台方面，插件本体在 Windows 环境下经过完整实测；macOS 桌面壳为社区构建，未经苹果开发者签名与公证；服务器形态请使用纯 web profile 命令行安装。

四、本地部署步骤

纯命令行环境（dsh web profile）的安装只有一步，在终端中执行：

dsh plugin --profile web add /绝对路径/dsh-our-free-model

其中路径替换为本机解压后的插件目录绝对路径，--profile 填写你实际使用的 profile 名称，安装完成后重启应用一次即可。也可以先从仓库的 Releases 页面下载官方发布包，解压后把解压目录作为上面命令的参数，这样能绕开插件市场走 git 源自动安装时本机 git 配置带来的问题。

如果你使用的是 DSHEAC AIO 或旧版桌面整合包，启动 web 服务前可能有一道 profile 闸门，报错 offline dependency migration is not yet available。此时不要使用符号链接或目录联接，应改用应用内插件管理器，或改用本地压缩包方式：在审核过的插件目录中执行打包命令生成 tgz，放入 <DSH_HOME>/profiles/<profile>/vendor/ 目录，再在该 profile 的 package.json 依赖中以 file:./vendor/ 形式引用，最后在 dsh.profile.bundles 末尾追加插件名。注意手工复制发布文件时必须复制完整目录，包括适配器、源码、本地化文件与渠道包下的元数据，只复制入口脚本会导致渠道加载失败。

安装过程中常见的两类报错可以对号入座：其一，pnpm 虚拟存储目录版本不一致类报错，这是目标 profile 旧依赖状态与 dsh 更新后内置 pnpm 版本不匹配所致，关闭 dsh 删除该 profile 的 node_modules 与 pnpm-lock.yaml 让其重建后重装即可；其二，桌面端提示该 profile 只允许 Electron 应用自己管理，这是宿主自身保护，请改用桌面端的插件管理器（设置 → 插件）完成安装，命令行只适用于纯 web profile。

安装完成后可以做一次自检：通过配置导出命令确认插件只注册了一个标识，没有重复条目。随后启动应用，打开输入框旁的模型选择器，即可看到 Our Free Model 分组下的模型列表，选择任意模型即可开始对话；选择结果按会话持久化。

五、浏览器端部署

dsh web 启动后在浏览器中打开应用页面，插件的全部界面都在设置页内，入口为设置 → Our Free Model。顶部导航共十一个页面：免费模型页的鱼缸水位直观表示可用模型占比；EAC 模型页展示桌面端协付池；白嫖模型接入页汇总各账号渠道的登录、账号池与积分领取；数据看板页呈现今日与累计 Token 消耗、平均生成速度、缓存命中率与成功率；运行日志页逐请求列出结果、耗时、首字延迟与速度细分；网关设置页管理转发开关、端点、密钥与局域网中继。新增的聚合渠道、省 Token、路由、插件升级与推荐项目页面则分别对应各自功能。

模型选择器内部分为两个分组：Our Free Model 是当前网络出口可直接使用的模型；Our Free Model · region-limited 是上游对本地区不放行、但保留可见并单独隔离的模型。被上游明确拒绝路由的模型不会出现在下拉框中，只在设置页保留记录并注明拒因；而网关自身故障、限流、超时与断网都不属于对模型的判定，这些模型一律保持可达。切换 VPN 状态后点击重新探测可用性，地区受限模型会在两个分组间自动迁移。

思考强度在同一菜单的 Effort 项中调节：声明了思考档位的模型给出它自己的档位菜单，选中值按原值下发到上游；其余模型提供 Light、Balanced、Deep 三档预算阶梯，档位越高思考占用的输出预算越多。如果回答被截断，可以切换到更高档位，或在设置页调高单次输出上限。

本地转发默认关闭，在设置 → Our Free Model → 本地转发中启用后复制 base URL 并生成密钥。同一面板下方还提供局域网访问开关，默认关闭；启用后中继绑定可路由地址并要求使用独立的局域网密钥，与本机密钥互不通用，任一泄露只需轮换对应一侧。该功能应仅在可信网络中启用，因为任何能访问该主机的人都可以用这把密钥消耗本机的免费额度。无 web server 的极简环境中插件同样能启动并输出模型，看板模块会挂在独立纤维上，等 web 服务就绪后再注册路由，不会阻塞模型车道。

macOS 用户如果使用社区构建的桌面壳，首次启动被 Gatekeeper 拦截时，可按住 Control 点按应用图标选择打开，或在终端清除隔离属性后重试。升级插件全程在应用内完成：设置 → 插件升级 → 检查更新 → 立即升级，无需重启应用；仓库推送公告后运行中的实例会在一个轮询周期内自动收到通知。

六、API 用法

启用本地转发后，本机其它工具就可以像调用任何 OpenAI 兼容服务一样调用这些模型。端点默认监听回环地址 127.0.0.1，端口默认 18899；该端口被占用时插件不会静默失效，会先在同端口重试数轮，仍被占用则顺延到下一个可用端口，并在设置页如实标注实际监听端口，落盘记录的也是实际端口。Windows 上最常见的占用来源是一条端口代理规则导致回环绑定被拒绝，可用系统命令列出并清除该规则。

支持的端点包括：

GET /v1/models —— 广播全部车道的模型清单，含聚合行与降级链；
POST /v1/chat/completions —— OpenAI Chat Completions，流式与非流式；
POST /v1/responses —— OpenAI Responses API；
POST /v1/messages —— Anthropic Messages，流式与非流式，含 thinking 与 tool_use 块；
POST /v1/messages/count_tokens —— 本地估算，插件不含分词器。

一次最小化的 curl 调用形如：

curl http://127.0.0.1:实际端口/v1/chat/completions \
  -H "Authorization: Bearer 你的本地密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"our-free-model/deepseek-v4.1-flash-free","messages":[{"role":"user","content":"你好"}]}'

网关设置页还内置了接入客户端分区，按实际绑定端口与真实密钥生成可直接复制的配方：Claude Code 的环境变量配置、Codex 的配置文件、OpenAI SDK、Anthropic SDK、curl 以及中继开启时的局域网版本。这样 Claude Code 与各类 Anthropic SDK 可以直接把本插件当作后端。转发端点是全流式的：思考期间的静默由周期性 SSE 注释帧填充，客户端的空闲超时不会把上游仍在推理误判为连接断开；思考内容按 reasoning、reasoning_content、reasoning_text 等多个字段识别。局域网中继仅放行 /v1/* 白名单路径，携带跳数标记的请求直接拒绝，因此即使配置成同一端口也不会自环。

七、常见问题 FAQ

问一：免费车道真的不要钱吗，有没有隐藏额度？
答：没有充值、没有套餐、没有按 token 计费的额度体系。但免费额度由上游单方面提供，按会话统计速率，短时间打满会返回限流状态，插件会把该模型标记为已达限额而不隐藏，下一轮探测自动恢复。需要注意 Kilo 免费池在其模型卡中明确声明提示词可能被上游记录用于改进服务，因此请勿通过免费车道发送密码、密钥、个人身份信息或商业机密，生产与敏感场景应使用自己的付费 API。

问二：模型下拉框是空的，或者某个常用模型不见了？
答：选择器只广播当前出口实测可用的模型。上游清单已声明但网关明确拒绝路由的模型会从下拉框移除，仅在设置页保留记录与拒因；后续探测重新通过后自动回到选择器。网关故障、限流、超时与断网一律不会把模型判定为不可用。如果是地区策略导致，模型会进入 region-limited 分组；点击重新探测可用性即可按当前出口刷新，切换网络环境后建议执行一次。

问三：本地转发端口起不来，或者端口号不是 18899？
答：这是有意设计。请求端口被占用时插件会顺延到下一个可用端口并落盘，设置页会标注实际监听端口，请以页面显示为准。Windows 上常见的原因是一条端口代理规则对 0.0.0.0 的监听导致回环绑定被拒绝，可用 netsh 相关命令列出规则并清除。另外，监听地址只允许绑定回环，改成可路由地址会被直接拒绝；要跨机器使用必须显式开启局域网访问并使用独立密钥。

问四：应该怎么升级插件，能不能顺手用 npm 更新？
答：不要用 npm。npm 上的同名包并非官方发布。正确方式是在设置 → Our Free Model → 插件升级中检查更新并一键升级，全流程为下载、清单签名与哈希校验、备份、原子替换、热重载，任一步失败自动回滚到上一版本。升级信任根为插件内置的签名公钥，镜像源被投毒只会导致升级失败而不会执行其中代码。

问五：思考很久之后回答是空的，或者长回答被截断？
答：部分模型的思考过程静默进行且与正文共享输出预算，思考阶段可能耗时数十秒。对策包括：在菜单中切换思考档位或调高设置页的单次输出上限到 16k 以上，或选择模型卡上标注思考关闭的模型。插件内置了一次有界的自动恢复：当首段只有思考没有正文且上游异常收尾时，会以已收到的思考为检查点重新发起一次请求直接整理回答；已输出正文、工具调用、用户取消与明确错误不触发恢复，每个逻辑回合最多追加一次请求。

交流群入群二维码

如果在使用中遇到问题，可以扫描上方二维码加入官方交流群（群号 1127616546）反馈，也欢迎在 GitHub 仓库提交 issue。