dsh-subagent-custom

dsh plugin --profile web add dsh-subagent-custom

<div align="center">

<!-- 项目 Logo -->

<img src="https://raw.githubusercontent.com/xingzhen199186/dsh-subagent-custom/main/docs/logo.png" alt="dsh-subagent-custom Logo" width="120" height="120" />

dsh-subagent-custom

DeepSeek Harness 子代理模型管控与 Jev 智能分流插件

<p align="center">

专为 <strong>DeepSeek Harness 用户与开发者</strong> 打造的 <strong>子代理模型决策与分流扩展</strong>，解决 <strong>子代理无法独立选型、复杂任务与琐碎任务共用高配主模型导致算力浪费与响应缓慢</strong> 的痛点。

</p>

<p align="center">

<img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License">

<img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg?style=flat-square" alt="Node.js Version">

<img src="https://img.shields.io/npm/v/dsh-subagent-custom?style=flat-square" alt="npm Version">

<img src="https://img.shields.io/badge/tests-97%20passed-success.svg?style=flat-square" alt="Tests">

<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome">

<img src="https://img.shields.io/badge/status-active%20development-informational.svg?style=flat-square" alt="Status">

</p>

<p align="center">

<a href="#-背景与痛点-why">背景与痛点</a> •

<a href="#-核心特性-features">核心特性</a> •

<a href="#-效果预览-preview">效果预览</a> •

<a href="#-快速上手-quick-start">快速上手</a> •

<a href="#-使用指南-usage">使用指南</a> •

<a href="#-核心机制与判定流转">核心机制与判定流转</a> •

<a href="#-离线策略回放-jev-replay">离线策略回放</a> •

<a href="#-开发与测试">开发与测试</a> •

<a href="#-由来与致谢-provenance">由来与致谢</a> •

<a href="#-开源协议-license">开源协议</a>

</p>

</div>

---

📌 背景与痛点 (Why?)

在 DeepSeek Harness (DSH) 原生的多智能体调度与协作体系中，派发子代理（Subagent）通常面临以下结构性痛点：

1. 子代理无法独立选型：原生子代理往往只能默认继承父级主模型的配置或调用方传参，用户无法根据子任务属性为子代理灵活绑定专用模型。

2. 高阶算力浪费与响应成本高昂：格式化排版、变量重命名、常规查阅等琐碎机械型任务，与深度业务架构设计同样依赖高配主模型执行，不仅消耗珍贵的高阶模型配额，还延长了整体响应耗时。

3. 分流缺乏工程化防御与硬性隔离：依赖大模型自身在 Prompt 里自我判断何时派发子任务，速度缓慢且容易产生幻觉。当任务涉及敏感凭据泄露或破坏性操作风险时，缺乏确定性的前置安全门禁与拦截策略。

dsh-subagent-custom 针对上述问题构建了一套前置判定与模型重写方案。它接入 TypeSafe System One 架构的 Jev 分类器，在毫秒级时延内对用户任务完成多维结构化评估；同时在底层拦截并硬性改写子代理的模型与推理参数，实现子代理选型的精细化管控。

---

✨ 核心特性 (Features)

• ⚡ 底层请求级硬性改写：基于 DSH 核心钩子 agent/request 拦截请求，直接改写子代理的 provider、model 与 reasoningEffort，覆盖调用方的默认传参，确保调度决策百分之百落地。
• 💬 角色前置提示词：每个角色可以带一条只喂给它的前置提示词，以一条消息注入、先于任务；只在 Jev 自动分配（auto）时生效，且对同一个子代理只注入一次。
• 🧠 Jev 语义极速判型：接入 Jev 判定模型，对任务类别（Task Class）、工作量（Effort）、爆炸半径（Blast Radius）与高危属性（Risky）展开结构化判定，毫秒级得出评估结果。
• 🎛️ 双层管控开关解耦：
• 插件级激活模式（mode）：控制后台分类器的侦听行为（off 关闭、once 按触发词判定、auto 全自动评估）。
• 会话级选择器模式（写在配置的 selections.<会话>.mode 里，由输入框上方的选择器写入）：控制当前会话对子代理模型的绑定行为（inherit 继承主模型、auto 依 Jev 判定自动映射、manual 手动指定固定模型与思考程度）。
• ⚖️ 「三点对齐」派发防御法则：必须同时满足目标角色有合法模型、任务类别映射该角色、活跃档位白名单放行该类别，三者缺一绝不放行，杜绝意外派发。
• 🛡️ 隐私脱敏与静默放行（Fail-Open）：进入判定前自动对 API Key、Token、Bearer 等凭据特征执行正则脱敏，并实施字符上限裁剪；判定超时（默认 4000 ms）或网络异常时静默放行，主会话正常流转绝不阻断。
• 🔄 预设类别平滑自动补入：升级时自动补全出厂预设中新增的任务类别与允许清单，采用增量补齐策略，不放宽用户收紧的档位规则，使用 adoptedClasses 防重标记保障幂等性。
• 🖥️ 全功能 Web GUI 与三语本地化：深度注入 DSH Web 界面，包含输入框上方的模式切换器、会话标题栏状态徽章、右侧边栏专属标签页（状态、角色矩阵与最近 20 条派发流水），完整支持中文、英文、俄语。

---

🖼️ 效果预览 (Preview)

输入框模式切换器 · 「子代理模型」边栏标签页 · 插件可视化设置卡片

!输入框模式切换器 · !子代理模型边栏标签页 · !插件设置卡片

位于主模型选择器右侧：继承主模型、交给 Jev 自动分配，或从列表中手动指定模型 · 当前会话状态、每个角色跑在哪个模型上，以及最近派发流水 · 提供商预设、决策档位，以及每个角色所用的模型与前置提示词

💡 注：三张均为实际界面截图（桌面端）。

---

🚀 快速上手 (Quick Start)

环境依赖

• Node.js：>= 22.0.0
• 包管理器：pnpm（建议 >= 9.0.0）
• 宿主系统：DeepSeek Harness (DSH) ^0.1.7-rc.2 或兼容版本
• 核心 Peer 依赖：
• @deepseek-ai/schemastery: >=3.18.1
• @deepseek-ai/dsh-typert-protocol: >=0.1.7-rc.2 <0.3.0
• @deepseek-ai/dsh-llm: ^0.2.0-rc.2 || >=0.1.0-rc.6 <0.2.0（可选）

安装与加载步骤

本项目已发布至 npm 官方注册表，下面三条路任选其一。

甲：在 DSH 桌面端安装（推荐）：

1. 打开 DSH 桌面客户端，点击导航栏上方的「插件」按钮，进入插件页面；

2. 点击「添加插件」；

3. 在输入框里填写包名 dsh-subagent-custom——该输入框也接受 GitHub 仓库地址或本地目录路径；

4. 确认「安装源」为 npm 官方源，点击「安装」。

💡 插件安装后暂不支持自动更新。需要升级时，先在插件页面卸载，再按同样步骤安装新版。

乙：从命令行安装（适用于 web 这类命令行管理的配置档）：

dsh plugin --profile web add dsh-subagent-custom

丙：从源码本地打包（想改动源码时）：

1. 获取源码并编译客户端资源：

   git clone https://github.com/xingzhen199186/dsh-subagent-custom.git
   cd dsh-subagent-custom
   pnpm install
   node scripts/build-client.mjs

2. 打包生成插件安装包：

   pnpm pack

执行完成后在项目根目录生成 dsh-subagent-custom-<版本号>.tgz。

3. 安装这一份本地包：回到桌面端「添加插件」，填入该 .tgz 文件（或项目目录）的完整路径，点击「安装」；命令行管理的配置档则用 dsh plugin --profile web add <该路径>。

⚠️ 注意：

插件包含宿主侧（Node.js 服务端）拦截逻辑。安装或更新插件后，必须重启 DSH 桌面端应用，宿主侧注入服务方可完全生效。

---

⚙️ 使用指南 (Usage)

1. 模式体系辨析：双层开关控制

本插件包含两个层级不同、职责分明的开关体系，请避免混淆：

控制维度 · 开关配置位置 · 可选枚举值 · 核心职责

插件全局侦听模式 · 插件全局设置面板 (config.mode) · off / once / auto · 控制后台判定服务何时介入：<br>• off：完全关闭监听与判定，零调用开销；<br>• once：仅当用户输入命中触发词（如 /route、/jev）时单次评估；<br>• auto：对每一轮用户普通输入均进行判定。

会话模型绑定模式 · 对话输入框上方选择器（写入配置的 selections.<会话>.mode） · inherit / auto / manual · 控制当前会话如何约束子代理模型：<br>• inherit：继承主模型或调用方原有参数，不强行重写；<br>• auto：依据 Jev 判定结果，自动挂载预设角色与对应模型；<br>• manual：会话内固定锁定用户选定的模型与思考程度。

---

2. 角色路由与任务类别矩阵

出厂预置 5 个角色 与 8 种任务类别。设计遵循「角色代表执行者身份（Worker），类别代表具体工作性质（Work）」原则：

角色名称 (Role) · 默认绑定模型示例 · 承接的任务类别 (Task Class) · 出厂策略状态

junior · openrouter/qwen3.8-flash · mechanical（格式化、重命名、样板代码、注释整理等有明确规约的机械改动） · 默认派发

implementer · openrouter/deepseek-v4-flash · bugfix（根因已知、改动范围可控的缺陷修复） · 默认派发（兜底角色）

researcher · openrouter/qwen3.8-flash · research（查阅代码、收集事实、对比方案，不做代码修改） · 默认派发

reviewer · openrouter/qwen3.8-flash · review（审查已有代码差异、PR 或技术方案，指出缺陷而非动手修复） · 默认派发

writer · openrouter/qwen3.8-flash · `documentation

…(truncated)