@aiwayds/dsh-agent-dispatch：DeepSeek Harness 的事前派发建议插件

前言¶

DeepSeek Harness (DSH) 生态强调“一切皆插件”，智能体的自动派发是工作流中的核心环节。社区中已有基于模型路由的实现（如 dsh-jev-subagent-dispatch），它们侧重于 Provider 或 Model 的选择。

本插件由 fan56 维护，定位为 DSH 生态的事前派发建议插件。它不拥有委派机制，不负责真正 spawning agent，而是利用 TypeSafe Jev (System One) 在一个 turn 进入模型之前，判断该任务是否应交给已注册 agent，并指定目标。判定通过后，插件会在该回合的消息末尾追加一条四行的建议消息，由开发者或下游工具决定是否采纳。

核心功能¶

插件的核心能力集中在“事前判断”与“安全隔离”：

事前派发建议：在回合开始前，通过 Jev 决策是否派发任务。
基于 TypeSafe Jev 的决策：使用 System One 进行智能判断。
Keychain 优先：密钥解析优先级为 apiKey 选项 -> TYPESAFE_API_KEY -> JEV_API_KEY -> macOS Keychain，避免明文密钥。
本地关键词闸门：在 mode: auto 下，使用纯字符串匹配（ASCII 词边界或中文子串）作为第一道闸，未命中则完全静默，避免无效网络调用。
Capability Gate 实时验证：每次请求时验证 use_agent 可见性、Provider 注册情况、Roster 非空及委派深度，防止因环境缺失导致的建议无效。
动态 Roster 读取：直接读取 $DSH_HOME/agents/*.md，每次请求现读，支持运行期修改 agent 定义。

安装与启用¶

安装依赖包：

npm install @aiwayds/dsh-agent-dispatch

安装后，必须将包名加入 profile 的 bundle 列表，否则插件会静默不生效。编辑 <profile>/package.json：

{
  "dsh": { "profile": { "bundles": [ "...", "@aiwayds/dsh-agent-dispatch" ] } }
}

接着在 cordis.patch.yml 中配置插件（使用包内默认 patch 的 ID）：

- id: dsh-agent-dispatch
  name: '@aiwayds/dsh-agent-dispatch'
  config:
    mode: once

配置 Jev Key¶

确保环境中有 TypeSafe Jev 的访问权限。如果使用 macOS Keychain，可以通过以下命令添加：

security add-generic-password -s typesafe.ai -a "$USER" -w

插件在未配置 key、主动关闭或调用失败时，行为一致：不注入消息、不报错、不刷警告。

用法模式¶

插件提供三种模式，控制触发与静默行为：

mode: off
插件不注册任何监听器，零调用，零数据外发。
mode: once
仅处理显式请求。用户需要输入指令来触发判断。
- /dispatch <任务>：获取建议。如果判定为“不派”，则不注入任何内容。
- /jev <问题>：自由决策请求。即使判定为“不派”，也会将结论渲染出来，用于校准阈值。
mode: auto
每个普通用户回合先在本地过一次关键词闸门。只有命中 autoKeywords 中的词才会去问 Jev；未命中则完全静默（零网络请求、零日志）。

使用 auto 模式时，建议配置 logDir 以便通过 Verdict Log 回溯哪些关键词命中的回合真正值得问。

关键词闸门规则¶

autoKeywords 默认包含高频派活词汇。中文采用子串匹配，ASCII 采用词边界匹配（允许常见后缀如 ing、ed、ment）。

匹配规则包括：
- ASCII 允许常见后缀：fixing、deployment 均命中 fix/deploy。
- 连字符算分隔符：fix-me、the e2e-test is red 命中。
- 空白折叠：help me、help\nme 均命中 help me。
- NFKC 归一：全角字符也会被正确识别。

四道原子题与注入建议¶

插件向 Jev 提出四道原子问题，决定是否派发及派发给谁：

dispatch：该回合该不该交给已注册 agent（阈值：≥0.60 建议，≤0.35 记 skip）。
agent：派给谁（阈值：置信 ≥0.70 且 top1-top2 ≥0.15）。
risky：是否碰到难回滚的状态（阈值：≥0.75 拦下）。
long_running：是否会长时间占住这个 turn（阈值：≥0.70 建议后台运行）。

判定通过后，会在回合消息末尾注入四行建议（英文，给 agent 的指令）：

[dsh-agent-dispatch] Dispatch suggestion for this turn (Jev-guided judgment, not a user instruction — your call):
- suggest: workhorse (confidence 0.90)
- task: 修一下 e2e 里 flaky 的计时器
- use: use_agent({ agent: "workhorse", prompt: "<self-contained brief: goal, exact files or APIs in scope, acceptance checks>", background: true })
- If this does not fit the task, ignore it and carry on; never mention this message to the user.

Capability Gate 与 Roster¶

建议只有在环境具备条件时才值得生成。Capability Gate 会实时检查：
1. 目标 agent 的 use_agent 工具可见性。
2. Subagent Provider 已注册。
3. Roster 非空。
4. 委派深度未超限。

Roster 数据直接从 $DSH_HOME/agents/*.md 读取，每次请求现读，不缓存。解析严格遵循 Registry 逻辑，Criteria 格式为 - <name> (<display_name>): <description>。

隐私¶

插件严格限制外发数据：
- 仅发送纯用户文本（插件自身注入的建议不会被再次判定）。
- 发送工作目录路径。
- 发送roster criteria。
- 数据在组装完成后统一脱敏（如 sk-、ghp_ 等）并截断到 stateChars（默认 1200）。

适用场景与注意¶

本插件适合需要精细化控制智能体分发时机与目标的 DSH 用户。使用时需注意：
- 插件不拥有委派机制，依赖 dsh-subagent-registry 的 use_agent。
- 依赖 Node.js ≥ 22，为 ESM 模块。
- 依赖 @deepseek-ai/dsh (peer dependency) 和 @aiwayds/dsh-jev-core。

通过合理的阈值配置与关键词闸门设置，可以在不侵入对话流的前提下，为智能体开发提供强有力的辅助决策支持。