superboy911/dsh-model-router

中文说明 · English + 中文 paired documentation / 中英配套文档

dsh-model-router is a thin routing-policy plugin for DeepSeek Harness (DSH). DSH still owns providers, credentials, model catalogs, modalities, and retries. This plugin adds deterministic keyword routing, a default-off allowlisted model_route tool, and an isolated image_gen channel.

dsh-model-router 是 DeepSeek Harness（DSH）的薄路由策略插件。模型提供方、凭据、模型目录、模态能力和重试仍由 DSH 管理；本插件只增加确定性的关键词路由、默认关闭的白名单 model_route 工具，以及隔离的 image_gen 生图通道。

The DSH Models page remains the one and only provider configuration entry. / DSH 模型页面仍是唯一的模型提供方配置入口。

Current release / 当前版本：v0.2.2，verified with / 已验证 DSH 0.1.0-rc.6。image_gen is Beta / 仍为 Beta。Video, audio, and 3D are not implemented / 视频、音频和 3D 尚未实现。

A note from the maintainer / 维护者的话

This is my first open-source repository and I am still learning plugin design, testing, security, documentation, and project maintenance. The current version is usable and tested, but it is not presented as a mature or perfect solution. Mistakes, rough edges, and better architectural choices may still exist.

这是我第一次维护开源仓库。我还在学习插件设计、测试、安全、文档和项目维护。当前版本已经可以使用并有自动化测试，但我不会把它包装成成熟或完美的方案；代码里仍可能存在错误、粗糙之处，或者更好的架构选择。

Experienced DSH, TypeScript, security, model-routing, and documentation contributors are especially welcome. A small issue, review comment, reproduction, documentation fix, or pull request is already a meaningful contribution. Please explain the reason when proposing a change so I can learn from it too.

非常欢迎熟悉 DSH、TypeScript、安全、模型路由和技术文档的朋友参与。无论是一个 Issue、一条审查意见、一份复现记录、一次文档修正，还是一个 Pull Request，都很有价值。提出修改时也欢迎说明原因，让我能跟着一起学习。

• How to contribute / 如何参与
• Open roadmap / 公开路线图
• Code of conduct / 社区行为准则

What it does / 能做什么

Capability / 能力	Behavior / 实际行为
Native model catalog / 原生模型目录	Reads active and dormant providers from DSH; never duplicates text adapters. / 读取 DSH 中启用及休眠的提供方，不重复注册文字模型适配器。
Keyword rules / 关键词规则	Ordered, first match wins; no match changes nothing. / 按顺序匹配，首次命中即停；未命中不改动会话。
Subagent routing / 子代理路由	Installs DSH model selection only after a validated subagent rule hit; listeners are removed on plugin disposal. / 仅在子代理规则命中并通过校验后安装 DSH 模型选择，插件卸载时清理监听器。
Exact validation / 精确校验	Validates provider, model, and optional reasoning effort before writing a session header. / 写入会话模型头之前校验提供方、模型和可选推理强度。
model_route	Off by default and limited to explicit allowlist entries. / 默认关闭，只能切换到明确加入白名单的模型。
image_gen Beta	Isolated OpenAI-compatible image endpoint; HTTPS required except loopback HTTP; result downloads are tightly restricted. / 隔离的 OpenAI 兼容生图端点；除本机回环 HTTP 外必须使用 HTTPS，并严格限制结果下载。
Unauthenticated media / 无认证媒体	An empty credential reference sends no Authorization header. / 凭据引用留空时不会发送 Authorization 请求头。
Kimi K3 output guidance / Kimi K3 输出约束	Adds K3-only prompt guidance; never hides or relabels response blocks. / 仅给 K3 增加提示约束，不猜测、不隐藏、不重标响应块。
V1 migration / V1 配置迁移	Migrates in memory and persists V2 only after an explicit save. / 只在内存中迁移，用户明确保存后才持久化 V2。

The router does not call another model to guess which model to use. It executes deterministic rules configured in Settings → Model Hub / 设置 → 模型中枢.

路由器不会再调用一个模型去“猜”应该选谁，而是执行你在设置 → 模型中枢中配置的确定性规则。

Model purchase strategy / 模型购买策略

The included example uses five models as a cost-aware starting point, not as a universal benchmark or purchasing requirement:

示例中的五个模型只是一套兼顾成本的起点，不代表通用排行榜，也不要求贡献者必须购买：

Model / 模型	Suggested role / 建议职责	Cost idea / 成本思路
DeepSeek V4 Flash	Default, daily questions, lightweight analysis / 默认模型、日常问答、轻量分析	Handles most traffic first / 优先承接大多数请求
DeepSeek V4 Pro	Architecture, difficult reasoning, important review / 架构、复杂推理、重要审查	Route only difficult work / 只把高难任务升级过去
Kimi K3	Product design, frontend direction, visual/content planning / 产品设计、前端方向、视觉与内容策划	Call when design keywords match / 设计类关键词命中时调用
Qwen3.7 Plus	Coding implementation, structured tool work, engineering tasks / 代码实现、结构化工具工作、工程任务	Call for coding and execution / 编码和执行型任务按需调用
Doubao Seedream 5.0 Lite / 豆包 Seedream 5.0 Lite	Image generation only / 只负责生图	Explicit tool call; no idle text cost / 明确调用工具才产生生图成本

The principle is “cheap default, targeted upgrade, explicit media call.” Prices and model availability change, so always check the provider’s current official page before purchasing.

原则是“低成本模型做默认、复杂任务定向升级、媒体模型明确调用”。价格和模型可用性会变化，购买前请以各提供方当期官网为准。

See Model strategy and routing boundaries / 模型策略与路由边界 for details.

Requirements / 运行要求

• DeepSeek Harness 0.1.0-rc.6
• Node.js ^22.19.0 or / 或 >=24.0.0
• pnpm 11 for development or rebuilding / 仅开发或重新构建时需要 pnpm 11

Install from GitHub / 从 GitHub 安装

git clone https://github.com/superboy911/dsh-model-router.git
cd dsh-model-router

# Optional: reproduce the committed build. / 可选：复现仓库中的构建产物。
corepack enable
pnpm install --frozen-lockfile
pnpm build

# Install into the DSH web profile. / 安装到 DSH web profile。
npm exec @deepseek-ai/dsh -- plugin --profile web add --force "$PWD"

Restart DSH Web after installation, then open Settings → Model Hub / 设置 → 模型中枢. If you start DSH manually / 安装后重启 DSH Web；手动启动命令如下：

npm exec @deepseek-ai/dsh -- web

Seedream image channel / Seedream 生图通道

Store the real key in DSH Credentials under the reference VOLCENGINE_ARK_API_KEY. Never paste the key into this file. / 请把真实密钥保存在 DSH Credentials 中，引用名使用 VOLCENGINE_ARK_API_KEY；不要把密钥值写进本文件。

model-router:
  mediaProviders:
    - id: volcengine-seedream
      name: Doubao Seedream 5.0 Lite / 豆包 Seedream 5.0 Lite
      capabilities: [image_gen]
      adapter: openai-images
      baseUrl: https://ark.cn-beijing.volces.com/api/v3
      credential: VOLCENGINE_ARK_API_KEY
      models:
        - doubao-seedream-5-0-lite-260128
      allowedResultHosts:
        - ark-acg-cn-beijing.tos-cn-beijing.volces.com
      defaultSize: 1920x1920

The conversation header shows the text model orchestrating the tool call; the image_gen result records the actual image provider and model. / 会话头显示的是负责调度工具的文字模型，image_gen 工具结果才记录真正的生图提供方和模型。

Routing example / 路由示例

model-router:
  schemaVersion: 2
  enabled: true
  matchCase: false
  rules:
    - id: architecture-review
      enabled: true
      keywords: [architecture, refactor, 架构, 重构]
      target:
        provider: deepseek-official
        model: deepseek-v4-pro
        reasoningEffort: high
  agentSwitch:
    enabled: false
    allow: []

No match changes nothing: the current manual selection or DSH default continues to govern the session. / 未命中不改动会话：继续使用当前手动选择，或由 DSH 默认模型接管。

Development and verification / 开发与验证

corepack enable
pnpm install --frozen-lockfile
pnpm test
pnpm check:secrets
pnpm build
pnpm pack:dry

accept:models makes real paid provider calls and is intentionally excluded from CI. / accept:models 会真实调用外部模型并可能产生费用，因此不会在 CI 中运行。

Documentation / 文档

• Configuration / 配置参考 · 中文
• Architecture / 架构说明 · 中文
• Model strategy / 模型策略
• Sanitized example / 脱敏示例
• Security / 安全策略 · 中文
• Contributing / 参与贡献 · 中文
• Changelog / 更新记录 · 中文
• MIT license / MIT 许可证 · 非正式中文译文

Security boundaries / 安全边界

• Never commit keys, DSH settings, signed media URLs, local absolute paths, or generated artifacts. / 不得提交密钥、DSH 设置、签名媒体地址、本机绝对路径或生成产物。
• Media API endpoints require HTTPS; only loopback development endpoints may use HTTP. / 媒体 API 端点必须使用 HTTPS；只有本机回环开发端点可以使用 HTTP。
• Result downloads require HTTPS and pass host, redirect, DNS, size, and magic-byte checks. / 生图结果必须使用 HTTPS，并经过域名、重定向、DNS、大小和文件魔数校验。
• Credential references may reach the settings page; credential values do not. / 设置页可以看到凭据引用名，但看不到凭据值。
• The CodeQL workflow runs after the repository is public. A private repository requires separately enabled GitHub Advanced Security, which this project does not enable automatically. / 仓库公开后 CodeQL 工作流会运行；私有仓库需要另行启用 GitHub Advanced Security，本项目不会自动开启该功能。

Please report suspected vulnerabilities privately through GitHub Security Advisories. / 疑似漏洞请通过 GitHub Security Advisories 私下报告。