前言¶
DeepSeek Harness（DSH）里，llm-pi-ai 适配器在构造 SDK 客户端时就固定了请求形态，请求体还是深冻结的。插件很难在会话流里可靠地改写「这一次用哪个模型」，也无法在上游返回 429 时自动换模型重发。把路由逻辑塞进 llm/stream 瀑布，往往还会跟着 DSH 升级一起失效。
下面介绍 DSH Token Steward（仓库名 dsh-token-steward，SkillHub 展示名 jiamingshi-jsphys/dsh-token-steward）。它在本机 127.0.0.1 起一个 OpenAI 兼容网关，把 llm-pi-ai 的 baseURL 指过去；DSH 的会话、子代理、工具调用不用改。选路、降级、健康熔断、精确缓存与计量发生在网关这一层。维护者为 JiamingShi-JsPhys，社区目录分类为模型推理。
这是什么¶
Token Steward 是面向 DSH 的模型矩阵调度中枢：官方 API、免费镜像、自建中转、高价全能模型都可以挂在同一张池子里。矩阵、厂家密钥、价目与擅长标签在 DSH 设置页的「管家设置」维护；插件还注册了 token_steward_manage 工具与同名技能，可由 Agent 通过对话改配置。
适用环境（据 README）：DeepSeek Harness ≥ 0.2.1-rc.3；包描述版本 1.1.3，README 安装示例标签为 v1.1.2，测试规模 README 写明 558 条。许可证 MIT，运行要求 Node ≥ 22。本包尚未发布到 npm（pnpm add dsh-token-steward 会 404）。
架构与请求路径¶
网关采用硬过滤 → 打分 → 降级链的微内核流水线：先淘汰不合格型号（缺能力标签、窗口放不下、用户下线、非对话模型等），再在剩余候选里排序；首个失败按序顶上。
请求大致路径为：Agent / 子代理 / 工具调用 → DSH 会话层 ctx.llm（不改）→ llm-pi-ai，baseURL 指向 http://127.0.0.1:<port>/v1 → 本地网关（Bearer 校验，仅回环）→ 路由引擎；可回放请求可命中 SQLite 精确缓存（0 token、不出站）→ 上游厂家 → 计量与面板。
要点如下：
- 网关只绑
127.0.0.1，端口由系统分配；每次启动生成随机本地令牌，客户端需带Authorization: Bearer。 - 硬过滤是硬拒绝：例如写代码任务不会派给不具备对应能力标签的模型。
- 降级仅在客户端尚未收到第一个字节时发生；首字节已发出则不再重发，避免二次副作用。
- 缓存命中不经过健康状态机，避免给上游制造假样本。
厂家 API Key 以明文存放在 $DSH_HOME/token-steward/vendors.json（权限 0600）。作者声明其未加密存储，与 DSH 凭据文件同级对待；白嫖模式之外的调用按上游账单计费，费用与第三方服务可用性由使用者自行承担。
四种调度模式¶
输入框里选的虚拟模型 id 决定档位；悬浮窗只显示当前档位，换档需改输入框模型。
| 模式 | 虚拟 id | 主序 |
|---|---|---|
| 极致便宜 | steward:frugal |
通过硬过滤的 C/D 级里最便宜，同价比六维分 |
| 效率优先 | steward:balanced |
任务维度须 A/A+ 及以上，质量 0.6 + 成本 0.4；同批并发打散到不同上游 |
| 最强火力 | steward:max_power |
六维总和最高，破平看 Tier 与上下文窗口 |
| 白嫖 | steward:free |
仅价目为 0 的型号；选不到则报错，不会偷偷切付费模型 |
steward:subagent 是子代理专用模型 id，不是上述四种模式之一；只要主会话使用管家开头的模型，子代理按独立打分规则选型（agentic 维度门槛 B+，含会话粘性与并发打散等）。可通过工具查询推荐：
action=recommend_model, profile=subagent, task="读仓库并改一个测试"
容灾与跨模型上下文¶
常见上游异常在单次客户端请求内处理，尽量不把失败抛回会话层：
| 状况 | 行为 |
|---|---|
| 429 | 指数退避冷却（上限 16 倍），本次换下一候选 |
| 连续超时 / 5xx / 传输失败 | 达阈值熔断，半开试探成功后复位 |
| 401 / 403 | 一次即熔断 |
| 400 含上下文措辞 | 归类上下文超限，换更大窗口 |
| 全部候选失败 | 502 + 可读原因 |
换模型时，DSH 会话历史仍会完整发给新模型；插件在 API 层处理前缀缓存粘性、跨厂商字段归一化（如 reasoning_content 等）、以及窗口过小时的硬拒绝（window-too-small），而不是悄悄截断历史。
SQLite 精确缓存¶
在配置 routing.cache.exact_match: true 时，对 prompt 取 SHA-256，在 $DSH_HOME/token-steward/cache.sqlite 查上次响应；命中则直接回放，不计费。规则包括：带 tools 的请求不缓存、超长 prompt 不缓存、模型下线后作废其缓存条目；无 node:sqlite 的老宿主可降级为内存 LRU。
计量与界面¶
token 以 dsh-usage 按日台账为主；插件另记路由维度台账。未定价模型成本显示 —；CNY 与 USD 混存时总额显示 —；未装 dsh-usage 时显示「计量不可用」。装上 DSH 后，界面有右下角悬浮球（档位与「今日已省」）及成本看板、模型矩阵、路由日志、代理协作等页签。
安装与启用¶
本插件以当前 DSH 进程权限运行；安装前请自行审阅源码与 MIT 许可证，并理解密钥与计费免责声明。
1. 安装依赖包¶
README 给出的 GitHub 安装方式（二选一之一，不使用 dsh plugin add 拼接）：
pnpm add https://github.com/JiamingShi-JsPhys/dsh-token-steward.git#v1.1.2
若无 git，可到 Releases 下载 dsh-token-steward-<版本>.zip，解压后：
pnpm add file:<解压路径>
2. 写入插件名册¶
在 ~/.dsh/profiles/desktop/cordis.patch.yml 追加（完整样例见包内 cordis.patch.yml）：
- insert:
- id: token-steward
name: dsh-token-steward
config:
enabled: true
3. 重启 DSH¶
重启后插件会检查 profile 里 @deepseek-ai/dsh-llm-pi-ai 的 providers，缺 steward 时自动写入一段 OpenAI 兼容配置（baseURL 指向本机网关，apiKeyEnv: STEWARD_LOCAL_TOKEN，并注册四个档位模型 id）。若不想自动改 profile，可在插件配置设 autoWire: false，再按 README 样例手写 steward 段。
写回后再重启一次 DSH，输入框可选「管家·极致便宜 / 效率优先 / 最强火力 / 白嫖」。「管家设置 → 个人网关」可确认是否接上。
适用场景与注意¶
适合需要在同一会话里混用多上游、按任务类型选模型、并在 429/5xx 时自动换路的 DSH 用户。也适合需要按路由维度看延迟与费用、并可选本地精确缓存省重复调用的场景。
使用时请注意：白嫖模式只承诺零价目候选，与「极致便宜」等付费档互不混淆；自建或未知价目型号在白嫖语义下可能以「推定免费」进候选，看板仍可能标未定价。插件是个人维护的调度工具，不是经同行评审的服务；上游价格与策略变动需自行关注。
结尾¶
Token Steward 把「选谁、失败了换谁、要不要读缓存、花了多少」收敛到本机 OpenAI 兼容网关，让 DSH 侧继续用熟悉的 llm-pi-ai 调用形状。目录与源码如下：
- SkillHub 目录页：https://www.skillhub.cn/plugins/JiamingShi-JsPhys/dsh-token-steward
- GitHub：https://github.com/JiamingShi-JsPhys/dsh-token-steward
社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装与配置以仓库 README 与 Releases 为准。
