文档

五类能力，一套约定

底层的七个 Service 都在 @baoyx/dsh-agent-kit 中。钉钉仅支持已登录的 user 身份，飞书、企业微信使用机器人身份；业务包通常只 inject notify。doctor、setup 与设置页在可选的 @baoyx/dsh-agent-kit-admin 中。

壹 · 连接 WebSocket 客户端 · ctx.agentWs 仅 wss:// 的 WebSocket 客户端：可刷新的鉴权请求头、心跳、指数退避重连、并发与背压控制；鉴权失败或指定关闭码时进入 failed 状态并可慢速重试。贰 · 消息钉钉消息 · ctx.dingtalk 通过钉钉 dws CLI 的 user 身份发送消息；统一监听群内 @ 消息，并按群 ID 与内容规则下发给业务插件。叁 · 通知通知渠道 · ctx.notify 通知入口：业务包通过 ctx.notify.send() 发送，默认发往配置的默认渠道，也可按调用指定渠道。肆 · 委托 Agent 任务 · ctx.agentTasks 调用 dsh 已注册的 subagent provider（如 claude-code、codex）执行一次性任务：默认只读权限、每个任务独立目录、类型化的 JSON Schema 输出、并发与排队上限。伍 · 校验 Jev 判断 · ctx.jev 调用 TypeSafe Jev 或本地部署的 Laya（二选一），返回 Choice / Noul / Score 的类型化判断和概率；一次 judge() 有严格的总时长。陆 · 收发飞书 · ctx.feishu 飞书机器人：发送文本或 Markdown 卡片，接收群内 @ 机器人与私聊机器人的消息并按会话分发给业务插件。柒 · 收发企业微信 · ctx.wecom 企业微信智能机器人：以 Markdown 发送消息，长连接接收群内 @ 机器人与单聊消息，按会话分发；可直接回复收到的消息。

配置引导可选的 @baoyx/dsh-agent-kit-admin：用 doctor 检查、用 setup 配置，或在 dsh Web 的设置页里操作。安全密钥、子进程、不可信数据、Agent 权限与 Web 写入限制。

通用约定

错误模型

所有错误都继承 KitError，带有 service、code、retryable，以及经过脱敏的 cause 与 details。业务包用 isKitError(e) 和 code 判断错误，不依赖 instanceof，这样即使出现多份模块实例也能正确判断。配置或环境变量非法时抛出 ConfigError（code: invalid_config），对应 Service 启动失败。

import { isKitError } from '@baoyx/dsh-agent-kit'

onError: (err, frame) => {
  if (isKitError(err) && err.retryable) {
    // 例如：记录下来，交给对端系统重投
  }
}

生命周期与卸载

连接、定时器、子进程、排队中的任务都随调用方插件的生命周期释放。
卸载时：WebSocket 以 1001 关闭；正在执行的 onMessage 收到的 signal 被中止；Agent 任务以 aborted 结束；dws 子进程先 SIGTERM、宽限后 SIGKILL 回收。

健康状态与可观测性

每个启用的 Service 提供 health()，返回 { status: 'ok' | 'degraded' | 'failed', detail, counters }。
状态变为 failed 时，除日志外还触发 Cordis 事件 agent-kit/service-failed（参数 { service, detail, error? }，已脱敏），可据此向外部监控上报。
所有调用都接受可选的 traceId 并写入日志，便于用事件 ID 串起一次处理链路。
日志通过 ctx.logger('agent-kit:<service>') 输出。cordis 默认只导出 error 与 info 级别，warn 与 debug 需要在 Profile 的日志 exporter 中调高级别。

本地开发与测试

@baoyx/dsh-agent-kit/testing 导出本地 WebSocket 测试服务端、假 subagent provider、Jev mock 和假 dws 脚本（createFakeDws），业务包可以在没有 dws 与 Agent 登录态的环境下开发和测试；钉钉推送也可以设为 dryRun。