前言¶

在 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/