dsh-subagent-custom

⚙️ 使用指南 (Usage)

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

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

控制维度	开关配置位置	可选枚举值	核心职责
插件全局侦听模式	插件全局设置面板 (config.mode)	off / once / auto	控制后台判定服务何时介入：
• off：完全关闭监听与判定，零调用开销；
• once：仅当用户输入命中触发词（如 /route、/jev）时单次评估；
• auto：对每一轮用户普通输入均进行判定。
会话模型绑定模式	对话输入框上方选择器（写入配置的 selections..mode）	inherit / auto / manual	控制当前会话如何约束子代理模型：
• inherit：继承主模型或调用方原有参数，不强行重写；
• auto：依据 Jev 判定结果，自动挂载预设角色与对应模型；
• 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（编写或修订面向读者的 README、发布说明、Changelog 等）	默认派发
(无绑定角色)	(由主模型承接)	feature_work（引入产品新行为的新增功能开发）	出厂故意闲置，交给主模型
(无绑定角色)	(由主模型承接)	refactor（不改变对外行为的代码重构，涉及设计权衡）	出厂故意闲置，交给主模型
(无绑定角色)	(由主模型承接)	meta_chat（闲聊、问答或单纯规划，本轮不产生代码任务）	出厂故意闲置，交给主模型

💡 设计说明：

• junior 与 implementer 虽均涉及代码修改，但机械性修改规格清晰无须深度排查，而缺陷修复需要排查根因。拆分后可避免为简单重命名支付高昂算力成本。
• feature_work、refactor 与 meta_chat 涉及复杂系统设计与全局上下文，出厂默认不在派发白名单内，故意留给主模型自身处理。

---

3. 角色前置提示词

在插件设置页的「路由」区域，每个角色下方均提供了一个可展开的输入框，中文标注为「这个角色的前置提示词（以一条消息注入，先于任务）」，对应配置项为 routes..prompt。

• 注入形态与时机：前置提示词以一条独立消息的形式注入，不是系统提示词（System Prompt），注入位置位于子代理自身任务的前面。该注入仅在子代理处理的第一步执行；一个子代理运行过程中会推进很多步，只有首步携带该提示词，后续步骤不会重复注入。
• 生效条件：必须同时满足以下三项条件，缺一不可：
  1. 当前会话的选择器模式为 auto（由 Jev 决定本轮模型）；
  2. Jev 这一轮判定确实指派给了该角色；
  3. 目标角色在配置中填写了非空的提示词。
• 状态与配置同源：该机制直接读取「会话级选择器」中的当前模式与匹配角色，与自动分流共用同一套运行时状态，无需维护额外的独立配置。
• 为何 manual 与 inherit 不注入：
  • 手动选择模型（manual）时，由用户直接指定具体模型，全程没有角色参与。此时若强行塞入角色提示词，相当于让一个手动挑选的模型去扮演它未被赋予的角色，效果适得其反。
  • 继承模式（inherit）同理，直接沿用主模型而不经由角色分流，因此同样不注入。
• 容错与重试机制：构造该消息失败时，插件仅记录一条警告日志，子代理照常继续运行，绝不中断本轮会话。由于系统仅在消息真正构造成功后才标记完成记账，若因临时原因构造失败，子代理在下一步仍会尝试重新注入。

注入情形速查

运行情形	是否注入前置提示词	说明
会话模式为 auto 且该角色被 Jev 选中（已配提示词）	注入	仅在子代理首步作为独立消息注入一次
会话模式为 manual（手动指定模型）	不注入	无角色参与，避免手选模型被迫扮演未指定角色
会话模式为 inherit（继承主模型）	不注入	直接沿用主模型配置，无角色参与
目标角色未配置提示词（内容为空）	不注入	未配置时不执行任何消息注入

---

4. 核心配置参数表

支持在 DSH 插件设置页或配置补丁中调整以下参数：

配置字段 (Key)	类型	默认值	说明与有效取值
mode	string	"off"	插件激活模式："off"、"once"、"auto"。
triggers	string[]	["/route", "/jev"]	once 模式下的触发指令前缀。支持 /route preview 仅评估不派发。
provider	string	"typesafe"	判定提供商预设："typesafe"、"bai"、"openrouter"。
endpoint	string	依预设	Jev 判定服务端点地址（预设提供，高级自建网关可覆盖）。
apiPath	string	依预设	Jev API 路径（预设提供，高级覆盖项）。
apiKeyEnv	string	依预设	密钥环境变量名或凭据项。
model	string	依预设	判定模型标识（例如 "jev-1.13.0" 或 "jev-1.13"）。
timeoutMs	number	4000	判定请求超时时间（毫秒）。超时后触发静默放行机制。
stateChars	number	1200	送往判定服务的任务状态文本长度截断上限（从头部截取）。
activeProfile	string	"auto"	当前生效的决策档位："auto"（常规）、"careful"（严苛）。
defaultRoute	string	"implementer"	未匹配到细分任务类别时的兜底路由角色。
logDir	string	null	判定流水 NDJSON 日志目录；留空或 null 表示不持久化日志。
logTurnText	boolean	false	日志是否记录用户对话原始文本；默认 false 仅记录评估指标元数据。

---

4. 核心配置参数表

支持在 DSH 插件设置页或配置补丁中调整以下参数：

配置字段 (Key)	类型	默认值	说明与有效取值
mode	string	"off"	插件激活模式："off"、"once"、"auto"。
triggers	string[]	["/route", "/jev"]	once 模式下的触发指令前缀。支持 /route preview 仅评估不派发。
provider	string	"typesafe"	判定提供商预设："typesafe"、"bai"、"openrouter"。
endpoint	string	依预设	Jev 判定服务端点地址（预设提供，高级自建网关可覆盖）。
apiPath	string	依预设	Jev API 路径（预设提供，高级覆盖项）。
apiKeyEnv	string	依预设	密钥环境变量名或凭据项。
model	string	依预设	判定模型标识（例如 "jev-1.13.0" 或 "jev-1.13"）。
timeoutMs	number	4000	判定请求超时时间（毫秒）。超时后触发静默放行机制。
stateChars	number	1200	送往判定服务的任务状态文本长度截断上限（从头部截取）。
activeProfile	string	"auto"	当前生效的决策档位："auto"（常规）、"careful"（严苛）。
defaultRoute	string	"implementer"	未匹配到细分任务类别时的兜底路由角色。
logDir	string	null	判定流水 NDJSON 日志目录；留空或 null 表示不持久化日志。
logTurnText	boolean	false	日志是否记录用户对话原始文本；默认 false 仅记录评估指标元数据。

---

1. 运行自动化单元测试套件（98 项用例，覆盖判定、回放、改写与配置合并；其中 1 项依赖宿主 dsh 命令，Windows 上自动跳过）

node --test "test/**/*.test.mjs"