@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。

通過合理的閾值配置與關鍵詞閘門設置，可以在不侵入對話流的前提下，爲智能體開發提供強有力的輔助決策支持。