前言¶

在 DeepSeek Harness（DSH）裏跑「常駐 Agent Worker」時，業務側往往重複實現同一套橫切能力：用 WebSocket 接上游事件、把告警推到 IM、把語義類任務交給 Claude Code 或 Codex、再用低成本校驗過濾 Agent 輸出。這些邏輯與具體協議、路由和業務模板無關，卻幾乎每個項目都要寫一遍。

@baoyx/dsh-agent-kit（社區目錄條目 byx-darwin/dsh-agent-kit）把上述能力做成一組可單獨啓用的 Cordis Service，業務包只負責協議、路由、模板和流程。下面介紹它的定位、五個 Service、安裝方式以及 README 中的典型寫法。

這是什麼¶

• 名稱：npm 包 @baoyx/dsh-agent-kit（倉庫 byx-darwin/dsh-agent-kit），當前 README 標註版本 0.2.0，許可證 MIT。
• 維護者：byx-darwin。
• 分類：SkillHub 目錄中爲「工作流」。
• 一句話：構建常駐 Agent Worker 的 DSH 插件工具包——WebSocket 接入、釘釘 user 推送與通知、Claude Code / Codex 任務委託、TypeSafe Jev（或本地 Laya）校驗。
• 文檔：官網 https://byx-darwin.github.io/dsh-agent-kit/；歷史設計文檔可能含已移除方案，以當前代碼與官網爲準。

本包不包含業務協議、事件類型、提示詞或分類體系，也不做可靠事件持久化；投遞可靠性由對端負責。一條上游 WebSocket 連接只應部署一個 Profile 實例。

兩個 npm 包¶

不安裝 admin 包時，五個 Service 仍可用，配置寫在 Profile 的 cordis.patch.yml 中。

核心功能：五個 Service¶

五個 Service 默認禁用，按需啓用；未啓用的 Service 不校驗配置，也不影響其他 Service。每個 Service 提供 health()；進入 failed 時觸發 agent-kit/service-failed 事件。錯誤統一爲 KitError，帶 code 與 retryable。

根入口 @baoyx/dsh-agent-kit 導出全部 Service、配置、錯誤與工具；另有子路徑 /ws、/dingtalk、/notify、/agent-tasks、/jev、/secrets、/testing。

架構上，業務包通過 inject 使用 kit，kit 再依賴 dsh 的 subagent、子進程與 Session；notify 不直連外部系統，發送時查找 dingtalk 並轉發。

環境要求¶

• Node.js ^22.19 或 >=24
• @deepseek-ai/dsh CLI 0.1.5-rc.3 或 0.1.7-alpha.2（預發佈；cordis 等依賴需與所用 dsh 版本鎖定；下文示例以 0.1.5-rc.3 爲準）
• ctx.dingtalk：已安裝並登錄 dws（README 已驗證 dingtalk-workspace-cli@1.0.62），僅 user 身份
• ctx.agentTasks：安裝 @deepseek-ai/dsh-subagent-claude-code 和/或 @deepseek-ai/dsh-subagent-codex，並完成原生登錄
• ctx.jev：安裝 @typesafe-ai/sdk，設置 TYPESAFE_API_KEY；或配置 provider: laya 與 baseURL
• 生產：Profile 由 systemd、pm2 等進程守護託管

本包運行時不會自動安裝 dsh、dws 等 CLI；可手動安裝，或通過 admin 包的 setup 在確認後安裝。

安裝與啓用¶

先做全局 dsh 與 Profile，再按 README 添加插件（不要憑倉庫名拼 github:owner/repo）。

npm i -g @deepseek-ai/dsh@0.1.5-rc.3

# 基於 web 模板創建常駐 Profile
dsh --profile my-agent --from-default-profile web

# 本包、Agent provider 與業務包（subagent 須顯式指定版本，latest 可能與 dsh 不匹配）
dsh plugin --profile my-agent add @baoyx/dsh-agent-kit \
  @deepseek-ai/dsh-subagent-claude-code@0.1.5-rc.3 \
  @deepseek-ai/dsh-subagent-codex@0.1.5-rc.3
dsh plugin --profile my-agent add ./my-business-plugin-0.1.0.tgz

# 可選：運維工具
dsh plugin --profile my-agent add @baoyx/dsh-agent-kit-admin

# 在 cordis.patch.yml 中啓用需要的 Service

dsh --profile my-agent --dump-config
dsh --profile my-agent --no-open

業務包應把 kit 聲明爲 peerDependencies，保證 Profile 內只加載一份實例；@deepseek-ai/cordis 版本與目標 dsh 一致（0.1.5-rc.3 對應 4.0.2，0.1.7-alpha.2 對應 4.0.4）。

典型用法¶

業務插件骨架¶

插件通過 inject 聲明需要的 Service，在 apply 裏連接 WebSocket、發通知、跑 Agent 任務並用 Jev 校驗。README 示例要點：WebSocket 與 Agent 輸出均視爲不可信（untrusted()、業務白名單）；告警走 ctx.notify.send()。

import type { Context } from '@deepseek-ai/cordis'
import { choice, isKitError, noul, untrusted } from '@baoyx/dsh-agent-kit'

export const name = 'my-agent'
export const inject = ['agentWs', 'notify', 'agentTasks', 'jev']

export function apply(ctx: Context, config: Config) {
  const conn = ctx.agentWs.connect<Frame>({
    url: config.url,
    headers: async () => ({ 'X-Token': await getToken() }),
    parse: parseFrame,
    concurrency: 2,
    onMessage: async (frame, { signal }) => {
      if (frame.type === 'alert') {
        await ctx.notify.send({
          title: frame.title,
          markdown: renderAlert(frame),
          idempotencyKey: frame.id,
          traceId: frame.id,
        })
        return
      }

      const draft = await ctx.agentTasks.run<Result>({
        provider: 'claude-code',
        title: `classify ${frame.id}`,
        prompt: [CLASSIFY_INSTRUCTIONS, untrusted('event', frame.input)],
        outputSchema: ResultSchema,
        signal,
        traceId: frame.id,
      })

      if (!CATEGORIES_ALLOWLIST.has(draft.output.category)) throw new Error('unexpected category')

      const { answers } = await ctx.jev.judge({
        state: { input: frame.input, candidate: draft.output },
        questions: {
          wrong: noul('候選結果與輸入證據不符', { true: '不符', false: '相符' }),
          pick: choice('輸入最符合哪個類別', CATEGORIES),
        },
        signal,
        traceId: frame.id,
      })

      await conn.send({ id: frame.id, result: draft.output, verified: answers.wrong.noul < 0.7 })
    },
    onError: (err, frame) => {
      if (isKitError(err) && err.retryable) {
        // 記錄後交給對端重投
      }
    },
  })
}

通知與釘釘¶

發通知推薦 ctx.notify；需指定羣時可傳 targets.dingtalk.chatId。釘釘未就緒時 NotifyError（channel_unavailable）。

await ctx.notify.send({
  title: '需要人工複覈',
  markdown: body,
  targets: { dingtalk: { chatId: 'cidxxxx' } },
  idempotencyKey: frame.id,
})

釘釘登錄與羣/用戶查找見 README「通知與釘釘登錄」；業務插件可登記 kind: 'dingtalk-target' 的設置字段，由 Web 設置頁輔助選目標 ID。

適用場景與注意¶

適合誰：已在 DSH 上跑常駐 Profile、需要「接 WebSocket → 釘釘告警 → 委託 subagent → Jev/Laya 校驗」流水線，且希望橫切能力與業務包分離的團隊。

使用前請知悉：

• 插件在 當前 dsh Profile 進程權限 下運行，會調用子進程（dws、Claude Code/Codex 等）；安裝前請閱讀 GitHub 源碼 與 MIT 許可證，自行評估組織合規與密鑰管理（provider 會剔除名稱含 KEY/TOKEN/SECRET/PASSWORD 的環境變量，需鑑權時在 provider Config 的 env 中顯式配置）。
• DSH 生態是「一切皆插件」；SkillHub 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。
• README 標明 npm 已發佈 @baoyx/dsh-agent-kit 與 @baoyx/dsh-agent-kit-admin 0.2.0；目錄頁星標爲 0，不代表功能完備度，以文檔與版本爲準。

結尾¶

dsh-agent-kit 把常駐 Agent Worker 常見的四項橫切能力收進五個可選 Service，業務包專注協議與流程即可複用同一套運維與監控鉤子（health()、KitError、service-failed 事件）。

• 目錄頁：https://www.skillhub.cn/plugins/byx-darwin/dsh-agent-kit
• 倉庫與 README：https://github.com/byx-darwin/dsh-agent-kit
• 官網文檔：https://byx-darwin.github.io/dsh-agent-kit/