前言¶
在 DeepSeek Harness（DSH）里做智能体或日常对话，模型往往不只有官方一条线：账号类免费额度、本机 OpenCode 或 Ollama、以及各家「自带 API Key」的免费层，来源分散、就绪条件各不相同。常见做法是各自配环境变量、各自试连通性，出问题时也很难判断该登录、该起进程还是该换 key。
下面介绍的 dsh-free-model（维护者 DeZhou123，分类为模型推理，当前版本 0.6.0）把上述渠道收进 DSH 的一个设置项、三个页签，并为每条渠道给出就绪状态和可执行的失败原因；渠道清单采用三层目录，可在不发插件新版本的情况下远程增补。
这是什么¶
dsh-free-model 是 DSH 的「免费模型控制台」插件：在宿主内挂载多类不花钱或低成本模型路由，并提供 HTTP 管理面（设置页 + /api/free-model/* 路由）。
它要回答的问题是：有哪些免费模型、现在能不能用、不能用时下一步做什么——而不是让用户在报错里猜。
三类渠道在插件内分开管理（合并成一句「不可用」容易让人试错方向）：
| 类 | 条数（0.6.0） | 路由前缀 | 能力概要 | 页签 |
|---|---|---|---|---|
| 账号渠道 | 2 | buddy/*、workbuddy/* |
工具调用、看图 | 账号渠道 |
| 服务渠道（本机进程） | 6 | 以 opencode/* 等本地/网关车道为主 |
无工具；能看图、不能调工具 | 本地与网关 |
| 自带 key / 免 key | 34 + 1 免 key | <渠道 id>/* |
取决于上游 | 自带 key |
服务车道包括 OpenCode 免费层、FreeLLMAPI 网关、Ollama、LM Studio、vLLM、llama.cpp 等；自带 key 目录在 0.6.0 从 21 条扩到 34 条（另含免 key 渠道），并新增与「就绪」分开的健康账本（401 吊销、429/402 冷却等，落盘于 $DSH_HOME/free-model/health.json）。
核心功能¶
就绪与健康两套信号¶
就绪（GET /channels）表示配置是否满足挂载条件，例如 key 是否已填、账号是否登录、本地服务是否在跑。状态包括：就绪、需动作、不可用、未知，并附带原因（配哪个凭据、去哪拿 key、起哪个服务）。
健康（GET /health）记录上次真实打上游的结果（探测或对话适配器回执），与就绪分离。例如 key 已填但被 401 拒：就绪仍为就绪，健康为已吊销；额度用尽则显示冷却中及剩余时间。页面每张卡有健康徽章（绿 / 黄 / 红 / 灰，灰表示未测），页头提供带计数的筛选胶囊与搜索（渠道名、凭据名、端点、模型样例均可搜）。
自带 key 页：填 key、探测、试跑¶
自 0.4.1 起可在页面保存或清除 key（写宿主凭据，永不回显原文，只返回脱敏值）。保存后立刻尝试挂载路由；清除后凭据删除，路由保留以便报错可读。
典型动作与路由对应关系：
| 动作 | 路由 |
|---|---|
| 保存 / 清除 key | POST /key、DELETE /key |
测试 key（打 /models 或声明的 modelsURL） |
POST /key/probe |
| 试一句话（最小补全，验证能否干活） | POST /key/try |
| 查额度 / 订阅窗口 | POST /key/balance、POST /key/windows |
| 批量探测已配凭据 | POST /key/probe-all |
| 换 key 后清健康 | POST /health/reset |
| 暂时不用某渠道（不清凭据） | POST /channels/toggle |
探测在无 key 时不发请求（no-key）；有 key 时按 kind 分类（如 ok、invalid-key、forbidden、rate-limited、quota 等），便于区分「key 错了」和「网络/WAF/限流」。
账号渠道与服务渠道¶
账号渠道覆盖 CodeBuddy、WorkBuddy：浏览器登录、积分领取、自动签到等能力走账号面路由（如 GET /login、POST /checkin、GET /credits）。插件在宿主已有 accountPool 时会复用。
服务渠道对本机或网关进程做 HTTP 探针（成功/失败各有 TTL 缓存）。OpenCode 可由插件代起 opencode serve（POST /opencode/start 等）；FreeLLMAPI、Ollama 等需按卡片提示配置或启动。
可远程更新的渠道目录¶
渠道元数据分三层叠加：shipped（随包）← remote JSON ← local override。远程拉取走 HTTPS，格式版本不符则整份拒绝；失败时降级到本地层。因此上游换域名、新增免费车道时，不必等插件发版。插件自身还有 semver 版本检查（GET /update）。
安装与启用¶
仓库许可证为 MIT（见 README 安装节）。安装前建议自行浏览 GitHub 源码 与许可证；插件以当前 DSH 进程权限运行，会读写凭据与健康状态文件。
先做下面命令从 GitHub 安装（--profile web 以 README 为准，请换成你实际使用的 profile 名）：
dsh plugin --profile web add github:DeZhou123/dsh-free-model
再做配置：在对应 profile 的 dsh.profile.bundles 末尾追加 "dsh-free-model"，然后重启 DSH 宿主。
README 另提供 link: 本地路径安装方式，适合改插件源码即时验证；路径需改为你本机仓库位置，此处不展开。
典型用法¶
经过上面的安装步骤后，在 DSH 设置里打开 免费模型（section id：free-model）。页内三个页签分别管账号、本地与网关、自带 key；当前页签会记在浏览器 localStorage 的 free-model:tab，刷新后仍停在原页签。
自带 key 渠道（README 0.4.1 流程）：
- 按卡片提示去上游申请免费 key（免 key 渠道跳过）。
- 粘贴到输入框并保存 → 宿主写入凭据并尝试挂载
<渠道 id>/*路由。 - 点「测试 key」→ 根据探测 kind 处理（401 换 key，429 等待，403 未必是 key 问题）。
- 可选：
POST /key/try或页面「试一句话」确认能完成最小补全。 - 换 key 后若仍显示「已吊销」，保存新 key 会自动清该车道健康，或手动
POST /health/reset。
账号渠道：在「账号渠道」页完成登录；需要积分时使用领取、签到相关操作；自动签到状态写在 $DSH_HOME/channel-pack/free-model-auto-checkin.json，与宿主其他自动签到文件独立。
服务渠道：在「本地与网关」查看探针结果；OpenCode 可一键启动/停止/刷新；其他服务按提示在本机起进程或填网关 key。
在智能体或 profile 里选用模型时，路由前缀与上表一致（例如已挂载的 groq/*、openrouter-free/*、buddy/*）。具体模型 id 以各渠道目录或探测结果为准。
维护者还提供 npm run probe:endpoints 等脚本用于端点可达性检查（README 记载 2026-10-26 实测 32/35 可达），属于仓库开发侧验证，普通使用者以设置页探测为主即可。
适用场景与注意¶
适合：希望在 DSH 内集中查看「免费/低成本」模型渠道状态；需要账号车道 + 本地 OpenCode/Ollama + 多家 BYOK 免费层混用；希望渠道清单随社区远程更新而不是等插件发版。
注意：
- 服务车道不支持工具调用，复杂智能体主链路应优先账号车道或能力完整的自带 key 上游。
- 「就绪」与「健康」含义不同：配置齐全不代表 key 未被吊销或额度未用尽。
- 403、网络超时等与 401 处理方式不同，应按探测 kind 与卡片文案操作，避免反复换 key。
- 关闭渠道（toggle）不等于删除 key；未挂载时查看宿主日志，并在页面上重新保存 key 触发挂载。
- DSH 社区插件目录站点 SkillHub 与 DeepSeek / 幻方无官方从属关系；安装来源以你信任的 GitHub 仓库与目录页为准。
结尾¶
dsh-free-model 把分散的免费模型来源收成 DSH 内一个控制台：三页签分治账号、本地服务与 BYOK，就绪与健康分开提示，渠道目录可远程迭代。当前版本 0.6.0，星标数在目录页显示为 0（以站点为准）。
